A BETTER WAY TO SHARE THE WORK
Explain an architecture decision without losing why it was made
Future teammates need the reason for the choice—not just the name of the technology.
New to creating with an agent? The request will guide it through the task. Bring your notes; you don’t need to write HTML.
How can an agent help create an architecture decision record?
Supply the problem, constraints, alternatives considered, and the actual decision state. Ask your agent to explain the chosen tradeoff and its consequences without inventing requirements or approval. Review the record, keep the authoritative version with your team's engineering records, and share an approved static reading companion when that helps other readers.
01 / SEE THE DIFFERENCE
An accepted snapshot decision with a visible cost
A fictional team's bounded documentation-page decision. It is not a recommendation for other systems.
ADR-007, accepted September 7 by technical owner Ada, covers a public documentation reading page. Readers need a daily reviewed summary, not live operational data. Options considered: live queries at page load or generated snapshots after review. Chosen: generated snapshots because the page should remain readable without a live data connection. Consequence: content can be stale until the next reviewed generation. No real-time guarantee is required. Implementation is not yet complete. Any change must use a new reviewed record that supersedes ADR-007; the source record remains in the repository.
- Scope
- A public documentation reading page requiring a daily reviewed summary, not live operational data.
- Decision state
- ADR-007 accepted September 7 by Ada. Implementation is not yet complete.
- Choice
- Generated snapshots rather than live queries at page load, to remain readable without a live data connection.
- Accepted cost
- Content can be stale until the next reviewed generation; no real-time guarantee is required.
- Future change
- Use a new reviewed record to supersede ADR-007. Keep the repository record authoritative.
Open a complete fictional HTML example, with its source notes →
Create my architecture decision record02 / MAKE IT YOURSELF
Start with the evidence. Shape the page around the reader.
Write the constraint before the choice
Explain what the design must accomplish and what the team knows. Keep a requirement separate from a preference or assumption. Narrow the scope so a choice for one documentation page does not read as an organization-wide architecture mandate.
Compare the real alternatives
Show each option against the same supplied constraints and preserve the reason the team preferred one. Mark unmeasured performance, unknown operational effort, and unresolved requirements honestly. A diagram can clarify boundaries, but it should not invent infrastructure.
Keep decision state and implementation separate
A proposal is not an accepted record, and an accepted decision may not yet be implemented. Preserve the actual approval evidence and consequences, including the costs the team knowingly accepts. The agent should not make the decision sound unanimous when no such agreement is documented.
Preserve the history when context changes
Keep the source record in the established engineering workflow. If the decision changes, follow the team's supersession process rather than silently rewriting why the earlier choice was made. An HTML companion can help non-specialists read it, but should state its snapshot date and source status.
03 / TRY THIS PROMPT
Copy this into your agent. Add your source material.
Use the conversation where you already did the work, or start one with your notes. Replace the placeholders and supply any missing context; only attach information you are allowed to share with your agent.
Get the ready-to-copy creation request for guided questions, this task, and a draft review before anything is published.
Create an architecture decision record companion from only the authorized requirements, alternatives, evidence, and decision records I provide. Ask for missing essentials: scope, constraints, actual alternatives, decision state, owner, source date, and consequences. Separate requirements from assumptions, proposed from accepted decisions, and acceptance from implementation. Preserve negative consequences and unresolved evidence. Do not invent benchmarks, security guarantees, consensus, requirements, or approval. Explain why the chosen tradeoff fits this scope, not why a technology is universally best. Keep sensitive infrastructure and credentials out of the shared version. State the authoritative record and supersession process without silently rewriting history. Create static HTML with no scripts, forms, or live system claims. Apply my saved artifact style if available. Show the draft and unresolved questions. Do not publish or change access without separate explicit approval. Do not edit the architecture, deploy changes, or mark a record accepted as part of drafting.
04 / BEFORE YOU SEND
A polished page still needs your judgment.
- Is the specific scope and governing constraint understandable before the solution?
- Are alternatives and consequences grounded in the actual evidence?
- Are proposed, accepted, superseded, and implemented states distinguished?
- Does the record retain negative tradeoffs and unmeasured claims honestly?
- Is the authoritative history preserved, with sensitive engineering details appropriately limited?
When HTML fits
A readable companion to a reviewed technical decision when stakeholders need the context and consequences without navigating the whole repository.
When another format fits better
Keep authoritative decision history with the engineering team's chosen records and use its review process. If the repository's Markdown already works for the audience, share that. This page does not review system security, choose an architecture autonomously, or implement the decision.
FROM DRAFT TO A LINK
Make it clear. Make it yours. Then share it.
Keep creating and revising in the agent you already use. With a compatible connection, share/artifacts publishes the reviewed HTML so you do not have to rebuild it in another editor. Ask your agent to use your saved artifact style for headings, color, and tone; review the result before sending it.
Choose who should be able to open the page and verify the returned link. For corrections to the same deliverable, update the existing artifact without changing its link. Publish a separate artifact when the old edition needs to remain available.
These are static pages, not live apps: no scripts, forms, or automatic data refresh. Source collection and scheduling depend on your agent and its available tools, not on share/artifacts.
Make this with my agentQuestions before you start
Is this the same as meeting notes?
No. An architecture record preserves one significant design choice and its context and consequences, which may span several discussions. Link to supporting notes when authorized rather than substituting a transcript for the decision.
Should an accepted decision be edited when we change our minds?
Follow the team's established process. A superseding record can explain the new context while preserving the earlier rationale. Do not silently erase a decision that others may still rely on.
Can the agent recommend the architecture?
It can help compare supplied options, but this workflow records and explains reviewed evidence and decisions. It must not invent performance or security claims, approve a design, or deploy changes on the strength of a writing request.