I built a tool that roasts your CLAUDE.md. So I fed it 14 real configs from real Claude Code users across GitHub, gists, and blog posts.
Here's what I found.
The Range Is Enormous
On one end: HumanLayer keeps their global CLAUDE.md under 60 lines by design. Their reasoning: frontier LLMs handle ~150-200 instructions reliably. Claude Code's system prompt already uses ~50. So they add only what's universally applicable - and nothing more.
On the other end: WSHobson has 51 specialized subagents organized into five categories - development, infrastructure, quality, specialized domains, and business. And Affaan Mustafa (Anthropic hackathon winner, $15K prize) runs 13 specialized agents, 50+ skills, and a three-agent adversarial security pipeline. His config spans multiple files with a dedicated .claude/rules/ directory for security, testing, git workflow, agents, and performance rules.
Both approaches are deliberate. Neither is wrong.
The 5 Patterns Everyone Uses
After analyzing 14 configs from enterprise security firms (Trail of Bits), SaaS builders, indie developers, and AI specialists, five patterns appeared in nearly every config:
1. Code style enforcement (12 of 14 configs)
Every serious user documents their conventions - not to educate Claude, but to eliminate friction. TypeScript strictness levels, naming conventions, line length limits, export patterns. Scpedicini's Node/TypeScript config even sequences post-completion commands: run pnpm format, then pnpm lint, then pnpm type-check, in exactly that order.
2. Testing requirements (10 of 14)
The experienced configs don't suggest testing. They mandate it. Minimum 80% coverage. TDD workflow. Unit + integration + E2E. Jarrod Watts' config forbids finishing a task until all tests pass - no exceptions.
3. Security rules (9 of 14)
No hardcoded secrets. Environment variables only. Parameterized queries. CSRF protection. Trail of Bits added explicit permission deny rules for SSH keys, cloud credentials, and shell config files. The pattern: if it can leak, make Claude unable to touch it.
4. Command catalogs (8 of 14)
What to run for tests. What to run for linting. What to run for builds. These aren't obvious to Claude in a new context - so the best configs document them explicitly. Builder.io notes these should stay under 300 lines total for token efficiency.
5. Architecture documentation (7 of 14)
File structure. Layer explanations. Domain terminology. Dometrain's fitness app config even maps business concepts to code: "Wraps" = video summaries, "Athlete" = Users. This prevents Claude from introducing naming inconsistencies.
The 5 Things Most People Miss
These appeared in fewer than half the configs, but the most effective setups included them:
1. Post-completion verification commands
Not just "run tests" - but "run these specific commands, in this order, after every change." The difference between Claude thinking it's done and actually being done.
2. Domain terminology maps
Every project has internal vocabulary. If your codebase calls users "Athletes" and Claude writes "User", you'll spend hours renaming. Document it once; eliminate the drift permanently.
3. Agent delegation rules
WSHobson's 51-subagent config and Affaan's 13-agent setup both have explicit criteria for when to stay central vs. route to a specialist. Without these rules, Claude either over-delegates (slow) or under-delegates (poor quality).
4. Exit conditions for autonomous operations
Ralph's autonomous loop config defines exactly what "done" looks like: completion indicators ? 2 AND explicit "EXIT_SIGNAL: true". Vague completion criteria lead to runaway sessions.
5. What NOT to do (anti-patterns)
The best configs document common mistakes explicitly. "Never use type suppressors (@ts-ignore, as any)." "Never batch-complete todos." "Never create files unless absolutely necessary." These are tribal knowledge - if you don't document them, you'll encounter them.
What Separates Expert Configs
Three things distinguished the most sophisticated setups:
Modularity over monolithic files. Enterprise users and experienced devs almost universally use .claude/rules/ subdirectories with separate files for security.md, testing.md, git-workflow.md, agents.md. This keeps the main CLAUDE.md under 100 lines while supporting hundreds of lines of specialized rules.
Manual crafting over auto-generation. The /init command generates a starter config automatically. The experts don't use it. HumanLayer's guide calls CLAUDE.md "the highest leverage point of the harness." It's too important to auto-generate.
References instead of inline content. Rather than pasting 200 lines of style guide, the best configs do @path/to/style-guide.md. The docs stay current, the config stays lean.
Where Does Your Config Rank?
After running these 14 configs through CC Roast, I found:
- HumanLayer (60 lines, principled minimalism): "The Minimalist" - or "Standard Issue Operator" depending on exact line count. Their deliberate brevity keeps them out of the strict-directive tiers entirely.
-
Trail of Bits (explicit deny rules, security-first): "Helicopter Operator" - ironic, because the tool's check order means
strictTotal > 15fires before the security-specific verdict can trigger. Their deny list pushes them past the helicopter threshold. - WSHobson (51 agents, complex orchestration): "S-Tier Micromanager" - orchestrating 51 subagents requires enough MUST/NEVER/ALWAYS rules to max out the strictness meter.
- My own config (28 strict directives in Japanese): "S-Tier Micromanager"
Two micromanagers and a helicopter parent. Turns out control freaks build the most interesting configs.
Check yours: Paste your CLAUDE.md into CC Roast and see what verdict you get. It detects strict directives, forbidden patterns, safety mechanisms, and more - in both English and Japanese.
If you want to go deeper, cc-health-check runs 20 diagnostic checks on your entire Claude Code environment - not just the config file.
I run Claude Code autonomously on WSL2 and document everything - the system I built, the tools I made, and the occasional disaster. This article came from building cc-roast and wanting to know: am I alone in being a micromanager?
More tools: Dev Toolkit - 56 free browser-based tools for developers. JSON, regex, colors, CSS, SQL, and more. All single HTML files, no signup.
Top comments (0)