feature-factory

Feature Factory

一个以目标为导向、本地优先的循环，用于将一个功能从意图推进到上线。整个方法围绕一条原则展开：不要让流程跑到功能前面。 保留核心流程（目标 → TDD → 确定性验证 → 人工合并 → 在必要时提供证据）；坚决删去繁文缛节。

这是行为指南，不是引擎。 不要构建通用配置、执行器、遥测、优化器或通用的 factory verify 封装。按此执行即可；不要打包任何功能本身不需要的东西。

核心原则

由人定义期望的系统状态。Agent 维护规格。测试和证据判定实际情况是否符合要求。 始终需要两个人工关卡——批准目标契约（容易更改的时机）和审查合并（不可逆的时机）——另外还有一个有条件触发的第三关（计划审批），在达到规模／风险触发条件时启用（见步骤 2）。中间所有环节组成一个专注的 Agent 循环。

何时采用，何时跳过

• 适用于范围明确、可以交付的功能。
• 简单变更跳过繁重流程——S 级修复只需：在脑中简要明确目标 → TDD → 运行仓库的检查 → 合并。不要为一行改动生成文档。
• 拒绝 XL 级——如果功能需要数天开发，涉及共享契约、迁移、身份验证／账单，或产品需求有歧义，先拆分；不要将整个 XL 级功能放进这个循环。

循环（六个步骤）

1. 收集需求——创建或修复目标契约

现在快速判断规模（步骤 2 会正式确定）——你需要据此决定需求收集要多繁重。对于 S 级／简单变更，跳过文件——在聊天中简要说明目标并由人确认即可；直接进入步骤 3。其他情况，将 assets/goal-contract.md 复制到目标仓库中，作为功能目录下的 goal.md（建议路径：docs/factory/<date>-<slug>/goal.md）；已填写的校准示例见 assets/goal-contract-example.md。模板的核心字段足以应对 M 级功能——条件部分用于 L 级功能或触发条件生效时。先根据请求起草，再让人逐项确认或修正字段——不要因空白表单而停滞，也不要在人工批准措辞前结束需求收集。要求：

• 所有 `` 字段均须填写：最小可交付切片和停止条件。
• 遵守上限（≤3、≤5）。设定上限的目标应保持为目标，而不是变成 Markdown 中的瀑布式流程。
• 每项预期结果都必须对应具体证据。 拒绝含糊不清或与解决方案绑定的预期结果。
• **失败规则：**如果目标无法产生证据，它就只是包装得更好的愿望——不能通过。
• Agent 可以提出目标修订；绝不能悄悄改写目标。

2. 规模与风险分流——决定流程的繁简程度

• **规模：**S（<½ 天，无公共 API／迁移）· M（1–2 天，有一些 UI／集成）· L（数天；共享契约、迁移、身份验证／账单／权限、AI 行为、数据保留）· XL（先拆分）。
• **风险：**R0 无 · R1 内部开发辅助 · R2 面向用户、低风险 · R3 敏感数据／建议／用户画像 · R4 禁止／高风险（《欧盟 AI 法案》第 5 条，或你所在司法辖区的同等规定），或需要法律审查 → 停止，在外部审查前不要实施。对于 AI 生成／聊天机器人／深度伪造输出，还需检查第 50 条的标注要求（或当地同等规定）。
• 默认采用更少的流程。 仅在规模／风险触发条件生效时（见 references/process-budget.md），才增加计划审批、跟踪器、视觉证据或审计（计划和／或差异——见步骤 4）。不确定时，少做一些。
• 计划审计（触发计划审批时）： 开始构建前，由具备独立新上下文的审查者（单独的 Agent／模型，例如 Codex）对照实际代码库检查目标和计划，查找顺序、架构和正确性方面的问题。这是发现阻碍因素成本最低的时机——修正计划，不要等到构建过程中才发现。超时和自我审查的后备方案与步骤 4 相同。

3. TDD 实现循环

在功能分支或工作树上开展工作——只有当工作尚未进入主线时，合并关卡才是真正的决策点。然后按红 → 绿 → 重构的顺序，在一个专注的循环中完成工作。不搞蜂群、不并行发散、不做推测性抽象、不悄悄扩大范围。先编写失败的测试。使用任何可用的 TDD 技能（例如 superpowers:test-driven-development）；否则直接遵循红 → 绿 → 重构。

