airbender

Airbender

A Claude Code reference manual for context engineering and MagicDocs plugin.

Claude Code has six different mechanisms for shaping agent behavior: CLAUDE.md, skills, memory, hooks, MagicDocs, and the insights system. Most people put everything in CLAUDE.md. This is a mistake.

CLAUDE.md is loaded once at session start, buried after five sections of Anthropic's own behavioral instructions, and has no verification loop — there's no mechanism to check whether a CLAUDE.md instruction actually changed behavior. Multi-step workflows, architectural descriptions, and sometimes-relevant preferences all end up in CLAUDE.md where they consume tokens on every API call and get ignored when it matters most. The other five mechanisms exist for good reasons, and each one outperforms CLAUDE.md for specific types of information.

This project grew from researching those differences. It includes:

1. A five-chapter manual explaining how Claude Code manages context internally — how it assembles its prompt, loads instructions, selects memories, compacts conversations, and maintains documentation. Every architectural claim cites source files from publicly available repositories.

2. A Claude Code plugin that replicates Anthropic's internal MagicDocs system — auto-maintained architectural documentation that captures non-obvious patterns, gotchas, design rationale, and entry points. MagicDocs is gated to Anthropic employees; this plugin rebuilds it using public primitives (skills, subagents, hooks).

The MagicDocs implementation was designed through iterative brainstorming, validated with TDD (RED/GREEN/REFACTOR against a real codebase), and tested against the actual Anthropic agent prompt for fidelity.

The Decision Tree

The core problem this project addresses: where should this instruction go? The answer depends on properties of the information, not its topic.

                     Can it be fully enforced
                     without Claude's judgment?
                    /                          \
                  yes                           no
                   |                             |
                 HOOK                  Describes how things work,
                                      or prescribes behavior?
                                     /                       \
                                describes                 prescribes
                                    |                         |
                               MAGIC DOCS           Does it need to be
                              (if available;      a prior (shape assumptions)
                              CLAUDE.md with      or fresh at point of action?
                              advisory if not)   /                        \
                                              prior                   at point
                                                |                     of action
                                         Always relevant                  |
                                         or sometimes?                  SKILL
                                        /            \
                                     always        sometimes
                                       |               |
                                  CLAUDE.md          MEMORY

A few examples to build intuition:

Instruction	Classification	Why
"Run pnpm test before any git commit"	Hook	Fully mechanical, specific command, no judgment needed
"The auth middleware uses Redis for sessions with a 24h TTL"	MagicDocs	Describes architecture — how the system works
"When committing: run tests, check coverage, lint, draft message, wait for approval"	Skill	Multi-step procedure, needs to arrive fresh at point of action
"This project uses pnpm, not npm"	CLAUDE.md	Prior that shapes assumptions before any reasoning starts, every session
"User prefers bundled PRs over many small ones"	Memory	Preference, sometimes relevant but not always
"The sky is blue"	None	Not actionable — Claude can't behave differently

The full decision tree with 26 test cases and detailed rationale is in Chapter 4: What to Put Where. The /classify-info skill (included in this plugin) implements this tree and scores 100% on the test suite.

Install

claude plugin marketplace add translunar/airbender
claude plugin install airbender

To upgrade:

claude plugin marketplace update airbender
claude plugin update airbender

Quickstart

Set up MagicDocs in your repo

/setup-magicdocs