Spec Driven Development with claud extracted from a project.

00_NOTES.md

🚀 Example Usage

Next time you have a complex feature:

You tell Claude Code: "I need to add rate limiting to the job API following the layered spec pattern in specs/mtls/. This involves updating the server, adding Redis, and new Terraform resources. Estimated 8 hours of work."

Claude Code will automatically:

1. Create specs/rate-limiting/ directory
2. Generate README.md with navigation
3. Create 00-architecture.md with design
4. Create 5 phase files for implementation
5. Add operations-runbook.md
6. Create examples/ with code references

The pattern is now documented and repeatable! 🎉

AGENT.md

Specification Documentation Standards

For complex features requiring significant implementation work (multi-package changes, infrastructure updates, new authentication systems), follow the layered specification pattern demonstrated in specs/mtls/.

When to Use Layered Specs

Use this pattern when:

• Implementation spans 3+ packages or components
• Requires infrastructure changes (Terraform, AWS resources)
• Involves architectural decisions with multiple approaches
• Takes 7+ hours to implement
• Benefits from phase-by-phase execution

Do NOT use for:

• Simple bug fixes or single-file changes
• Documentation-only updates
• Trivial feature additions

Layered Spec Structure

specs/<feature-name>/
├── README.md                    ← Entry point & navigation guide
├── 00-architecture.md           ← Design decisions, diagrams, data models
├── 01-phase1-<name>.md         ← First implementation phase
├── 02-phase2-<name>.md         ← Second implementation phase
├── 03-phase3-<name>.md         ← Third implementation phase
├── ...                          ← Additional phases as needed
├── operations-runbook.md        ← Day 2 operational procedures
├── ARCHIVE_*.md                 ← Original consolidated spec (if migrated)
└── examples/                    ← Complete code examples
    ├── <package1>/              ← Examples organized by package
    ├── <package2>/
    └── <package3>/

File Guidelines

README.md (250-400 lines):

• Overview of what the feature provides
• Prerequisites (tools, access, knowledge)
• Quick start guide (5-step summary)
• File navigation table with duration estimates
• Phase-by-phase execution guide with success criteria
• Troubleshooting section
• Next steps

00-architecture.md (400-800 lines):

• Summary and goals (what/why)
• Design decisions and trade-offs
• Architecture diagrams (Mermaid)
• Data models (DynamoDB schemas, structs)
• Key concepts and terminology
• References to example code

Phase Files (250-500 lines each):

• Clear goal and duration estimate
• Prerequisites (previous phase completion)
• Success criteria (checkboxes)
• Package-by-package implementation guide
• Code snippets for interfaces and key patterns (inline)
• References to complete implementations in examples/
• Verification steps with specific commands
• Next phase reference

operations-runbook.md (300-500 lines):

• Common operational procedures
• Emergency procedures
• Monitoring and alerting guidance
• Troubleshooting scenarios
• Metrics definitions
• AWS CLI commands for manual operations

examples/ directory:

• Complete files for small, critical code (interfaces, small utilities)
• Reference/skeleton files for large implementations (500+ lines)
• Organized by package structure (mirrors actual codebase)
• Include comments about imports and dependencies
• Reference back to original spec line numbers for full implementations

Code in Specs: Inline vs Examples

Keep inline in spec files:

• Interface definitions (<100 lines)
• Struct definitions (<50 lines)
• Key method signatures
• Small code snippets demonstrating patterns (<30 lines)
• Configuration examples (<50 lines)
• All Mermaid diagrams
• All tables and matrices

Move to examples/ directory:

