Context in practice For engineers
Recover architecture decisions before your next AI-assisted change
Recover a decision as a choice, reason, scope, status, and source. Check what still applies before handing it to an agent; a plausible historical explanation is not the current contract.
Search from the change you need to make.
“Find our architecture decisions” is a broad archival task. “We need to change retry behavior; what earlier constraint must survive?” gives retrieval a purpose. Start with the new behavior, the component, and the consequence you are trying to avoid.
Write down the likely relationships: caller, API, persistence boundary, failure mode, and any earlier incident. These relationships often help more than one exact technical term. A design note may talk about duplicate orders while the ticket calls the feature retry support.
Recover the whole decision.
A useful record contains more than a choice. It explains the pressure that made the choice sensible and what it ruled out. Otherwise the next engineer may repeat a rejected approach without understanding the constraint it violated.
AWS describes architectural decision records as lifecycle documents containing a decision, context, and consequences. Its process preserves accepted decisions and supersedes them with new records. You can use a lightweight equivalent even if your team has no formal ADR program.
| Field | Question to answer |
|---|---|
| Choice | What behavior or approach was selected? |
| Reason | Which requirement, incident, dependency, or tradeoff motivated it? |
| Scope | Which service, caller, version, or time period did it cover? |
| Alternatives | What was rejected, and for what reason? |
| Status | Was it proposed, accepted, rejected, or superseded? |
| Evidence | Where is the source, when was it recorded, and who can clarify it? |
Work through a fictional retry change.
Suppose a design note requires one accepted order per request ID. A later incident says that an accepted request can outlive a broken client connection. Neither source answers what happens when a caller reuses an ID with a different body.
The recovered context supports an idempotent retry plan, but it does not supply the missing conflict policy. Put that policy in open questions. Do not let the model infer that every duplicate request must succeed, or that a timeout proves no order exists.
Decision: same ID recovers the original accepted order.
Reason: clients can lose responses after acceptance.
Scope: order creation; verify caller and API version.
Source status: check that the design was accepted and remains current.
Unknown: same ID with a different body.
Plan implication: inspect atomic acceptance and result recovery.
Validation: retry after lost response; overlapping requests; conflict policy.Check history against the present.
Read the relevant current code, tests, and interface contract. Confirm whether the source describes behavior that was implemented, a decision that is still pending, or an old state. A newer document is useful evidence, but date alone does not establish that it supersedes an accepted decision.
When sources disagree, preserve the disagreement in the task brief. State both accounts and the scope each seems to cover. Ask the owner a focused question, or narrow the task to behavior supported by the evidence. Replacing uncertainty with a tidy merged sentence makes the next action less trustworthy.
Keep the search bounded and the result inspectable.
Start with one combined question about the task, relevant components, prior reasoning, exceptions, and changed decisions. Inspect the sources behind important findings. A search result may be an excerpt, a paraphrase, or an interpretation; those are different kinds of support.
Stop when the critical decisions have enough evidence for the next action, or when a specific gap needs a person or source you cannot access. Record the gap. Repeating the same broad query does not turn a bounded search into exhaustive history.
Finish with a task brief, not a history dump.
Give the coding assistant the few constraints that change its plan, with source links and open questions. Ask it to explain how the proposed implementation preserves each constraint before editing. Keep the rest of the recovered history available for inspection instead of pasting it all into the prompt.
After the change, record whether the old decision remained applicable and which new facts were verified. That leaves a useful next entry in the decision lifecycle. It also keeps a successful implementation from silently rewriting what the team originally decided.
Try this on one active change: recover one important reason, one exception, and one unresolved question. If none of those affects the plan, the recovered material may be interesting history rather than useful task context.
Sources and further reading
Prepared with AI assistance and reviewed for source fidelity and practical usefulness. Examples marked fictional are illustrations, not customer results.