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

#ai #programming #productivity #tutorial

When working with Claude Code on complex repositories, the agent will inevitably run into non-obvious environment quirks: outdated TypeScript definitions, hidden runtime dependencies, or bundler-specific behaviors. Fixing the same mistake repeatedly in chat wastes context and time. Conversely, dumping multi-page session transcripts into instructions causes prompt clutter and degraded model attention.

A practical pattern is maintaining a lightweight MISTAKES.md in your repository root. It records only reproducible incidents, verified causes, and prevention actions, which are subsequently promoted into project tests, linter rules, and persistent configuration.

1. MISTAKES.md vs. Session Transcript

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

Dimension	Session Transcript	MISTAKES.md Incident Log
Volume	Thousands of lines of raw tool calls and intermediate steps	5–10 structured lines per incident
Purpose	Single-run debugging and audit	Reference base to prevent future recurrence
Secret Handling	May capture raw environment variables or tokens	Strictly prohibited: zero credentials or secrets
Lifespan	Ephemeral artifact	Persistent documentation until automated

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:

Incident: Exactly what broke and under what conditions (error code, command, tool).
Impact: Downstream effect (build broken, migration corrupted, test suite aborted).
Root Cause: Confirmed technical source. If unproven, explicitly mark as [Hypothesis].
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.

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

First occurrence: Add a concise record to MISTAKES.md.
Second occurrence (Recurrence): If the issue can be caught deterministically, write a test or linter rule. Automated gates outperform textual prompts.
Non-mechanical checks: Formulate an explicit negative rule in CLAUDE.md (e.g., "Never run jest without --runInBand in CI").
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:

Start a fresh Claude Code session.
Provide a prompt that previously triggered the failure.
Inspect whether the agent respects the new rule or is stopped by the pre-commit hook.
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.

Originally published on the BetterToken blog.

BetterToken provides pay-as-you-go access to AI model APIs through
OpenAI-compatible and Anthropic-compatible endpoints — useful if you are wiring
Claude Code, Codex, or your own tooling to a custom base URL.
See the docs to get started.

DEV Community