Error-Driven Evolution

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

| Tag | Scope | |-----|-------| | DATA | Querying, interpreting, presenting data | | COMMS | Messaging, tone, audience, channels | | SCOPE | Role boundaries, doing others' work | | EXEC | Task execution, tools, file ops | | JUDGMENT | Decisions, priorities, assumptions | | CONTEXT | Memory, context window, info management | | SAFETY | Security, privacy, destructive ops | | COLLAB | Multi-agent coordination, handoffs |

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:

| About to... | Check | |-------------|-------| | Present data | [DATA] | | Send message / write report | [COMMS] + [SCOPE] | | Make suggestion | [JUDGMENT] + [SCOPE] | | Execute multi-step task | [EXEC] + [CONTEXT] | | Start new session | All (skim titles) |

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:

| File | Source | Load on startup | Size target | |------|--------|-----------------|-------------| | lessons.md | Your own mistakes | Yes, fully | Grows organically | | top-100.md | Community top picks | Yes, skim titles | ~8KB, curated |

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.

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