| name | adr-workflow |
| description | このリポジトリで、トレードオフを伴う設計判断や運用判断を Architecture Decision Record として docs/adr に作成・更新するときに使う。パッケージ責務、依存方向、セキュリティ境界、リリース方式、外部ツール連携、互換性方針、テスト戦略など、後から理由を参照したい判断に適用する。 |
ADR Workflow
トレードオフを伴う判断を docs/adr/ に記録する。
docs/plans/ は実装ログ、docs/design.md は現在の設計、ADR は判断の理由と代替案を残す文書として扱う。
ADRを書く判断
次の条件を一つでも満たすなら ADR を作る。
- 複数の選択肢があり、どれにも明確なコストがある。
- 将来の実装者が「なぜその方針か」を確認する可能性が高い。
- セキュリティ境界、依存方向、配布、互換性、外部ツール連携、テスト戦略に影響する。
docs/design.md に結論だけを書くと、理由や不採用案が失われる。
通常のバグ修正、局所的なリファクタリング、単純な実装手順だけなら ADR は作らない。
その場合は docs/plans/ の実装ログで足りる。
作成手順
docs/adr/README.md と docs/adr/template.md を読む。- 関連する
docs/design.md、docs/roadmap.md、直近の docs/plans/ を読む。
docs/adr/ の最大連番を確認し、次の NNN-kebab-case-topic.md を作る。docs/adr/template.md を写し、今回の判断に不要なプレースホルダを削る。Status は採用前なら Proposed、採用する変更と同じ PR に入れるなら Accepted にする。- 不採用案は「弱いから」ではなく、どの制約に合わないかを書く。
Consequences には良い影響だけでなく、運用コスト、制約、将来の変更時の注意を書く。- 関連文書への反映漏れを確認する。
更新手順
過去 ADR は判断の履歴として残す。
判断が変わる場合は、既存 ADR を大きく書き換えず、新しい ADR を作って Supersedes と Superseded by を相互に更新する。
軽微なリンク切れや誤字は既存 ADR を修正してよい。
判断の理由、代替案、影響を変える修正は新しい ADR にする。
関連文書
ADR を作ったら、次を点検する。
docs/design.md: 採用済みの現在設計として反映する必要があるか。docs/roadmap.md: フェーズや完了項目として記録する必要があるか。docs/plans/: 実装ログから ADR へリンクする必要があるか。- README: 利用者や開発者に届く説明が変わるか。
.agents/skills/: 今後のエージェント作業の手順を変える必要があるか。
文体
ADR は日本語で書く。
一文ごとに改行し、見出しは具体的な名詞句にする。
「重要」「包括的」「多角的」のような評価語だけで理由を済ませない。
トレードオフは、選択肢ごとに得るものと失うものを明示する。
検証
文書だけの変更でも pnpm format を実行する。
skill を変更した場合は quick_validate.py で SKILL.md の frontmatter を検証する。
