architecture-decision-records
Record a significant technical or accessibility decision as a short decision record — context, the choice, the alternatives rejected and why, consequences — and file it in rinnegan's decision store or the project's ADR directory. Use when the user picks between frameworks, storage, API styles, auth strategies or patterns, says "we decided" or "record this decision", or asks why an earlier choice was made.
- License 许可
- MIT
- 最近更新
- 2026-09-25
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- architecture-decision-records
- description
- Record a significant technical or accessibility decision as a short decision record — context, the choice, the alternatives rejected and why, consequences — and file it in rinnegan's decision store or the project's ADR directory. Use when the user picks between frameworks, storage, API styles, auth strategies or patterns, says "we decided" or "record this decision", or asks why an earlier choice was made.
- allowed-tools
- [ "Read", "Grep", "Glob", "Write" ]
03 SKILL.md 正文
Architecture Decision Records
Purpose
Turn a decision that was made in conversation into a durable record that explains itself a year later. The skill writes one file per decision, after the user has seen the draft; it does not make decisions, and it does not record trivia.
Trigger Conditions
Use it when a choice with lasting consequences is settled: a technology, a data model, an API shape, a
deployment or security approach, a testing strategy, a process rule — or an accessibility commitment such as a
colour-contrast floor, a keyboard-navigation rule or a screen-reader labelling convention. Use it read-only when
the user asks "why did we choose X": search existing records first (recalling-context owns broad recall).
Do not record naming, formatting or one-off implementation choices.
Where Records Live
| Store | Path | When |
|---|---|---|
| rinnegan (default) | ${CLAUDE_PLUGIN_DATA}/projects/<key>/decisions/<NNNN>-<slug>.md |
Always available |
| Project | <project-root>/docs/adr/<NNNN>-<slug>.md plus a row in docs/adr/README.md |
Exists, or user asks |
<key> is read from ${CLAUDE_PLUGIN_DATA}/projects.json by the project's absolute root. Confirm before creating
docs/adr/.
Numbers are four digits, scanned from the chosen store and incremented; never reuse one. Writes go nowhere else.
Record Format
# 0007: <Decision as a sentence>
Date: YYYY-MM-DD | Status: proposed | accepted | deprecated | superseded by 0012 | Kind: architecture | accessibility
## Context
The forces at work — the problem, the constraints, who is affected. Two to five sentences.
## Decision
What is done, in the present tense, in one to three sentences.
## Alternatives
For each option that lost: what it offered, what it cost, and the specific reason it was not taken.
## Consequences
What becomes easier, what becomes harder, and the risk carried with its mitigation.
For an accessibility decision (Kind: accessibility) the Context names the users and assistive technologies
affected and the criterion or standard being met or knowingly missed, the Decision states the rule the codebase
now follows, and the Consequences name what must be checked in review so the commitment survives. The structure
is otherwise identical: accessibility choices are architecture, and they are recorded the same way.
Workflow
- Notice the decision moment — an explicit "let's go with", a comparison that reached a verdict, or a request. When the signal is implicit, propose recording rather than assuming.
- Grep the existing decision titles for the same subject. If one exists, offer to supersede it instead of adding a duplicate; a superseded record gets its status updated to point at the new number.
- Extract the choice, the context, at least one rejected alternative with its reason, and honest consequences. "We just picked it" is not a rationale; ask for the reason before writing.
- Assign the next number and slug, draft the record, and show it to the user.
- Write the file only after the user approves; if they decline, discard the draft. Then say the path, and note
that
/rinnegan:capturewill index it as adecisionrecord. - For "why did we choose X": grep the store for X, present Context and Decision of the matches, and if nothing matches say so and offer to record it now.
Safety Checks
- Never write before the user has seen the draft and agreed; never create
docs/adr/unasked. - A record holds reasons, not secrets: refer to credentials or endpoints by location and type only.
- Backfilled decisions carry their original date and say they were recorded later.
Output Contract
- Decision — number, title, status, kind, and the path written (or "not written" and why)
- Superseded — any earlier record whose status changed
- Open — anything the user still has to settle before the status can move to accepted
04 同仓库更多 Skills
good-skill
Fixture - a skill whose name equals its directory and whose description clears the forty-character floor (N-2).
wrong-name
Too short.
<skill-name>
<What the skill does, then the situations that should trigger it. Concrete and situational, third person, never marketing. Minimum 40 characters — this text is the auto-invocation surface (N-2).>
writing-plans
Turns an agreed design or spec into a step-by-step implementation plan that an engineer with no context could execute. Use when a multi-step change is understood well enough to sequence but no plan exists yet, before touching code. Produces a plan file with exact paths, test-first steps, interfaces between tasks, and no placeholders.
verification-before-completion
Gate that runs before any claim that work is done, fixed, passing, or shipped. Identifies the command that would prove the claim, runs it fresh, reads the whole output, and only then reports — with the evidence attached and any gap stated. Use before committing, opening a pull request, marking a task complete, or telling the user something works.
using-skills
Session discipline that fires before the first action of any task. Checks whether an installed skill or command already covers the job, keeps every action inside the requested scope, and reports verification as evidence rather than confidence. Use at the start of a conversation, before answering a question, before exploring a codebase, and whenever a task changes shape mid-session.