Part 2 of 5 in The Claude Code Enterprise Stack series

Your team's first CLAUDE.md saved them 12 hours. Your second CLAUDE.md saved them 80 hours. Not because you added more content. Because Claude finally understood your monorepo structure, your authentication patterns, and your component naming conventions.

This is the leverage story of CLAUDE.md.

Without shared context, every Claude Code session starts from zero. Same questions. Same answers. Tokens burn. Patience frays. And Claude still gets it wrong half the time because the answers weren't explicit enough.

CLAUDE.md solves this by encoding your team's knowledge in one place. It's not a README. It's not a style guide. It's team memory.

The Context Problem: Why Your Team Needs a Shared CLAUDE.md Right Now

When you work with Claude Code without proper context, here's what happens: Session 1 takes 20 minutes to set up context. Session 2 (the next day) starts from zero again. By Session 20, you're repeating the same patterns over and over.

A proper CLAUDE.md means Session 2 loads with full context instantly. No questions. No delays.

The research backs this up. Proper repository configuration significantly reduces iterations and prevents common integration issues. That's not small—that's the difference between Claude Code feeling like a productivity multiplier and feeling like a burden.

Here's the leverage that compounds:

First CLAUDE.md: Eliminates context setup overhead. Every session loads with your team's patterns already known. For a 10-person team, that's measurable weekly time recovered.

Second version (after team adds patterns): Compounds. New developers onboard faster. Fewer misunderstandings. Standards enforcement becomes automatic.

Third version (refined, domain-specific): Matures. The file reflects your actual team practices, not theoretical ideals. It becomes genuinely useful instead of just looking useful.

Scale this across a 50-person team over a year: You're recovering hours every single week. Hours that become features. That's worth paying attention to.

But there's a secondary win that's harder to measure: consistency. When every developer is working with the same standards, every PR reflects the same patterns. Code reviews go faster. Onboarding drops from days to hours. Junior developers work faster because senior patterns are already documented.

File Structure: What Goes Where

Let's start with the directory structure. This is where a lot of teams get it wrong.

.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. What lives in settings.local.json or CLAUDE.local.md does not. Personal overrides are gitignored. 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. Every low-value line crowds out a high-value one.

Your CLAUDE.md should cover exactly these eight sections:

1. Project Overview (2–3 sentences)
What does this project do? Who uses it? What's the business context?

2. Tech Stack (5–10 lines)
List versions, key decisions, non-obvious dependencies. Why did you choose this tool over that?

3. Directory Map (5–10 lines)
How is code organized? What's in /src? What's in /api? Where do migrations live?

4. Essential Commands (5–10 lines)
What commands do developers actually run? Clone, install, build, test, lint, deploy. Only the ones you run weekly.

5. Coding Conventions (10–15 lines)
Naming rules, import patterns, error handling philosophy. Anti-patterns to avoid.

6. Git Workflow (5–10 lines)
Branch naming, PR requirements, commit message style. Deployment process.

7. Common Gotchas (5–10 lines)
Mistakes Claude (or juniors) commonly make. N+1 query patterns. Connection pooling issues. Silent job failures.

8. Links (5–10 lines)
Pointers to detailed documentation. Architecture ADRs. Runbooks. Performance monitoring dashboards.

Total: 150–200 lines. One screen. Maintainable.

Why this length? Because keeping CLAUDE.md concise is strongly recommended. Longer files look comprehensive but aren't. Developers won't maintain them. And Claude will miss 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.

A basic example:

{
  "$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"
  }
}

This says: allow npm and git commands, allow editing in /src, allow reading the project, allow web fetches, 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.

Example: .claude/rules/security.md

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

# Security Patterns

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

The applies_to field is a glob pattern—Claude automatically loads matching rules based on the file you're editing. It's 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"]

Frontend developers working in src/components/ automatically load React patterns. Backend developers get database patterns. No overhead. No context pollution.

Writing Your CLAUDE.md: By Example

Here's a realistic example. You're 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)

Notice how "we use migrations, never raw SQL" is explicit. That's the kind of 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 in your editor. Clear. Maintainable. Specific.

That's what effective CLAUDE.md looks like.

Maintaining CLAUDE.md: The Continuous Improvement Cycle

The best CLAUDE.md isn't built once—it's built weekly. Here's the pattern:

Developer works with Claude Code. Claude misunderstands something. Maybe it uses the wrong pattern. Maybe it forgets a convention.

Developer fixes it manually. They implement the right solution.

Developer adds the pattern to CLAUDE.md. One sentence. Boom. Documented.

Next session, Claude gets it right. Because the pattern is explicit now.

This is how institutional knowledge scales. Not through top-down documentation efforts. Through the lived experience of your team discovering patterns and encoding them once.

Set a team norm: If Claude has gotten it wrong twice, add it to CLAUDE.md. After a quarter, you'll have a repository of patterns that actually reflect how your team works.

Measure this. Track "iterations to success"—how many times does Claude need to try before it gets something right? With a good CLAUDE.md, you should drop from 3–4 iterations to 1–2. In March: 2.8 iterations average. In May, after CLAUDE.md refinements: 1.5 iterations. Quantifiable improvement.

Also: Assign ownership. CLAUDE.md belongs to your team, not to one person. Anyone can propose changes via PR. But someone owns the review process—quarterly "CLAUDE.md spring cleaning" to remove outdated patterns.

Rotating ownership works well. Every quarter, a different person takes the lead. Keeps the file alive.

When to Use .claude/rules/ for Scale

CLAUDE.md works until it doesn't. Here's when to split into .claude/rules/:

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 (frontend, backend, DevOps)
• Domain-specific patterns too specialized for main CLAUDE.md
• Rules that apply only to certain file paths
• You're hitting the 200-line limit and want to add more

The beauty of .claude/rules/ is context. Frontend developers working in src/components/ automatically get React patterns. They don't need to wade through backend database patterns. It's invisible, automatic, focused.

Example rule file structure:

---
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...

When the team clones the repo and starts editing in src/components/, Claude automatically loads this file. No configuration. No slash commands. Just context.

The Bridge to Post 3

At this point, your team has shared context. Static patterns are documented. Claude knows how you work.

Next: dynamic automation. Hooks that enforce standards deterministically. Skills that encode team workflows. A private plugin marketplace that distributes capabilities across your team.

CLAUDE.md covers the patterns. Hooks and skills make them automatic.

That's when you move from "Claude, remember to follow this pattern" to "Claude, this pattern is enforced—no exceptions."

Post 3 adds that layer.

The CLAUDE.md Template: Copy-Paste Starting Point

Here's a 100-line template. Copy it. Fill it in. Commit it to your repo. You're done.

# [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]

That's your starting point. Fill in the blanks. Commit it. Share it with your team. Watch them work faster.

The Real Win: Time Reclaimed

CLAUDE.md isn't flashy. It's not a new feature. It's infrastructure.

But it's the difference between Claude Code feeling like an assistant and feeling like a burden.

Without it, developers re-explain context every session. With it, they focus on problems. For a 50-person team, that's hours every week. Hours that become features. That become competitive advantage.

That's why CLAUDE.md matters.

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