• Complete implementations (>100 lines)
• Full file contents (even if <100 lines, if it's a complete file)
• Large Terraform modules (>80 lines)
• Complete CLI commands (>200 lines)
• Any code that would be copy-pasted wholesale

Phase Organization

Organize phases by natural implementation flow:

1. Phase 1: Core Code - Interfaces, core logic, no infrastructure
2. Phase 2: Integration - Local testing, docker-compose, integration tests
3. Phase 3: Infrastructure - Terraform, AWS resources
4. Phase 4: Deployment - Production deployment, verification
5. Phase 5: Cleanup - Remove old code, update docs

Checkpoint between each phase:

• Each phase must have clear success criteria
• Must be verifiable independently
• Next phase should not start until previous succeeds

Instructing Claude Code

When asking Claude Code to create layered specs, provide this template:

I need to create a layered specification for [FEATURE NAME] following the pattern in specs/mtls/.

The feature involves:
- [List key components/packages affected]
- [Infrastructure changes needed]
- [Estimated complexity: X hours]

Please create a layered spec structure with:
1. README.md as entry point
2. 00-architecture.md with design decisions and diagrams
3. Phase files (01-0X) for sequential implementation
4. operations-runbook.md for Day 2 operations
5. examples/ directory with code references

Follow the pattern established in specs/mtls/ including:
- Inline code for interfaces and small snippets
- Examples directory for complete implementations
- Success criteria for each phase
- Verification commands
- Mermaid diagrams where appropriate

See AGENT.md "Specification Documentation Standards" section for complete guidelines.

Example: mTLS Authentication Spec

Reference implementation: specs/mtls/

This spec demonstrates:

• ✅ Clear README with navigation and quick start
• ✅ Architecture file with design decisions and Mermaid diagrams
• ✅ 5 phase files for sequential implementation
• ✅ Operations runbook with procedures and metrics
• ✅ Examples directory with 12 code reference files
• ✅ Original 3,056-line spec archived for reference
• ✅ Each phase independently actionable
• ✅ Total: 3,062 lines across 8 focused spec files

Key principles demonstrated:

• Each file is independently readable
• Cross-references between files are clear
• Developers can start at README and execute sequentially
• Examples are copy-paste ready when needed
• Original consolidated spec preserved for reference

LAYERED_SPEC_TEMPLATE.md

Layered Specification Template

Use this template when instructing Claude Code to create a new layered specification.

Quick Instruction for Claude Code

I need to create a layered specification for [FEATURE NAME] following the pattern in specs/mtls/.

The feature involves:
- [List key components/packages affected]
- [Infrastructure changes needed]
- [Estimated complexity: X hours]

Please create a layered spec structure with:
1. README.md as entry point
2. 00-architecture.md with design decisions and diagrams
3. Phase files (01-0X) for sequential implementation
4. operations-runbook.md for Day 2 operations
5. examples/ directory with code references

Follow the pattern established in specs/mtls/ including:
- Inline code for interfaces and small snippets
- Examples directory for complete implementations
- Success criteria for each phase
- Verification commands
- Mermaid diagrams where appropriate

See AGENT.md "Specification Documentation Standards" section for complete guidelines.

Expected Directory Structure

specs/<feature-name>/
├── README.md                    # Entry point & navigation (250-400 lines)
├── 00-architecture.md           # Design decisions (400-800 lines)
├── 01-phase1-<name>.md         # Phase 1 implementation (250-500 lines)
├── 02-phase2-<name>.md         # Phase 2 implementation (250-500 lines)
├── 03-phase3-<name>.md         # Phase 3 implementation (250-500 lines)
├── ...                          # Additional phases as needed
├── operations-runbook.md        # Day 2 operations (300-500 lines)
├── ARCHIVE_*.md                 # Original spec if migrated
└── examples/                    # Complete code examples
    ├── <package1>/
    ├── <package2>/
    └── <package3>/

When to Use This Pattern

✅ Use layered specs when:

• Implementation spans 3+ packages or components
• Requires infrastructure changes (Terraform, AWS resources)
• Involves architectural decisions with multiple approaches
• Takes 7+ hours to implement
• Benefits from phase-by-phase execution

❌ Do NOT use for:

• Simple bug fixes or single-file changes
• Documentation-only updates
• Trivial feature additions

File Content Guidelines

README.md

• Overview and benefits
• Prerequisites (tools, access, knowledge)
• Quick start (5 steps)
• File navigation table
• Phase-by-phase execution guide
• Troubleshooting
• Next steps

00-architecture.md

• Summary and goals
• Design decisions and trade-offs
• Architecture diagrams (Mermaid)
• Data models
• Key concepts
• References to examples

Phase Files (01-0X)

• Clear goal and duration
• Prerequisites
• Success criteria (checkboxes)
• Implementation steps
• Code snippets (inline for interfaces)
• References to examples/
• Verification commands
• Next phase link

operations-runbook.md

• Common procedures
• Emergency procedures
• Monitoring/alerting
• Troubleshooting
• Metrics
• AWS CLI commands

examples/

• Complete interfaces (<100 lines)
• Reference files for large implementations (>100 lines)
• Organized by package structure
• Include import comments

Code Organization

Inline in specs:

• Interface definitions (<100 lines)
• Struct definitions (<50 lines)
• Method signatures
• Small snippets (<30 lines)
• Mermaid diagrams
• Tables

In examples/ directory:

• Complete implementations (>100 lines)
• Full files (even if <100 lines)
• Large Terraform modules (>80 lines)
• CLI commands (>200 lines)

Phase Organization Pattern

1. Phase 1: Core Code - Interfaces, logic, no infrastructure
2. Phase 2: Integration - Local testing, docker-compose
3. Phase 3: Infrastructure - Terraform, AWS resources
4. Phase 4: Deployment - Production, verification
5. Phase 5: Cleanup - Remove old code, docs

Reference Implementation

See specs/mtls/ for a complete example demonstrating all these patterns.

Stats from mTLS spec:

• 8 spec files (README + architecture + 5 phases + runbook)
• 12 example files
• 3,062 lines of focused documentation
• Each phase independently actionable
• Clear success criteria throughout

Additional Resources

• Full guidelines: AGENT.md → "Specification Documentation Standards"
• Reference implementation: specs/mtls/
• Quick start: specs/mtls/README.md