Give every repo a CLAUDE.md runbook any AI can follow

The problem

Your repo works because you remember how it works. The deploy has one manual step, the copy has voice rules, one config value must never change. None of that is written where an agent can find it, so every fresh Claude Code session starts by guessing, and every guess is a chance to break something. Without a CLAUDE.md runbook, you are the only maintainer your repo will ever have.

One file, loaded every session

Every repo in my ecosystem gets a root CLAUDE.md written as a runbook, not a wiki. Claude Code loads it automatically at the start of every session, so whatever lives there is the first thing any agent knows about the project. The convention I hold every repo to: the header points to PRD.md (what we are building and why) and README.md (facts and quickstart), so the read order for a fresh agent is always the same. CLAUDE.md, then PRD, then README. An agent landing in a repo that follows it orients the same way every time instead of improvising.

This website runs on that file. “Add a free guide” is a numbered job in its runbook, and launches are gated: a grep for leftover placeholder markers must return nothing before anything goes live. The same pattern runs my second brain that maintains itself, where the vault’s CLAUDE.md is the librarian agent’s entire job description.

What goes in a CLAUDE.md runbook?

Three sections carry all the weight. Golden rules: the short list of non-negotiables that apply to every task. Routine jobs: each recurring job written as literal numbered steps, specific enough that an agent needs zero judgment calls. Gates: checks that must pass before anything ships. Here is the skeleton to copy:

# my-app: agent runbook

Read order for a fresh agent: this file, then PRD.md (vision),
then README.md (facts and quickstart).

## Golden rules
1. Config over code: brand, links, and offers live in src/config/.
   Edit config before touching components.
2. All copy follows the voice rules below. Sentence case headings.
3. Verify every change: the build must pass before you call it done.

## Job: publish a post
1. Copy any file in src/content/posts/ and rename it.
   The filename becomes the URL slug.
2. Fill the frontmatter: title, description under 170 chars, date.
3. Run the build. Fix anything it flags.

## Gate before deploy
grep -rn "REPLACE-ME" src/    # must return nothing

Write every job for a stranger with no memory, because that is exactly what a fresh agent session is.

When a job outgrows a few steps, move it into its own skill and leave a one-line pointer in the runbook. I covered that split in turn any workflow into a Claude Code skill.

Do this now

1. Open your most active repo and run /init in Claude Code to draft a starter CLAUDE.md.
2. Rewrite your most common routine job as literal numbered steps under a ## Job: heading.
3. Add one gate: a single grep or build command that must pass before deploy.

Then run the next deploy by asking an agent to follow the runbook. Every place it stumbles is a missing line.