AI Coding Agents: How a Fool-Me List Prevents Repeat Mistakes

An AI coding agent can repeatedly make the same mistake unless you give it a structured way to remember and avoid those errors. A “fool-me list� is a simple text file or project document where you record every mistake the agent has made, why it happened, and the exact instruction that would have prevented it. By feeding this list back into the agent’s context at the start of each session, you stop the cycle of repeating the same costly errors.

Formula

The calculator above estimates the total time you lose to a recurring mistake. It uses two inputs: the average time spent on the mistake each time it occurs (t, in minutes) and the number of times the mistake has been repeated (n, a count). The total wasted time is simply the product:

Total wasted minutes = t × n

The second output converts that into hours by dividing by 60. This gives you a concrete number to justify the effort of building and maintaining a fool-me list.

Worked Example

Suppose you spent 30 minutes debugging a mistake the agent made, and it has happened 3 times. Using the default values:

• Total wasted minutes = 30 × 3 = 90 minutes
• Total wasted hours = 90 ÷ 60 = 1.5 hours

That is 1.5 hours you could have saved by adding one line to your fool-me list.

What Is a Fool-Me List?

A fool-me list is a living document that records every mistake an AI coding agent has made in your project. It is not a generic “best practices� file—it is specific to your codebase, your tools, and the particular ways the agent has failed you. Each entry typically contains:

• The mistake: What the agent did wrong (e.g., “used the wrong API endpoint�).
• The context: Where and when it happened (e.g., “in the payment module, during the refactor�).
• The correct behavior: What it should have done instead.
• The prevention instruction: A clear, direct command to include in future prompts (e.g., “Always check the API version before writing client code�).

The list is usually stored as a plain text file (like FOOL_ME.md) in the project root, and its contents are injected into the agent’s context at the start of every session. Some developers also use it as a checklist for code review.

Why Agents Repeat Mistakes

AI coding agents are stateless by default—they do not remember previous conversations unless you explicitly provide that context. Each new session starts fresh, with no memory of the bug you fixed yesterday or the pattern you told it to avoid last week. This is why the same mistake can appear over and over: the agent has no way to learn from its past errors unless you teach it.

Another reason is that agents optimize for the immediate request, not for long-term project consistency. If you ask it to “add a new feature,� it will happily write code that follows the current request, even if it contradicts a convention you established earlier. A fool-me list acts as a persistent memory that overrides this forgetfulness.

How to Build and Use a Fool-Me List

Creating an effective fool-me list takes a little discipline, but the payoff is immediate. Here is a practical workflow:

1. Start a new file named FOOL_ME.md in your project root. Add a header explaining its purpose.
2. Add an entry every time the agent makes a mistake—even small ones. Write the mistake, the context, and the exact instruction that would have prevented it.
3. At the start of each session, paste the entire contents of the file into your first prompt. Or, if your tool supports it, set it as a “system prompt� or “project instructions� so it is always loaded.
4. Review and prune the list periodically. Remove entries that are no longer relevant, and merge similar ones to keep the list short and focused.
5. Use the list in code review: before accepting any agent-generated code, check it against the list to see if any known mistake patterns are present.

The key is to be specific. Instead of “Don’t break the build,� write “Before committing, run npm test and ensure all tests pass.� The more concrete the instruction, the more likely the agent will follow it.

Common Problems and How to Avoid Them

While the concept is simple, there are pitfalls that can make a fool-me list ineffective:

• Too long: If the list grows beyond a few pages, the agent may ignore it or lose focus. Keep it under 50 entries, and prioritize the most costly mistakes.
• Vague entries: “Be careful with the database� is useless. Instead, write “Always use parameterized queries—never concatenate user input into SQL.�
• Not updating: A static list becomes stale. Update it after every mistake, and remove entries that no longer apply.
• Not injecting it: Creating the file but forgetting to include it in prompts defeats the purpose. Make it part of your workflow, not an afterthought.

Another common issue is that the agent might follow the list too literally, leading to over-correction. For example, if you wrote “Never use any in TypeScript,� the agent might avoid it even when it is the pragmatic choice. Add context to each entry, such as “except when parsing unknown API responses.�

Comparing Fool-Me Lists to Other Approaches

Fool-me lists are not the only way to prevent repeat mistakes. Here is how they compare to other common strategies:

• Fine-tuning the model: This requires significant technical expertise and resources, and it only works for the specific model you train. A fool-me list is cheaper and model-agnostic.
• Custom instructions in the UI: Many AI tools let you set persistent instructions, but these are often global and not project-specific. A fool-me list can be tailored to each codebase.
• Automated tests: Tests catch mistakes after they happen, but they do not prevent the agent from making them in the first place. A fool-me list reduces the number of iterations needed.
• Manual code review: Reviewing every line of agent-generated code is time-consuming. A fool-me list helps you focus on the areas where the agent has failed before.

The best approach is usually a combination: use a fool-me list to guide the agent, and rely on tests and review to catch what slips through.

Costs and Benefits

The cost of maintaining a fool-me list is small: a few minutes per mistake to write an entry, and a few seconds per session to paste it. The benefits are substantial: fewer debugging cycles, less frustration, and more consistent code. The calculator at the top of this page helps you quantify the time saved. For example, if a mistake that takes 30 minutes to fix has happened 3 times, that is 1.5 hours lost. If the list prevents just one repetition, it has already paid for itself.

There is also a cognitive benefit: writing down what went wrong forces you to understand the root cause, which improves your own understanding of the codebase. And when you share the list with teammates, everyone benefits from the accumulated knowledge.

Frequently Asked Questions

How long should my fool-me list be?

Keep it under 50 entries. If it gets longer, prune aggressively—merge similar mistakes and remove ones that are no longer relevant. A long list dilutes the agent’s attention, so focus on the mistakes that cost you the most time or cause the most damage.

Can I use a fool-me list with any AI coding agent?

Yes, as long as you can inject text into the agent’s context. Most tools allow you to paste text into the prompt, and many support “project instructions� or “system prompts� that are automatically loaded. Even if your tool does not support automatic loading, you can copy and paste the list at the start of each session.

What if the agent ignores the list?

If the agent consistently ignores a specific instruction, try rephrasing it more clearly or breaking it into smaller steps. Also, check that the instruction is not contradictory with other parts of the prompt. If it still fails, add a test that catches the mistake, so at least you catch it early.

Should I include positive instructions too?

Yes, but keep them separate. A fool-me list is for mistakes, but you can have a companion “do this� list for conventions you want the agent to follow. For example, “Always use TypeScript strict mode� or “Use the repository pattern for data access.�

How do I get my team to use the same list?

Store the list in a shared location, like a repository file or a wiki page, and make it part of your team’s definition of done. Encourage everyone to add entries when they see a mistake, and review the list together during retrospectives.

Is a fool-me list the same as a “lessons learned� document?

Not quite. A lessons-learned document is usually written at the end of a project and is often too long to be useful. A fool-me list is short, actionable, and actively used in every session. It is more like a living checklist than a report.

Related

• Generate Changelog from Git History
• Sync Mac Desktop and Documents with Dropbox
• Dig Ruby Guide: How to Use It

in t | Time spent on mistake (min) | min | 30 | 0
in n | Times mistake repeated | count | 3 | 1
out cost | Total wasted minutes | min | t * n | 0
out waste | Wasted hours | h | (t * n) / 60 | 1