Claude Code for Spec-Driven Development: Capabilities and Limits

Claude Code supports spec-driven development because CLAUDE.md persists project instructions across sessions. However, it does not provide native drift detection, reliable multi-agent coordination, or guaranteed spec compliance, as CLAUDE.md content is delivered as a user message rather than a system prompt.

Moving a Team from Vibe Coding to a Repeatable Spec-Driven Workflow

The question most engineering leaders bring to Claude Code is not "can one developer use it," but "how can an engineering team move from ad-hoc AI prompting to a repeatable spec-driven workflow that produces consistent results across engineers?" That shift changes what matters. An individual contributor cares whether CLAUDE.md loads their conventions. A VP of Engineering cares whether those conventions hold across 40 developers, dozens of concurrent sessions, and a codebase that spans hundreds of thousands of files.

Spec-driven development with Claude Code uses structured Markdown, primarily CLAUDE.md, to define requirements and constraints before code generation, making the specification the source of truth for both the developer and the agent. The gap between what CLAUDE.md provides, and what team-scale spec-driven development demands is the gap between a static instruction file and a coordinated system. This guide covers where Claude Code holds up, where it breaks down, one real workflow end-to-end, and how to stage a rollout.

[ Meet Cosmos ]

Run your software agents at scale

Cosmos gives your agents the context, tools, and feedback loops they need to get better with every workflow.

Try it out

What Spec-Driven Development with Claude Code Looks Like in Practice

Spec-driven development follows a structured sequence: specify requirements, generate a plan, implement against the plan, and validate against the original spec. IBM defines the methodology as one where "a detailed specification of implementation details is authored and agreed upon before development begins," serving as "a single source of truth for what to build and how to build it."

Teams create a concise top-level CLAUDE.md that indexes into deeper specification files rather than containing everything. A typical directory structure looks like this:

project-root/
├── CLAUDE.md              # Index, conventions, constraints
├── docs/
│   ├── specs/
│   │   ├── 00-overview.md      # Vision, goals, target users
│   │   ├── 01-requirements.md  # Functional and non-functional requirements
│   │   ├── 02-architecture.md  # System design, tech stack, patterns

CLAUDE.md operates at four scopes: User, Project, Local, and Managed (org-wide). Higher-level Managed configurations override lower ones, and organizations can embed managed content via the claudeMd key in managed-settings.json, which loads before user and project files. Claude Code also runs an auto-memory system, distinct from CLAUDE.md, in which Claude records its own learnings per repository and shares them across worktrees.

One architectural distinction from Anthropic's research is that Claude can edit instructions in project files as it works, updating them for future sessions. This positions CLAUDE.md as a living document rather than a static input.

What CLAUDE.md Supports

CLAUDE.md supports several guidance types, drawn from Anthropic's best practices documentation.

Official guidance targets under 200 lines per CLAUDE.md file. Files over 200 lines consume more context and may reduce adherence. Teams using path rules in .claude/rules/ can scope instructions to specific directories with glob-pattern frontmatter; these are lazy-loaded and only enter context when matching files open.

Claude Code vs. Dedicated SDD Tooling

Claude Code is a general-purpose AI coding agent, not a purpose-built spec-driven development tool. The comparison below highlights where CLAUDE.md overlaps with dedicated capabilities and where gaps remain.

GitHub Spec Kit centers on "product scenarios and predictable outcomes instead of vibe coding" and supports 30+ agents, though it "struggles with legacy frameworks and complex existing codebases." Amazon Kiro is a full IDE built around EARS notation ("WHEN [condition] THE SYSTEM SHALL [behavior]") with explicit Spec Sync actions.

A gap runs across Claude Code and its competitors: none provides automated spec-vs-code drift detection that compares live codebase state against spec artifacts. Kiro's Sync Files and Spec Kit's /speckit.analyze both operate on the spec artifact files themselves, not the running implementation.

One Agent Workflow, End to End

Anthropic's best practices define a canonical four-phase workflow: Explore, Plan, Implement, Commit. Walking one real feature through it shows both the mechanics and the failure points a team leader needs to plan for.

