CLAUDE.md

Template for a new project with spec-driven development. Replace the <...> placeholders. Canon: /spec/standards/spec_driven_standard.md.

Project

<PROJECT_NAME> — <one sentence: what the product is, for whom>.

Stack: <backend> · <frontend> · <DB> · <extra stores: vector/object/cache>.

Mission / feature filter: <the primary outcome by which features are cut>.

Working principle (read first)

This project is spec-driven. The source of truth is the /spec directory, not the code.

1. Spec is authoritative, code is derivative. Spec–code mismatch → we fix the spec first, then the code.
2. No code without an approved spec. Implementation only after the spec is in approved status with a DoD.
3. Session resumes from disk. State lives in files (/spec, CHANGELOG.md, tasks), not in context.

The full canon is /spec/standards/spec_driven_standard.md. Below is the operational digest.

Output density (loop-aware)

Write for your next self, not a reader. Max meaning per line: facts, decisions, state — no preambles, restatements, praise, hedging. Skimmable prose is context the loop pays for twice (to write, to re-read). Dense over polite.

Minimal code (YAGNI)

Least correct code, most direct path. Before writing: does it exist (reuse)? is it needed at all? No abstractions or "for-later" hooks without a requirement. Three plain lines beat a premature abstraction; one clear call beats three duplicated blocks. Smallest correct diff wins.

Session start

1. Read the last 3–5 entries of CHANGELOG.md.
2. Check active tasks (in_progress).
3. Load the spec of the task you're working on (/spec/features/<slug>/spec.yaml).
4. Unfinished task → continue it, don't start a new one.

Before any action

• Classify the request: question or command. A question ≠ a command to execute.
• Code — only on an explicit trigger and an approved spec.
• Architectural decision (3+ components / data model) → the six filters + pre-mortem (see canon §4.5, §6).
• Feature triage: KILL / KEEP / FREEZE before design.

TDD (mandatory)

🔴 failing test against an acceptance criterion from the spec → 🟢 minimal code → 🔵 refactor on green.

Definition of Done

• Tests written BEFORE the code, all green, coverage ≥ <80%>
• Lint / format / typecheck green
• openapi.yaml updated, if the API is touched
• Migration applies; secondary-store reindexing described, if data is touched
• Acceptance of all spec flows met
• CHANGELOG.md updated; ADR recorded on an architectural decision

Architecture rules (canon §4)

• Layers: HTTP → Application → Domain → Infrastructure. Dependencies inward only.
• The domain knows nothing of the DB and HTTP. The transport layer is thin.
• OpenAPI is the source of truth for the API. Version /api/v1 from day one.
• The source of truth is the relational DB. Vector/cache/search are rebuildable projections.
• Files go in object storage; the DB holds metadata + key + checksum.
• Tenant isolation by workspace_id on every data query.
• Permission checks in the application layer per /spec/domain/roles.yaml, not in the controller/UI.
• Secrets only in env / a secret manager. Never in the repo/logs/specs.

Migrations (canon §5)

• Code-first, applied on deploy. A manual migrate on prod is forbidden.
• downgrade on prod is forbidden — recovery is a restore from backup.
• Removing schema is expand/contract across two releases. Don't drop what the code still reads.

Defaults that are forbidden

• Interpreting a question as a command — forbidden.
• Refactoring without a request — forbidden.
• Changing an interface without auditing all callers — forbidden.
• Deletion without a regression check — forbidden.
• Push / deploy / irreversible external actions — only on confirmation.

Finishing a task

Prepend to CHANGELOG.md:

## YYYY-MM-DD HH:MM
**Task:** short description
**Changes:**
- `path` — what changed
**Result:** completed | partial | blocked
---

Report the result → propose the next step. Don't chain the next task without confirmation. Critical things (failing tests, a broken deploy, a blocker) — raise immediately.

Delegating to sub-agents

Sub-agent prompt: 5 sections — identity, specific task (input→output→where to write), stop conditions (don't touch canon/changelog, no git/deploy, don't step outside scope), output format, validation criteria.

Sources and facts

A claim about system state = a source citation (file:line, SHA, command output, test). Without a citation — mark it as a hypothesis: "presumably X (not verified)."