adr-author

adr-author

概要

このスキルは、ADR Creator エージェントが使用する、アーキテクチャ決定記録（ADR）の各フェーズにおける作成規約を定めます。また、ADR Creator の状態ファイルがない場合に、直接呼び出して使用することもできます。直接呼び出す場合は、まず adr-identity.instructions.md に記載されたセッション復旧およびブートストラップのプロトコルを実行し、.copilot-tracking/adr-plans/{projectSlug}/state.json を解決または作成して、entryMode、projectSlug、outputTemplate を確認してから、状態に記録されたフェーズに進みます。3 つのエントリーモードと 2 つの出力テンプレートに対応し、最終 ADR ファイルを作成して系譜情報をアトミックに更新する Govern フェーズですべてのモードが合流します。

エントリーモード（state.entryMode）：

• capture — Frame と Decide の質問に対するユーザーの回答をもとに、対話形式で作成します。
• from-planner-handoff — 上流のプランナー（Security、RAI、SSSC）から、Frame のフィールドが事前入力された状態で開始します。Frame は終了前にユーザーの確認が必要です。
• adopt-template — プロジェクトに既存の ADR テンプレートがある場合に取り込む、1 回限りのセットアップモードです。最初の ADR と、コミット済みの .adr-config.yml の両方を生成します。

出力テンプレート（state.outputTemplate）：

• y-statement — 影響が小さい、または元に戻せる決定向けの、簡潔な Y-Statement 形式の ADR です。Frame は圧縮され、ASR トリガーの評価は任意です。
• madr-v4 — アーキテクチャ上重要な決定向けの、長形式の MADR v4.0.0 ADR です。Frame 中に ASR トリガーの評価が必要です。

エントリーモードと出力テンプレートは独立しています。from-planner-handoff セッションでは y-statement と madr-v4 のどちらも指定でき、capture セッションも同様です。adopt-template モードでは、ユーザーが正規化したテンプレートに沿った出力が生成されます。

ライフサイクルの概要：

モード	フェーズの順序	出力
capture	Frame → Decide → Govern	outputTemplate（y-statement または madr-v4）に準拠
from-planner-handoff	Frame（事前入力内容を確認）→ Decide → Govern	outputTemplate（y-statement または madr-v4）に準拠
adopt-template	Ingest → Normalize → Derive Questions → Fill → Govern	BYO 契約に基づく最初の ADR + .adr-config.yml

状態マシン、厳格な終了ゲート、自律性の階層（manual、partial、full）、および標準の state.json スキーマは adr-identity.instructions.md で定義されています。このスキルでは作成作業と成果物の契約を定めますが、状態マシンは再定義しません。

フレーム

アクティビティ：

• スコープ — 決定事項を1〜2文で記録し、単一のプロジェクトに限定します。
• 意思決定者 — deciders、consulted、informed（RACIに準拠）を記録します。個人名よりも役職やチームの識別子を優先し、いかなるADRフィールドにも個人の連絡先情報、秘密情報、認証情報、第三者または顧客の個人情報を記録してはいけません。
• 判断基準 — 意思決定の判断基準（機能上のニーズ、ビジネス目標）を列挙します。
• 制約 — 譲れない条件（規制、プラットフォーム、契約、時間）を列挙します。
• ASRトリガーの評価 — state.outputTemplate == 'madr-v4' の場合は必須です。adr-standards.instructions.md の評価基準に照らしてトリガーを評価し、結果を state.asrTriggers[] に記録します。評価基準と分類体系の全容は、このファイルと references/asr-trigger-taxonomy.md を参照してください。
• 図の形式に関する質問 — state.userPreferences.diagramFormat が未設定の場合は、.copilot-tracking/architecture-diagrams/state.json にあるアーキテクチャ図のルート状態を確認します。そのファイルに userPreferences.diagramFormat が設定されていれば、その値を使用します。設定されていない場合は、ユーザーに ascii または mermaid を尋ね、回答を state.userPreferences.diagramFormat に保存するとともに、単独で再利用できるようアーキテクチャ図のルート状態にも保存します。呼び出し元、引き継ぎ、または既存のADR状態ですでに state.userPreferences.diagramFormat が指定されている場合は、その値を確定値として扱い、再度尋ねてはいけません。フレームを終了する前に必ず設定してください。

厳格な終了ゲート（adr-identity.instructions.md より再掲）：