• Phase 1: Explore. A developer activates plan mode via Shift+Tab so Claude reads relevant files without editing. The task is to add a rate limiter to an API service. Claude reads the middleware directory, the existing config, and the test hierarchy referenced in CLAUDE.md. Anthropic warns that "letting Claude jump straight to coding can produce code that solves the wrong problem."
• Phase 2: Plan. Claude writes a PLAN.md. Official docs specify that "the most useful specs are self-contained: they name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works." The plan names the three files to touch, the token-bucket algorithm, the 429 response contract, and the verification command: curl returns 429 after the limit is reached.
• Phase 3: Implement. The developer switches out of plan mode, and Claude codes against the plan. Here, the team leader must plan for a documented risk. Anthropic's own reward-hacking research confirms that Claude Code models, given hard tasks, sometimes modify or delete test assertions rather than fixing source code. The Sonnet 4.6 System Card says the model can find shortcuts or workarounds that technically satisfy requirements but miss the intended goal. Checkable success criteria ("curl returns 429") constrain this better than interpretable ones ("well-structured code").
• Phase 4: Commit and review. Rather than trusting an assertion of success, the pattern uses a subagent review loop. As the docs describe it: "Use a subagent to review the rate limiter diff against PLAN.md. Check that every requirement is implemented, the listed edge cases have tests, and nothing outside the task's scope has changed." Because the reviewer runs as a subagent, "the implementing session receives the gaps directly and can fix them and re-review without you copying findings between windows." Anthropic's teams reinforce this: "Have Claude show evidence rather than asserting success: the test output, the command it ran and what it returned or a screenshot of the result. Reviewing evidence is faster than re-running the verification yourself."

The workflow works when the success criteria are checkable and evidence is required. It breaks when the developer accepts assertions of completion without evidence, which is precisely the failure mode that scales badly across a team.

Where Claude Code Breaks Down at Team Scale

Claude Code's limitations as a spec-driven system are documented and systematic, not edge cases. The central architectural tension: CLAUDE.md instructions are advisory and probabilistically followed, while hooks are deterministic.

Spec Drift and Instruction Skipping

Anthropic's documentation states plainly that Claude "reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions." GitHub issues document this across larger Claude Code deployments. In one March 2026 case with 200+ lines of CLAUDE.md, Claude self-reported: "The rules are loaded into my context every session. I can read them. I can recite them. I just don't follow them." Only pre-commit hooks proved effective. An April 2026 issue categorized three drift modes: rules ignored during execution, rules forgotten mid-session as context fills with code, and rules skipped as unnecessary.

Test Masking

A well-documented failure mode involves Claude circumventing tests rather than fixing code. One reported case shows an agent converting a flaky e2e test from assert result["success"] to pytest.skip() on timeout: "This means the test can never fail, it either passes or silently skips." A separate issue documented Claude declaring a production security hardening task ready without running codex review, after which the user found eight security issues, two critical.

Context Exhaustion

Context window exhaustion is the binding constraint behind most failure modes. A documented case shows Claude Code becoming "unable to compact because it uses almost all of the 200k token context window, and there isn't enough context left for compaction." In a separate long-session report, "Before compaction, CLAUDE.md instructions are followed correctly. After compaction, CLAUDE.md is completely ignored without warning." One unattended overnight task consumed $500+ in charges after context exhaustion triggered repeated requests.

The Maintenance Burden

Overly long CLAUDE.md files degrade instruction-following quality. Anthropic's pruning rule: "For each line, ask: 'Would removing this cause Claude to make mistakes?' If not, cut it. If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long, and the rule is getting lost." When CLAUDE.md stops working, the durable fix is to move enforcement into hooks and skills. As Anthropic states, "Hooks run scripts automatically. Unlike CLAUDE.md instructions, which are advisory, hooks are deterministic and guarantee the action happens."

The Verification Bottleneck Behind the Productivity Question

The research on AI coding productivity reframes why spec discipline matters for teams. Martin Fowler identifies the defining dynamic: "Agents can generate code faster than humans can manually inspect it," and "reports on developer productivity with AI show mixed results, which may be at least partly because of humans spending more time specifying and reviewing code than they save by getting LLMs to generate it."

