MISTAKES.md with Claude Code: Turning Repeat Failures into Project Rules

1. MISTAKES.md vs. Session Transcript

Do not confuse an incident log with a raw terminal transcript:

MISTAKES.md must stay concise so that Claude Code can ingest it at the start of a session without consuming excessive context tokens.

---

2. Anatomy of an Incident Record

Every incident entry contains four required fields:

1. Incident: Exactly what broke and under what conditions (error code, command, tool).
2. Impact: Downstream effect (build broken, migration corrupted, test suite aborted).
3. Root Cause: Confirmed technical source. If unproven, explicitly mark as [Hypothesis].
4. Prevention: Concrete rule or check preventing recurrence.

Example Incident Record

ERR-014: PostgreSQL Migration Failed on DROP COLUMN without CASCADE

• Incident: Claude Code executed ALTER TABLE orders DROP COLUMN customer_ref; in migration 0042.
• Impact: Staging deployment failed due to dependent view v_active_orders.
• Root Cause: Views referencing base tables require explicit cascade recreation or prior view updates.
• Prevention: All DDL column removal migrations must check dependent views via pg_depend before execution.

> [!IMPORTANT]
> **Zero Secrets Policy**: Never commit real database connection strings, private keys, tokens, or `.env` snippets into `MISTAKES.md`. Manage your Claude Code API keys through local environment variables.

For a reliable Claude Code setup with an API provider, use your own API Key and follow the [BetterToken Claude Code Integration Guide](https://docs.bettertoken.ai/ai-tools/claude-code?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-101&utm_content=mistakes-md-claude-code-workflow).

---

3. Promotion Threshold: From Log to Test or Rule

Not every one-off typo deserves a permanent rule. Promote entries into automated gates using a clear threshold:

Incident Occurred
  │
  ├─> First time: Log 4-field entry in MISTAKES.md
  │
  └─> Second time (Recurrence):
        │
        ├─> Can be verified mechanically?
        │     └─> YES: Add unit test, ESLint rule, or pre-commit hook
        │
        └─> NO: Add strict negative instruction to CLAUDE.md / AGENTS.md

1. First occurrence: Add a concise record to MISTAKES.md.
2. Second occurrence (Recurrence): If the issue can be caught deterministically, write a test or linter rule. Automated gates outperform textual prompts.
3. Non-mechanical checks: Formulate an explicit negative rule in CLAUDE.md (e.g., "Never run jest without --runInBand in CI").
4. Archiving: Once a test or hook is deployed, archive or remove the entry from MISTAKES.md to prevent file bloat.

---

4. Verifying on the Next Task

To confirm the new guardrail works:

1. Start a fresh Claude Code session.
2. Provide a prompt that previously triggered the failure.
3. Inspect whether the agent respects the new rule or is stopped by the pre-commit hook.
4. If the agent bypasses text instructions, convert the constraint into a strict command wrapper or automated check.

This feedback loop turns random development failures into a robust, self-improving engineering foundation.