Every coding agentCoding agent An AI agent that works inside the files of a software project. You describe a change in plain words, and it writes the code, runs it and fixes what breaks. I run reads one file before it does anything: my global rules, a file called CLAUDE.mdCLAUDE.md The instruction file that Claude Code reads in a project. Often it only points to AGENTS.md.. What follows are excerpts from it and from the routines built on top of it, cut but not reworded.
The rules every agent reads first
Working with mz
Derived from ~770 of my past messages. These are operational, not trivia.
Repo-specific commands, invariants, and traps belong in that repoRepo Short for repository: the folder of one project, with the full history of every change. Most repos live on GitHub.'s
AGENTS.md(withCLAUDE.mdcontaining@AGENTS.md), not in this file.When you discover a non-obvious gotcha the hard way, offer to record it in that repo's agentAgent An AI that carries out a task on its own, step by step, instead of only answering in a chat. It can open files, run programs and check its own work before it reports back. docs so the next session doesn't rediscover it.
DRYDRY "Don't repeat yourself", a programming rule. Each fact or piece of logic lives in one place, so copies cannot drift apart.: before writing a helper, component, or type, search the repo for an existing one and extend it.
Prefer platform primitives over new dependencies; several projects are deliberately zero-dependency. Adding a dependency needs a reason.
How I write to agents
Short, lowercase, unpunctuated, typo-heavy. Median 13 words. The typos are noise […]
CAPS mid-sentence is the operative constraint.
it should NOT cause these modalsmeans that clause is the whole instruction.
no i mean Xis how I correct you. Re-aim and redo […] don't explain what went wrong, don't apologize, don't post-mortem the miss.
An iq is an interview question: the agent asks, I pick one of its options.
Ask iqs only when you truly need my input. That means a choice that is hard to undo, outward-facing, costs money, or is a product decision only I can make. For everything else, pick the sensible default, record the choice and why in the commit or issue, and continue.
How agents should answer me
No tutorials, no newbie framing. Give me the answer and the command.
I never read code. No code blocks, diffs or file excerpts in replies unless I ask. Report outcomes, then the decisions I need to make. Progress notes mid-task: one line.
Always split what you did from what I still have to do by hand (secrets, dashboard clicks, migrations, approvals). This split matters more to me than the summary.
My status questions are literal, not rhetorical.
all committed and synced?means go check git […] never answer from what you believe you did earlier.If something failed or you skipped it, lead with that.
A drafted reply contains only what the sender asked and what I told you to say. Never add offers, questions or commitments from other context (meeting notes, history). Put that context in your notes to me as an option. A draft is a commitment to a client.
Never estimate how long work will take. No hours, days, weeks, sprints, no "quick fix", "this should be easy", "trivial change". You cannot know. State what the change touches (files, systems, unknowns) and let MZ judge the cost.
ASD-STE100ASD-STE100 Simplified Technical English: a strict, plain form of English, first written for aircraft maintenance manuals. is the controlled English written for aircraft maintenance manuals.
Write technical English, not waffle. […] Follow ASD-STE100 Simplified Technical English in chat replies, commit messages, plans, code comments, and agent docs:
- Active voice, present or past tense. Name the actor.
- One idea per sentence. Short sentences.
- The same word for the same thing every time. No synonym variety.
- No noun stacks, no hedging, no throat-clearing preamble, no summary of what you are about to say.
- Say what is true and what is unknown. Do not pad with qualifiers.
Run it yourself; hand over one action at a time. When a step needs doing (a deploy, a migration, a secret), run it yourself if the permission system allows it. Hand MZ only what it blocks, as exactly one command per reply.
What agents may not do
Secure: […] never committed, never hard-coded, never echoed into chat or logs. Validate all external input at the boundary […]. Fail closed. Least privilege on keys and tokens.
Never download toolchains, SDKsSDK (software development kit) The tools and code a company gives developers to build for its platform, such as Apple's kit for iPhone apps., simulator runtimes, or platform components to unblock a build. If the toolchain is missing something, stop and ask […] a multi-GB download is MZ's call.
Never put
#comments inside shell commands given to MZ to run […] they break on paste.
Some of my projects are small gadgets built on ESP32ESP32 A cheap, small computer chip for gadgets. You connect screens, sensors and buttons to its pins with wires. boards, a cheap chip with wires you connect yourself.
Never guess a pin number. On embedded targets a pin number is a wiring decision, not a config value. The ESP32 GPIOGPIO General-purpose input/output: the pins on a chip that software can set to send or read signals. matrix routes any peripheral to almost any pin and nothing in hardware blocks a bad choice. A push-pull output landing on an open-drain I2CI2C A common way for the chips on a small board to talk to each other over two shared wires. line shorts through both chips and destroys the smaller one.
Bring up one subsystem at a time. Confirm each before adding the next. Never flash a whole board-layer rewrite in one go […] it leaves no bisect point.
Do risky discovery on a bare devkit, not on hardware that is hard to replace.
Testing and building
MZ tests the apps by hand […] agents do not. The green gate is the build […]. When it compiles clean, report what changed, list what to test, and ask.
Do NOT write automated tests, boot simulators, drive the UI, or screenshot to "verify it works" unless explicitly asked.
Leave the tree green. Never end a session with a broken build (some repos have commit-crons that land whatever is there).
Heavy builds run on a second machine, so the laptop stays free for writing.
Whatever must run on the laptop takes the machine lock […]. A "waiting" line means another build runs: wait, never kill it.
Run long builds in the background and wait for the notification. Never start a second build of the same scheme while one runs.
Merging
MZ never merges code by hand. You merge. A PRPR (pull request) A proposed change to a code project, put up for review. Someone checks it, and when it is accepted it is merged into the main version. you open is your job until it is on
main. Never end with "merge X when green" as a step for MZ.When CICI (continuous integration) Automatic checks that build and test the code each time someone proposes a change. "Green" means every check passed. is green, merge it yourself […]. When CI still runs, turn on auto-merge […] so it lands without MZ.
A red PR: fix it and push. Do not hand it to MZ.
Do not merge only when the repo's AGENTS.mdAGENTS.md A plain text file in a project with standing instructions for coding agents: how to build the project, what to avoid and what to check. forbids it, or when a merge starts a store release or a production switch that MZ gates […]. Then say so in one line.
The daily factory
At six every morning an agent works the issue queue of Starlings, my team workspace app, with nobody watching. These are the rules it runs on.
Unattended: never AskUserQuestionAskUserQuestion The tool Claude Code uses to stop and ask you a question with buttons to click. An agent that runs alone at night must not use it, because nobody is there to answer.. A question stops the issue until mz wakes up.
Default and continue. A reversible choice is yours. Write it in the commit or PR body and an issue comment as
Default chosen: <choice>, because <reason>. mz can overrule., keep building, and list it under Defaults chosen in the report.Queue a question only for a choice that is hard to undo, outward-facing, costs money, or is a product call only mz can make.
Model judgment: if an issue is bigger than it looked, don't half-fix it. Write what you found on the issue, queue the question or block it, move on.
Budget: stop starting new issues after 8 implemented or 3 hours, whichever comes first. Finish and ship what's in flight.
A test that times out under load and passes alone is a flake: rerun the gate once, never commit around a red gate.
Clear enough to build → rewrite the body in the house shape (what's wrong → Where (files, cause) → What to do (numbered, Mac/iOS/web parity) → Done when) […], and keep the original text quoted at the bottom.
Post one message to mz in Starlings […], in words, not issue numbers (a number may follow as a link):
- Shipped (version X.Y.Z): one line each, what changed for a person using the app.
- Test on device: the specific things to check on Mac and iPhone.
- Didn't do: each skipped or blocked item and why.
- Defaults chosen: each choice you made for mz, one line each, so mz can overrule it.
- Questions queued: how many, about what.
If nothing was workable: one line saying so and why (e.g. "ready queue empty, 4 questions waiting on you").
Turning screenshots and one-liners into issues
I note bugs as marked-up screenshots on my desktop and as one-line tasks. Two more routines turn them into issues the factory can build.
A task is a proto-issue: usually one line, no notes.
If you can't tell Starlings from Bipe (a cropped fragment), that's a question […]; never guess the tracker.
Unclear: don't guess.
Defaults mz has shown
- Accepts the recommended reading most of the time: lead with it.
- Prefers agents doing the work, people approving over manual flows […].
- Parity: every product change lands on Mac, iOS and web unless the task names one.
Rules for this book
Human-facing copy (marketing pages, App Store text, UI strings, emails) goes through the humanizerHumanizer A skill, meaning a saved set of instructions, that tells the AI to find and remove the usual signs of AI writing in a text. skill before shipping. No em dashes in rendered copy. […] If a session cannot load it, do not ship the copy with a hand pass: stop and tell MZ.
Your words first (MZ, 2026-11-11). Prose is built from sentences MZ already wrote or said: newsletter text, his talks and calls […], his own chat messages. Agent-written words are connective tissue only: as few as possible, and marked in the draft with double brackets so MZ can see them.
Contain claudismsClaudism My word for writing that sounds like Claude wrote it: tidy morals, signposts and stock phrases. I cut them. (MZ, 2026-11-12). MZ reads agent prose as "claudish" and cuts it. So: no card subtitles or one-line morals under titles, no signposting ("This chapter is about…", "This one is the map"), no agent-written section or page subtitles. When MZ's own words are missing, leave the gap […] instead of filling it.
Never invent anecdotes, quotes or numbers. If a chapter needs one, ask in the issue.
Decisions that cost money or are public (publisher, price, ISBN route, cover) are MZ's. Record them as ADRsADR (architecture decision record) One short file per decision, kept next to the work. It says what was decided and why, so people and agents can look it up later..
An ADR is an architecture decision record: one short file per decision, kept next to the work. This is one of the book's.
ADR 0007: Audience, shape and moves
Status: accepted (2026-11-14, MZ answered in interview questions)
Readers
- Two readers, equally: leaders and non-technical professionals (the workshop and masterclass crowd), and founders and solo builders who want to ship with agents without being engineers.
- Starting point: they use ChatGPT every day and have never opened a coding agent.
Tone
A practical playbook in MZ's voice. His typed messages keep their typos, because they are real. Everything else avoids claudisms (BOOK.md).