How Spec‑Driven Development with Claude Code Transforms Small‑Scale AWS Projects

Spec‑Driven Development (SDD)

SDD structures AI‑assisted coding by requiring a written specification before code generation. Three levels are defined:

Spec‑first : Draft a detailed spec, then use it as the primary input for AI tools.

Spec‑anchored : Keep the spec after implementation to guide future iterations and maintenance.

Spec‑as‑source : Treat the spec as the source of truth; developers edit the spec, not the generated code.

Adhering to the spec‑first approach helps avoid “spec‑once” development, where the spec is abandoned after initial coding.

Prototype Workflow for an AgentCore Interceptor

The goal is to understand how an interceptor Lambda integrates with the AgentCore Gateway. The workflow consists of three phases:

Research: Read the official CloudFormation and AgentCore documentation to identify required resource properties.

Planning: Design a modular stack architecture on AWS, splitting the project into two sub‑stacks (red) each with staged deployment (yellow).

Implementation: Build small, testable modules using AWS SAM for the interceptor and CloudFormation for the remaining resources.

Key artifacts: InterceptorConfigurations – a custom resource added to the Gateway stack to configure the interceptor.

Lambda function (interceptor) deployed in its own stack and tested with sam local invoke.

Credential provider created via boto3 to inject OAuth 2 credentials into the Gateway target.

Because the AgentCore CLI (public preview) lacked support for some resources, the implementation fell back to raw CloudFormation templates.

Stack Details

Sub‑stack 1 – Interceptor

# sam template (YAML excerpt)
Resources:
  InterceptorFunction:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: python3.11
      Handler: interceptor.handler
      CodeUri: ./interceptor
      Policies:
        - AWSLambdaBasicExecutionRole

Sub‑stack 2 – MCP Server

# CloudFormation snippet for MCP server (simplified)
Resources:
  MCPServer:
    Type: AWS::EC2::Instance
    Properties:
      InstanceType: t3.micro
      ImageId: ami-0abcdef1234567890

Sub‑stack 3 – AgentCore Gateway

# CloudFormation snippet for Gateway with OAuth2 authorizer
Resources:
  Gateway:
    Type: AWS::ApiGatewayV2::Api
    Properties:
      Name: AgentCoreGateway
      ProtocolType: HTTP
  Authorizer:
    Type: AWS::ApiGatewayV2::Authorizer
    Properties:
      ApiId: !Ref Gateway
      AuthorizerType: JWT
      IdentitySource: ['$request.header.Authorization']
      JwtConfiguration:
        Audience: ['my-audience']
        Issuer: 'https://my-issuer'

Adding OAuth 2 required replacing the AuthorizerType property, which forced a full resource replacement (delete‑and‑recreate).

Claude Code Usage Insights

Claude Code provides a default 200 k token context window, sufficient for most interactions (code, docs, tool descriptions, conversation history). The Pro plan shares this limit; only Max 20x subscribers receive a 1 M token window via Bedrock.

To attempt a Bedrock backend, set the environment variable: export CLAUDE_CODE_USE_BEDROCK=1 Extended context requires the custom request header anthropic-beta: context-1m-2025-08-07, but Claude Code currently cannot forward this header, so the window remains at 200 k tokens.

When the limit is reached, Claude Code automatically compacts the conversation history, a process that can take 3–12 minutes depending on load.

Response options for each operation are:

Yes

Yes, and don’t ask again for this operation type

No

Over time the author trusted the tool enough to allow write operations and to run multiple sessions in parallel using tmux.

Practical Takeaways

Investing time in early specification improves implementation efficiency and reduces rework.

Modular, testable stacks enable incremental changes rather than large rewrites.

When a preview CLI lacks features, fallback to CloudFormation and SDKs (e.g., boto3) for full control.

OAuth 2 integration may require full resource replacement; plan for multi‑step delete‑and‑recreate workflows.

Document custom skills (e.g., CLAUDE.md, SKILL.md) to accelerate future projects.

References

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