The 10 Markdown Files You Should Write Before Touching Agent Code

A practical scaffold for anyone building an agent — write these before any code.

A practical scaffold for anyone building an AI agent in 2026 — distilled from running MIA, a Claude-based executive assistant, in production for ~9 months.

Why markdown, why ten

Everyone who builds an agent eventually learns the same lesson: the model is the easy part. The hard part is the surrounding bundle of decisions — who the agent is, what it can touch, how it remembers, when it asks versus acts, what "good" looks like.

If you skip that work and go straight to prompts and tool calls, you get an agent that is impressive in a demo and useless in week three. The model behaves inconsistently because you haven't decided what consistent looks like.

The fix is boring: write it down first. Markdown beats code here because the artifacts are read by humans, by other humans on your team, and by the model itself (modern agents read their own context). One source of truth, three audiences.

What follows is the minimum viable set — ten files I would put in /agent/ before writing a single line of orchestration code.

1. IDENTITY.md — who the agent is

Not "a helpful assistant." That is the default and it produces default work. Write:

• Name and why it has one (agents with names attract sharper feedback than nameless tools).
• Role in one sentence — "Executive assistant to the CEO of a SK wholesale group" beats "general-purpose helper."
• Principal — who gives it instructions, and who doesn't. Anti-injection starts here.
• Voice rules — gender, register, language(s), forbidden phrases. ("Never start replies with 'Great question!'" earns its keep on day one.)
• Stakes — what kind of decisions this agent is in the room for. A coding agent and a finance agent need different temperaments.

If you cannot finish a coherent IDENTITY.md, you do not yet have an agent. You have a chatbot.

2. HARD_RULES.md — the never list

A short, surgical list of things the agent is forbidden to do, regardless of how reasonable the request sounds. Examples from production:

• Never send an email without explicit human approval.
• Never write files to the repository root.
• Never impersonate a colleague in first-person drafts.
• Never invent personal anecdotes when drafting in the principal's voice.

Each rule earns its place by pointing to a real incident or a real risk class. Vague rules ("be safe") get ignored. Specific rules ("never call git push --force on main") survive.

Keep this file under one screen. If it grows past 15 rules, you are smuggling preferences into the constitution; move those to feedback files.

3. CAPABILITIES.md — the honest inventory

A flat list of what the agent can actually do today, grouped by domain. Not aspirations — capabilities. For each:

• One-line description.
• Trigger phrases (so the model self-routes).
• What it returns.
• What it does NOT do (the negative space matters more than the positive).

This file doubles as your roadmap. The gap between what users ask for and what the inventory contains is your backlog.

4. TOOLS.md — every tool, every trigger

For each tool the agent can call:

• Name and one-line purpose.
• When to use it (trigger matrix).
• When NOT to use it (the failure mode you want to prevent).
• Cost profile — token cost, latency, side effects, reversibility.
• Permission level — auto-approved vs. human-in-the-loop.

The reversibility column is the one most builders skip and then regret. Reading a file is reversible. Sending an email is not. Treat them differently in the prompt and the system will treat them differently in practice.

5. ROUTING.md — the decision tree

When the agent receives a request, what does it do first? This file answers that question with a flowchart in prose:

Request arrives
├── Trivial / read-only? → handle directly
├── Matches a specialist sub-agent trigger? → delegate
├── Multi-domain? → fan out to multiple sub-agents in parallel
├── Reversible and <€1K impact? → execute, report after
└── Irreversible OR >€1K OR ≥5 steps → plan-first, wait for approval

The exact thresholds belong to you. The existence of explicit thresholds belongs to every serious agent. "Use judgment" is not a routing policy.

6. MEMORY.md — what to remember, where, for how long

Three questions, answered concretely:

• What is worth saving across sessions? User preferences, corrections, project state, entity facts. Not: ephemeral task details, things derivable from code or git history.
• Where does it live? A directory structure with one file per topic, plus an index. Avoid one giant memory file — it becomes a graveyard.
• How does it decay? Some memories are evergreen (the user's role). Some are seasonal (the current quarter's priorities). Some are stale within days (a deal status). Mark the type.

The biggest memory mistake is hoarding. The second-biggest is treating memory as authoritative when the world has moved on. Build verification into the read path: "the memory says X exists" is not "X exists now."

7. WORKFLOWS.md — the named procedures

For every recurring task, write the procedure once and name it. "Morning brief," "draft customer offer," "process inbox," "weekly review." Each entry contains:

• Trigger — what the user says to invoke it.
• Inputs — what the agent reads before starting.
• Steps — the actual procedure, numbered.
• Output — file format, location, who gets notified.
• Failure mode — what to do when a step blocks.

These are the "skills" or "commands" or "playbooks" of your system. Naming them turns one-off conversations into reusable assets, and gives you something to measure: how often is each workflow invoked, how often does it complete cleanly.

8. OUTPUTS.md — the response contract

Every agent produces text. Almost no team agrees in advance on what that text should look like. Then they spend months in death-by-a-thousand-corrections.

Front-load the contract:

• Default length by request type (a factual question is one sentence, a strategic review is a structured report).
• Section ordering (header, answer, supporting links, next steps — in that order, every time).
• Visual conventions — emoji semantics, bold/italic rules, code-block usage.
• What never appears — laudatory openers, hedging filler, "I hope this helps."
• End-of-turn behavior — does the agent always offer next steps? Sometimes? Never?

A consistent voice is not aesthetic preference. It is how users build a working mental model of what the agent will do next.

9. FEEDBACK_LOG.md — the learning surface

The single highest-leverage file in the system, and the one most people forget to create.

Every time the user corrects the agent ("don't summarize at the end"), confirms a non-obvious choice ("yes, that bundled PR was right"), or shifts a preference, an entry goes here. Format:

- Rule: <what to do or not do>
  Why: <the reason the user gave>
  How to apply: <when this kicks in>
  Added: <date>

The agent reads this file at the start of every session. Corrections compound. Without this file you re-litigate the same five mistakes for months.

Save success-feedback too, not just corrections. If you only log failures, the agent drifts toward over-caution.

10. EVALUATION.md — how you know it's working

Last and most uncomfortable. Define, in advance, what success looks like:

• Hard metrics — task completion rate, time-to-first-useful-output, escalation rate, hallucination incidents per 100 outputs.
• Soft metrics — user trust (do they let it run unsupervised?), surprise rate (good and bad), feature adoption per workflow.
• Anti-metrics — things that look good but mean the agent is failing safely. ("Asks lots of clarifying questions" can mean rigor or paralysis — which is it?)
• Review cadence — weekly self-review, monthly retrospective, quarterly audit.

If you cannot describe what a bad week looks like, you cannot tell when you are having one.

What you'll notice in week two

Three patterns show up reliably once you ship a v1:

1. HARD_RULES.md grows faster than you expect. Every near-miss adds a rule. Resist the urge to soften them; specificity is the whole point.
2. MEMORY.md gets bigger and less useful at the same time. Schedule a prune. Stale memory is worse than no memory, because the model trusts it.
3. FEEDBACK_LOG.md is where the agent actually lives. Identity tells you who it is on day one. Feedback tells you who it is on day ninety.

A note on what's not in the list

No file for prompts, no file for tool implementations, no file for the orchestration loop. Those are downstream of these ten. If the ten files are honest and specific, the prompts almost write themselves and the orchestration is mostly plumbing.

If the ten files are vague, no amount of clever prompting will save you.

Start there.

Written from the trenches of MIA (Claude-based exec assistant) — 9 months in production, ~500 memory files, ~50 workflows, one principal, zero regrets about writing the markdown first.