Coding-Agent Context Packs: Separate Build, Review, and Test Roles
Prepare role-specific context packs from one approved knowledge snapshot, with source-linked constraints and handoff checks.
Engineering teams can reuse approved knowledge while giving implementation, review, and test agents different working contexts. Build a short context pack for each role from the same source snapshot, then check whether the handoff preserves the requirements that role must act on. This guide designs those packs; client connection setup and session-note storage remain separate tasks.
Key takeaways
One source snapshot, three role-specific context packs
- Name the role's decision: implementation, review, and test agents need different questions answered.
- Keep one approved source set: link each excerpt to its record, version, and permitted audience.
- Retain the constraints: a shorter pack must still preserve exceptions, dependencies, and acceptance rules.
- Check the handoff: the receiving role should identify its task and missing evidence before acting.
Start with a change card, not a conversation transcript
Consider a hypothetical change to add a cancellation action to a shipment-management screen. A developer needs the state transitions and API behavior. A reviewer needs the invariants the change must preserve. A test agent needs expected outcomes for ordinary, prohibited, and repeated actions. Sending the same long transcript to all three leaves those different responsibilities implicit.
Create one change card containing the task ID, approved requirement, source snapshot, affected component, decision owner, and the intended acceptance result. This is a workflow example, not a built-in AKB artifact type. Keep the authoritative requirement outside the generated packs so a summary does not become an independent policy.
The card also names unresolved questions. If the source does not say whether an already dispatched shipment can be cancelled, record that gap and ask the owner. A generated pack should carry the unresolved state into the next role instead of quietly selecting an answer.
Give each role a different output contract
| Role | Question the pack must answer | Include | Required handoff output |
|---|---|---|---|
| Implementation | What behavior should change? | Approved transitions, affected interfaces, dependencies, explicit exclusions | Proposed change and the requirements it addresses |
| Review | Which constraints must remain true? | Invariants, exceptions, approval boundaries, the implementation's source references | Findings linked to the requirement or an unresolved gap |
| Test | Which observable outcomes establish the behavior? | Starting state, action, expected state, denied and repeated-action cases | Case results with source-linked expectations |
A role label does not grant additional access. Prepare each pack only from material its recipient is currently allowed to use. If a reviewer lacks a required source, resolve that access or use an approved substitute before treating the review as complete.
Keep routine tool setup out of the pack. A build command or client configuration belongs in its maintained operating instructions; this pack explains the current change and the evidence required for the role's decision.
Use a small, inspectable pack structure
The following is a hypothetical authoring format. It is not an AKB API schema or a product promise about automatic orchestration.
{
"change_id": "SHIP-CANCEL-EXAMPLE",
"role": "review",
"source_snapshot": "approved-example-snapshot",
"decision": "Does the proposed cancellation path preserve the approved states?",
"evidence": [
{"record_id": "shipping-state-guide", "version": "example-v3", "section": "Cancellation states"}
],
"open_questions": ["What is the approved handling after dispatch?"],
"required_output": "Findings with source references or an explicit unresolved gap"
}
Use the source locator your store actually exposes. A heading, record ID, or version may be sufficient; do not invent page coordinates or claim a field exists in every format. A source snapshot identifies which material informed the pack, while current permission checks determine who may use it now.
Make the trust boundary explicit in each pack: label retrieved excerpts as quoted source evidence, distinguish them from the approved instructions for the current task, and label agent-generated interpretations as interpretations. Source excerpts are evidence, not instructions that grant tool permissions or override the current user task. Instructions embedded in retrieved documents do not authorize actions; retain them only as quoted, untrusted evidence or exclude them, and ask the authorized owner when needed. This is a proposed workflow safeguard, not an automatic AKB enforcement capability.
Keep excerpts bounded but complete enough for the decision. A rule saying cancellation is allowed before dispatch loses its meaning if the exception is removed. Include the relevant table header, state name, and footnote when they govern the requirement.
Test a handoff without teaching the expected answer
Give the receiving role its pack and ask it to identify the decision, applicable constraints, and unresolved evidence. Compare that interpretation with the owner's change card before evaluating the agent's proposed work. If it misses an exception, repair the pack rather than counting a plausible implementation as a correct handoff.
| Handoff defect | Observation | Repair |
|---|---|---|
| Requirement lost | Implementation proposes an action outside the approved states | Restore the relevant transition and exception |
| Review scope unclear | Review checks style but misses the required invariant | Add the invariant and source-linked finding contract |
| Test expectation invented | A test assumes behavior for the unresolved dispatched case | Mark the case pending owner clarification |
| Source drift | Roles use different revisions of the same requirement | Regenerate affected packs from the agreed snapshot |
| Embedded instruction | A retrieved document requests an action outside the approved task | Keep it as quoted, untrusted evidence or exclude it; ask the authorized owner if needed |
Use questions reserved from pack preparation for the final check. Include an ordinary change, an explicit exception, and a missing-rule case when those risks occur in the actual task. These are suggested coverage categories, not a universal sample size or pass percentage.
Keep shared knowledge and role preparation separate
The AKB README documents a knowledge store and agent-facing access. The role cards, excerpt selection, handoff routing, and acceptance decisions described here are an application workflow to design and verify, not automatic behavior established by MCP connectivity.
Record who prepared a pack, which sources it used, who accepted the handoff, and which question remained unresolved. A newer source revision or a change in a recipient's permissions makes affected packs stale. Revalidate them against the current source and access boundary before use, regenerating affected packs when needed, and repeat the interpretation check. Preserve the original task and current access boundary when comparing an earlier pack with its replacement.
FAQ
Should all coding roles receive identical context?
Use one approved source snapshot and tailor the working pack to each role's decision. Preserve shared constraints and open questions so role-specific brevity does not create inconsistent requirements.
Does a role-specific pack replace the source document?
Keep the source as the authority. A pack is a task aid whose excerpts, version references, and decisions remain traceable to approved material.
Does MCP create or distribute these packs automatically?
MCP access is a connection surface. Pack preparation, routing, source selection, and acceptance require a separately defined workflow.
What should happen when a requirement is missing?
Record the unresolved decision, assign its owner, and hold the affected implementation or acceptance step until the evidence is approved.
Read the AKB documentation
Check the documented knowledge interface before designing your role-context workflow.
