理解確認(Comprehension Check)

.agents/workflow/comprehension/ 配下の質問ファイルについて、ユーザーの回答を判定し、解説を追記する。

引数

• 第1引数: タスクID(例: T1)。指定時は .agents/workflow/comprehension/<タスクID>.md のみを対象とする。
  省略時は .agents/workflow/comprehension/ 配下の「回答記入済み・未解説」の全ファイルを対象とする。

手順

1. 対象ファイルの検出

引数指定時:

• .agents/workflow/comprehension/<タスクID>.md が存在することを確認
• 存在しない場合はエラーとして中断しユーザーに報告する

引数省略時:

• .agents/workflow/comprehension/*.md を一覧する
• 以下の条件で「回答記入済み・未解説」のファイルを抽出する:
  • 回答記入済み: 各質問の **あなたの回答**: 行にコメントアウト(<!-- ここに記入 -->)以外のテキストが記入されている
  • 未解説: ファイル内に ## 解説 見出しが存在しない(行頭の見出しとして判定する。詳細は「『回答記入済み』『未解説』の判定方法」を参照)

2. メタデータからの最小限のコード読込(別セッション対応)

各対象ファイルの ## メタデータ セクションから以下を読み取り、必要最小限のコードのみを読み込む:

• コミット: <hash> → git show <hash> --stat で変更概要を把握
• 主な変更ファイル: <一覧> → 各ファイルの該当コミット時点の内容を git show <hash>:<path> で取得
• 関連する受け入れ基準: ... → 質問の背景を理解

これにより、別セッション(コンテキストなし)でも実装内容を復元して解説できる。

3. 回答の判定

質問ごとに、正答・誤答・曖昧の3段階で判定する:

• 正答: 選択式の正解と一致、または記述式で実装内容と整合する回答
• 誤答: 選択式の誤答を選択、または記述式で事実と異なる内容
• 曖昧: 判断材料が不足、または部分的にしか合っていない

4. 解説の追記

質問ファイルに ## 解説 セクションがなければ末尾に追記する。既存のセクション(Q1, Q2, 回答欄等)は一切変更しない。

## 解説

### Q1: <質問の要約>
- **判定**: ✅ 正答 / ❌ 誤答 / ⚠️ 曖昧
- **解説**: <該当コードを引用しながら、なぜその回答が正しい/誤りかを説明>

### Q2: ...

• 誤答・曖昧な回答には該当コードの該当箇所を引用して具体的に説明する
• 正答の場合も、簡潔な補足解説を付ける(理解の定着のため)

5. 会話への出力

会話(標準出力)には以下だけを出力する:

## 理解確認: <タスクID>
- 対象ファイル: <ファイル名>
- 結果: Q1: ✅ / Q2: ❌ / Q3: ⚠️
- 解説はファイルを参照: `.agents/workflow/comprehension/<タスクID>.md`

質問ファイルのフォーマット

各タスク完了時に agent-review-commit が以下の形式で生成する。この形式は docs/plans/comprehension-check.md の設計に従う。

# 理解確認: <タスクID> <タスクタイトル>

## メタデータ(別セッション解説用)
- コミット: <hash>
- 主な変更ファイル: foo.ts, bar.ts
- 関連する受け入れ基準: ...

## Q1: <設計判断を問う質問>
(選択式の場合、A/B/C/D の選択肢、もっともらしい誤答肢つき)

**あなたの回答**: <!-- ここに記入 -->

## Q2: ...

「回答記入済み」「未解説」の判定方法

以下の2条件をともに満たすファイルを「回答記入済み・未解説」と判定する:

1. 回答記入済み: 各質問の **あなたの回答**: 行の直後がコメントアウト(<!-- ここに記入 -->)のままではない。すなわち、何らかのテキストが記入されている
2. 未解説: ファイル内に ## 解説 見出しが存在しない。判定は行頭の見出しとして行うこと(grep なら ^## 解説)。質問文中にインライン引用された `## 解説` を誤検出しないため

質問観点テンプレート

質問生成時に以下の観点からバランスよく作成する:

• 設計判断: なぜこの実装方針か、トレードオフ
• 動作の仕組み: 変更したコードの処理フロー、エッジケース
• 依存の理解: 実装で利用した既存モジュール・外部ライブラリ・フレームワーク機能について、その大まかな役割と仕組み
• 影響範囲: この変更が他のどこに影響しうるか