SPEC WRITINGTEMPLATE
CLAUDE.md
CLAUDE.md is the file your coding agent reads at the start of every session: what the project is, how it is laid out, which commands run things, and which conventions you refuse to relitigate. Without it, every session starts with the agent guessing at all four and you correcting it. Write it on day one, keep it current, and treat "What NOT to do" as the most valuable heading in the file.
markdown
# CLAUDE.md
This file gives coding agents (Claude Code, Cursor, etc.) the context
they need to work effectively in this repo. Read this first, every
session.
## Project
[Project Name]: one-paragraph summary of what this project is.
Status: [active / in maintenance / experimental]
Owner: [name / handle]
## Stack
- Language: [Python 3.12 / Node 20 / etc.]
- Backend: [FastAPI / Devii / Express / etc.]
- Frontend: [Svelte / React / etc.]
- Database: [PostgreSQL 16 / SQLite / etc.]
- Infra: [Mac mini / Docker Compose / AWS ECS / etc.]
- Package management: [uv / pip / npm / pnpm]
## Conventions
- Code style: [Black for Python / Prettier for JS / etc.]
- Naming: [snake_case for Python files, kebab-case for routes,
PascalCase for React components, etc.]
- Imports: [absolute imports preferred / relative imports preferred]
- Tests: [pytest / vitest, location of test files]
- Commits: [conventional commits / freeform / signed required]
## Directory Structure
```
.
├── README.md
├── CLAUDE.md # this file
├── data-shape.md # data shapes, see section 5.1
├── design-tokens.md # design tokens, see section 5.4
├── roles.md # user roles, see section 5.5
├── src/
│ ├── backend/
│ ├── frontend/
│ └── shared/
├── specs/ # feature specs (one .md per feature)
├── tests/
└── scripts/
```
## What NOT to Do
- Do NOT add new dependencies without asking.
- Do NOT modify the database schema directly. Use migrations in
`scripts/migrations/`.
- Do NOT hardcode secrets. Read from environment variables. See
`.env.example` for the list.
- Do NOT touch files in `vendor/` or `_archive/`.
- Do NOT auto-format unrelated files when working on a single change.
## Out of Scope (Project-Level)
- Mobile apps (this is web-only).
- Internationalization (English-only for now).
- Multi-tenancy (single-tenant deployment).
## Useful Commands
- Dev server: `npm run dev` (frontend), `uv run uvicorn ...` (backend).
- Tests: `pytest` (backend), `npm test` (frontend).
- Migrations: `python scripts/migrate.py up`.
- Lint: `ruff check .` (Python), `npm run lint` (JS).
## Active Work
(Update as you go. Helps the agent know what's in flight.)
- In progress: [feature X]
- Blocked: [feature Y on decision about Z]
- Done this week: ...
## Notes for Agents
- When adding a new feature, start by writing or updating the spec
in `specs/` before writing code.
- When unsure, ask clarifying questions instead of guessing.
- Read `data-shape.md` before any data-touching code.
- Read `roles.md` before any permission-touching code.
- Read `design-tokens.md` before any UI-touching code.