{"slug": "adr-template-how-ai-generates-architecture-decision-records-your-future-self-you", "title": "ADR Template: How AI Generates Architecture Decision Records Your Future Self Will Thank You For", "summary": "A developer proposes using AI to generate Architecture Decision Records (ADRs) in 3-5 minutes instead of 30-40, solving the documentation gap that plagues most teams. The approach uses LLMs to produce structured ADRs covering context, decision, consequences, and alternatives, with CI pipeline automation for enforcement.", "body_md": "Teams make dozens of architectural decisions every month but document almost none of them. The rest dissolve into Slack threads, hallway conversations, and the minds of people who will leave the company within a year.\n\nSix months later, a new developer stares at the code and asks: \"Why Redis here instead of PostgreSQL for queues?\" Nobody remembers. An archaeological dig through Git history, Slack, and Notion begins. Two hours spent investigating a decision that originally took 15 minutes.\n\nArchitecture Decision Records (ADRs) solve this problem. But they don't get written. The reason is simple: drafting an ADR takes 30-40 minutes, and the developer has already moved on to the next task. AI compresses that to 3-5 minutes. This article covers ADR structure, prompts for LLM-based generation, real-world examples, and CI pipeline automation.\n\nAn ADR (Architecture Decision Record) is a document that captures one specific architectural decision. Not a spec, not an RFC, not a design document. One decision, one file.\n\nMichael Nygard introduced the concept in 2011. The format took hold at large companies (Spotify, Thoughtworks, GitHub) but remains rare in smaller teams. The main reason: the writing overhead feels higher than the value it delivers.\n\nThree situations where the absence of ADRs hurts the most:\n\n**Onboarding.** A new developer reads the code and encounters an unconventional decision. Without an ADR, they either spend hours investigating, or treat it as a mistake and \"fix\" it. Both paths are expensive for the team.\n\n**Revisiting decisions.** Context changes: load increases, new requirements emerge, a dependency goes stale. Without a record of why the current solution was chosen and which alternatives were rejected, the team re-runs the entire analysis from scratch.\n\n**Audits and compliance.** In regulated industries (fintech, healthtech), architectural decisions require documented justification. ADRs close that gap automatically.\n\nA minimum viable ADR contains seven sections. Each answers a specific question.\n\n```\n# ADR-{number}: {Decision title}\n\n## Status\nProposed | Accepted | Deprecated | Superseded by ADR-{number}\n\n## Date\n2026-03-26\n\n## Context\nWhat problem or situation forces this decision?\nTechnical constraints, business requirements, current system state.\n\n## Decision\nExactly what was decided. A concrete statement without vague language.\n\n## Consequences\nPositive and negative effects of the decision.\nWhat becomes easier, what becomes harder.\n\n## Alternatives Considered\nWhich options were evaluated and why they were rejected.\nComparison criteria, trade-offs.\n\n## References\nLinks to issues, PRs, discussions, documentation, benchmarks.\n```\n\n**Status** has four values. `Proposed`\n\nmeans the decision is under discussion. `Accepted`\n\nmeans it's adopted and in use. `Deprecated`\n\nmeans it's outdated, but no replacement has been chosen yet. `Superseded by ADR-{N}`\n\nmeans it was replaced by a newer decision with a direct link.\n\n**Context** is the most important section. Without context, a decision loses meaning. \"We chose Redis for caching\" tells you nothing. \"We chose Redis for caching because PostgreSQL LISTEN/NOTIFY couldn't deliver sub-millisecond latency for autocomplete at 10K RPS\" tells you everything.\n\n**Alternatives Considered** is the section most often skipped and the one that provides the most value. When the question \"why not Kafka?\" comes up a year later, the answer is already recorded.\n\nA baseline prompt that works with Claude, GPT-4, and Gemini:\n\n```\nYou are a senior software architect. Generate an ADR (Architecture Decision Record)\nusing the following template.\n\nDECISION: {description of the decision made}\n\nPROJECT CONTEXT:\n- Stack: {languages, frameworks, infrastructure}\n- Scale: {load, team size, product stage}\n- Constraints: {budget, deadlines, compliance, legacy}\n\nOUTPUT FORMAT:\n# ADR-{number}: {Title}\n\n## Status\nAccepted\n\n## Date\n{current date}\n\n## Context\nDescribe the problem that led to this decision. Include technical and business factors.\nSpecific metrics where applicable. 3-5 sentences.\n\n## Decision\nState the decision in one paragraph. No words like \"we decided\" or \"we will\" - facts only.\nSpecify the scope: what is included, what is not.\n\n## Consequences\n### Positive\n- List 3-5 concrete improvements\n\n### Negative\n- List 2-3 trade-offs or risks\n\n## Alternatives Considered\nFor each alternative:\n### {Alternative name}\n- Description in 1-2 sentences\n- Reason for rejection (specific, not \"didn't fit\")\n\n## References\n- Links to relevant resources\n\nRULES:\n- Active voice, no filler\n- Specific metrics instead of \"faster/better/simpler\"\n- If metrics are unavailable, use qualitative criteria\n- Every Consequences item must be verifiable\n```\n\nThis prompt covers 80% of cases. The remaining 20% require specialized variants.\n\nMigrations carry the highest risk and the longest consequence horizon.\n\n```\nGenerate an ADR for a migration.\n\nFROM: {current solution, version, how long in production}\nTO: {target solution}\nREASON FOR MIGRATION: {what broke or stopped working}\n\nIn addition to the standard template, add these sections:\n\n## Migration Strategy\n- Approach: Big Bang | Strangler Fig | Parallel Run\n- Justification for the approach\n- Migration phases with estimated timelines\n\n## Rollback Plan\n- Rollback triggers\n- Rollback procedure\n- Acceptable rollback window\n\n## Success Criteria\n- Metrics that define migration as complete\n- Stabilization period after migration\nGenerate an ADR for a technology selection.\n\nTASK: {what problem the chosen technology solves}\nCANDIDATES: {list of evaluated options}\nCHOICE: {winner}\n\nAdditionally:\n\n## Evaluation Criteria\nComparison table of candidates by criteria:\n| Criterion | Weight | {Candidate 1} | {Candidate 2} | {Candidate 3} |\nCriteria: performance, DX, community/support, cost, learning curve, integration\n\n## Proof of Concept\n- What was tested in the PoC\n- Results with numbers\nGenerate an ADR recording the rejection of a previously accepted decision.\n\nORIGINAL ADR: {number and title}\nREASON FOR REJECTION: {what changed since the decision was made}\nREPLACEMENT: {new decision, if any}\n\nAdditionally:\n\n## What Changed\n- Specific context changes that made the decision obsolete\n- Date or event that made it apparent\n\n## Lessons Learned\n- What the team learned from using the previous solution\n- How this influences similar future decisions\n```\n\nA team is choosing a caching strategy for a travel app API. Here is what AI generates using the prompt above:\n\n```\n# ADR-012: Redis for External API Response Caching\n\n## Status\nAccepted\n\n## Date\n2026-03-26\n\n## Context\nThe travel app API calls external services (Foursquare, weather, flights)\nfor every user request. Average response time: 800ms on a cold call. 40%\nof requests are repeat calls to the same data within a 15-minute window\n(user switches between tabs, refreshes the page). External API rate limits:\n500 req/min (Foursquare), 1000 req/min (weather). At 200 DAU, current load\nis at 60% of the limit.\n\n## Decision\nUse Redis (Upstash Serverless) as a cache layer between edge functions\nand external APIs. TTL: 15 minutes for geo data, 60 minutes for weather,\n5 minutes for flight prices. Cache key: `{api}:{endpoint}:{normalized_params_hash}`.\nInvalidation strategy: TTL-based, no manual invalidation in the first phase.\n\n## Consequences\n### Positive\n- Response time for cached requests: 800ms to 15-25ms (Upstash REST API)\n- Rate limit consumption drops by 40% with current usage patterns\n- Edge functions free up faster, reducing compute consumption\n\n### Negative\n- Additional dependency: Upstash (managed, but still a point of failure)\n- Stale data within the TTL window: users may see outdated ticket prices\n- Cost: ~$5/mo at current load, scales with growth\n\n## Alternatives Considered\n### In-memory cache (Map in Deno isolate)\nZero latency, but state is lost on cold start. At the current cold start\nfrequency (every 3-5 minutes), hit rate would be below 20%. Doesn't\njustify the implementation complexity.\n\n### Cloudflare KV\nEventual consistency with up to 60-second delay. Acceptable for flight\nprice caching, but creates UX issues for geo data (user is moving).\nCost is comparable to Redis.\n\n### PostgreSQL materialized views\nRequires reworking the data layer. Not suitable for edge functions due\nto connection latency (50-100ms vs 5-15ms for Redis REST API).\n\n## References\n- Upstash Redis REST API: https://docs.upstash.com/redis\n- Foursquare rate limits: https://docs.foursquare.com/reference/rate-limits\n```\n\nNote the specificity. No phrases like \"improves performance\" or \"reduces load.\" Numbers instead: 800ms to 15-25ms, 40% reduction in rate limit consumption, $5/mo. Every item can be verified six months from now.\n\nAI can extract architectural decisions from existing artifacts. This closes the \"we made a decision three months ago and forgot to document it\" problem.\n\nPrompt for retrospective generation:\n\n```\nAnalyze the following PR (diff + description + comments) and determine\nwhether it contains an architectural decision. If so, generate an ADR.\n\nPR TITLE: {title}\nPR DESCRIPTION: {description}\nPR DIFF (key files):\n{diff}\nPR COMMENTS:\n{review comments}\n\nCriteria for an architectural decision:\n- Adding a new dependency\n- Changing data structure or DB schema\n- New pattern (caching, queues, retry strategy)\n- Changing an API contract\n- Choosing between two or more approaches (recorded in the discussion)\n\nIf the PR contains no architectural decision, respond \"No ADR needed\" with\na brief explanation.\n```\n\nFor Claude Code, this process can be automated with:\n\n```\n# Fetch the latest PR diff and generate an ADR\ngh pr view --json title,body,comments,files | \\\n  claude -p \"Analyze this PR and generate an ADR if you find an architectural decision.\"\n```\n\nManual ADR generation works but requires discipline. CI automation removes the human factor.\n\n```\n# .github/workflows/adr-check.yml\nname: ADR Check\n\non:\n  pull_request:\n    types: [opened, synchronize]\n\njobs:\n  check-adr:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Detect architectural changes\n        id: detect\n        run: |\n          CHANGED_FILES=$(gh pr diff ${{ github.event.pull_request.number }} --name-only)\n\n          ADR_NEEDED=false\n\n          # New dependencies\n          if echo \"$CHANGED_FILES\" | grep -q \"package.json\\|Cargo.toml\\|go.mod\\|requirements.txt\"; then\n            ADR_NEEDED=true\n          fi\n\n          # DB migrations\n          if echo \"$CHANGED_FILES\" | grep -q \"migration\\|schema\"; then\n            ADR_NEEDED=true\n          fi\n\n          # Infrastructure config\n          if echo \"$CHANGED_FILES\" | grep -q \"docker\\|terraform\\|cloudflare\\|nginx\"; then\n            ADR_NEEDED=true\n          fi\n\n          echo \"adr_needed=$ADR_NEEDED\" >> $GITHUB_OUTPUT\n\n      - name: Check for ADR file\n        if: steps.detect.outputs.adr_needed == 'true'\n        run: |\n          CHANGED_FILES=$(gh pr diff ${{ github.event.pull_request.number }} --name-only)\n          if ! echo \"$CHANGED_FILES\" | grep -q \"^docs/adr/\"; then\n            echo \"::warning::This PR contains architectural changes but no ADR. Consider adding one to docs/adr/\"\n          fi\n        env:\n          GH_TOKEN: ${{ github.token }}\n```\n\nThis workflow warns rather than blocks. Blocking PRs through ADR requirements creates friction that kills adoption.\n\n```\ndocs/\n└── adr/\n    ├── README.md           # Index of all ADRs\n    ├── template.md         # Template\n    ├── 001-use-astro.md\n    ├── 002-redis-caching.md\n    └── 003-event-driven.md\n```\n\nThree-digit numbering with leading zeros. Files in chronological order. One file, one decision.\n\n``` bash\n#!/bin/bash\n# scripts/new-adr.sh\n\nADR_DIR=\"docs/adr\"\nLAST_NUM=$(ls \"$ADR_DIR\" | grep -oP '^\\d+' | sort -n | tail -1)\nNEXT_NUM=$(printf \"%03d\" $((10#$LAST_NUM + 1)))\n\nSLUG=$(echo \"$1\" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')\nFILENAME=\"${ADR_DIR}/${NEXT_NUM}-${SLUG}.md\"\n\ncat > \"$FILENAME\" << EOF\n# ADR-${NEXT_NUM}: $1\n\n## Status\nProposed\n\n## Date\n$(date +%Y-%m-%d)\n\n## Context\n<!-- What problem forces this decision? -->\n\n## Decision\n<!-- What was decided? -->\n\n## Consequences\n### Positive\n-\n\n### Negative\n-\n\n## Alternatives Considered\n###\n-\n\n## References\n-\nEOF\n\necho \"Created: $FILENAME\"\n```\n\nUsage: `./scripts/new-adr.sh \"Switch from REST to GraphQL\"`\n\n.\n\nADRs gain additional value as context for AI coding. When an AI agent (Claude Code, Cursor, Copilot) works with a codebase, ADRs provide architectural context that does not exist in the code itself.\n\nAdding ADRs to the project's CLAUDE.md:\n\n```\n## Architecture Decisions\nKey ADRs to follow when making changes:\n- ADR-005: Event-driven architecture for notifications (docs/adr/005-event-driven.md)\n- ADR-008: PostgreSQL RLS for multi-tenancy (docs/adr/008-rls-multitenancy.md)\n- ADR-012: Redis caching strategy (docs/adr/012-redis-caching.md)\n```\n\nThe AI agent respects these decisions when generating code. Instead of suggesting a REST call for notifications, it uses the event bus because ADR-005 recorded that decision. More on structuring context for AI: [Context Engineering Guide](https://dev.to/blog/context-engineering-guide/).\n\n**Context that is too abstract.** \"We needed to improve performance\" is useless. \"API response time grew to 2.3s at p95; SLA requires < 500ms\" is useful.\n\n**Missing Alternatives.** Without an alternatives section, the ADR looks like post-hoc justification rather than a deliberate choice. Even if there was only one alternative (doing nothing), that is worth recording.\n\n**Scope that is too broad.** An ADR captures one decision. \"Moving to microservices\" is not one decision. It is ten. Each service, each contract, each communication mechanism deserves its own ADR.\n\n**Stale Status.** An ADR with `Accepted`\n\nstatus that was replaced long ago by another decision misleads readers. Updating the status to `Superseded by ADR-{N}`\n\ntakes seconds and saves others hours.\n\n**Confusing ADRs with documentation.** An ADR does not describe how the system works. It describes why the system works the way it does. How is the job of [SOPs and operational documentation](https://dev.to/blog/sop-generator-ai-documentation/).\n\nFour metrics that show whether ADRs are working for the team:\n\n| Metric | How to measure | Target |\n|---|---|---|\n| ADR coverage | Number of ADRs / number of architectural PRs per month | > 70% |\n| Time-to-ADR | Time from decision to recorded ADR | < 24 hours |\n| Reference rate | How often ADRs are cited in PRs and discussions | > 2 times/month per ADR |\n| Onboarding feedback | New joiners rate ADR usefulness (1-5) | > 4.0 |\n\nADR coverage below 50% means the process has not taken hold. Time-to-ADR above one week means context is being lost and the record becomes a fictional reconstruction.\n\n`docs/adr/`\n\ndirectory and the template`new-adr.sh`\n\nscript for quick creationThe first three steps take 30 minutes with AI. The rest is a habit that forms over 2-3 sprints.\n\n*Need help with architecture decision records or engineering processes? I help startups build AI products and automate processes — belov.works.*\n\nYes, this is the most effective approach. Reviewing ADRs via PRs keeps the architectural record auditable, allows team members to challenge or refine the decision before it is locked in, and creates a natural link between the code change and the rationale. The review process also surfaces disagreements early: an ADR under debate in a PR is better than a contested decision discovered six months into implementation.\n\nOne ADR per atomic decision, not per service or per project. Choosing Redis for caching and choosing Upstash specifically as the managed provider are two separate ADRs. \"Moving to microservices\" is not one ADR — it is at minimum one per service boundary, one for the communication protocol, and one for the deployment strategy. Overly broad ADRs lose precision; overly narrow ones become noise.\n\nTreat inherited ADRs as unverified hypotheses. Read them for context, but audit each against the current state of the system. Some decisions will be stale (the library is deprecated, the load assumption changed), some will still be valid. The fastest path is a one-day \"ADR audit sprint\": read every ADR, update Status fields, and add a brief note to any where the context has shifted. This investment pays back in the first month of development.", "url": "https://wpnews.pro/news/adr-template-how-ai-generates-architecture-decision-records-your-future-self-you", "canonical_source": "https://dev.to/spyrae/adr-template-how-ai-generates-architecture-decision-records-your-future-self-will-thank-you-for-18ii", "published_at": "2026-07-14 03:37:38+00:00", "updated_at": "2026-07-14 03:56:31.365013+00:00", "lang": "en", "topics": ["artificial-intelligence", "developer-tools", "large-language-models"], "entities": ["Michael Nygard", "Spotify", "Thoughtworks", "GitHub", "Claude", "GPT-4", "Gemini"], "alternates": {"html": "https://wpnews.pro/news/adr-template-how-ai-generates-architecture-decision-records-your-future-self-you", "markdown": "https://wpnews.pro/news/adr-template-how-ai-generates-architecture-decision-records-your-future-self-you.md", "text": "https://wpnews.pro/news/adr-template-how-ai-generates-architecture-decision-records-your-future-self-you.txt", "jsonld": "https://wpnews.pro/news/adr-template-how-ai-generates-architecture-decision-records-your-future-self-you.jsonld"}}