What is architecture-decision-records?

A manager for Architecture Decision Records, which are documents that explain important technical choices, their context, alternatives, and reasoning.

Use it to list, search, and create records for framework, database, security, infrastructure, API, and integration decisions.

It preserves why major design decisions were made, making them easier to review and understand when the system changes.

architecture-decision-records — Skill for Claude Code by tranhieutt

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.

Any agent

npx skills add tranhieutt/software_development_department --skill architecture-decision-records

Clone the repo

git clone --depth 1 https://github.com/tranhieutt/software_development_department

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/skills/tranhieutt/software_development_department/architecture-decision-records/github.svg)](https://agentmods.dev/skills/tranhieutt/software_development_department/architecture-decision-records)

Your own site

<a href="https://agentmods.dev/skills/tranhieutt/software_development_department/architecture-decision-records"><img src="https://agentmods.dev/badge/skills/tranhieutt/software_development_department/architecture-decision-records/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/skills/tranhieutt/software_development_department/architecture-decision-records"><img src="https://agentmods.dev/badge/skills/tranhieutt/software_development_department/architecture-decision-records.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 49 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 1,068 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

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.

Model	Per session	Once invoked
Fable 5.1	$0.00049	$0.01068
Opus 5	$0.00024	$0.00534
Sonnet 5	$0.00010	$0.00214
Haiku 4.5	$0.00005	$0.00107

Measured 12d ago against content hash 1232f50d2520, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-12, from the pricing page.

Security

Grade A, and why

architecture-decision-records 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 12d ago.

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.

.claude/skills/architecture-decision-records/SKILL.md · 143 lines

How it starts

The opening of the file, as written. The whole thing — 143 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Architecture Decision Records

Workflow Protocol

Determine the next ADR number by scanning docs/internal/adr/ for existing ADRs.
Run the decision-ledger read gate before drafting: /trace-history --risk High --last 20. Include relevant prior decisions, or state that no relevant high-risk prior decision was found.
Gather context by reading related code and existing ADRs.
Guide the user through the decision by asking clarifying questions if the title alone is insufficient.
Generate the ADR following the template below.
Save the ADR to docs/internal/adr/ADR-[NNN]-[slug].md.
Update the Index Table in docs/technical/DECISIONS.md.

When to write an ADR vs skip

Write ADR	Skip ADR
New framework/database adoption	Minor version upgrades
API design patterns	Bug fixes
Security architecture	Implementation details
Integration patterns	Routine maintenance

ADR lifecycle

Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected

Template (MADR format — use this)

# ADR-NNN: [Title]

## Status
Accepted | Proposed | Deprecated | Superseded by ADR-NNN

## Context
[Problem statement, current situation, constraints, scale]

## Prior Decision Check
[Result of `/trace-history --risk High --last 20`; cite relevant prior entries
or state "No relevant prior high-risk decisions found."]

## Decision Drivers
- [Must/Should/Could requirement]

## Considered Options
### Option 1: [Name] — [one-line summary]
Pros: ... | Cons: ...

### Option 2: [Name]
Pros: ... | Cons: ...

## Decision
We will use **[Option N]** because [key rationale].

## Consequences
**Positive:** ...
**Negative:** ...
**Risks:** ... Mitigation: ...

## Related ADRs
- ADR-NNN: [relationship]

Quick examples

Lightweight ADR (for clear-cut decisions):

# ADR-0012: Adopt TypeScript for Frontend

**Status**: Accepted | **Date**: 2024-01-15 | **Deciders**: @alice, @bob

## Context
50+ React components with prop-type-mismatch bugs. PropTypes are runtime-only.

## Decision
TypeScript for all new frontend code. Migrate incrementally with `allowJs: true`.

## Consequences
Good: Compile-time errors, better IDE support.
Bad: Learning curve, initial slowdown.

Read the full file on GitHub · 143 lines

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.

12d ago First seen · 143 lines · 49 tokens per session scan A 1232f50d2520

Subscribe to this mod's changes

architecture-decision-records is a skill published in the GitHub repository tranhieutt/software_development_department (72 stars, last pushed 4mo ago), licensed MIT. It adds 49 tokens to every session and 1,068 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-30.

Planning Writing and docs antigravity-skills brainstorming claude claude-skills harness-engineering human-in-the-loop

playwright-cli

Automates browser interactions for testing and validating your own web applications using playwright-cli. Use when you need terminal-first browser control for navigation, form filling, screenshots, tracing, bound browser sessions, debugging, or generating Playwright test code. Only use against applications you own or…

testdino-hq/playwright-skill · 64 tokens

architecture-decision-records