• 仓库里没有测试框架？ 以最精简的方式引入该技术栈的标准运行器（一份配置、一个测试目录——参见 references/stack-discovery.md）；测试框架是功能成本的一部分，如果引入它要花一天时间，就重新评估任务规模。
• Spike 逃生口： 如果你还不了解足够的信息，无法编写失败的测试（例如不熟悉某个库，或 API 行为不明确），就为一次临时 spike 设定时间上限，丢弃 spike 代码，然后根据学到的信息开始红 → 绿。不要伪造测试，也不要让 spike 悄悄变成正式实现。
• 确定性： 不要使用基于挂钟时间或 sleep 的测试断言——使用同步屏障或回调。
• 变更契约 ⇒ 验证所有调用点： 变更共享函数的契约时，必须列举每个调用方及并行路径，并证明它们都遵循该契约。

4. 验证与审计规范

运行目标仓库实际的验证命令（测试 · lint · 类型检查 · 构建，以及可用时的密钥扫描）——本地和 CI 使用相同命令。如果仓库有 factory verify / 项目验证命令，就调用它；否则，使用仓库实际的命令，并将命令（准确命令及输出）记录在功能目录下的 evidence/verify.log 中。不要在仓库还不需要通用封装器时就凭空创建一个。 不确定仓库实际使用哪些命令？按照 references/stack-discovery.md 的顺序查找：CI 工作流、Makefile/justfile、贡献者文档，然后是生态系统清单。

• 不稳定测试 = 失败，不要重试。 任何间歇性失败都必须先查明根因或改写为确定性测试，才能合并。不得隔离。
• 审计（由独立人员在全新上下文中审查）是标准步骤，不是事后补做。 由处于全新上下文的另一个 Agent 或模型（例如 Codex 或其他模型）在两个关键节点审查工作：（a）构建前审计计划（参见步骤 2）；（b）合并关卡前审计差异。审计要求如何随规模/风险调整——何时必须进行、何时可以跳过、超时后如何由自审兜底——在 references/process-budget.md 中统一定义；按照其中的表格执行，不要自行重新推导。将审查结果保存在 evidence/audit-*.md 中；继续之前，将结果纳入计划/差异（不落实的审计只是作秀）。人工关卡仍由人决定——审计为其提供参考，但不能取代目标/合并审批。

5. 证据整理

仅在功能目录的 evidence/ 下保存相关证据：verify.log（命令及输出）；且仅针对符合条件的 UI 变更，保存截图至 evidence/screenshots/（符合条件的情况及默认单视口规则，见 references/process-budget.md 中的“视觉证据”）。只有在能提供有用信息时才添加目标可追溯性表。证据是产物，不是声明：“已完成”必须可审计。不要让证据文件夹喧宾夺主。

• 逃生口——统计/行为类声明： 如果期望结果是在嘈杂的真实世界数据上测得的效果（参与度、延迟分布、拒绝率、ML 指标），而不是通过/失败测试，那么测试套件全绿并不能证明它。应在目标契约中预先登记指标，并将其作为真实实验评估（进行置换检验，对分析开展对抗性审查）——如果有可用的 rigorous-experiments 技能就使用它，否则进行留出集检查。不要声称实现了你实际上未测试过的测量结果——这和失败规则所捕捉的代理指标作弊问题本质相同，只是发生在更下一层。

6. 事后删除钩子（策展人）

发布后，在功能目录下的 retro.md 中恰好写四行（只有在单独文件不切实际时才追加到 goal.md 中——一个便于检索的默认约定胜过两种约定）：

1. 什么拖慢了发布？
2. 什么发现了一个真实的 bug？
3. 哪个产物从未使用？
4. 下个功能开始前要删除什么？

这就是小规模 N 下的全部自我改进机制——手动、可读性强、不可能过度构建。不要添加使用情况遥测、仪表盘或计数器。（只有在大约 5 个功能之后才汇总为 Markdown 表格；只有在大约 10 个功能之后才考虑更重的机制。）

