Working on large team codebases
Coding agents dazzle on small clean projects. The historic criticism was that they choke on a massive inherited codebase. That’s far less true now — but there are still rules of the road that keep a big team successful. Most will feel like common sense by this point; that’s a good sign.
These techniques lean on the foundational (“2025”) skills more than the wild new cloud tricks. On a fifty-person repo, discipline beats novelty.
01Why big codebases are different
On a small from-scratch project, an agent can hold the whole thing in its head, write the docs, and nail a zero-shot demo. Inheriting a huge codebase is harder: there is far more than fits in context, many people are changing it, and a careless instruction can do a lot of damage. Models have got much better at this since late last year — but the practices below are what keep it working.
021 — Invest in your agent docs
Your AGENTS.md / CLAUDE.md files are the single biggest lever. The trick is progressive disclosure: documentation at every level of the tree, revealed only as an agent enters that subdirectory.
/backend/market_data reads that folder’s doc and instantly knows the interface — no need to load the whole repo.Too much detail wastes context; too little and the wrong functions get called. Aim for tight docs that reflect the package’s interface. You can have Claude write them — but then eyeball them, do a couple of review rounds, and keep a step in your process for revising docs whenever code changes.
032 — Link docs, don’t embed them
When you reference a document with an @ tag, its entire contents get inserted into the outer document — usually not what you want, and a fast way to blow your context.
Dumps the whole file in
See @docs/market-data-spec.md pastes all 1,400 lines into context whether they are needed or not.
Let the agent choose
“Market-data spec (interface + providers): docs/market-data-spec.md.” The agent reads it only if the task needs it.
So structure docs to summarise, then point to detailed documents. That is how an agent navigates a big repo efficiently instead of drowning in it.
043 — One consistent team workflow
Pick one agreed process and rally the team around it. If everyone does it differently, you get a muddle — who files Jira tickets? who tags @claude? A single flow (say Jira → FeatureDev → PR, or GitHub issues tagged for Claude) means everyone knows the right way to order a new feature.
054 — Favour plugins & skills
Plugins first
Bring in the right plugins for your project — e.g. code-simplification, FeatureDev — and make them part of the shared process so everyone works the same way.
Domain skills
Write skills for how your project does things — your frameworks, your patterns (e.g. the right way to use your market-data API). They reinforce common standards across all agent work.
065 — Robust, not brittle, tests
A strong test suite has always mattered (80% coverage was long the gold standard). But do not fixate on the coverage percentage — LLMs will chase it and, to a fault, write heavily mocked, brittle tests that check every code path rather than real behaviour.
Tests that survive a re-implementation but fail when the logic actually breaks. Give feedback on your testing strategy (put it in AGENTS.md), and push back whenever you see a pile of over-mocked tests added “for the sake of testing” — exactly as you would for a human.
076 — The human owns quality
At the end of the day, you are accountable for the code. The agent is a tool. Build a culture with a human reviewer where the buck stops, and a firm habit of rejecting agent “slop”: over-long files, over-defensive code, anything painful to review.
It is now trivially easy to generate tons of code — and the burden shifts onto the human to review it all, which is hard work. So insist that agents write succinct code that doesn’t overwhelm the reviewer, and keep disciplined review in the loop.
087 — Bite-sized chunks
On a massive project, never tag Claude with “refactor the whole codebase” — you are asking for trouble. (You can get away with that on a tiny project like our capstone, not on a fifty-person repo.) Instead, let a human — or Claude Code itself — divide big work into small steps, each one independently specifiable, testable and human-reviewable, then hand those out one at a time.
09A quick assignment
Clone a popular open-source project from your own industry. Ask the agent to find a TODO in the code and do it, and see how it does. Build out a detailed AGENTS.md across the tree, try the FeatureDev plugin, and put these practices into play. As an anti-test, try “refactor/simplify everything” in a Ralph loop for ten iterations — and watch how un-pretty the result is. That contrast teaches you what works and what doesn’t.
✓ Key takeaways
- Progressive-disclosure docs at every subdirectory are the biggest lever — keep them tight and updated.
- Link to docs, don’t
@-embed them — let the agent decide what to read. - Agree on one team workflow; standardise with plugins and domain skills.
- Write robust tests, not brittle over-mocked ones; don’t worship coverage %.
- A human owns quality — reject slop, demand succinct code, and work in bite-sized chunks.