Configuring Claude Code
Relevant source files
The following files were used as context for generating this wiki page:Configuring a spec-kit project for use with Anthropic's Claude Code involves a streamlined initialization process and a set of specific files that guide the AI agent's behavior. This setup enables Claude Code to understand the project context, follow architectural principles, and execute the core commands of Spec-Driven Development (/specify, /plan, /tasks).
The configuration ensures that Claude Code can generate specifications, create implementation plans, and break down work into executable tasks, all while adhering to the project's defined constitution. The primary mechanism for this is the specify CLI and a set of template files that are instantiated during project setup.
Sources: README.md, spec-driven.md
Initial Project Setup
To configure a project for Claude Code, you use the specify init command. This interactive tool sets up the necessary directory structure and template files.
Sources: src/specify_cli/init.py:530-658
Initialization Flow
When initializing a project, you must select claude as the AI assistant. The CLI then downloads the appropriate template and configures the environment. The init command performs several checks, including verifying that the claude CLI tool is installed on the local machine, unless the --ignore-agent-tools flag is used.
The diagram below illustrates the initialization process when selecting Claude Code.
This diagram shows the flow of the specify init command for a Claude Code project.
Sources: src/specify_cli/init.py:368-380, 597-613, 450-469
Key init Command Options
The init command provides several options to customize the setup for Claude Code.
| Option | Description |
|---|---|
--ai claude | Explicitly selects Claude Code as the AI assistant. |
--ignore-agent-tools | Skips the check for the installed claude CLI tool. |
--here | Initializes the project in the current directory instead of creating a new one. |
--no-git | Skips the automatic git init process. |
Sources: src/specify_cli/init.py:530-536
Project Structure for Claude Code
After initialization, the project contains files specifically for interacting with Claude Code. These files define custom commands and provide runtime context to the agent.
A typical structure for a Claude Code-configured project includes:
.
├── CLAUDE.md
├── memory/
│ ├── constitution.md
│ └── constitution_update_checklist.md
├── scripts/
│ └── update-claude-md.sh
├── specs/
└── templates/
├── CLAUDE-template.md
└── commands/
├── plan.md
├── specify.md
└── tasks.md
Note: The README.md shows a slightly different structure, but plan-template.md and update-agent-context.sh confirm the existence and management of CLAUDE.md.
Sources: README.md:144-162, templates/plan-template.md:21, scripts/update-agent-context.sh:11
Core Commands
The Spec-Driven Development workflow is orchestrated through three main commands that are made available to Claude Code. These commands are defined in markdown files within the templates/commands/ directory.
| Command | Description | Source File |
|---|---|---|
/specify | Starts a new feature by creating a specification and a feature branch. | templates/commands/specify.md |
/plan | Creates a technical implementation plan from an existing specification. | templates/commands/plan.md |
/tasks | Breaks down a plan into a list of executable tasks. | templates/commands/tasks.md |
Sources: spec-driven.md:188-220
Command Execution Sequence
When a user invokes a command like /specify within the Claude Code environment, the agent reads the corresponding markdown file from templates/commands/ to understand how to execute it. This typically involves running a shell script.
The following sequence diagram shows the execution flow for the /specify command.
This diagram shows how Claude Code uses a command definition and a script to create a new feature specification.
Sources: templates/commands/specify.md:1-12
Agent Context Management (CLAUDE.md)
The CLAUDE.md file (or CLAUDE-template.md as its base) is a critical component for configuring Claude Code. It serves as a dynamic, high-level summary of the project's technical landscape, providing the agent with essential context during development.
Sources: templates/plan-template.md:21, memory/constitution_update_checklist.md:12
Purpose and Structure
The CLAUDE.md file is generated from templates/agent-file-template.md. Its purpose is to give the AI agent a quick overview of the project without needing to parse the entire codebase.
The structure includes:
- Active Technologies: A list of languages, frameworks, and databases used.
- Project Structure: A high-level view of the source code layout.
- Commands: Key build, test, and lint commands.
- Code Style: Pointers on language-specific conventions.
- Recent Changes: A log of the last few features added.
Sources: templates/agent-file-template.md
Automatic Updates
The CLAUDE.md file is kept up-to-date automatically by the scripts/update-agent-context.sh script. This script is designed to be run as part of the /plan command's execution flow. It parses the newly created plan.md for a feature and incrementally updates CLAUDE.md.
The update process is as follows:
This diagram shows how the update-agent-context.sh script maintains the CLAUDE.md file.
This ensures that as the project evolves, Claude Code's context remains current, reflecting new technologies or structural changes. The script is careful to preserve any manual additions made to the file.
Sources: scripts/update-agent-context.sh, templates/plan-template.md:100-106