代码审查 (review)

代码审查（review）

概述

review 是 GStack 的核心代码审查技能。它在代码合并到主分支之前进行深度分析，检查 SQL 安全、LLM 信任边界违反、条件副作用和其他结构性问题。

核心原则： 在代码落地前主动发现并修复问题。

核心功能

Preamble 机制

每次调用 review 技能时，会自动运行 Preamble 脚本：

检查更新 - 是否有新版本可用
会话追踪 - 记录当前会话
遥测配置 - 处理匿名使用统计
完整性原则 - 首次使用时介绍”沸腾湖泊”原则

AskUserQuestion 格式

GStack 的审查采用结构化的用户问答格式：

Re-ground - 重申项目、当前分支、当前任务
Simplify - 用 16 岁能懂的语言解释问题
Recommend - 推荐完整方案（Completeness: X/10）
Options - 提供选项，带工作量估算

沸腾湖泊原则（Boil the Lake）

AI 辅助编码使得完整实现的边际成本接近于零。当呈现选项时：

如果选项 A 是完整实现，选项 B 是节省 effort 的捷径 —— 始终推荐 A
湖泊 vs 海洋： 湖泊是可以沸腾的（100% 测试覆盖率），海洋不是
用双尺度估算：人类团队时间 vs AI+工具时间

任务类型	人类团队	AI+工具	压缩比
样板代码	2 天	15 分钟	~100x
编写测试	1 天	15 分钟	~50x
功能实现	1 周	30 分钟	~30x
Bug 修复	4 小时	15 分钟	~20x

审查要点

SQL 安全

检查 SQL 注入风险
验证参数化查询
检查 ORM 使用规范

LLM 信任边界

验证外部输入验证
检查敏感数据处理
确保 API 响应正确处理

条件副作用

检查状态变更
验证事务边界
检查并发问题

结构性检查

代码重复
圈复杂度
命名一致性

模拟场景

场景 1：PR 审查

用户要求：review this PR
✅ 流程：Preamble → 获取 diff → 检查 SQL/信任边界/结构 → 给出建议

场景 2：主动建议

用户说：可以合并了
✅ 主动建议：运行 review 进行预合并审查

核心命令

# 1. Preamble 自动运行
# 检查更新、会话追踪、遥测

# 2. 获取 diff
git diff main...HEAD

# 3. 使用沸腾湖泊原则评估
# Completeness: X/10

# 4. 给出结构化建议

避坑指南

坑	表现	解决
只看表面	只检查语法错误	深入检查 SQL/信任边界
推荐捷径	建议 skip tests	沸腾湖泊原则，推荐完整方案
被动等待	用户不问就不审查	主动建议审查

速查卡片

何时使用

用户要求 “review this PR”
代码审查
预合并审查
检查 diff

关键要点

使用结构化 AskUserQuestion 格式
遵循沸腾湖泊原则
推荐完整方案而非捷径
主动建议而非被动等待

审查类别

SQL 安全
LLM 信任边界
条件副作用
结构性检查

与 Superpowers 对比

Superpowers: 侧重 systematic-debugging
GStack: 侧重结构化审查 + 沸腾湖泊原则

GStack 特色

主动建议

当用户即将合并代码时，主动建议使用审查：

“我注意到你要合并这个分支。要我先运行 review 技能进行预合并审查吗？“

Completeness 评分

每个选项显示 Completeness 评分：

10 = 完整实现（所有边界情况、100% 覆盖率）
7 = 覆盖快乐路径但跳过一些边界情况
3 = 捷径，推迟重要工作

贡献者模式

如果启用了贡献者模式，在每个主要工作流步骤结束时反思工具使用体验。