Architecture Decision Record Extraction Prompt Template

This prompt is designed for platform engineers and tech leads who need to reconstruct the architectural decision history of an existing codebase. The primary job-to-be-done is onboarding: when new developers join a team, they need to understand not just what the code does, but why specific architectural choices were made. This prompt automates the discovery of that rationale by scanning repository artifacts—commit messages, pull request discussions, design documents, code comments, and configuration files—to identify decisions and produce structured Architecture Decision Records (ADRs). It is a forensic tool for extracting institutional knowledge that was never formally documented.

Use this prompt when you have a repository with a meaningful history of changes and discussions but lack formal ADRs. The prompt requires access to a rich context: a codebase with a non-trivial git log, pull request threads with substantive debate, inline code comments that explain workarounds or trade-offs, and design documents stored in the repository. The output is a set of structured ADRs, each containing a title, context, decision, consequences, and a list of traceable source references (e.g., commit SHAs, PR numbers, file paths with line annotations). This traceability is the core value proposition—every architectural claim must be grounded in evidence, not inferred from thin air. Do not use this prompt for greenfield projects where no decisions have been made yet, or for generating aspirational ADRs from scratch without repository evidence. It is also unsuitable for repositories with squashed git histories or those that lack any form of design discussion in their artifacts.

Before running this prompt, ensure you have assembled the repository context into a format the model can consume. This typically means providing a concatenated dump of relevant git log entries, PR descriptions, markdown design docs, and key configuration files. The prompt works best when you constrain the scope to a specific architectural domain (e.g., database choices, API design, or service boundaries) rather than asking it to extract every decision from the entire codebase at once. After generation, every ADR must pass a human review step where a senior engineer verifies that the cited sources actually support the stated decision and rationale. The next step is to integrate these generated ADRs into your project's docs/decisions/ directory and treat them as living documents that can be refined as new context emerges.

This prompt template is designed to be pasted directly into your AI coding agent or LLM workflow. It instructs the model to act as a software architect analyzing a repository to retroactively produce Architecture Decision Records (ADRs). The template uses square-bracket placeholders that you must replace with actual values before execution. The core job is to transform unstructured signals—commit messages, pull request discussions, code comments, and design documents—into a structured, traceable decision log.

markdownCopy
You are a senior software architect tasked with extracting Architecture Decision Records (ADRs) from a repository's history and context. Your goal is to produce a set of structured, evidence-backed ADRs that explain the key technical decisions made in this codebase.

## Input Context
You will be provided with the following repository context. Analyze it carefully to identify architectural decisions.
- **Repository Summary:** [REPOSITORY_SUMMARY]
- **Relevant Commit History:** [COMMIT_HISTORY]
- **Pull Request Discussions:** [PR_DISCUSSIONS]
- **Design Document Excerpts:** [DESIGN_DOC_EXCERPTS]
- **Key Code Comments/Annotations:** [CODE_COMMENTS]

## Output Schema
For each distinct architectural decision you identify, generate a JSON object conforming to this schema. Return a JSON array of these objects.
{
  "adrs": [
    {
      "title": "string (concise decision title)",
      "status": "string (proposed | accepted | deprecated | superseded)",
      "context": "string (the problem, forces, and constraints that led to this decision)",
      "decision": "string (the specific architectural choice that was made)",
      "consequences": "string (the resulting context, both positive and negative)",
      "evidence": [
        {
          "source_type": "string (commit | pr_discussion | design_doc | code_comment)",
          "source_reference": "string (e.g., commit hash, PR number, file path and line)",
          "excerpt": "string (the direct quote or summary of the evidence)"
        }
      ]
    }
  ]
}

## Constraints
- [CONSTRAINTS]
- Only create an ADR if you have sufficient evidence from the provided context. Do not fabricate decisions.
- If a decision is clearly documented but its status is ambiguous, default to "accepted" and note the ambiguity in the consequences.
- Link every ADR to at least one piece of concrete evidence.
- If no architectural decisions can be reliably extracted, return an empty `adrs` array.

To adapt this template, start by populating the [REPOSITORY_SUMMARY] and other context placeholders with data pulled from your actual repository. The [CONSTRAINTS] placeholder is critical for tailoring the output; for example, you might add constraints like Focus only on decisions related to data persistence and API design or Ignore decisions made before 2023-01-01. After running the prompt, you must validate the output by checking that each evidence.source_reference is a real, verifiable link to a commit, file, or PR in your repository. For high-stakes documentation, a human architect should review the generated ADRs for accuracy and completeness before they are committed to the project's decision log.

This prompt is designed to be called programmatically as part of a documentation pipeline, not as a one-off chat interaction. The implementation harness should treat each ADR extraction as a batch job: gather the required context from the repository, assemble the prompt, call the model, validate the output, and store the result. Because ADRs are durable engineering records, the harness must enforce evidence grounding and decision traceability before any output is accepted into the documentation repository.

The harness should assemble the [REPOSITORY_CONTEXT] input from multiple sources: commit messages filtered by architectural keywords (e.g., 'refactor', 'extract', 'introduce pattern'), pull request descriptions and comments from merged PRs, design document fragments from /docs or /rfcs, and inline code comments near module boundaries. Use a retrieval step to gather relevant context before prompt assembly. For model choice, prefer a model with strong reasoning and long-context handling (e.g., Claude 3.5 Sonnet or GPT-4o). Set temperature low (0.0–0.2) to maximize factual consistency. The output must conform to the [OUTPUT_SCHEMA] defined in the prompt template—validate this structurally before accepting the response. If the model returns malformed JSON or missing required fields, retry once with a repair prompt that includes the validation error message. After structural validation, run evidence-grounding checks: for each ADR, verify that the source_references field contains actual commit hashes, file paths, or PR numbers that exist in the repository. Flag any ADR where the decision field cannot be traced to at least one concrete source reference.

Store validated ADRs in a version-controlled directory (e.g., /docs/adr/) with a naming convention like ADR-{NNN}-{slug}.md. Log every extraction run with the prompt version, model used, input context hash, validation results, and any human review flags. For high-risk architectural decisions—those involving security boundaries, data integrity, or system contracts—require human approval before the ADR is merged. The harness should create a draft PR with the generated ADRs and request review from a designated architecture owner. Avoid fully automated merging of ADRs without review; the prompt extracts and structures evidence, but architectural judgment about correctness and completeness remains a human responsibility.