Your AGENTS.md Was Written for a Worse Model: Auditing Prompt Debt
Old AGENTS.md rules outlive the model flaws they patched. Learn to spot prompt debt, trim skills into routers, set permissions and define done before the path.
This article is published in English.
Each line in an AGENTS.md file was usually added to patch a real failure. Models improve, the failure fades, and the rule stays behind. This is prompt debt: a workaround for one model's weakness promoted into permanent policy. The remedy is to give the file a narrower job, covering invariants, hidden constraints and permission boundaries, plus a definition of done.
Whenever a coding agent fails in a way people remember, someone adds a rule. It edits too much, so the file says to touch only what is necessary. It skips verification, so another line demands the full test suite every time. It changes a dependency unasked, so dependency changes become approval-only. It wanders around the repository, so the file spells out which documents to read first.
Each rule made sense when it was written. Then the model changed.
OLD: Read A → Edit B → Test C
NEW: Boundaries → Permissions → Definition of done
The newest generation of models, with GPT-6 Astra cited as the example, follows instructions noticeably better than earlier coding models, and that shifts the economics of prompting. A weak model might ignore an overbroad rule. A strong one may obey it to the letter. So an instruction written to offset an older model's flaws can turn into friction on a newer one. Upgrade the model without auditing its instructions and you carry the old weaknesses forward as standing policy inside the new system. The model got better, and the prompt stack stayed where it was.
Every failure leaves a fossil
Code accumulates technical debt when a quick local workaround hardens into a structural constraint. Instructions to agents gather debt in just the same manner.
Say an older coding model kept forgetting to check its changes, so someone added:
Always run the entire test suite after every change.
At the time that may have improved reliability. A year on, the model already picks out the affected tests and checks its own work, yet the instruction is still there. Now a one-word copy fix can set off twenty minutes of integration testing. Nothing is broken, and the agent is following the repository faithfully. The trouble is that an old behavioural patch has been promoted into lasting engineering policy.
That's prompt debt. A rule fixes a real problem, the problem goes away, and the rule lives on.
Skills cost something before they run
Skills look cheap, since their full contents load only when needed. The Agent Skills format describes progressive disclosure: a skill's name and description load first, and the complete file only when a task matches.
Yet before the model can pick a skill it has to recognise the options, so names and descriptions already compete for attention.
Imagine a repository with separate skills covering database migrations, PostgreSQL, schema design, persistence in the backend, query tuning and recovery. Each one carries a catch-all description that mentions SQL, migrations, schemas, queries, models and storage alike. Even a minor query tweak now looks relevant to half the library, so the agent has to classify before it can code.
The better pattern is still progressive disclosure, which OpenAI's skills documentation also argues for: detailed guidance lives in supporting files that arrive only when a task needs them.
database/
├── router.md
└── references/
├── migrations.md
├── performance.md
└── recovery.md
The root file needs just enough to route the task. A schema change leads to migrations.md, a slow query to performance.md, a restore or data loss to recovery.md. The detail hasn't been thrown away. It appears when the task gives the agent a reason to read it, which uses context better than loading operational knowledge on speculation.
AGENTS.md should hold what code can't explain
Repository-level instructions behave differently because they accompany the agent on nearly every task. Files like AGENTS.md load into a session as standing context, the way Claude Code's memory docs describe it, and that makes them costly when they're wrong, stale or needlessly broad.
A handy test: could a capable engineer looking at this repository work this out safely and cheaply? If so, the rule may not belong in AGENTS.md. If not, it probably does.
Compare two instructions. The first is repository-specific knowledge a model can't safely infer, so it stays:
KEEP
Generated API clients in /src/sdk are immutable.
Edit the generator source instead.
The second describes a workflow that may suit an architectural refactor but is overkill for a one-word typo fix, so it should move or go:
MOVE OR REMOVE
Before making any change:
1. Read ARCHITECTURE.md
2. Inspect the repository map
3. Review all package documentation
4. Identify downstream dependencies
Persistent instructions should mostly capture three things: invariants that must stay true, hidden constraints the codebase doesn't make obvious, and autonomy boundaries showing where the agent may proceed and where a human has to decide. That's a much smaller job than teaching a model how to do software engineering.
Better models make permission matter more
Stronger instruction following brings a subtler failure. The agent can honour your boundaries so carefully that it stops where you wanted it to carry on.
Suppose it implements a change and a local test affected by that change fails. It reports that auth_spec.ts is failing and asks whether it should fix it. The model knows how to repair the test. It doesn't know whether the repair falls inside the authority it was given. In that case a permission grant helps more than another procedure:
Local tests use disposable fixtures and have no production access.
Run affected tests, fix regressions caused by the requested change,
and rerun them without asking for approval at each step.
Those lines tell the agent three things it can't always infer: the environment is safe, remediation is in scope, and it may keep going. Boundaries drawn that way guide decisions better than sweeping bans like "never expand scope."
One way to split ownership in practice:
Needs human approval:
- Deleting production data.
- Changing authentication policy.
- Breaking a public API contract.
- Introducing a migration with operational risk.
The agent can usually continue with:
- Repairing a test that its own change broke.
- Updating nearby local types.
- Formatting files it modified.
- Rerunning affected local tests.
Consequence is what divides the lists. Neighbouring actions don't all deserve the same level of approval.
Define done before describing the path
Older prompts often describe the route:
Read these files.
Modify these modules.
Run this command.
Inspect this output.
Run these tests.
That can help when a workflow really is fragile, but a capable agent usually gains more from a clear endpoint. Compare the bare request
Implement the avatar endpoint.
with a version that adds a finish line:
Run the affected local tests, inspect the returned payload,
fix regressions caused by this change, and stop when the requested
behavior works or an external blocker requires a decision from me.
The second never says which file to open first. It says what finished looks like. That distinction grows as models gain enough judgment to choose their own path through a codebase. People set the destination and the dangerous edges, and the agent works out the route.
Keep the instruction hierarchy deliberate
A tidy setup has three separate layers. The first is the repository file:
AGENTS.md
↓
Repository invariants
Safety boundaries
Global permissions
The second holds skills:
Skills
↓
Specialized workflows
Loaded only when relevantTask prompt
↓
Immediate objective
Local constraints
Definition of done
The third is the task prompt itself. Problems begin once the layers bleed together: a one-off task workflow promoted into AGENTS.md, a global safety rule hidden inside a skill the model might never load, a skill that swells into an encyclopedia, or a task prompt restating repository knowledge the model has already. As models grow more capable, that duplication gets more expensive.
Audit prompt debt when the model changes
A model upgrade should trigger an instruction audit. That's not because every old instruction is wrong. It's because the assumptions behind them may have changed. A useful audit has four passes.
Take inventory of historical compensations
Collect everything that shapes agent behaviour:
AGENTS.md- skill descriptions
- skill bodies
- system-level repository prompts
- instructions repeated in task templates
For each rule, work out why it exists and which failure first pushed somebody to add it.
Tell real invariants from habit
Ask whether a capable engineer could safely and cheaply infer the rule from the repository. If they could, test whether it can go. If not, keep it. Rules touching production risk, generated artefacts, hidden infrastructure behaviour and non-obvious operational constraints deserve special care.
Turn heavy skills into routers
If one skill spans several workflows, shrink its entry point. Load migration instructions only for migrations and recovery procedures only when recovery is relevant. The specialised knowledge stays, without being forced into every nearby task.
Reread every prohibition for the risk behind it
Rules in the style of NEVER touch X, ALWAYS ask before Y or ONLY modify Z can still be right, but each should be checked against the consequence it was meant to prevent. Sometimes a better rule says X may be modified freely in local development but needs a question first in production, or that regressions from the agent's own change may be fixed while anything broader needs sign-off.
The goal isn't maximum autonomy. It's to spend human attention where the consequences justify it.
What should outlast every upgrade
Some instructions should survive however good models get. A deployment may need an undocumented legacy flag. Generated files may look editable even though edits get overwritten. A local environment may resemble production while using disposable fixtures. A migration may have to work across two running versions of an application. These carry high value because intelligence alone doesn't reliably reveal them.
The filter to use is information value. If the instruction captures something the model can't safely discover, keep it. If it only describes how an older model had to be walked through an ordinary engineering chore, reconsider. Having many instructions isn't what creates prompt debt. The debt sits in the ones whose reason for existing is gone.
The old playbook for coding agents was to spell out ever more of the route. As models improve, a simpler design works better: keep the invariants, set the permissions and state what done means. Leave the middle to the agent, and when a new model ships, go through the rules before writing more.