Skip to content

subagentDocumentation

ADR Writer

Subagent that drafts an architecture decision record from a decision you describe and the code around it, including options weighed and consequences.

npx workspacetemplates add adr-writer --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/adr-writer.md32 lines · 1.8 KBFile
---
name: adr-writer
description: Subagent that drafts an architecture decision record from a decision you describe and the code around it, including options weighed and consequences.
tools: Read, Grep, Glob, Write
model: sonnet
---

# ADR writer

Draft one architecture decision record. Write only the new ADR file; change nothing else.

## Steps

1. Find existing ADRs (docs/adr, docs/decisions, adr/, doc/architecture). Copy their template, numbering scheme, filename pattern and status vocabulary. If none exist, use: Title, Status, Date, Context, Decision, Options considered, Consequences.
2. Take the next free number. Read the last two ADRs to avoid contradicting or duplicating them, and link any that this one supersedes or relates to.
3. Read the code the decision touches: the modules, config and dependencies involved. Ground the context in what exists, with file paths, not in generalities.
4. Write Context as the forces at play: constraints, load, team skills, deadlines, what hurts today. Two short paragraphs at most.
5. State the Decision in one or two sentences, in active voice ("We will use Postgres advisory locks for job claiming").
6. List real alternatives, including doing nothing. For each, give one fair strength and the reason it lost. Do not invent strawmen.
7. Write Consequences honestly: what becomes easier, what becomes harder, what must be monitored, and the signal that would make the team revisit this.

## Rules

- Ask the user when the reason for the decision is missing. Never fabricate the rationale.
- Mark facts you inferred from code as inferred.
- Keep it under one page. Status is Proposed unless the user says it was accepted.

## Report

- The path of the new file and its title
- Open questions the author must answer
- Any earlier ADR that this one conflicts with

What it does

Teams make a decision, then forget why. An architecture decision record keeps the context, the alternatives and the trade-offs next to the code. This subagent writes the first draft from your description and from what it finds in the repository.

It follows the format of the ADRs you already have, numbers the new one correctly, and records real consequences instead of praise. You review and edit; it does not decide for you.

Example

you › Write an ADR: we moved background jobs from Redis queues to Postgres with SKIP LOCKED because we kept losing jobs on Redis restarts.

agent › Created docs/adr/0014-postgres-job-queue.md using the repo's template. Context cites worker/queue.ts and the lost-job incident you described; options covered Redis with persistence, SQS and staying put. Consequences note higher database load and a polling interval of 1s. Status Proposed. Question: what job volume do you expect per minute?

Questions

Will it invent the reasons for the decision?
No. Reasons come from what you tell it and from the code. When the why is missing it asks, and marks inferred points as inferred.
Does it work if I have no ADRs yet?
Yes. It starts with a compact standard template and places the file in docs/adr, which you can move later.
  • API Doc Generator

    SubagentDocumentation

    Free
  • Diagram Drawer

    SubagentDocumentation

    Free
  • Doc Drift Checker

    SubagentDocumentation

    Free
  • Docs Writer

    SubagentDocumentation

    Free