Agentic workflows / Practical guide # How to record design decisions so coding agents preserve intent A decision record that explains the reason behind a design rule. [By CRRT](/)·November 2, 2026·3 min read [← All resources](/resources) ## The short answer Record a design decision as a specific choice with a reason, scope, source, and conditions for revisiting it. Link that record from the project’s agent instructions and the affected component documentation so an agent can find the rule before changing the interface. ## 1\. Record a choice someone is likely to undo Start with decisions that are easy to mistake for accidents: a deliberately quiet secondary action, a compact table, a persistent notice, or an exception to the usual component layout. A record is most valuable when the next implementer could plausibly “improve” the screen by removing its intent. Separate an approved decision from a suggestion or an unresolved question. State who owns the decision and link to the supporting discussion, prototype review, or product requirement when that evidence is available. Do not turn a draft comment into an authoritative rule by placing it in an agent file. ## 2\. Capture the choice, reason, and boundary Write the decision in concrete terms and explain the task it supports. “Keep the project picker above the table so people can confirm their context before editing” is more durable than “use this layout because it looks cleaner.” The reason gives an agent something to preserve when the implementation changes. Bound the rule. Identify the component, screen, or workflow it governs and any exceptions. Include a review condition, such as a change to the permission model or evidence that users cannot find the action. A documented decision should remain revisable when its assumptions change. Copy & adapt ``` Decision: keep the project picker visible above the editable table Status: approved Reason: editing must happen in an explicit project context Applies to: project-scoped table screens Preserve: context remains visible before the first editable row Exceptions: read-only summaries outside a project workspace Source: [review or requirement link] Owner: [decision owner] Revisit when: workspace navigation or project permissions change ``` ## 3\. Put the record on the implementation path Store the record where the team keeps product and design context, then link it from the repository’s entry instructions and the affected component brief. Prefer a stable source over copying the same paragraph into several files that can diverge. Ask the coding agent to identify applicable decisions before proposing a change. It should be able to point to the source and describe how the requested correction respects the boundary. If two records conflict, resolve the conflict before implementation rather than asking the agent to guess which owner intended the current behavior. ## 4\. Review changes against the original intent During review, check the outcome the decision protects. The project picker example needs a task-level check that editing still occurs in a visible project context. Matching the old pixels would not be enough if navigation changes how the screen is reached. When the decision changes, update its status and source instead of silently erasing the previous reason. Record any migration or affected consumers. Accepted visual feedback can then refer to the new rule, and the reviewer can confirm both the local correction and the broader intent before approving the result. * Identify stale assumptions during the review. * Distinguish a one-off exception from a new default. * Link the decision from the next agent task when relevant. * Keep unresolved questions separate from approved instructions. ## Common questions ### Should every small style choice have a decision record? No. Use records for choices with meaningful consequences or a high chance of being misinterpreted. Routine token and component usage belongs in the system documentation. ### Does a decision record prevent an agent from making a mistake? No. It provides discoverable context. The task still needs clear boundaries, implementation checks, and human review of the result. ## Sources & further reading * [Storybook: examples that explain component usage](https://storybook.js.org/docs/ai/best-practices) * [CRRT: handoff context and review boundaries](https://crrt.ai/docs/agent-handoff) Written with AI assistance. Tool references checked against the linked documentation on November 2, 2026. Examples are starter templates to adapt and review in your own project. Keep going ## Put the next piece in place. [ Practical guide · 3 min read ### How to document components for coding agents A reusable component brief for your existing library. ](/resources/document-components-for-coding-agents)[ Practical guide · 3 min read ### How to scope one visual fix for a coding agent A bounded implementation brief with a clear review point. ](/resources/scope-a-visual-fix) ## See something off? Ship the fix. Pin the feedback. Give your coding agent the context. Review what comes back. [Try CRRT](/docs/install)