Error-Driven Evolution

Turn mistakes into rules. Not reflections, not apologies — rules.

Core Concept

When an agent makes an error or gets corrected, it must:

1. Extract a rule (not a story)
2. Write it to lessons.md in its workspace
3. Scan relevant rules before future decisions in that domain
4. Optionally share anonymized rules to the community repo

lessons.md Format

File location: {workspace}/lessons.md

Each rule follows this structure:

### [CATEGORY] Short imperative title

- **When**: The specific situation/trigger
- **Do**: The correct action (imperative, specific)
- **Don't**: The wrong action that was taken
- **Why**: One sentence — what went wrong
- **Added**: YYYY-MM-DD

Categories

When to Record

Record a rule when:

1. User corrects you — explicit feedback
2. User overrides your output — they redo your work
3. Same error twice — second occurrence MUST become a rule
4. Near miss — you catch yourself about to repeat a mistake

Do NOT record: one-off technical glitches, user preference changes (those go in MEMORY.md).

How to Record

1. Stop. Don't apologize at length.
2. Identify the category.
3. Write the rule in imperative form.
4. Append to lessons.md (never overwrite).
5. Confirm briefly: "Added to lessons: [title]"

Pre-Decision Scan

Before acting, scan lessons.md for applicable rules:

Scan = read ### [TAG] headers, check if any When matches your situation.

Community Sharing

Share anonymized lessons to help other agents: https://github.com/anthropic-ai/agent-lessons

See references/community-sharing.md for the anonymization and submission process.

Setup

1. Create lessons.md in your workspace:

# Lessons
Rules extracted from mistakes. Append after failing, scan before deciding.

2. Copy community/top-100.md to your workspace as top-100.md — this is your pre-installed immune system. Small enough to skim on startup, covers the most common and costly mistakes across all agent deployments.

3. Add to your startup instructions:

- On startup: skim top-100.md titles (pre-installed community lessons)
- On correction/failure: append rule to lessons.md
- Before decisions: scan lessons.md + top-100.md for [CATEGORY] rules

Loading Strategy

Your agent has two rule files:

For deeper community search (beyond top-100), query community/{category}.md files on-demand when facing an unfamiliar situation.

Maintenance

When lessons.md exceeds 50 rules: review for duplicates, retire obsolete rules (mark don't delete), consider splitting by category.