If you're using Claude Code without a CLAUDE.md file, you're starting every session from zero. The AI has no idea what your project is, what your conventions are, or what it shouldn't touch.
CLAUDE.md fixes that. It's a Markdown file you drop in your project root, and Claude Code reads it automatically at the start of every session. Think of it as a briefing document for your AI teammate.
But here's the thing — most developers who do create one write something generic like "This is a React project using TypeScript." That barely helps.
After months of daily Claude Code use across multiple projects, I've landed on 4 patterns that consistently produce better output. Each one solves a specific problem.
Pattern 1: The Minimal Spec (Personal Projects)
Problem: Claude adds unnecessary complexity to simple projects.
# finance-cli
## Overview
Personal finance CLI tool. Python + SQLite + Click.
## Stack
- Python 3.13, SQLite3, Click
- Tests: `pytest tests/`
- Format: `ruff format .`
- Type annotations required
## Rules
- Keep it simple — this is a single-user CLI
- No ORM — raw SQL is fine for this scale
- Output format: plain text tables
Why it works: By stating "single-user CLI" and "raw SQL is fine," you prevent Claude from suggesting SQLAlchemy, user authentication, or other over-engineering. The explicit "keep it simple" directive carries surprising weight.
Key insight: Tell Claude what level of complexity is appropriate. Without this, it defaults to enterprise-grade suggestions.
Pattern 2: The Monorepo Navigator
Problem: In monorepos, Claude modifies the wrong package or misses cross-package dependencies.
# myproject-monorepo
## Structure
| Package | Path | Tech | Entry |
|---------|------|------|-------|
| API | packages/api/ | FastAPI, SQLAlchemy | main.py |
| Web | packages/web/ | Next.js 15, TypeScript | src/app/ |
| Shared | packages/shared/ | TypeScript | src/index.ts |
## Build & Test
- API: `cd packages/api && pytest`
- Web: `cd packages/web && pnpm test`
- All: `pnpm -r test`
## Critical Rules
- Changes to shared/ require testing BOTH api and web
- API changes must update the OpenAPI spec
- PRs must be scoped to one package unless cross-cutting
- Web uses server components by default — client components need justification
Why it works: The table gives Claude a mental map of the entire repo. The "Critical Rules" section prevents the most common monorepo mistakes — changing shared types without testing consumers, or bundling unrelated changes.
Key insight: The table format is important. Claude Code parses tables more reliably than prose for structured information.
Pattern 3: The Team Playbook
Problem: Multiple developers get inconsistent output from Claude Code.
# TeamProject
## Architecture
Backend: Go microservices (services/)
Frontend: React SPA (web/)
Infrastructure: Terraform (infra/)
Database: PostgreSQL 16
## Coding Standards
- Minimal changes: only modify what is explicitly required
- No over-engineering: don't add abstraction for one-off operations
- Delete unused code entirely — no compatibility shims or renamed _vars
- Comments explain "why," never "what"
- Error messages must include context (what failed + what was expected)
## Security (Non-Negotiable)
- SQL: parameterized queries only. No string concatenation.
- User input: validate at system boundaries
- .env files: never read, never commit
- Secrets: use environment variables via config
## Git Workflow
- Branches: feature/xxx, fix/xxx, docs/xxx
- Commits: Conventional Commits format
- No direct push to main — PRs only
- Squash merge preferred
Why it works: The "Non-Negotiable" label on security rules signals priority. Claude treats labeled sections with urgency words differently than regular instructions.
The "Minimal changes" and "No over-engineering" rules are the most impactful lines in this entire template. Without them, Claude will refactor adjacent code, add docstrings to functions you didn't modify, and introduce abstractions for things that happen once.
Key insight: Negative instructions ("don't do X") are more effective than positive ones for controlling Claude Code behavior. Tell it what to avoid.
Pattern 4: The Behavior Fence
Problem: Claude makes changes you didn't ask for — creating README files, adding comments, pushing code.
## Prohibited Actions
- Do NOT create README.md or documentation files unless explicitly asked
- Do NOT add docstrings or comments to code you didn't modify
- Do NOT run `git push` unless explicitly instructed
- Do NOT modify .env or credentials files
- Do NOT add error handling for scenarios that can't happen
- Do NOT refactor code adjacent to your changes
## Priorities (in order)
1. Edit existing files > Create new files
2. Simple implementation > Abstracted implementation
3. Working code > Perfect code
4. Fewer files changed > Comprehensive refactor
## When Unsure
- Ask before creating new files
- Ask before modifying interfaces used by other modules
- Ask before adding dependencies
Why it works: This is the pattern that changed how I use Claude Code. Without explicit fences, the AI will:
- Create a README.md for every directory it touches
- Add type annotations to functions you didn't ask about
- "Improve" code near your changes
- Add defensive error handling for impossible edge cases
Each prohibited action came from a real incident where Claude did something I didn't want.
Key insight: The "Priorities" list with comparison operators (>) gives Claude a decision framework. When it's unsure whether to create a new file or edit an existing one, it now has a rule to follow.
Combining Patterns
In practice, I use elements from all four. A typical production CLAUDE.md looks like:
# ProjectName
## Overview
[Pattern 1: Brief description]
## Structure
[Pattern 2: Package/directory table]
## Standards
[Pattern 3: Team coding rules]
## Prohibited Actions
[Pattern 4: Behavior fences]
## Commands
- Test: `npm test`
- Build: `npm run build`
- Lint: `npm run lint`
The order matters. Overview first (sets context), structure second (navigation), standards third (how to write code), prohibitions last (guardrails).
One More Thing: The Hierarchy
CLAUDE.md can live in multiple places:
| Location | Scope | Loaded |
|---|---|---|
~/.claude/CLAUDE.md |
All projects | Always |
Project root CLAUDE.md
|
This project | When in project |
Parent directory CLAUDE.md
|
Workspace-wide | When in child dirs |
Put personal preferences (editor style, formatting rules) in ~/.claude/CLAUDE.md. Put project-specific rules in the project root. For monorepos, use the parent directory for shared rules.
Getting Started
Pick the pattern closest to your situation. Copy the template. Modify the specifics. Drop it in your project root.
You'll notice the difference on the very first prompt — Claude will reference your CLAUDE.md context and produce output that actually fits your project instead of generic boilerplate.
These patterns come from the Claude Code setup guide I wrote — it covers CLAUDE.md plus six other configuration areas (Hooks, MCP, Skills, multi-agent, permissions, and daily recipes). The full guide is on my Gumroad if you want the complete picture.
— myouga the axolotl
Building Claude Code tools and writing about what actually works. @myougaTheAxo
Related Articles
- I Asked AI to Build an Android App. It Took 47 Seconds.
- Claude Code vs Cursor vs GitHub Copilot
- Zero to Android App in 11 Minutes
- Why I Stopped Using Free Apps
All 8 Android app templates on Gumroad
Top comments (0)