claude-md

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty). User may specify:

• create - Create new CLAUDE.md from scratch
• update - Improve existing CLAUDE.md
• audit - Analyze and report on current CLAUDE.md quality
• A specific path to create/update (e.g., src/api/CLAUDE.md for directory-specific instructions)

Core Principles

LLMs are stateless: CLAUDE.md is the main project file loaded into every conversation (alongside auto memory and unscoped rules). It serves as the primary onboarding document for AI agents into your codebase.

The Golden Rules

1. Less is More: Frontier LLMs can follow ~150-200 instructions. Claude Code's system prompt already uses ~50. Keep your CLAUDE.md focused and concise.

2. Universal Applicability: Only include information relevant to EVERY session. Task-specific instructions belong in separate files.

3. Don't Use Claude as a Linter: Style guidelines bloat context and degrade instruction-following. Use deterministic tools (prettier, eslint, etc.) instead.

4. Never Auto-Generate: CLAUDE.md is the highest leverage point of the AI harness. Craft it manually with careful consideration.

Execution Flow

1. Project Analysis

First, analyze the current project state:

1. Check for existing CLAUDE.md files:

   • Root level: ./CLAUDE.md or .claude/CLAUDE.md
   • Directory-specific: **/CLAUDE.md
   • Global user config: ~/.claude/CLAUDE.md

2. Identify the project structure:

   • Technology stack (languages, frameworks)
   • Project type (monorepo, single app, library)
   • Development tools (package manager, build system, test runner)

3. Review existing documentation:

   • README.md
   • CONTRIBUTING.md
   • package.json, pyproject.toml, Cargo.toml, etc.

2. Content Strategy (WHAT, WHY, HOW)

Structure CLAUDE.md around three dimensions:

WHAT - Technology & Structure

• Technology stack overview
• Project organization (especially important for monorepos)
• Key directories and their purposes

WHY - Purpose & Context

• What the project does
• Why certain architectural decisions were made
• What each major component is responsible for

HOW - Workflow & Conventions

• Development workflow (bun vs node, pip vs uv, etc.)
• Testing procedures and commands
• Verification and build methods
• Critical "gotchas" or non-obvious requirements

3. Progressive Disclosure Strategy

For larger projects, recommend creating an agent_docs/ folder:

agent_docs/
  |- building_the_project.md
  |- running_tests.md
  |- code_conventions.md
  |- architecture_decisions.md

In CLAUDE.md, reference these files with instructions like:

For detailed build instructions, refer to `agent_docs/building_the_project.md`

Important: Use file:line references instead of code snippets to avoid outdated context.

4. Quality Constraints

When creating or updating CLAUDE.md:

1. Target Length: Keep it under a few hundred lines; shorter is better
2. No Style Rules: Remove any linting/formatting instructions
3. No Task-Specific Instructions: Move to separate files
4. No Code Snippets: Use file references instead
5. No Redundant Information: Don't repeat what's in package.json or README

5. Essential Sections

A well-structured CLAUDE.md should include:

# Project Name

Brief one-line description.

## Tech Stack
- Primary language and version
- Key frameworks/libraries
- Database/storage (if any)

## Project Structure
[Only for monorepos or complex structures]
- `apps/` - Application entry points
- `packages/` - Shared libraries

## Development Commands
- Install: `command`
- Test: `command`
- Build: `command`

## Critical Conventions
[Only non-obvious, high-impact conventions]
- Convention 1 with brief explanation
- Convention 2 with brief explanation

## Known Issues / Gotchas
[Things that consistently trip up developers]
- Issue 1
- Issue 2

6. Anti-Patterns to Avoid

DO NOT include:

• Code style guidelines (use linters)
• Documentation on how to use Claude
• Long explanations of obvious patterns
• Copy-pasted code examples
• Generic best practices ("write clean code")
• Instructions for specific tasks
• Auto-generated content
• Extensive TODO lists

7. Validation Checklist

Before finalizing, verify:

• Kept under a few hundred lines; shorter is better
• Every line applies to ALL sessions
• No style/formatting rules
• No code snippets (use file references)
• Commands are verified to work
• Progressive disclosure used for complex projects
• Critical gotchas are documented
• No redundancy with README.md

Output Format

For create or default:

1. Analyze the project
2. Draft a CLAUDE.md following the structure above
3. Present the draft for review
4. Write to the appropriate location after approval

For update:

1. Read existing CLAUDE.md
2. Audit against best practices
3. Identify:
   • Content to remove (style rules, code snippets, task-specific)
   • Content to condense
   • Missing essential information
4. Present changes for review
5. Apply changes after approval

For audit:

1. Read existing CLAUDE.md
2. Generate a report with:
   • Current line count vs target
   • Percentage of universally-applicable content
   • List of anti-patterns found
   • Recommendations for improvement
3. Do NOT modify the file, only report

AGENTS.md Handling

If the user requests AGENTS.md creation/update:

Since v2.1.277, Claude Code reads AGENTS.md directly as project instructions — but only when the working directory and every directory above it contain no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md. ~/.claude/CLAUDE.md, managed CLAUDE.md, and .claude/rules/ do not count for that check and keep loading alongside. Which files are read is controlled by Project instructions in /config: claude-md-or-agents-md (default), claude-md-and-agents-md, claude-md, or managed-only. Where direct reading is unavailable — versions before v2.1.277 (before v2.1.281 on Bedrock/Vertex/Foundry, LLM gateways, or with telemetry disabled), or the first session after upgrading — fall back to importing it from CLAUDE.md with @AGENTS.md, or symlinking CLAUDE.md to it.

AGENTS.md is a cross-tool project-context file — the same category of document as CLAUDE.md, not an agent-definition format. It exists so several coding agents can share one set of project conventions:

• Build, test, and lint commands
• Code style and architectural conventions
• Repository layout and where things live

Subagents are defined separately, in .claude/agents/*.md — not in AGENTS.md.

Apply similar principles:

• Keep focused and concise
• Use progressive disclosure
• Reference external docs instead of embedding content

Notes

• Always verify commands work before including them
• When in doubt, leave it out - less is more
• The system reminder tells Claude that CLAUDE.md "may or may not be relevant" - the more noise, the more it gets ignored
• Monorepos benefit most from clear WHAT/WHY/HOW structure
• Directory-specific CLAUDE.md files should be even more focused

Last Updated: October 15, 2026 Claude Code Version: 2.1.300 Sources:

• https://code.claude.com/docs/en/skills
• https://code.claude.com/docs/en/memory#agents-md
• https://code.claude.com/docs/en/memory#when-agents-md-support-is-unavailable
• https://code.claude.com/docs/en/memory Compatible Models: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5