adr-skill

アーキテクチャ上の決定

重要な代替案や影響を伴う、長期にわたって有効なアーキテクチャ上の選択には ADR を使用します。通常の修正や、すでに確立された実装上の選択については、新しい ADR は不要です。対象コードを変更する前に、関連する承認済みの記録を確認してください。

決定を記録する

プロジェクトの指示、既存の決定インデックス、関連する記録、依存関係、影響を受けるコードを確認します。既存の規約を再利用してください。Brain ツリーでは、文章は .svx 形式で記述します。

依頼と情報源から意図を読み取ります。正確な記録を妨げる判断事項が不足している場合に限り、質問してください。確定済みの決定を記録する依頼では、事前の聞き取りや確認のやり取りは不要です。承認されていない選択肢は proposed のままにしてください。キュー内で最上位にあるというだけで、承認済みにしてはいけません。

きっかけ、制約、検討した代替案、選択した案、影響、対象外の事項、見直しの条件を記録します。ユーザーの決定とエージェントの推奨を区別してください。

作成と検証

テンプレートの種類を参照し、assets/templates/ にあるシンプルなテンプレートまたは MADR テンプレートを選びます。実装が対象に含まれる場合は、影響を受けるパス、パターン、実装手順、観測可能な検証方法を記載してください。その作業に実際に必要なスキルだけを挙げます。

下書きの後にレビュー用チェックリストを読みます。情報源に照らして、事実の誤りや記載漏れを修正してください。通常の編集についてではなく、未解決で重要な判断事項について質問します。アーキテクチャの理解に役立つ場合に限り、図を追加してください。使用するツールやスラッシュコマンドは、実行前に確認してください。

ADR を対象コードと実装の証跡にリンクします。該当する境界に短いコード参照を置けば十分です。該当する場合は、既存のインデックスと図のリンクを更新してください。

完了とは、記録に決定とステータス、情報源、影響、実装範囲、検証が正確に記載されていることです。承認済みと捏造せず、未解決の問題を報告してください。

ライフサイクル

承認、却下、非推奨化、または置き換えには、ユーザーの許可とプロジェクトのステータス規約を適用します。履歴は保持してください。置き換える場合は、双方の記録から相互にリンクします。実装を確認し、その検証を記録してから、出荷済みにしてください。

依頼に含まれていない限り、トラッカーの作成と実装は別の作業です。次に取り組む proposed の ADR を選んでも、承認や実行が許可されたことにはなりません。

既存の JoelClaw ADR ストアでは、同期イベントは system/adr.sync.requested、ソースは adr-skill です。イベントを発行する前に、現在の担当ハンドラーを確認してください。それ以外では、プロジェクト独自のインデックス作成手順を使用します。ローカルの下書きがあるからといって、無関係なフリート全体の同期を正当化することはできません。

ツールと参考資料

使用前に、最新のヘルプを確認してください。

• scripts/new_adr.js：テンプレートから作成し、任意でインデックスを更新します。
• scripts/set_adr_status.js：記録のステータスを更新します。
• scripts/bootstrap_adr.js：依頼された場合に ADR の規約を初期化します。
• ADR の規約：命名、ステータス、ライフサイクル。
• 例：完成した記録。

次の ADR の検索を依頼された場合は、joelclaw vault adr --help を確認します。候補を準備状況と価値に基づいて順位付けし、すでに出荷済みかどうかを確認してください。