The context engineering playbook

What the playbook covers

From a session that relearns the repo to one that starts where the last stopped. Acme Inc is a made up company. Its payments team runs one change on the acme-payments repo, a split-shipment refund, in a fresh session every week for a month, until the agent stops relearning the codebase.

What context engineering is, and why more context is not the answer. Context engineering is choosing what the agent sees on every turn, and for Acme's payments team the obvious move, adding more instructions, is not the answer. This chapter sorts each piece of context into one of four moves: write, select, compress or isolate.

Count what a fresh session relearns. Day one, before anyone writes a line for the agent: Acme's payments tech lead runs the split-shipment refund in a fresh session and counts what it relearns.

Write the day-one brief. Week one: the day-one brief is one short root file of commands, house style and gotchas, and every line in it prevents a mistake the baseline found. Most of Acme's long first draft goes to a link, a linter or nowhere, and a one-line CLAUDE.md imports the brief. The prune test asks of every line whether removing it would cause a mistake.

Load knowledge only where it applies. Week one: the refund rules matter only in services/refunds/ and the migration rules only in migrations/, so they go in files that load only there. Folder files hold links and pointers, and each agent is tested on them.

Give the agent the decision before it plans. Week one: the files say to refund per shipment line but not why, so Acme writes the decision and a one-page spec into the repo for the agent to read before it plans. Without it, the agent refunds the whole order's shipping. A spec is written only when a change touches money or a past decision.

Turn every review correction into a line or a check. Week two: the brief already says to call LedgerClient, and Acme's reviewer still types "use the ledger client" for the third time. Each correction now gets the cheapest home that stops it.

Spend the window on the task. Week three: Acme's files are right, but one long session fills the window, so each task gets its own session, searches go to a sub-agent and compaction keeps what matters. A progress file tells each fresh session what is done and what is next, and the session rules go in AGENTS.md.

Hand every file an owner and run the baseline again. A month on, Acme's split-shipment refund runs once more in a fresh session. This chapter reads the rerun against the baseline, names who keeps each file and sets the monthly prune. A row that did not drop points to the missing file, and CODEOWNERS gives every file an owner.

Find out where the rest of your engineering system stands. The refund change now starts where the last session stopped, and every file the agents read on acme-payments has an owner. The brief, the folder files, the decision, the lessons, the check and the session rules each answer a mistake the baseline counted, and the monthly prune keeps them short. The rerun points past the files, to review capacity, release ownership and how the team shares what works with agents. Those are the gaps a file in the repo cannot close. The assessment asks where your team stands on each and shows which to fix next. You can run the same baseline on your own repo in one afternoon, and rerun it each month with the prune to see whether each file still earns its place.