How to Master the CLAUDE.md File: The Context Layer That Makes Spec-Driven Development Work 

Part 2 of our series on intent-driven development. If you haven't read Part 1 — Code is No Longer the Source of Truth. Your Spec Is. — start there. 

In Part 1, we explored how spec-driven development with tools like Kiro shifts the source of truth from code to intent. The spec — requirements, design, and tasks — becomes the durable artifact that the AI executes against. 

But there's a layer that sits underneath the spec. One that doesn't appear in the task list, doesn't get generated by the tool, and doesn't get checked into the client repository. It's the layer that determines whether the AI executing your spec actually understands the project — the decisions already made, the constraints that must hold, the standards your team has agreed on. 

That layer is the CLAUDE.md file. And getting it right is what separates a spec-driven workflow that runs cleanly from one that requires constant correction. 

What the CLAUDE.md File Is 

When you work with Claude Code inside a spec-driven workflow, the AI doesn't carry memory between sessions. It doesn't know what was decided last week, what library the team approved last month, or what the client specifically asked you to avoid last sprint. 

The CLAUDE.md file is how you fix that. It's a markdown document that lives in your project's Claude folder and loads as context at the start of every session. Think of it as the standing brief — the document that answers the question "what does this AI need to know before it touches anything?" 

This is distinct from the spec files themselves. The spec captures what a specific feature needs to do. The CLAUDE.md file captures what the project is: the stack, the structure, the standards, the constraints, and the data flows that every feature shares. 

What to Put in It 

Getting the CLAUDE.md file right means thinking like the most senior engineer on the project — the one who holds the entire system in their head and doesn't let any decision happen by accident. 

1. Project Overview and Goals 

Start with a bounded description of what you're building and what success looks like. Not aspirational language — specific scope. What this project is, what problem it solves, and what the initial delivery covers. This is the anchor the AI uses when it encounters an ambiguous requirement. 

2. Tech Stack and Approved Libraries 

Every library, framework, and tool the team has agreed to use — listed explicitly. If it isn't in this section, the AI doesn't reach for it. This is not a preference list. It's a boundary. If you're building with React, Tailwind, and Auth0, say exactly that. If you've chosen a specific state management approach or a specific API client, specify it here. 

This section is also where you document what you've moved away from. On one project, the initial spec referenced Keycloak for authentication. When the requirement changed to Auth0, the CLAUDE.md file was updated — Keycloak removed, Auth0 added — before any implementation ran. One file update, clean propagation, no ambiguity in subsequent sessions. 

3. Folder Structure and Naming Conventions 

Document the exact folder structure the team has agreed on. Not a rough outline — the actual structure, with naming conventions specified. The AI will fill gaps if you leave them. Filling gaps means making decisions you didn't make, in ways you didn't intend. 

If your team has a convention for where feature modules live, where shared utilities go, where constants are stored — document it here. Every session starts from the same structural understanding. 

4. API Data Flow 

How does your application get its data? From which endpoints? Through which client? What happens when data isn't available — are there fallback constants, or does the UI handle empty states? Is location passed as a parameter or resolved from a service? 

These decisions shape how every feature gets built. If they're not documented, the AI will make reasonable assumptions. Reasonable assumptions from an AI that doesn't know your system are not the same as the right decisions for your project. 

5. MCP Configuration 

If you're using Model Context Protocol servers — for database access, CLI integration, external APIs — document which ones are in use and what they connect to. This is the equivalent of telling a new developer which tools are available and which ones are already configured. Without it, the AI is working with one hand tied behind its back. 

6. What Not to Do 

This section is not optional. List explicit restrictions: patterns the team has chosen not to use, dependencies that must not be introduced, architectural decisions that are settled and should not be relitigated. The AI is capable and well-intentioned. Without constraints, it will introduce solutions that are technically correct but inconsistent with the project you're building. 

If certain UI components are off-limits, say so. If there's a pattern for error handling that must be followed consistently, document it. If the team has decided not to use a particular abstraction — even a popular one — write it down. 

How to Write It Well 

The CLAUDE.md file isn't written once and filed away. It's a living document that reflects the current state of the project's decisions. 

Write it before you write any specs. The file needs to exist before the first proposal is raised. It's the context layer every spec runs on top of. A spec generated without it will make assumptions. A spec generated with it will reflect your project. 

Be specific, not general. "Use modern React patterns" is not useful. "Use React 18 with functional components, hooks only, no class components" is. Specificity is what makes the file actionable for the AI and legible for your team. 

Update it before you run changes. When a requirement shifts — a library changes, a data flow is amended, a constraint is added — update the CLAUDE.md file first. Then tell the AI the file has been updated and which section changed. This is how requirement changes propagate cleanly through the workflow, rather than requiring a full re-brief from scratch. 

Keep it internal. The CLAUDE.md file and the Claude folder stay out of the client repository via .gitignore. The client receives the output — the code, the implemented features. They don't need the brief that produced it. Your team's methodology, the way you've structured your context layer and your workflow conventions, stays proprietary. 

What It Looks Like in Practice 

On the client project, the CLAUDE.md file wasn't a quick summary of requirements. It was the result of a refinement process — the client's instructions translated into a structured, precise document that the AI could act on without ambiguity. 

The file specified the complete tech stack, the folder structure the lead architect had defined, the API data flow and fallback behaviour, and the things the AI must not do. When the project kicked off, the first proposal was scoped to foundation setup only: one screen, correct stack, no extra UI. The AI had the full project context from a detailed brief before it was asked to do anything. 

That investment in the file is what made the proposal → spec → tasks → implementation loop run cleanly. The AI wasn't guessing at the project's structure or its conventions. It was executing against a brief that the team had already agreed on. 

The Principle to Hold Onto 

Spec-driven development works because it makes intent durable. The CLAUDE.md file is what makes that intent consistent — across sessions, across team members, across requirement changes. 

The spec captures what a feature needs to do. The CLAUDE.md file captures what the project needs to be. You need both. 

In Part 3, we walk through a complete OpenSpec implementation from proposal to deployed feature — showing exactly what each stage produces, where human review happens, and what the output looks like without writing a line of code manually.