1---
  2name: claude-md-forge
  3description: Generate or optimize a CLAUDE.md and .claude/ infrastructure for a repository. Use when user says "create CLAUDE.md", "optimize CLAUDE.md", "set up .claude", "audit my CLAUDE.md", or is bootstrapping a new project.
  4argument-hint: "[repo path or leave blank for current]"
  5---
  6
  7# CLAUDE.md Forge
  8
  9Generate the best possible CLAUDE.md and .claude/ infrastructure for a repository. Research-backed principles, patterns from top open-source repos.
 10
 11## When to Use
 12
 13- Bootstrapping a new project
 14- Optimizing an existing CLAUDE.md
 15- Setting up .claude/ directory (rules, skills, settings, hooks)
 16- Auditing current CLAUDE.md for anti-patterns
 17
 18## Process
 19
 20Target repository: $ARGUMENTS (if blank, use current working directory).
 21
 22### Step 1: Analyze the Repository
 23
 24Read the codebase to understand:
 25- Languages and frameworks used
 26- Build system and package manager
 27- Test framework and commands
 28- Project structure (monorepo vs single package)
 29- Existing CLAUDE.md, .claude/, AGENTS.md, CONTRIBUTING.md
 30- CI/CD setup
 31- Linting and formatting tools
 32
 33### Step 2: Apply Research-Backed Principles
 34
 35The following principles are derived from 23+ academic papers and official Anthropic documentation.
 36
 37#### Attention and Positioning
 38
 39**Primacy effect dominates.** Evidence shows LLMs attend most strongly to the beginning and end of context, with 30%+ accuracy drop for middle content. The primacy effect is stronger than recency.
 40
 41**Action:** Put the 3-5 most critical behavioral rules at the TOP of CLAUDE.md. Put the "Do NOT" prohibitions at the BOTTOM. Reference material goes in the middle where lower attention is acceptable.
 42
 43#### Length and Density
 44
 45**More context hurts even with perfect retrieval.** Evidence shows performance degrades 13-85% as input length increases, regardless of content quality.
 46
 47**Instruction following degrades with count.** Studies across 20 frontier models show threshold decay at ~150 instructions for reasoning models, linear decay for Claude Sonnet. Errors shift from "wrong thing" to "forgetting entirely" above ~100 instructions.
 48
 49**Action:** Target under 200 lines per CLAUDE.md (official Anthropic guidance). Target 30-70 distinct instructions (sweet spot). Apply the pruning test: "Would removing this line cause Claude to make mistakes?" If no, cut it.
 50
 51#### Formatting
 52
 53**Markdown formatting improves performance up to 40%** compared to unformatted text for Claude-class models.
 54
 55**Action:** Use `##` headers for sections, `-` bullets for lists, backtick code blocks for commands. Max 2 levels of heading nesting.
 56
 57#### Instruction Framing
 58
 59**Negative instructions are disproportionately forgotten** under cognitive load. Evidence shows excessive constraints can cause advanced models to over-focus on avoidance instead of achieving goals.
 60
 61**Positive instructions outperform negative ones.** "All SQL in .sql files via QueryLoader" beats "Do NOT write inline SQL."
 62
 63**Action:** State rules positively in their relevant sections. Reserve "Do NOT" for 3-5 genuinely critical prohibitions that have no positive equivalent. Use ALWAYS/NEVER/PREFER/AVOID verb prefixes for unambiguous scanning (astral-sh/uv pattern).
 64
 65#### Context Persistence
 66
 67**CLAUDE.md survives compaction.** It is re-injected fresh on every API request. It is the single most durable piece of project context.
 68
 69**At 70% context utilization, instruction precision drops.** At 90%+, behavior becomes erratic. Shorter CLAUDE.md = more room for actual work.
 70
 71**Action:** Keep CLAUDE.md short. Add a "Compact Instructions" section telling the compaction process what to preserve.
 72
 73#### Instruction Hierarchy
 74
 75**System/user priority is unreliable.** Even simple formatting conflicts produce inconsistent behavior in choosing which instruction wins across all major LLMs (Control Illusion, 2025).
 76
 77**Action:** Make CLAUDE.md instructions non-conflicting with likely user requests. Do not depend on CLAUDE.md always overriding user messages.
 78
 79### Step 3: Apply Structural Patterns from Top Repos
 80
 81Based on analysis of React (240k stars), Deno (103k stars), PyTorch (90k stars), uv (55k stars), Next.js (138k stars), Biome (17k stars), Crush (21k stars), LangChain (105k stars), and Anthropic's own repos.
 82
 83#### CLAUDE.md Structure (target 80-150 lines)
 84
 85```markdown
 86# Project Name (use proper capitalized display name, e.g. "Exo Teams" not "exo-teams")
 87One-line description.
 88
 89## Critical Rules
 903-5 ALWAYS/NEVER rules that matter most. Primacy effect = maximum attention here.
 91
 92## Architecture
 93Stack decisions that affect daily coding. 5-10 bullets, NOT a directory tree.
 94Claude explores filesystems natively - do not waste lines on project structure.
 95
 96## Stack Decisions (Locked)
 97Prevent the model from second-guessing locked choices.
 98
 99## Commands
100Build, test, lint, deploy. Only commands Claude cannot guess from the codebase.
101
102## Implementation Pitfalls
103What WILL break if you are not careful. Non-obvious gotchas.
104(Pattern from Anthropic's claude-code-action repo.)
105
106## Commit Style
107Convention + any repo-specific rules. NEVER add co-author tags.
108
109## Compact Instructions
110Tell the compaction process what to preserve (e.g. "always keep: current task, file paths being edited, test results, architectural decisions made this session").
111
112## Do NOT
1133-5 hard prohibitions. Benefits from recency effect at bottom of file.
114```
115
116#### What to EXCLUDE from CLAUDE.md
117
118These are explicitly called out by Anthropic's official documentation as anti-patterns:
119
120- Project structure trees (Claude explores filesystems)
121- Standard language conventions Claude already knows
122- Detailed API documentation (link to docs instead)
123- Information that changes frequently (entity types, enum values)
124- Long explanations or tutorials
125- File-by-file codebase descriptions
126- Self-evident practices ("write clean code")
127- Code conventions details (put in path-scoped rules instead)
128
129#### .claude/ Directory Infrastructure
130
131Before generating, **analyze the codebase** and determine which path-scoped rules are needed based on:
132- What languages/frameworks exist in the repo
133- What file patterns need specific conventions
134- What testing patterns are used
135- What database/query patterns exist
136
137Only create rules for languages and patterns that actually exist in the codebase. Don't generate a `go.md` rule for a Python-only project.
138
139```
140.claude/
141├── settings.json          # hooks, deny list, project metadata
142├── rules/                 # path-scoped rules (auto-load by file pattern)
143│   ├── python.md          # paths: ["**/*.py"] - only if Python in repo
144│   ├── typescript.md      # paths: ["**/*.ts", "**/*.tsx"] - only if TS in repo
145│   ├── go.md              # paths: ["**/*.go"] - only if Go in repo
146│   ├── sql.md             # paths: ["**/queries/**/*.sql"] - only if SQL queries exist
147│   └── testing.md         # paths: ["**/tests/**", "**/*_test.*"] - only if tests exist
148└── skills/                # on-demand invokable skills
149    └── code-conventions/
150        └── SKILL.md       # full style guide with examples
151```
152
153Each rule file should contain the **specific conventions, linters, formatters, and patterns** for that language as used in THIS codebase. Read existing code to extract the actual patterns being followed, don't assume generic defaults.
154
155**settings.json patterns to include:**
156
157```json
158{
159  "hooks": {
160    "PostToolUse": [
161      {
162        "matcher": "Edit|Write|MultiEdit",
163        "command": "auto-format.sh \"$CLAUDE_FILE_PATH\""
164      }
165    ]
166  },
167  "permissions": {
168    "deny": ["wrong-package-manager", "git push --force", "git reset --hard"]
169  }
170}
171```
172
173The PostToolUse auto-format hook (from uv, React, Anthropic repos) eliminates "run the formatter" reminders entirely. The deny list prevents wrong tools. Detect the actual formatter from the repo (ruff for Python, gofmt for Go, prettier for TS/JS, biome, etc.) and wire it into the auto-format script.
174
175**Path-scoped rules vs CLAUDE.md vs skills:**
176
177| Put here | When |
178|----------|------|
179| CLAUDE.md | Rule applies to ALL work in the repo, every session |
180| .claude/rules/ | Rule applies only when touching specific file types |
181| .claude/skills/ | Detailed reference or workflow invoked on demand |
182
183Rules are more token-efficient than CLAUDE.md because they only load when relevant. A python style rule does not burn context during Go work.
184
185### Step 4: Generate the Files
186
1871. Write CLAUDE.md following the structure above
1882. Create settings.json with auto-format hook and deny list
1893. Create path-scoped rules for each language/domain in the repo
1904. Optionally create skills for complex workflows
1915. Create the auto-format script if the repo has linters/formatters
192
193### Step 5: Validate
194
195- Count lines: CLAUDE.md should be under 200
196- Count distinct instructions: should be 30-70
197- Apply pruning test to every line
198- Check for duplication across CLAUDE.md, rules, and skills
199- Verify no project structure trees or enumerable data that will go stale
200- Confirm critical rules are at the top, prohibitions at the bottom
201