名称: harness-review 描述: “多角度审查代码、计划和范围。质量守护者随时为您服务。当用户提到审查、代码审查、计划审查、范围分析、安全、性能、质量检查、PRs、差异或变更审查时使用。不要用于：实施工作、新功能开发、错误修复或设置。” 描述-en: “Multi-angle review of code, plans, and scope. Quality guardian at your service. Use when user mentions reviews, code review, plan review, scope analysis, security, performance, quality checks, PRs, diffs, or change review. Do NOT load for: implementation work, new feature development, bug fixes, or setup.” 描述-ja: “コード・プラン・スコープを多角的にレビュー。品質の番人、参上。Use when user mentions reviews, code review, plan review, scope analysis, security, performance, quality checks, PRs, diffs, or change review. Do NOT load for: implementation work, new feature development, bug fixes, or setup.” 允许工具: [“读取”, “搜索”, “全局”, “Bash”, “任务”] 上下文: fork 参数提示: “[代码|计划|范围]” 钩子:
- 事件: 预工具调用 类型: 命令 命令: “${CLAUDE_PLUGIN_ROOT}/scripts/check-codex.sh” 一次: true
审查技能
负责代码审查、计划审查、范围分析的技能群。 从上下文自动判定审查类型。
审查类型（上下文感知）
审查类型从上下文自动判定：
| 最近活动 | 审查类型 | 4专家 |
|---|---|---|
/plan-with-agent 后 |
计划审查 | 清晰度、可行性、依赖关系、接受度 |
/work 后 |
代码审查 | 安全、性能、质量、可访问性 |
| 任务添加后 | 范围审查 | 范围蔓延、优先级、可行性、影响 |
手动指定
/harness-review # 自动判定
/harness-review code # 强制代码审查
/harness-review plan # 强制计划审查
/harness-review scope # 强制范围分析
功能详细（代码审查）
| 功能 | 详细 |
|---|---|
| 变更审查 | 参见 references/changes-review.md |
| 质量检查 | 参见 references/quality-review.md |
| 安全 | 参见 references/security-review.md |
| 性能 | 参见 references/performance-review.md |
| 可访问性 | 参见 references/accessibility-review.md |
| SEO/OGP | 参见 references/seo-review.md |
| Codex 集成 | 参见 references/codex-integration.md |
| 提交判定 | 参见 references/commit-judgment-logic.md |
功能详细（计划/范围审查）
计划审查和范围审查使用 Codex 专家：
| 审查类型 | 专家 | 参考 |
|---|---|---|
| 计划审查 | 清晰度、可行性、依赖关系、接受度 | ../codex-review/references/experts/clarity-expert.md 等 |
| 范围审查 | 范围蔓延、优先级、可行性、影响 | ../codex-review/references/experts/scope-creep-expert.md 等 |
详细: …/codex-review/references/codex-parallel-review.md
执行步骤
- 质量判定门（步骤 0）
- 剩余上下文确认（Codex 模式时）（步骤 1）
- 分类用户的请求
- （Claude-mem 有效时）搜索过去的审查指摘
- 判定并行执行（参见下文）
- 从上述“功能详细”中读取适当的参考文件，或启动并行子代理
- 整合结果完成审查
输入的优先级
- 如果传递了
files，则仅审查那些文件 - 如果没有传递
files，则从git_diff推断变更位置 - 如果传递了
context_from: code_content，则优先审查该内容
步骤 0: 质量判定门（确定审查重点领域）
审查开始前分析变更内容，确定重点领域：
变更文件分析
↓
┌─────────────────────────────────────────┐
│ 质量判定门 │
├─────────────────────────────────────────┤
│ 判定项目: │
│ ├── 覆盖率不足？（无测试） │
│ ├── 安全注意？（auth/api/） │
│ ├── a11y 注意？（UI 组件） │
│ └── 性能注意？（DB/循环） │
└─────────────────────────────────────────┘
↓
确定重点审查领域
覆盖率判定
| 情况 | 指摘内容 |
|---|---|
| 新文件无测试 | “测试不足” |
| 变更文件的测试过时 | “考虑更新测试” |
| 覆盖率 < 60% | “建议提高覆盖率” |
安全重点审查
| 路径 | 追加检查项目 |
|---|---|
| auth/, api/ | OWASP Top 10 检查清单 |
| 输入处理 | 消毒、验证 |
| DB 查询 | 参数化确认 |
a11y 重点审查
| 路径 | 检查项目 |
|---|---|
| src/components/ | alt, aria, 键盘操作 |
| src/pages/ | 标题结构, 焦点管理 |
性能重点审查
| 模式 | 警告内容 |
|---|---|
| 循环内 DB 查询 | N+1 查询的可能性 |
| 大规模数据处理 | 考虑分页 |
| useEffect 滥用 | 渲染优化 |
SEO/OGP 重点审查
| 路径 | 检查项目 |
|---|---|
| src/pages/, app/ | title, description, canonical |
| public/ | robots.txt, sitemap.xml, OGP 图像 |
| layout.tsx, _document.tsx | viewport, OGP 标签, Twitter Card |
跨平台重点审查
| 路径 | 检查项目 |
|---|---|
| src/components/, app/ | 响应式（固定宽检查） |
| *.css, *.scss, tailwind | 100vw 使用、overflow 设置 |
| public/ | favicon, apple-touch-icon |
重点审查整合输出
📊 质量判定结果 → 重点审查领域
| 判定 | 该当 | 目标文件 |
|------|------|-------------|
| 安全 | ⚠️ | src/api/auth.ts |
| 覆盖率 | ⚠️ | src/utils/helpers.ts (无测试) |
| a11y | ✅ | - |
| 性能 | ✅ | - |
| SEO/OGP | ⚠️ | app/layout.tsx (OGP 未设置) |
| 跨平台 | ✅ | - |
→ 重点审查安全、覆盖率、SEO
LSP 基础的影响分析（推荐）
变更审查时使用 LSP 工具确认影响范围：
| 变更类型 | LSP 操作 | 确认内容 |
|---|---|---|
| 函数签名变更 | findReferences | 所有调用方是否已对应 |
| 类型定义变更 | findReferences | 使用处的类型兼容性 |
| API 变更 | incomingCalls | 受影响的端点 |
审查流程:
- 确定变更文件
- 使用
LSP.findReferences列举影响范围 - 包括受影响文件进行审查
使用例:
# 1. 确认变更函数的参照处
LSP operation=findReferences filePath="src/api/user.ts" line=42 character=15
# 2. 确认函数的调用层次
LSP operation=incomingCalls filePath="src/api/user.ts" line=42 character=15
# 3. 确认类型定义的使用处
LSP operation=findReferences filePath="src/types/api.ts" line=10 character=12
输出例:
🔍 LSP 影响分析结果
变更: updateUserProfile() 的签名变更
受影响的地方:
├── src/pages/profile.tsx:89 ⚠️ 需要更新参数
├── src/pages/settings.tsx:145 ⚠️ 需要更新参数
├── tests/user.test.ts:67 ✅ 已更新
└── src/api/admin.ts:23 ⚠️ 需要更新参数
→ 3处需要更新参数
注: 仅在设置了 LSP 服务器的语言中工作。
步骤 1: 剩余上下文确认（Codex 模式时）
Codex 模式（review.mode: codex）时，如果剩余上下文低于 30%，先执行 /compact。
注意: /compact 后如果余裕少，不退行继续。
Git log 扩展标志的活用（CC 2.1.49+）
审查时活用结构化的日志进行提交分析。
变更历史的结构化分析
# 获取结构化格式的提交历史
git log --format="%h|%s|%an|%ad" --date=short -10
# 排除合并提交进行审查
git log --cherry-pick --no-merges main..HEAD
# 附带变更文件列表
git log --raw -5
主要活用场景
| 用途 | 标志 | 效果 |
|---|---|---|
| 获取提交列表 | `–format="%h | %s"` |
| 明确审查对象 | --cherry-pick --no-merges |
排除合并提交 |
| 变更影响分析 | --raw |
详细显示文件变更 |
| 时间序列原因追踪 | --topo-order |
拓扑排序 |
输出例
📊 提交历史分析（结构化）
| Hash | Subject | Author | Date |
|------|---------|--------|------|
| a1b2c3d | feat: 添加认证 | Alice | 2026-02-04 |
| e4f5g6h | fix: cors 错误 | Bob | 2026-02-03 |
变更文件（--raw）:
├── src/auth.ts (修改)
├── src/api/middleware.ts (添加)
└── tests/auth.test.ts (修改)
→ 重点审查认证周边的变更
步骤 2: 搜索过去的审查指摘（Memory-Enhanced）
Claude-mem 有效时，审查开始前搜索过去的类似指摘：
# 使用 mem-search 搜索过去的审查指摘
mem-search: type:review "{变更文件的模式}"
mem-search: concepts:security "{安全相关的关键词}"
mem-search: concepts:gotcha "{变更处相关的关键词}"
显示例:
📚 过去的审查指摘（相关）
| 日期 | 指摘内容 | 文件 |
|------|---------|---------|
| 2024-01-15 | XSS脆弱性: 禁止使用 innerHTML | src/components/*.tsx |
| 2024-01-20 | N+1查询: 必须 prefetch | src/api/*.ts |
💡 本次审查中重点检查上述模式
注: 如果 Claude-mem 未设置，跳过此步骤。
审查模式的选择
审查技能以 2 种模式工作：
确认设置: .claude-code-harness.config.yaml
↓
├── review.mode: default → Claude 单独审查
└── review.mode: codex → Codex 并行审查（按审查类型 4 专家）
Default 模式（Claude 单独）
Claude 直接执行审查。最适合小〜中规模变更。
Codex 模式（并行专家）
通过 Codex MCP 按审查类型对应的 4 个专家 个别并行调用:
| 审查类型 | 专家 |
|---|---|
| 代码审查 | 安全、性能、质量、可访问性 |
| 计划审查 | 清晰度、可行性、依赖关系、接受度 |
| 范围审查 | 范围蔓延、优先级、可行性、影响 |
⚠️ Codex 模式执行时的必须规则
绝对不要在 1 次 MCP 调用中汇总多个专家。
✅ 正确: 在 1 个响应内并行执行 4 次 MCP 调用
❌ 错误: 在 1 次调用中请求“从全观点审查”
执行步骤:
- 判定调用的专家（仅需而非全部）:
- 设置中
enabled: false→ 排除 - CLI/后端 → 排除可访问性、SEO
- 仅文档变更 → 优先质量、架构、计划审查员、范围分析师（可排除安全、性能）
- 设置中
- 从有效专家的
experts/*.md个别读取 提示 - 仅有效专家 在 Bash 后台进程中并行执行
codex exec - 整合各结果判定
详细: codex-review/references/codex-parallel-review.md
Codex 模式有效化:
/codex-mode on
详细: references/codex-integration.md
并行子代理启动（Default 模式）
变更文件数・审查观点的计算（必须）
files_count 基于 merge-base 计算（包括 staged/unstaged）:
base=$(git merge-base HEAD origin/main 2>/dev/null \
|| git merge-base HEAD main 2>/dev/null \
|| git merge-base HEAD master 2>/dev/null \
|| git rev-parse HEAD~1 2>/dev/null \
|| git hash-object -t tree /dev/null)
committed=$(git diff --name-only --diff-filter=ACMRTUXB $base...HEAD)
staged=$(git diff --name-only --cached)
unstaged=$(git diff --name-only)
files=$(echo -e "$committed
$staged
$unstaged" | sort -u | grep -v '^$')
files_count=$(echo "$files" | wc -l)
review_aspects 基于路径检测:
function countReviewAspects(files) {
let aspects = 0;
if (files.some(f => /\/(auth|api|middleware|security)\//.test(f))) aspects++;
if (files.some(f => /\/(db|sql|repository|cache)\//.test(f))) aspects++;
if (files.some(f => /\/(components|pages|app)\/.*\.tsx$/.test(f))) aspects++;
if (files.some(f => /\/(pages|app)\/.*\.(metadata|head|seo)/.test(f))) aspects++;
return Math.max(aspects, 1);
}
满足以下两条件时，使用 Task tool 并行启动 code-reviewer:
- 审查观点 >= 2（例: 安全 + 性能）
- 变更文件 >= 5
启动模式（在 1 个响应内同时调用多个 Task tool）:
Task tool 并行调用:
#1: subagent_type="code-reviewer"
prompt="从安全观点审查: {files}"
#2: subagent_type="code-reviewer"
prompt="从性能观点审查: {files}"
#3: subagent_type="code-reviewer"
prompt="从代码质量观点审查: {files}"
小规模情况（不满足条件）:
- 顺序读取子技能（doc.md）串行执行
🔧 MCP Code Intelligence 工具的活用
审查中活用 MCP 工具（AST-Grep, LSP）提高精度。
重要: 如果通过
/dev-tools-setup设置了 MCP 服务器，优先使用 MCP 工具 而非标准工具（Grep, Read）。MCP 工具可以进行结构性搜索，获得更准确结果。
AST-Grep MCP 工具（harness_ast_search）
用于结构性代码模式搜索。比基于正则表达式的 Grep 精度高，最适合代码气味检测。
| 检测模式 | AST-Grep 模式 | 用途 |
|---|---|---|
| Debug logs | console.log($$$) |
发布前残留日志检测 |
| Empty catch | catch ($ERR) { } |
错误掩盖检测 |
| Unused async | async function $NAME($$$) { $BODY } |
无 await 的 async 检测 |
| Magic numbers | 数值文字搜索 | 硬编码常数检测 |
使用例:
harness_ast_search pattern="console.log($$$)" language="typescript" path="src/"
harness_ast_search pattern="catch ($ERR) { }" language="typescript" path="src/"
输出例:
🔍 AST-Grep Code Smell Scan
Patterns checked:
- console.log($$$) → Debug logs
- catch ($ERR) { } → Empty catch blocks
Results:
├── 3x console.log found (src/api/*.ts)
├── 1x empty catch block (src/utils/error.ts:45)
└── 0x unused async
注: 如果
harness_ast_search不可用，回退到sg命令（Bash）或 Grep。
🔧 LSP 功能的活用
审查中活用 LSP（Language Server Protocol）提高精度。
MCP 版优先: 如果可用
harness_lsp_*MCP 工具，优先使用于标准 LSP 工具。
LSP 集成到审查
| 审查观点 | LSP 活用方法 |
|---|---|
| 质量 | Diagnostics 自动检测类型错误・未使用变量 |
| 安全 | Find-references 追踪机密数据流 |
| 性能 | Go-to-definition 确认重处理实现 |
LSP Diagnostics 的输出例
📊 LSP 诊断结果
| 文件 | 错误 | 警告 |
|---------|--------|------|
| src/components/Form.tsx | 0 | 2 |
| src/utils/api.ts | 1 | 0 |
⚠️ 检测到 1 个错误
→ 添加到审查指摘事项
Find-references 的影响分析
🔍 变更影响分析
变更: validateInput()
参照处:
├── src/pages/signup.tsx:34
├── src/pages/settings.tsx:56
└── tests/validate.test.ts:12
→ 测试已覆盖 ✅
🔧 PDF 页面范围读取（Claude Code 2.1.49+）
文档审查时高效处理大型 PDF 的功能。
页面范围指定读取
// 页面范围指定读取
Read({ file_path: "docs/architecture.pdf", pages: "1-15" })
// 仅变更历史部分
Read({ file_path: "docs/changelog.pdf", pages: "5-12" })
// 仅安全要求
Read({ file_path: "docs/requirements.pdf", pages: "45-60" })
文档审查时的推荐方法
| 审查对象 | 推荐读取方法 | 理由 |
|---|---|---|
| 大型规格书 | 目录 + 仅变更处 | 集中相关部分 |
| API设计书 | 端点列表 + 安全章 | 优先重要观点 |
| 架构文档 | 系统构成图 + 非功能要求 | 缩小审查对象 |
| 用户手册 | 目录 + 可访问性项 | 确认易用性 |
| 发布笔记 | 仅最新版本的变更点 | 特定相关变更 |
审查观点别的活用例
安全审查
大型安全规格书（200页）的审查:
1. **把握目录结构**（1-3页）
Read({ file_path: "security-spec.pdf", pages: "1-3" })
2. **精读认证・授权章**（25-45页）
Read({ file_path: "security-spec.pdf", pages: "25-45" })
3. **精读脆弱性对策章**（78-92页）
Read({ file_path: "security-spec.pdf", pages: "78-92" })
此方法可高效确认安全审查所需部分。
性能审查
性能要求书（150页）的审查:
1. **目录和摘要**（1-5页）
Read({ file_path: "performance-spec.pdf", pages: "1-5" })
2. **响应时间要求**（34-50页）
Read({ file_path: "performance-spec.pdf", pages: "34-50" })
3. **负载测试结果**（120-135页）
Read({ file_path: "performance-spec.pdf", pages: "120-135" })
审查工作流集成
步骤 0: 质量判定门（文档分析）
文档审查时，首先使用页面范围指定把握概要：
1. 阅读目录理解结构
Read({ file_path: "spec.pdf", pages: "1-3" })
2. 特定变更处
从目录获取变更部分的页面号
3. 仅精读相关部分
Read({ file_path: "spec.pdf", pages: "{变更范围}" })
4观点审查中的活用
| 观点 | 应读的页面范围 | 例 |
|---|---|---|
| 安全 | 认证・授权、加密、脆弱性对策 | pages: “25-45,78-92” |
| 性能 | 非功能要求、负载测试结果 | pages: “34-50,120-135” |
| 质量 | 编码规范、测试策略 | pages: “60-75” |
| 可访问性 | UI/UX要求、WCAG 准据 | pages: “95-110” |
最佳实践
| 原则 | 说明 |
|---|---|
| 目录优先 | 始终先把握结构再深入 |
| 观点别页面范围 | 按审查观点特定所需页面 |
| 集中变更差分 | 仅审查现有文档的变更处 |
| 重要性顺序 | 按 Critical → Major → Minor 顺序阅读 |
令牌消耗的比较
| 审查方法 | 文档规模 | 令牌消耗 | 审查精度 |
|---|---|---|---|
| 全页读取 | 200页 | ~100,000 | 高 |
| 页面范围指定 | 所需30页 | ~15,000 | 高 |
→ 可能减少 85% 的令牌消耗和审查时间
注意事项
- 页面范围是 1-indexed（第1页是
pages: "1"） - 未支持多范围（将来扩展中对应）
- 当前仅可指定连续页面范围
VibeCoder 向
📝 请求代码检查时的说法
1. **“检查一下”**
- 请整体看看是否有问题
2. **“安全没问题吗？”**
- 检查是否能抵抗恶意攻击
3. **“不慢吗？”**
- 检查速度是否有问题
4. **“谁都能用吗？”**
- 检查是否有障碍的人也能使用
💡 提示: 如果说“全部检查一下”，
自动确认全部 4 个观点