In an agent setup, instructions accumulate over time. A rule is added for every problem, a guardrail written for every error, and a year later you are left with a pile of text nobody reads end to end.
OpenAI's Eric Provencher argues in a developer note for newer models that this pile has become a cost item. Detailed instructions written for older models now get in the way of a more capable one.
This guide opens that note through four entrenched mistakes and says what to do about each. The core idea fits in one sentence: a more capable model wants less hand-holding. The advice was given for OpenAI's own model, but the problem is provider-independent; the same accumulation happens in every agent setup and the fix runs through the same place.
Why old instructions do harm
An instruction text is shaped by the weaknesses of the model it was written for. If the model skipped something, you added a rule making it mandatory; if it misread something, you wrote a step-by-step sequence.
When the model changes those rules do not disappear, but their reasons do. What remains is text constraining something the new model can already do.
- Rules accumulate and none get deleted.
- Every rule takes up room in the context window.
- Restrictive rules stop the model from choosing a better route.
- The source of the problem stays invisible, because each rule looks reasonable on its own.
Context is a budget
Underneath the trimming debate sits a measurable constraint: the context window is not infinite, and every line you put in it displaces another.
As instructions grow, the room left for the actual work — the task and the code — shrinks. The model sees less code and reads more rules, and the result inverts: rules meant to improve the work become the obstacle in front of it.
- Every mandatory reading rule pulls a whole document into the context.
- Long skill lists are reloaded on every call.
- Unused rules cost the same; there is no such thing as a dead rule.
- When the context fills up, the first thing lost is usually the task itself.
Mistake one: long skill descriptions
Provencher's first warning concerns skill definitions. Accumulated instructions consume context, and overly long descriptions make it harder for the model to pick the right skill.
The problem is not only the space. Long descriptions can get truncated, and a truncated description leads the model to select the wrong skill.
The recommended approach is plain: skill names and descriptions should clearly indicate when that skill applies. Not a long paragraph explaining what it does, but a short sentence saying when to use it.
A practical test: can someone reading a skill description tell in one pass when that skill should be called? If a person cannot, the model cannot either, and the selection drifts towards random.
Mistake two: mandatory reading on every change
Teams often set a rule for the agent: read the architecture, database and deployment docs before making any change.
The rule is well meant but unnecessary for simple fixes. Reading an architecture document to correct a typo spends context, time and money.
| Document | When to read it |
|---|---|
| Architecture note | When service boundaries are touched |
| Database docs | When the schema changes |
| Deployment docs | When the release flow changes |
| None of them | For a small bug fix |
So you are not banning the documents, you are making them conditional. Instead of "always read", the rule becomes "if you change this, read that".
The table also draws a boundary: reading a document is a cost item, not a safety measure. Making the model read a doc does not make the change correct; it only adds information to the context. Whether that information is needed depends on the type of change.
Mistake three: rigid approval rules
In older setups it made sense for an agent to ask approval before every risky step; its judgement was not trusted. The same rules backfire with a more capable model.
According to Provencher, rigid guardrails can cause Astra to stop work prematurely. Unable to get past the rule in front of it, the model treats an unfinished job as finished.
The fix is to grant explicit permission for safe operations: throwaway tests, single-use files and error fixes should not require repeated confirmation. The narrower the permission list, the more the agent stalls; the wider it is, the more work flows.
Where the balance sits is not obvious and varies by team. Asking approval for an operation that touches the production database is still right; asking approval to create and delete a temporary file only produces delay. What separates them is whether the operation is reversible.
Mistake four: not stating the completion condition
The fourth item may be the most useful. Rather than placing mid-task check-ins, define upfront when the job is done.
Write out all the required steps in advance: implement, test, verify, fix any errors. The agent reads that list as a completion condition and does not stop before finishing it.
- Mid-task check-ins create premature stopping points.
- With no completion condition written, the model sets its own threshold.
- Listing steps differs from sequencing them: one says what to do, the other how to do it.
- Putting the verification step on the list is, on its own, the single most useful item.
The order within that list matters too. The verification step belongs in the middle rather than at the end, so that when an error is found the fix step is still inside the list.
A concrete example
Seeing the four items in one example makes it easier. Picture a typical instruction given to a coding agent in its old form: "Before any change, read the architecture, database and deployment docs. Ask approval before every file change. Ask approval before running tests. Report when the change is done."
There are four separate problems in that text, and each looks reasonable alone. The trimmed version reads like this: "If you touch service boundaries read the architecture note; if you change the schema read the database doc. You may create and delete temporary test files. The job counts as done when these steps are complete: implement, test, verify, fix any errors."
- Mandatory reading became conditional rather than being removed.
- Safe operations were explicitly permitted.
- Mid-task check-ins were removed.
- The completion condition was defined in one sentence.
The second text is shorter than the first but more decisive. The difference is not the number of rules but which question they answer: the first says "how to work", the second says "when it is done".
The cost of spelling out every step
The idea underneath the note is this: detailed step-by-step sequences needlessly constrain the model's judgement on nuance and ambiguity.
That does not mean stop writing instructions. Saying what to do is necessary; writing out how to do it step by step is what stops the model from finding a better route.
When to do the trimming
The natural moment for this work is a model change. When you move to a new model, the instruction text you hold was written for the weaknesses of a model that no longer exists.
Rewriting the text from scratch at every upgrade is not realistic either. The practical path is to keep instructions annotated with the problem they were added against; when that problem disappears, removing the rule becomes easy.
Unannotated rules are the most dangerous. Because nobody remembers why one was added, nobody dares delete it, and the text keeps growing for years.
The order for trimming your own setup
Rather than rewriting the whole text in one sitting, it is safer to move while measuring.
- Shorten skill names and descriptions first; the most visible gain is there.
- Make mandatory reading rules conditional rather than deleting them.
- Review the approval list and explicitly release safe operations.
- Add a completion condition to every task and drop the mid-task check-ins.
After each step, rerun the same tasks and record the result. Whether the trimming worked can only be measured against a fixed set of tasks.
Do not change without measuring
The insidious part of trimming is that neither improvement nor regression shows up immediately. Remove a guardrail and the agent finishes most tasks faster; the problem only surfaces in a particular edge case.
That is why a fixed task set is necessary. Even a small list of fifteen tasks is enough; what matters is that the list does not change and that it is rerun after every trim.
- Success rate: how many tasks finished without human intervention.
- Premature stopping: in how many tasks the agent left the job half done and asked for approval.
- Context use: tokens spent per task.
- Wrong skill selection: in how many tasks an irrelevant skill was called.
The fourth item shows directly whether shortening skill descriptions worked. The other three measure the price of the guardrails you removed.
Where to stop
All of this advice rests on one assumption: that the judgement of the model you use is better than the rule you wrote. That is not true for every model.
If you work with a small, fast model, the guardrail you removed may genuinely be needed. Do the trimming when you change models and measure every time; this is a model-dependent setting, not a general rule. The same text producing different results on two models does not mean the instruction was badly written; it only shows that who it was written for matters.