architectural-decisions

Repowise によるアーキテクチャ上の意思決定

Repowise は、アーキテクチャ上の意思決定、つまりコードがどのように構築されているかという背景にある 理由 を記録します。

get_why には 4 つのモードがあります。渡す値に応じて選んでください。

1. get_why(query="why is auth using JWT?") — キーワードとセマンティック検索で意思決定を検索します。
2. get_why(query="src/auth/service.py") — そのファイルを規定する意思決定に加えて、ファイルの来歴と整合性スコア（ファイルが現在も自身の ADR に従っているか）を取得します。
3. get_why(query="why was caching added?", targets=["src/auth/cache.py"]) — ターゲットを基準に検索します。ターゲットに関係する意思決定の優先度が上がります。
4. get_why() — 意思決定の健全性ダッシュボードを取得します。

意思決定は 5 つのソース（ADR ファイル、PR と squash commit の本文、インラインマーカー、Git の履歴調査、中心性で範囲を限定したコードコメント）から抽出されます。各根拠には、ソース内の一字一句そのままの範囲と、exact／fuzzy／unverified のいずれかのスタンプが付与されます。パスに関する意思決定がない場合、get_why は Git の履歴調査にフォールバックするため、呼び出し結果が空になることはありません。

ユーザーが「X はなぜこのように構築されているのですか？」と尋ねた場合

get_why(query="X") を呼び出します。

アーキテクチャを変更しようとしている場合

1. get_why(query="the specific area you're changing") を呼び出して、その領域を規定する既存の意思決定を探します。
2. 意思決定が見つかった場合は、作業を進める前にユーザーに提示します。既存のアーキテクチャ上の選択に反することを望んでいない可能性があります。
3. 意思決定が見つからない場合は作業を進めますが、その領域を規定する記録済みの意思決定がないことを伝えます。

具体的なクエリなしで呼び出された場合

引数を指定せずに get_why() を呼び出し、意思決定の健全性ダッシュボードを取得します。

• 古くなっている可能性のある意思決定
• 確認待ちの提案された意思決定
• 規定する意思決定が記録されていない、高変更頻度のファイル（管理されていないホットスポット）

同じ情報は CLI の repowise decision health / /repowise:decision でも確認でき、作業の途中で repowise why / /repowise:why（get_why アダプター）を使って 理由 を尋ねることもできます。repowise decision candidates --format json には、提案された各意思決定と、その確定に必要な項目が表示されます。repowise decision confirm <id> で承認できます（/repowise:decision を参照）。

ファイルに意思決定マーカーがある場合

コード内に # WHY:、# DECISION:、# TRADEOFF:、または # ADR: コメントが見つかった場合は、get_context(targets=["that_file.py"]) を呼び出して、コンテキストと影響を受けるモジュールを含む意思決定の完全な記録を確認します。

新しい意思決定の記録

自分でアーキテクチャ上の選択を確定した場合（選択肢を検討し、そのうち 1 つを選んだ場合）は、記録します。

repowise decision add --agent <your slug> --title "..." --decision "..." --rationale "<why, and what you rejected>" --affects <path>

コミット後に --evidence-commit <sha> を追加します。記録は候補として登録されます。承認されるまでは何も規定しないため、安心して記録できます。

候補の確認

候補を自分で確認して承認できます。repowise decision candidates --format json には、各候補の blockers が表示されます。repowise decision confirm <id> --agent <your slug> で承認し、阻害要因の内容に応じて --reason、--scope <path>、--evidence <commit|file|link>、または --decision を追加します。誤った候補は repowise decision dismiss <id> --agent <your slug> --reason ... --yes で却下し、重複した候補は repowise decision merge <id> <into-id> --agent <your slug> で統合します（統合先はすでに承認済みである必要があります。先に承認してください）。また、repowise decision deprecate <id> --agent <your slug> --reason ... で廃止できます。承認済みの意思決定が needs_review で、引き続き有効な場合は、repowise decision reaffirm <id> --agent <your slug> で更新します。confirm は候補にのみ使います。--format json を指定すると、対象が 1 件だけの場合でも、すべての確認コマンドが results[] を返します。あなたによる承認は本人のものとして記録され、他の人の承認として記録されることはありません。リポジトリでエージェントによる承認が無効になっている場合、confirm は拒否されます。その場合は人に任せ、その旨を伝えてください。

ユーザーが意思決定を述べた場合は、同じ方法で --agent を付けずに記録することを提案します。