Why Your AI Agent Config Falls Apart (and Nobody Notices)

You set it up in an afternoon. Gave it some context about the project, told it your naming conventions, pointed it at a few key files. It started helping straight away. Then you moved on, because you had actual work to do.

That was six months ago. The codebase has moved since. New patterns in, old ones deprecated, a module renamed, the testing approach changed. The agent knows none of it. It is still working from the context you gave it on day one. It mostly still works, just not as well as it should. And you have not noticed.

What good config actually contains

An agent can only apply judgement it has been given. What you put in sets the ceiling on what comes out. Every major tool has a first-class home for this: Claude Code reads a CLAUDE.md file at the start of every session, Cursor has Project Rules, and Copilot picks up repository custom instructions.

A config worth keeping covers four things:

• Project context. Not a README dump. Just enough to orient: what the codebase does, which parts are live, which are legacy. The mental map a new engineer builds in their first week.
• Conventions and constraints. How you name things, which patterns you follow, what you have decided not to do. The knowledge that lives in your head after a year on a project and nowhere in the code.
• What to avoid. Anti-patterns, deprecated approaches, the things that look reasonable from outside but are wrong here. This is the highest-leverage section, and most configs skip it. Without it, the agent reaches for sensible patterns that happen to be the exact ones your team walked away from.
• Your agent ecosystem. Not every task belongs to your general agent. Security, architecture, performance: each has specialists. A good setup knows which agent to reach for and when.

That third one, what to avoid, is the section most configs are missing. Here is what it looks like in practice:

# What to avoid
- Do not use class-based React components. Use hooks.
- Do not handle errors inline. Surface them to the error boundary at src/components/ErrorBoundary.tsx.
- Do not add index.ts barrel files. Import directly from the module file.
- Do not add console.log in committed code. Use the logger at src/lib/logger.ts.

Clean, current, no backstory. The agent does not need to know why. It needs to know what. Keep each rule to a single sentence: what not to do, and where the alternative lives.

The feedback loop

Every correction you give the agent is a config update waiting to happen. The catch is that corrections come with one specific case in mind, and it is easy to write a rule far broader than you meant.

Here is what drift looks like. You add a rule scoped to the auth module:

# Auth module
- Validate tokens before calling downstream services.

Six months on, the agent is validating tokens before every service call in the codebase, including internal ones that never touch auth, because the rule never said where it applied. The behaviour feels slightly off. You cannot quite trace why. The rule made perfect sense the day you wrote it.

This compounds. Each update was reasonable on its own. Together they start to contradict each other, and what the config tells the agent drifts from what you actually want. The agent is doing exactly what you told it. The trouble is that what you told it has piled up into something you no longer recognise.

So review is not only about keeping docs current. Ask the agent what it understands about your conventions. Ask which patterns it avoids. Read the answers as a diagnostic: rules applied too broadly, instructions that no longer fit the project. It can surface things you forgot you ever wrote. It goes both ways.

How to review it

A review does not take long. Three steps.

1. Interview before you edit. Ask the agent what it currently understands. What are the conventions? What does it think you want to avoid? The gaps in its answers tell you what needs updating. You are diagnosing, not guessing.
2. Bring in a specialist. Once you have updated it, do not self-review. Ask an agent with a different focus, security or architecture or performance, to read the config and flag gaps, over-broad rules, and the blind spots your general agent would wave through. Fresh context catches what you have stopped seeing.
3. Set a cadence. Once a month is a fair starting point. Put it in the calendar like a dependency audit. It does not take long.

This goes beyond config files. For anything high-stakes, an architecture decision or security-sensitive code, get a specialist to review it before you commit.

The multiplier

Two developers, same tool, same codebase. One gets noticeably more out of it. The difference is almost never the tool. It is the configuration: what context the agent has, how well the conventions are captured, whether the setup has been tended or left to rot.

For a tech lead, that gap multiplied across a team becomes a consistency problem. New people get different output depending on whose config they started from, or no config at all. Shared knowledge about the codebase ends up trapped in individual setups, or nowhere.

The developer getting more from the tool treats configuration as ongoing work. They review it. They interview the agent. They pull in specialists for the high-stakes calls. The gap is real and it compounds in both directions.

On your own, this is a Sunday-afternoon job: interview the agent, update what has drifted, bring in a specialist to check the result. On a team it changes shape. Who owns the shared config, what belongs in it, how the specialist agents fit the workflow, what happens when someone new joins. That is where it gets interesting.