I Gave My AI a Brain

A CLAUDE.md tells AI what your project is. A brain/ tells AI how to think. The difference is 8 corrections that would have shipped without it.

Most people using AI for content or code have a context file. CLAUDE.md, .cursorrules, AGENTS.md. A file that tells the model what the project is. "This is a Python repo." "Use lowercase headings." "Target 1,500 words."

A brain is different. A brain is a directory of files that tells the model how to do the work. Not "this is a content repo" but "here are 16 patterns that make AI writing sound robotic. Check every article against them." Not "use markdown" but "here are 8 things AI fabricates when editing articles. Verify each one manually before publishing." The brain also sequences the work: evidence first, then draft, then verify against sources, then revise for voice, then generate distribution posts.

Context tells AI what. Process knowledge tells AI how. The distinction matters because context alone doesn't prevent mistakes. I had a CLAUDE.md from day one. On day two, AI was still producing 10 em-dashes per article, fabricating metrics, and writing enterprise content in first person singular. The CLAUDE.md told it what the project was. It didn't tell it what goes wrong or how to avoid it.

the 8 corrections that became 23 files

Day 1-2 of building a content pipeline, every AI interaction needed corrections. "Make it more human, less em-dashes." "Are you sure this is for enterprise? It says 'I' everywhere." "Check whether those links actually resolve." "Don't round 187 to 'about 200.'" Eight corrections, each given once, each forgotten by the next session. By the third session, I was repeating the same feedback.

On day 3, I extracted every correction into files. One commit. The corrections themselves didn't change. They just moved from ephemeral session feedback into versioned markdown. The em-dash complaint became a rule: "target 0-3, AI defaults to 8-12." The enterprise voice fix became a skill: "first person plural for enterprise, first person singular for personal." The link-checking reminder became a verification checklist with 8 categories ordered by cost.

I didn't design the brain. I organized my corrections. The corrections were already the brain. They just weren't written down.

That single commit created brain/ with 23 files across four directories. Not designed upfront. Extracted from two days of fixing the same problems twice.

Ramya Chinnadurai hit the same wall independently. Five days debugging her AI agent's memory. Day 5, she audited the system prompt: 11,887 tokens, 51 skills (20 never used), a 200-line MEMORY.md loaded every session. She pruned to 8,529 tokens, 32 skills, a structured directory with learnings/, memory/, skills/, docs/. Her rule: "LEARNINGS.md is the most underrated file. Every mistake becomes a one-line rule." Same pattern, different domain. The corrections are the brain.

what's in a brain

Four layers, each solving a different problem.

Lessons are the raw evidence. 8 retrospectives with commit-level data from real projects. "AI rewrote Crawshaw's 'real but eclipsed' as 'dismissive.' A nuance flip, not a typo." "Every AI-generated feature needed 1-3 fix commits across 6 of 7 repos." These are the facts that make articles credible. Without lessons, every claim is opinion.

Skills are the operational rules. 5 files covering drafting (voice, structure, formatting), revision (16 AI-sounding patterns, 8 fabrication categories), evidence correlation (verification status per claim), plan creation (topic evaluation scoring), and distribution (platform-specific format rules). The revision skill alone is checked in every editorial session.

Prompts are invocation templates. 5 files encoding how to start a task. "Write piece #N of the series. Use this article as tone reference. Here's the evidence. Here's the outline." Most useful in fresh sessions. When the AI already has brain/ loaded, skills provide the same instructions directly.

Workflows are pipeline sequences. 4 files encoding what order. The content pipeline: research, then evidence map, then plan, then draft, then evidence correlation, then editorial revision, then distribution. Workflows prevent the most common quality failure: drafting before evidence mapping, which produces articles with unsupported claims.

The layered structure means each file stays focused. A skill describes how to do one thing well. A lesson stores raw evidence without mixing in process. When the revision skill gets a new fabrication category, every workflow that references it inherits the update.

Anthropic's Skills Guide calls this "execution design": the shift from crafting prompts to designing execution systems. A skill is a structured system, not a single prompt. The brain applies that architecture across an entire content workflow.

what it catches

The evidence, from production.

The fabricated metric. Evidence correlation flagged "20% of fabrications" as UNVERIFIED. A number AI invented with no primary source. The percentage appeared in no retrospective, no curated industry article, no earlier draft. Without the brain's correlation step, that number ships to readers.

