--- name: stellata-adr description: Manage Architecture Decision Records (ADR) under docs/decisions/. Use /stellata-adr new|supersede|deprecate|find to create, replace, retire, or look up project design decisions. Invoke proactively when a design decision is made or when discussing prior decisions. allowed-tools: Read, Write, Edit, Glob, Grep, Bash --- # stellata-adr Skill ## Role You are a specialized skill for maintaining `docs/decisions/` — the canonical Architecture Decision Records (ADR) of this project. ADR は **プロジェクトについての細かな決定事項に関する Claude Code の長期記憶** として育てる。 ## Core Mission - 新規 ADR の起草 (`new`): 連番採番・テンプレ展開・INDEX 同期・SERVICE.md 同期を機械化 - 既存決定の置換 (`supersede`): `documentation_protocol.md` の 9 ステップを **不変条件付きで** 実行 - 廃止 (`deprecate`): 代替なし廃止フロー - 検索 (`find`): INDEX → 本文 → supersede chain を辿った要約 **Success Criteria:** - 古い ADR の本文 (コンテキスト・決定・結果) は **絶対に書き換えない** - INDEX.md / SERVICE.md / ADR 本文の整合が常に保たれる - 連番に重複・欠番が起きない - `documentation_protocol.md` の ADR 章 §「既存の決定を変更する場合」と §「廃止」の手順を厳密に再現する ## Invocation `/stellata-adr [args]` | Subcommand | 用途 | 例 | |---|---|---| | `new ""` | 新規 ADR ドラフト作成 | `/stellata-adr new "Backtest を HTTP ではなくライブラリ直呼びにする"` | | `supersede NNNN ""` | 既存 ADR を新 ADR で置換 (9 ステップ実行) | `/stellata-adr supersede 0007 "Redis Streams から NATS に移行"` | | `deprecate NNNN ""` | 代替なし廃止 | `/stellata-adr deprecate 0012 "該当機能を削除した"` | | `find ""` | キーワード / タグ / サービスで関連 ADR を検索 | `/stellata-adr find "ml-inference"` | 引数なし or 未知のサブコマンドの場合は、使い方サマリを返す。 ## Pre-execution Checklist (全サブコマンド共通) 1. `.kiro/steering/custom/documentation_protocol.md` の ADR 章を **必ず読む** (信頼できる唯一の正本) 2. `docs/decisions/INDEX.md` を Read 3. `docs/decisions/_0000-example-decision.md` をテンプレ参照として Read 4. 作業を進める前に「これから何をするか」をユーザーに 1 文で宣言する これらが終わるまでファイル書込はしない。 ## Subcommand: `new` ### 目的 新規 ADR を起草し、テンプレ通りに記述してから INDEX と関連 SERVICE.md に紐付ける。 ### 手順 1. **連番採番** - `docs/decisions/*.md` の `_0000-example-decision.md` を除く全ファイル名から最大番号を抽出 - 次番号 = 最大 + 1 (4 桁ゼロ埋め) - INDEX.md の既存行も照合し、重複しないことを確認 (採番事故防止) 2. **slug 生成** - `` を kebab-case に変換 (英数字 + ハイフン、最大 60 文字) - 例: `"Backtest を HTTP ではなくライブラリ直呼びにする"` → `backtest-library-direct-import` (ユーザーに確認) 3. **対話的フィールド収集** - 既に会話文脈に十分な情報がある場合はドラフトを直接生成 - 不足している場合は **以下を 1 度にまとめてユーザーに確認** (個別質問の連打はしない): - タイトル (一文) - コンテキスト (なぜこの判断が必要か、1-3 段落) - 検討した選択肢 (採用 + 却下 ≥2 つ。1 案しかない ADR は禁止) - 決定内容と理由 - 結果 (ポジティブ / ネガティブ / 影響範囲) - タグ (`#xxx` 形式、複数可) - 関連サービス (`services//` の name、複数可) - 関連 ADR (既存 ADR 番号、任意) - **関連 Deferred Task** (起票元が Deferred Task の cancel (B/C パターン) の場合は必須。形式: `Cancels: DEF-NNNN`) 4. **関連 Deferred Task 検索 (自発)** - 起票元の会話が「DEF-NNNN の cancel 議論から派生した」場合、ユーザーに DEF 番号を確認 - 不明な場合でも `grep -i "" docs/deferred/INDEX.md` で関連 DEF を探索 (起票漏れ防止) - 関連 DEF が見つかった場合、本 ADR の「関連 Deferred Task」欄に `Cancels: DEF-NNNN ()` を記載し、「コンテキスト」セクションで経緯を 1-2 文言及 5. **ファイル作成** - パス: `docs/decisions/NNNN-.md` - テンプレ (`_0000-example-decision.md`) の構造を厳密に踏襲 - `Status: proposed` で初期化 (ユーザーが accepted を明言したら `accepted` に) - 日付: 今日の日付 (UTC ベース) - **テンプレの 1 行目の注記 "これは ADR のテンプレートファイル..." はコピーしない** 6. **INDEX.md 更新** - 「ADR 一覧」テーブルに 1 行追記: `| [ADR-NNNN](./NNNN-.md) | | <status> | <tags> | <services> | <YYYY-MM-DD> |` - 該当する「カテゴリ別ショートカット」節があれば ADR 番号を追記 - 新カテゴリが必要な場合は新節を追加 (重複は作らない) 7. **SERVICE.md 同期** - 関連サービスの `services/<name>/SERVICE.md` を Read - 「関連 ADR」セクションがあれば 1 行追記。なければユーザーに「セクションを新設しますか?」と確認のうえ追加 - 複数サービスがある場合は全て同期 (片落ち禁止) 8. **Deferred Task 同期 (`Cancels: DEF-NNNN` を記載した場合)** - 対象 DEF (`docs/deferred/NNNN-*.md`) を Read - DEF の `Status:` を `cancelled` に変更 (まだ `pending` の場合) - DEF の「関連 ADR」欄に本 ADR (ADR-MMMM) を追記 - DEF の「履歴」セクションに `- YYYY-MM-DD: cancelled (B|C) — ADR-MMMM 起票により取消` を追記 - `docs/deferred/INDEX.md` の status 列も `cancelled` に同期更新 - これにより DEF ↔ ADR の双方向リンクが完成する 9. **完了報告** - 作成パス・採番した番号・更新した INDEX 行・更新した SERVICE.md ファイル一覧をユーザーに返す - Deferred Task と連動した場合は同期した DEF 番号も併記 - `proposed` のままにした場合は「accepted への昇格は実装着手・レビュー完了後にユーザーが指示してください」と添える ### 禁止事項 - 1 案しかない ADR の作成 (Options Considered は最低 2 案必須。1 案しか思い浮かばない場合は「却下した暗黙の対案」を文章化させる) - INDEX 行を書かずに ADR 本体だけ作ること - 採番ロジックの省略 (会話文脈から「たぶん次は NNNN」と推測しない。必ず `Glob` / `Bash ls` で確認する) ## Subcommand: `supersede` ### 目的 古い決定を新しい ADR で置換する。`documentation_protocol.md` §「既存の決定を変更する場合」の **9 ステップを機械的に実行** する。 ### 不変条件 (絶対に破ってはいけない) - 古い ADR の **本文 (コンテキスト・決定・結果)** は 1 文字も変更しない - 古い ADR で書き換えてよいのは **Status 行** と **末尾の `Superseded by:` 1 行追加** のみ - 新旧両 ADR の整合性チェック (双方向リンク) を完了報告前に確認する ### 手順 1. **入力検証** - `docs/decisions/NNNN-*.md` が実在することを確認 - 既に `superseded-by-MMMM` の Status なら「既に supersede 済み」と返してユーザー確認 2. **新 ADR 起草** (`new` サブコマンドの手順 1〜4 を実行) - ただしテンプレの「関連 ADR」に `Supersedes: ADR-NNNN` を必ず明記 - 「検討した選択肢」に **「旧 ADR-NNNN の決定を継続」** を必ず含め、却下理由を書く（手順 4) - 「コンテキスト」で **なぜ過去の決定を覆すのか** を必ず説明 (手順 3) 3. **古い ADR 更新** (本文は不変・以下 2 点のみ) - 1 行目近辺の `Status:` を `superseded-by-MMMM` に変更 - 末尾に `Superseded by: ADR-MMMM (YYYY-MM-DD)` を 1 行追加 (ヘッダ部または末尾、テンプレに従う) 4. **INDEX.md 更新** - 新 ADR の行を追加 - 旧 ADR の Status 列を `superseded-by-MMMM` に変更 - 両方ともカテゴリショートカットを更新 5. **SERVICE.md 同期** - 旧 ADR の関連サービス + 新 ADR の関連サービス両方の SERVICE.md を更新 - 旧 ADR 参照行に「(superseded by ADR-MMMM)」注釈を併記、新 ADR 行を追加 6. **完了報告** - 変更ファイル一覧 + 9 ステップそれぞれの実行有無チェックリスト形式で返す ### 禁止事項 - 古い ADR の本文 (Status と末尾 1 行を除く) への一切の変更 - 旧 ADR を削除すること - 双方向リンク不整合 (旧の Status と新の Supersedes が片方しか書かれていない状態) のまま完了報告すること ## Subcommand: `deprecate` ### 目的 代替なしで決定を廃止する (該当機能自体を削除したなど)。 ### 手順 1. 古い ADR を Read。既に `deprecated` の場合は終了 2. Status を `deprecated` に変更 3. 末尾に `Deprecated on: YYYY-MM-DD` + 廃止理由を追記 4. **本文 (コンテキスト・決定・結果) は変更しない** 5. INDEX.md の Status 列を `deprecated` に更新 6. 関連 SERVICE.md の「関連 ADR」セクションに `(deprecated)` 注釈を追加 ## Subcommand: `find` ### 目的 プロジェクトに関する会話で過去の決定を引き出す Claude Code の長期記憶アクセス。 ### 手順 1. **INDEX を多面検索** ```bash grep -iE "<query>" docs/decisions/INDEX.md ``` - タグ (`#xxx`) / サービス名 / タイトルキーワード / 日付の全てを対象 - ヒットなしの場合は ADR 本文全体を grep (`grep -irl "<query>" docs/decisions/`) 2. **ヒットした ADR を Read** - 一気に 3-5 件まで読む。それ以上は要求しすぎなのでユーザーに絞り込みを依頼 3. **supersede chain を辿る** - Status に `superseded-by-NNNN` があれば後続 ADR も Read - 最新の有効 (`accepted`) ADR を「現在有効な決定」として最初に提示 4. **関連 Deferred Task を辿る** - ADR 本文に `Cancels: DEF-NNNN` の記載があれば、`docs/deferred/NNNN-*.md` も Read - 「もともとこの DEF として保留にしていたが、ADR-NNNN で取消・代替採用された」経緯を応答に含める (議論の再燃防止) 5. **応答フォーマット** ```markdown ## 関連 ADR (現在有効) - **ADR-NNNN**: <タイトル> (accepted, YYYY-MM-DD) - 決定: <1-2 文要約> - 関連サービス: <list> - 関連 DEF: DEF-MMMM (cancelled — 当 ADR で取消) ※ あれば - 参考: docs/decisions/NNNN-<slug>.md ## 関連 ADR (過去・supersede 済み) - ADR-MMMM: <タイトル> (superseded-by-NNNN) - 当時の決定: <1 文> ## 該当なしの場合 - INDEX に該当 ADR なし。新規 ADR 候補としてセクション §A トリガー判定に戻る。 ``` ### 禁止事項 - ADR を要約する際に「決定の本質」を変えるような言い換えをすること (引用元番号は必ず併記) - `find` の結果として ADR ファイルを編集すること (検索は read-only) ## 共通ルール ### 連番採番の信頼性 - 採番は `Glob docs/decisions/*.md` + ファイル名先頭 4 桁の最大値で確定する - `_0000-example-decision.md` の `_` プレフィックスは「テンプレ・連番外」を意味するため採番計算から **必ず除外** する - 採番後に同番 ADR が既に INDEX に書かれていないかも併せて検証する (sanity check) ### slug 命名 - kebab-case、英数字とハイフンのみ - 60 文字以内 (ファイル名トータル `NNNN-<slug>.md` で約 70 文字以内) - 既存 slug との重複は許容しない ### Status の遷移 ``` proposed → accepted → (superseded-by-NNNN | deprecated) ``` `proposed` のままで実装を進めるのは原則禁止 (ユーザーが明示的に承認したら `accepted` に上げる)。 ### 失敗時のロールバック - ファイル作成・編集の途中でエラーが起きた場合、**INDEX.md と SERVICE.md の更新を完了させてから** 完了報告する - 中途半端な状態 (ADR は作ったが INDEX に書いていない 等) で終わらせない ## 出力例 (new サブコマンド) ``` ADR 起票完了 ## 作成 - docs/decisions/0007-backtest-library-direct-import.md (Status: proposed) ## 更新 - docs/decisions/INDEX.md (ADR 一覧に 1 行追加、#architecture / #backtest カテゴリに追記) - services/backtest/SERVICE.md (関連 ADR セクションに追加) - services/analysis-engine/SERVICE.md (関連 ADR セクションに追加) ## 次のアクション - レビュー完了後、`/stellata-adr` 経由ではなく該当 ADR ファイルの Status 行を `accepted` に書き換えてください (proposed → accepted の昇格は本 Skill 経由を必須としません) ``` ## 参考 - 正本: `.kiro/steering/custom/documentation_protocol.md` §「ADR (Architecture Decision Records) の運用」 - テンプレ: `docs/decisions/_0000-example-decision.md` - INDEX: `docs/decisions/INDEX.md` - トリガー検知: `documentation_protocol.md` §「Claude Code 行動ルール」§ A / B / C