# Architecture Decision Record Drafts an architecture decision record (ADR) that documents why a technical choice was made, what alternatives were considered, and what consequences to expect. Use it whenever you make a significant design or infrastructure decision so the reasoning survives beyond the meeting. ## Prompt ## Context You are a technical writing assistant helping an engineer or architect document a significant design decision. The audience is the engineering team and future maintainers who need to understand not just what was decided but why, and what the team gave up by not choosing the alternatives. System or service name: [SYSTEM OR SERVICE NAME] Decision title: [DECISION TITLE] Context and problem being solved: [CONTEXT AND PROBLEM] Decision made: [DECISION] Alternatives considered: [ALTERNATIVES CONSIDERED] Consequences and trade-offs: [CONSEQUENCES AND TRADE-OFFS] Status (proposed, accepted, deprecated, superseded): [STATUS] Date and decision owner: [DATE AND OWNER] ## Task Draft an ADR with these sections: Title, Status, Context, Decision, Alternatives Considered, Consequences, and Notes. ## Standards - Plain technical language. Write for an engineer who was not in the room. - Context states the problem as it existed before the decision, not the solution. - Decision is one or two sentences naming exactly what was chosen and why it beat the alternatives. - Alternatives Considered lists each option with its key trade-off. Minimum two alternatives. - Consequences states what the team gains and what it gives up. Include operational, security, and maintenance implications where applicable. - Do not invent technology names, version numbers, performance figures, or integration details the user did not supply. - Notes section is optional. Use it only for links, follow-on decisions, or review dates the user provides. - Do not fabricate CVEs, known vulnerabilities, or security claims for any technology named. - If any named input is missing or ambiguous, ask before drafting. ## Verification checklist (embedded reminder) Before using this ADR: confirm every technology name and version, confirm every trade-off claim against your team's actual testing or documented knowledge, and confirm status with the decision owner. ## Variables - SYSTEM OR SERVICE NAME - DECISION TITLE - CONTEXT AND PROBLEM - DECISION - ALTERNATIVES CONSIDERED - CONSEQUENCES AND TRADE-OFFS - STATUS - DATE AND OWNER ## Input checklist - [ ] The exact decision made, in one or two plain sentences - [ ] At least two alternatives that were genuinely considered, with the reason each was rejected - [ ] Known consequences: what the team gains, what it gives up, and any follow-on decisions created - [ ] Confirm all technology names, version numbers, and performance claims come from your team's own research or testing, not from the AI - [ ] Redact any credentials, internal IP ranges, customer data, or classified information before pasting context, per your org policy - [ ] Status of the decision and the name or role of the decision owner ## Verification checklist - [ ] Every technology name and version number checked against your actual environment or procurement records - [ ] Trade-off claims verified against your team's testing, spike results, or documented benchmarks, not the AI's general knowledge - [ ] No CVEs or known vulnerabilities cited that the AI introduced without your supplying them - [ ] Alternatives section reflects what your team actually considered, not plausible options the AI added on its own - [ ] Consequences match your team's real experience with the chosen technology - [ ] Status and owner confirmed with the person named before the ADR is committed to your repo - [ ] ADR reviewed by at least one other engineer who was present for the decision before it is marked accepted ## Sample output Sample output. Generated by AI from sample inputs: # ADR-014: Use PostgreSQL for the Northwind Inventory Service **Status:** Accepted **Date:** 2026-06-10 **Owner:** Platform Engineering, J. Calloway ## Context The Northwind Inventory Service needs a persistent store for SKU records, stock levels, and transaction history. The team evaluated storage options during the Q2 architecture review. The service handles roughly 40,000 writes per day with moderate read traffic. Strong consistency on stock-level updates is a hard requirement; a double-decrement on the same SKU causes fulfillment errors. ## Decision Use PostgreSQL 16 as the primary data store. It provides the ACID (atomicity, consistency, isolation, durability) guarantees the stock-level update pattern requires, and the team already operates a managed PostgreSQL cluster on the company's cloud platform. ## Alternatives Considered **DynamoDB:** Offers near-unlimited scale and low operational overhead, but eventual consistency on stock counters without careful application-side locking would require significant extra work to avoid double-decrements. Rejected because the consistency model adds complexity that offsets the operational savings. **MongoDB:** Document model fits the SKU catalog well, but multi-document transactions carry a performance cost and the team lacks MongoDB operational experience. Rejected on operational risk. ## Consequences Gains: Strong consistency on stock writes, familiar operational tooling, straightforward migration path from the existing prototype. Gives up: horizontal write scaling beyond a single primary node; if write volume grows beyond current projections, a sharding strategy will be needed. Follow-on decision required: connection pool sizing for the inventory service container fleet. ## Notes Revisit if daily write volume exceeds 500,000. See ADR-011 for the managed database platform choice. ## Customization notes Add a Compliance or Security section if your org requires documenting security implications of architectural choices, such as data residency or encryption decisions. For government or regulated environments, link the ADR to the relevant control framework control, for example NIST SP 800-53 (National Institute of Standards and Technology Special Publication) or FedRAMP (Federal Risk and Authorization Management Program). Teams using a numbered ADR format should include the number in the title variable. If your organization uses a specific ADR template, paste it as a formatting guide. --- From The IT & Cybersecurity Library at vetslearn.com/libraries/it-cyber