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: Extract a rule (not a story) Write it to lessons.md in its workspace Scan relevant rules before future decisions in that domain 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

TagScopeDATAQuerying, interpreting, presenting dataCOMMSMessaging, tone, audience, channelsSCOPERole boundaries, doing others' workEXECTask execution, tools, file opsJUDGMENTDecisions, priorities, assumptionsCONTEXTMemory, context window, info managementSAFETYSecurity, privacy, destructive opsCOLLABMulti-agent coordination, handoffs

When to Record

Record a rule when: User corrects you — explicit feedback User overrides your output — they redo your work Same error twice — second occurrence MUST become a rule 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

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

Pre-Decision Scan

Before acting, scan lessons.md for applicable rules: About to...CheckPresent data[DATA]Send message / write report[COMMS] + [SCOPE]Make suggestion[JUDGMENT] + [SCOPE]Execute multi-step task[EXEC] + [CONTEXT]Start new sessionAll (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

• Create lessons.md in your workspace:
• # Lessons
• Rules extracted from mistakes. Append after failing, scan before deciding.
• 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.
• 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: FileSourceLoad on startupSize targetlessons.mdYour own mistakesYes, fullyGrows organicallytop-100.mdCommunity top picksYes, 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.