title: "Intermediate CLAUDE.md Template" tested_with: claude-code: "1.0.x" last_updated: 2026-03-21 status: proven difficulty: intermediate prerequisites: [02-project-memory]

Intermediate CLAUDE.md Template

What This Config Does

A more detailed CLAUDE.md for teams or complex projects. Includes architecture context, testing standards, and common pitfalls. Use this after you've outgrown the starter template.

The Config

# [Project Name]

[2-3 sentence description of what this project does and who it serves.]

## Architecture

- `src/api/` — REST API endpoints (Express)
- `src/services/` — Business logic (no framework dependencies)
- `src/models/` — Database models (Prisma)
- `src/utils/` — Shared utilities
- `tests/` — Mirrors src/ structure

## Tech Stack

- Runtime: Node.js 20 with TypeScript 5.x
- Framework: Express 4.x
- Database: PostgreSQL 16 with Prisma ORM
- Testing: Vitest + Supertest for API tests
- CI: GitHub Actions

## Conventions

- Use `async/await`, never raw Promises or callbacks
- All functions must have TypeScript return types
- Business logic goes in `src/services/`, not in route handlers
- Route handlers only do: parse request → call service → format response
- Use Zod for runtime input validation on all API endpoints
- Error responses follow RFC 7807 (Problem Details)

## Testing Standards

- Every new function needs a unit test
- Every new API endpoint needs an integration test
- Run `npm test` before suggesting changes are complete
- Test file naming: `foo.test.ts` next to `foo.ts`

## Common Commands

- Dev: `npm run dev` (starts on port 3000)
- Test: `npm test`
- Test watch: `npm run test:watch`
- Build: `npm run build`
- Lint: `npm run lint`
- DB migrate: `npx prisma migrate dev`

## Do NOT

- Do not use `any` type — use `unknown` and narrow
- Do not put business logic in route handlers
- Do not use string concatenation for SQL — always use Prisma
- Do not skip writing tests for new code

# Adapt this by:
# - Replace all specifics with your project's details
# - The "Do NOT" section is high-value — add rules for mistakes that cost you time
# - Keep under 80 lines — if it's longer, consider directory-level CLAUDE.md files

Where to Put It

Project root as CLAUDE.md. For large monorepos, also create CLAUDE.md files in subdirectories for directory-specific instructions.

How to Verify It Works

Ask the agent to implement a new API endpoint. It should:

  • Place the route in src/api/
  • Put business logic in src/services/
  • Add Zod validation
  • Create both unit and integration tests
  • Use async/await (not callbacks)

If it doesn't follow these conventions, your CLAUDE.md needs adjustment.

Notes

  • This is the "sweet spot" level for most projects. See Module 02 for when to go beyond this.
  • Review and update quarterly. Stale CLAUDE.md files teach the agent outdated patterns.