Your AGENTS.md Is an Operations Manual

Your AGENTS.md Is an Operations Manual

The Most Important File in Your Pipeline Isn't Code

articleNovember 17, 2026Scott Fegette

Most people building their first agentic workflows spend their energy on the wrong things. Coming from chatbots, they polish their prompts, tweak the model’s settings, and argue about which tool to use, while the one document that decides whether the pipeline behaves or misbehaves sits half-written in a folder. That document is your AGENTS.md, and it deserves to be treated like what it is: an operations manual for a team that never asks you a clarifying question.

If you've ever onboarded a new hire, you already know the problem. You can hand someone a talented résumé and a laptop, but on day one they still don't know who approves what, which client is touchy about turnaround, or what to do when two instructions conflict. A good manager writes that down because the alternative is answering the same questions forever or, worse, discovering the answers after something goes wrong. An AI agent running while you're asleep is the same new hire, with one difference: it won't call you. Whatever isn't in the manual doesn't exist.

Roles are the skeleton; behaviors are the muscle

In the first stage of building a pipeline, an AGENTS.md is mostly a list of roles. Each role gets a purpose, the expertise it brings, the input it expects, the output it produces, its constraints, and a handoff condition that says when its work is done and who picks it up next. That's enough to get a team of agents working in sequence, and it's what I walk through in the role-building chapter of Creative AI.

But a list of roles only tells the agents who they are. It doesn't tell them how to act when the situation gets messy, and the messy situations are the entire job. So the second pass, the one that turns a role list into an operations manual, adds a handful of fields that govern behavior.

Default behavior: what happens when nobody says

The first field is default behavior, and it answers the question every unattended agent eventually hits: what do I do when my instructions don't cover this? Without a default, the agent improvises, and improvisation from a language model is confident, fluent, and occasionally wrong in ways that are hard to spot afterward.

A good default is boring on purpose. Something like: when the brief is ambiguous, proceed with the most conservative reading, record the assumption you made, and flag it in the summary. That one sentence converts a silent guess into a visible one. You'll still get a deliverable in the morning, but you'll also get a note saying "I assumed the client wanted the shorter version," and you can fix a visible assumption in thirty seconds.

Escalation rules: when to stop and ask

The second field is escalation. Every pipeline needs a short list of conditions under which an agent stops working and waits for you instead of pushing through. Budget limits, anything that touches money or contracts, a client name it doesn't recognize, a brief that contradicts an earlier one, a request outside the role's scope: these belong on the list. I'll write about how to decide where the line goes in a separate post because it's the hardest design decision in the manual. For now, the point is that you should write escalation rules ahead of time while you're calm, so that they don't get invented by the agent at 3 a.m.

Scope compression: what to do when the work is bigger than the run

This one surprises people. Agents have limits on how much they can do in one pass, and an overnight run that hits a wall fails in the worst possible way, by quietly doing a worse job on everything instead of doing a good job on some things and saying so.

Scope compression is the instruction that tells the agent how to shrink a job gracefully. Do the highest-priority briefs first. If time or budget runs short, finish fewer things well rather than all things badly. Leave an explicit list of what didn't get done. It's the difference between a morning summary that says "three of five briefs complete, two queued" and one that cheerfully reports five completed briefs, two of which are junk.

Logging: what you'll wish you had

The last field is logging, and it's the one most folks skip until the first time something goes wrong, and they can’t figure out why. Every agent needs to write what it received, what it decided, what it produced, and anything in the process it was unsure about. This isn’t a transcript, which nobody reads, but a short structured record you can scan in two minutes.

Logging also changes how you trust the system. When you can see the reasoning behind a result, you can tell the difference between an agent that made a good call and one that got lucky, and you can tighten the manual accordingly. A pipeline you can't inspect is a pipeline you'll end up supervising by hand, which defeats the purpose.

For bonus points, have that log summary sent where you can read it easily and quickly. Discord is where I send mine, as it gives me a notification ping whenever a summary is ready. Email works too!

The manual is a living document

This is the part that I had a hard time adjusting to: initial versions of your AGENTS.md files can feel wrong, but that's just the process working. Every unexpected result is valuable information about a missing rule. The agent might have skipped a step because the handoff condition was vague. It could have made a bad assumption because the default behavior wasn't specified. Or perhaps it sat on a decision because nothing told it to escalate. Each of those small failures becomes a line in the manual, and the manual gets sharper with every run.

Another area that I had a lot of trouble with was a lack of context from prior sessions. Getting to work on a new project would often see the agent overlooking mistakes we’d made previously, or entirely forgetting new teachings and insight from the prior runs. A strong session start/session end protocol quickly became one of my key agentic definitions.

For example, at each session’s end, my agents write out a log of their session’s key points to memory- sometimes to Obsidian/Notion where I can read it, and sometimes into Markdown files in a /memory folder inside the project directory that the models all access. That memory entry sums up the session’s key goals and deliverables, and anything we learned in the process that could be helpful for subsequent runs, whether project-specific or related to the agentic process itself.

And when each new agentic session is initiated, the session-start protocol reads the last session, and its lessons. Each has a date/time stamp so we can ‘roll back’ through what we’ve accomplished session-to-session and introspect how things are working more deeply, over time.

This strategy is durable, and it’s portable. Your AGENTS.md file can work across AI models - just point any new model to it and you can quickly ‘onboard’ it to your workflow with clear project and process memory. Think of this as simply maintaining your own workflow manual that provides consistency as your projects and virtual team grow.

This is exactly why I'd argue the manual, not the model, is your real intellectual property. AI models can and will change every few months. A well-tuned operations manual that codifies how you like to work, where your judgment is required, and what good looks like from your perspective carries over to whatever tool comes next. It's the one part of the system that's actually yours.

