1. 项目概述：一个为AI时代开发者设计的“自我审视”框架

如果你和我一样，长期在代码、设计和文档之间来回切换，肯定经历过那种“交付时才发现不对劲”的瞬间。明明设计稿上画得清清楚楚，写出来的功能却总觉得差了点意思；或者上周刚总结出一个绝佳的代码模式，这周在新模块里又忘了用。这种“意图”与“交付物”之间的微妙偏差，我们称之为“设计漂移”。它不一定是bug，但却是项目质量无声的腐蚀剂。今天要聊的 motiful/self-review ，就是一个专门为解决这个问题而生的工具——一个能集成到你的AI编程助手（如Claude Code、Cursor）中，帮你系统化“自我审视”的技能包。

简单来说， self-review 不是一个传统的代码检查器或linter。它不关心你的分号有没有加，也不管代码风格是否符合某个规范。它的核心使命是 审计“意图”与“实现”之间的一致性 。无论你是开发者、设计师、内容创作者还是研究者，只要你的工作有“设计构思”和“最终产出”这两个阶段，这个工具就能帮你发现两者之间可能存在的脱节。它的工作方式很特别：通过扫描你项目的四个支柱（设计、产出物、技能、进度）并在它们之间的六个维度上进行交叉检查，来生成一份结构化的审计报告。最让我觉得实用的是，它特别适配当前AI辅助编程的工作流，能作为一个“技能”被你的AI编程助手调用，在你提交代码前，强制插入一个结构化的反思环节。

2. 核心设计理念与差异化优势解析

2.1 从“存在性检查”到“一致性审计”的范式转变

大多数质量保证工具停留在“存在性检查”层面：文件是否存在、测试是否通过、依赖是否安装。 self-review 的目标更高一层： 一致性审计 。它假设你的项目包含四个关键支柱：

1. 设计 ：你的意图、规划、蓝图，无论是写在文档里的，还是存在于你脑海中的心智模型。
2. 产出物 ：最终交付的代码、文档、设计稿等实体。
3. 技能 ：在执行过程中学到并值得固化的经验、模式或教训。
4. 进度 ：项目当前所处的阶段和已完成的工作记录。

这四者之间应该保持对齐。 self-review 的审计，就是检查这四根柱子是否立得正，彼此之间的连接是否牢固。例如，它会问：“设计文档中承诺的功能X，在产出物中是否完整实现？”“在实现功能Y时发现了一个更优的算法，这个新‘技能’有没有被记录下来，并考虑回溯应用到功能X上？”“进度报告说模块Z已完成，但其产出物是否真的达到了设计中的验收标准？”

2.2. 六大差异化特性，解决传统工具的盲区

经过我的深度使用和代码分析，我发现 self-review 有几个设计非常精妙，直接命中了传统开发流程的痛点：

1. 基于范围的智能锁定 这是防止审计报告变成“抱怨清单”的关键。工具会先读取你的“进度”支柱（比如 progress.md 、Git提交历史、TODO注释），来确定当前阶段的工作范围。然后，它会将所有待检查项分类为“范围内”、“已延期”或“范围外”。 只对“范围内”的项目进行审计 。这意味着，你不会在审计Phase 1时，收到一堆关于Phase 2还没开始做的无关警告。这个设计极大地提升了报告的针对性和可操作性。

2. 产出物验证，而非简单存在性检查 这是它比简单脚本强大得多的地方。对于代码，它不只是检查文件是否存在，而是会尝试 运行构建命令、执行CLI工具、运行测试 ，来验证产出物是否真的能工作。比如，它说“测试通过”，意味着它实际执行了 npm test 或 pytest 并看到了成功结果。对于文档，它可能会尝试构建网站来看内部链接是否有效。这种动态验证让审计结果可信度大增。

3. 设计内省：先审视目标本身 在检查设计是否被正确实现之前， self-review 会先对“设计”本身进行一轮审视。它会评估设计目标的清晰度、为用户带来的价值、范围是否合理，以及是否存在更简单的替代方案。这相当于在动手前，强迫你回答：“我们真的要解决这个问题吗？有没有更优雅的解法？” 这个步骤能提前避免在错误的方向上投入大量精力。

4. 假设的时效性检查 这是一个让我拍案叫绝的功能。 self-review 可以（在配置允许的情况下） 使用当前年份的查询词进行网络搜索 ，来验证你设计所依赖的假设是否仍然成立。例如，如果你的设计基于“库A是解决某问题的最佳选择”这个假设，而该库已在去年停止维护，工具就会标记出来。或者，它可能发现社区已经出现了一个标准解决方案，使得你的自定义实现不再必要。这相当于给你的项目加了一个“外部现实检查器”。