フレームフェーズは、次のすべてが記録されるまで次に進めません：スコープの説明、意思決定者のリスト、判断基準、ASRトリガーの判定（outputTemplate == 'madr-v4' の場合）、および userPreferences.diagramFormat。次に進む前に、ユーザーがフレームの要約を確認する必要があります。

出力成果物：

• 作成中のADRドラフトのフレームセクション（作業用ドラフトのみ。まだディスクには書き込みません）。
• state.json の更新フィールド：scope、deciders、consulted、informed、drivers、constraints、asrTriggers（outputTemplate == 'madr-v4' の場合）、userPreferences.diagramFormat。

決定

アクティビティ：

• 選択肢の列挙 — 検討した選択肢を少なくとも2つ挙げます。このゲートでは、選択肢が1つだけのADRは却下されます。
• 評価基準 — 各選択肢を、フレームで記録した判断基準と制約に照らして評価します。
• 決定結果の選択 — 選択した案を明示し、その理由を説明します。
• 結果 — 肯定的、否定的、中立的な結果を記録します。否定的な結果は省略できません。欠点が記録されていないADRは、このゲートで却下されます。

Yステートメントの作成（state.outputTemplate == 'y-statement' の場合）：

• templates/y-statement.md にある6つのスロットの定型文をそのまま使用して、選択した案をまとめます：

  In the context of (USE CASE), facing (CONCERN), we decided for (OPTION) and against (ALTERNATIVES), to achieve (QUALITY), accepting (DOWNSIDE).

• y-statement テンプレートでは、Yステートメントが「決定」の出力全体となります。MADRの選択肢表全体は省略します。

厳格な終了ゲート：

「決定」フェーズは、少なくとも2つの検討した選択肢、選択した案、および決定理由が記録されるまで次に進めません。次に進む前に、ユーザーが「決定」の要約を確認する必要があります。

統制

このフェーズでは3つすべてのエントリーモードを統合し、ADR ファイルをディスクに書き込む唯一のフェーズです。

アクティビティ：

1. MADR v4 フロントマターの組み立て — templates/madr-v4.md から ADR のフロントマターを生成します。このテンプレートは MADR v4.0.0（CC0）をそのまま再現したものです。帰属表示については references/standards-excerpts.md を参照してください。templates/madr-v4-frontmatter-overlay.md を重ねて適用し、上流の逐語的なテンプレートを変更することなく、hve-core 拡張フィールド（id、deciders、tags、supersedes、superseded-by、related、asr_triggers）を追加します（GP-17）。
2. 図のレンダリング — state.userPreferences.diagramFormat に基づき、templates/diagram-ascii.md または templates/diagram-mermaid.md のいずれかから図の本文を埋め込みます。スキルの呼び出し元はプラットフォームによる分岐を行いません。テンプレートの選択はデータのみに基づきます。図がインフラストラクチャのソースファイル（Terraform、Bicep、ARM）から派生する場合は、state.userPreferences.diagramFormat に記録された権威ある形式を指定して architecture-diagrams スキルを呼び出し、その出力をひな形の断片の代わりに埋め込みます。単独の図の生成では、ADR の状態ではなく、architecture-diagrams のルート状態コントラクトを使用します。
3. 系譜の検証 — 以下にまとめた6つの置き換えルールを適用します。全文は references/lineage-rules.md にあります。
4. フロントマターの検証 — ステージング済みの ADR ファイルに対して scripts/validate_frontmatter.py を呼び出します。このスクリプトはスキーマまたは列挙値に違反がある場合、ゼロ以外の終了コードを返します。フロントマターの形式に関する唯一の基準です。
5. 系譜アロケーター — scripts/update_lineage.py を呼び出して .adr-config.yml を変更します。last_decision_id の唯一の書き込み元はこのアロケーターです。last_decision_id を手動で編集することは禁止されています。
6. 最終書き込み — ADR を docs/planning/adrs/{NNNN}-{slug}.md に書き込みます。パスは、アロケーターが発行した NNNN と、ADR タイトルをスラッグ化した値から導出されます。
7. 引き継ぎトリガー — adr-handoff.instructions.md に従い、二重形式（ADO + GitHub）の作業項目を出力します。このスキルは引き継ぎの出力で停止し、ルーティングはエージェントの責任です。

Govern では、adr-identity.instructions.md と shared/disclaimer-language.instructions.md が要求する自律性および免責事項のバナーを使用します。これらの文面をここに重複して記載しないでください。実行時に読み込んでください。

