ADRによる開発

ADRによる開発 は何をしますか？

必須の最初のステップ：競合チェック

ドメインを尋ねる、エージェントを作成する、コードを調査する、または変更を行う前に、バンドルされた読み取り専用スクリプトを実行してください：

python3 <絶対スキルディレクトリ>/scripts/check_conflicting_skills.py --project <リポジトリパス>

プレースホルダーを実際のパスに解決し、必要に応じてパスを引用符で囲んでください。セッションの利用可能なスキルカタログにあるすべての名前を、クラウド専用やプラグイン修飾名を含めて、--available-skill 引数を繰り返して渡します。非標準のスキルディレクトリは --root で追加します。関連するネストされたディレクトリシンボリックリンクのターゲットは明示的に追加します。このスクリプトは、ローカルスキルファイルとカタログエントリを、そのインストラクションをロードしたりインストールを変更したりせずに検出します。

• grill-me と spec-first を競合スキルとして扱います。大文字小文字、スペース、アンダースコア、ハイフンのバリエーション（例：Grill Me や spec_first）も含みます。
• 終了コード 0 は、検査したスコープ内で競合が見つからなかったことを意味します。終了コード 1 は競合が見つかったことを意味し、スクリプトの障害ではありません。終了コード 2 は発見が不完全であったことを意味します：エラーとカバレッジの制限を報告し、可能な場合はそれらを解決して再実行します。カバレッジが不完全な場合に、すべてのスキルがチェックされたと主張しないでください。
• 一致するものが見つかった場合、このワークフロー内でのそれらの使用を無効にし、続行する前にユーザーの言語で警告します：検出されたスキルを名前を挙げて説明し、それらが現在のワークフローでのみ無効化されていることを説明します。グローバルなアンインストールやアカウント設定の変更を暗に示さないでください。これらのワークフロー除外に対して追加の承認は必要ありません。
• 除外されたスキルを呼び出したり、その指示に従ったり、それらに作業を委任したりしないでください。コーディネーター、アーキテクト、実装者に除外を適用します。すべてのエージェントハンドオフ時に除外リストを渡します。このワークフロー自身の明確化と承認ステップを使用します。
• スクリプトは競合を検出します。コーディネーティングエージェントが除外を強制します。セッションカタログが、そのファイルにアクセスできない場合でも、スキルの存在を明らかにした場合は、そのスキルも除外します。スクリプトが実行できない場合は、その制限を報告し、既知の除外を適用し、スキャンが成功したとは主張しません。
• セッションを再開した後、または利用可能なスキルに変更があった後は、再実行します。このチェックの一部として、インストールされたスキルを決して削除、名前変更、またはグローバルに無効化しないでください。

エントリとロール

1. ワークフローを開始する前に、アーキテクトが焦点を当てるべきドメインを尋ねます。ビジネスドメインまたは技術ドメインを受け入れます。明示的に提供されたドメインがある場合は、再度尋ねずに再利用します。
2. 選択されたドメインに対して、セッション全体を通して別のアーキテクトエージェントを作成します。このルール、ドメイン、リポジトリパス、および既知のコンテキストを提供します。アーキテクトに、ユーザーがどの問題を解決するかを尋ねさせます。メインエージェントは質問と回答を中継しても構いません。問題がすでに提供されている場合は、不足している情報のみを尋ねます。
3. メインエージェントに、対話、ドキュメント、およびコンテキストのハンドオフを調整させます。アーキテクトに、調査、設計、ADRの維持、および結果の独立した検証を行わせます。別の実装エージェントに、承認された決定を実装し、証拠を準備させます。アーキテクトと実装者のロールを組み合わせないでください。
4. 環境のネイティブな独立エージェント機能（Codexのサブエージェント、Claude Codeの利用可能なエージェント/タスク機能）を使用します。APIを発明したり、ロールを切り替える単一のエージェントを独立した検証として提示したりしないでください。独立したエージェントが利用できない場合は、制限を説明し、ユーザーに適切な環境を選択するよう求めます。調査は続行できますが、このワークフローでの実装は開始してはなりません。
5. コンテキストロス後は、ドキュメントとコードから状態を復元します。新しいアーキテクトを作成する必要がある場合は、元のエージェントが存続したと主張せず、そのドメインと責任を復元します。

調査と決定

• アーキテクトに、プロジェクトの指示、コード、関連するADR、証拠を読み、問題と制約を明確にさせます。コードを調査し、問題を明確にする前にADRを作成しないでください。コードがまだ存在しない場合は、その事実を記録し、利用可能な資料を調査します。
• 現在の決定との競合を特定します。最初に競合をユーザーに提示し、決定を要求します。応答があった後にのみ、新しいADRを準備します。代替案を準備する許可は、それを実装する承認を意味しません。
• テンプレートを使用して、docs/adr/ にADRを作成します。簡単な問題文、提案された解決策、根拠、安定したIDを持つ検証可能な受け入れ基準を含めます。初期ステータスを accepted-for-discussion に設定します。
• 独立した決定は別々のADRに分け、依存関係を明示的に記録します。依存関係や置き換えの循環を導入しないでください。
• 特定のADRまたは列挙されたADRのセットを、実装するための明示的なユーザー承認を求めて提示します。沈黙、何かを構築するという一般的なリクエスト、または調査の許可から承認を推測しないでください。
• ユーザーの応答、日付、および承認されたドキュメントのバージョンを記録します。明示的な承認があった後にのみ accepted-for-work に設定します。列挙されたADRのセットの明示的な承認を許可します。

