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. 选择问题

我会根据代码，从以下六个类别中选择问题：

• 设计：为什么选择这种方案？
• 边界情况：在不常见的情况下会发生什么？
• 清晰度：你会如何解释这一点？
• 理念：这是否符合项目原则？
• 故障模式：可能会出现什么问题？
• 测试：你如何确认它能正常工作？

3. 对话

我会一次提出一个问题，并等待你的回答：

**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 第 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. Agent 分析代码，找出可能存在的问题
3. 生成结构化 JSON 输出
4. 输出可自动发布为 PR 评论

**自动检测：**此技能会自动检测非交互环境（例如，claude --print、CI 管道、没有 TTY），并切换到非交互模式。这可以避免令人沮丧的情况：提出问题后，等待永远不会到来的回答，最后以 INCONCLUSIVE 结束，却没有任何有用的输出。

发布到 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. 结对编程：对话能发现独自工作时遗漏的问题

相关内容

• Agent：~/.amplihack/.claude/agents/amplihack/specialized/socratic-reviewer.md
• 传统审查：使用 /reviewing-code 技能获取直接反馈
• 理念检查：使用 philosophy-guardian Agent 检查合规性

执行

调用此技能时：

1. 解析参数（文件路径、深度级别、关注重点）
2. 阅读并分析目标代码
3. 在上下文中调用 socratic-reviewer Agent
4. 推进对话并等待用户回应
5. 最后综合整理发现

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

Agent 将处理提问流程，并使用 [WAIT] 标记等待回应。