Claude Code
Spec-driven AI development with betterspec and Claude Code.
Claude Code
betterspec integrates natively with Claude Code through betterspec init. No separate plugin or package is needed — the init command scaffolds all the necessary files directly into your project.
Setup
betterspec init
# Select your AI tool: Claude CodeThis creates everything Claude Code needs to run a spec-driven workflow.
What betterspec init Creates
Subagents in .claude/agents/
Four specialized agent files are created:
| Agent | File | Role |
|---|---|---|
| Planner | .claude/agents/planner.md | Reads the proposal. Writes requirements, scenarios, design, and tasks. Runs betterspec verify to confirm completeness. |
| Builder | .claude/agents/builder.md | Reads the specs. Implements tasks one by one, checking them off as it goes. |
| Validator | .claude/agents/validator.md | Reviews the implementation against requirements and scenarios. Runs tests, checks edge cases, reports issues. |
| Archivist | .claude/agents/archivist.md | Archives the completed change, extracts knowledge, and updates capabilities. |
Use these agents by switching roles in Claude Code: /agent planner, /agent builder, etc.
Hooks in .claude/hooks/
betterspec installs hook scripts and registers them in .claude/settings.json:
- Context injection — Before each prompt, the hook injects the active change's specs, relevant knowledge, and capabilities into the conversation context. Agents always have full project awareness.
- Unspecced edit warning — If an agent tries to edit a file not covered by any active spec, the hook warns and asks for confirmation. This prevents unplanned scope creep.
CLAUDE.md Context
betterspec appends a section to your project's CLAUDE.md file that tells Claude Code:
- Where specs are located
- How the betterspec workflow operates (propose → plan → build → validate → archive)
- That the builder should never validate its own work
- Where to find knowledge and capabilities
Skills via agentskills.io
Skills are installed through agentskills.io and give Claude Code reusable workflows for common spec-driven tasks like writing requirements from a proposal or extracting knowledge from a completed change.
Workflow
A typical workflow with Claude Code and betterspec:
- Propose a change:
betterspec propose "Add rate limiting" - Switch to the Planner agent to flesh out specs
- Switch to the Builder agent to implement tasks
- Switch to the Validator agent to review the work
- If issues are found, the Builder fixes them
- The Archivist archives the change and extracts knowledge
The Golden Rule
The builder never validates its own work.
The Builder and Validator are separate agents with separate system prompts. This separation catches mistakes that self-review misses — the same reason code review exists in human teams.