How to Create Context Documents for Your AI Agents

Most advice about AI agents stops at three words: give it context. Fine. In what form? How many files? Which agent reads which one?

Those questions matter more than they sound, because an agent starts every run cold. Anthropic's Claude Code documentation puts it plainly: "Each Claude Code session begins with a fresh context window." Whatever it knows about you on Tuesday morning is whatever you wrote down.

We've already covered why an agent needs context about you and why that context belongs in plain text. This one is the build.

What's the best way to create context documents for AI agents?

Write a small set of short, plain-text files, each with one job, and load each agent only the ones its work needs. Start with four: who you are, what's current, your voice, and the rules for the job. Use headings and rules you could check, test on a real task, and give every fact one home.

Document	What it holds	Which agents load it	How often it changes
Who you are	Role, values, how you make decisions	Nearly all of them	Rarely
What's current	Projects, deadlines, people in play	Any agent touching live work	Every few weeks
Voice	How you write, with real examples	Any agent that writes for you	Rarely
Job file	Steps, standing rules, and hard limits for one kind of work	Only the agent doing that job	When the job changes

If you're unsure what belongs in the first two, start here.

Why split your context into several documents?

Because every line has a cost.

Anthropic's guide to context engineering says the goal is the "smallest possible set of high-signal tokens" that gets you the outcome you want. The agent drafting your newsletter doesn't need your rules for chasing late invoices, and those rules compete for attention with the parts that matter. The Claude Code docs make the same point about instruction files: "Longer files consume more context and reduce adherence."

There's a second reason. Documents age at different speeds. Your values hold for years, and your deadlines hold for weeks. Keep them apart and you can refresh one without touching the other.

But here's the catch. Splitting only helps if the agent actually loads less. Claude Code lets a file import other files, and the docs are candid that imports "don't reduce its context cost, because imported files load together with the CLAUDE.md that imports them." A tidy folder loaded all at once is the same long file in a nicer coat.

So sort everything into two piles: what the agent needs on every run, and what it needs only sometimes. The first pile stays short and always loads. The second sits somewhere the agent can reach when the task calls for it. Claude Code's skills are built for exactly this: "a skill's body loads only when it's used, so long reference material costs almost nothing until you need it."

How do you write a document an agent can follow?

Five habits do most of the work.

Write rules you could check. Anthropic's advice is to make instructions "concrete enough to verify." Its example comes from code, "Use 2-space indentation" instead of "Format code properly," and the idea holds anywhere. "Be concise" is a wish. "Keep client replies under 100 words" is a rule, and you can tell at a glance whether it was followed.

Say why when it isn't obvious. A reason helps the agent handle the case you didn't foresee. Anthropic's prompting guide says explaining the motivation behind an instruction gives the model "more information about your goals." "Don't offer discounts, because my prices are published and the same for everyone" travels further than "don't offer discounts."

Show, don't describe. That same guide calls examples "one of the most reliable ways to steer Claude's output format, tone, and structure," and suggests three to five of them. So a voice document needs real paragraphs of yours, and this guide to giving AI your writing style shows how to pick them.

Point instead of pasting. Long material doesn't need to live in the document. Anthropic describes agents that keep "lightweight identifiers (file paths, stored queries, web links, etc.)" and pull the data in when they need it. If your agent can read files, one line will do: "Pricing lives in pricing.md. Check it before quoting."

Date the top. A date tells the agent, and you, that this was true as of a moment.

What does a set of context documents look like?

Here's a made-up example: an independent bookkeeper running two agents, one that sorts client email and one that drafts a monthly newsletter.

context/
  about-me.md           both agents
  current.md            both agents
  voice.md              both agents
  rules-inbox.md        inbox agent only
  rules-newsletter.md   newsletter agent only

Three shared files, two job files. Here's the inbox one:

# Inbox rules (updated 2026-11-04)

## Your job
Sort client email and draft replies. I approve every send.

## Standing rules
- Keep replies under 100 words and sign with my first name
- Tax-deadline questions go to the top of the queue
- For status questions, check current.md before you answer

## Never without asking
- Promise a delivery date
- Quote a price
- Give tax advice

## If you're unsure
Leave a one-line question for me. Don't guess.

Notice the last section, because it's the one people skip. Agents hit gaps constantly, and without a written instruction for that moment, they fill the gap with a confident guess.

The "never" list deserves a second layer too. Written rules guide an agent, and they don't physically stop it, so back the hard limits with the tool's own permission settings.

Where do these documents go in each tool?

The same files work everywhere. Only the door changes.

Tool	Always-loaded instructions	Longer reference material
Claude Code	CLAUDE.md, in a project or in your home folder for all projects	Skills, which load only when used
Coding agents that read AGENTS.md	AGENTS.md at the top of a project	Another AGENTS.md in a subfolder, where the closest file wins
Custom GPTs	The Instructions field	Knowledge files
Gemini Gems	The Gem's instructions	Knowledge files

If you run several agents in Claude Code, its subagents match this split neatly: each one "runs in its own context window with a custom system prompt," so each job file has a natural home. AGENTS.md is the portable option for coding work, and it's "just standard Markdown." For a Gem, Google's own tips ask for persona, task, context, and format, which map cleanly onto these documents.

These details shift, so check each tool's current docs before you set up. Either way, keep your originals in a folder you own and treat every tool as a copy, which also means moving to a new assistant is a paste.

How do you test and maintain them?

Give the agent a small, real task you already know the right answer to, then read what it did.

When it misses, fix the document instead of the output. Fix only the output and you'll fix it again tomorrow. Was the rule missing, was it buried, or did two rules collide? That last one is sneaky. The Claude Code docs warn that "if two instructions contradict each other, Claude may pick one arbitrarily."

Then give every fact one home. If a deadline appears in two files, one of them will eventually be wrong, and the agent won't know which. Keep it in current.md and let the job files point there. The rule matters even more once several people share the files, which is why team context needs a named owner.

After that, it's upkeep, and this guide to keeping context from going stale breaks the routine down layer by layer.

Where to start

Start with the shared layer, because every agent you add will read it. RUMO builds that layer as six short documents you own.

The first is the deepest: what you value, what you won't do, and how you make decisions. It's also where your agents' hard limits come from. The free Personal Constitution builder interviews you and drafts it in about thirty minutes.

Your agent will start cold tomorrow morning, and the morning after that. Leave it something worth reading.