The Claude Code Blueprint Nobody Posts

Every week, a new Claude Code infographic hits LinkedIn. Perfect folder trees. Color-coded architecture diagrams. Clean terminal screenshots where nothing is broken.

They're not wrong. Most of them are describing real features, CLAUDE.md, skills, hooks, MCP configs, agents. The problem is they're describing the menu, not the meal. The distance between "here's the folder structure" and "here's what happens when you actually use it for six months" is where every interesting lesson lives.

I've been running Claude Code across multiple projects since late 2025. I have 50 skills in active rotation. I've broken things that the cheatsheets don't warn you about.

CLAUDE.md: Keep It Under 200 Lines Is Wrong

The most common advice: keep your CLAUDE.md short. Under 200 lines. "Claude loads it at session start, so keep it lean."

What actually matters is information density per line, not line count. A 400-line CLAUDE.md that prevents five minutes of re-prompting per session pays for itself in the first week. A 50-line CLAUDE.md that reads like a README helps nobody.

My approach: CLAUDE.md carries the hard rules, stack, conventions, security constraints, testing patterns, and the things Claude gets wrong repeatedly. Everything else goes into skills, which load on-demand and don't burn context until triggered.

Skills Are the Actual Superpower

What they miss: skills encode your mistakes, not just your process. Every time Claude gets something wrong and I correct it, the fix goes into a skill, not as a positive instruction, but as a gotcha with a FAIL condition. "If the output contains X, the skill failed." That's what makes the system learn.

After 50 skills, the pattern is clear: the best skills are the ones I captured retroactively after watching Claude make the same mistake three times.

The Compliance Gap Nobody Warns About

Hooks are the enforcement mechanism. PreToolUse hooks block dangerous operations. PostToolUse hooks auto-lint after writes. But here's the gap in every cheatsheet: none of them address the environment split.

I learned this by deploying skills that passed every test in Claude Code and silently failed to enforce in Cowork. Four compliance gaps currently gate my next deployment. The fix: separate your skill library into "Claude Code native" and "claude.ai portable" categories. Test each in its target environment.

Project Structure: What You Actually Need

project/
├── CLAUDE.md              # Hard rules, >200 lines
├── .claude/
│   ├── settings.json      # Permissions, hooks, model
│   ├── settings.local.json # Personal overrides (.gitignored)
│   ├── skills/
│   │   └── skill-name/
│   │       ├── SKILL.md
│   │       └── references/
│   ├── commands/
│   └── agents/
├── .mcp.json              # Root only. Never nested.
└── src/

The key differences from the poster versions:

settings.local.json is non-negotiable. Personal overrides that never touch git. Different developers, different permission levels, no merge conflicts. Every cheatsheet mentions .gitignore. Almost none mention this file specifically.

Skills get references/ subdirectories. A skill that needs a 3-page API reference shouldn't embed it inline. Supporting docs stay accessible but out of the critical path. The SKILL.md stays focused on decision logic.

.mcp.json stays at root. One file, one place. The moment you split MCP configs across directories, you introduce a debugging nightmare where Claude connects to the wrong server. I learned this the hard way, Claude hit a staging database because the config inherited from a parent directory I'd forgotten about.

The Self-Improvement Loop Is the Whole Point

Boris Cherny nails this and most guides miss it entirely. After any correction: update a lessons file. Write rules that prevent the same mistake. Review lessons at session start.

My implementation: every skill has an implicit fail condition. When Claude produces output that trips it, I don't just fix the output, I update the skill with a new GOTCHA entry. The next time the skill fires, the gotcha is in context. The mistake rate on that specific pattern drops to near-zero.

The cheatsheets show you the architecture. The correction loop is the engine.

Five viral infographics, and the most important lesson isn't in any of them: Claude Code's value is in the judgment you encode into it over time. The structure is scaffolding. The skills, hooks, and correction loops are the building.

If your Claude Code setup looks exactly like the cheatsheet, you've built the scaffolding. The question is whether you've started building yet.