The /add-mistake Command: Teaching Claude Not to Repeat Itself

Claude Code is good at writing code. It's less good at remembering what went wrong last time. If you've used it on a real project, you've had this experience: Claude makes a mistake, you fix it, and three conversations later it makes the exact same mistake again.

I built a slash command that fixes this. It's called /add-mistake, it's about 50 lines of markdown, and it's genuinely changed how I work with AI-assisted development.

The problem

Claude Code doesn't have persistent memory across conversations by default. Every new session starts fresh. That's fine for one-off questions, but on a real project you accumulate context: "don't use that deprecated API," "always await that database call," "the auth middleware expects a specific header format."

Without a system to capture these lessons, you end up repeating the same corrections over and over. It's the AI equivalent of a team member who never reads the project wiki.

The solution: CLAUDE.md as institutional memory

Claude Code reads a file called CLAUDE.md from your project root at the start of every conversation. It's like a system prompt, but it lives in your repo. Anything in that file becomes part of Claude's context automatically.

The insight — which I borrowed from Boris Cherny's workflow — is simple: use CLAUDE.md as a running log of mistakes. Every time Claude does something wrong, add it to the file. Claude reads the file next session. The mistake doesn't happen again.

The command

Here's the full /add-mistake command. You save this as ~/.claude/commands/add-mistake.md and it becomes available as /add-mistake in every Claude Code session:

---
description: Add a mistake to CLAUDE.md so it won't be repeated
allowed-tools: Read, Edit
---

# Add Mistake to CLAUDE.md

You are adding a mistake to the project's CLAUDE.md file
to prevent it from happening again.

## Context from User

$ARGUMENTS

## Instructions

1. Find CLAUDE.md in the current project root
2. Locate the "Known Mistakes" section (or create one)
3. Categorize the mistake under the appropriate heading:
   - Database / Data Layer
   - API / Backend
   - Frontend / UI
   - Testing
   - Build / Deploy
   - Other
4. Write a clear, actionable entry that:
   - Describes what went wrong (briefly)
   - States the correct approach
   - Is specific enough to prevent recurrence

## Entry Format

- **[Brief Issue]**: [What to do instead].

That's it. When I type /add-mistake forgot to await the database query, Claude opens my CLAUDE.md, finds or creates a "Known Mistakes" section, categorizes the issue, and writes a clear entry. Next session, Claude reads that entry and doesn't make the same mistake.

What good entries look like

The command is opinionated about entry quality. It pushes Claude to write entries that are specific and actionable:

Good entries: - Missing null check on user.profile: Always check user?.profile before accessing nested properties in the dashboard components - Forgot to await async function: Database operations must be awaited — await db.query() not db.query() - Used hardcoded API URL: Use environment variables for all external URLs — process.env.API_URL

Bad entries (the command avoids these): - "Fix the bug" - "Handle errors better" - "Check types"

The difference matters. Vague entries don't prevent anything. Specific entries act as guardrails.

Why this works better than you'd expect

Three reasons:

1. It compounds. After a few weeks on a project, your CLAUDE.md has 15-20 specific mistakes logged. That's 15-20 things Claude won't do wrong again. The error rate drops noticeably.

2. It's zero-friction. The moment something goes wrong, you type /add-mistake [what happened] and move on. No context switching, no opening another file, no formatting. The command handles everything.

3. It benefits the whole team. CLAUDE.md lives in the repo. When a teammate starts a Claude Code session on the same project, they get all the accumulated lessons automatically. It's like pair programming with someone who actually reads the docs.

The broader pattern

This command is one example of a larger idea: making AI tools learn from their mistakes in the same way teams do. Every engineering team has some version of institutional knowledge — "don't deploy on Fridays," "always run migrations before the API deploy," "the staging database has different column names." The difference is whether that knowledge lives in people's heads or in a system.

CLAUDE.md is that system for AI-assisted development. The /add-mistake command is just a fast way to write to it.

Set it up yourself

1. 1.Create the file at ~/.claude/commands/add-mistake.md with the command content above
2. 2.Make sure your project has a CLAUDE.md file (even an empty one works — the command will create the section)
3. 3.Next time Claude makes a mistake: /add-mistake [describe what went wrong]

That's it. No dependencies, no configuration, no API keys. Just a markdown file that makes your AI assistant get smarter over time.

What I'd add next

The natural extension is categorized severity. Some mistakes are "this crashed the build" and some are "this is a style preference." Weighting them differently in the CLAUDE.md file — maybe with a priority marker — would help Claude focus on the ones that matter most.

But honestly, the simple version works well enough that I haven't needed to build that yet. Sometimes the best tool is the one that's 50 lines of markdown.