Every few years our industry rediscovers that humans can only hold so much in their heads, slaps a new label on it, and sells it back to us. Microservices. Platform engineering. Modular monoliths. Team Topologies. And now: context engineering.
The label is new. The problem isn't.
Throughout my career I've talked a lot about cognitive load. Mostly in two contexts: platform engineering, and migrations to microservices or modular monoliths. The questions customers asked me back then are basically the same questions they ask me now about AI coding agents. Same shape, same root cause, same family of answers. This post is about that link, and what I think you should do once you see it.
Three questions, one answer
Over the years, three questions have shown up over and over in slightly different costumes:
"I can't keep all the infrastructure for my app in my head. Can someone else take care of it and streamline it for me?"
The answer was platform engineering.
"The codebase is too big and I can't realistically tell what the blast radius of my change is. How do I fix that?"
The answer was revisiting the architecture — usually toward a modular monolith or microservices, depending on how brave the org was feeling that quarter.
"My AI coding agent's results keep getting worse on our large codebase. What's going on?"
The answer is the same. Reduce cognitive load. Just not for a human this time, but for an agent.
I want to be upfront here: I'm optimistic about AI being infused into the way we work. I just don't think it's magic, and I'm not going to pretend it is. We still have to do the boring structural work. If anything, the agents make the cost of not doing it more obvious, faster.
Why "more context" makes agents dumber
The instinct, when an agent struggles on a big codebase, is to give it more. More files. More instructions. A bigger context window. Model providers keep advertising one-million-token windows like they're a feature you're supposed to use.
You're not. A 1M-token window is a ceiling, not a target.
Chroma's Context Rot research tested 18 frontier models and found every single one degrades as input length grows, and not just near the limit. A 1M-token window still rots at 50K tokens.1 Anthropic's own writing on context engineering points the same way: the discipline isn't filling the window, it's curating what goes in.2
This shouldn't be surprising, because we already know what it looks like in humans. My brain has more than enough capacity for "where are my keys?" right up until the point where I'm running late, mentally rehearsing a meeting, and trying to remember whether I packed my laptop charger. Then the keys vanish, even though they are in my hand. The capacity didn't shrink, or at least I like to tell myself that. The signal just got buried under the rest of the mess.
LLMs do the same thing. Bigger context isn't more attention. It's more noise competing for the same attention budget. It's like finding a needle in a haystack, where the haystack could be gigantic.
Onboarding, with one twist
The clearest way I've found to explain this to customers is through onboarding. Apply the same ceremonies to an agent as you would to a new hire.
You wouldn't drop a new engineer into a 500k-line codebase and expect them to be productive on day one. You'd walk them through the architecture, point at the classes that matter, explain why the deployment pipeline has that one weird step nobody likes to touch, tell them whether you do GitFlow or trunk-based, show them how to run a smoke test. After a month or two they're useful. After a year they're load-bearing.
Coding agents need exactly the same treatment. The init commands in Claude Code and GitHub Copilot exist precisely to bootstrap this. I used to skip this, but now it's the first thing I do whenever I see it hasn't been run yet. And honestly, that's tip number one: just run init. It's free. But there's one twist that matters more than people give it credit for:
Every session is day one for an agent.
Humans accumulate context over months and forget the irrelevant bits. Agents start fresh every conversation, and forget nothing you give them, including all the noise. So the goal isn't "teach the agent everything you'd teach a new hire." It's "codify the minimum useful onboarding and make it scoped, retrievable, and trustworthy." Basically, it's your onboarding runbook for whenever you get a new developer, but then in markdown files in your repository.
After init, go further. Split your instructions by what part of the system the agent is touching. Frontend gets its own markdown file. Pipelines get theirs. Each one tells the agent only what it needs for that job, plus how to smoke-test, plus how you ship.
This is also where Team Topologies stops being a name-drop and starts being load-bearing. One of my takeaways from Skelton and Pais's book is that organisations should be designed around cognitive load and explicit team interaction patterns.3 The same shape works for an agent fleet, and a recent QCon London talk reframes Team Topologies as "infrastructure for agency" with AI for exactly this reason.4 If you set up sub-agents by domain, you're not just managing tokens. You're running Conway's Law inside your tooling. The shape of your agent team will mirror, and reinforce, the shape of your codebase. Whether that's a good thing depends on how you feel about your current codebase, which is a separate, albeit crucial, conversation.
Claude Code's subagents5 and GitHub Copilot's /fleet6 both exist for this scoping. You could ask your coding agent to spin up one or more subagents which will take care of part of the problem you posed to your coding agent. For example, if I would want to introduce a new feature, I'd specify it together with my coding agent, before I let the coding agent take point in delegating it to a frontend, backend and documentation subagent to take care of it. They will have their specific instructions on how to deal with what code base they find, not pollute their context window with other concerns.
Five structural moves that pay back immediately
Tools help. But before you reach for tools, the cheapest wins are structural. Things you can do this afternoon without installing anything.
- Scope your AGENTS.md / CLAUDE.md per directory, not per repo. A single root file becomes its own monolith of cognitive load. Place a small, focused file beside the code it describes. Agents will pick up the nearest one when they're working there.
- Write a per-package README aimed at a stranger. Not architecture diagrams. Five sentences: what this package owns, what it doesn't, how to test it, the one weird thing. Humans as well as agents will benefit whenever they dive into that specific directory, package, or hidden away bit of vital business logic.
- Make module boundaries enforceable, not aspirational. Lint rules, dependency checks, anything that fails CI when someone reaches across a boundary. Agents respect boundaries that are enforced. They happily ignore ones that are merely documented. So do humans, in my experience.
- Treat navigation cost as a real metric. Fredrik Claesson, a developer at Mews, wrote recently that the cost of an AI coding agent isn't what it reads once it's in the right place, it's how many wrong files it touched on the way there.7 "How many files does the agent open before it finds the right one?" is the new "how long does onboarding take?" Track it informally and you'll start noticing where your codebase is hostile to navigation.
- Codify the corrections. When an agent makes the same wrong assumption twice, that's a missing line in your AGENTS.md, not a personality flaw. Every code-review correction is a permanent learning if you write it down once. Make it a habit to constantly update your onboarding documentation with new decisions and new features, and stay critical.
None of this is new advice for humans. That's the point.
A word about token squeeze
I want to briefly justify why being efficient with context matters beyond quality. The AI industry is changing fast, and lately we've all felt a bit of a squeeze. Token limits getting tighter, certain subscription tiers no longer including coding agents. This is because demand is basically exploding, and we are drowning in our own success. There aren't enough GPUs on the planet right now to let every engineer use this technology however they want. That's a whole other topic, but it does mean that most customers I talk to are not just asking "how do I make my agent better." They're also asking "how do I make my agent cheaper." Good news is, the answer is largely the same. Smaller, scoped, well-curated context produces better results and burns fewer tokens.
Tools I actually use
I want to flag four that earn their keep, especially the less well-known ones.
Squad: built by a colleague of mine. Bootstraps a repo with multiple scoped instruction files instead of one mega-prompt. You define a virtual team: Obi-Wan does frontend, R2-D2 owns CI/CD. Each team member gets only the context they need. It's the structural advice from the previous section, packaged. I use it as a default on most of my repositories now. I redefine my team frequently, and I tweak the specifics of each team member's context more than once per coding session. It also comes with rituals much akin to the scrum rituals we are used to, also to check on the quality of the documentation.
Superpowers: gives you a structured spec-then-implement loop. You describe the feature, review the spec (which forces ownership and stops you from generating slop), then sub-agents implement against it. Free documentation and structure for your agent's onboarding, with the ability to inspect past decision-making. Your main session becomes the orchestrator, not the implementer, which keeps your context window clean and the work focused. I tend to use the brainstorming of this, and then hand it over to the squad mention above.
Context Mode: an MCP server that compresses tool-call output before it hits the context window. Raw tool calls are sandboxed; only the fields the agent declared up-front make it through. As a result we do not bloat our context window, which MCP servers could very much do. A local SQLite store keeps anything the agent decides is worth retaining across the session. Context rot mitigation by construction, basically.
GitHub Copilot Spaces: the most underused thing in Copilot in my eyes. Of course I am a bit biased, but I see very few organizations utilize spaces. Org-wide, centrally maintained context: a shared frontend style guide, an architectural decision log, anything you want every team's agent to follow. This is crucial even without AI Agents, and Spaces is very agent-friendly. The single source of truth for "this is how we do it." If you're in a big org and you're not using this yet, start there.
There's a lot more out there, obviously. These are just the ones I keep reaching for.
What this is really about
The AI industry will keep shipping bigger context windows, faster models, more autonomous agents. None of that erases the underlying constraint, because the constraint isn't really about the model. It's about the system you're asking it to reason over. Ultimately, this is an organizational problem, as Conway's law suggests.
If our codebases keep growing and we do not define boundaries in our organizations through concepts like platform engineering and software architectures like microservices, we will keep failing to become more agile and reactive to an ever-evolving world, even with AI.
Sources and inspiration:
- Martin Fowler's site, Context Engineering for Coding Agents
- Packmind, Context engineering for large codebases: a practical guide
- 1Password, What we learned using AI agents to refactor a monolith
- Foote & Yoder, Big Ball of Mud (original paper)
Footnotes
-
Hong et al., Context Rot: How Increasing Input Tokens Impacts LLM Performance, Chroma Research. ↩
-
Anthropic, Effective context engineering for AI agents. ↩
-
Skelton & Pais, Team Cognitive Load, IT Revolution. ↩
-
InfoQ, Team Topologies as 'Infrastructure for Agency' with AI, QCon London 2026. ↩
-
Anthropic, Claude Code sub-agents. ↩
-
GitHub, Running tasks in parallel with the /fleet command. ↩
-
Mews Developers, Navigation is the Real Cost of AI Coding Agents. ↩