5. 基于明确原则的判断 所有的审计发现都不是随意的，而是基于一套内置的、明确的判断原则。这套原则融合了费曼的“好理论”标准（如清晰性、完整性、简洁性）和工程约束（如可维护性、可验证性、演进性）。每个维度的检查都直接对应这些原则的具体问题。这使得审计过程一致、可重复，并且审计结果有据可查，便于团队讨论和复盘。

6. 隐式锚点推断与技能沉淀建议 你不需要有完美的 DESIGN.md 或 progress.md 文件。如果没有显式的设计文档， self-review 会尝试从提交信息、PR描述、代码中的TODO注释、Git日志的时间线甚至代码模式中，推断出你的设计意图和进度。此外，它还会评估在执行过程中学到的经验教训，是否值得被捕获并沉淀为可复用的“技能”（例如，一个最佳实践文档或一个代码模板），并给出具体的沉淀建议。

3. 实战部署与集成指南

3.1 安装与基础配置

self-review 的安装非常简洁，因为它本质上是一个符合 Agent Skills 规范的技能包。最推荐的方式是使用 npx 直接安装：

npx skills add motiful/self-review

这条命令会自动处理下载和链接到正确目录的过程。如果你想手动控制，或者想研究其内部结构，也可以克隆仓库并手动创建软链接：

# 克隆仓库到你的技能目录
git clone https://github.com/motiful/self-review ~/skills/self-review

# 根据你使用的AI编程平台，创建软链接
# 如果是 Claude Code
ln -sfn ~/skills/self-review ~/.claude/skills/self-review

# 如果是 Cursor, Windsurf, Codex 等支持 Agent Skills 的平台
ln -sfn ~/skills/self-review ~/.agents/skills/self-review

安装完成后，通常需要重启你的代码编辑器或AI助手插件，以确保新技能被正确加载。

注意 ： Agent Skills 是一个开放的技能协议，旨在让不同的AI编程助手能共享和调用同样的增强功能。确保你使用的平台（如Cursor的最新版本）支持此协议。你可以在 agentskills.io 查看兼容平台列表。

3.2 在项目中启用与调用

安装技能只是第一步，要让 self-review 对你的项目生效，关键在于项目根目录下的几个“锚点”文件。这些文件构成了审计的四个支柱：

1. 设计支柱 ：最理想的是有一个 DESIGN.md 或 SPEC.md 文件，清晰阐述项目目标、用户故事、架构决策等。如果没时间写详细设计，至少在 README.md 开头用一段话说明项目要解决的核心问题。
2. 进度支柱 ：维护一个 progress.md 或 CHANGELOG.md ，甚至只是保持有意义的Git提交信息。 self-review 能从中解读出阶段划分。
3. 技能支柱 ：可以有一个 SKILLS.md 或 LEARNINGS.md 文件，记录项目过程中总结的模式。没有也没关系，审计报告会建议哪些经验值得沉淀。
4. 产出物 ：这就是你的代码库本身。

调用审计非常简单，在你的AI编程助手的聊天框中，直接输入触发命令即可。根据 SKILL.md 的配置，通常的触发词包括：

• /self-review
• self-review
• audit
• 审视一下 (中文支持)

输入后，AI助手会加载 self-review 技能，开始扫描你的项目目录，执行审计流程，并在几分钟内生成一份详细的Markdown格式报告。

3.3 配置详解与个性化调整

self-review 的默认配置已经相当智能，但为了适应不同项目类型（前端、后端、库、文档站），你可能需要做一些调整。核心配置文件是项目根目录下的 AGENTS.md 、 .cursorrules 或 CLAUDE.md 等文件。 self-review 会读取这些文件中的规则，并将其作为额外的质量关卡。

例如，你可以在 .cursorrules 中加入：

# 项目特定规则
- 所有API响应必须包含 `requestId` 字段。
- 错误处理必须使用中央化的错误中间件。

当 self-review 审计时，它会发现这些规则，并检查代码是否符合这些项目级约定。

此外， self-review 支持“技能组合”。如果你还安装了其他领域技能（如针对React的最佳实践技能、针对数据库设计的技能）， self-review 会 分层引用 这些技能的规则，进行更全面的审计。这意味着你的质量检查体系可以像搭积木一样不断丰富。

4. 审计报告深度解读与问题修复

4.1 报告结构解剖：从摘要到行动项