置き換え系譜のルール（概要）

簡潔な列挙です。規範となる全文と例外的なケースは references/lineage-rules.md に記載されています。

1. supersedes と superseded-by は、それぞれスカラー文字列または null です。
2. 単一親による置き換え — 1つの ADR が持つ superseded-by は最大1つです。
3. ステータスの遷移 — 置き換える側の ADR の status は accepted になり、置き換えられる側の ADR の status は superseded になります。
4. 系譜の更新はアトミックです — 両方の ADR ファイルを同じ Govern フェーズ内で更新 MUST します。
5. 系譜アロケーター（scripts/update_lineage.py）は、.adr-config.yml 内の last_decision_id の唯一の書き込み元です。手動での編集は禁止されています。

ステータス分類

ADR の status は、次の6つの固定値のいずれかです。各値の定義とライフサイクルの遷移については adr-standards.instructions.md を参照してください。

• proposed — 現在作成中で、まだ決定されていません。
• accepted — 決定が採用され、対象範囲における現在の基準となっています。
• rejected — 検討の結果却下され、履歴情報として保持されています。
• deprecated — 推奨されなくなっていますが、まだ置き換えられていません。
• superseded — 以下の系譜ルールに従い、新しい ADR に置き換えられています。
• withdrawn — 決定前に提案が取り下げられました。

ASR トリガーカタログ（概要）

ASR（アーキテクチャ上重要な要件）トリガーは、state.outputTemplate == 'madr-v4' の場合にのみ評価されます。固定の列挙値は次の8つです。

• cost
• performance
• security
• compliance
• availability
• scalability
• maintainability
• evolvability

トリガーの評価基準、評価プロンプト、マッピング例は adr-standards.instructions.md に定義され、references/asr-trigger-taxonomy.md で詳しく説明されています。固定の列挙値以外のトリガー値を追加しないでください。

Adopt-Template ライフサイクル

5 ステップの概要です。GP-13（.adr-config.yml のスキーマと 2 層の設定解決を含む完全なライフサイクル）は、adr-byo-template.instructions.md に記載されています。

1. 取り込み — ユーザーが既存の ADR テンプレートファイルまたはテンプレートディレクトリを提供できるようにします。
2. 正規化 — scripts/normalize_template.py を実行し、テンプレートを標準の ADR フロントマターとセクション構成に変換します。
3. 質問の導出 — 正規化されたテンプレートの必須フィールドから、Frame と Decide の質問セットを生成します。
4. 入力 — 導出された質問を実行して、最初の ADR に内容を入力します。
5. ガバナンス — 標準の Govern フェーズを実行します。採用したテンプレートに lineage_fields がない場合、エージェントはユーザーに警告し、書き込み前に明示的な確認を求めなければなりません。これは adr-byo-template.instructions.md で説明されている、警告と確認を行う Govern の動作です。

テンプレート

• templates/madr-v4.md — MADR v4.0.0 ADR テンプレート（原文のまま、CC0）。state.outputTemplate == 'madr-v4' の場合、Govern のフロントマター組み立てに使用されます。
• templates/y-statement.md — Decide の組み立てに使用する、6 つのスロットからなる Y-Statement の形式。state.outputTemplate == 'y-statement' の場合に使用されます。
• templates/diagram-ascii.md — ASCII 図のブロック。state.userPreferences.diagramFormat == "ascii" の場合に選択されます。
• templates/diagram-mermaid.md — Mermaid 図のブロック。state.userPreferences.diagramFormat == "mermaid" の場合に選択されます。

参照資料

• references/standards-excerpts.md — MADR v4.0.0 の原文と CC0 の帰属表示、Y-Statement の帰属表示、ステータスの分類。
• references/lineage-rules.md — 6 つの置き換えルールの全文、エッジケース、および具体例。
• references/asr-trigger-taxonomy.md — ASR トリガーの分類、評価基準のプロンプト、および 8 つの列挙値それぞれの例。

スクリプト

