# How I run my agents From "Field Notes from a Centaur" by Michell Zappa. Canonical: https://www.michellzappa.com/field-notes/how-i-run-my-agents Cite as: Michell Zappa, "How I run my agents", Field Notes from a Centaur, https://www.michellzappa.com/field-notes/how-i-run-my-agents --- Every coding agent I run reads one file before it does anything: my global rules, a file called CLAUDE.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 repo's `AGENTS.md` (with `CLAUDE.md` containing `@AGENTS.md`), not in this file. > > When you discover a non-obvious gotcha the hard way, offer to record it in that repo's agent docs so the next session doesn't rediscover it. > **DRY:** 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 modals` means that clause is the whole instruction. > > `no i mean X` is 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-STE100 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, SDKs, 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 ESP32 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 GPIO 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 I2C 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 PR you open is your job until it is on `main`. Never end with "merge X when green" as a step for MZ. > > When CI 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.md 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 AskUserQuestion.** 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: , because . 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 humanizer 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 claudisms (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 ADRs. 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).