Part 2 of 5 in The Claude Code Enterprise Stack series

Monday morning. A developer opens Claude Code and types a prompt. Claude asks which testing framework they use, where the schema lives, what the naming convention for API routes is. The developer answers all three. Twenty minutes gone, zero code written. Tuesday, different session, same questions, same answers. By Friday that's two hours re-explaining context that hasn't changed since the repo was created. Multiply across ten developers and a hundred sessions a week, and the math gets ugly.

I used to pay this tax myself — the first ten minutes of every session spent re-teaching Claude the same five facts about a repo, onboarding a new hire every single morning. A good CLAUDE.md is the team's working memory written down once, so nobody, human or model, keeps paying it. One file, loaded automatically, every session starting with full context. No questions about which Prisma version you use or why default exports are banned.

Why Shared Context Changes Everything

A proper CLAUDE.md means Session 200 loads the same way Session 2 did. Proper repository configuration measurably reduces iterations and integration errors — the difference between Claude Code feeling like a multiplier and feeling like a tax. The secondary win is harder to measure: consistency. With the same standards loaded, every PR reflects the same patterns. Code reviews go faster. Onboarding drops from days to hours. Juniors produce senior-quality output because the patterns are already documented.

File Structure: What Goes Where

This is where teams stumble: one massive file, everything stuffed in, and Claude ignoring half of it. The architecture is deliberate:

.claude/
├── CLAUDE.md              # Team playbook (committed to git)
├── settings.json          # Team permissions & MCP config (committed)
├── settings.local.json    # Personal overrides (gitignored)
├── rules/                 # Domain-specific guidance (auto-loaded by glob)
│   ├── security.md
│   ├── backend/
│   │   └── database.md
│   └── frontend/
│       └── react-patterns.md
├── agents/                # Custom subagents for specialized tasks
│   ├── code-reviewer.md
│   └── test-generator.md
├── skills/                # Reusable workflows (with YAML frontmatter)
│   └── create-pr/
│       └── SKILL.md
└── hooks/                 # Event handlers for automation
    └── hooks.json

The key distinction: what lives in .claude/ gets committed to git. settings.local.json and CLAUDE.local.md are gitignored personal overrides. Team standards are shared.

CLAUDE.md — The Core Team Playbook (150-200 lines)

This is the file that loads automatically every session. Keep it ruthlessly focused — every line is a token consumed, and every low-value line crowds out a high-value one. Cover exactly these eight sections:

1. Project Overview (2-3 sentences) — what it does, who uses it, the business context.
2. Tech Stack (5-10 lines) — versions, key decisions, non-obvious dependencies. Not just what you use, why you chose it.
3. Directory Map (5-10 lines) — what's in /src, /api, where migrations live.
4. Essential Commands (5-10 lines) — only the ones you run weekly: install, build, test, lint, deploy.
5. Coding Conventions (10-15 lines) — naming, import patterns, error-handling philosophy, anti-patterns.
6. Git Workflow (5-10 lines) — branch naming, PR requirements, commit style, deployment.
7. Common Gotchas (5-10 lines) — mistakes Claude (or juniors) make: N+1 queries, pooling, silent job failures.
8. Links (5-10 lines) — detailed docs, ADRs, runbooks, monitoring dashboards.

Total: 150-200 lines. One screen. Keeping CLAUDE.md concise is strongly recommended — longer files look comprehensive but developers won't maintain them, and Claude misses the important stuff buried in the noise.

settings.json — Team Permissions & Integration (Committed)

