The past two weeks changed how I think about agents.
I’d been building tools to manage context — snapshots that capture the actual state of a problem instead of relying on stale documentation, compression checkpoints that keep sessions clean as work progresses. Everything I was building circled the same insight: context is king. The more precise, the less generic, the better the output.
Then I looked at my agent library. Senior implementer. Junior implementer. Task classifier. Code reviewer. Generic domain experts, ready to deploy anywhere.
They were the odd ones out. I was solving context problems everywhere except in my agents.
That’s when it clicked: the same principle applies. If tuned context beats generic context for snapshots and checkpoints, it beats generic context for agents too.
The Human Analogy That Changed My Thinking
Take two engineers. Same seniority. Same tech stack expertise. One works on Project A, the other on Project B.
Ask the Project A engineer to review code from Project B. They can do it — they’re qualified. But they’ll be slower. They’ll miss context. They’ll flag things that aren’t actually problems and miss things that are.
This isn’t a skills gap. It’s a calibration gap.
The Project A engineer has internalized the conventions, the architecture decisions, the historical context of their codebase. They know why that weird pattern exists in the payment module. They know which “code smells” are actually intentional tradeoffs.
This knowledge doesn’t transfer. You earn it by working in the codebase.
”Just Inject Project Context” — Why That Doesn’t Work
The obvious objection: why not keep global agents and inject project-specific context at runtime?
Because context windows are limited. And it’s worse than just “limited” — performance degrades significantly as you approach capacity. With Claude Code, I’ve noticed a sharp drop around the 50% mark. The model starts losing track, missing details, producing worse outputs.
This means you have a working buffer — the usable portion of your context window. If you front-load that buffer with project-specific context for a generic agent, you’ve shrunk your working space before the agent even starts its task.
The math doesn’t work. You need that buffer for the actual work.
What Agents Actually Are
Here’s a reframe that changed how I think about this.
Agents aren’t personas. “Senior implementer with 100 years of experience” is not a useful agent design. That’s cargo cult prompting.
Agents are design tools. They have:
- Their own context window (subagents run in isolation)
- Specific instructions and methodology
- A defined workflow
- A narrow purpose
The key insight: subagents don’t pollute the main context. They do their work in their own space, then return results to the orchestrator. The orchestrator integrates only what’s relevant.
This is how you maintain longer sessions and tackle larger tasks. The work is distributed across context windows, not crammed into one.
Infrastructure stays generic — skills, commands, hooks, process frameworks. That’s how you work, and it applies everywhere. But agents that execute domain work — implementers, reviewers, documenters — need to know what you’re working on. Those get calibrated.
The Shift: Project-Specific Agents
I’m removing all my global agents.
Now, when I work on a project, agents emerge from the work itself. I build them with the same iterative, dogfooding, recursive process I use for everything else. A code reviewer for this project. An implementer who knows this codebase’s patterns.
They evolve with the project. New insight? Review the agent. Decide if it belongs in the context.
This is an attention dilution problem. Every piece of context competes for the model’s limited attention. Generic context is low-relevance signal — it’s not wrong, but it’s not this project. The more low-relevance context you add, the harder the model works to find what matters.
The Maintenance Objection
“But now you’re maintaining N agent configurations instead of one. How do cross-project learnings propagate?”
In practice, this dissolves. Creating an agent takes minutes. I could build a global command that scaffolds a project-specific agent from a template — start with the generic version, then tune it through use.
The tuning happens naturally. I use the agent, notice friction, adjust. Same dogfooding loop as everything else.
This works because I stay engaged with what the agents are doing. I understand the architecture, the system design, the decisions that shaped the codebase. When an agent drifts off course, my intuition catches it — that implicit knowledge from years of working in code. The agents work with me, not instead of me. If you’re deeply familiar with your projects, you can tune agents the same way.
The Deeper Principle
We’re mimicking how humans learn.
A senior engineer joining a new team doesn’t arrive fully productive. They spend weeks absorbing context before their expertise translates into effective contribution.
Global agents skip that learning phase and pay for it in every interaction.
Project-specific agents do the learning. They accumulate the context. They become genuine experts on the codebase they serve, not generic experts pretending to be.
I haven’t built benchmarks for this. I find them easy to bias — you end up measuring what you expect to find. The benchmark is the work itself. My gut says project-specific agents produce fewer blunders, less wasted back-and-forth. But it’s intuition, not data.
A future experiment: build evals that compare global vs. project-specific agents on the same tasks. Put them under the same magnifying glass. See if there are tangible, measurable differences. That would make a good follow-up.
For now, this is a snapshot of how I work today. I could be wrong. Next month I might write “Why I’m Going Back to Global Agents” because I discovered something that changes the calculus. That’s the point — these are raw reports from an evolving practice, not settled doctrine.
What I know: this approach is working for me right now. That’s enough to share it.
This is part of my ongoing exploration of agent calibration — the practice of tuning AI tools to specific contexts rather than accepting their generic defaults.