Create or Improve a CLAUDE.md
FIRST: Explore the Codebase
Before doing ANYTHING else, use the Task tool with these exact parameters:
- :
- :
- : Include the WHAT/WHY/HOW questions listed below
Do NOT proceed until exploration is complete.
Overview
You are creating or improving a
file for a codebase. This file is the
only content guaranteed to appear in every Claude conversation, making it critical infrastructure for agent effectiveness.
Key Principles (from HumanLayer research)
- Under 300 lines (ideally <100). Shorter = better followed.
- Only universally applicable directives. Claude's system prompt uses ~50 of ~150-200 available instruction slots.
- Progressive disclosure: Reference separate docs, don't inline everything.
- Never use as linter: Use actual linters/formatters, not LLM instructions for code style.
- No commands, skills, hooks, or automations: These are discoverable via , , , , and . Don't inventory them in CLAUDE.md — they change frequently and become stale.
- Use pointers instead of code snippets (prevents outdated info).
What "Universally Applicable" Means
A rule is universally applicable if it applies to every single task in this codebase. Ask yourself:
- Would this rule apply when fixing a bug? Adding a feature? Writing tests? Refactoring?
- If the answer is "only sometimes", it does NOT belong in CLAUDE.md.
Examples of universally applicable rules:
- "Use instead of " (applies to every Python task)
- "Run before committing" (applies to every change)
- "All API endpoints require authentication except " (applies to every API task)
Examples of NOT universally applicable (don't include):
- "Use React Query for data fetching" (only applies when adding data fetching)
- "Add migration files for schema changes" (only applies when changing schema)
- Code style rules (use linters instead)
- Commands, skills, hooks, and automations (discoverable via tools, not LLM guidance)
Your Process
Step 1: Explore (ALREADY DONE ABOVE)
Your Explore agent should have discovered:
WHAT (Technology & Structure):
- Primary language(s) and frameworks
- Project structure (especially monorepo layouts)
- Key directories and their purposes
- Configuration files (package.json, pyproject.toml, Cargo.toml, etc.)
- Build/CI configuration
WHY (Purpose & Architecture):
- What the project does
- How different components relate
- Key abstractions and patterns used
HOW (Commands & Workflows):
- Build commands
- Test commands (unit, integration, e2e)
- Lint/format commands
- Run/dev commands
- Deployment patterns
Step 2: Check Existing Documentation
Search for:
- Existing README.md, CONTRIBUTING.md, docs/
- Existing CLAUDE.md — if one exists, read it carefully and propose targeted edits rather than rewriting from scratch. Preserve what's already working.
- Architecture decision records (ADRs)
- Code conventions documentation
Step 3: Create Progressive Disclosure Structure
If complex docs are needed, create an
directory at the repo root with focused files:
agent-docs/
├── architecture.md # System design, component relationships
├── build-and-test.md # How to build, test, verify changes
├── conventions.md # Code patterns specific to this project
├── database.md # Schema, migrations, data patterns
├── api-patterns.md # API design, authentication, etc.
└── glossary.md # User-specific vocabulary Claude can't infer
Only create files that add real value. Don't create empty templates.
Step 4: Write the CLAUDE.md
Structure the file as:
markdown
# Project Name
[One sentence describing what this project is]
## Quick Reference
- **Build**: `[command]`
- **Test**: `[command]`
- **Lint**: `[command]`
- **Dev server**: `[command]`
## Non-Obvious Structure
[Don't list directories — Claude can discover those via tools]
[Instead, document things that AREN'T discoverable from file names alone:]
[- Generated code paths (so Claude doesn't edit them)]
[- Monorepo package relationships and dependency direction]
[- Naming conventions that imply behavior (e.g. *.server.ts = server-only)]
[- Co-location patterns (e.g. each feature owns its routes/, models/, services/)]
## Key Patterns
[2-3 critical patterns or conventions unique to this codebase]
[Use file:line references, not code snippets]
## Documentation
- `agent-docs/architecture.md` - System design and component relationships
- `agent-docs/build-and-test.md` - Detailed build and test instructions
[Only list files that exist]
## Critical Rules
[Only include rules that are UNIVERSALLY applicable across ALL tasks]
[Max 5-10 rules]
[If it can be enforced by a linter, don't include it here]
Step 5: Validate Against Checklist
Before writing the CLAUDE.md:
Output
- First: Summarize what you discovered about the codebase
- Second: Directly create or edit the file. If one exists, make targeted edits. If not, create it.
- Third: Create any files that add real value
- Fourth: List unresolved questions (e.g., "Is there a staging environment?")
Important Notes
- If a CLAUDE.md already exists, default to targeted edits — don't rewrite from scratch. Only do a full replacement if the existing file is fundamentally broken.
- Ask clarifying questions if the codebase purpose is unclear.
- Don't guess at commands—verify they exist in package.json/Makefile/etc.
- Don't include commands, skills, hooks, automations, or other discoverable/deterministic config. These belong in , , , and — not CLAUDE.md.
Additional information provided by User
$ARGUMENTS