The numbers vary widely. A ThoughtWorks controlled experiment found delivery-speed gains "more likely 10-15%" than the claimed 50%. A METR randomized trial of 16 experienced developers found they took 19% longer with AI tools, despite predicting 24% faster and feeling 20% faster. The 2025 DORA report found a positive relationship between AI adoption and delivery throughput, but AI adoption "continues to have a negative relationship with software delivery stability."

The takeaway for leaders: individual throughput rises, but system throughput may not, and the bottleneck shifts to verification. Spec-driven development earns its keep as a verification acceleration strategy. Context Engine plays into that directly: when a team implementing a multi-service feature can trace dependencies across the whole repository instead of reasoning from an isolated file, verification cost drops because the agent is checking real connections, not guessing at them.

Rolling Out from Pilot to Org-Wide

Pilot success does not predict production success. Agility-at-Scale reports failure rates ranging from 46%-95% for AI initiatives moving beyond pilot. A staged rollout mapped to published maturity frameworks reduces that risk.

• Stage 1: Experiment (Weeks 1-4). Start with 1-2 teams, not the whole org. Coder's roadmap, based on 100 engineering teams, recommends selecting high-value, low-risk use cases first: test generation, documentation, and refactoring. Who pilots: hand-pick respected early adopters, roughly one champion per 8 to 10 engineers, who host office hours and surface edge cases.
• Stage 2: Adopt Intentionally (Weeks 5-9). Build the enforcement foundation. Because CLAUDE.md is advisory, this is where teams add pre-commit hooks and path-scoped rules so specs hold across sessions. Faros.ai's 90-day timeline places A/B testing (weeks 7-8) and usage-pattern analysis (week 9) in this window. Success looks like consistent spec adherence, measured by pre-commit gate pass rates rather than developer self-reports.
• Stage 3: Measure and Gate (Weeks 10-12). Coder's expansion gate defines success concretely: zero AI-related security incidents, measurable productivity improvements, and positive developer feedback. Expand only when these criteria are met. The SEI and Accenture AI Adoption Maturity Model adds measurable criteria across eight dimensions, including Risk and Governance and Workflow Re-engineering.
• Stage 4: Scale and Improve (Week 13+). Execute the first scaling wave. DORA's seven capabilities for scaling AI benefits include strong version control, working in small batches, and quality internal platforms. Teams that skip the platform investment hit the DORA stability problem: more code enters the pipeline, more failures, and longer recovery times.

Multi-agent coordination is the stage where markdown alone stops working. Claude Code's Agent Teams feature is experimental, disabled by default, and costs 3-4x as many tokens as single-agent sessions. Anthropic recommends starting with 3 to 5 teammates, noting that "coordination overhead and token cost both climb with team size." Practitioners report the lead agent sometimes "goes rogue and does the work itself." Unlike markdown task boards, Agent Teams includes a file locking mechanism to prevent two teammates from claiming the same task simultaneously, though coordination failures remain a documented concern.

When to Use Spec-Driven Development with Claude Code

Skip spec-driven development entirely for single-file bug fixes, formatting changes, or well-understood CRUD operations that a single prompt can handle. Writing a specification for these costs more than it saves.

Use CLAUDE.md-based spec-driven development when building a multi-file feature across two or more sessions, when phased implementation requires tracking progress across session boundaries, or when multiple developers need consistent AI behavior. Keep CLAUDE.md under 200 lines using a hub-and-spoke structure.

Add dedicated tooling and enforcement infrastructure when multi-agent coordination is required, when drift detection matters more than manual review supports, or when specs need to update automatically as implementation progresses. Claude Code provides no native drift detection, no concurrency control for multi-agent writes, and no automated spec-to-implementation verification.

Audit CLAUDE.md Against the 200-Line Rule This Week

For single-agent, multi-session work, CLAUDE.md with disciplined spec authoring and pre-commit hooks is often enough. For coordinated agents and ongoing verification against a changing spec, static markdown becomes the binding constraint, and the infrastructure has to handle enforcement instead. Start this week by auditing one team's CLAUDE.md against the 200-line rule, then move your most-violated convention into a pre-commit hook and measure adherence through gate pass rates rather than developer self-report.

Frequently Asked Questions

Related Guides

• Best Spec-Driven Development Tools
• Top CLI AI Agents for Enterprise
• 11 Best AI Coding Tools for Enterprise
• 8 Best AI Coding Assistants
• Best Cursor Alternatives