review-tui

TUI 代码审查

参数

• --parallel：如果 Agent 支持，则并行审查各技术领域（参见步骤 6）
• 路径：目标目录（默认为当前工作目录）

门禁（顺序执行）

只有在每项通过条件都满足时才能继续（以减少范围偏移和缺乏依据的阻塞性声明）：

门禁	通过条件
G1 — 范围	步骤 1 生成了具体的目标 .go 路径列表（来自 git 命令或用户明确指定的路径）。如果列表为空，则在审查前已停止并要求澄清范围，或记录了双方同意的非 git 范围（例如单个文件／目录）。
G2 — 审查前加载技能	已加载 review-verification-protocol、go-code-review 和 bubbletea-code-review；步骤 4 的条件技能（测试 → go-testing-code-review，Wish → wish-ssh-code-review）已在步骤 5 之前加载。
G3 — Critical/Major 级问题的证据	每项 Critical/Major 级发现都引用了已打开源文件中的文件路径 + 行号（或简短的引用片段），而不只是 diff 片段。
G4 — 输出前检查	写入 Issues 部分之前，已根据步骤 7 和已加载的验证协议检查每项保留的发现。

G2 未通过前，不要开始步骤 5。G3 和 G4 未通过前，不要发布 Critical/Major 级问题。

步骤 1：识别变更文件

git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '\.go$'

步骤 2：检测技术

# Detect BubbleTea (required for TUI review)
grep -r "charmbracelet/bubbletea" --include="*.go" -l | head -3

# Detect Lipgloss styling
grep -r "charmbracelet/lipgloss\|lipgloss\.Style" --include="*.go" -l | head -3

# Detect Bubbles components
grep -r "charmbracelet/bubbles\|list\.Model\|textinput\.Model\|viewport\.Model" --include="*.go" -l | head -3

# Detect Wish SSH server
grep -r "charmbracelet/wish\|ssh\.Session" --include="*.go" -l | head -3

# Check for test files
git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '_test\.go$'

步骤 3：加载验证协议

加载 review-verification-protocol 技能，并在整个审查过程中牢记其中的检查清单。

步骤 4：加载技能

加载以下所有适用技能（打开其 SKILL.md 并遵循其中的说明）。

始终加载：

• go-code-review
• bubbletea-code-review

根据检测结果有条件地加载：

条件	技能
测试文件有变更	go-testing-code-review
检测到 Wish SSH	wish-ssh-code-review

步骤 5：审查重点领域

Model/Update/View（Elm 架构）

• Model 不可变（Update 返回新 model）
• Init 返回适当的初始命令
• Update 处理所有消息类型
• View 是纯函数（无副作用）
• 正确使用 tea.Quit 退出

Lipgloss 样式

• 样式在包级别定义一次
• 不在 View 函数中创建样式
• 颜色使用 AdaptiveColor 适配浅色／深色主题
• 布局会响应 WindowSizeMsg

组件组合

• 子组件的更新得到传递
• WindowSizeMsg 会传递给可调整大小的组件
• 管理多个组件的焦点
• 视图切换有清晰的状态机

SSH 服务端（如适用）

• 主机密钥已持久化
• 已实现平稳关闭
• PTY 窗口大小已传递给 TUI
• 每个会话使用独立的 Lipgloss 渲染器

步骤 6：审查

如果 Agent 支持子 Agent，则为每个技术领域并行分派一个子 Agent；否则按顺序执行各领域。两种方式都会生成相同的输出。

顺序执行（默认；子 Agent 不可用时的回退方式）：

1. 加载适用技能
2. 审查 Go 代码质量
3. 审查 BubbleTea 模式（Model/Update/View）
4. 审查 Lipgloss 样式
5. 审查组件组合
6. 审查 SSH 服务端（如适用）
7. 汇总发现

并行执行（--parallel；仅当 Agent 支持子 Agent 时）：