语义保留防护（编辑此方法自身的产物时）

此防护适用于编辑方法本身时——目标契约模板、风险评估标准或验证检查——**不适用于普通功能工作。**当任何编辑、优化器或改写涉及这些产物时，**不得让润色后的文字删掉承载关键约束的内容。**接受改写前，请确认其保留了：必填字段、≤N 上限、失败规则、停止条件、最小可发布切片、风险分类、证据映射、禁止静默改写，以及禁止引擎／配置抽象。发生冲突时，**优先保留实际操作效用，而非可读性。**详情见：references/semantic-preservation.md。

问题跟踪——每个功能一个台账（不做抽象）

跟踪是有条件的：只有当功能确实可拆分为多个（>1 个）待跟踪任务时，才创建 epic 和问题。单任务的 S/M 功能无需跟踪器。由人工在目标契约的 ## Tracker 部分为每个功能选择一个台账——选择环境中实际可用的工具（如 bd、Linear、GitHub Issues），或选择 none——不设置适配层。

• bd（beads）——适合本地／个人使用，是 Git 原生且能处理依赖关系的好默认选择：如果没有 .beads 存储，运行 bd init；epic = 父 bead，任务 = 子 bead，通过 bd link 设置依赖关系。
• 托管式跟踪器（Linear、GitHub Issues 等）——当工作必须对他人可见或已经在其中进行时使用：使用此环境提供的任何访问方式（CLI 或 MCP）；epic = 项目／父问题，任务 = 问题。如果人工明确选择的跟踪器在此环境中不可用，请停止并询问——切换跟踪器或改为 none 属于目标修订，不得静默降级。
• 同一项工作绝不能打开两个台账（例如，同时使用 Linear 项目和 beads epic）。

保持手动／不在范围内的内容（不要构建）

GEPA／模板优化 · 产物使用情况遥测 · 通用 pipeline.config · 执行器抽象 · 自动跟踪器连接 · 视觉证据矩阵 · 评测自动化 · 超出自我评估提示范围的风险治理 · 自动更新 Agent 指令文件（AGENTS.md / CLAUDE.md）· **任何有“引擎”意味的东西。**只有在实际完成 5–10 个功能之后，方法才值得配备引擎，不要提前构建。

可移植性——可从任意 Agent（Codex、Copilot、Gemini，……）运行

此技能采用纯 Markdown 编写，不依赖特定平台：整个循环是 shell/CLI 操作，而非 Claude 专用工具。这里提到的任何工具（bd、Linear、TDD 子技能、第二意见模型）都是可选的——如果当前环境中没有，就使用所述回退方案并继续；除非明确要求跟踪，否则缺少可选工具不会阻碍工作。

不会自动发现技能的 Agent（例如 Codex CLI）不会仅仅因为文件存在就找到此技能。若要让目标仓库能够发现它，请在该仓库的 Agent 指令文件（AGENTS.md 或 CLAUDE.md）中添加一条：

## feature-factory
When asked to build/ship a single feature, or to "write a goal contract", read
<path-to>/feature-factory/SKILL.md and follow it. For non-trivial features, copy
<path-to>/feature-factory/assets/goal-contract.md to docs/factory/<date>-<slug>/goal.md.

如果不使用技能运行器，请直接阅读 references/process-budget.md（规模／风险触发条件）、references/stack-discovery.md（查找仓库的验证命令；为缺失的测试框架搭建初始环境），以及 references/semantic-preservation.md（仅在编辑该方法自身的产物时阅读）。

将此技能复制到其他仓库时，只复制其内容文件（SKILL.md、assets/、references/）——本地工具状态（例如 .enzyme/、.claude/）可能与这些文件并存，不得随之发布。

背景

此技能提炼自 feature-factory 方法——公开仓库：**https://github.com/glebis/feature-factory**（README 和目标契约模板）。更完整的设计规范以及三条外部审计研究线索均为私有内容；此技能是可运行的精简版本。最需要诚实看待的高风险假设是：在一个范围明确、逻辑密集的试点中奏效的流程，尚未证明在杂乱的 UI／集成工作中也能保持轻量——请在下一个刻意选择不同类型的功能上对其进行压力测试。