القائمة
进行多维度代码评审。适用于合并任何变更之前。适用于评审由你自己、另一个 agent 或人类编写的代码。适用于在代码进入主分支之前，需要跨多个维度评估代码质量的场景。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Manage git submodules for the learning-open-code mono-repo. Use when the user wants to: (1) Add a new git submodule — auto-detect or specify the category (open-ai-skills/open-sdd/open-ai-agent/open-ai-desktop/open-knowledge/open-productivity/open-java/open-trading/open-data), record the tracking branch in .gitmodules, clone the repo, and update README.md index. (2) Sync all existing submodules to their configured branches (git fetch + checkout branch + pull). (3) Update the root README.md with an up-to-date index of all synced projects grouped by category. (4) Initialize submodules after git clone — when open-*/ directories are empty or git submodule status returns nothing, guide through the full SOP (git submodule update --init --recursive [--remote]). Trigger keywords: submodule, git submodule, 子模块, add submodule, sync submodule, update submodule, submodule branch, README index, 更新索引, clone, init, 初始化子模块, submodule init, 拉取子模块.
对开源项目进行穷尽式教学文档生成——从宏观架构到微观实现的五层分级讲解，使用 Goal Loop 算法自主驱动完整代码覆盖。所有具体教学内容生成必须激活 `.agents/skills/teach/SKILL.md`。触发条件：用户要求"完整学习某个项目"、"生成项目架构文档"、"从入口到落地讲清楚每个功能"、"代码考古"、"源码分析"、或指定一个项目目录/仓库要求全面教学。
使用并行子 agent 为模块生成多个截然不同的接口设计。当用户想要设计 API、探索接口选项、比较模块形态，或提到 "设计两次" 时使用。
交互式 QA 会话，用户以对话方式报告 bug 或问题，agent 将其录入 GitHub Issue。在后台探索代码库以获取上下文和领域语言。当用户想要报告 bug、做 QA、以对话方式录入 issue，或提及 "QA session" 时使用。
通过用户访谈创建包含微小提交的详细重构计划，并将其录入 GitHub Issue。当用户想要规划重构、创建重构 RFC，或将重构分解为安全的渐进步骤时使用。
从当前对话中提取 DDD 风格的通用语言词汇表，标记歧义并提出规范术语。保存到 UBIQUITOUS_LANGUAGE.md。当用户想要定义领域术语、构建词汇表、固化术语、创建通用语言，或提到 "领域模型" 或 "DDD" 时使用。
| name | code-review-and-quality |
| description | 进行多维度代码评审。适用于合并任何变更之前。适用于评审由你自己、另一个 agent 或人类编写的代码。适用于在代码进入主分支之前，需要跨多个维度评估代码质量的场景。 |
带质量门控的多维代码评审。每个变更在合并之前都需经过评审——无例外。评审覆盖五个维度：正确性、可读性、架构、安全性和性能。
通过标准： 当变更确实改善了整体代码健康状况时批准，即使它不完美。完美的代码不存在——目标是持续改进。不要因为代码不是按照你的方式编写的就阻止变更。如果它改善了代码库并遵循项目约定，就批准它。
每次评审均从以下维度评估代码：
代码是否做了它声称要做的事？
另一个工程师（或 agent）能否在作者不解释的情况下理解此代码？
temp、data、result）_unused）、向后兼容垫片或 // removed 注释？变更是否适合系统的设计？
any/unknown/optional/强制转换，以及掩盖不清晰不变量的静默回退——使边界明确通常会使周围的流程更简单。详细安全指引参见 security-and-hardening。此变更是否引入了漏洞？
详细的性能分析与优化参见 performance-optimization。此变更是否引入了性能问题？
当你标记一个结构性问题时，提出移动方案——而不仅是问题本身。一个仅说"这很复杂"的评审让作者只能猜测。使用命名的重构方式：
优先选择减少活动部件的修复方案，而非将相同复杂性摊开的修复方案。
小而聚焦的变更更易于评审、更快合并、更安全部署。以以下规模为目标：
约 100 行变更 → 良好。可一次阅读评审完毕。
约 300 行变更 → 若是单次逻辑变更可以接受。
约 1000 行变更 → 过大。请拆分。
关注文件大小，而不仅是 diff 大小。 小的 diff 仍然可能将文件推过合理边界——单个文件总共约 1000 行（区别于上文中约 1000 变更行的阈值）是一个常见的检查信号，而非硬性上限。当一次变更显著增长一个已经很大的文件时，应问自己：是否应先提取辅助函数、子组件或模块，再继续往上堆叠。先分解，再添加。
什么算"一次变更"： 一个自包含的修改，解决一件事，包含相关测试，且在提交后保持系统可用。这是功能的一部分——而非整个功能。
变更过大时的拆分策略：
| 策略 | 方式 | 适用场景 |
|---|---|---|
| 堆叠式 | 先提交一个小变更，再基于它开始下一个 | 串行依赖关系 |
| 按文件组 | 对不同组的文件分别提交，供不同评审者评审 | 横切关注点 |
| 水平式 | 先创建共享代码 / 桩代码，再创建消费者 | 分层架构 |
| 垂直式 | 将功能拆分为较小的全栈切片 | 功能开发 |
可接受的大变更： 完整的文件删除和自动化重构，评审者只需验证意图，无需逐行检查。
将重构与功能开发分开。 一个既重构现有代码又添加新行为的变更是两次变更——分别提交。小的清理（变量重命名）可在评审者酌情考虑后包含在内。
每个变更需要一段在版本控制历史中能够独立存在的描述。
首行： 简短、祈使语气、独立。如"删除 FizzBuzz RPC"而非"正在删除 FizzBuzz RPC"。必须信息量足够，让搜索历史的人无需阅读 diff 即可理解此变更。
正文： 变更了什么以及为什么。包含代码本身不可见的上下文、决策和推理。链接到相关的 Bug 号、基准测试结果或设计文档。在存在不足时，承认方法上的欠缺。
反模式： "修复 Bug"、"修复构建"、"添加补丁"、"将代码从 A 移到 B"、"第 1 阶段"、"添加便利函数"。
在审视代码之前，理解意图：
- 此变更试图达成什么？
- 它实现了什么规格或任务？
- 预期的行为变更是什么？
测试揭示了意图和覆盖范围：
- 此变更是否存在测试？
- 测试的是行为（而非实现细节）吗？
- 是否覆盖了边界情况？
- 测试是否有描述性的名称？
- 如果代码变更，测试能否捕捉到回归？
带着五维度的视角审视代码：
对每个变更的文件：
1. 正确性：此代码是否做到了测试所说的？
2. 可读性：我能否无需帮助就能理解？
3. 架构：此代码是否适合系统设计？
4. 安全性：是否存在漏洞？
5. 性能：是否存在瓶颈？
为每条评论标注严重级别，让作者清楚什么是必须的，什么是可选的：
| 前缀 | 含义 | 作者操作 |
|---|---|---|
| （无前缀） | 必须修改 | 合并前必须处理 |
| Critical（严重）： | 阻塞合并 | 安全漏洞、数据丢失、功能损坏 |
| Nit（细枝末节）： | 次要、可选 | 作者可忽略——格式、风格偏好 |
| Optional（可选）： / Consider（考虑）： | 建议 | 值得考虑但非必须 |
| FYI（供参考） | 仅信息性 | 无需操作——供将来参考的上下文 |
这可以防止作者将所有反馈视为强制性并浪费时间在可选建议上。
优先处理最重要的内容。 按杠杆效应排序发现：正确性和安全性优先，然后是结构性退化和遗漏的简化，最后是其他。不要将真正的问题埋在表面性琐碎问题下——几个高确定性的评论胜过一长串细枝末节。如果你有一个结构性问题和十个琐碎问题，那个结构性问题就是评审的核心。
检查作者的验证情况：
- 运行了哪些测试？
- 构建是否通过？
- 变更是否经过了手动测试？
- UI 变更是否有截图？
- 是否有前后对比？
使用不同模型获取不同的评审视角：
模型 A 编写代码
│
▼
模型 B 评审正确性和架构
│
▼
模型 A 处理反馈
│
▼
人类做出最终决定
这可以发现单一模型可能遗漏的问题——不同模型有不同的盲点。
评审 agent 的示例提示：
评审此代码变更的正确性、安全性，以及是否符合我们的项目约定。
规格描述是 [X]。此变更应达到 [Y]。
将问题标记为 Critical、Required、Optional 或 Nit。
在任何重构或实现变更之后，检查孤立的代码：
不要让死代码闲置于此——它会迷惑未来的读者和 agent。但也不要悄悄删除你不确定的东西。如有疑问，先问。
发现的死代码：
- src/utils/date.ts 中的 formatLegacyDate() — 已被 formatDate() 替代
- src/components/ 中的 OldTaskCard 组件 — 已被 TaskCard 替代
- src/config.ts 中的 LEGACY_API_URL 常量 — 无剩余引用
→ 可以安全删除这些吗？
慢的评审会阻塞整个团队。上下文切换进行评审的成本低于强加给他人的等待成本。
解决评审争议时，按以下层级处理：
不要接受"我之后会清理"。 经验表明延迟的清理很少发生。要求提交前清理，除非是真正的紧急情况。如果相关内容无法在本次变更中处理，要求提交一个 Bug 并自分配。
在评审代码时——无论是由你、另一个 agent 还是人类编写的：
代码评审的一部分是依赖评审：
在添加任何依赖项之前：
npm audit）规则： 优先使用标准库和现有工具函数，而非新依赖。每个依赖都是一项负债。
## 评审：[PR/变更标题]
### 上下文
- [ ] 我理解此变更做了什么以及为什么
### 正确性
- [ ] 变更匹配规格 / 任务需求
- [ ] 边界情况已处理
- [ ] 错误路径已处理
- [ ] 测试充分覆盖此变更
### 可读性
- [ ] 命名清晰且一致
- [ ] 逻辑直观易懂
- [ ] 无不必要的复杂性
### 架构
- [ ] 遵循现有模式
- [ ] 无不必要的耦合或依赖
- [ ] 抽象层级适当
- [ ] 重构减少了复杂性而非重新安置它
- [ ] 无功能逻辑在共享模块中；文件大小保持在合理范围内
### 安全性
- [ ] 代码中无密钥
- [ ] 输入在边界进行了验证
- [ ] 无注入漏洞
- [ ] 认证检查到位
- [ ] 外部数据源被视为不可信
### 性能
- [ ] 无 N+1 模式
- [ ] 无无界操作
- [ ] 列表端点有分页
### 验证
- [ ] 测试通过
- [ ] 构建成功
- [ ] 手动验证已完成（如适用）
### 裁定
- [ ] **批准** — 可以合并
- [ ] **要求修改** — 问题必须处理
references/security-checklist.mdreferences/performance-checklist.md| 借口 | 现实 |
|---|---|
| "能跑就行，够好了" | 能跑但不可读、不安全或架构错误的代码，会产生复利式的债务。 |
| "我自己写的，我知道它是正确的" | 作者对自己的假设视而不见。每个变更从另一双眼睛中受益。 |
| "我们以后再清理" | 以后再也不会来。评审就是质量门控——利用它。要求合并前清理，而非合并后。 |
| "AI 生成的代码应该没问题" | AI 代码需要更多审查，而非更少。它自信且合理，即使它是错误的。 |
| "测试通过了，所以没问题" | 测试是必要的但不充分。它们不能捕捉到架构问题、安全问题或可读性问题。 |
| "这个重构让它更干净了" | 重新安置复杂性不是减少复杂性。如果读者仍需记住相同数量的概念，结构就没有改进——寻找分支能够消失的版本。 |
| "只是给这个文件加了一小点" | 小的 diff 仍然能将文件推过健康大小，并向不相关的流程中添加分支。评判的是最终结构，而非 diff 大小。 |
评审完成后：
推定阻塞项： 对以下每项，暴露并提议更简单的设计；仅当变更实际恶化了结构时才升级为 Required：一个重新安置而非减少复杂性的重构；一个将文件推过大小边界而无分解的变更；添加到共享模块中的功能逻辑；对现有规范辅助函数的近乎重复的实现；隐藏不清晰不变量的静默回退。