How to Organize Context for AI Agents When It Lives Everywhere
A five-step method to organize context for AI agents: inventory the sources, rank them by authority per question type, set the permission boundary, pick rules files or MCP, and measure with real questions.
TL;DR: You organize context for AI agents by deciding which source is authoritative for each kind of question and enforcing that at answer time. Consolidating files is optional. Inventory the sources, rank them by authority and freshness, set the permission boundary, deliver stable rules through rules files and live facts through MCP, and measure with 20 to 50 real questions. A context layer applying those rules turns scattered institutional context for coding agents into one answer.
How do you organize context for AI agents when it is spread across repos, tickets, wikis, and chat, and growing every day? You stop trying to move it and instead decide, per type of question, which source wins, then let retrieval apply that ranking the moment an agent asks. The rest of this guide makes that concrete: a five-step process, four honest ways to put the result in front of your coding agents, and a small test that shows whether the agent is pulling the right thing.
We have context all over the place and constantly being generated. How do we organize it so AI pulls the right stuff?#
Treat "organize" as ranking, not relocating. Anthropic's 2026 Agentic Coding Trends Report describes engineers handing agents the verifiable and repetitive work while keeping high-level design decisions and "anything requiring organizational context" for themselves (Anthropic, 2026). That split exists because the organizational context is unranked. The agent sees three candidate sources and no rule for choosing, so engineers keep the work.
Writing the rule down is the organizing act. For "how does this work today," code and merged PRs outrank docs, and docs outrank chat. For "why did we decide this," the ticket and the Slack thread outrank the doc, because the doc records the plan and the thread records the argument. Once those rules exist, where each source lives stops mattering.
What does "organize" mean when the context never stops changing?#
It means defining a context layer and giving it rules. DORA's 2026 ROI report lists "AI-accessible internal data" as one of seven capabilities that determine whether AI investment pays off, and argues the returns come from the organizational system around the tools (DORA, 2026; InfoQ, May 2026). "Accessible" has two halves: the agent can reach the data, and the agent knows which version to believe.
A context layer is the step between an agent and your sources that retrieves across all of them, applies your authority and freshness rules, enforces the asker's permissions, and returns a reconciled answer with citations. It cannot be a folder. A hand-curated wiki is a snapshot; the context layer stays correct while new PRs merge. We draw the line between that and a full context engine in a context layer is not a context engine.
The five-step method to organize context for AI agents#
Each step is a decision. The output is a one-page document plus a test set.
- Inventory the sources. List every system where engineering knowledge lands: repos, PR reviews, issue trackers, wikis, design docs, chat channels, incident tools, and the shared drives nobody admits to. For each, note who writes to it, how often it changes, and whether it has an API or an MCP server.
- Classify each source by freshness and authority, per question type. Write down three or four question types your engineers actually ask agents, then rank the sources for each. For "how does this work today," code and merged PRs beat docs, and docs beat chat. For "why did we decide this," tickets and Slack beat docs. For "what are our conventions," a maintained rules file beats everything. Where two sources conflict, the rule says which wins, and the answer should say a conflict existed.
- Decide the permission boundary. Choose whether the agent sees what the asking engineer can see, or some broader or narrower set, and write it down before connecting anything. The clean default is to mirror source-system permissions, so a private channel stays private when an agent reads it.
- Pick the delivery path for each class of context. Stable conventions go into rules files, because every agent reads them on every session. Live facts go through MCP or a context layer queried at answer time, because they change daily. The format choice is covered in CLAUDE.md vs AGENTS.md vs Cursor rules.
- Measure with a small question set. Collect 20 to 50 real questions, each with the answer a senior engineer would give and the source they would cite. Anthropic's engineering team recommends that scale for agent evals: "20-50 simple tasks drawn from real failures is a great start" (Anthropic, January 2026). Run the set monthly, grade on whether the agent cited the authoritative source, and treat regressions as bugs.
How do we get context into our coding agents in a consistent, quick way?#
Split it by rate of change, then respect the size limits the agents impose. Claude Code's docs say to target under 200 lines per CLAUDE.md because longer files reduce adherence, and warn that when two instructions contradict each other the model may pick one arbitrarily (Claude Code docs). Cursor recommends keeping rules under 500 lines (Cursor docs). Codex concatenates AGENTS.md files from the repo root down and stops at 32 KiB by default (OpenAI Codex docs). Copilot gives precedence to the nearest AGENTS.md in the directory tree (GitHub Docs).
Spend that budget carefully. A January 2026 study of 124 pull requests associated an AGENTS.md file with a 28.64% lower median runtime and 16.58% fewer output tokens (arXiv 2601.20404). A February 2026 study found context files did not generally improve task success while raising inference cost by over 20%, and that repository overviews in particular were not helpful (arXiv 2602.11988). A short file of non-obvious rules earns its place; a file that summarizes the repo does not. Everything that changes weekly should arrive through a live lookup over MCP, and the protocol is deliberately silent on the hard part: its architecture docs state that MCP "does not dictate how AI applications use LLMs or manage the provided context" (MCP architecture, 2026-07-28). Our guide to giving agents Slack, Jira, and Confluence knowledge covers making those sources reachable.
Our agents are islands. They don't share context across our systems. What tools solve this?#
Four kinds of tool, and the deciding question is who applies the ranking from step two: a human curator, a static file, the agent at query time, or a service that does it once for every agent.
| Option | What it organizes | Who applies the authority rules | Freshness | Permission boundary |
|---|---|---|---|---|
| Wiki consolidation | Documents moved into one place | A human curator, by hand | Decays after migration day | The wiki's own, rarely matching the sources |
| Rules files | Stable conventions, in-repo | The file author, once per edit | Frozen until the next commit | None; the file is plain text |
| RAG you build | Chunks from the sources you index | The agent, from whatever ranks highest | As fresh as your index jobs | Whatever filtering you build |
| Context engine | Reconciled answers across sources | The engine, per question, with rules you set | Continuous | Mirrors each source system per asker |
Wiki consolidation moves documents without ranking them. Rules files are nearly free and belong in every repo, but they cover only the slow-changing slice. A homegrown RAG pipeline can apply authority rules if you write them into the ranker, which tends to become a product of its own. A context engine applies the rules at answer time for every agent on the team. Governing which servers an agent may call is covered in centralizing context for coding agents; search tools that return links rather than answers are compared in tools that search Slack, GitHub, and Jira in one query.
Where does Unblocked fit in this method?#
Unblocked handles steps two through five at answer time, so the ranking is applied on every query. It connects GitHub, Slack, Confluence, Jira, Linear, and more, reconciles information across sources including ones that contradict each other, cites what it consulted, and mirrors each source's access controls per asker (Unblocked docs). Over MCP, Claude Code, Cursor, and Copilot all start from that same reconciled answer: institutional context for coding agents delivered as a lookup rather than a file. Engineers at UserTesting put the difference at 20 to 30 percent of their productivity when that context is in reach.
Unblocked used about a third of the tokens. Five thousand versus fifteen thousand. And the thing I thought was amazing is that Unblocked had the answer already. The rest was just my AI dressing it up. After that I opened up about twenty PRs, and now the first thing all of our skills do is ask Unblocked.
Charles Thompson — Engineering Manager, Reservation and Guest, Cloudbeds
"The first thing all of our skills do" is step four made concrete: one line in the rules file points every agent at the live lookup, and the rules file stays short.
Should we just consolidate everything into one wiki first?#
No. A consolidation project produces a corpus that is accurate on the day it ships and decays from there, because the sources keep changing and the copy does not. Claude Code's guidance on instruction files is blunt about what happens next: contradictory instructions get chosen between arbitrarily, so files need periodic review to remove outdated entries (Claude Code docs). Consolidation also strips step-two signal: a Slack thread's timestamp and author are part of what makes it authoritative on a "why" question, and a rewritten wiki page loses both. We covered the failure mode in rules file rot. Organize the ranking first; consolidate only the stable conventions that survive it.
How do we know the rules are working?#
Grade citations, not vibes. The 2026 Stack Overflow Developer Survey found that 93% of developers require source attribution to trust what AI gives them, and that 48% trust AI only when they can easily validate the answer (Stack Overflow, 2026; survey data). Grade your step-five question set the same way: did the agent cite the source your ranking calls authoritative, and did it flag conflicts? The baseline to beat is not zero. July 2026's Agent Retrieval Bench found that logged coding-agent trajectories missed every relevant repository file on 27 to 35 percent of samples, inside a single repo (arXiv 2607.24882). Anthropic's harness work for long-running agents used "structured artifacts to hand off context between sessions" for the same reason: an agent that loses state produces confident, wrong continuations (Anthropic, March 2026). When the agent hides a disagreement between sources, that is the first bug to chase; how context tools handle conflicts shows what good looks like.
What to do this week#
Run step one on Monday: a shared doc listing every source, who writes to it, and how fast it changes. Tuesday, write the ranking for your three most common question types and get two senior engineers to argue about it, because the argument is the documentation. Wednesday, pick the permission boundary and prune every rules file to the conventions that survive the ranking. Thursday, collect 20 real questions with the answer and source a senior engineer would give. Friday, run them through whatever the agent uses today and count the citations. Most teams find that organizing context for AI agents was never a filing problem; the missing piece was a written ranking. If the Friday count is bad and the questions span systems, put a context layer behind the agent, one that connects code, discussions, tickets, and docs in one query and applies the ranking you just wrote on every answer.
