adr

A template for an Architecture Decision Record, a short document that explains an important software design choice and the reasons behind it.

In plain words
What is it for?
It helps record why a particular approach was chosen, what options were rejected, and what effects the decision has.
Why use it?
It preserves the context, alternatives, constraints, and consequences of a decision so future developers or agents can understand it.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/5uck1ess/devkit/adr
Any agent
npx skills add 5uck1ess/devkit --skill adr
Clone the repo
git clone --depth 1 https://github.com/5uck1ess/devkit

Made for: Claude Code, Codex.

Per session 30 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 478 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00030 $0.00478
Opus 5 $0.00015 $0.00239
Sonnet 5 $0.00006 $0.00096
Haiku 4.5 $0.00003 $0.00048

Measured yesterday against content hash b3590b4d6360, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

adr scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

skills/adr/SKILL.md · 64 lines

What it actually says

ADR — Architecture Decision Record

Capture the why behind architectural decisions so future-you (and future-agents) don't reverse them without context.

Step 1: Gather Context

Identify:

  • What decision was made (or needs to be made)
  • What alternatives were considered
  • What constraints drove the choice
  • What the consequences are

If the user hasn't specified, ask one question: "What decision are you documenting?"

Step 2: Check Existing ADRs

mkdir -p .devkit/docs/adr
ls .devkit/docs/adr/ 2>/dev/null | grep -oE '^[0-9]+' | sort -n | tail -1

Add 1 to the highest number found, zero-padded to 4 digits. If no output, the directory is empty — start at 0001.

Step 3: Write the ADR

Create .devkit/docs/adr/NNNN-short-title.md:

# NNNN. Short Decision Title

**Date:** YYYY-MM-DD
**Status:** accepted | proposed | deprecated | superseded by [NNNN]

## Context

What is the issue? What forces are at play? 2-4 sentences max.

## Decision

What did we decide? State it directly. 1-3 sentences.

## Alternatives Considered

- **Alternative A** — why rejected (1 line)
- **Alternative B** — why rejected (1 line)

## Consequences

What follows from this decision? Both positive and negative. Bullet list.

Rules

  • Keep it short. An ADR is a reference, not an essay. Under 200 words total.
  • One decision per ADR. If there are two decisions, write two ADRs.
  • Use plain language. No jargon that requires context to parse.
  • Status is usually accepted. Use proposed only if the user hasn't decided yet.
  • Never modify the substantive content of existing ADRs (Context, Decision, Alternatives, Consequences). When superseding, only update the old ADR's Status line to superseded by [MMMM].
Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. yesterday First seen · 64 lines · 30 tokens per session scan A b3590b4d6360

Subscribe to this mod's changes

adr is a skill published in the GitHub repository 5uck1ess/devkit (5 stars, last pushed 13d ago), licensed MIT. It adds 30 tokens to every session and 478 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

Other skills, from other repositories