AI代理自我审查框架：防止设计漂移，确保意图与交付对齐

1. 项目概述一个为AI代理和开发者设计的自我审查框架在任何一个需要交付成果的创作或开发项目中无论是写代码、做设计还是搞研究我们都会面临一个共同的困境最初的设想和最终的成品之间总会不知不觉地产生偏差。这种“设计漂移”现象就像你计划画一幅风景画结果画着画着不知不觉就变成了一幅抽象画回头一看才发现和最初的草图相去甚远。对于开发者来说这可能意味着代码实现偏离了技术方案对于内容创作者可能是成片与脚本的初衷不符。更棘手的是这种偏差往往在项目接近尾声时才被发现导致返工成本高昂。今天要聊的motiful/self-review就是为了解决这个问题而生的。它不是一个传统的代码检查工具而是一个结构化的“自我审查”框架。它的核心思想是在项目交付前的关键节点强制你停下来系统地审视四个核心支柱设计、产出物、技能、进度之间的六个维度的对齐情况。简单来说它帮你回答一个根本问题“我做的这个东西是不是我当初想做的那个东西”这个工具特别有意思的一点是它天生为AI代理Agent工作流而生。像Claude Code、Cursor、Codex这类AI编程助手它们擅长根据指令生成代码但缺乏“反思”和“全局审视”的能力。self-review就像一个内置的质检员可以命令AI代理在完成任务后自动运行一次审查确保生成的内容没有跑偏。当然它同样适用于任何有交付意图的个人或团队无论你的“设计”是写在文档里的详细规划还是仅仅存在于脑海中的一个想法。2. 核心设计理念与差异化优势解析2.1 超越静态检查的动态审计哲学市面上大多数质量保证工具无论是代码格式化工具如Prettier、静态分析工具如ESLint还是单元测试框架它们关注的都是“产出物”本身的属性格式对不对、语法有没有错误、功能是否按预期运行。这些当然重要但它们解决的是“做得对不对”的问题而不是“做的是不是你要的”这个更根本的问题。self-review的出发点完全不同。它基于一个前提任何有价值的创作都始于一个意图Intent这个意图会演化为设计Design设计再通过执行转化为具体的产出物Artifact。在这个过程中我们还会积累经验Skill并记录进度Progress。这四者——设计、产出物、技能、进度——构成了项目的四个支柱。项目的质量很大程度上取决于这四个支柱之间是否始终保持一致和对齐。因此self-review的审计是动态和关联性的。它不孤立地检查代码文件而是会去追问“这段代码的实现是否完全覆盖并正确理解了设计文档中提到的用户需求”“我们在开发过程中学到的新方法技能有没有被反向应用到对最初设计的优化中”“进度报告说功能A已完成但对应的产出物真的达到了‘完成’的定义吗”2.2 六大差异化特性深度解读仅仅有理念是不够的self-review通过一系列精巧的设计将理念转化为可执行、可感知的价值。以下是它区别于普通工具的六大核心特性1. 基于范围的智能审计这是防止审计报告变得无用的关键。很多审查工具会把所有问题都罗列出来包括那些你计划在下一阶段才做的事情。self-review会首先读取你的“进度”支柱比如progress.md文件或者从Git提交历史中推断锁定当前项目阶段的范围。然后它将所有待检查项分类为“在范围内”、“已延期”或“范围外”。只有“在范围内”的工作项才会被审计。这意味着审计报告不会用“Phase 2的功能还没做”这种无效信息来打扰你它只关心当前阶段承诺要交付的东西是否达标。2. 产出物验证而非存在性检查这是最具实操价值的特性之一。普通的工具可能只检查文件是否存在或者配置文件格式是否正确。self-review会尝试去“运行”你的产出物。对于代码项目它可能会执行构建命令如npm run build、运行测试套件如npm test并验证输出是否符合预期。对于文档项目它可能会尝试构建静态网站。它要确认的不是“有这个东西”而是“这个东西能按预期工作”。报告里说“测试通过”意味着它真的运行了测试并看到了成功结果。3. 设计内省先审视目标本身在检查对齐情况之前self-review会先对“设计”支柱本身进行审视。它会评估你的设计目标是否清晰、提供的价值是否明确、范围是否大小合适以及是否存在更简单的实现方案。这相当于在出发前先检查一下地图画得对不对。有时候项目偏离的根源在于最初的设计就不够合理或过于复杂。这个步骤能帮你提前发现这类根本性问题。4. 时效性与假设验证这是一个非常“聪明”的功能。你的设计可能基于几个月甚至几年前的技术现状或社区方案。self-review可以在配置允许的情况下使用当前年份的查询词进行网络搜索来验证你设计中所依赖的关键假设是否仍然成立。例如如果你设计了一个自定义的解决方案来处理某个数据格式但审计发现社区最近已经发布了一个成熟、高效的标准库它就会标记这一发现。这能有效防止你“重新发明轮子”或者基于过时的信息做出决策。5. 跨平台质量标准的发现与集成不同的开发环境和AI代理平台有自己的规则文件比如CLAUDE.md、.cursorrules、CONTRIBUTING.md等。self-review会主动发现项目中的这些文件并将它们的内容作为额外的质量检查关卡。同时如果项目中安装了其他领域特定的技能Skill它也会将这些技能的规则集成到审计标准中。这使得审计标准能够自适应不同的项目上下文和团队规范非常灵活。6. 隐性锚点推断与技能沉淀建议你不需要为了使用它而创建一堆模板文件。如果没有明确的design.md或progress.mdself-review会尝试从Git提交信息、Pull Request描述、代码中的TODO注释、甚至代码模式中推断出设计和进度的锚点。此外它还会评估在执行过程中学到的经验教训是否值得被捕获为可重用的技能并给出具体的沉淀建议比如“将处理XX错误的模式编写为工具函数并添加到utils/目录下”。这推动了知识的持续积累和团队能力的进化。3. 核心框架四大支柱与六个维度要理解self-review如何工作必须深入其框架。这个框架由4个支柱Pillars和6个维度Dimensions构成审计过程就是检查每两个支柱在特定维度上的对齐情况。3.1 四大支柱项目的核心构成要素设计Design项目的蓝图和意图。它可以是正式的文档如需求说明书、设计稿也可以是非正式的如会议记录、头脑风暴的便签、甚至是你脑海中的构想。它定义了“我们要做什么”以及“为什么要做”。产出物Artifact项目创造的具体成果。对于软件是源代码、可执行文件、部署的API对于文档是生成的PDF或网页对于视频是最终的成片。它代表了“我们做出了什么”。技能Skill在执行过程中获得或应用的知识、经验、模式和技术。包括新学的库、优化的算法、总结的最佳实践甚至是失败的教训。它体现了“我们是如何做的”以及“我们学到了什么”。进度Progress项目向目标推进的状态记录。可以是甘特图、燃尽图、简单的待办事项列表或是Git提交历史。它说明了“我们做到哪一步了”。3.2 六个维度支柱间的对齐关系审计不是胡乱比较而是沿着六个明确的维度检查支柱两两之间是否对齐。这六个维度源于3个理论原则借鉴自费曼评判好理论的标准和3个工程约束。理论原则维度检查“为什么”和“是什么”清晰性Clarity设计意图是否被清晰、无歧义地传达和理解产出物是否明确体现了设计完整性Completeness设计所涵盖的所有要点是否都在产出物中得到了实现进度报告是否反映了所有已完成的工作一致性Consistency在不同地方如设计文档的不同部分、代码的不同模块对同一概念的描述和处理方式是否一致工程约束维度检查“怎么做”可行性Feasibility设计在给定的技术、资源和时间约束下是否可行当前的技能水平是否足以实现该设计简单性Simplicity是否存在比当前设计或实现更简单的方案当前的实现是否引入了不必要的复杂性可维护性Maintainability产出物的结构是否清晰便于未来的修改和扩展积累的技能是否被很好地文档化以便他人或未来的自己复用审计过程会系统性地检查例如“设计与产出物在清晰性上是否对齐”、“技能与进度在完整性上是否对齐”即学到的技能是否都记录下来了等问题。每个维度都有一套具体的问题清单Check Questions来引导审查。3.3 审计深度与验证级别self-review的审计不是一刀切的。它会根据产出物的类型采用不同深度的验证级别基础级检查文件是否存在、格式是否正确。执行级运行构建、测试或脚本验证功能性输出。集成级在更复杂的环境如模拟用户交互中验证行为。例如对于一个Web后端项目它可能会执行docker-compose up启动服务然后使用curl调用几个关键API端点来验证响应。4. 安装与集成实战指南4.1 安装方式选择与平台适配self-review被设计为一个“技能”Skill可以轻松集成到支持Agent Skills协议的各类AI辅助开发平台中。安装非常简单。推荐方式一键安装如果你的开发环境已经配置了Agent Skills例如你正在使用Claude Code或Cursor的最新版本通常只需在项目根目录或技能目录下执行npx skills add motiful/self-review这条命令会从npm仓库或GitHub自动获取并安装该技能。手动安装适用于自定义或离线环境如果你想更精细地控制安装位置或者你的平台有特殊要求可以手动克隆仓库并创建软链接。# 1. 克隆仓库到本地技能目录 git clone https://github.com/motiful/self-review ~/skills/self-review # 2. 根据你使用的平台创建软链接 # 对于 Claude Code: ln -sfn ~/skills/self-review ~/.claude/skills/self-review # 对于其他支持 Agent Skills 的平台 (如 Cursor, Windsurf): ln -sfn ~/skills/self-review ~/.agents/skills/self-review注意软链接的路径可能因操作系统和平台版本的默认配置而异。如果上述路径不生效请查阅你所使用平台的官方文档确认其技能加载的具体目录。通常可以在平台的设置或~/.config目录下找到相关配置。4.2 在不同工作流中的触发方式安装成功后你可以在项目中通过多种方式触发自我审查在AI代理聊天窗口中直接输入命令如/self-review、self-review、audit。这是最常用的方式AI代理会调用这个技能来审查当前对话上下文或打开的项目。作为提交钩子Git Hook你可以将self-review脚本集成到pre-commit或pre-push钩子中在代码提交或推送前自动运行轻量级审查。这需要一些额外的脚本编写主要检查“设计与产出物”的快速对齐。在CI/CD流水线中在GitHub Actions、GitLab CI等持续集成环境中可以添加一个审计步骤。这对于团队项目尤其有用确保主分支的合并请求Pull Request在合并前都经过一致性审查。手动运行脚本虽然主要作为技能运行但其核心逻辑是独立的。理论上你可以编写一个Node.js脚本或Shell脚本来调用其审计模块实现定期的自动化报告生成。4.3 项目结构与必要文件准备为了让self-review发挥最大效用建议在项目中维护一些简单的锚点文件。这不是强制要求但能极大提升审计的准确性和深度。DESIGN.md或docs/design.md存放设计意图、用户故事、架构决策记录ADR。内容无需非常正式要点列表即可。PROGRESS.md或docs/progress.md记录当前迭代/版本的目标、完成的任务列表、待办事项。可以链接到具体的Issue或提交。SKILLS.md或docs/learned.md一个动态文档记录在项目中学到的新技术、遇到的坑及其解决方案。平台规则文件如CLAUDE.md、.cursorrules用于定义项目特定的代码风格、约束或给AI的指令。即使没有这些文件self-review也能工作它会从代码注释、提交历史中尽力推断。但有这些文件就像是给审计员提供了更精确的地图。5. 实战演练从零开始一次完整的自我审查让我们通过一个模拟的实战场景来看看self-review如何在一个前端React组件开发项目中运作。假设我们正在开发一个UserProfile组件。5.1 审计前项目状态快照设计在DESIGN.md中我们写道“UserProfile组件需展示用户头像、姓名、邮箱并有一个‘关注’按钮。邮箱地址较长时应自动省略并显示提示工具tooltip。组件需支持深色模式。”产出物我们已经编写了UserProfile.jsx和相应的样式文件。代码实现了头像、姓名、邮箱的展示以及一个按钮。技能在实现过程中我们学会了使用clsx库来条件合并CSS类名以更好地处理深色模式样式。进度PROGRESS.md中标记该组件为“进行中”待办项包括“实现邮箱省略功能”和“测试深色模式切换”。5.2 触发审计与报告解读我们在项目根目录打开AI代理如Cursor输入命令/self-review。几秒钟后一份结构化的审计报告生成。报告可能包含以下部分为简洁起见已简化## Self-Review Audit Report **项目范围锁定**基于 PROGRESS.md聚焦于 UserProfile 组件状态进行中。 ### 设计内省 - ✅ **清晰性**设计目标展示信息、支持深色模式描述清晰。 - ⚠️ **简单性**设计提到“邮箱省略”和“提示工具”但未指定具体交互是hover显示还是点击显示。建议明确。 - ✅ **价值**组件功能明确为用户提供核心信息展示。 ### 维度对齐检查 **1. 设计与产出物 - 完整性** - ❌ **缺失实现**设计要求的“邮箱地址较长时自动省略并显示提示工具”功能未在 UserProfile.jsx 中找到实现代码第15-25行仅简单显示邮箱。 - ✅ **已实现部分**头像、姓名、关注按钮已实现。 **2. 设计与产出物 - 可行性** - ✅ **技术可行**使用当前技术栈React, Tailwind CSS实现设计目标完全可行。 **3. 技能与进度 - 一致性** - ⚠️ **技能未记录**在实现中使用了 clsx 库处理样式此技能点未被记录到 SKILLS.md 或任何团队知识库中。建议添加。 **4. 产出物与进度 - 清晰性** - ⚠️ **进度更新延迟**PROGRESS.md 中“实现邮箱省略功能”仍为待办但代码中已存在部分相关注释// TODO: truncate long email。进度文件未反映最新的代码状态。 ### 发现与建议 1. **高优先级**立即实现邮箱省略与提示工具功能以匹配设计。 2. **中优先级**更新 PROGRESS.md将“实现邮箱省略功能”细化为“实现邮箱截断与Tooltip交互”并反映当前注释状态。 3. **低优先级**在 SKILLS.md 中新增条目记录 clsx 库在条件样式中的应用模式。 4. **设计建议**更新 DESIGN.md明确提示工具的触发方式例如hover触发。 ### 范围外项目已忽略 - “测试深色模式切换”被识别为下一阶段任务本次审计未包含。5.3 报告后的行动这份报告就像一位冷静的搭档帮你指出了盲点。根据报告你可以立刻去实现缺失的邮箱省略功能。顺手更新进度文档保持信息同步。花两分钟把clsx的使用心得记下来方便以后复用。顺便完善一下设计文档的细节。一次高效的自我审查就此完成它阻止了“一个功能不完整的组件被误认为已完成”的情况发生。6. 高级技巧与定制化配置6.1 调整审计严格度与范围self-review可以通过配置文件或命令行参数进行定制。你可以在项目根目录创建一个.self-reviewrc.json文件来定义规则。{ verificationDepth: { code: execution, // 对代码执行构建和测试 documentation: basic // 对文档只做基础检查 }, ignorePaths: [**/node_modules/**, **/*.test.js], // 忽略某些目录/文件 assumptionCheck: { enabled: true, maxQueries: 5 // 限制网络搜索查询次数 }, principles: { enforceSimplicity: high // 将“简单性”原则的检查权重设为高 } }通过调整verificationDepth你可以控制对不同类型产出物的检查强度。对于大型项目合理设置ignorePaths可以显著提升审计速度。6.2 与现有开发流程无缝集成与代码审查Code Review结合在发起Pull Request前先运行一次self-review。将生成的审计报告附在PR描述中这能为审查者提供远超代码差异diff的上下文让他们更关注“是否实现了设计意图”而不仅仅是代码风格。与任务管理工具联动你可以编写一个简单的脚本在完成一个Jira Issue或GitHub Issue后自动运行self-review并将输出结果作为评论更新到该任务下作为完成的补充证据。创建审计基线在项目初期或每个主要版本开始时运行一次self-review并保存报告。后续的审计可以与此基线进行比较帮助你量化“设计漂移”的程度。6.3 处理误报与噪音任何自动化审计工具都可能产生误报。self-review通常通过上下文推断来减少误报但仍可能发生。例如它可能误将某些临时性的实验代码识别为偏离设计的正式产出。应对策略精炼锚点文件确保你的DESIGN.md和PROGRESS.md足够清晰、更新及时。模糊的设计描述是误报的主要来源。使用注释忽略在代码中可以使用特定的注释标记来告诉审计工具忽略某段代码。例如在代码块前添加// self-review-ignore: 实验性功能下一阶段评估。审查即对话不要将审计报告视为最终判决而应视为一个发起对话的起点。报告中的每个发现都是一个提问“这里是否真的有问题我们是否接受这种偏差”7. 常见问题与排查实录在实际使用中你可能会遇到一些典型问题。以下是我在多次实践中总结的经验和解决方案。7.1 审计命令无响应或报错问题现象在AI代理中输入/self-review后没有任何反应或返回“技能未找到”的错误。排查步骤确认安装路径首先检查技能是否安装在了正确的目录。运行ls -la ~/.claude/skills/或ls -la ~/.agents/skills/查看self-review目录是否存在且是一个有效的软链接。检查平台兼容性确认你使用的AI代理平台如Cursor、Claude Code版本是否支持Agent Skills功能。较旧的版本可能不支持。查看技能清单有些平台提供了列出已安装技能的命令如/skills list。尝试运行看self-review是否在列表中。手动运行调试进入技能目录 (cd ~/skills/self-review)尝试查看其SKILL.md文件或运行node -e console.log(require(./package.json).name)来确认核心文件完好。解决方案最常见的原因是软链接路径错误。重新按照官方文档的指引创建软链接或直接使用npx skills add命令让工具自动处理。7.2 审计报告过于空泛或遗漏关键问题问题现象报告生成了但内容很浅只检查了文件是否存在没有深入验证功能或者明明有设计偏差却没被发现。可能原因与解决锚点信息不足项目中没有DESIGN.md、PROGRESS.md等文件且Git历史、代码注释也缺乏有效信息。解决至少创建一个简单的DESIGN.md哪怕只是几句话列出核心需求。这能极大提升审计质量。验证深度不足默认的验证级别可能被设置为basic。解决检查或创建.self-reviewrc.json配置文件将关键产出物类型如code的verificationDepth设置为execution。产出物类型不被支持如果你在做一个非常规项目如硬件设计、音乐创作self-review可能没有内置对应的深度验证逻辑。解决目前可能需要等待技能更新支持更多类型或者你可以通过编写自定义的验证脚本并在设计文档中说明如何调用来间接实现深度检查。7.3 网络搜索假设验证功能不工作问题现象报告中没有出现关于“时效性”或“社区方案”的检查结果。排查与解决功能未启用默认情况下出于隐私和速度考虑网络搜索功能可能是关闭的。解决在配置文件.self-reviewrc.json中明确设置assumptionCheck: { enabled: true }。网络或API限制技能可能需要访问特定的搜索API而你的环境存在网络限制或未配置API密钥。解决查看技能的详细文档确认是否需要配置如Serper、Google Custom Search等API的密钥。通常相关配置说明会在项目的README或SKILL.md中。设计文档中缺乏可验证的假设网络搜索依赖于从设计文档中提取出具体的、可查询的技术假设。例如“我们认为X库是处理Y问题的最佳选择”。如果设计写得很笼统该功能就无法生效。解决在撰写设计时有意识地将关键的技术选型决策和其依据写清楚。7.4 审计速度慢影响工作流问题现象每次运行审计都需要等待较长时间无法融入快速迭代的流程。优化建议配置忽略规则在.self-reviewrc.json中充分利用ignorePaths排除node_modules、dist、build等第三方依赖和生成目录。分阶段审计不要每次都进行全量深度审计。可以配置两个预设快速审计仅检查“设计与产出物”的“完整性”和“一致性”验证深度设为basic。用于日常提交前检查。深度审计检查所有维度和支柱验证深度设为execution。用于里程碑节点或PR合并前。缓存机制检查self-review是否支持缓存上次的审计结果。对于未更改的部分可以直接使用缓存只分析变更部分。这通常需要技能本身的支持。7.5 与团队现有规范冲突问题现象self-review提出的建议如代码结构、文档格式与团队长期形成的、未成文的习惯不一致。处理原则工具服务于人而非相反。讨论与适配将审计报告作为团队讨论的引子。如果工具的建议有道理可以考虑采纳并逐步更新团队规范。如果团队有充分的理由坚持现有做法可以修改技能规则或团队的质量标准文件如.cursorrules让工具适应团队而不是团队适应工具。定制检查规则高级用户可以深入研究self-review的规则定义文件通常在references/dimensions.md或类似位置了解如何扩展或修改其检查逻辑使其更贴合团队的具体上下文。使用self-review的终极目的不是追求一份完美的、零发现的审计报告而是通过这个结构化的过程培养一种“意图与交付对齐”的思维习惯。刚开始可能会觉得它有点麻烦但坚持几次后你会发现自己在动手写代码或创作内容之前会不自觉地先问自己那几个核心问题这才是这个工具带来的最大价值。