别让 AI 写完代码才开始补救：把需求、验证与审查拆进 ai-factory 的阶段流水线
AI 编程助手把“写出第一版”变得很快，却没有自动解决工程交付里更难的部分：需求有没有被澄清、架构选择能否回溯、测试是否覆盖真正的约束，以及合并前是否有人专门反驳这份实现。把这些问题留到 Agent 已经改动大量文件之后，通常只会得到一轮昂贵的返工。
ai-factory 是 Highflame 发布的 MIT 许可工具包，定位为面向 AI 辅助软件工程的、由配置驱动的开发实践。它将技能、子代理、确定性 hook 和角色能力模型组合为一条阶段化流程。它不是模型，也不会替团队判断产品优先级；它的价值在于把“让 Agent 写代码”前后那些容易被跳过的检查点，变成可重复执行的工程工序。
本文以一个新功能为例，说明如何把它用于已有代码库，并重点讨论哪些门应该自动化、哪些门仍应由人保留。
问题不在生成速度，而在阶段被压扁
一次典型的 Agent 驱动开发经常是这样的：输入一句需求，模型搜索仓库、直接修改、跑一组测试，然后请求合并。这个路径把需求分析、架构设计、实现、复盘和审查压成一次长对话。上下文一旦被压缩、换人或换模型，之前的取舍就只剩下代码注释，甚至什么也不剩。
ai-factory 把主流程明确为：spec → architect → validate → implement → reflect → review → ship。其中 validate 并不是末尾“跑绿测试”的同义词，而是每一个产物进入下一阶段前的检查；reflect 则在正式审查之前要求实现者先审视自身输出。这样做的直接好处是，每个阶段都有相对明确的输入、输出和失败位置。
它还把团队约束放在项目内的 .aif/ 目录：需求与架构文档、任务、已验证的假设和经验记录可以与代码库一起演进。相比把所有约束都塞进一次性 prompt，这更适合长期维护的仓库；不过其中可能出现内部架构和业务背景，因此应根据团队策略决定是否提交、如何做访问控制。
先安装，再把流程接到真实仓库
官方 README 提供的最小安装方式如下。脚本会建立技能、代理、hook 和 aif 命令的链接，并在结束时运行环境检查；执行任何远程或第三方安装脚本前，仍应先审阅仓库与脚本内容。
git clone https://github.com/highflame-ai/ai-factory.git cd ai-factory && ./install.sh
安装后，针对某个代码库在 Agent 会话中使用 /init 建立 .aif/ 结构。不要把初始化误解为“立刻替换现有工程规范”：项目配置 .aif/config.yml 可以按需加入，README 也说明它用于驱动项目或组织特定的内容，例如技术栈、相邻仓库和环境约束。先从一个风险适中的仓库或单一服务试点，确认生成的目录、hook 和权限边界符合预期，再推广到更多项目。
工具还提供 aif doctor。这一步很实用，因为 Agent 工具链往往依赖符号链接、全局配置和本地可执行文件；如果技能已复制但 hook 没有真正接入，流程表面上存在，实际却不会生效。将 doctor 的结果纳入首次安装与升级后的检查，比在一次失败的发布后再排查要便宜得多。
用一个功能请求走完整条链路
假设团队要为已有服务增加“导出报表前必须经过权限检查”的能力。与其直接要求 Agent 修改 handler，可以先把不变量写进规格：谁可以导出、数据范围如何确定、失败返回什么、审计记录是否必须存在。接着执行 /spec 形成需求产物，再用 /validate 检查它是否遗漏可测试的约束。
通过后，/architect 将规格拆为组件边界和任务，例如权限策略、查询层过滤、审计事件和回归测试。架构输出再次经过 /validate 后，才进入实现。官方列出的端到端命令是 /proceed，其流程覆盖验证、架构、实现、复盘、审查、PR 与收尾；但自动化不意味着无条件放行。对于权限模型、迁移、删除数据和生产配置变更，团队应在对应阶段插入人工确认，而不是把“流程已跑完”当成批准。
/spec → /validate → /architect → /validate → implement → /reflect → /review → merge → /wrapup
这个序列真正约束的是顺序：先让需求和设计接受反驳，再扩大改动面。若验证阶段发现“导出范围”没有定义，应回到规格；若审查发现查询绕过了权限层，应回到架构或实现，而不是只给当前 diff 打一个补丁。阶段有回退路径，才不会把每个缺陷都伪装成最后一分钟的代码问题。
让不同代理有不同权限，而不是不同人设
多代理协作的风险不只是重复劳动，还包括“一个审查代理意外拥有写权限”。ai-factory 的角色文件把能力定义为单一来源，例如一个 reviewer 可以被约束在读取、搜索和执行检查，而不拥有写入权限；aif compile --check 用于检查生成的运行时配置是否偏离角色边界。
这适合处理一个常见矛盾：为了让审查有用，代理需要读取代码、运行测试和查看配置；为了让审查可信，又不应允许它顺手修改被审查的内容。将“检查”和“实施”拆开，不会消除模型误判，却能减少审查过程本身改变证据的机会。
README 中还列出了多种审查角色，覆盖正确性、质量、架构、测试和安全等方向。它们不等于安全保证，也不能替代组织的合规审查；更现实的用法是把它们当作并行提出反例的机制。对外部输入、授权、账单和数据删除等高风险路径，仍应要求人类维护者阅读结论、复现关键证据并决定是否合并。
hook 是护栏，不是隐藏的 CI
工具包提供格式化、秘密扫描、提交信息检查、暂存文件静态分析和会话反思等 hook。尤其是写操作前的秘密扫描和提交前门禁，能避免 Agent 在高速迭代时绕过最基本的约束。不过 hook 的前提是项目配置真的加载了它们，而且规则与团队的 CI 一致。
一个可操作的做法是分三层设置门槛：第一层用本地 hook 快速反馈格式、明显的凭据暴露和提交规范；第二层由 CI 执行可复现的测试、静态分析和依赖检查；第三层把权限提升、数据迁移、部署和合并保留为人工决策。不要把所有检查都放进 Agent 的单次上下文，也不要把所有检查都放到昂贵而缓慢的 CI 队列。
ai-factory 的 README 将其内部使用中的交付效率改善描述为 3–5 倍，并明确标注这是团队自身经验、结果会因环境而异。因此，试点时不应把该数字写成预期 KPI。更可靠的衡量方法是比较引入前后的返工次数、评审发现缺陷的阶段、PR 等待时间和失败发布数；工具自身也提供 /measure 用于从 git、PR 和 .aif/ 产物汇总交付与质量指标，并带有使用边界说明。
适用边界：流程先服务于项目，而不是反过来
ai-factory 更适合需要持续演进、多人协作、且 AI 改动已经开始影响合并质量的代码库。对于一次性脚本、短期原型或只有很小改动的修复，完整的规格—架构—多代理审查链路可能比问题本身更重；此时可以只保留关键测试和人工 review，而不是为了使用工具而制造文档。
反过来，流程复杂也不能掩盖责任归属。规格是否正确、架构是否接受风险、生产变更是否执行，最终仍应由能够理解业务和后果的人负责。把阶段、角色和检查编排清楚的意义，是让 Agent 的速度不再以丢失依据、跳过验证或扩大权限为代价。
相关链接