Coding Agents at Team Scale

The previous posts in this series covered keeping your AGENTS.md lean, loading domain knowledge with Skills, and using infrastructure to enforce rules. All of those assume one thing: that someone on the team is keeping those files up to date.

Unfortunately, that’s not always the case. At the pace our industry moves, and as priorities shift within a team or company, it’s easy to forget to keep those files up to date. On a recent client project, the AGENTS.md referenced a library and one of its commands that had been deprecated weeks earlier (they had moved from Kysely to Drizzle). Every day, the agent kept running kysely migrate latest instead of the new Drizzle equivalent. It would then read the package.json, notice the error, and correct itself — so developers wouldn’t see the issue immediately and never thought to update the AGENTS.md. The file wasn’t particularly long, but it was already stale.

Context rots as the code and priorities change. That’s one of the problems at team scale, and this post is about the unglamorous, less talked about part that determines whether your agent setup actually works over time: maintenance.

The drift problem

Your AGENTS.md is probably already out of date and it’s not particularly your fault. The codebase just moved or someone renamed a package or a new service got added or the schema changed.

Agents make decisions based on what they read and the first thing they read is that file. If it’s stale, the decisions are stale too and the cost compounds over weeks. Every outdated instruction is a wrong turn that humans need to correct or additional inference costs.

Eventually you stop trusting the agent, you stop maintaining the file and the cycle goes on.

Ownership

The fix starts with someone specific owning the AGENTS.md, the same way a team would own a package in a monorepo. In most smaller teams, this can end up being the tech lead or a senior developer. This doesn’t mean nobody else can change it, it means that this person makes sure it stays current and leverages their complete vision of the project and of the company/business.

Over time, this can change as the codebase and the team grows. What they do is review changes, flag drift and push back when the file gets too bloated.

To enforce this, make the boundary explicit. On GitHub, the best way is a CODEOWNERS file so that changes to any AGENTS.md request a review from the right people:

# CODEOWNERS
**/AGENTS.md       @platform-team @tech-leads
.agents/skills/    @platform-team

You can also add CI checks: e.g. if the package.json file changes, the nearest AGENTS.md should be reviewed or confirmed as still accurate.

You can also have a check on the length of the AGENTS.md. In one of my projects, this wasn’t a hard rule, but some necessary friction so that developers would ask themselves whether what they’re adding is relevant and if it is, whether it should be split into a child file or moved into tooling¹.

Maintenance strategies

However, ownership alone isn’t enough without processes behind it. Here are a few things that have worked for me.

Hooks and reminders

Set up hooks that prompt updates when key files change. They’re just nudges so that someone with enough context can actually make the changes. A CI annotation that says “key files changed, consider reviewing AGENTS.md” is sometimes more than enough:

# .github/workflows/agents-md-check.yml
name: Check AGENTS.md freshness

on:
  pull_request:
    paths:
      - "package.json"
      - "packages/*/package.json"

jobs:
  check-freshness:
    steps:
      - uses: actions/checkout@v4

      - name: Warn if no AGENTS.md changed
        run: |
          changed_files="$(git diff --name-only origin/${{ github.base_ref }}...HEAD)"
          echo "$changed_files" | grep -Eq '(^|/)AGENTS\.md$' && exit 0
          echo "::warning::Key files changed but no AGENTS.md was updated. Consider reviewing agent context for drift."

Regular review cadence

Do it weekly or every other week, but not quarterly. Things are moving way too fast for that. You can pair it with something that already happens: dependency updates, sprint planning, sprint retrospectives or internal demos. Most of the time, five minutes is enough assuming you’re doing it regularly and consistently.

LLM audits

This is the one that has given me the best results: using an LLM and an agentic loop to audit your own AGENTS.md files against what the code actually looks like. What is pretty great is that it checks for actual staleness concretely. It looks in the AGENTS.md and checks whether the commands mentioned there still exist. It checks if the paths are still relevant and if new packages or services that are important are mentioned.

The most realistic way to do this is to run the audit on a schedule and open an issue when drift is detected. It’s a maintenance signal, and we still leave the actual update to a person.

The setup is pretty simple: a GitHub Action that runs on the main branch, gathers repository facts and sends them to a model with the right prompt. Here’s one of the prompts I’ve used as a starting point. For each team, you would iterate on it:

Review all AGENTS.md files in this repository for drift and bloat.

Definition of "stale" (use these checks):
- Commands mentioned in AGENTS.md that do not exist in package.json / Makefile / task runner configs.
- File paths or package names mentioned that no longer exist (moved/renamed/deleted).
- Stack/tool versions mentioned that conflict with version sources (lockfiles, .tool-versions, .nvmrc, Dockerfiles).
- Missing coverage: new workspace packages or services that exist but are not referenced.

For each AGENTS.md file:
1. List concrete findings (quote the exact line and explain what it conflicts with).
2. Propose a minimal fix (1-3 bullet points). Prefer deleting or moving text over adding more.
3. Enforce brevity: if a file is >50 lines, suggest what to cut or split into a child AGENTS.md.

For bigger teams, allocate budget for this the same way you would for faster CI runners. You can use cheaper and/or open source models. It’s a fairly simple task, but something that LLMs excel at.

What triggers drift

Triggers usually come from small changes over time, not from big rewrites. It’s adding a new script, updating a package, removing a package or renaming a service. Here’s a table of what usually starts drift and which guardrail you could attach to avoid it².

The first post was about keeping instructions lean. The second was about loading context on demand. The third was about enforcement through tools. This one is about making all of that work at team scale.

This has been a series about the best way of working with coding agents as I’ve seen it in the last year of working with teams trying to increase their productivity with these new tools. Every team’s setup is of course different. If you want help figuring out what works for yours, feel free to reach out or learn more about what I do.