What Goes in a Minimal CLAUDE.md File: The 100-Line Example

Mar 27, 2026

Problem

My CLAUDE.md file was 473 lines long. I had spent hours crafting the perfect instructions, and it still wasn’t working well.

# Project Overview (50 lines of explanation)
# Coding Standards (80 lines of Python best practices)
# Git Workflow (60 lines of commit message templates)
# Testing Guidelines (90 lines of pytest instructions)
# Error Handling Patterns (70 lines of try/except examples)
# API Response Format (40 lines of interface definitions)
# Agent Orchestration (50 lines of when to use which agent)
# Security Checklist (33 lines of mandatory checks)

Every session, Claude read all 473 lines. Then I’d ask a question. By the time Claude responded, it had burned through most of its context window just processing my configuration file.

The result? Shallow responses that ignored half my instructions anyway.

What I Found

I stumbled across a Reddit thread about Boris Cherny’s CLAUDE.md. The comment that caught my attention:

“His entire CLAUDE.md config file is barely 100 lines.”

Someone else added:

“A lot of us are writing massive, step-by-step prompt files, but the best examples are surprisingly short.”

I was skeptical. How could 100 lines be enough when I needed 473?

The Experiment

I decided to test this myself. I took my bloated CLAUDE.md and asked: what does Claude actually need that it doesn’t already know?

# REMOVED: Python coding tutorial (Claude knows Python)
# REMOVED: Git commit message templates (Claude knows conventions)
# REMOVED: Step-by-step testing procedures (Claude knows pytest)
# REMOVED: Error handling examples (Claude knows patterns)
# REMOVED: API response interface (generic boilerplate)
# REMOVED: Security tutorial (Claude knows OWASP)

What remained was about 90 lines. Here’s the structure:

# Project
E-commerce API built with FastAPI and PostgreSQL.
Handles orders, payments, and inventory.

# Conventions
- Use Python 3.11+ features
- Prefer async/await for I/O
- snake_case for functions, PascalCase for classes
- Write tests for all new endpoints

# Key Files
- `app/main.py` — FastAPI app entry
- `app/models/` — SQLAlchemy models
- `app/routes/` — API endpoints
- `tests/` — Pytest tests

# Session Rules
- Before closing: update lessons.md with discoveries
- Commit message format: `<type>: <description>`
- Never push to main directly

# Known Issues
- Payment gateway has rate limiting (100 req/min)
- Inventory sync has race condition under load

That’s 27 lines. Not 100. My real file is around 90 lines because I have more context-specific entries, but the principle holds: project-specific context only.

Why Less Is More

Context window is finite. Every line in CLAUDE.md is read every session. Here’s the math:

My bloated CLAUDE.md:    473 lines * ~15 tokens = ~7,095 tokens
Minimal CLAUDE.md:        90 lines * ~15 tokens = ~1,350 tokens

Saved:                    ~5,745 tokens per session

That’s 5,745 tokens available for actual work. Claude can read more of my codebase, understand more context, and give better answers.

But there’s another reason brevity matters:

WRONG: Including tutorials the model already knows

"Why include Python best practices?"
→ Claude was trained on PEP 8, PEP 20, thousands of Python repos
→ Your 80-line "coding standards" section adds zero new information
→ It dilutes the unique project context you DO need to convey

RIGHT: Include only what Claude doesn't know

"What does Claude NOT know?"
→ Your specific project structure
→ Your naming conventions (which might differ from standard)
→ Your known issues and workarounds
→ Your team's preferences

What to Include

I narrowed my CLAUDE.md to five essential sections:

1. Project Identity — What is this codebase?

# Project
E-commerce API built with FastAPI and PostgreSQL.
Handles orders, payments, and inventory.

# Alternative for a different project
# Project
React dashboard for monitoring Kubernetes clusters.
Uses WebGL for real-time visualizations.

One to three sentences. Claude now knows the domain and tech stack.

2. Conventions — How does this team code?

# Conventions
- Use Python 3.11+ features (pattern matching, TypeAlias)
- Prefer async/await for I/O operations
- snake_case for functions, PascalCase for classes
- Write tests for all new endpoints
- No mutation in service layer (immutable patterns)

These are team-specific choices. Claude doesn’t know them unless you tell it.

3. Key Files — Where are things?

# Key Files
- `app/main.py` — FastAPI app entry point
- `app/models/` — SQLAlchemy ORM models
- `app/routes/` — API endpoint handlers
- `app/services/` — Business logic layer
- `tests/` — Pytest test suite

This helps Claude navigate your codebase faster.

4. Session Rules — Workflow-specific behaviors

# Session Rules
- Before closing: update `docs/lessons.md` with discoveries
- Commit message format: `<type>: <description>`
- Never push to main directly
- Run linter before every commit

These are triggers for specific actions Claude should take.

5. Known Issues — Landmines to avoid

# Known Issues
- Payment gateway has rate limiting (100 req/min)
- Inventory sync has race condition under load
- User search is slow for queries >3 words
- Webhook retries cause duplicate orders (use idempotency key)

This prevents Claude from suggesting code that will hit known problems.

What to Exclude

Here’s what I removed and why:

Tutorials the model already knows:

# WRONG: Python tutorial
## How to Write Python
Python is a programming language that uses indentation...
When writing functions, always use docstrings...
Here's how to write a docstring:
```python
def foo():
    """Docstring goes here."""

(200 more lines of Python tutorial)

CORRECT: Assume the model knows Python

Just specify deviations from standard:

Use Python 3.11+ features
Prefer async/await for I/O

**Step-by-step procedures for every task:**

```markdown title="REMOVE: Step-by-step procedures"
# WRONG: Step-by-step for every task
## How to Add an Endpoint
1. Create a new file in app/routes/
2. Import FastAPI router
3. Define the endpoint function
4. Add request validation
5. Call the service layer
... (30 more steps)

# CORRECT: Just the convention
## Conventions
- Endpoints live in `app/routes/`
- Use dependency injection for services
- Validate with Pydantic models

Generic style guides:

# WRONG: Copy-pasted style guide
## Code Style
Follow PEP 8 style guide:
- Use 4 spaces for indentation
- Limit lines to 79 characters
- Use blank lines to separate functions
- Import order: standard library, third-party, local
(50 more lines of PEP 8)

# CORRECT: Team-specific deviations
## Code Style
- Line limit: 100 characters (not 79)
- Use f-strings (no .format() or %)
- Prefer dataclasses over dicts

Explanations of basic concepts:

# WRONG: Explaining REST
## API Design
REST APIs use HTTP methods:
- GET: Retrieve resources
- POST: Create resources
- PUT: Update resources
- DELETE: Remove resources
(30 more lines of REST tutorial)

# CORRECT: Assume the model knows REST
Just specify your conventions:
## API Design
- Use PUT for full updates, PATCH for partial
- Return 201 for creates, 200 for updates
- Include Location header for created resources

The Real 100-Line Example

After all the trimming, here’s a realistic 100-line CLAUDE.md:

# Project
E-commerce API built with FastAPI and PostgreSQL.
Handles orders, payments, and inventory.
Serves 3 mobile apps and 2 web frontends.

# Architecture
- API Gateway (Kong) routes to microservices
- Redis for caching and session storage
- Celery for background jobs (email, PDFs)
- S3 for file storage

# Conventions
## Python
- Use Python 3.11+ features (pattern matching, Self type)
- Prefer async/await for I/O operations
- snake_case for functions, PascalCase for classes
- Use dataclasses for DTOs, Pydantic for API models

## Testing
- Write tests for all new endpoints
- Use factory_boy for test data
- Mock external services (Stripe, SendGrid)
- Minimum coverage: 80%

## Git
- Commit format: `<type>: <description>`
- Types: feat, fix, refactor, docs, test, chore
- Never push to main directly
- PR reviews required for production changes

# Key Files
- `app/main.py` — FastAPI app entry, middleware setup
- `app/models/` — SQLAlchemy ORM models
- `app/routes/` — API endpoint handlers
- `app/services/` — Business logic (no I/O in routes)
- `app/tasks/` — Celery background jobs
- `tests/` — Pytest test suite

# Environment Variables
Required:
- `DATABASE_URL` — PostgreSQL connection string
- `REDIS_URL` — Redis connection string
- `STRIPE_API_KEY` — Stripe secret key
- `SENDGRID_API_KEY` — SendGrid API key

# Known Issues
- Payment gateway rate limits at 100 req/min
- Inventory sync has race condition under load
- User search degrades after 3 words
- Webhook retries cause duplicate orders (use idempotency key)
- PDF generation times out for >50 pages

# Session Rules
- Before closing: update `docs/lessons.md` with discoveries
- Run `make lint` before committing
- Run `make test` before pushing
- If stuck >10 min: update `docs/blockers.md`

That’s 58 lines. I could add more context and still stay under 100.

Common Mistakes

Mistake 1: The “Just in Case” Syndrome

# WRONG: Everything you might need
## Python Best Practices
(use async/await for I/O, avoid global state, use type hints...)
## Git Best Practices
(commit often, write good messages, use branches...)
## Testing Best Practices
(test edge cases, use fixtures, mock external calls...)
## Security Best Practices
(validate input, sanitize output, use HTTPS...)

# RIGHT: What you actually need
Team-specific choices that differ from standard practices.

Mistake 2: Explaining “How” Instead of “What”

# WRONG: Explaining how to test
When writing tests:
1. Create a test file in tests/
2. Import pytest and the module
3. Write test functions starting with test_
4. Use assertions to check results
5. Run with pytest command

# RIGHT: Just the requirement
Minimum test coverage: 80%

Mistake 3: Not Updating as Project Evolves

# WRONG: Outdated context
# Key Files
- `app/legacy/` — Old Flask endpoints (migrating to FastAPI)

# RIGHT: Remove stale entries
# Key Files
- `app/routes/` — FastAPI endpoints
(Legacy Flask routes removed in PR #234)

Summary

I went from a 473-line CLAUDE.md to about 90 lines. The result was better Claude responses, more available context, and faster sessions.

The principle is simple: Claude already knows Python, Git, REST APIs, testing patterns, and security best practices. What it doesn’t know is your specific project — that’s what CLAUDE.md should contain.

A minimal CLAUDE.md works because it contains only what Claude doesn’t already know: your project’s specifics. Skip tutorials, skip procedures, focus on conventions and context. The model can reason — it doesn’t need a playbook.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion - Boris Cherny's CLAUDE.md

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!