一份典型的 self-review 报告结构清晰，通常包含以下部分：

1. 执行摘要 ：概述审计范围、发现的严重问题总数、整体一致性评分。让你一眼掌握项目健康度。
2. 范围锁定声明 ：明确列出本次审计基于哪个进度节点（如“基于 progress.md 中标记的 ‘Phase 1: 用户认证’ 完成状态”），以及哪些项目被判定为“范围内”。这是理解后续所有发现的基础。
3. 设计内省结果 ：首先对设计本身提出质疑或肯定。例如：“设计目标‘提升页面加载速度’表述清晰，但缺乏可量化的指标（如目标从X秒降到Y秒）。”
4. 六大维度审计详情 ：这是报告的核心。每个维度下会列出具体发现，每个发现都包含：
   • 问题描述 ：清晰说明哪里不一致。
   • 证据位置 ：精确到文件路径和行号（如 src/auth/service.js:45-52 ）。
   • 涉及的原则 ：指出违反了哪个判断原则（如“违反了‘清晰性’原则”）。
   • 严重等级 ：通常用 ⚠️ （警告）、 ❌ （错误）等标识。
   • 修复建议 ：具体的修改方向或代码示例。
5. 技能沉淀建议 ：列出在本次审计中识别出的、值得记录下来的经验。例如：“在 src/utils/dateFormatter.js 中使用的本地化日期处理模式，建议抽象为共享工具函数，并记录于 SKILLS.md#date-handling 。”
6. 生成的规范草案 ：如果某个问题反复出现且项目中没有对应规范， self-review 会直接起草一段规范文本，并建议你将其添加到 CONTRIBUTING.md 或 README.md 的特定部分。

4.2 典型问题场景与修复策略

结合官方示例和我自己的使用经验，这里列举几个常见的审计发现及处理思路：

场景一：设计漂移——说好的没做

• 报告发现 ：“设计文档中提及‘用户头像支持GIF格式’，但在 UserAvatar 组件中只处理了JPG/PNG。”
• 证据 ： DESIGN.md#user-profile 与 components/UserAvatar.jsx:22 (仅见 ['jpg', 'png'] )。
• 修复 ：这不是简单的遗漏，需要评估。是设计过度了（GIF需求不真实）？还是实现偷工减料？与团队或产品经理确认后，要么更新设计文档，要么补全实现逻辑。

场景二：技能未沉淀——重复发明轮子

• 报告发现 ：“在 api/orders.js 和 api/products.js 中发现了相似的数据验证错误处理逻辑，但未发现对应的共享验证中间件技能记录。”
• 证据 ：两处代码块均包含相似的 try-catch 和错误响应格式。
• 修复 ：这正是提升代码质量的好机会。按照报告建议，创建一个 src/middlewares/validationError.js 中间件，然后将该模式记录到 SKILLS.md 中，并逐步重构其他类似接口。

场景三：过时的外部假设

• 报告发现 ：“设计基于‘使用 axios-fetch-adapter 库来解决SSR环境下的请求兼容性’，但网络检查发现该库近两年无维护，且Next.js 13+已内置等效解决方案。”
• 证据 ： DESIGN.md#tech-stack 提及该库；网络查询显示其GitHub仓库最后更新于2022年。
• 修复 ：研究Next.js最新文档，评估移除该适配器库的可行性，并更新技术选型部分。这个发现可能为你节省了未来的一个兼容性大坑。

场景四：进度与产出物不符

• 报告发现 ：“ progress.md 标记‘用户仪表盘数据可视化完成’，但 dashboard/charts/ 目录下仅有一个静态示例文件，动态数据获取与绑定逻辑缺失。”
• 证据 ： progress.md 第8项 vs. 相关源代码文件。
• 修复 ：更新进度报告的真实状态为“进行中”，或者紧急补全缺失的逻辑。这有助于保持项目管理信息的准确性。

4.3 将审计融入开发工作流

单独运行一次审计很有用，但将其制度化才能发挥最大价值。我建议的集成点：

1. 提交前自查 ：在完成一个功能模块、准备提交Pull Request之前，运行一次 self-review 。把它当作一次强制的“预检”，确保你的代码实现了你承诺的功能。
2. 迭代周期回顾 ：在每个冲刺或迭代周期结束时，对主要交付物运行审计。报告可以作为周期回顾会议的材料，系统化地讨论哪些地方出现了“漂移”，原因是什么，如何改进流程。
3. 文档更新触发器 ：将 self-review 的报告视为更新项目文档的触发器。当它建议增加一条新规范或更新设计文档时，立即（或安排）处理，让文档与代码同步进化。
4. 新手入职指南 ：让新成员在熟悉项目代码后，对某个小模块运行 self-review 。报告能非常直观地展示项目的设计理念、现有规范以及实际执行情况，是比阅读零散文档更高效的学习方式。

