CLAUDE.md — Project Behavioral Contract Template

Instructions: Replace all [BRACKETED] items with project-specific values. This file is read by Claude Code at the start of every session. Keep it lean — only high-signal, project-specific information. Version: 1.0

[PROJECT_NAME]

Project Identity

Project: [One sentence describing what this project does] Tech Stack: [Primary languages, frameworks, databases] Repository Type: [monorepo / polyrepo / library / application / service] Team Size: [number] engineers Stage: [prototype / MVP / production / enterprise]

Architecture Overview

[Simple ASCII or text description of the main components]
Example:
Frontend (Next.js) → API Gateway → Microservices → PostgreSQL + Redis
                                  ↓
                            Vector DB (Pinecone) ← RAG Pipeline

Standards This Project Follows

Language: [e.g., TypeScript strict mode, no any]
Style: [e.g., ESLint + Prettier, Google Java Style Guide]
Testing: [e.g., Jest for unit, Playwright for e2e, 80% coverage minimum]
Commits: [e.g., Conventional Commits — feat/fix/docs/chore]
Branches: [e.g., main → staging → feature/XXX]

Critical Constraints

These override all other guidance. They are non-negotiable.

[CONSTRAINT_1 — e.g., "Never expose internal error messages to API responses"]
[CONSTRAINT_2 — e.g., "All database queries must use parameterized statements"]
[CONSTRAINT_3 — e.g., "No synchronous I/O in the request path"]
[CONSTRAINT_4 — e.g., "All new components require a Storybook story"]

Behavioral Rules

When working in this repository:

Before coding: Always create an implementation plan and wait for explicit approval
When adding dependencies: Always ask first. Justify with: performance need, missing capability, or security requirement
When modifying existing code: Change only what is required by the task. Do not refactor unrequested
When creating files: Follow the existing folder structure. Do not invent new directories
When encountering ambiguity: Ask one clarifying question, wait for answer, then proceed

Domain Knowledge

[Key domain concepts that aren't obvious from code]

Example:

"In this system, 'sessions' and 'conversations' are different — sessions are auth sessions, conversations are LLM interaction threads"
"The 'tenant' concept is per organization, not per user"
"Prices are always stored in cents, never dollars"

What's In Scope

[Area 1]
[Area 2]
[Area 3]

What's NOT In Scope (Do Not Touch Without Explicit Instruction)

[Area to avoid — e.g., "The legacy auth module — it's being replaced next quarter"]
[Area to avoid — e.g., "The payments integration — it requires Stripe certification"]
[Area to avoid]

Testing Requirements

Every code change requires:

Unit test for new logic
Integration test if touching API boundaries
Update to relevant documentation
No reduction in coverage percentage

Documentation Requirements

All public functions must have JSDoc / docstring
All API endpoints must update the OpenAPI spec
All architectural decisions must have an ADR in /architecture/

Security Reminders

Never log sensitive data (tokens, passwords, PII, payment info)
Never hardcode credentials — use environment variables
Always validate and sanitize user input before processing
Report security concerns immediately, even if outside current task scope

Quick Reference

Task	Command
Run tests	`[TEST_COMMAND]`
Start dev server	`[DEV_COMMAND]`
Lint	`[LINT_COMMAND]`
Build	`[BUILD_COMMAND]`
Type check	`[TYPECHECK_COMMAND]`