Recap — CLAUDE.md, .cursorrules, Project Conventions

# CLAUDE.md, .cursorrules, Project Conventions Without persistent instructions, AI drifts from your conventions on every prompt. With them, AI consistently follows your standards. The compound effect is significant. ## What these files do `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), `system_prompt.md` (custom): plaintext files in your repo that AI reads at the start of every session. You write project context, conventions, framework choices, what to avoid. AI applies them automatically. ## A minimal CLAUDE.md ```markdown # Project conventions ## Stack - Python 3.12, FastAPI, SQLAlchemy 2.0 (Mapped style), Pydantic v2. - Postgres in production; SQLite in tests. - Pytest for tests; ruff + pyright for lint/type check. ## Patterns - Use src/ layout. Source in `src/my_app/`. - Dependency injection via Depends(). - Pydantic models in schemas.py; SQLAlchemy models in models.py; separate. - Repository pattern for DB access (services call repositories). - Async endpoints when external I/O involved. ## Conventions - Function names: snake_case verb_phrase (fetch_user, validate_email). - Class names: PascalCase nouns. - Constants: UPPER_SNAKE_CASE. - No bare `except:`. Always `except SpecificException`. - Log via `logger.info("event_name", extra={...})`, not f-strings. ## What to avoid - Don't suggest microservices for this monolith. - Don't use Pydantic v1 syntax (`class Config:` is wrong; use `model_config = ConfigDict(...)`). - Don't use sync libraries (requests, psycopg2) inside async endpoints. - Don't add unnecessary classes; prefer functions. ## Testing - Use pytest fixtures; conftest.py for shared. - Mock external services; real DB in fixtures via transactional rollback. - Coverage > 80% on business logic. ``` This file isn't sacred — refine over time as you notice AI making the same mistakes. ## Layered context For monorepos or sub-areas: ``` project/ ├── CLAUDE.md # global conventions ├── backend/ │ └── CLAUDE.md # backend-specific └── frontend/ └── CLAUDE.md # frontend-specific ``` AI uses the closest one. ## What to include ### Stack and versions "We use FastAPI 0.110, Python 3.12, SQLAlchemy 2.0." Prevents AI from generating old-version code. ### Patterns to follow "Use the repository pattern: services → repos → DB." Prevents AI from putting DB queries in routes. ### What to AVOID "Don't suggest async SQLAlchemy; we're staying sync." Saves you rejecting suggestions. ### Naming conventions "functions: verb_phrase; classes: nouns; tests: test_ _ ." Consistent code without per-prompt reminders. ### Error handling style "Custom exceptions inherit from AppError. Don't raise generic Exception." Consistent error model. ### Logging style "Use structlog; log events with `logger.info('event_name', extra={...})`." Avoid f-string logging. ### What we DON'T do "No print(). No requirements.txt; use pyproject.toml. No setup.py." Forbidden patterns. ## What NOT to include - Things obvious from the code (AI sees the codebase). - Sensitive information (this file is read by AI providers). - Long lists nobody reads. Keep it focused and short. AI ignores walls of text. ## Update over time When you notice AI making the same mistake repeatedly: add to CLAUDE.md. Patterns: - AI keeps using Pydantic v1 syntax → add a note. - AI keeps suggesting microservices → add a "don't suggest" line. - AI uses wrong test naming → add the convention. The file grows organically. ## Example: AI keeps making a mistake ```markdown ## Database sessions ALWAYS use `Depends(get_db)` for DB sessions. NEVER create SessionLocal() directly in functions. The fixture handles cleanup; manual creation leaks sessions. ``` Three lines; AI stops making the mistake. ## Cursor's `.cursorrules` Same idea, Cursor-specific filename: ``` .cursorrules ``` Cursor reads this on session start. ## System prompts (other tools) For tools without a standardized file: - Continue: settings.json has `systemMessage`. - Aider: `--system` flag or aider config. - OpenAI API: include in system message. All do the same thing differently. ## Inheritance and overrides You can layer: 1. Global (CLAUDE.md at root): broad rules. 2. Per-directory: subset-specific. 3. Per-prompt: override for one task ("for this task, ignore the no-classes rule"). AI reads global → specific → prompt. Last wins. ## What about secrets / sensitive info Don't put in CLAUDE.md: - API keys, passwords. - Database connection strings with credentials. - Customer data. - Confidential business logic. These get sent to AI providers as context. For commercial tools: usually fine per their privacy policies, but check. ## Examples worth pointing to Best CLAUDE.md / .cursorrules examples: - Reference specific files: "Follow patterns in src/auth/router.py." - Reference docs: "See docs/architecture.md for our service patterns." AI navigates and applies. ## Measure impact After adding rules: - AI's first-attem