Turn repeated corrections into rules, hooks, skills, and an independent review loop that improves the next session.
I stopped judging my coding agent setup by whether one session went well. The better test is what happens when a mistake happens again.
A correction in chat with the agent can fix the current task. If the same mistake comes back, the lesson needs somewhere more durable to live.
When rules for specific tasks live in agent config, the agent loads instructions it does not need for every other type of task. Piling exceptions into a skill or agent makes the important instructions harder for the agent to follow. A hook attached to the wrong event runs another check or review every time that event occurs, whether the work needs it or not.
The real job is deciding where each correction belongs.
I use six different places: agent config, skills for specific tasks, hooks, independent review agents, mistake logs backed by regression tests, and independent code review. All six are necessary in my setup, and each solves a different kind of failure.
That distinction lets the system improve without bloating every prompt, skill, and agent configuration.
Start with the correction, not the tool
When I correct an agent, I ask two questions before deciding where the correction belongs:
- What exactly failed?
- What change would keep it from happening again?
That second question matters. A rule can guide judgment. A hook can run a deterministic check or trigger agent review when a defined event occurs. A skill can bring in deep context for one kind of work. An independent review agent can examine the work from one role's perspective without sharing the producer's context. None of them can substitute for the others.
Suppose an agent edits a maintained reference document by appending a new section at the bottom, even though the document is supposed to keep the current decision at the top. You could correct the current edit in chat and move on. But that only fixes that one file one time.
The agent needs the same instruction every time it edits one of these documents: update the existing section at the top instead of appending a new one at the bottom. That belongs in the agent config or a skill for editing those specific types of documents.
The agent config or triggered skill puts that instruction in front of every agent that edits the file, including the next one in a fresh session.
Put facts every task needs in the agent config
Codex, Kimi Code, and Antigravity load repository instructions from AGENTS.md. Claude Code loads them from CLAUDE.md. Because that config is present throughout the session, it needs to contain only the facts and constraints an agent needs whenever it works in that repository.
Put only what every task needs in the agent config: the repository layout, build and test commands, project conventions, safety boundaries, and the checks that define done. These instructions establish how work happens in the repository before the task begins.
The temptation is to put every lesson here. That can work while the project and the instruction file are still small. Eventually the file becomes a junk drawer. The agent pays to load writing guidance during backend work, release procedure during research, and edge cases from jobs it may never perform.
Those files are always loaded, so I keep them very short, ideally under 60 lines and 4,000 characters. I ask one blunt question of each line: does every agent working in this repository need this before it can act safely? If only one or two kinds of task need it, I put it in a skill instead of the agent config.
Load a skill only for the task that needs it
A skill is for context and judgment that should appear only when the task calls for it.
Writing a technical article needs the business and marketing strategy behind it, plus voice examples, title standards, product claim limits, and a publication checklist. A coding task does not. Loading all of that into every session would waste context and bury the rules every task needs, making those rules harder for the agent to follow.
A skill can load automatically when its description matches the work, be invoked directly, or be referenced by an agent or another skill. The skill carries the detailed method without putting those instructions in every session's context.
It also tells the agent which files to change. If three articles open with implementation details before the reader knows why they matter, that is not three isolated sentence problems. That means the blog writing skill is missing an opening rule. Fix the skill once, add contrasting examples, and use the fixed version on the next draft.
Once loaded, the skill stays in the session context. That makes precise descriptions, narrow triggers, and compact instructions part of the design. When a skill grows, I use Caveman Compress to remove filler without dropping commands, paths, code, or technical terms.
Use hooks to run the right check or review deterministically
A hook runs an action when a defined event occurs in the agent harness.
If public copy must not contain a private path, a check can search for that path and stop the write. If a command would delete a broad directory, a hook can block it before execution. The agent does not need another paragraph explaining why. It needs a hard boundary.
A hook can also invoke an agent review. I use that when the trigger is deterministic but the question needs judgment and semantic analysis, such as whether an opening is compelling or comments are written well. The hook guarantees that the review runs at the point I chose. It does not make the reviewer right, so the result still needs evidence and audit.
Every hard block also needs an escape route. The hook should name the failed condition and tell the agent what it can do next. Otherwise the agent either stalls or starts looking for a way around the guardrail.
I only use a hard block when a machine can detect the violation reliably and the issue is serious enough to stop the work. A hook can trigger agent review without pretending the reviewer's judgment is deterministic.
Give an independent review agent one bounded role
Some work deserves an independent review agent because the job has a clear input, a narrow perspective, and an output that can be audited.
A fact checker can compare every public claim with canonical product documents. A technical reviewer can test whether an explanation preserves the real actor, action, and boundary. A skeptical buyer agent can identify the exact sentence where the argument stops being credible.
Separating those jobs protects the main working context and reduces the pressure for one agent to draft, defend, and approve the same artifact. It does not make the review agent right.
I require evidence with the verdict: the cited passage, the source that supports or contradicts it, the business cost, and the change that would resolve it. That work is reviewed independently and preserved so it can be audited later if necessary. A reviewer that returns polished opinions without receipts has not completed the job and is not verifiable.
A fact every agent needs belongs in the agent config. A repeatable review method belongs in a skill. The prompt for an independent review agent should contain one role's principles and rubric for judging one artifact.
Do not turn one failure into a universal law
A log can preserve a failure, but preserving it is not the same as learning from it.
Appending every failure to a file and loading it next session is not learning. One bad outcome becomes a permanent prohibition. The file grows around yesterday's accidents until nobody can explain the rules or make sense of their exceptions.
Repeated evidence must be observed before a failure becomes a permanent rule. I keep the exact evidence, identify the producer that allowed it, write the positive behavior I actually want, and decide whether the lesson generalizes beyond the incident.
If it does, I fix the owning rule, skill, agent, or hook. Then I keep a regression case that proves the original failure is rejected. I also keep a positive test case that must continue to pass.
That last part prevents crude fixes. If an agent writes one test around the wrong boundary, the answer is not “never use mocks.” A useful regression suite rejects the broken example without banning the valid cases the team still needs.
The system has learned only when the producer changes and a regression test proves the change rejects the bad case without rejecting the good one.
Decide where the correction belongs
Take the last correction you gave your coding agent and run it through this sequence:
-
Does every relevant session need this fact? Put it in
AGENTS.mdorCLAUDE.md. - Does one kind of task need deeper context or judgment? Put it in a skill for that kind of task and have it loaded when needed.
- Should a defined event run an exact check or invoke an agent review? Put that action in a hook. Reserve hard blocks for serious violations a machine can detect reliably.
- Does the job have a bounded input, question, output, and review rubric? Give it to an independent review agent, then audit the result.
- Is this a verified recurring failure? Fix the producer and preserve both a regression case and a positive test case after human review.
- Is the question whether generated code is actually correct? Send the result to an independent agent reviewer and a deterministic review tool. Neither is enough on its own.
If none of those fit, the correction may belong only to the current task. Not every preference deserves infrastructure.
Better generation does not remove the need for review
Rules, skills, hooks, and independent review agents improve how the code gets produced. They can make an agent more consistent, keep relevant context close, and encode a team's standards so that the required checks and reviews run at the right time.
They do not make the agent an impartial judge of its own output.
The same agent that chose an implementation has already committed to its assumptions. It can run tests and inspect its diff, but it is still reviewing the path it selected with the context that led it there. Reviewing its own work is useful, but it is neither independent nor repeatable. An agent will not always produce the same output given the same input.
That is where Mindrealm comes in. Mindrealm is the deterministic code reviewer for AI-generated code. After a coding agent finishes, Mindrealm reviews the generated code and returns concrete findings. Then it sends the findings back for the agent to fix, and reviews the changed code again. The review returns the same findings for the same code under the same rules every time.
Now the correction survives in the code, skill, hook, or regression test that owns it. And the next session benefits from it. Mindrealm reviews the code independently from the agent that wrote it. No LLM decides what gets flagged, so the findings are reproducible and give agent reviewers deterministic evidence to use alongside their own judgment.
Top comments (0)