Pro tip: tell your AI agent to track things it thought would work but ended up needing different or additional steps. Kind of an after-action report or postmortem, but ongoing instead of just after a project.
One of my website deployments stopped because the server no longer had enough free space for its required backup. Old deployment archives were taking up nearly two gigabytes. Removing verified redundant copies let the work continue, but the useful result was the change to the deployment procedure: check capacity before transferring another archive, and account for the files left behind when the release is complete.
I want my AI development tools to carry that kind of experience into the next task. Otherwise, I get another capable assistant discovering the same problem, and the discovery gets less interesting each time. I’ve added instructions to record this friction: work that should have proceeded normally but needed an unexpected retry, a different tool, or intervention from me. The record includes what failed, the execution environment, what actually worked, and how much of the cause is known. It also asks the agent to consider a change that would prevent a repeat, verify it, and put the resulting guidance where future work will find it.
Recording friction can also reduce token use on recurring work. A short, verified procedure can replace another round of diagnosis and failed attempts. The reporting has a cost of its own, so the benefit depends on keeping instructions concise and consulting the relevant history. I haven’t taken any measurements of this though.
I use a global AGENTS.md for the general practice, project instructions for local requirements, and separate logs for the evidence. The instructions make recording and following up part of the task; the remedies live in scripts, tests, configuration, and working procedures.
You can use the same approach with other development agents. The place to install the instruction varies:
| Tool | Where to put the instruction |
|---|---|
| Codex | Global or project AGENTS.md; see its instruction-loading rules. |
| Claude Code | CLAUDE.md, or a supported AGENTS.md setup. Existing Claude instruction files can affect whether AGENTS.md loads; check the current documentation. |
| Antigravity | Workspace AGENTS.md or GEMINI.md, or its configured Rules. |
Other tools should have similar persistent project-instruction mechanisms; just confirm that it loads the instruction and can read the referenced log.
Here’s a compact version to adapt. Choose the log location first and replace docs/agent-friction.md if needed:
Before a workflow with known problems, consult relevant entries in
docs/agent-friction.md and use the verified procedure when applicable.
Record unexpected failures and recoveries briefly: date, task,
tool/environment, observed error, cause confidence, workaround,
and verification. Exclude secrets. Update the existing issue for a
recurrence. Expected approvals are not failures.
For recurring or consequential problems, propose a preventive change.
Apply small, reversible fixes within the task's existing authority;
verify them without weakening safeguards. Record the changed script,
test, or instruction and what the check actually established.
Keep proposed fixes, verified recoveries, and successful later reuse
distinct. Give unfinished follow-up an owner and a review trigger.
If the log is unwritable, save a local pending note and report its path.The distinction between recovery and prevention matters. In another website task, file-creation tests passed after a permissions repair, but an ordinary upload through a browser still produced an unreadable PDF. The test created a file directly in the destination directory. The real upload moved a temporary file there, preserving different permissions. After correcting that path, actual upload request tests passed on staging and production, and the operations and acceptance documents were amended to require that test. “Test uploads” became a specific, reproducible requirement.
Some improvements are smaller. My GitHub instructions direct the agent to use the already-authorized browser session for pull requests. Later task records show draft pull requests created and updated through that route without attempts to repair unrelated command-line authentication. That’s useful evidence of the preferred workflow being followed. It doesn’t tell me how many minutes it saved.
The log itself needs maintenance. Reviewing mine while writing this post uncovered a shared entry still proposing a backup remedy while the project log recorded an implemented solution. Some familiar mistakes also kept recurring. Writing a lesson down establishes that it was recorded; a later task has to show whether it was found and used. My next improvement was to give each issue a current status, an owner, a link to the actual fix, and a check on its next relevant use.
Keep the standing instruction short. Detailed incident history belongs in the log, and a repeatable mechanical check usually belongs in a script or test. Instructions guide the agent; permissions and executable checks still need to do their jobs.
Start with one repeated annoyance in your own workflow. Ask the agent to record the evidence, verify the recovery, and leave one concrete improvement for the next task. Then check whether the next task uses it.
—jhunterj