Step 1: Make each correction stick

An agent can learn during a conversation and still repeat the same mistake in the next one. The correction lived in the chat, not in the project.

The remedy is simple: make each useful correction outlive the session. Put project-specific guidance in the file your coding agent reads when it starts: AGENTS.md for Codex, CLAUDE.md for Claude Code, or the equivalent file for your tool. Keep the filename your agent actually supports; the principle is the same.

You’ve met this file before: it’s the team style guide, agreed once and referenced forever. The teammate reading it is now an agent.

Write down behavior, not wishes

A useful instruction tells the agent what to do at a recognizable moment:

Too vague	Useful next session
Be careful with verification.	Reproduce the bug and show the failure before changing code.
Keep changes focused.	Record unrelated findings; do not add them to the current diff.
Use the right vault folder.	Recurring topics go in `topics/`; `active/` is only for work with an endpoint.

The right rule is usually small. It records a real convention, command, stop condition, or check. It does not try to describe an ideal project that does not exist.

The Agent Workflow Failure List came from measured failures in real sessions. Use it as a menu: keep the entries you have actually encountered and ignore the rest.

Put each lesson at the right level

Not every lesson belongs in the project instruction file.

A project instruction records a fact or rule for this repository: how to run tests, where files belong, what must not change, or when the agent must stop.
A skill packages a repeatable workflow that should work across projects: reviewing prose, preparing a release, or checking a pull request against a failure list.
A small tool or hook handles the parts a program can check reliably: validating JSON, finding broken links, or running a linter after an edit.

This creates a useful path: a correction starts as a sentence, becomes a skill when the whole workflow repeats, and becomes code where judgment is no longer needed.

Skills do not need to be copied separately into every agent. The open-source skills CLI can install one managed skill for the agents you use:

npx skills add chronick/lemon-agent --global \
  --agent codex claude-code --skill agent-workflow-failure-list --yes

Use npx skills to discover, add, list, and update skills. Keep authored skill files in their source repository; let the installer manage the copies your agents load.

Try it

TRY IT Borrowed rules

you

Add a working agreements section to this project's agent instructions. I want the lessons from our work to survive future sessions.

agent

There are two ways to fill that section: with the genre's best practices, or with this project's actual history.

Pick the agent's next move, then see where it leads:

AI've written 22 agreements covering verification, testing, security, code style, error handling, documentation, and communication. The full best-practices canon. Comprehensive coverage from day one.

you

Three sessions later: you shipped a fix validated by a probe that never failed. Isn't that... agreement #4?

agent

It is. But #4 says "verify thoroughly before claiming success"; at the moment I ran the probe, that read as satisfied. Nothing in the sentence told me a clean first run was the failure case.

the baseline

Twenty-two borrowed generalities and none of them fired, because none was concrete enough to trigger at the moment it applied. A list the agent can't check is documentation, not a checklist.

BFirst, which failures have actually happened here? Tell me the last three times agent work bit you, and I'll encode exactly those, as behavior, one line each.

you

The fake-green fix last month. The test suite that called the paid embeddings API. And you keep restructuring files nobody asked about.

agent

Four gates, then: (1) show the failing probe before any fix; (2) grep for metered clients before the first test run; (3) touch only files the task names (list any others and ask); (4) a probe that's clean on first run is broken until proven otherwise. Each one names its trigger moment. Diff ready.

correct

Four gates, each purchased by a real incident and each stating the exact moment it applies, which is what makes them checkable by the agent and enforceable by you.

CThe most-starred agent ruleset on GitHub covers this well. I'll copy its 40 rules in verbatim. Battle-tested by thousands of users.

agent

Done. Note: rule 12 mandates a src/ layout, so I've queued a restructuring of your flat layout; rule 31 requires conventional commits, so I'll be rewriting commit style too.

you

Nobody asked for any of that. Half these rules are for a different kind of project.

plausible but wrong

Battle-tested by someone else's battles. A famous ruleset encodes its author's incidents and stack. Imported wholesale, it starts fights with your project's reality instead of preventing your failures.

Do it yourself

Think of the last correction you gave your agent twice.
Find the instruction file the agent actually reads for this project.
Add one plain sentence that would have prevented the second correction.
Ask the agent to show the diff. Remove anything aspirational or unrelated.

Five useful lines beat a page of generic advice. Add instructions when real work earns them, and prune rules that no longer describe the project.

Try it with your agent

Review this session for corrections, project conventions, and repeated
workflows that should survive the conversation. For each one, recommend one
home: this project's instruction file (AGENTS.md, CLAUDE.md, or the supported
equivalent), a reusable skill, or a deterministic tool or hook. Explain the
choice in one sentence. Draft only the smallest useful change, show me the
diff, and do not document conventions that the project does not yet follow.

Watch out

A policy dump: long generic instructions become wallpaper. Prefer a few rules tied to decisions this project actually makes.
Documentation ahead of reality: if the files and the instructions disagree, either change the project first or document the project as it is.
Chat-only learning: “I will remember” is not persistence. Put the lesson somewhere the next session will read or run it (AF-19).