The CodeMySpec Method
Stop Fighting AI Drift. Control What Goes Into Context.
The 5-phase methodology I use to build CodeMySpec with AI - from stories to production code.
📝 User Stories
Define requirements in plain English
🗺️ Context Mapping
Map stories to Phoenix contexts
📐 Design Documents
Write specifications that control AI context
🧪 Test Generation
Generate tests from design documents
⚡ Code Generation
Generate code that makes tests pass
The Problem: Compounding Drift
AI drift compounds through reasoning layers. The farther the LLM's reasoning gets from your actual prompt, the more the output drifts from your intent.
Reasoning Drift
LLM's reasoning slightly off from your intent → code generation is more off. Each inference step compounds the error.
Documentation Drift
Generate PRD → generate code from PRD → two layers of drift between your intent and the output.
Process Drift
Ask LLM to prescribe AND follow process → compounding error. Every time you ask the LLM to figure out the process, you add drift.
The Solution: Control Context
Remove drift by controlling exactly what goes into the LLM's context. No intermediate reasoning about requirements. No inventing process.
Design documents define the specifications
Tests define the validation
LLM only generates code to match both
The Five Phases
📝 User Stories
Define requirements in plain English
What You Create
Manual
Write stories yourself or interview with AI
- Create user_stories.md in your repo
- Interview yourself about requirements
- Write stories in 'As a... I want... So that...' format
- Add specific, testable acceptance criteria
Automated
Stories MCP Server handles interviews and generation
- AI interviews you about requirements with structured PM persona
- AI creates stories in database with full version history
- AI reviews stories for quality and completeness on demand
- Link stories to components automatically during design
- Track status (in_progress, completed, dirty) throughout lifecycle
lib/code_my_spec/stories/story.ex
🗺️ Context Mapping
Map stories to Phoenix contexts
What You Create
Manual
Map stories to Phoenix contexts using vertical slice architecture
- Group stories by entity ownership
- Apply business capability grouping within entity boundaries
- Keep contexts flat (no nested contexts)
- Identify components within each context
- Map dependencies between contexts
Automated
Architect MCP Server guides context design and validates dependencies
- AI interviews you about architecture with structured architect persona
- AI creates domain and coordination contexts in database
- AI validates dependencies and detects circular references
- Link stories to contexts automatically during design
- Track architectural health (orphaned contexts, dependency depth)
- Review architecture quality on demand with best practices validation
docs/design/code_my_spec/stories.md
📐 Design Documents
Write specifications that control AI context
What You Create
Manual
Write design docs following template structure
- Create docs/design/{app_name}/{context_name}.md
- Follow template structure (purpose, entities, access patterns, etc.)
- Be specific about behavior, edge cases, error handling
- Include acceptance criteria from relevant user stories
- List every component (file) that needs to be implemented
- Paste design document into AI context before asking for code
Automated
Design Sessions orchestrator generates validated designs from architecture
- AI generates context design from architecture and user stories
- System validates design against schema (required sections, dependencies)
- AI revises if validation fails, loops until design passes
- System spawns parallel component design sessions
- All designs committed to git with clear audit trail
lib/code_my_spec/documents/context_design.ex
🧪 Test Generation
Generate tests from design documents
What You Create
Manual
Write tests from design docs before implementation
- Read design document
- Write tests for each component's public API
- Include edge cases and error scenarios from acceptance criteria
- Create fixtures for test data
- Run tests (they should fail - no implementation yet)
- Paste design doc + failing tests into AI context for implementation
Automated
Component Test Sessions orchestrator generates and validates tests
test/code_my_spec/stories_test.exs
⚡ Code Generation
Generate code that makes tests pass
What You Create
Manual
Paste design + tests into LLM, iterate until green
- Paste design document into AI context
- Paste failing tests into AI context
- Ask AI to implement each component following the design
- Run tests
- If tests fail, paste errors back to AI and ask for fixes
- Iterate until all tests pass
- Commit with clear message referencing design doc and tests
Automated
Component Coding Sessions orchestrator implements and iterates until green
lib/code_my_spec/stories.ex
The Proof
I built CodeMySpec using this method. The codebase is the proof.
- Stories context: Generated from design docs
- Components context: Generated from design docs
- Sessions orchestration: Generated from design docs
- MCP servers: Generated from design docs
- This entire application: Built with the product
Getting Started
Manual Process
Learn the methodology, works with any framework
Best for:
- Learning the method
- Non-Phoenix projects
- Small projects
- Prefer more control
Steps:
- Read "Managing User Stories" guide
- Create user_stories.md
- Map contexts
- Write one design doc
- Write tests
- Generate code with design + tests
Automated Workflow
Full automation with CodeMySpec, Phoenix/Elixir only
Best for:
- Phoenix/Elixir projects
- Want maximum speed
- Trust the automated workflow
- Medium/large projects
Steps:
- Install CodeMySpec
- Run setup session
- Interview generates stories
- Review generated designs
- Approve and generate code
FAQ
Update stories → regenerate designs → update tests → regenerate code. Version control shows impact. The process supports change.
Manual process works anywhere. Automation is Phoenix/Elixir only (for now).
No. Manual process is copy-paste. MCP removes tedium.
They optimize prompts. This controls context. Different approach.
Tests catch it. Iterate until green. If repeatedly failing, refine design. Tests are the validation gate.
Less overhead than refactoring AI-generated technical debt. Manual process takes time; automation removes overhead.