How Spec‑Driven Development with Claude Code Transforms Serverless AWS Projects

Understanding Spec‑Driven Development

Spec‑driven development (SDD) is presented in three maturity levels: spec‑first – write a thoughtful specification before any code; spec‑anchored – keep the spec after implementation for future evolution; and spec‑as‑source – treat the spec as the sole source of truth, with humans editing only the spec.

The author favors a spec‑first approach, using a single, well‑crafted document to guide design and implementation, while warning against abandoning the spec once development begins.

Planning and Drafting the Specification

To explore how an interceptor works with the AgentCore Gateway, the author first researched the interceptor’s input and output payloads, then drafted a detailed spec that would drive the AI‑assisted workflow.

The workflow consists of three main phases:

Research: read documentation and related material.

Plan AWS resources needed for deployment.

Build small, testable modules.

Modular Stack Construction

The project is split into two sub‑stacks (red) with stages (yellow) to simplify testing and composable deployment.

For the first sub‑stack, a Lambda interceptor is added to the Gateway via the InterceptorConfigurations property and deployed as a separate SAM stack.

For the second sub‑stack, three stages are defined:

Stage 1 (stack 2): create an MCP server and deploy it to AgentCore Runtime, then run local tests followed by end‑to‑end tests.

Stage 2 (stack 3): provision the AgentCore Gateway, configure the MCP server as the target, and set up an OAuth2 credential provider.

Stage 3 (stack 3 updates): add an interceptor that injects a custom request header, increase logging, and verify header propagation through the call chain.

All stages are documented in the spec to ensure alignment with design intent.

Using Claude Code: Tips and Limitations

The default 200k‑token context window is sufficient for most prompts. Larger 1 million‑token windows are only available to Max 20x subscribers and require the custom HTTP header anthropic-beta: context-1m-2025-08-07, which Claude Code cannot currently set, so the author remains with 200k tokens.

When the context limit is reached, Claude Code automatically compresses conversation history, taking 3‑5 minutes for light usage and up to 10‑12 minutes for heavy usage.

Model usage observations: Opus quickly hits the subscription’s conversation‑budget limit (≈45 minutes of heavy use), whereas Sonnet remains usable for several hours without hitting limits.

Claude Code can ask clarification questions and present selectable options; the author often chooses “yes” and gradually trusts the tool enough to allow write operations without the dangerous --dangerously-skip-permissions flag.

Multiple sessions are managed with tmux (or tmux -CC in iTerm2) to keep parallel Claude Code instances organized.

Observations and Lessons Learned

Early planning dramatically improves implementation efficiency and output quality; incremental, small‑unit builds make testing and adjustments easier.

Stacked pull requests enable smaller, inter‑dependent reviews.

Flexibility is essential: when the preview‑stage AgentCore CLI lacked needed features, the author fell back to CloudFormation and used boto3 to create a credential provider, later injecting its ARN into the Gateway.

Security should be addressed early; changing the AuthorizerType on the Gateway required a full stack redeployment, highlighting the cost of late security additions.

Continuous spec updates keep the design aligned with evolving requirements, embodying a spec‑anchored mindset.

Conclusion and Future Direction

The rapid evolution of generative AI tools like Claude Code encourages developers of any background to prototype small projects and iterate quickly. The author plans a larger project that will employ agent teams to handle backlog items, documenting the journey in a forthcoming blog post.

Resources

https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html

https://github.com/heeki/agents/tree/main/interceptors

https://x.com/bcherny/status/2017742741636321619

https://www.cjroth.com/blog/2026-02-18-building-an-elite-engineering-culture

https://builder.aws.com/content/39vdJOeWD0pbA7hpKpW1a2tBw8x/extending-claude-code-with-plugins-and-skills-for-aws-development