socratic-review

ソクラテス式コードレビュー

ソクラテス式のコードレビューセッションを開始します。開発者に問題点を伝えるのではなく、問題を自ら発見し、考えを言語化できるよう促す質問をします。

このスキルを使う場面

次のような場合は、ソクラテス式レビューを使います。

• 単に要件を満たすだけでなく、深く理解したい
• 開発者自身に気づきを得てもらいたい（修正より学びを重視）
• 設計上の判断を言語化し、文書化する必要がある
• 隠れた前提を明らかにしたい
• コードが複雑で、説明が必要
• メンタリングやオンボーディングをしている

次のような場合は、従来のレビューを使います。

• 時間が限られており、すぐにフィードバックが必要
• 問題が明白で、対応が単純
• 文書化のための報告書が必要
• 開発者が明確なフィードバックを明示的に希望している

使用方法

# Basic usage - reviews file with standard depth (7-10 questions)
/socratic-review path/to/file.py

# Quick review - 3-5 focused questions
/socratic-review path/to/file.py --depth=quick

# Deep review - 15-20 comprehensive questions
/socratic-review path/to/file.py --depth=deep

# Review specific function/class
/socratic-review path/to/file.py --focus="function_name"

# Review a directory
/socratic-review src/auth/

# Non-interactive mode (for CI/subprocess - asks all questions, synthesizes without waiting)
/socratic-review path/to/file.py --non-interactive

# Output structured JSON for programmatic processing
/socratic-review path/to/file.py --non-interactive --output=review.json

# Write insights to DECISIONS.md
/socratic-review path/to/file.py --write-decisions

仕組み

1. コンテキストの分析

まず、コードを分析して以下を把握します。

• レビュー対象のファイルや関数
• 複雑さのレベルと使用されているパターン
• 深く掘り下げる価値のある領域

2. 質問の選定

コードに基づいて、次の6つのカテゴリから質問を選びます。

• 設計：なぜこのアプローチを選んだのですか？
• エッジケース：通常とは異なる状況では何が起きますか？
• 明確さ：これをどのように説明しますか？
• 理念：これはプロジェクトの原則に沿っていますか？
• 障害モード：何が問題になる可能性がありますか？
• テスト：正常に動作すると、どのように確認できますか？

3. 対話

質問を1つずつ提示し、回答を待ちます。

**Q1** [Category: Design]
Why did you choose to store session data in memory rather than a database?

[WAIT FOR YOUR RESPONSE]

各回答の後、次のいずれかを行います。

• 回答から不確かな点が明らかになった場合は、追加の質問をする
• 理解が十分であれば、次の質問に進む
• 最終的な統合に向けて、気づきを記録する

4. 統合

すべての質問が終わったら、次の内容をまとめます。

• 明らかになった気づき：対話を通じて明確になったこと
• 表面化した前提：明らかになった隠れた前提
• 推奨事項：対話に基づいて変更すべきこと
• 強み：十分に理解できていたこと

深さのレベル

クイック（3～5問、約5分）

次のような場合に適しています。

• 小さなバグ修正
• 単純な変更
• 明白なコード

重点：リスクが最も高い領域のみ

標準（7～10問、約15分）

次のような場合に適しています。

• 機能の実装
• リファクタリング
• 一般的な PR

重点：すべての質問カテゴリを網羅

ディープ（15～20問、約30分）

次のような場合に適しています。

• セキュリティ上重要なコード
• コアインフラストラクチャ
• アーキテクチャの変更

重点：追加質問を含めて包括的に確認

セッションの例

## Socratic Review: auth/login.py

I'm going to ask you some questions about this login implementation.
There are no wrong answers - the goal is to think through the design together.

---

**Q1** [Category: Design]
I see you're storing session data in an in-memory dictionary.
Why did you choose this approach over Redis or database storage?

> Your answer: "It was simpler to implement and we don't have many users yet."

That makes sense for simplicity. **Follow-up**: What would trigger you to
migrate to a different storage mechanism?

> Your answer: "Um... I guess when we scale? Or add multiple servers?"

**Insight noted**: Migration criteria aren't clearly defined.

---

**Q2** [Category: Edge Case]
What happens if a user's session expires while they're submitting a form?

> Your answer: "I... actually haven't thought about that."

**Insight noted**: Session timeout during active use is unhandled.

---

[... more questions ...]

---

## Review Synthesis

### Insights Revealed

- Session storage is pragmatic but migration path unclear
- Session timeout during active use is unhandled

