Part 2 of 5 in The Claude Code Enterprise Stack series

Monday morning. A developer opens Claude Code, types a prompt, and waits. Claude asks which testing framework they use. The developer answers. Claude asks where the database schema lives. The developer answers again. Claude asks about the naming convention for API routes. The developer sighs.

Twenty minutes gone. Zero code written.

Tuesday morning. Same developer, different session. Claude starts from zero again. Same questions. Same answers. Same twenty minutes burned. By Friday, that developer has spent nearly two hours just re-explaining context that hasn't changed since the repo was created.

Now multiply that across ten developers. A hundred sessions a week. The math gets ugly fast.

CLAUDE.md fixes this. One file. Loaded automatically. Every session starts with full context. No questions. No delays. No re-explaining what Prisma version you use or why default exports are banned.

It's not a README. It's not a style guide. It's team memory.

The Context Problem: Why Shared Context Changes Everything

Without proper context, Claude Code is like a brilliant contractor who shows up every morning with amnesia. They can do extraordinary work — once you spend twenty minutes reminding them where the tools are, what the client wants, and which walls are load-bearing.

A proper CLAUDE.md means Session 2 loads the same way Session 200 does. Full context. Instantly.

The research backs this up. Proper repository configuration significantly reduces iterations and prevents common integration issues. That's not a minor optimization — it's the difference between Claude Code feeling like a productivity multiplier and feeling like a tax on your time.

Here's how the value 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 feedback): New developers onboard faster. Fewer misunderstandings. Standards enforcement becomes automatic instead of aspirational.

Third version (refined, battle-tested): 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 become shipped products. That become the reason you hired these people in the first place.

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

File Structure: What Goes Where

This is where a lot of teams stumble. They create one massive file, stuff everything into it, and wonder why Claude ignores 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. 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. Not just what you use — why you chose it.

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. 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. They don't wade through backend database patterns. No overhead. No context pollution. Just the right guidance at the right time.

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. Not aspirational principles — operational boundaries.

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. 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 continuously, in the moments when someone notices Claude getting it wrong.

The pattern is simple:

Developer works with Claude Code. Claude misunderstands something. Uses the wrong pattern. Forgets a convention.

Developer fixes it manually. Implements the right solution.

Developer adds one line to CLAUDE.md. Boom. Documented.

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

This is how institutional knowledge actually scales. Not through top-down documentation sprints that consume a week and produce a document nobody reads. Through the lived experience of your team discovering patterns and encoding them once, at the moment of pain.

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 reflect how your team actually works — not how someone imagined you work in a planning meeting.

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 see that number drop. In March: 2.8 iterations average. In May, after refinements: 1.5. That's not a minor improvement. That's half the friction, gone.

And 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 and add emerging ones.

Rotating ownership works well. Every quarter, a different person takes the lead. It keeps the file alive instead of letting it fossilize into another piece of ignored documentation.

When to Use .claude/rules/ for Scale

CLAUDE.md works until it doesn't. Here's 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

The beauty of .claude/rules/ is invisible context. Frontend developers working in src/components/ automatically get React patterns. They don't need to wade through backend database patterns. Backend developers get database guidelines without seeing CSS conventions. It's automatic, focused, and entirely frictionless.

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

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

The Bridge to Post 3

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

But here's an honest admission: CLAUDE.md is still just a suggestion. It's a very good suggestion — one that loads automatically and shapes every interaction. But Claude can still ignore it. Claude can still forget it. Claude can still decide that a particular instruction doesn't apply to this particular situation.

That's the gap between documentation and enforcement.

Post 3 closes that gap. Hooks make standards deterministic. They fire every time, with no exceptions and no judgment calls.

CLAUDE.md tells Claude what to do. Hooks guarantee it happens.

The CLAUDE.md Template: Copy-Paste Starting Point

Here's a 100-line template. Copy it. Fill it in. Commit it. 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 the questions stop and the code start.

The Real Win

If you're a team lead reading this and your developers are still re-explaining context every session — that's not a Claude Code problem. That's a configuration problem. And it has a one-file solution.

CLAUDE.md isn't flashy. It won't make the tech blogs. It's infrastructure — quiet, invisible, and load-bearing.

But it's the difference between Claude Code feeling like an assistant who remembers everything and one who shows up every morning with amnesia.

For a 50-person team, that difference is hours every week. Hours that become features. Features that become competitive advantage.

One file. One hundred and fifty lines. That's all it takes.

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