This file configures permissions, MCP servers, and environment variables for your team:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "defaultMode": "acceptEdits",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Edit(/src/**)",
      "Read(.)",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm -rf)",
      "Read(.env)",
      "Read(.ssh/*)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://localhost/myapp"
  }
}

Allow npm and git, edit in /src, read the project, fetch the web — but block dangerous deletions and deny access to secrets.

rules/ Directory — Modular Domain Guidance

When CLAUDE.md gets too long, move patterns to .claude/rules/. These files use YAML frontmatter with glob patterns indicating when they apply:

---
name: "Security Guidelines"
applies_to:
  - "**/*.ts"
  - "**/*.js"
---

# Security Patterns

Always validate user input. Never interpolate SQL. Use parameterized queries...

The applies_to glob means Claude loads matching rules based on the file you're editing — contextual, not something you have to remember. For larger teams, organize rules hierarchically:

rules/
├── security.md             # applies_to: ["**/*.ts", "**/*.js"]
├── backend/
│   └── database.md         # applies_to: ["src/db/**/*.ts"]
└── frontend/
    └── react-patterns.md   # applies_to: ["src/components/**/*.tsx"]

A frontend developer in src/components/ loads React patterns automatically, never wading through backend database guidance. No context pollution.

Writing Your CLAUDE.md: By Example

A realistic example — a Node.js SaaS team building a CRM API.

Project Overview:

Production SaaS API for real estate CRM. 50K active users, $2M ARR.
PostgreSQL database, Express backend, Next.js frontend (separate repo).
Critical for deal workflows—downtime costs the business $10K/hour.

Tech Stack:

- Node.js 22 LTS (runtime)
- Express 5 (API framework)
- PostgreSQL 16 (primary database)
- Redis 7 (caching, job queues)
- Next.js 16 (frontend)
- Prisma 5.x (ORM) — we use migrations, never raw SQL in production
- Drizzle for reporting queries (read-only access)

"We use migrations, never raw SQL" is explicit — operational boundaries, not aspirational principles. That's the guidance Claude needs.

Directory Map:

/src
  /api           → Express route handlers
  /db            → Prisma schema, migrations
  /services      → Business logic (CRM sync, billing, etc.)
  /middleware    → Auth, error handling, logging
  /utils         → Shared helpers
/frontend        → Next.js app (separate repo)
/tests           → Integration tests (Vitest + supertest)

Essential Commands:

npm install                 → Install dependencies
npm run dev                 → Starts API on :3000, watcher on src/
npm run test                → Full suite, stops on first failure
npm run lint                → ESLint + Prettier check
npm run migrate             → Run pending migrations
npm run db:seed             → Populate test data
npm run deploy:staging      → Deploy to staging
npm run deploy:prod         → Deploy to production (requires approval)

Coding Conventions:

- Naming: camelCase for functions/vars, PascalCase for classes
- No default exports; always named exports for tree-shaking
- Errors: throw descriptive Error objects or use AppError(500, "message")
- Async: prefer async/await over .catch()
- Avoid: try/catch for control flow, nested ternaries >1 level
- Database: always use prepared statements (Prisma default)
- Auth: verify user.id before accessing user data; check roles before mutations

Git Workflow:

Branches: feat/feature-name, fix/issue-id, refactor/what-changed
Commits: "fix: auth middleware handles expired tokens" (conventional commits)
PRs: Must have tests passing, one approval, feature branch squashed into main
Deployment: main branch deploys to prod automatically via GitHub Actions

Common Gotchas:

- Don't modify migrated schema by hand; create a new migration
- N+1 queries: Always use Prisma relations, not separate queries in loops
- Silent job failures: Check Redis queue monitoring before assuming jobs ran
- Database connections: Verify connection pooling in production (not unlimited)
- API rate limiting: Check headers on 429s; includes retry-after

Links:

Architecture decisions: /docs/architecture/adr-001-prisma-vs-typeorm.md
Deployment runbook: /docs/runbooks/production-deployment.md
Emergency contacts: /docs/on-call/escalation.md
Performance monitoring: https://grafana.company.com/d/api-production

Total: 180 lines. One screen. Not comprehensive, not exhaustive — just enough to make Claude dangerous from the first prompt.

Maintaining CLAUDE.md: The Continuous Improvement Cycle

The best CLAUDE.md isn't built once; it's built in the moments someone notices Claude getting it wrong. Claude uses the wrong pattern, the developer fixes it manually and adds one line to CLAUDE.md, and next session Claude gets it right. That's how institutional knowledge scales — not a week-long documentation sprint nobody reads, but patterns encoded once, at the moment of pain. Set the norm: wrong twice, add it to CLAUDE.md.

Measure it. Track "iterations to success" — how many tries before Claude gets something right — and watch it fall as the file matures. Unlike most "productivity" claims, it's a number you can put on a dashboard.

And assign ownership. CLAUDE.md belongs to the team, not one person: anyone proposes changes via PR, but someone owns a quarterly spring-cleaning to drop outdated patterns and add emerging ones. Rotate the lead each quarter so the file stays alive instead of fossilizing into another piece of ignored documentation.

When to Use .claude/rules/ for Scale

CLAUDE.md works until it doesn't. The inflection point:

Keep CLAUDE.md lean if:

• Team <30 people
• Single codebase or simple monorepo
• Reasonably unified tech stack
• Patterns fit in 200 lines

Add .claude/rules/ when:

• Multiple teams with different domains (frontend, backend, DevOps)
• Domain-specific patterns too specialized for the main file
• Rules that apply only to certain file paths
• You're hitting the 200-line limit and every line already earns its place

Example rule file:

---
name: "React Component Patterns"
applies_to:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---

# Use named exports for all components
# Avoid prop drilling deeper than 2 levels
# Prefer composition over inheritance...

Clone the repo, start editing in src/components/, and Claude loads this file. No configuration, no slash commands.

The Bridge to Post 3

Your team now has shared context and documented patterns. But an honest admission: CLAUDE.md is still just a suggestion — a very good one that loads automatically and shapes every interaction, but one Claude can ignore, forget, or decide doesn't apply this time. That's the gap between documentation and enforcement, and Post 3 closes it. Hooks make standards deterministic — they fire every time, no exceptions, no judgment calls. CLAUDE.md tells Claude what to do; hooks guarantee it happens.

The CLAUDE.md Template: Copy-Paste Starting Point

A 100-line template. Copy it, fill it in, commit it.

# [Project Name]

## Overview
[1-2 sentences: what this project does, who uses it, why it matters]

## Tech Stack
- Runtime: [Node.js version / Python version]
- Framework: [Express / FastAPI]
- Database: [PostgreSQL / MongoDB]
- [Other key dependencies with versions]

## Directory Structure
/src
  /api      → Route handlers
  /db       → Database schema and migrations
  /services → Business logic
  /utils    → Shared helpers

## Essential Commands
npm/yarn/pnpm install   → Install dependencies
npm run dev             → Start development server
npm run test            → Run test suite
npm run lint            → Check code quality
npm run build           → Production build
npm run deploy          → Deploy to production

## Coding Conventions
- **Naming:** camelCase for functions, PascalCase for classes
- **Imports:** Named exports only (no defaults)
- **Errors:** Throw descriptive Error objects
- **Async:** Prefer async/await over callbacks
- **Avoid:** Try/catch for control flow, nested ternaries >1 level

## Git Workflow
- Branches: feat/name, fix/issue, refactor/what-changed
- Commits: Conventional commits (feat:, fix:, refactor:)
- PRs: One approval required, tests must pass
- Main deploys automatically to production

## Common Mistakes
- N+1 queries: Use relations, not loops
- Silent failures: Check job queues, don't assume jobs ran
- Database connections: Verify pooling in production
- Schema changes: Create migrations, never modify by hand

## Links
- Architecture decisions: /docs/architecture/
- Deployment: /docs/runbooks/deploy.md
- Monitoring: [link to observability dashboard]

Fill in the blanks, commit it, share it. Watch the questions stop and the code start.

The Real Win

If your developers are still re-explaining context every session, that's not a Claude Code problem. It's a configuration problem with a one-file solution.

CLAUDE.md is quiet, unglamorous infrastructure — the kind nobody notices until it's missing. I've worked both ways. The amnesia version is the one I'll never go back to.

Series Navigation

• Post 1: Why Configuration Matters More Than Models
• Post 2: Building Your First CLAUDE.md (you are here)
• Post 3: Hooks: Deterministic Policy Enforcement
• Post 4: Skills, Agents, and Private Marketplaces
• Post 5: Measuring ROI and Scaling Beyond Day One