The em-dash flood. AI defaults to 8-12 em-dashes per article. The brain's rule says target 0-3. That single line is the fastest, most reliable way to make AI prose sound human-written. It fired in every article across both the writing series and the enterprise series.

The file count error. I wrote "24 files" in a draft of Part 4. The evidence correlation didn't catch it because the number required running find brain/ -name "*.md" | wc -l, which returned 23. Environmental verification: the kind where the answer lives in the filesystem, not in curated sources. I caught it on a manual pass. The brain's stale reference and distorted quote checks (Part 2, Part 3) catch the categories they were built for. This one fell outside the taxonomy.

Voice consistency across 8 articles. The brain's voice rules produced word counts between 1,601 and 1,671 for a 1,500-2,000 target. Consistent formatting, consistent tone, consistent structure. Without the rules, each session drifts toward generic blog voice.

The brain is a test suite for prose. Each rule maps to a real failure. Each failure was caught in production before publication.

when you need one (and when you don't)

The trigger is repetition. If you've corrected the same thing across three sessions, that's a rule. Write it down. 10+ rules become a skill file. 3+ skill files covering different capabilities become a brain.

For a side project with one AI session a week, CLAUDE.md is enough. The context file handles project description, conventions, and basic rules. The corrections are infrequent enough that repeating them manually isn't a bottleneck.

For production content with multiple articles per week, the brain earns its weight. I have two working implementations: a 23-file content brain (3,011 lines, at last count) for the article pipeline, and a 6-file site brain (545 lines) for the blog itself. Each was extracted in a single commit from accumulated corrections. Each went stale within 5 days when I stopped updating it. The structural problems were identical: duplication between files, no feedback loop from production.

Scale determines shape, not complexity. Mitchell Hashimoto describes harness engineering: "anytime an agent makes a mistake, engineer a solution so it never happens again." His Ghostty AGENTS.md has every line mapping to a fixed bad behavior. That's a brain in a single file. When the file outgrows itself, you split it. When the split files need sequencing, you add workflows. The architecture follows the problems.

Simon Willison makes the broader point: "LLMs actively reward existing top-tier engineering practices." Good documentation, automated testing, planning in advance. The brain is documentation of process, and by Willison's logic, the highest-leverage investment. Models build implementations from docs alone.

how to build one

Every brain I've built started the same way: not from a design session, but from a week of corrections.

I worked with AI for two days on production content. I wrote down every correction. No structure yet, just capture. "Too many em-dashes." "Wrong voice for this audience." "Check the links." "Don't summarize the previous article." "Evidence before claims."

After day 2, I grouped by type. Voice corrections became voice rules. Verification failures became a verification checklist. Formatting fixes became formatting patterns. Repeated mistakes in a specific capability became a skill file for that capability.

I organized into directories: skills/ for how to do it, lessons/ for what I'd learned (specific examples, real failures), workflows/ for what order. A README tells AI which files to read for which task. One commit.

That's the brain. Extracted from corrections, not designed from scratch.

Armand Ruiz, distilling practices from Anthropic's internal engineering, documents the same progression. A tasks/lessons.md file where "after ANY correction, update lessons.md." A "compounding system where mistake rate drops over time by learning from feedback." The lessons file is the seed. The brain is what grows from it.

The pattern is converging from multiple directions. Heinrich runs 249 interconnected markdown files as a traversable knowledge graph. When Levelsio asked about AI memory, Vadim Strizheus posted the memory prompt that 143 replies confirmed as the #1 frustration with AI. The vocabulary differs: AGENTS.md, skill graphs, memory folders, vaults. The structure converges: organized process knowledge that persists across sessions, grows from corrections, and makes AI output reliable.

The brain doesn't eliminate the human pass. It compresses it. Mine went from 2-3 days per article to under 3 hours. Not because AI got smarter. Because the harness encoded everything I'd already learned.

This is part 5 of a series on AI-assisted writing. Part 1: "AI Writes Code, I Write Prose" established the inversion. Part 2: "47 Rules, Each from a Real Mistake" built the system. Part 3: "Everything AI Fabricates When Editing an Article" mapped the taxonomy. Part 4: "The System Outgrew the Series" traced the evolution.

Built in Porto. Data from real articles, real revision passes, real brains built.