• scripts/render_template.py — templates/ のテンプレートを Frame+Decide ペイロードに適用して、メモリ内の ADR ドラフトを生成します。パストラバーサル対策として、docs/planning/adrs/ の外にある出力パスは拒否します。
• scripts/validate_frontmatter.py — ADR のフロントマターを MADR v4 スキーマおよび限定列挙値に照らして検証します。違反がある場合は、ゼロ以外の値を返します。同じルートに対するパストラバーサル対策が施されています。
• scripts/update_lineage.py — .adr-config.yml の last_decision_id を更新する唯一のスクリプトです。新しい ADR の supersedes とともに、先行する ADR の superseded-by をアトミックに変更します。パストラバーサル対策が施されています。
• scripts/normalize_template.py — ユーザーが提供した ADR テンプレートを、templates/madr-v4.md で使用される標準構成に変換します。adopt-template ライフサイクルでのみ使用されます。パストラバーサル対策が施されています。
• scripts/scan_sensitive_content.py: ファイルパスまたは標準入力を受け取り、マスク済みの JSON 検出結果を出力する、決定的な情報開示リスクスキャナーです。基本動作では、高い確度で検出できる個人識別情報（PII）を検出します。--public を指定すると、内部 URL の検出が追加されます。--data を指定すると、構造化された機密列、接続情報、認証情報、サンプル行、および国際識別子の検出が個別に追加されます。--denylist <path> を指定すると、UTF-8 ファイルから、大文字と小文字を区別しない顧客用語の完全一致検出が個別に追加されます。このファイルは、スキャン対象パスと同じ許可ルートガードを通じて解決され、ファイルサイズ、用語数、用語の最小長に上限が適用されます。--allow-root <dir> を指定すると、そのディレクトリがガードに追加されます。これらのフラグは和集合として組み合わされ、フラグを指定しない場合の ADR の動作は変わりません。永続的な ADR 書き込み、および外部への出力や引き継ぎの前に必ず実行してください。

スキャナーレポートの契約

スキャナーは、エラーパスを含むすべての終了パスで標準出力に 1 つの JSON オブジェクトを出力するため、呼び出し側は文章を解析せずにフィールドを検証できます。このオブジェクトには、schema_version（scan-sensitive-content-v1）、status（completed または error）、modes（public、data、denylist のブール値）、denylist_rule_count、findings、および high、warn、total の件数を含む summary が含まれます。status が error の場合は、安定した code と message を持つ error も含まれます。終了コードは、高信頼度の検出がない状態でスキャンが完了した場合は 0、高信頼度の検出が 1 件以上ある状態でスキャンが完了した場合は 1、エラーの場合は 2 です。denylist による適用を必要とする呼び出し側は、modes.denylist が true であり、denylist_rule_count が 0 より大きいことを検証します。これにより、空または未ロードの denylist によってゲートが暗黙に無効化されることを防ぎます。

すべてのスクリプトは、作業ディレクトリを信頼できない入力として扱います。ADR 作成スクリプトは、プロジェクトの ADR ルート外を指すパスを拒否します。scan_sensitive_content.py は ADR 以外のコンテンツをスキャンするため、このスキルのディレクトリ、リポジトリのルート、コマンドラインで渡された各パスの親ディレクトリ、および --allow-root で指定されたディレクトリという許可ルート外を指すパスを拒否します。

出典の表示

• templates/madr-v4.md — MADR v4.0.0（タグ 4.0.0、ファイル template/adr-template.md）からバイト単位で同一の状態で複製しており、CC0-1.0 のもとで公開されています。CC0 では出典の表示は必須ではありませんが、透明性のためにここに記載しています。上流にある表記上の異常（例：status: プレースホルダー内の引用符の不整合）は、上流リリースとの差分をなくすため意図的に保持しています。

必須の読み込み指示

ADR Creator エージェントは、adr-identity.instructions.md に従って、フェーズからセクションへの読み込み契約を適用します。各フェーズでは、そのフェーズの作業を実行する前に、このスキルの該当セクションを必ず読み込み、セクションのアンカーを state.phaseSkillsLoaded に追加する必要があります。

Phase	Section anchor	Required phaseSkillsLoaded entry
Frame	#frame	adr-author#frame
Decide	#decide	adr-author#decide
Govern	#govern	adr-author#govern

エージェントは、このスキルファイルに対して read_file を使用してセクションを読み込み、フェーズの作業を実行する前にそのエントリを state.phaseSkillsLoaded に記録します。phaseSkillsLoaded は永続的な読み込み履歴であり、現在のモデルコンテキストにガイダンスが存在することの証明ではありません。1 つのライブコンテキスト内では、すでに読み込んだセクションのフェーズに再び入る場合、再読み込みは不要です。コールドスタート、再開、またはコンテキストの要約の後は、エントリが記録されていても、エージェントは現在のフェーズのセクションを再読み込みします。