5. 高级技巧、常见问题与排查

5.1 针对不同项目类型的优化配置

self-review 是通用的，但通过一些配置可以让它更贴合你的项目。

• 纯文档/内容项目 ：确保你的“产出物”是可构建的（如Markdown可通过静态站点生成器构建）。在项目根目录添加一个简单的 makefile 或 package.json 脚本，用于构建文档站点。 self-review 会执行这个构建命令来验证链接和格式。
• 前端项目 ：充分利用“假设时效性检查”。在 DESIGN.md 中明确记录你所选用的关键前端库和版本（如“采用React 18 + Zustand进行状态管理”）。审计时会帮你检查是否有更稳定、更主流的新选择出现。
• 后端/API项目 ：重点维护好 progress.md ，将API端点与实现状态一一对应。 self-review 的范围锁定功能能确保只审计已声明“完成”的API，避免噪音。
• 设计稿项目 ：将设计文件（Figma链接、Sketch文件）的当前版本号或哈希值记录在 DESIGN.md 中。虽然工具不能直接解析设计文件，但你可以通过注释说明“产出物（代码）应与设计稿v2.3保持一致”，为人工复核提供明确依据。

5.2 性能与深度权衡

对于大型项目，全量审计可能耗时较长。你可以通过以下方式控制：

• 指定路径 ：在调用时，可以尝试指定子目录，如 /self-review src/components ，只审计特定模块。
• 调整验证深度 ：默认配置会运行构建和测试。如果只想快速进行静态分析，可以查阅 SKILL.md 看是否有环境变量或参数可以跳过耗时步骤（例如 SELF_REVIEW_SKIP_BUILD=true ）。 但请注意，这会降低审计的置信度。
• 阶段性审计 ：不要每次都审计整个项目。结合“范围锁定”，只对当前活跃的、标记为“进行中”或“刚完成”的模块进行深入审计。

5.3 常见问题与解决方案

Q1: 运行 self-review 后，AI助手没有反应或报错。 A1: 首先确认技能安装路径正确，并且你的AI助手平台支持 Agent Skills 。尝试在平台内重新加载技能列表或重启编辑器。检查项目根目录是否有最基本的锚点文件（至少要有 README.md 和若干代码文件），空目录可能无法触发有效审计。

Q2: 审计报告没有网络检查（假设时效性）部分。 A2: 网络检查功能可能需要显式启用或配置API密钥（如SerpAPI等）。检查 self-review 技能的文档或 SKILL.md ，看是否有相关的配置说明。出于隐私和成本考虑，该功能可能默认关闭。

Q3: 报告中的“技能沉淀建议”我觉得不重要，可以忽略吗？ A3: 完全可以。报告只是建议。但建议你至少花一分钟思考：这个被重复的模式未来三个月内还会用到吗？如果答案是肯定的，那么花十分钟把它沉淀下来，长远看是节省时间的。你可以建立一个简单的 SKILLS.md 文件，哪怕只是记录“某类问题，用某段代码”。

Q4: 它和ESLint/Prettier/单元测试有什么区别？ A4: 互补而非替代 。ESLint/Prettier管代码风格和语法，单元测试验证代码逻辑是否正确。 self-review 管的是更高层次的“一致性”：你的代码是否实现了设计目标？项目文档是否跟上了代码变化？团队积累的经验有没有被记录下来？它填补了传统工具在“意图管理”和“知识管理”方面的空白。

Q5: 一定要用AI助手才能使用吗？ A5: 从仓库结构看， self-review 的核心是一套定义清晰的审计逻辑和规则（在 references/dimensions.md 等文件中）。虽然目前它主要通过AI技能的形式提供最流畅的体验，但其理念和检查清单是独立的。有经验的团队完全可以将其检查点提炼出来，作为代码审查或设计评审的检查列表来手动执行。当然，自动化执行带来的效率和一致性是手动无法比拟的。

这个工具的精髓不在于某个酷炫的功能，而在于它引入了一种 系统化的、基于原则的反思习惯 。在AI加速开发的时代，我们更容易一头扎进“生成-修改”的循环里，而忽略了停下来问一句：“我做的，是我最初想做的吗？” self-review 就是那个逼你暂停、帮你审视的伙伴。