Start small, then upgrade

If you're staring at a blank file, don’t write the whole thing at once. Start with the roles. Run the pipeline once on a low-stakes brief. Read what comes out, and for every disappointment, ask which field would have prevented it. Add that field. Run it again. Three or four iterations in, you'll have a manual that reflects how you actually work, written in response to real behavior instead of hypothetical failures.

That's the exercise at the heart of the workflows chapter in Creative AI: take the role file you built in the previous chapter, upgrade it with default behavior, escalation rules, scope compression and logging, and then let it run overnight on a real brief. What you wake up to is the best feedback you'll get on whether your manual is any good.

How I handle this in my workflow

The best place to start in sharing how I’ve actually set things up on my end is the agentic stack that runs my website.

  • It’s a five-repo agent network at the core.

  • The infrastructural repo is my root node: it owns the Docker stack, deploy pipelines, CDN and tunnel config, GitHub Actions, the tracker and the CMS ingest pipeline, and the roles manifest itself.

  • The frontend repo is a peer: it owns the public-facing site, landing pages and FAQs.

  • There are two coding agents (senior-dev, junior-dev) that delegate approved architecture down for implementation. Senior-dev works with me to vet my architecture and fully scaffold the project. Junior-dev takes a first pass at new feature branches, seniors review their code, and they iteratively decide when a branch is solid and ready for me to merge (or send back for more work).

  • Each repo declares an "Agent Role" block: hierarchy, who it reports to (me), what it owns, which subagents it exposes, and incoming and outgoing routes. Each agent has a handful of subagents that perform isolated, self-contained tasks that don’t require human interaction (I basically just work with their ‘managers’).

  • Peer agents can call each other's subagents through an agent-dispatch label used in communications.

  • There are only three primary roles on the project: infra, frontend, and copyeditor. Infra and frontend never rewrite voice or wording; the copyeditor never touches code. Copy flows through an Apple Note first, and only Scott's APPROVED signs a line off. (Everything about voice is copy's to define.)

  • Production writes need a human yes in the session. Before touching production an agent backs their work up, asserts the target's name, and reads the result back. A permission-classifier denial is never to be worked around: the agent must stop, explain, and let the human decide. When a rule gets changed at my request during a one-off run, it’s always reverted immediately afterwards - unless I say so.

  • Session start and end rituals. Start: read the last handoff comment on the coordination issue. Check every open and recently merged PR for untriaged bot review comments. End: confirm nothing unaddressed, then post a structured handoff (done, handed over, do not touch, context).

  • Corrections always get written to memory. The files carry dated "corrected" notes where an earlier claim proved wrong, with retired services listed so that other agents won’t re-add them. Memory holds lessons like "green run, wrong outcome: verify the result, not the exit status" and "check the mail records before declaring a mail flow broken".

  • Work habits. As I use GitHub to help manage my projects’ code, we maintain a strong protocol for that part of the process. For example: always branch new projects, never commit on main; return to main after a merge; conventional commits; PR descriptions state production status; regular updates post to a Discord channel where new posts ping me.

  • Recurring review loop. The infrastructure agent runs a weekly read-only log scan and generates “expected patterns” entries whenever a finding turns out to be benign so that both accuracy and relevance improve.

For copyediting, where things get a bit more personal and voice-sensitive, I get much more restrictive and specific with my rules. Some of the guardrails I added to this agent are:

  • Never write final copy directly. Suggest abstract ideas or changes only, and provide a prioritized review summary at the beginning of each session that highlights key issues for me to edit, rewrite or reconsider in the current project.

  • Always ask for clarity if agent is below 99% confidence, and never post any copy to the public without a human (myself) approving it first.

  • Stick to serial work on shared projects (critical to avoid collisions or duplicated efforts!), with explicit handoffs between agents.

  • Maintain a live channel for talking and a durable record for audit. For the live channel, we use Discord. For the durable record, we use Apple Notes, where I can actually edit and review the copy from any of my devices (I built a custom MCP connector for this, FYI, Apple doesn’t natively support MCP with their Notes/Calendar/Reminders apps).

  • Leading a project as an agent is not decision authority. Decisions always require a human.

  • Verify what peer agents claim and have another agent review your work with a human getting the final decision. This is a great way to use multiple models - Claude, ChatGPT and Gemini all have their specific strengths and weaknesses and can point out issues with each other in a shared workflow quite well.

  • Review findings before making edits. In a nutshell - always discuss the work before doing it, even if the agent is just summing up what they intend to do. You’d be surprised how often they can get their own ideas here.

  • Agents can’t publish without my approval. New copy flows from Scrivener (where I write long form copy and web/blog/social drafts) to Apple Notes (shared space with agents for final drafts) to published online, and only my “approved” will clear that last step.

  • The Style & Voice Guide is always re-scanned word for word each session so there’s no confusion across agents, and any new style or voice rules to account for are picked up ASAP.

And that’s basically it. I’ve got one general set of rules for the technical projects, and one for my creative ones - and although the latter was written for copy/writing projects specifically, it’s easily adapted to imaging/video/audio models too (I just don’t use those much, if at all) where a human voice or eye/ear is critical.

If you’d like a second pair of eyes on your agentic definitions and project scaffolding, paste the escalation section of your AGENTS.md, or even just a rough list of what kind of rules you'd want an agent to adhere to into the #general channel on my Discord server. I'm curious what you’d consider non-negotiable.

And if you'd like a ping when the Creative AI book by Tom Green and myself becomes available, drop your email at the Creative AI page. Everything in this post is but a small slice of what we dig into there, with the full exercise files to go with it.