adr-workflow
Standard procedure for documenting architectural decisions using ADRs.
Install
mkdir -p .claude/skills/adr-workflow && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/15976" && unzip -o skill.zip -d .claude/skills/adr-workflow && rm skill.zipInstalls to .claude/skills/adr-workflow
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
設計判断・プロセス決定をADR (Architecture Decision Record) として作成・更新する具体的な手順。Use this skill whenever the user asks to record a decision, write an ADR, or says ADRを書きたい, 設計判断を記録したい, ADR作って, この決定を残したい.Key capabilities
- →Create new Architecture Decision Records (ADRs)
- →Update existing ADRs by changing their status
- →Maintain the ADR documentation registry
- →Determine the next sequential number for a new ADR
- →Copy a template to create a new ADR file
- →Link related design documents to ADRs
How it works
This skill provides a procedure for creating and updating Architecture Decision Records (ADRs) by following a template, assigning sequential numbers, and updating the ADR registry, while adhering to immutability rules for finalized decisions.
Inputs & outputs
When to use adr-workflow
- →Record architectural decision
- →Write new ADR
- →Supersede old decision
- →Maintain ADR log
About this skill
ADR Workflow
ADRの運用ルールの全体像は docs/adr/README.md を参照。
このskillは「今まさにADRを1本書く/更新する」ときの実務手順をまとめたもの。
いつADRを書くべきか
以下のいずれかに該当する決定は、口頭やコミットメッセージだけで済ませず、ADRとして残す。
- アーキテクチャ・プロジェクト構成に関わる決定（例: 層構成、依存方向、主要ライブラリ選定）
- 開発プロセス・ツールに関わる決定（例: テストフレームワーク、モデルルーティング方針）
- 一度決めたら覆すコストが高い決定（データ永続化方式、外部連携方式など）
逆に、些細な実装詳細（変数名、内部のprivateメソッド分割など）はADR化しない。
手順
.github/agents/adr-writer.agent.mdを使うか、以下を手動で行う。docs/adr/の既存ファイル名から次の連番を決める（歯抜けにしない）。docs/adr/template.mdをコピーして新規ファイルを作成。Context/Decision/Consequencesを埋める（docs/adr/README.mdの 不変性ルールを厳守: 一度書いたら本文は書き換えない）。docs/adr/README.mdの一覧表に1行追加する （内容判断が完了した後の目次反映のみであれば、 ADR-0008によりquick-fixagentに委譲してよい）。- 関連する
docs/design/のドキュメントがあれば、そこから今回のADRへリンクを追加する。
既存の決定を覆す場合
- 古いADRの本文は変更しない。
StatusだけをSuperseded by ADR-YYYYに変更する。 - 新しいADRの
Contextに「なぜADR-XXXXを置き換えるのか」を書く。 docs/adr/README.mdの一覧表のStatus列も更新する。
rubber-duckとの関係
決定内容自体に自信がない場合は、ADRを書く前に task ツールで agent_type: "rubber-duck" を使い、
決定の妥当性をレビューしてから起票する（feature-workflow の
詳細設計フェーズと同じ扱い）。
When not to use it
- →When decisions are trivial implementation details (variable names, internal private methods)
- →When the decision does not involve architecture, project structure, or development processes
- →When the cost to reverse a decision is not high
Limitations
- →ADR content (Context, Decision, Consequences) is immutable once written
- →Only the `Status` field of old ADRs can be changed when superseded
- →Requires manual steps or use of `adr-writer.agent.md`
How it compares
This skill formalizes the process of documenting architectural and process decisions using ADRs, ensuring consistency and traceability, which differs from informal decision-making or ad-hoc documentation.
Compared to similar skills
adr-workflow side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| adr-workflow (this skill) | 0 | 1mo | No flags | Intermediate |
| project-planner | 32 | 10mo | Review | Intermediate |
| spec-kit-workflow | 11 | 8mo | No flags | Intermediate |
| specification-architect | 13 | 9mo | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by runceel
View all by runceel →You might also like
project-planner
adrianpuiu
Comprehensive project planning and documentation generator for software projects. Creates structured requirements documents, system design documents, and task breakdown plans with implementation tracking. Use when starting a new project, defining specifications, creating technical designs, or breaking down complex systems into implementable tasks. Supports user story format, acceptance criteria, component design, API specifications, and hierarchical task decomposition with requirement traceability.
spec-kit-workflow
jmanhype
Guides specification-driven development workflow. Automatically invoked when discussing new features, specifications, technical planning, or implementation tasks. Ensures proper workflow phases (specify → clarify → plan → checklist → tasks → analyze → implement).
specification-architect
adrianpuiu
A rigorous, traceability-first system that generates five interconnected architectural documents (blueprint.md, requirements.md, design.md, tasks.md, and validation.md) with complete requirements-to-implementation traceability. Use this skill when users need to architect systems, create technical specifications, or develop structured project documentation with guaranteed traceability.
architecture
davila7
Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.
context-driven-development
wshobson
Use this skill when working with Conductor's context-driven development methodology, managing project context artifacts, or understanding the relationship between product.md, tech-stack.md, and workflow.md files.
planning-agent
parcadei
Planning agent that creates implementation plans and handoffs from conversation context