1. 预先检测所有技术
2. 分别为以下领域分派一个子 Agent：Go 代码质量、BubbleTea、SSH
3. 等待所有子 Agent 完成
4. 汇总发现

第 7 步：验证发现

报告任何问题前：

1. 重新阅读实际代码（而不只是差异上下文）
2. 对于“未使用”的说法——你是否搜索了所有引用？
3. 对于“缺失”的说法——你是否检查了框架／父级的处理逻辑？
4. 对于语法问题——你是否依据当前版本的文档进行了核实？
5. 删除任何属于风格偏好而非实际问题的发现

第 8 步：评审收敛

单轮完整性

你 MUST 在单轮评审中报告所有类别（风格、逻辑、类型、测试、安全、性能）的所有问题。不要把问题留到后续轮次。

提交发现前，先问自己：

• “如果应用了我建议的所有修复，我会在修复后的代码中发现新问题吗？”
• “我是否要求编写新的代码（测试、类型、模块），而这些代码本身也需要评审？”

如果任一答案为是：现在就将预计会出现的后续问题纳入本轮评审，以便作者一次性处理所有问题。

范围规则

• 只评审差异中的代码及其直接相关的现有代码
• 不要要求添加差异前不存在的新功能、测试基础设施或架构变更
• 如果缺少测试覆盖，将其作为一个 Minor 问题指出（“缺少对 X、Y、Z 的测试覆盖”）——不要指定会引入大量新代码的实现细节，例如 mock 库、行为提取或依赖注入模式
• 类型规范、文档和命名问题属于 Minor，除非它们影响公共 API 契约
• 不要要求添加新依赖项（例如 Mox、测试库、linter 插件）

修复复杂度预算

无论修复现有代码的工作量多大，都应按其实际严重程度指出。

但是，对差异前不存在的新代码的要求必须归类为 Informational：

• 添加新依赖项（例如 Mox、linter 插件）
• 创建全新的模块、文件或测试套件
• 提取新的行为、协议或抽象

这些是供作者在未来工作中考虑的改进建议，不应阻止评审通过。

迭代政策

如果这是修复完成后的重新评审：

• 只验证先前指出的问题是否得到了妥善解决
• 不要提出与先前问题无关的新发现
• 接受未修复的 Minor／Nice-to-Have 问题，不要再次指出
• 重新评审的目标是验证，而非发现

输出格式

## Review Summary

[1-2 sentence overview of findings]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: Description of what's wrong
   - Why: Why this matters (UI freeze, crash, resource leak)
   - Fix: Specific recommended fix

### Major (Should Fix)

2. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Minor (Nice to Have)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Informational (For Awareness)

N. [FILE:LINE] SUGGESTION_TITLE
   - Suggestion: ...
   - Rationale: ...

## Good Patterns

- [FILE:LINE] Pattern description (preserve this)

## Verdict

Ready: Yes | No | With fixes 1-N (Critical/Major only; Minor items are acceptable)
Rationale: [1-2 sentences]

修复后验证

应用修复后，运行：

go build ./...
go vet ./...
golangci-lint run
go test -v -race ./...

所有检查都必须通过后才能批准。

规则

• 在评审前加载技能（不要事后加载）
• 为每个问题按顺序编号（1、2、3……）
• 每个问题都注明 FILE:LINE
• 清楚区分 Issue／Why／Fix
• 按实际严重程度分类
• 特别留意：
  • Update 中的阻塞操作（会冻结 UI）
  • View 中的样式创建（影响性能）
  • 缺少 WindowSizeMsg 处理（调整大小时会出错）
• 在单轮评审中报告所有问题——不要将发现留到后续轮次
• 重新评审只验证先前的修复——不得有新发现
• 对新增代码的要求（新模块、依赖项、测试套件）属于 Informational，不会阻止批准
• Verdict 忽略 Minor 和 Informational 项目——只有 Critical 和 Major 会阻止批准