feat(docs): add development methodologies documentation v3.5.0
- Add guide/methodologies.md: index of 15 methodologies with decision tree - Add guide/workflows/: 4 practical workflow guides - tdd-with-claude.md: TDD with Claude-specific patterns - spec-first.md: SDD adapted for CLAUDE.md - plan-driven.md: effective /plan mode usage - iterative-refinement.md: prompt→feedback→reprompt loops - Add Section 9.14 in ultimate-guide.md linking to workflows - Update guide/README.md with new documentation - Bump version 3.4.0 → 3.5.0 across all files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
f9044e2deb
commit
f7551037fe
11 changed files with 1638 additions and 5 deletions
47
CHANGELOG.md
47
CHANGELOG.md
|
|
@ -6,6 +6,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|||
|
||||
## [Unreleased]
|
||||
|
||||
## [3.5.0] - 2026-01-14
|
||||
|
||||
### Added - Development Methodologies & Workflows
|
||||
|
||||
Comprehensive documentation covering 15 structured development methodologies for AI-assisted development (2025-2026), with practical workflow guides.
|
||||
|
||||
#### New Files
|
||||
- **guide/methodologies.md** (NEW, ~400 lines) - Complete methodology reference:
|
||||
- 15 methodologies organized in 6-tier pyramid (Orchestration → Optimization)
|
||||
- BMAD, SDD, TDD, BDD, DDD, ATDD, CDD, FDD, Context Engineering, Eval-Driven, Multi-Agent, Iterative Loops, Prompt Engineering
|
||||
- Decision tree for choosing the right approach
|
||||
- SDD tools reference (Spec Kit, OpenSpec, Specmatic)
|
||||
- Combination patterns by project type
|
||||
- Claude Fit ratings for each methodology
|
||||
|
||||
- **guide/workflows/** (NEW directory, 4 files, ~700 lines total):
|
||||
- **tdd-with-claude.md** - Test-Driven Development workflow with Claude-specific prompting patterns
|
||||
- **spec-first.md** - Spec-First Development (SDD) adapted for CLAUDE.md
|
||||
- **plan-driven.md** - Effective use of /plan mode
|
||||
- **iterative-refinement.md** - Prompt → Observe → Reprompt loops
|
||||
|
||||
#### Guide Updates
|
||||
- **guide/ultimate-guide.md** - Section 9.14 "Development Methodologies" (NEW, ~60 lines):
|
||||
- Quick decision tree for workflow selection
|
||||
- 4 core workflows summary table
|
||||
- 15 methodologies reference table
|
||||
- SDD tools overview
|
||||
- Combination patterns by situation
|
||||
|
||||
#### Navigation Updates
|
||||
- **guide/README.md** - Contents table updated with methodologies.md and workflows/
|
||||
|
||||
### Sources
|
||||
- Anthropic Engineering Blog (claude-code-best-practices, context-engineering)
|
||||
- GitHub (Spec Kit official announcement)
|
||||
- Martin Fowler (SDD essays)
|
||||
- Fission AI (OpenSpec)
|
||||
- Specmatic.io
|
||||
- Community production reports (2025-2026)
|
||||
|
||||
### Stats
|
||||
- 5 new files created (~1,100 lines total)
|
||||
- 2 files modified (ultimate-guide.md, guide/README.md)
|
||||
- Focus on practical, actionable workflows over theory
|
||||
|
||||
---
|
||||
|
||||
## [3.4.0] - 2026-01-14
|
||||
|
||||
### Added - Architecture & Internals Documentation
|
||||
|
|
|
|||
|
|
@ -519,7 +519,7 @@ If this guide saved you time, helped you master Claude Code, or inspired your wo
|
|||
|
||||
---
|
||||
|
||||
*Version 3.4.0 | January 2026 | Crafted with Claude*
|
||||
*Version 3.5.0 | January 2026 | Crafted with Claude*
|
||||
|
||||
<!-- SEO Keywords -->
|
||||
<!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
|
||||
|
|
|
|||
|
|
@ -12,6 +12,19 @@ Core documentation for mastering Claude Code.
|
|||
| [adoption-approaches.md](./adoption-approaches.md) | Implementation strategies for teams | 15 min |
|
||||
| [data-privacy.md](./data-privacy.md) | Data retention and privacy guide | 10 min |
|
||||
| [observability.md](./observability.md) | Session monitoring and cost tracking | 15 min |
|
||||
| [methodologies.md](./methodologies.md) | 15 development methodologies reference (TDD, SDD, BDD, etc.) | 20 min |
|
||||
| [workflows/](./workflows/) | Practical workflow guides for Claude Code | 30 min |
|
||||
|
||||
### Workflows
|
||||
|
||||
Hands-on guides for effective development patterns:
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [workflows/tdd-with-claude.md](./workflows/tdd-with-claude.md) | Test-Driven Development with Claude |
|
||||
| [workflows/spec-first.md](./workflows/spec-first.md) | Spec-First Development (SDD) |
|
||||
| [workflows/plan-driven.md](./workflows/plan-driven.md) | Using /plan mode effectively |
|
||||
| [workflows/iterative-refinement.md](./workflows/iterative-refinement.md) | Iterative improvement loops |
|
||||
|
||||
## Recommended Reading Order
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
**Written with**: Claude (Anthropic)
|
||||
|
||||
**Version**: 3.4.0 | **Last Updated**: January 2026
|
||||
**Version**: 3.5.0 | **Last Updated**: January 2026
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -393,4 +393,4 @@ where.exe claude; claude doctor; claude mcp list
|
|||
|
||||
**Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
|
||||
|
||||
*Last updated: January 2026 | Version 3.2.0*
|
||||
*Last updated: January 2026 | Version 3.5.0*
|
||||
|
|
|
|||
319
guide/methodologies.md
Normal file
319
guide/methodologies.md
Normal file
|
|
@ -0,0 +1,319 @@
|
|||
# Development Methodologies Reference
|
||||
|
||||
> **Confidence**: Tier 2 — Validated by multiple production reports and official documentation.
|
||||
>
|
||||
> **Last updated**: January 2026
|
||||
|
||||
This is a quick reference for 15 structured development methodologies that have emerged for AI-assisted development in 2025-2026. For hands-on practical workflows, see [workflows/](./workflows/).
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Decision Tree](#decision-tree-what-do-you-need)
|
||||
2. [The 15 Methodologies](#the-15-methodologies)
|
||||
3. [SDD Tools Reference](#sdd-tools-reference)
|
||||
4. [Combination Patterns](#combination-patterns)
|
||||
5. [Sources](#sources)
|
||||
|
||||
---
|
||||
|
||||
## Decision Tree: What Do You Need?
|
||||
|
||||
```
|
||||
┌─ "I want quality code" ────────────→ workflows/tdd-with-claude.md
|
||||
│
|
||||
├─ "I want to spec before code" ─────→ workflows/spec-first.md
|
||||
│
|
||||
├─ "I need to plan architecture" ────→ workflows/plan-driven.md
|
||||
│
|
||||
├─ "I'm iterating on something" ─────→ workflows/iterative-refinement.md
|
||||
│
|
||||
└─ "I need methodology theory" ──────→ Continue reading below
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The 15 Methodologies
|
||||
|
||||
Organized in a 6-tier pyramid from strategic orchestration down to optimization techniques.
|
||||
|
||||
### Tier 1: Strategic Orchestration
|
||||
|
||||
| Name | What | Best For | Claude Fit |
|
||||
|------|------|----------|------------|
|
||||
| **BMAD** | Multi-agent governance with constitution as guardrail | Enterprise 10+ teams, long-term projects | ⭐⭐ Niche but powerful |
|
||||
|
||||
**BMAD (Breakthrough Method for Agile AI-Driven Development)** inverts the traditional paradigm: documentation becomes the source of truth, not code. Uses specialized agents (Analyst, PM, Architect, Developer, QA) orchestrated with strict governance.
|
||||
|
||||
- **Key concept**: Constitution.md as strategic guardrail
|
||||
- **When to use**: Complex enterprise projects needing governance
|
||||
- **When to avoid**: Small teams, MVPs, rapid prototyping
|
||||
|
||||
---
|
||||
|
||||
### Tier 2: Specification & Architecture
|
||||
|
||||
| Name | What | Best For | Claude Fit |
|
||||
|------|------|----------|------------|
|
||||
| **SDD** | Specs before code | APIs, contracts | ⭐⭐⭐ Core pattern |
|
||||
| **Doc-Driven** | Docs = source of truth | Cross-team alignment | ⭐⭐⭐ CLAUDE.md native |
|
||||
| **Req-Driven** | Rich artifact context (20+ artifacts) | Complex requirements | ⭐⭐ Heavy setup |
|
||||
| **DDD** | Domain language first | Business logic | ⭐⭐ Design-time |
|
||||
|
||||
**SDD (Spec-Driven Development)** — Specifications BEFORE code. One well-structured iteration equals 8 unstructured ones. CLAUDE.md IS your spec file.
|
||||
|
||||
**Doc-Driven Development** — Living documentation versioned in git becomes the single source of truth. Changes to specs trigger implementation.
|
||||
|
||||
**Requirements-Driven Development** — Uses CLAUDE.md as comprehensive implementation guide with 20+ structured artifacts.
|
||||
|
||||
**DDD (Domain-Driven Design)** — Aligns software with business language through:
|
||||
- Ubiquitous Language: Shared vocabulary in code
|
||||
- Bounded Contexts: Isolated domain boundaries
|
||||
- Domain Distillation: Core vs Support vs Generic domains
|
||||
|
||||
---
|
||||
|
||||
### Tier 3: Behavior & Acceptance
|
||||
|
||||
| Name | What | Best For | Claude Fit |
|
||||
|------|------|----------|------------|
|
||||
| **BDD** | Given-When-Then scenarios | Stakeholder collaboration | ⭐⭐⭐ Tests & specs |
|
||||
| **ATDD** | Acceptance criteria first | Compliance, regulated | ⭐⭐ Process-heavy |
|
||||
| **CDD** | API contracts as interface | Microservices | ⭐⭐⭐ OpenAPI native |
|
||||
|
||||
**BDD (Behavior-Driven Development)** — Beyond testing: a collaboration process.
|
||||
1. Discovery: Involve devs and business experts
|
||||
2. Formulation: Write Given-When-Then examples
|
||||
3. Automation: Convert to executable tests (Gherkin/Cucumber)
|
||||
|
||||
```gherkin
|
||||
Feature: Order Management
|
||||
Scenario: Cannot buy without stock
|
||||
Given product with 0 stock
|
||||
When customer attempts purchase
|
||||
Then system refuses with error message
|
||||
```
|
||||
|
||||
**ATDD (Acceptance Test-Driven Development)** — Acceptance criteria defined BEFORE coding, collaboratively ("Three Amigos": Business, Dev, Test).
|
||||
|
||||
**CDD (Contract-Driven Development)** — API contracts (OpenAPI specs) as executable interface between teams. Patterns: Contract as Test, Contract as Stub.
|
||||
|
||||
---
|
||||
|
||||
### Tier 4: Feature Delivery
|
||||
|
||||
| Name | What | Best For | Claude Fit |
|
||||
|------|------|----------|------------|
|
||||
| **FDD** | Feature-by-feature delivery | Large teams 10+ | ⭐⭐ Structure |
|
||||
| **Context Eng.** | Context as first-class design | Long sessions | ⭐⭐⭐ Fundamental |
|
||||
|
||||
**FDD (Feature-Driven Development)** — Five processes:
|
||||
1. Develop Overall Model
|
||||
2. Build Features List
|
||||
3. Plan by Feature
|
||||
4. Design by Feature
|
||||
5. Build by Feature
|
||||
|
||||
Strict iteration: 2 weeks max per feature.
|
||||
|
||||
**Context Engineering** — Treat context as design element:
|
||||
- Progressive Disclosure: Let agent discover incrementally
|
||||
- Memory Management: Conversation vs persistent memory
|
||||
- Dynamic Refresh: Rewrite TODO list before response
|
||||
|
||||
---
|
||||
|
||||
### Tier 5: Implementation
|
||||
|
||||
| Name | What | Best For | Claude Fit |
|
||||
|------|------|----------|------------|
|
||||
| **TDD** | Red-Green-Refactor | Quality code | ⭐⭐⭐ Core workflow |
|
||||
| **Eval-Driven** | Evals for LLM outputs | AI products | ⭐⭐⭐ Agents |
|
||||
| **Multi-Agent** | Orchestrate sub-agents | Complex tasks | ⭐⭐⭐ Task tool |
|
||||
|
||||
**TDD (Test-Driven Development)** — The classic cycle:
|
||||
1. **Red**: Write failing test
|
||||
2. **Green**: Minimal code to pass
|
||||
3. **Refactor**: Clean up, tests stay green
|
||||
|
||||
With Claude: Be explicit. "Write FAILING tests that don't exist yet."
|
||||
|
||||
**Eval-Driven Development** — TDD for LLMs. Test agent behaviors via evals:
|
||||
- Code-based: `output == golden_answer`
|
||||
- LLM-based: Another Claude evaluates
|
||||
- Human grading: Reference, slow
|
||||
|
||||
**Multi-Agent Orchestration** — From single assistant to orchestrated team:
|
||||
```
|
||||
Meta-Agent (Orchestrator)
|
||||
├── Analyst (requirements)
|
||||
├── Architect (design)
|
||||
├── Developer (code)
|
||||
└── Reviewer (validation)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Tier 6: Optimization
|
||||
|
||||
| Name | What | Best For | Claude Fit |
|
||||
|------|------|----------|------------|
|
||||
| **Iterative Loops** | Autonomous refinement | Optimization | ⭐⭐⭐ Core |
|
||||
| **Prompt Engineering** | Technique foundation | Everything | ⭐⭐⭐ Prerequisite |
|
||||
|
||||
**Iterative Refinement Loops** — Autonomous convergence:
|
||||
1. Execute prompt
|
||||
2. Observe result
|
||||
3. If result ≠ "DONE" → refine and repeat
|
||||
|
||||
**Prompt Engineering** — Foundations for ALL Claude usage:
|
||||
- Zero-Shot Chain of Thought: "Think step by step"
|
||||
- Few-Shot Learning: 2-3 examples of expected pattern
|
||||
- Structured Prompts: XML tags for organization
|
||||
- Position Matters: For long docs, place question at end
|
||||
|
||||
---
|
||||
|
||||
## SDD Tools Reference
|
||||
|
||||
Three tools have emerged to formalize Spec-Driven Development:
|
||||
|
||||
| Tool | Use Case | Official Docs | Claude Integration |
|
||||
|------|----------|---------------|-------------------|
|
||||
| **Spec Kit** | Greenfield, governance | [github.blog/spec-kit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) | `/speckit.constitution`, `/speckit.specify`, `/speckit.plan` |
|
||||
| **OpenSpec** | Brownfield, changes | [github.com/Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
|
||||
| **Specmatic** | API contract testing | [specmatic.io](https://specmatic.io) | MCP agent available |
|
||||
|
||||
### Spec Kit (Greenfield)
|
||||
|
||||
5-phase workflow:
|
||||
1. Constitution: `/speckit.constitution` → guardrails
|
||||
2. Specify: `/speckit.specify` → requirements
|
||||
3. Plan: `/speckit.plan` → architecture
|
||||
4. Tasks: `/speckit.tasks` → decomposition
|
||||
5. Implement: `/speckit.implement` → code
|
||||
|
||||
### OpenSpec (Brownfield)
|
||||
|
||||
Two-folder architecture:
|
||||
```
|
||||
openspec/
|
||||
├── specs/ ← Current truth (stable)
|
||||
└── changes/ ← Proposals (temporary)
|
||||
```
|
||||
|
||||
Workflow: Proposal → Review → Apply → Archive
|
||||
|
||||
### Specmatic (API Contracts)
|
||||
|
||||
- **Contract as Test**: Auto-generates 1000s of tests from OpenAPI spec
|
||||
- **Contract as Stub**: Mock server for parallel development
|
||||
- **Backward Compatibility**: Detects breaking changes
|
||||
|
||||
---
|
||||
|
||||
## Combination Patterns
|
||||
|
||||
Recommended stacks by situation:
|
||||
|
||||
| Situation | Recommended Stack | Notes |
|
||||
|-----------|-------------------|-------|
|
||||
| Solo MVP | SDD + TDD | Minimal overhead, quality focus |
|
||||
| Team 5-10, greenfield | Spec Kit + TDD + BDD | Governance + quality + collaboration |
|
||||
| Microservices | CDD + Specmatic | Contract-first, parallel dev |
|
||||
| Existing SaaS (100+ features) | OpenSpec + BDD | Change tracking, no spec drift |
|
||||
| Enterprise 10+ | BMAD + Spec Kit + Specmatic | Full governance + contracts |
|
||||
| LLM-native product | Eval-Driven + Multi-Agent | Self-improving systems |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Table
|
||||
|
||||
| Methodology | Level | Primary Focus | Team Size | Learning Curve |
|
||||
|-------------|-------|---------------|-----------|----------------|
|
||||
| BMAD | Orchestration | Governance | 10+ | High |
|
||||
| SDD | Specification | Contracts | Any | Medium |
|
||||
| Doc-Driven | Specification | Alignment | Any | Low |
|
||||
| Req-Driven | Specification | Context | 5+ | Medium |
|
||||
| DDD | Specification | Domain | 5+ | Very High |
|
||||
| BDD | Behavior | Collaboration | 5+ | Medium |
|
||||
| ATDD | Behavior | Compliance | 5+ | Medium |
|
||||
| CDD | Behavior | APIs | 5+ | Medium |
|
||||
| FDD | Delivery | Features | 10+ | Medium |
|
||||
| Context Eng. | Delivery | AI sessions | Any | Low |
|
||||
| TDD | Implementation | Quality | Any | Low |
|
||||
| Eval-Driven | Implementation | AI outputs | Any | Medium |
|
||||
| Multi-Agent | Implementation | Complexity | Any | Medium |
|
||||
| Iterative | Optimization | Refinement | Any | Low |
|
||||
| Prompt Eng. | Optimization | Foundation | Any | Very Low |
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
### Official Documentation (Tier 1)
|
||||
|
||||
- Anthropic: [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
|
||||
- Anthropic: [Effective Context Engineering for AI Agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
|
||||
- Anthropic: [Demystifying Evals for AI Agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
|
||||
- GitHub: [Spec-Driven Development Toolkit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
|
||||
- Microsoft: [Spec-Driven Development with Spec Kit](https://developer.microsoft.com/blog/spec-driven-development-spec-kit)
|
||||
|
||||
### Methodology References (Tier 2)
|
||||
|
||||
**SDD & Spec-First**
|
||||
- Martin Fowler: [SDD Tools Analysis](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
|
||||
- InfoQ: [Spec-Driven Development](https://www.infoq.com/articles/spec-driven-development/)
|
||||
- Kinde: [Beyond TDD - Why SDD is the Next Step](https://kinde.com/learn/ai-for-software-engineering/best-practice/beyond-tdd-why-spec-driven-development-is-the-next-step/)
|
||||
- Tessl.io: [Spec-Driven Dev with Claude Code](https://tessl.io/blog/spec-driven-dev-with-claude-code/)
|
||||
|
||||
**BMAD**
|
||||
- GMO Recruit: [The BMAD Method](https://recruit.group.gmo/engineer/jisedai/blog/the-bmad-method-a-framework-for-spec-oriented-ai-driven-development/)
|
||||
- Benny Cheung: [BMAD - Reclaiming Control in AI Dev](https://bennycheung.github.io/bmad-reclaiming-control-in-ai-dev)
|
||||
- GitHub: [BMAD-AT-CLAUDE](https://github.com/24601/BMAD-AT-CLAUDE)
|
||||
|
||||
**TDD with AI**
|
||||
- Steve Kinney: [TDD with Claude](https://stevekinney.com/courses/ai-development/test-driven-development-with-claude)
|
||||
- Nathan Fox: [Taming GenAI Agents](https://www.nathanfox.net/p/taming-genai-agents-like-claude-code)
|
||||
- Alex Op: [Custom TDD Workflow Claude Code](https://alexop.dev/posts/custom-tdd-workflow-claude-code-vue/)
|
||||
|
||||
**BDD & DDD**
|
||||
- Alex Soyes: [BDD Behavior-Driven Development](https://alexsoyes.com/bdd-behavior-driven-development/)
|
||||
- Alex Soyes: [DDD Domain-Driven Design](https://alexsoyes.com/ddd-domain-driven-design/)
|
||||
- Inflectra: [Behavior-Driven Development](https://www.inflectra.com/Ideas/Topic/Behavior-Driven-Development.aspx)
|
||||
|
||||
**Context Engineering**
|
||||
- Intuition Labs: [What is Context Engineering](https://intuitionlabs.ai/articles/what-is-context-engineering)
|
||||
- Manus.im: [Context Engineering for AI Agents](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)
|
||||
|
||||
**Eval-Driven & Multi-Agent**
|
||||
- Fireworks AI: [Eval-Driven Development with Claude Code](https://fireworks.ai/blog/eval-driven-development-with-claude-code)
|
||||
- Brandon Casci: [Transform into a Dev Team using Claude Code Agents](https://www.brandoncasci.com/2025/09/21/how-to-transform-yourself-into-a-dev-team-using-claude-codes-ai-agents.html)
|
||||
- The Unwind AI: [Claude Code's Multi-Agent Orchestration](https://www.theunwindai.com/p/claude-code-s-hidden-multi-agent-orchestration-now-open-source)
|
||||
|
||||
### Tools Documentation (Tier 1)
|
||||
|
||||
- OpenSpec: [github.com/Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
|
||||
- Spec Kit: [github.com/github/spec-kit](https://github.com/github/spec-kit)
|
||||
- Specmatic: [specmatic.io](https://specmatic.io)
|
||||
- Specmatic Article: [Spec-Driven Development with GitHub Spec Kit and Specmatic MCP](https://specmatic.io/article/spec-driven-development-api-design-first-with-github-spec-kit-and-specmatic-mcp/)
|
||||
|
||||
### Additional References
|
||||
|
||||
- Talent500: [Claude Code TDD Guide](https://talent500.com/blog/claude-code-test-driven-development-guide/)
|
||||
- Testlio: [Acceptance Test-Driven Development](https://testlio.com/blog/what-is-acceptance-test-driven-development/)
|
||||
- Monday.com: [Feature-Driven Development](https://monday.com/blog/rnd/feature-driven-development-fdd/)
|
||||
- Paddo.dev: [Ralph Wiggum Autonomous Loops](https://paddo.dev/blog/ralph-wiggum-autonomous-loops/)
|
||||
- Walturn: [Prompt Engineering for Claude](https://www.walturn.com/insights/mastering-prompt-engineering-for-claude)
|
||||
- AWS: [Prompt Engineering with Claude on Bedrock](https://aws.amazon.com/blogs/machine-learning/prompt-engineering-techniques-and-best-practices-learn-by-doing-with-anthropics-claude-3-on-amazon-bedrock/)
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [workflows/tdd-with-claude.md](./workflows/tdd-with-claude.md) — Practical TDD guide
|
||||
- [workflows/spec-first.md](./workflows/spec-first.md) — Spec-first development
|
||||
- [workflows/plan-driven.md](./workflows/plan-driven.md) — Using /plan mode
|
||||
- [workflows/iterative-refinement.md](./workflows/iterative-refinement.md) — Refinement loops
|
||||
- [ultimate-guide.md#912](./ultimate-guide.md) — Section 9.12 summary
|
||||
|
|
@ -10,7 +10,7 @@
|
|||
|
||||
**Last updated**: January 2026
|
||||
|
||||
**Version**: 3.4.0
|
||||
**Version**: 3.5.0
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -8106,6 +8106,67 @@ Time savings from effective Claude Code usage typically far outweigh API costs f
|
|||
|
||||
---
|
||||
|
||||
## 9.14 Development Methodologies
|
||||
|
||||
> **Full reference**: [methodologies.md](./methodologies.md) | **Hands-on workflows**: [workflows/](./workflows/)
|
||||
|
||||
15 structured development methodologies have emerged for AI-assisted development (2025-2026). This section provides quick navigation; detailed workflows are in dedicated files.
|
||||
|
||||
### Quick Decision Tree
|
||||
|
||||
```
|
||||
┌─ "I want quality code" ────────────→ workflows/tdd-with-claude.md
|
||||
├─ "I want to spec before code" ─────→ workflows/spec-first.md
|
||||
├─ "I need to plan architecture" ────→ workflows/plan-driven.md
|
||||
├─ "I'm iterating on something" ─────→ workflows/iterative-refinement.md
|
||||
└─ "I need methodology theory" ──────→ methodologies.md
|
||||
```
|
||||
|
||||
### The 4 Core Workflows for Claude Code
|
||||
|
||||
| Workflow | When to Use | Key Prompt Pattern |
|
||||
|----------|-------------|-------------------|
|
||||
| **TDD** | Quality-critical code | "Write FAILING tests first, then implement" |
|
||||
| **Spec-First** | New features, APIs | Define in CLAUDE.md before asking |
|
||||
| **Plan-Driven** | Multi-file changes | Use `/plan` mode |
|
||||
| **Iterative** | Refinement | Specific feedback: "Change X because Y" |
|
||||
|
||||
### The 15 Methodologies (Reference)
|
||||
|
||||
| Tier | Methodologies | Claude Fit |
|
||||
|------|--------------|------------|
|
||||
| Orchestration | BMAD | ⭐⭐ Enterprise governance |
|
||||
| Specification | SDD, Doc-Driven, Req-Driven, DDD | ⭐⭐⭐ Core patterns |
|
||||
| Behavior | BDD, ATDD, CDD | ⭐⭐⭐ Testing focus |
|
||||
| Delivery | FDD, Context Engineering | ⭐⭐ Process |
|
||||
| Implementation | TDD, Eval-Driven, Multi-Agent | ⭐⭐⭐ Core workflows |
|
||||
| Optimization | Iterative Loops, Prompt Engineering | ⭐⭐⭐ Foundation |
|
||||
|
||||
→ Full descriptions with examples: [methodologies.md](./methodologies.md)
|
||||
|
||||
### SDD Tools (External)
|
||||
|
||||
| Tool | Use Case | Integration |
|
||||
|------|----------|-------------|
|
||||
| **Spec Kit** | Greenfield projects | `/speckit.*` slash commands |
|
||||
| **OpenSpec** | Brownfield/existing | `/openspec:*` slash commands |
|
||||
| **Specmatic** | API contract testing | MCP agent available |
|
||||
|
||||
→ See official documentation for installation and detailed usage.
|
||||
|
||||
### Combination Patterns
|
||||
|
||||
| Situation | Recommended Stack |
|
||||
|-----------|-------------------|
|
||||
| Solo MVP | SDD + TDD |
|
||||
| Team 5-10, greenfield | Spec Kit + TDD + BDD |
|
||||
| Microservices | CDD + Specmatic |
|
||||
| Existing SaaS | OpenSpec + BDD |
|
||||
| Enterprise 10+ | BMAD + Spec Kit |
|
||||
| LLM-native product | Eval-Driven + Multi-Agent |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Section 9 Recap: Pattern Mastery Checklist
|
||||
|
||||
Before moving to Section 10 (Reference), verify you understand:
|
||||
|
|
@ -8126,6 +8187,7 @@ Before moving to Section 10 (Reference), verify you understand:
|
|||
- [ ] **Common Pitfalls**: Understand security, performance, workflow mistakes
|
||||
- [ ] **Continuous Improvement**: Refine over multiple sessions with learning mindset
|
||||
- [ ] **Best Practices**: Do/Don't patterns for professional work
|
||||
- [ ] **Development Methodologies**: TDD, SDD, BDD, and other structured approaches
|
||||
|
||||
### What's Next?
|
||||
|
||||
|
|
|
|||
312
guide/workflows/iterative-refinement.md
Normal file
312
guide/workflows/iterative-refinement.md
Normal file
|
|
@ -0,0 +1,312 @@
|
|||
# Iterative Refinement
|
||||
|
||||
> **Confidence**: Tier 2 — Validated pattern observed across many Claude Code users.
|
||||
|
||||
Prompt, observe, reprompt until satisfied. The core loop of effective AI-assisted development.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [TL;DR](#tldr)
|
||||
2. [The Loop](#the-loop)
|
||||
3. [Feedback Patterns](#feedback-patterns)
|
||||
4. [Autonomous Loops](#autonomous-loops)
|
||||
5. [Integration with Claude Code](#integration-with-claude-code)
|
||||
6. [Anti-Patterns](#anti-patterns)
|
||||
7. [See Also](#see-also)
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
```
|
||||
1. Initial prompt with clear goal
|
||||
2. Claude produces output
|
||||
3. Evaluate against criteria
|
||||
4. Specific feedback: "Change X because Y"
|
||||
5. Repeat until done
|
||||
```
|
||||
|
||||
Key insight: **Specific feedback > vague feedback**
|
||||
|
||||
---
|
||||
|
||||
## The Loop
|
||||
|
||||
### Step 1: Initial Prompt
|
||||
|
||||
Start with clear intent and constraints:
|
||||
|
||||
```
|
||||
Create a React component for a user profile card.
|
||||
- Show avatar, name, bio
|
||||
- Include edit button
|
||||
- Use Tailwind CSS
|
||||
- Mobile-responsive
|
||||
```
|
||||
|
||||
### Step 2: Evaluate Output
|
||||
|
||||
Claude produces code. Evaluate:
|
||||
- Does it meet requirements?
|
||||
- What's missing?
|
||||
- What's wrong?
|
||||
- What could be better?
|
||||
|
||||
### Step 3: Specific Feedback
|
||||
|
||||
Provide targeted corrections:
|
||||
|
||||
```
|
||||
Good start. Changes needed:
|
||||
1. Avatar should be circular, not square
|
||||
2. Edit button should only show for own profile (add isOwner prop)
|
||||
3. Bio should truncate after 3 lines with "Show more"
|
||||
```
|
||||
|
||||
### Step 4: Repeat
|
||||
|
||||
Continue until satisfied:
|
||||
|
||||
```
|
||||
Better. One more thing:
|
||||
- Add loading skeleton state for when data is fetching
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feedback Patterns
|
||||
|
||||
### Effective Feedback
|
||||
|
||||
| Pattern | Example |
|
||||
|---------|---------|
|
||||
| **Specific location** | "Line 23: change `===` to `==`" |
|
||||
| **Clear action** | "Add error boundary around the form" |
|
||||
| **Reason given** | "Remove the console.log because it leaks user data" |
|
||||
| **Priority marked** | "Critical: fix the SQL injection. Nice-to-have: add pagination." |
|
||||
|
||||
### Ineffective Feedback
|
||||
|
||||
| Anti-Pattern | Why It Fails | Better Alternative |
|
||||
|--------------|--------------|-------------------|
|
||||
| "Make it better" | No direction | "Improve readability by extracting the validation logic" |
|
||||
| "This is wrong" | No specifics | "The date format should be ISO 8601, not Unix timestamp" |
|
||||
| "I don't like it" | Subjective | "Use functional components instead of class components" |
|
||||
| "Fix the bugs" | Too vague | "Fix: 1) null check on line 12, 2) off-by-one in loop" |
|
||||
|
||||
---
|
||||
|
||||
## Autonomous Loops
|
||||
|
||||
Claude can self-iterate with clear completion criteria.
|
||||
|
||||
### The Ralph Wiggum Pattern
|
||||
|
||||
Named after the self-improvement loop pattern:
|
||||
|
||||
```
|
||||
Keep improving the code quality until:
|
||||
1. All tests pass
|
||||
2. No TypeScript errors
|
||||
3. ESLint shows zero warnings
|
||||
|
||||
After each iteration, run the checks and fix any issues.
|
||||
Stop when all criteria are met.
|
||||
```
|
||||
|
||||
### Completion Criteria Examples
|
||||
|
||||
```
|
||||
Iterate until:
|
||||
- Response time < 100ms for 95th percentile
|
||||
- Test coverage > 80%
|
||||
- All accessibility checks pass
|
||||
- Bundle size < 200KB
|
||||
```
|
||||
|
||||
### Iteration Limits
|
||||
|
||||
Always set limits to prevent infinite loops:
|
||||
|
||||
```
|
||||
Improve the algorithm performance.
|
||||
Maximum 5 iterations.
|
||||
Stop early if improvement < 5% between iterations.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Claude Code
|
||||
|
||||
### With TodoWrite
|
||||
|
||||
Track refinement iterations:
|
||||
|
||||
```
|
||||
TodoWrite:
|
||||
- [x] Initial implementation
|
||||
- [x] Fix: handle empty arrays
|
||||
- [x] Fix: add input validation
|
||||
- [ ] Optimization: memoize expensive calculations
|
||||
```
|
||||
|
||||
### With Hooks
|
||||
|
||||
Auto-validate after each change:
|
||||
|
||||
```yaml
|
||||
# .claude/hooks.yaml
|
||||
post_edit:
|
||||
- command: "npm run lint && npm test"
|
||||
on_failure: "report"
|
||||
```
|
||||
|
||||
Claude sees failures and can self-correct.
|
||||
|
||||
### With /compact
|
||||
|
||||
When context grows during iterations:
|
||||
|
||||
```
|
||||
/compact
|
||||
|
||||
Continue refining the search algorithm.
|
||||
We've made good progress, focus on the remaining issues.
|
||||
```
|
||||
|
||||
### Checkpointing
|
||||
|
||||
After significant progress:
|
||||
|
||||
```
|
||||
Good progress. Let's checkpoint:
|
||||
- Commit what we have
|
||||
- List remaining issues
|
||||
- Continue with the next priority
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Iteration Strategies
|
||||
|
||||
### Breadth-First
|
||||
|
||||
Fix all issues at same level before going deeper:
|
||||
|
||||
```
|
||||
First pass: Fix all type errors
|
||||
Second pass: Fix all lint warnings
|
||||
Third pass: Improve test coverage
|
||||
Fourth pass: Optimize performance
|
||||
```
|
||||
|
||||
### Depth-First
|
||||
|
||||
Complete one area fully before moving on:
|
||||
|
||||
```
|
||||
1. Perfect the authentication flow (all aspects)
|
||||
2. Then move to user management
|
||||
3. Then move to settings
|
||||
```
|
||||
|
||||
### Priority-Based
|
||||
|
||||
Address by importance:
|
||||
|
||||
```
|
||||
Iterate in this order:
|
||||
1. Security issues (critical)
|
||||
2. Data integrity bugs (high)
|
||||
3. UX problems (medium)
|
||||
4. Code style (low)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### Moving Target
|
||||
|
||||
```
|
||||
# Wrong
|
||||
"Actually, let's change the approach entirely..."
|
||||
(Repeated 5 times)
|
||||
|
||||
# Right
|
||||
Commit to an approach, iterate within it.
|
||||
If approach is wrong, explicitly restart.
|
||||
```
|
||||
|
||||
### Perfectionism Loop
|
||||
|
||||
```
|
||||
# Wrong
|
||||
Keep improving forever
|
||||
|
||||
# Right
|
||||
Set clear "good enough" criteria:
|
||||
- Tests pass
|
||||
- Handles main use cases
|
||||
- No critical issues
|
||||
→ Ship it, improve later
|
||||
```
|
||||
|
||||
### Lost Context
|
||||
|
||||
```
|
||||
# Wrong
|
||||
After 50 iterations, forget what the goal was
|
||||
|
||||
# Right
|
||||
Periodically restate the goal:
|
||||
"Reminder: we're building a rate limiter.
|
||||
Current state: basic implementation works.
|
||||
Next: add Redis backend."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example Session
|
||||
|
||||
### Initial Request
|
||||
```
|
||||
Create a debounce function in TypeScript.
|
||||
```
|
||||
|
||||
### Iteration 1
|
||||
```
|
||||
Looks good. Add:
|
||||
- Generic type support for any function signature
|
||||
- Option to execute on leading edge
|
||||
```
|
||||
|
||||
### Iteration 2
|
||||
```
|
||||
Better. Issues:
|
||||
- The return type should preserve the original function's return type
|
||||
- Add cancellation support
|
||||
```
|
||||
|
||||
### Iteration 3
|
||||
```
|
||||
Almost there. Final polish:
|
||||
- Add JSDoc comments
|
||||
- Export the types separately
|
||||
- Add unit tests
|
||||
```
|
||||
|
||||
### Completion
|
||||
```
|
||||
Perfect. Commit this as "feat: add debounce utility with full TypeScript support"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [tdd-with-claude.md](./tdd-with-claude.md) — TDD is iterative refinement with tests
|
||||
- [plan-driven.md](./plan-driven.md) — Plan before iterating
|
||||
- [../methodologies.md](../methodologies.md) — Iterative Loops methodology
|
||||
250
guide/workflows/plan-driven.md
Normal file
250
guide/workflows/plan-driven.md
Normal file
|
|
@ -0,0 +1,250 @@
|
|||
# Plan-Driven Development
|
||||
|
||||
> **Confidence**: Tier 1 — Based on Claude Code's native /plan mode functionality.
|
||||
|
||||
Use `/plan` mode for anything non-trivial. Claude explores the codebase (read-only), then proposes an implementation plan for your approval.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [TL;DR](#tldr)
|
||||
2. [The /plan Workflow](#the-plan-workflow)
|
||||
3. [When to Use](#when-to-use)
|
||||
4. [Plan File Structure](#plan-file-structure)
|
||||
5. [Integration with Other Workflows](#integration-with-other-workflows)
|
||||
6. [Tips](#tips)
|
||||
7. [See Also](#see-also)
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
```
|
||||
1. /plan (or ask complex question)
|
||||
2. Claude explores codebase (read-only)
|
||||
3. Claude writes plan to .claude/plans/
|
||||
4. You review and approve
|
||||
5. Claude executes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The /plan Workflow
|
||||
|
||||
### Step 1: Enter Plan Mode
|
||||
|
||||
Either use the slash command:
|
||||
```
|
||||
/plan
|
||||
```
|
||||
|
||||
Or ask a complex question that triggers plan mode automatically:
|
||||
```
|
||||
How should I refactor the authentication system to support OAuth?
|
||||
```
|
||||
|
||||
### Step 2: Claude Explores
|
||||
|
||||
In plan mode, Claude:
|
||||
- Reads relevant files
|
||||
- Searches for patterns
|
||||
- Understands existing architecture
|
||||
- CANNOT make any changes
|
||||
|
||||
### Step 3: Claude Writes Plan
|
||||
|
||||
Claude creates a plan file at `.claude/plans/[name].md`:
|
||||
|
||||
```markdown
|
||||
# Plan: Refactor Authentication for OAuth
|
||||
|
||||
## Summary
|
||||
Add OAuth support while maintaining existing email/password auth.
|
||||
|
||||
## Files to Modify
|
||||
- src/auth/providers/index.ts (add OAuth provider)
|
||||
- src/auth/middleware.ts (handle OAuth tokens)
|
||||
- src/config/auth.ts (OAuth config)
|
||||
|
||||
## Files to Create
|
||||
- src/auth/providers/oauth.ts
|
||||
- src/auth/providers/google.ts
|
||||
|
||||
## Implementation Steps
|
||||
1. Create OAuth provider interface
|
||||
2. Implement Google OAuth provider
|
||||
3. Update middleware to detect token type
|
||||
4. Add OAuth routes
|
||||
5. Update config schema
|
||||
|
||||
## Risks
|
||||
- Breaking existing sessions during migration
|
||||
- Token format differences between providers
|
||||
```
|
||||
|
||||
### Step 4: You Review
|
||||
|
||||
Review the plan for:
|
||||
- Completeness (all requirements covered)
|
||||
- Correctness (right approach for your codebase)
|
||||
- Scope (not over-engineering)
|
||||
|
||||
### Step 5: Approve and Execute
|
||||
|
||||
```
|
||||
Looks good. Proceed with the plan.
|
||||
```
|
||||
|
||||
Or request changes:
|
||||
```
|
||||
Modify the plan: also add support for GitHub OAuth, not just Google.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
### Use Plan Mode
|
||||
|
||||
| Scenario | Why |
|
||||
|----------|-----|
|
||||
| Multi-file changes | See all affected files upfront |
|
||||
| Architecture changes | Validate approach before coding |
|
||||
| New features | Ensure complete implementation |
|
||||
| Unfamiliar codebase | Let Claude explore first |
|
||||
| Risky operations | Review before execution |
|
||||
|
||||
### Skip Plan Mode
|
||||
|
||||
| Scenario | Why |
|
||||
|----------|-----|
|
||||
| Single-line fixes | Obvious, low risk |
|
||||
| Typo corrections | No planning needed |
|
||||
| Simple questions | Exploration, not implementation |
|
||||
| Adding comments | Trivial change |
|
||||
|
||||
---
|
||||
|
||||
## Plan File Structure
|
||||
|
||||
Plans are stored in `.claude/plans/` with auto-generated names.
|
||||
|
||||
### Typical Plan Sections
|
||||
|
||||
```markdown
|
||||
# Plan: [Title]
|
||||
|
||||
## Summary
|
||||
[1-2 sentence overview]
|
||||
|
||||
## Context
|
||||
[Why this change is needed]
|
||||
|
||||
## Files to Modify
|
||||
[List of existing files that will change]
|
||||
|
||||
## Files to Create
|
||||
[List of new files]
|
||||
|
||||
## Files to Delete
|
||||
[List of files to remove, if any]
|
||||
|
||||
## Implementation Steps
|
||||
[Ordered list of steps]
|
||||
|
||||
## Testing Strategy
|
||||
[How to verify the changes]
|
||||
|
||||
## Risks & Mitigations
|
||||
[What could go wrong and how to handle it]
|
||||
|
||||
## Open Questions
|
||||
[Things to clarify before proceeding]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Workflows
|
||||
|
||||
### Plan + TDD
|
||||
|
||||
```
|
||||
/plan
|
||||
|
||||
I need to implement a rate limiter.
|
||||
Plan the test cases first, then the implementation.
|
||||
```
|
||||
|
||||
Claude plans both tests and implementation in proper TDD order.
|
||||
|
||||
### Plan + Spec-First
|
||||
|
||||
```
|
||||
/plan
|
||||
|
||||
Review the Payment Processing spec in CLAUDE.md.
|
||||
Create an implementation plan that satisfies all acceptance criteria.
|
||||
```
|
||||
|
||||
### Plan + TodoWrite
|
||||
|
||||
After plan approval, Claude can break down into todos:
|
||||
|
||||
```
|
||||
Approved. Create a todo list from this plan and start implementing.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
### Be Specific About Scope
|
||||
|
||||
```
|
||||
# Too vague
|
||||
/plan
|
||||
Improve the API
|
||||
|
||||
# Better
|
||||
/plan
|
||||
Add pagination to the /users endpoint with cursor-based navigation.
|
||||
Maintain backwards compatibility with existing clients.
|
||||
```
|
||||
|
||||
### Request Plan Modifications
|
||||
|
||||
```
|
||||
The plan looks good but:
|
||||
- Add error handling for network failures
|
||||
- Skip the caching optimization for now
|
||||
- Include rollback procedure
|
||||
```
|
||||
|
||||
### Use for Architecture Decisions
|
||||
|
||||
```
|
||||
/plan
|
||||
|
||||
I'm considering two approaches for state management:
|
||||
A) Redux Toolkit
|
||||
B) Zustand
|
||||
|
||||
Explore the codebase and recommend which fits better.
|
||||
```
|
||||
|
||||
### Save Plans for Documentation
|
||||
|
||||
Plans in `.claude/plans/` serve as decision documentation:
|
||||
- Why certain approaches were chosen
|
||||
- What files were expected to change
|
||||
- Implementation order rationale
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [../ultimate-guide.md](../ultimate-guide.md) — Section 2.3 Plan Mode
|
||||
- [tdd-with-claude.md](./tdd-with-claude.md) — Combine with TDD
|
||||
- [spec-first.md](./spec-first.md) — Combine with Spec-First
|
||||
- [iterative-refinement.md](./iterative-refinement.md) — Post-plan iteration
|
||||
326
guide/workflows/spec-first.md
Normal file
326
guide/workflows/spec-first.md
Normal file
|
|
@ -0,0 +1,326 @@
|
|||
# Spec-First Development with Claude
|
||||
|
||||
> **Confidence**: Tier 2 — Validated by multiple production teams and aligns with official SDD guidance.
|
||||
|
||||
Define what you want in CLAUDE.md BEFORE asking Claude to build. One well-structured iteration equals 8 unstructured ones.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [TL;DR](#tldr)
|
||||
2. [The Pattern](#the-pattern)
|
||||
3. [CLAUDE.md Spec Templates](#claudemd-spec-templates)
|
||||
4. [Step-by-Step Workflow](#step-by-step-workflow)
|
||||
5. [Integration with Tools](#integration-with-tools)
|
||||
6. [When to Use](#when-to-use)
|
||||
7. [Anti-Patterns](#anti-patterns)
|
||||
8. [See Also](#see-also)
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
```
|
||||
1. Write spec in CLAUDE.md
|
||||
2. Claude reads spec automatically
|
||||
3. Implementation follows spec exactly
|
||||
4. Verify against spec
|
||||
```
|
||||
|
||||
CLAUDE.md IS your spec file. Treat it as a contract.
|
||||
|
||||
---
|
||||
|
||||
## The Pattern
|
||||
|
||||
Spec-First Development inverts the typical AI coding flow:
|
||||
|
||||
```
|
||||
Traditional: Spec-First:
|
||||
─────────── ──────────
|
||||
Prompt → Code Spec → Prompt → Code → Verify
|
||||
│ │ │ │
|
||||
└─ Hope it's └── Contract └── Follows spec
|
||||
what you want defined └── Check against spec
|
||||
```
|
||||
|
||||
The spec becomes the source of truth that:
|
||||
- Constrains what Claude builds
|
||||
- Documents decisions for the team
|
||||
- Enables verification of completeness
|
||||
|
||||
---
|
||||
|
||||
## CLAUDE.md Spec Templates
|
||||
|
||||
### Feature Spec (Most Common)
|
||||
|
||||
```markdown
|
||||
## Feature: [Name]
|
||||
|
||||
### Description
|
||||
[2-3 sentences explaining the feature purpose]
|
||||
|
||||
### Capabilities
|
||||
- MUST: [Required functionality]
|
||||
- MUST: [Another requirement]
|
||||
- SHOULD: [Nice to have]
|
||||
- MUST NOT: [Explicit exclusions]
|
||||
|
||||
### Tech Stack
|
||||
- Required: [lib1, lib2, lib3]
|
||||
- Forbidden: [lib4, lib5]
|
||||
|
||||
### Acceptance Criteria
|
||||
- [ ] Criterion 1: [Specific, testable condition]
|
||||
- [ ] Criterion 2: [Another condition]
|
||||
- [ ] Criterion 3: [Edge case handling]
|
||||
|
||||
### API Contract (if applicable)
|
||||
- Endpoint: POST /api/[resource]
|
||||
- Request: { field1: string, field2: number }
|
||||
- Response: { id: string, created: timestamp }
|
||||
- Errors: 400 (validation), 404 (not found), 500 (server)
|
||||
```
|
||||
|
||||
### Architecture Spec
|
||||
|
||||
```markdown
|
||||
## Architecture: [Component Name]
|
||||
|
||||
### Purpose
|
||||
[Why this component exists]
|
||||
|
||||
### Boundaries
|
||||
- Owns: [What this component is responsible for]
|
||||
- Delegates to: [What other components handle]
|
||||
- Does NOT: [Explicit non-responsibilities]
|
||||
|
||||
### Dependencies
|
||||
- Upstream: [Components that call this]
|
||||
- Downstream: [Components this calls]
|
||||
|
||||
### Data Flow
|
||||
```
|
||||
Input → Validation → Processing → Output
|
||||
│ │
|
||||
└─ Errors ─────┘
|
||||
```
|
||||
|
||||
### Constraints
|
||||
- Performance: [Response time, throughput]
|
||||
- Security: [Auth requirements, data handling]
|
||||
- Scalability: [Expected load, limits]
|
||||
```
|
||||
|
||||
### API Spec
|
||||
|
||||
```markdown
|
||||
## API: [Endpoint Name]
|
||||
|
||||
### Endpoint
|
||||
`POST /api/v1/[resource]`
|
||||
|
||||
### Authentication
|
||||
Bearer token required. Scopes: `read:resource`, `write:resource`
|
||||
|
||||
### Request
|
||||
```json
|
||||
{
|
||||
"field1": "string (required, max 255 chars)",
|
||||
"field2": "number (optional, default: 0)",
|
||||
"nested": {
|
||||
"subfield": "boolean"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"created_at": "ISO 8601 timestamp",
|
||||
"data": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### Error Codes
|
||||
| Code | Meaning | Response Body |
|
||||
|------|---------|---------------|
|
||||
| 400 | Validation failed | `{ "errors": [...] }` |
|
||||
| 401 | Not authenticated | `{ "message": "..." }` |
|
||||
| 403 | Not authorized | `{ "message": "..." }` |
|
||||
| 404 | Resource not found | `{ "message": "..." }` |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step Workflow
|
||||
|
||||
### Step 1: Write the Spec
|
||||
|
||||
Before any implementation request, add spec to CLAUDE.md:
|
||||
|
||||
```markdown
|
||||
## Feature: User Authentication
|
||||
|
||||
### Capabilities
|
||||
- MUST: Email/password login
|
||||
- MUST: JWT token generation
|
||||
- MUST: Password hashing with bcrypt
|
||||
- SHOULD: Remember me functionality
|
||||
- MUST NOT: Store plain text passwords
|
||||
|
||||
### Tech Stack
|
||||
- Required: bcrypt, jsonwebtoken
|
||||
- Forbidden: passport.js (too heavy for this use case)
|
||||
|
||||
### Acceptance Criteria
|
||||
- [ ] User can login with valid credentials
|
||||
- [ ] Invalid credentials return 401
|
||||
- [ ] Token expires after 24h (or 7d with remember me)
|
||||
- [ ] Passwords hashed with cost factor 12
|
||||
```
|
||||
|
||||
### Step 2: Reference Spec in Prompt
|
||||
|
||||
```
|
||||
Implement the User Authentication feature as specified in CLAUDE.md.
|
||||
Follow the acceptance criteria exactly.
|
||||
```
|
||||
|
||||
Claude automatically reads CLAUDE.md and follows the spec.
|
||||
|
||||
### Step 3: Verify Against Spec
|
||||
|
||||
After implementation, verify:
|
||||
|
||||
```
|
||||
Review the implementation against the User Authentication spec.
|
||||
Check off each acceptance criterion that's satisfied.
|
||||
List any gaps.
|
||||
```
|
||||
|
||||
### Step 4: Update Spec if Needed
|
||||
|
||||
If requirements change during implementation:
|
||||
|
||||
```
|
||||
Update the User Authentication spec to include:
|
||||
- MUST: Rate limiting (5 attempts per minute)
|
||||
Then implement the rate limiting.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Tools
|
||||
|
||||
### With Spec Kit (Greenfield)
|
||||
|
||||
```bash
|
||||
# Install Spec Kit
|
||||
npx @anthropic/spec-kit init
|
||||
|
||||
# Use slash commands
|
||||
/speckit.constitution # Define project guardrails
|
||||
/speckit.specify # Write feature specs
|
||||
/speckit.plan # Create implementation plan
|
||||
/speckit.implement # Build from spec
|
||||
```
|
||||
|
||||
### With OpenSpec (Brownfield)
|
||||
|
||||
```bash
|
||||
# Install OpenSpec
|
||||
npm install -g @fission-ai/openspec@latest
|
||||
openspec init
|
||||
|
||||
# Use slash commands
|
||||
/openspec:proposal "Add dark mode" # Create change proposal
|
||||
/openspec:apply add-dark-mode # Implement changes
|
||||
/openspec:archive add-dark-mode # Merge to specs
|
||||
```
|
||||
|
||||
### With /plan Mode
|
||||
|
||||
```
|
||||
/plan
|
||||
|
||||
I need to implement the Payment Processing feature.
|
||||
Review the spec in CLAUDE.md and create an implementation plan.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
### Use Spec-First
|
||||
|
||||
| Scenario | Why |
|
||||
|----------|-----|
|
||||
| New features | Define before building |
|
||||
| API design | Contract must be explicit |
|
||||
| Architecture decisions | Document constraints |
|
||||
| Team collaboration | Shared understanding |
|
||||
| Complex requirements | Reduce ambiguity |
|
||||
|
||||
### Skip Spec-First
|
||||
|
||||
| Scenario | Why |
|
||||
|----------|-----|
|
||||
| Quick fixes | Overhead not worth it |
|
||||
| Exploration | Don't know what you want yet |
|
||||
| Prototyping | Requirements will change |
|
||||
| Single-line changes | Obvious intent |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### Vague Specs
|
||||
|
||||
```markdown
|
||||
# Wrong
|
||||
## Feature: User Management
|
||||
- Handle users
|
||||
|
||||
# Right
|
||||
## Feature: User Management
|
||||
### Capabilities
|
||||
- MUST: Create user with email, password, name
|
||||
- MUST: Update user profile (name, avatar)
|
||||
- MUST: Soft delete (mark as inactive, don't remove data)
|
||||
- MUST NOT: Allow duplicate emails
|
||||
```
|
||||
|
||||
### Spec After Code
|
||||
|
||||
```
|
||||
# Wrong workflow
|
||||
1. Ask Claude to implement feature
|
||||
2. Write spec documenting what was built
|
||||
|
||||
# Right workflow
|
||||
1. Write spec defining what should be built
|
||||
2. Ask Claude to implement from spec
|
||||
```
|
||||
|
||||
### Ignoring Forbidden
|
||||
|
||||
```markdown
|
||||
# Don't forget exclusions
|
||||
### Tech Stack
|
||||
- Required: React, TypeScript
|
||||
- Forbidden: jQuery, vanilla JS, class components
|
||||
↑ These constraints prevent drift
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [../methodologies.md](../methodologies.md) — SDD and other methodologies
|
||||
- [Spec Kit Documentation](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
|
||||
- [OpenSpec Documentation](https://github.com/Fission-AI/OpenSpec)
|
||||
- [tdd-with-claude.md](./tdd-with-claude.md) — Combine with TDD
|
||||
304
guide/workflows/tdd-with-claude.md
Normal file
304
guide/workflows/tdd-with-claude.md
Normal file
|
|
@ -0,0 +1,304 @@
|
|||
# TDD with Claude Code
|
||||
|
||||
> **Confidence**: Tier 1 — Based on official Anthropic best practices and extensive community validation.
|
||||
|
||||
Test-Driven Development with Claude requires explicit prompting. Claude naturally writes implementation first, then tests. TDD requires the inverse.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [TL;DR](#tldr)
|
||||
2. [The Problem](#the-problem)
|
||||
3. [Setup](#setup)
|
||||
4. [The Red-Green-Refactor Cycle](#the-red-green-refactor-cycle)
|
||||
5. [Integration with Claude Code Features](#integration-with-claude-code-features)
|
||||
6. [Anti-Patterns](#anti-patterns)
|
||||
7. [Advanced Patterns](#advanced-patterns)
|
||||
8. [See Also](#see-also)
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
```
|
||||
Red → Green → Refactor
|
||||
|
||||
But you MUST prompt Claude explicitly:
|
||||
"Write a FAILING test for [feature]. Do NOT write implementation yet."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
Without explicit instruction, Claude will:
|
||||
1. Write implementation code
|
||||
2. Then write tests that pass against that implementation
|
||||
|
||||
This defeats TDD's purpose: tests should drive design, not validate existing code.
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
### CLAUDE.md Configuration
|
||||
|
||||
Add to your project's CLAUDE.md:
|
||||
|
||||
```markdown
|
||||
## Testing Conventions
|
||||
|
||||
### TDD Workflow
|
||||
- Always write failing tests BEFORE implementation
|
||||
- Use AAA pattern: Arrange-Act-Assert
|
||||
- One assertion per test when possible
|
||||
- Test names describe behavior: "should_return_empty_when_no_items"
|
||||
|
||||
### Test-First Rules
|
||||
- When I ask for a feature, write tests first
|
||||
- Tests should FAIL initially (no implementation exists)
|
||||
- Only after tests are written, implement minimal code to pass
|
||||
```
|
||||
|
||||
### Hook for Auto-Run Tests (Optional)
|
||||
|
||||
Create `.claude/hooks/test-on-save.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Auto-run tests when test files change
|
||||
if [[ "$1" == *test* ]] || [[ "$1" == *spec* ]]; then
|
||||
npm test --watchAll=false 2>&1 | head -20
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Red-Green-Refactor Cycle
|
||||
|
||||
### Phase 1: Red (Write Failing Test)
|
||||
|
||||
**Prompt**:
|
||||
```
|
||||
Write a failing test for [feature description].
|
||||
Do NOT write the implementation yet.
|
||||
The test should fail because the function/method doesn't exist.
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Write a failing test for a function that calculates the total price
|
||||
of items in a cart, applying a 10% discount if total exceeds $100.
|
||||
Do NOT implement the function yet.
|
||||
```
|
||||
|
||||
**Expected Claude behavior**:
|
||||
- Creates test file with test cases
|
||||
- Tests reference function that doesn't exist
|
||||
- Running tests would fail with "function not defined" or similar
|
||||
|
||||
**Verification**:
|
||||
```bash
|
||||
npm test # Should fail with "calculateCartTotal is not defined"
|
||||
```
|
||||
|
||||
### Phase 2: Green (Minimal Implementation)
|
||||
|
||||
**Prompt**:
|
||||
```
|
||||
Now implement the minimum code to make these tests pass.
|
||||
Only write enough code to pass the current tests, nothing more.
|
||||
```
|
||||
|
||||
**Expected Claude behavior**:
|
||||
- Creates implementation file
|
||||
- Writes minimal code to satisfy tests
|
||||
- Avoids over-engineering
|
||||
|
||||
**Verification**:
|
||||
```bash
|
||||
npm test # Should pass
|
||||
```
|
||||
|
||||
### Phase 3: Refactor (Clean Up)
|
||||
|
||||
**Prompt**:
|
||||
```
|
||||
Refactor the implementation to improve code quality.
|
||||
Tests must stay green after refactoring.
|
||||
Focus on: [readability / performance / removing duplication]
|
||||
```
|
||||
|
||||
**Expected Claude behavior**:
|
||||
- Improves code without changing behavior
|
||||
- Runs tests to verify they still pass
|
||||
- Documents any significant changes
|
||||
|
||||
---
|
||||
|
||||
## Integration with Claude Code Features
|
||||
|
||||
### With TodoWrite
|
||||
|
||||
Track TDD phases in your task list:
|
||||
|
||||
```
|
||||
User: "Implement user authentication with TDD"
|
||||
|
||||
Claude creates todos:
|
||||
- [ ] RED: Write failing tests for login
|
||||
- [ ] GREEN: Implement login to pass tests
|
||||
- [ ] REFACTOR: Clean up login implementation
|
||||
- [ ] RED: Write failing tests for logout
|
||||
- [ ] GREEN: Implement logout
|
||||
- [ ] REFACTOR: Clean up
|
||||
```
|
||||
|
||||
### With /plan Mode
|
||||
|
||||
Use planning for test strategy:
|
||||
|
||||
```
|
||||
/plan
|
||||
|
||||
I need to implement a shopping cart with TDD.
|
||||
Plan the test cases before we start writing any code.
|
||||
```
|
||||
|
||||
Claude will explore codebase, then propose test plan before any implementation.
|
||||
|
||||
### With Hooks
|
||||
|
||||
Auto-run tests on file changes:
|
||||
|
||||
```yaml
|
||||
# .claude/hooks.yaml
|
||||
post_edit:
|
||||
- pattern: "**/*.test.ts"
|
||||
command: "npm test -- --testPathPattern=$FILE"
|
||||
- pattern: "**/*.ts"
|
||||
command: "npm test --watchAll=false"
|
||||
```
|
||||
|
||||
### With Sub-Agents
|
||||
|
||||
Delegate test writing to specialized agent:
|
||||
|
||||
```
|
||||
Use the test-writer agent to create comprehensive tests for
|
||||
the UserService class, covering all edge cases.
|
||||
Then I'll implement to pass those tests.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### What NOT to do
|
||||
|
||||
| Anti-Pattern | Why It's Wrong | Correct Approach |
|
||||
|--------------|----------------|------------------|
|
||||
| "Write tests for this feature" | Claude implements first | "Write FAILING tests that don't exist yet" |
|
||||
| "Add tests and implementation" | Loses test-first benefit | Separate into two prompts |
|
||||
| "Make sure tests pass" | Encourages implementation-first | "Write tests, then implement minimally" |
|
||||
| Skipping refactor phase | Accumulates technical debt | Always refactor after green |
|
||||
| Multiple features at once | Loses focus | One feature per TDD cycle |
|
||||
|
||||
### Common Mistakes
|
||||
|
||||
**Mistake**: Asking Claude to "test" existing code.
|
||||
```
|
||||
# Wrong
|
||||
"Write tests for the existing calculateTotal function"
|
||||
|
||||
# Right
|
||||
"Write tests for calculateTotal behavior, assuming function doesn't exist.
|
||||
Then we'll verify the existing implementation passes."
|
||||
```
|
||||
|
||||
**Mistake**: Combining red and green phases.
|
||||
```
|
||||
# Wrong
|
||||
"Implement calculateTotal with tests"
|
||||
|
||||
# Right
|
||||
"Write failing tests for calculateTotal. Stop there."
|
||||
[After tests written]
|
||||
"Now implement to pass those tests."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Property-Based Testing
|
||||
|
||||
```
|
||||
Write property-based tests for the sort function.
|
||||
Properties to test:
|
||||
- Output length equals input length
|
||||
- All input elements exist in output
|
||||
- Output is ordered
|
||||
Use fast-check or similar library.
|
||||
```
|
||||
|
||||
### Mutation Testing
|
||||
|
||||
```
|
||||
After tests pass, run mutation testing to find weak spots.
|
||||
Identify tests that don't catch mutations.
|
||||
```
|
||||
|
||||
### TDD with Legacy Code
|
||||
|
||||
```
|
||||
I need to refactor legacyFunction.
|
||||
First, write characterization tests that capture current behavior.
|
||||
Then we'll refactor with confidence.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example Session
|
||||
|
||||
### User Request
|
||||
```
|
||||
Implement a URL shortener service with TDD.
|
||||
```
|
||||
|
||||
### Phase 1: Red
|
||||
```
|
||||
Let's use TDD. First, write failing tests for:
|
||||
1. Shortening a URL returns a short code
|
||||
2. Retrieving a short code returns original URL
|
||||
3. Invalid URLs are rejected
|
||||
4. Expired links return error
|
||||
|
||||
Do NOT implement anything yet.
|
||||
```
|
||||
|
||||
### Phase 2: Green
|
||||
```
|
||||
Tests are written and failing. Now implement the minimum
|
||||
code to make them pass. Use an in-memory store for now.
|
||||
```
|
||||
|
||||
### Phase 3: Refactor
|
||||
```
|
||||
Tests pass. Now refactor:
|
||||
- Extract URL validation to separate function
|
||||
- Add proper error types
|
||||
- Improve variable names
|
||||
|
||||
Run tests after each change to ensure they stay green.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [../methodologies.md](../methodologies.md) — Full methodology reference
|
||||
- [Tight Feedback Loops](../ultimate-guide.md) — Section 9.5
|
||||
- [examples/skills/tdd-workflow.md](../../examples/skills/tdd-workflow.md) — TDD skill template
|
||||
- [Anthropic Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
|
||||
|
|
@ -3,7 +3,7 @@
|
|||
# Source: guide/ultimate-guide.md
|
||||
# Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
|
||||
|
||||
version: "3.4.0"
|
||||
version: "3.5.0"
|
||||
updated: "2026-01"
|
||||
|
||||
# ════════════════════════════════════════════════════════════════
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue