Coding agents degrade when their context window becomes a transcript of everything that happened: repository searches, failed commands, test logs, abandoned hypotheses, diff fragments, and repeated user corrections. The model may still have capacity left, but the signal-to-noise ratio is poor. Important facts are buried behind stale output, and the agent starts optimizing for recent noise instead of the original engineering goal.
Frequent intentional compaction treats context as a managed workflow artifact rather than an accidental chat history. The engineer deliberately pauses before the context window is saturated, distills current state into a compact research note, plan, or progress file, reviews that artifact, and resumes work from the distilled state. The HumanLayer article frames this as a research-plan-implement workflow that keeps context utilization in the middle of the window and puts human review where mistakes are most expensive.
The technique is not a magic prompt. It is an orchestration pattern for brownfield codebases: split exploration from planning, split planning from edits, compact after each phase, and use subagents or fresh sessions for noisy discovery work. The goal is to make each model call see the smallest reliable state needed for the next decision.
Compaction is the deliberate conversion of a noisy interaction history into a smaller, structured state document. A useful compaction records the end goal, confirmed facts, relevant files, decisions already made, failed approaches, open questions, and the next concrete step. It should not summarize everything equally; it should preserve the information that controls future behavior.
The research-plan-implement split prevents the agent from editing while it is still discovering how the codebase works. Research gathers evidence. Planning turns evidence into an ordered edit strategy. Implementation executes bounded steps and validates each one. Each phase has a different output shape and a different review question.
Repository exploration is token-expensive. File search, call-graph inspection, and log reading can fill the parent session with low-level details that are useful only temporarily. Subagents or separate sessions let that noisy work happen in an isolated context and return a compact answer to the main workflow.
A bad line in a plan can generate hundreds of bad lines of code. Frequent compaction increases leverage by making research and plans explicit artifacts that humans can review before the agent spends tokens and wall time editing files.
The first phase asks the agent to inspect the codebase without editing. Its output should be a research artifact, not a patch. For a bug, that artifact might include the failing path, relevant modules, reproduction steps, suspected root cause, counterevidence, and commands already run. If the research is wrong or shallow, throw it away and rerun with better steering before planning.
# research.md
Goal: fix cancellation propagation in the worker runtime.
Confirmed facts:
- Worker handles start in src/runtime/worker.ts.
- Cancellation tokens are created in src/runtime/cancel.ts.
- Existing tests cover timeout cancellation but not explicit user cancellation.
Failed paths:
- Do not patch the HTTP client first; the missing propagation happens before request dispatch.
Open questions:
- Does the queue retry layer swallow CancelledError?
Next step:
- Inspect queue retry behavior and then draft an implementation plan.The plan phase should reference the research artifact explicitly. A good plan lists files to edit, expected changes, verification commands, rollback points, and risks. The plan is compact enough to fit in the next implementation context and precise enough that a reviewer can reject bad architecture before code is generated.
Implementation should proceed one plan slice at a time. After each slice, the agent runs targeted validation and compacts the new state back into the plan: completed tasks, changed files, test results, and current blocker. This prevents late-stage sessions from relying on an aging transcript.
Established repositories contain conventions that are not obvious from the immediate file. Frequent compaction gives the agent time to discover module boundaries, generated-code rules, test idioms, and dependency constraints before making edits. This reduces the common failure mode where generated code is locally plausible but inconsistent with the project.
Bugs that cross queues, database transactions, caches, or async workers need evidence preservation. A compact research note can hold the causal chain without dragging every log line into the implementation prompt. Reviewers can also audit whether the agent diagnosed the real layer rather than patching a symptom.
When an agent produces a large diff, reviewers need mental alignment. Compacted research and plan artifacts explain why the diff exists, what alternatives were rejected, and which tests establish safety. This shifts review from line-by-line archaeology to checking whether the implementation matches the agreed plan.
Make phase boundaries visible to the agent and to the harness. A research prompt should ban edits. A planning prompt should require file paths, ordered steps, and validation commands. An implementation prompt should execute only the current phase and update progress after validation.
## Research mode
- Do not edit files.
- Find the relevant code paths and tests.
- Return: confirmed facts, likely cause, rejected hypotheses, and missing evidence.
## Plan mode
- Use research.md as the source of truth.
- Return numbered implementation phases.
- For each phase include files, expected behavior, and validation command.
## Implement mode
- Execute one phase at a time.
- Run the listed validation.
- Update progress.md before continuing.A compaction that says “we looked at many files” is nearly useless. Preserve decisions and evidence. Record what must not be done again. Include exact file paths and command names, but omit bulk output unless the next step depends on it.
Subagents are most useful for bounded discovery: locate the authorization path, summarize test conventions, compare two modules, or inspect an error trace. The parent agent should retain task ownership and integrate the compacted findings into the plan. Otherwise the workflow becomes multiple uncoordinated agents each carrying partial truth.