name: harness-review description: “多角度评审代码、计划和范围。质量守护者，随时待命。在用户提及评审、代码评审、计划评审、范围分析、安全、性能、质量检查、PR、差异或变更评审时使用。不要在实施工作、新功能开发、错误修复或设置时加载。” description-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.” description-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.” allowed-tools: [“Read”, “Grep”, “Glob”, “Bash”, “Task”] context: fork argument-hint: “[code|plan|scope]” hooks:
- event: PreToolCall type: command command: “${CLAUDE_PLUGIN_ROOT}/scripts/check-codex.sh” once: 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：过去的评审指摘搜索（记忆增强）
如果 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 模式执行时的必须规则
绝对不要在一次 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 模式 | 用途 |
|---|---|---|
| 调试日志 | console.log($$$) |
发布前的残留日志检测 |
| 空 catch | catch ($ERR) { } |
错误忽略检测 |
| 未使用 async | async function $NAME($$$) { $BODY } |
无 await 的 async 检测 |
| 魔法数字 | 数值字面量搜索 | 硬编码常数检测 |
使用例:
harness_ast_search pattern="console.log($$$)" language="typescript" path="src/"
harness_ast_search pattern="catch ($ERR) { }" language="typescript" path="src/"
输出例:
🔍 AST-Grep 代码异味扫描
检查模式:
- console.log($$$) → 调试日志
- catch ($ERR) { } → 空 catch 块
结果:
├── 3x console.log 找到 (src/api/*.ts)
├── 1x 空 catch 块 (src/utils/error.ts:45)
└── 0x 未使用 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 个观点