Stop Your AI Coding Agent From Making the Same Mistake Twice: a CLAUDE.md / AGENTS.md Workflow That Actually Works

Stop Your AI Coding Agent From Making the Same Mistake Twice

If you use an AI coding agent for real work — Claude Code, Cursor, Codex, whatever — you already know the specific frustration I mean. You correct it. It says "You're absolutely right." Then two prompts later it does the exact same thing again. Wrong test runner. Wrong import style. Reformats a file you told it not to touch. Adds a dependency you don't want.

The instinct is to blame the model. The real problem is that the correction lived in your chat history, and chat history is not memory. Every fresh session, every context compaction, every new task — that correction is gone.

The fix is boring and it works: write the rule down in a file the agent reads on every run. Below is the workflow I actually use, what belongs in that file (and what absolutely does not), and how to verify it's working instead of assuming it is.

The file the agent reads every time

Most agents now support a project-root instruction file that gets injected into context automatically:

• Claude Code reads CLAUDE.md from the project root (and merges nested ones from subdirectories you're working in).
• Cursor uses .cursor/rules/*.mdc files (the older .cursorrules still works).
• The emerging cross-tool convention is AGENTS.md — a plain-markdown file that OpenAI's Codex, Cursor, and a growing list of tools have standardized on. It's just markdown; no schema to learn. (See agents.md and OpenAI's Codex docs.)

The mechanism is the same everywhere: the file's contents are prepended to the model's context on every task, so the rules are present before the model writes a single line. That's the whole trick. You're not fine-tuning anything — you're just refusing to rely on chat history for durable facts.

What actually belongs in it

Here's the part people get wrong. They dump a wishlist of aspirational values ("write clean, maintainable, well-documented code") and wonder why nothing changes. Vague virtues don't constrain behavior. Specific, testable rules do.

The test I use for every line: could the agent verify whether it followed this? If not, cut it or make it concrete.

A real, trimmed example from a Node project:

# Project Rules

## Commands
- Run tests: `node --test test/` (NOT jest — we removed it)
- Typecheck: `npm run check` — must pass before you say a task is done
- Never run `npm install <pkg>` without asking; propose the dep and wait

## Code style
- ESM only. `import`, never `require`.
- No default exports. Named exports only.
- Don't reformat files you didn't change. No drive-by prettier passes.

## Boundaries
- `src/legacy/` is frozen. Read it, don't edit it.
- Secrets live in `.env` (gitignored). Never hardcode keys or print them.

## Definition of done
- New behavior ships with a test that fails without the change.

Notice what's not there: no essay about our mission, no "be helpful," no restating what the language already does. Every line is a rule the model can check itself against. When I add a rule, it's almost always because the agent burned me on that exact thing once. The file is a scar log.

Turn corrections into commits

This is the habit that compounds. When the agent makes a mistake you've now corrected, don't just fix it in chat and move on — add the rule to the file in the same session. One line. Then it's permanent.

In Claude Code you can even do this without leaving the loop:

# add a rule to CLAUDE.md for the current dir
Append to CLAUDE.md: "Use `pnpm`, not npm — this repo has a pnpm-lock.yaml."

Over a couple of weeks the file stops being something you wrote once and becomes a living record of every trap in the codebase. New contributors (human or AI) inherit all of it for free.

Keep it short — context is a budget

Counterintuitive but important: a longer rules file is not a better one. Everything in CLAUDE.md / AGENTS.md is injected into context on every task, competing for attention with the actual code and your actual request. A 2,000-line manifesto dilutes the ten rules that matter.

My guideline: if it's over roughly 150–200 lines, something in there is either obvious, stale, or belongs in real documentation instead. Prune it like code. When a rule stops being violated for a month, I sometimes remove it and see if the habit stuck.

For anything genuinely large or reference-heavy — an architecture overview, an API contract — put it in a normal doc and reference the path from the rules file, so the agent pulls it only when relevant instead of on every keystroke.

Verify it's actually working

Don't trust that the file is being read. Test it. Add a deliberately checkable rule near the top:

- When you start a task, first state which command you'll use to run tests.

Then start a fresh session and give it any small task. If it opens by naming your test command, the file is in context and being honored. If it doesn't, check that the filename and location are exactly what your tool expects (CLAUDE.md at project root, AGENTS.md at root, .cursor/rules/ for Cursor) — a misplaced or misnamed file is silently ignored, which is the most common reason people conclude "this doesn't work."

Why this beats the alternatives

You could paste your rules into every prompt — but you won't, consistently, and the moment you forget is the moment it breaks. You could use a big system prompt — but that's per-tool and doesn't travel with the repo or show up in code review. A committed rules file is version-controlled, diffable, reviewable, and shared across your whole team and every agent that opens the project. It's the difference between correcting an agent and configuring one.

The whole thing in four steps

1. Create CLAUDE.md (or AGENTS.md) at your project root.
2. Write only specific, self-checkable rules — commands, style constraints, hard boundaries, definition of done.
3. Every time the agent burns you, add one line in the same session. Keep it short; prune stale rules.
4. Verify with a fresh session and a checkable rule before you trust it.

None of this is clever. That's why it works. The agents keep getting smarter, but they still can't remember what you told them yesterday unless you write it down where they'll actually read it.

---

Sources: agents.md (AGENTS.md convention); Anthropic — Claude Code memory / CLAUDE.md docs; Cursor rules documentation. Filenames and mechanisms verified against these as of mid-2026; confirm against your tool's current docs, since conventions are still shifting.