Claude.md Template (project Context For Coding Agents)

# 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.