### Assumptions Surfaced

- Single server deployment assumption
- Users won't have long form submissions

### Recommendations

1. Document session storage migration criteria
2. Add graceful session timeout handling

### Strengths Identified

- Clear awareness of simplicity trade-offs
- Quick recognition of gaps when prompted

ワークフローとの統合

ソクラテス式レビューは、DEFAULT_WORKFLOW の Step 11 で標準レビューの代わりに使用できます。

Step 11: Review the Code

Choose review approach:
A) Standard review - Direct feedback from reviewer agent
B) Socratic review - Dialogue with socratic-reviewer agent

Use Socratic when:

- Learning is as important as fixing
- Design decisions need documentation
- Mentoring/onboarding context

効果的な回答のためのヒント

質問に答える際は、次の点を意識してください。

1. 具体的に答える：「null の場合は空の配列を返します」は、「問題ないはずです」より適切です
2. 不確かさを認める：「何が起きるかわかりません」という回答にも価値があります。理解の不足が明らかになるためです
3. 考えを声に出して説明する：答えだけでなく、考えた過程も説明します
4. 説明を求める：質問が不明確であれば、その旨を伝えます

フィードバックループ：気づきを改善につなげる方法

重要な問いは、対話から得た気づきを、どのように実際の改善につなげるかです。

インタラクティブモード（デフォルト）

対話をリアルタイムで進める場合：

1. 各質問と回答を記録します
2. 気づきをその場で記録します
3. 最後に、内容をまとめます
4. --write-decisions を使って、気づきを DECISIONS.md に保存できます

非インタラクティブモード（CI／サブプロセス）

自動化された環境で使用する場合：

1. すべての質問を修辞的に提示します
2. エージェントがコードを分析し、想定される問題を特定します
3. 構造化された JSON 出力を生成します
4. 出力を PR のコメントに自動投稿できます

自動検出： このスキルは、非インタラクティブな環境（例：claude --print、CI パイプライン、TTY がない場合）を自動的に検出し、非インタラクティブモードに切り替えます。これにより、質問をしても回答が得られず、有用な出力がないまま「判定不能」で終了するという、もどかしい状況を防ぎます。

PR への投稿

# Run non-interactive review
/socratic-review src/auth/ --non-interactive --output=review.json

# Post results to PR
gh pr comment 123 --body "$(jq -r '.synthesis | "## Socratic Review\n\n### Insights\n" + (.insights_revealed | map("- " + .) | join("\n")) + "\n\n### Recommendations\n" + (.recommendations | map("- [" + .priority + "] " + .description) | join("\n"))' review.json)"

結論が出ない場合の終了

インタラクティブモードで3つの質問に回答がない場合、セッションはINCONCLUSIVEステータスで終了します。ソクラテス式レビューには、進んで参加する姿勢が必要です。参加が得られない場合は、別のことをしたふりをせず、問題なく終了します。その後、ユーザーは代わりに従来の/reviewを実行できます。

これは何ではないか

• テストではありません：正解も不正解もありません
• 批判ではありません：質問は評価するのではなく、探求するためのものです
• チェックリストではありません：質問はコードと回答に応じて変化します
• テストの代替ではありません：これは理解を深めるためのものであり、検証のためのものではありません

基本となる考え方

このスキルは、次の考え方に基づいています。

1. フェインマン・テクニック：教えることで、理解の不足が明らかになります
2. ソクラテス式問答法：質問は回答よりも深い洞察をもたらします
3. ラバーダック・デバッグ：説明することで、徹底的に考えるようになります
4. ペアプログラミング：対話によって、一人での作業では見落とす点に気づけます

関連項目

• エージェント：~/.amplihack/.claude/agents/amplihack/specialized/socratic-reviewer.md
• 従来のレビュー：直接フィードバックを行う/reviewing-codeスキル
• 理念の確認：準拠状況を確認するphilosophy-guardianエージェント

実行

このスキルが呼び出されたとき：

1. 引数（ファイルパス、深さのレベル、重点項目）を解析します
2. 対象コードを読み、分析します
3. コンテキストとともに s o c r a t i c-reviewerエージェントを呼び出します
4. 対話を進行し、ユーザーの回答を待ちます
5. 最後に調査結果をまとめます

Task(
  subagent_type="socratic-reviewer",
  prompt="Conduct Socratic review of [file] at [depth] level. Focus on: [areas]"
)

エージェントは質問の進行を管理し、[WAIT]マーカーを使って回答を待ちます。