実装

• そのADRが依存するすべてのADRが完了した後にのみ、ADRの実装を開始します。たとえセット全体がすでに承認されていても同様です。
• 実装者に、ADR、基準、依存関係、および制約を渡します。承認された決定の範囲内で実装することを要求します。
• 実装が不可能であるか、決定または基準を変更する必要がある場合は、影響を受ける作業を停止し、問題をアーキテクトに戻します。独立した承認済みの作業は続行しても構いません。
• 承認後は、解決策の説明または受け入れ基準を決して変更しないでください。変更は、別の承認を伴う新しいADRに記録します。
• 実装者に、docs/evidence/ に証拠を準備させます：各基準の結果、コマンドと再現手順、および検証されたコミットまたは正確なコードバージョン。テストされたバージョンに将来のコミットを代用しないでください。コミットされていない変更については、保存された差分とチェックされたファイルの識別子またはハッシュを含めます。

独立した検証と完了

• アーキテクトに、自らチェックを実行し、実際の結果をすべての受け入れ基準と比較させます。実装者の報告とコード検査は実行の代わりにはなりません。
• コマンド、環境、結果、ログリンク、および検証されたバージョンを証拠に保存します。実行されなかったチェック、ブロックされたチェック、または失敗したチェックは正直にマークします。未検証または未達成の基準があるADRを完了しないでください。
• 実装が検証に失敗したがADRが有効なままである場合、最初に結果と具体的な修正範囲をユーザーに提示し、許可を求めます。応答の前に修正を委任または実行しないでください。許可を得た後、実装者に問題を修正させ、アーキテクトが再度検証します。別の検証失敗があった場合、次の修正サイクルには新たな許可が必要です。
• 失敗が新しいアーキテクチャ決定を必要とする場合は、調査と新しいADR手順に戻ります。
• すべての基準が独立して検証された後にのみ、アーキテクトのみが completed を設定できるようにします。証拠ドキュメントへのリンクが必要です。ADRを完了するために追加のユーザー承認は必要ありません。

ステータスと履歴の保存

正確に4つの標準 status 値を使用します。以下のロシア語ラベルは元の意味を示しています。既存のプロジェクト履歴を、レガシードキュメントを黙って書き換えるのではなく、保存します。

ステータス	元のラベル	条件
accepted-for-discussion	принято к обсуждению	調査された提案であり、議論または承認を待っている
accepted-for-work	принято к работе	ユーザーが特定のADRを明示的に承認した
completed	завершен	アーキテクトがすべての基準を独立して検証した。証拠がリンクされている
rejected	отклонено	新しい承認済みADRと拒否の根拠/証拠が存在する

• ADRまたは証拠ドキュメントを決して削除したり、そのIDを再利用したりしないでください。承認前は、実質的な変更を記録しながらドラフトの洗練を許可します。
• 承認後は、解決策本文と基準を不変に保ちます。現在のステータスとリンクの更新を、履歴エントリを追加して許可します。以前のエントリ、証拠、検証結果を保存します。失敗したチェックを合格結果で上書きしないでください。
• ユーザーが代替案を作業用に明示的に承認した時点で、古いADRを拒否します（古いADRが完了していた場合も含む）。古いADRをその代替案と、別の拒否根拠ドキュメントにすぐにリンクします。これは、古い決定がなぜ拒否されたかを証明します。新しい実装が機能することを証明するものではありません。
• 以前の完了、その日付、バージョン、および証拠を保存します。代替案がまだ実装されていない可能性があることを明示的に記録します。ドキュメントを拒否しても、それ自体で動作中のコードが削除されるわけではありません。
• 新しい決定なしにADRを拒否しないでください。ユーザーが代替案を選択していない場合は、現在のステータスを保持し、議論エントリを追加します。ステータス遷移を可能にするためだけに代替案をでっち上げないでください。
• 依存関係が拒否または置き換えられた場合は、影響を受ける作業を一時停止し、アーキテクトに影響を評価させます。承認された決定を黙って再配線しないでください。

ドキュメントグラフ

• ドキュメントを作成する前にテンプレートを読み、新しい環境を使用する際は移植性ガイダンスを読んでください。
• ADRは docs/adr/ADR-0001-short-slug.md として、証拠は docs/evidence/EVID-0001-short-slug.md として保存します。既存の履歴を考慮して、次に使用されていない番号を選択します。古いドキュメントに番号を付け直さないでください。
• 明示的な相対Markdownリンクと関係タイプを使用します：replaces / replaced_by、depends_on / required_by、extends / extended_by、evidence / proves。バックリンクを維持し、証拠が実装を証明するのか、拒否の理由を証明するのかを特定します。
• ADRと証拠をグラフのドキュメントとして扱います。別のグラフデータベースは不要です。ハンドオフ時に、リンクターゲット、バックリンク、依存関係サイクルの欠如、およびステータス条件を確認します。
• 各ステップの最後に、ADRステータス、結果、ドキュメントリンク、およびユーザーを待っている場合は必要な具体的な決定を報告します。単に承認された、または実装されたが未検証の作業を完了したと説明しないでください。