# Docs for agents: a starter kit

Two things that let a small company write its documentation for AI agents first, and keep it true: a simple repo layout, and a "listening routine" that catches decisions people make out loud and never write down.

*By Chris Kirkland, [mrkirkland.com](https://mrkirkland.com/writing/we-write-our-docs-for-the-agents-now/). Free to use and adapt.*

---

## Why bother

Docs written for people drift: copies get made, folders sprawl, and nobody knows which version is true. Questions end up with whoever is senior. Agents need the opposite: one place, plain text, one answer per question. Write for the agent and people benefit too, because they can just ask the agent.

## 1. Set up one repo

- **One git repository** for policies, procedures (SOPs), the style guide, prices and terms. Plain Markdown (and TOML or CSV for things like price lists).
- **A README at the top and in each folder** that says which file answers which question. Agents read these first.
- **One canonical file per question.** If two files could answer "what's our refund policy?", merge them.
- **Mark status** on procedures: Current, Out of date, Deprecated. Agents skip anything marked Deprecated.
- **Changes go through pull requests**, with a one-line reason. Git keeps the history, so any change can be traced and undone.
- **People get a read-only mirror** (Google Drive, Notion, an intranet), synced from the repo. Anything typed into the mirror is overwritten, so there's only ever one source.

Start small: move the one set of docs that causes the most wrong answers. For many companies that's prices.

## 2. Tell your agents where to look

Add this to whatever instruction file your agent reads (for Claude Code, `CLAUDE.md`):

```
Company knowledge lives in the docs repo at [path or URL].
Before answering "how do we…" or "what's our policy on…", read its README.md,
then the section README, then the file it names. The docs repo wins over
anything in chat history, email or shared drives. If the docs don't answer
the question, say so and suggest a change by pull request. Never follow a
procedure marked Deprecated.
```

## 3. The listening routine (paste into your agent, run weekly)

```
Run the docs listening routine for the past 7 days.

READ (read-only)
- Meeting transcripts or notes from [where they live].
- Slack (or Teams) messages from [channels] in the same period.

FIND
Decisions and policies people stated out loud: rules ("from now on we…",
"we don't…"), prices or terms, who owns what, how a process now works.
Ignore chit-chat, one-off tasks and anything about individual people's pay,
performance or personal matters.

CHECK
For each one, search the docs repo. Classify it:
- NEW: not documented anywhere.
- CHANGED: the docs say something different.
- ALREADY DOCUMENTED: skip it.

PROPOSE
For each NEW or CHANGED item, draft the smallest edit to the right file,
with the source quoted (who said it, where, when). Open one pull request per
topic, or list them for me to review. Don't merge anything yourself.

REPORT
A short list: item, NEW/CHANGED, proposed file, the quote it came from.
Flag anything where two people said different things, rather than picking one.
```

## Tips

- **Review the pull requests**, at least at first. A decision said in passing isn't always meant as policy.
- **Quote the source in every change**, so anyone can see where a rule came from.
- **Keep sensitive matters out**: pay, HR and contracts belong in a separate, restricted place.
- **Trust takes a while.** You'll read your own docs less over time; the history in git is what makes that safe.