adr.zone

ADRs when your team uses LLMs

Large language models are useful for exploration and draft text; they are not a substitute for an agreed process, a merge review, or a durable record. ADRs still live in the same place as before: version control, as small Markdown documents your team owns and reviews.

Why keep ADRs in an LLM-heavy workflow

  • Grounding. An ADR gives humans (and tools) a stable statement of what was decided, by whom, and under which constraints, separate from day-to-day chat or generated snippets.
  • Token discipline. Pasting a short ADR (or a link to a file in the repo) into a model’s context is cheaper and clearer than re-explaining history on every request.
  • Reviewability. A PR that adds or changes an ADR is reviewable the same way as code. Generated prose should still pass that bar.

The line between drafting and deciding

LLMs can help draft the text, but an ADR records a human judgment, not a generation. The value is in the thinking, not the output. A model that writes plausible prose about tradeoffs it has never lived through is not making a decision; your team is.

What to avoid

  • Treating model output in a thread as a “decision” without a committed ADR in the repo.
  • Letting the model invent past decisions: always verify against the actual ADR files, tickets, and owners.
  • Dumping an entire monolith into a prompt instead of the narrow context (interfaces, invariants) that a decision should reference.

Practical patterns

  1. Draft, then human-edit. Use the generator or your template, paste a rough draft from a model if useful, and tighten for your team’s voice and scope before merge.
  2. One ADR per real decision. The same “small and durable” rule as without LLMs: avoid mega-documents that no one rereads.
  3. Link out. Reference issues, SLOs, and security notes by URL or ID. Models can help draft those cross-links; humans should confirm.
  4. Regenerate later. If you adopt a new format, older ADRs do not have to be rewritten for AI, only when the decision is still relevant to restate in a clearer shape.

HTTP API for agents and scripts

If you want an LLM or a CI job to emit ADRs in a known shape, call the same stateless JSON API the site documents on Public API. There is no sign-up: send JSON, receive Markdown (and a suggested slug) in the response. Use it when you need repeatable structure instead of asking the model to invent headings on every run.

  1. Discover fields. GET https://www.adr.zone/api/formats returns each format id plus required and optional field names for POST /api/generate-adr.
  2. Generate Markdown. POST https://www.adr.zone/api/generate-adr with Content-Type: application/json, a format (for example nygard), and a JSON object whose keys match those fields. The response includes markdown and slug.
  3. Machine-readable contract. Fetch OpenAPI 3.0 or open the try panel on the API page to inspect example bodies and errors (429 rate limit, 413 body size limit).

Minimal example (Nygard fields, default format is nygard if omitted):

curl -s -X POST "https://www.adr.zone/api/generate-adr" \
  -H "Content-Type: application/json" \
  -d '{"format":"nygard","title":"Use PostgreSQL for new services","context":"We need one default DB.","decision":"Default to PostgreSQL 15+ for new stateful services.","consequences":"MySQL stays until migrated."}'

Full endpoint list, per-format required fields, and a browser try panel: adr.zone public HTTP API.

Related on this site