Project Instructions
In one line: Project instructions give the AI the map a human would acquire in their first month — stack, architecture, commands, conventions, constraints.
What: Project instructions live in PROJECT/CLAUDE.md and PROJECT/.claude/settings.json. They provide the technology stack, architecture, build commands, testing conventions, data flow, coverage targets, and known constraints.
Why: The AI has no prior knowledge of any specific project. Without project instructions, every session begins with it guessing at conventions and generating code with the wrong data-access pattern, the wrong test config, or the wrong directory structure. Project instructions eliminate this cold-start by handing over the architecture as a map instead of forcing rediscovery.
The value compounds: as the project grows, the instructions grow with it. A CLAUDE.md that accurately describes a large codebase saves significant time per session because the AI starts oriented rather than exploring.
What belongs here:
| Category | Example | Rationale |
|---|---|---|
| Tech stack | The Python version pinned in appendix-m, FastAPI, Pydantic v2, Next.js 16, React 19 | AI needs to know which libraries and versions to use |
| Architecture overview | 9-step data flow, case status state machine | Structural context that shapes every implementation decision |
| Build & run commands | cd backend && uvicorn app.main:app --port 8002 --reload | AI must be able to start, test, and verify the system |
| Testing rules | asyncio_mode=auto, no @pytest.mark.asyncio needed | Framework-specific conventions that prevent common errors |
| Coverage targets | 90% for workflow layer, 70% for all other layers | Quality thresholds enforced by tooling |
| Directory structure | app/api/, app/services/, app/models/, app/workflows/ | Navigation context — where to put new code and where to find existing code |
| Known constraints | CAST(:param AS jsonb) not ::jsonb for asyncpg | Hard-won knowledge that prevents recurring bugs |
| Not-yet-implemented | List of features planned but not built | Prevents AI from assuming a feature exists when it does not |
| Hook definitions | Stop hook with verification prompt | Quality gates specific to this project's risk profile |
What does NOT belong here:
- Generic coding style rules (indentation, naming conventions) — these are handled by linters and formatters configured in the project.
- Rules that apply to all projects — these belong in global CLAUDE.md.
- Ephemeral information (current sprint tasks, today's debugging context) — these belong in memory files, not in project instructions.
Evidence: A CLAUDE.md that inventories the router files, service modules, and data flow lets the AI add a new endpoint following the established split-router pattern, the right auth dependency, and the service-layer convention — without per-request specification or code exploration. Reproducible: ask for a new endpoint with and without the inventory present and compare how many conventions the AI gets right on the first try.
How: See templates/project-claude.md for a parameterized template with {{PLACEHOLDER}} syntax. The setup guide (Step 5) walks through filling in the template for a new project. For existing projects with a CLAUDE.md, the setup guide proposes a merged version that preserves existing content.