# CraftKit 全流程自动化使用指南

## 1. 文档用途

本文档是一份可直接交给 Codex 或其他已安装 CraftKit 的智能体执行的流程契约。它用于把原始需求、零散对话、会议纪要、问题描述和项目源码，逐步转化为：

1. 可确认的需求分析文档；
2. 基于项目事实的技术设计文档；
3. 符合仓库约定的开发分支；
4. 经过验证的代码与测试；
5. 可复核的代码审核结论；
6. 范围准确的本地 Git 提交。

流程采用“自动执行到审批门”的方式推进。智能体负责取证、分析、编写、验证、修正和阶段衔接；人只负责批准阶段基线、选择无法从证据确定的业务决策，以及确认具有 Git 或外部环境副作用的操作。

本文档不授予推送、合并、发布、生产数据库变更、生产环境操作或明文凭据访问权限。若需要这些操作，必须由用户另行明确授权。

## 2. 适用前提

执行环境应满足以下条件：

- 已安装 CraftKit 中任务所需的 `doc`、`dev`、`git`、`knowledge` 和 `skill` 插件；
- 智能体能够读取目标项目的需求材料、源码、Git 状态和项目内说明文件；
- 目标项目是 Git 仓库，且用户已经给出或允许智能体识别项目根目录；
- 项目使用的构建、测试或格式化工具在本地可用，或允许智能体如实记录环境阻塞；
- 用户允许智能体在已批准范围内修改项目文件并运行非破坏性验证命令。

如果项目尚未建立 `AGENTS.md` 或 `.craftkit/project.json`，智能体可以建议使用 `init` 初始化项目上下文，但必须遵循该 Skill 的确认要求，不能隐式覆盖现有配置。

## 3. 核心执行原则

### 3.1 证据优先

每项结论必须标记为以下类型之一：

- **输入事实**：来自用户原始材料或已确认对话；
- **源码事实**：来自当前分支的代码、配置、测试、数据库脚本或接口契约；
- **项目规则**：来自适用的 `AGENTS.md`、`.craftkit/` 或仓库明确约定；
- **设计建议**：尚未实施、但有依据的技术方案；
- **待确认项**：无法从现有证据可靠确定的业务或技术决策；
- **待验证项**：静态证据不足以证明的运行时行为。

不能从当前代码行为反推业务意图，也不能把相似模块的实现直接当作本需求规则。代码只能说明当前系统如何实现，不能替代用户对目标行为的确认。

### 3.2 最小充分读取

先读取项目入口、适用规则、构建文件和最相关调用链，再按证据需要扩大范围。禁止无目的加载整个仓库、整个知识库或与任务无关的业务数据。

### 3.3 自动推进

每个阶段完成且满足质量门后，智能体必须自动进入下一个阶段，不要求用户重复发送“继续”。只有到达审批门、发生阻塞或需要新增权限时才暂停。

用户批准某一审批门后，该批准同时表示允许智能体继续执行到下一审批门，但不扩大文件范围、外部系统范围或破坏性操作权限。

### 3.4 保留工作区

任何阶段都必须保护用户已有改动：

- 开始时记录 staged、unstaged 和 untracked 状态；
- 不覆盖、还原、清理或暂存无关改动；
- 不自动使用 `git reset --hard`、强制切换、强制删除或历史改写；
- 无法区分本次改动与既有改动时暂停并请求用户确认；
- `.craftkit/local/**` 和 `.craftkit/cache/**` 不纳入提交范围。

### 3.5 验证分层

验证结果必须区分：

- 静态检查；
- 编译或构建；
- 单元测试；
- 集成测试；
- 浏览器或真实环境验证；
- 未执行或受环境阻塞的验证。

一种验证通过不能替代另一种，也不能把“计划已生成”写成“功能已验收”。

## 4. 流程状态机

| 阶段 | 主要 Skill | 核心产物 | 完成后动作 |
| --- | --- | --- | --- |
| S0 项目接入 | `init`、`guidance` | 项目上下文、适用规则、初始 Git 快照 | 自动进入 S1 |
| S1 原始需求归集 | `requirements` | 需求分析文档草案、疑问清单、验收标准 | 进入审批门 G1 |
| S2 变更规划 | `plan-change` | 影响范围、依赖顺序、验证计划 | 自动进入 S3 |
| S3 技术设计 | `design-db`、`design-api`、`design-backend`、`design-frontend`、`design-frontend-data`、`design-workflow`、`prepare-api` | 按需生成的设计文档集合 | 进入审批门 G2 |
| S4 分支准备 | `branch` | 分支名、基准、创建命令及风险预览 | 进入审批门 G3 |
| S5 代码实现 | `implement-backend`、`implement-frontend` | 业务代码、配置内的非敏感必要变更、测试代码 | 自动进入 S6 |
| S6 验证与自修复 | `test-backend`、`test-ui` | 分层验证记录、失败分类、修复结果 | 自动进入 S7 |
| S7 代码审核 | `review-code`，按需叠加 `review-java`、`review-mybatis`、`review-frontend` | 审核报告、问题清单、未验证边界 | 自动修复明确问题后复审，进入 G4 |
| S8 提交准备 | `commit-msg` | 精确文件范围、提交拆分与提交信息 | 进入审批门 G5 |
| S9 本地提交与收尾 | Git 原生命令、`branch close` | 一个或多个本地提交、提交后状态、Worktree 清理结果 | 释放额外 Worktree 后输出最终交付报告 |

阶段不得仅凭名称跳过。确实不适用时，应记录“不适用”的证据和原因，再继续推进。

## 5. 审批门

### G1 需求基线审批

智能体必须展示：

- 目标、范围内和范围外事项；
- 用户角色、主流程、异常流程和业务规则；
- 可测试的验收标准；
- 输入冲突、模糊表述、缺失规则和建议默认值；
- 拟落盘路径及将创建或修改的需求文档。

用户批准后，需求文档成为后续设计和验收的基线。后续发现需求级冲突时，必须回到 G1 做增量审批。

### G2 技术设计审批

智能体必须展示：

- 当前实现与目标实现的差距；
- 前端、后端、数据库、API、工作流等适用设计；
- 关键技术决策、备选方案及选择依据；
- 数据迁移、兼容、回滚、安全和性能风险；
- 实施步骤、文件影响范围和验证矩阵；
- 仍需业务或外部系统确认的事项。

用户批准后，智能体不得自行扩大设计范围。实现过程中若必须改变已批准的核心契约，应暂停并返回 G2。

### G3 分支创建审批

按照 `branch` Skill 的要求，智能体必须在执行前展示：

- 当前分支和工作区状态；
- 目标分支名；
- 基准引用及提交短哈希；
- 在当前工作区还是独立 Worktree 创建，以及是否影响未提交修改；
- 使用独立 Worktree 时的准确绝对路径；
- 唯一的分支创建命令。

只有用户明确批准这组最终信息后才能创建本地分支。`fetch`、创建分支、移除 Worktree 和推送分支是彼此独立的授权；本流程默认不执行 fetch 和 push。

### G4 代码效果审批

智能体必须展示：

- 已实现的需求条目及对应文件；
- 需求验收标准与验证证据的映射；
- 构建、测试、静态检查和浏览器验证结果；
- 已自动修复的审核问题；
- 尚未修复的问题、环境阻塞、待验证行为和残余风险；
- 实际 Git 差异摘要。

只有用户确认代码效果可接受后，才能进入提交准备。用户要求调整时，流程返回 S5，并重新执行 S6、S7 和 G4。

### G5 提交审批

智能体必须展示：

- 每个拟提交逻辑分组及其精确文件清单；
- staged、unstaged、untracked 和排除项；
- Conventional Commit 提交信息；
- 敏感文件、本地配置、缓存、二进制文件和无关改动检查结果；
- 将执行的 `git add -- <明确路径>` 和 `git commit` 命令。

用户批准后，只允许暂存展示过的精确路径并创建本地提交。不得使用 `git add .`、`git add -A` 或包含未确认文件的通配符。提交完成后不得自动 push、合并、打标签或发布。

## 6. 各阶段执行要求

### S0：项目接入与基线检查

1. 确定项目根目录和需求材料范围。
2. 读取所有适用的 `AGENTS.md`。
3. 检查 `.craftkit/project.json`、规范索引、构建文件、依赖锁文件和主要源码目录。
4. 使用 `guidance` 获取本任务适用的项目规则，并区分明确规则、公共建议和代码现状。
5. 执行只读 Git 检查，记录当前分支、HEAD、工作树状态、远程引用现状和 worktree 占用情况。
6. 若项目上下文缺失，只在确有必要时提出 `init`；初始化写入仍遵守该 Skill 的确认步骤。
7. 建立任务台账，至少记录任务编号、当前状态、输入、产物、审批记录、风险和下一动作。

推荐将本次任务的本地运行状态保存到 `.craftkit/local/`；除非用户明确要求共享，不把运行状态写入可提交目录。

### S1：需求归集与落表

使用 `requirements` 处理原始需求。输入可以是完整需求文档，也可以是聊天记录、口头描述转写、邮件、会议纪要、Bug 描述、截图文字或零散技术说明。

需求文档至少包含：

1. 背景与目标；
2. 输入来源和证据索引；
3. 术语与角色；
4. 当前行为；
5. 目标行为；
6. 功能范围；
7. 主流程与异常流程；
8. 业务规则和状态规则；
9. 数据、权限、兼容和审计要求；
10. 非功能要求；
11. 范围外事项；
12. 可测试验收标准；
13. 冲突、假设、待确认项和待验证项；
14. 需求追踪编号。

需求追踪编号建议使用 `REQ-001`、`REQ-002`。后续设计、代码、测试和审核都引用这些编号，形成端到端追踪。

对于模糊输入，智能体应优先用源码确认“当前行为”，用用户材料提取“目标方向”，但不能替用户决定金额、时点、角色权限、状态跳转、合规要求、数据口径或其他会改变业务结果的规则。

### S2：变更计划

使用 `plan-change` 将批准的需求基线映射到项目实际代码。计划至少说明：

- 需求类型：新功能、增量修改、缺陷修复或重构；
- 真实入口、调用链、数据流和相邻稳定实现；
- 可能修改的模块和文件；
- 前后置依赖及执行顺序；
- 每一步的输入、产物、验证和停止条件；
- 数据库、接口、前端、后端、工作流、部署和外部系统影响；
- 对已有行为、版本兼容和脏工作区的保护方式。

变更计划是设计编排依据，不替代详细设计，也不执行代码修改。

### S3：技术设计

只调用实际适用的设计 Skill：

| 场景 | 使用 Skill | 重点输出 |
| --- | --- | --- |
| 后端模块、事务、异常、权限 | `design-backend` | 模块职责、调用关系、事务与错误语义 |
| 表结构、约束、索引、迁移 | `design-db` | 数据模型、DDL 方案、迁移与回滚 |
| HTTP 契约 | `design-api` | 路径、方法、请求响应、错误与兼容 |
| 页面、路由、交互、状态 | `design-frontend` | 页面级契约和交互流程 |
| 请求状态、缓存、竞态 | `design-frontend-data` | 状态所有权、转换和并发策略 |
| 审批、任务、状态流转 | `design-workflow` | 状态转换、权限、幂等和补偿 |
| 前后端字段对接 | `prepare-api` | 接口清单、字段映射和联调风险 |
| 组件、表单、样式 | `component`、`form`、`style` | 基于项目证据的专项设计 |

设计产物应使用 `REQ-*` 关联需求，并为关键方案使用 `DES-*` 编号。数据库、API、前端和后端设计相互引用，不能产生字段、枚举、状态或错误语义冲突。

若现有项目没有明确文档目录，智能体应在 G2 前提出建议路径并取得确认，不能自行制造固定目录约定。

### S4：创建开发分支

需求与设计批准后，使用 `branch`：

1. 检查当前分支、所有本地和远程分支、Git worktree 及工作区状态；
2. 从仓库约定识别分支格式，无约定时再建议 `feature/<short-name>`、`fix/<short-name>` 等名称；
3. 不默认基准分支，不默认远端为最新；
4. 验证分支名、基准提交和同名引用；
5. 到达 G3，等待用户对最终命令的明确批准；
6. 创建后验证实际工作目录中的分支、起点和状态；使用独立 Worktree 时，还要确认主工作区未变化并记录分支占用路径。

若工作区不干净，不能自动 stash、提交、还原或清理。必须说明直接切换会携带哪些修改，并优先建议在经 G3 批准的独立 Worktree 中创建分支。独立 Worktree 在开发期间保持使用，任务完成后必须通过 `branch close` 清理门禁释放分支占用。

### S5：代码实现

根据设计分别使用 `implement-backend` 和 `implement-frontend`。实现过程必须：

- 从当前项目确认语言、框架和精确版本；
- 延续现有目录、命名、注释、异常、日志、事务、组件、请求和测试风格；
- 追踪真实入口、调用方和数据落点；
- 只实现批准范围内的最小完整变更；
- 在代码和测试映射中引用相关 `REQ-*`、`DES-*`，但不为追踪编号制造不符合项目风格的代码注释；
- 不虚构内部依赖、组件属性、接口、数据库行为或业务校验；
- 不修改凭据、部署参数和生产配置；
- 新增依赖、执行数据迁移或触达外部系统前单独申请权限。

前后端可独立实现时可以并行分析，但共享契约必须先稳定。任何并行工作都不能让多个执行者同时修改同一文件或同一职责边界。

### S6：验证与自动修复

智能体根据项目已有命令执行与风险匹配的验证：

1. 格式化和静态检查；
2. 类型检查或编译；
3. 聚焦单元测试；
4. 必要的模块级或集成测试；
5. 在具备可访问系统、授权账号和数据清理策略时，使用 `test-ui` 执行浏览器测试。

失败后按以下类别处理：

- **本次实现缺陷**：自动修复，并重新执行受影响验证；
- **既有失败**：保留原始证据，确认与本次变更的关系，不擅自修复范围外代码；
- **环境或依赖阻塞**：记录命令、错误摘要和未验证范围；
- **需求或设计冲突**：返回 G1 或 G2；
- **需要新权限**：暂停并申请最小权限。

不得删除测试、降低断言、屏蔽错误或伪造结果来取得通过状态。

### S7：代码审核与闭环

使用 `review-code` 审查最终工作区差异；Java、MyBatis 或前端变更存在专项风险时，叠加相应专项审核 Skill。

审核范围必须包含：

- 基线提交和最终差异；
- 需求与设计追踪；
- 正确性、兼容、安全、性能、并发、事务、权限和数据风险；
- 测试充分性和未验证边界；
- staged、unstaged 和 untracked 的准确区分。

对于审核发现：

- 明确属于已批准范围、修复方式唯一且低风险的问题，智能体可自动返回 S5 修复并重新验证、复审；
- 会改变业务行为、公共契约、数据库结构、依赖或范围的问题，返回相应审批门；
- 范围外问题只记录，不擅自修改。

只有不存在阻塞级问题，或用户明确接受残余风险时，才能进入 G4。

### S8：提交准备

代码效果经 G4 批准后，使用 `commit-msg` 只读分析真实变更，生成一个或多个逻辑提交建议。然后由总控智能体补充精确暂存和提交命令，进入 G5。

提交拆分以业务目的和依赖关系为准，不按文件类型机械拆分。需求与设计文档如果是本功能交付的一部分，可以和实现一起提交，也可以按项目惯例单独提交，但必须在 G5 明确展示。

### S9：本地提交和交付

G5 批准后：

1. 再次检查 Git 状态；
2. 使用精确路径暂存每个已批准分组；
3. 检查 `git diff --cached --name-status`、`git diff --cached --check` 和暂存差异；
4. 确认无敏感文件、缓存、本地配置和无关改动；
5. 使用批准的提交信息创建本地提交；
6. 验证提交哈希、提交内容、当前分支和提交后工作区状态；
7. 如果本次使用独立 Worktree，确认开发、验证和本地交付已完成，检查 Worktree 干净、无进行中的 Git 操作且 HEAD 已被本地分支引用；
8. 展示准确清理路径、分支、HEAD 和 `git worktree remove` 命令，取得独立确认后使用 `branch close` 移除额外 Worktree；
9. 验证 Worktree 目录和占用记录已移除、分支与提交仍存在、主工作区未变化；
10. 输出最终交付报告。

最终报告至少包含：需求与设计产物路径、分支、提交哈希、实现摘要、验证结果、审核结论、未提交文件、未验证边界和后续建议。

## 7. 阻塞与回退规则

出现下列任一情况时，智能体必须暂停自动推进：

- 用户输入之间存在会改变业务结果的冲突；
- 无法确定项目根目录、基准分支或目标仓库；
- 关键业务规则、权限、状态、金额、时间或数据口径缺失；
- 项目规则要求人工确认或禁止当前操作；
- 工作区已有改动与本次改动重叠且无法安全区分；
- 需要新增依赖、联网下载、访问外部系统、执行数据库变更或使用凭据；
- 需要 fetch、push、合并、标签、发布或历史改写；
- 验证失败表明需求或设计基线需要变化；
- 发现疑似密钥、令牌、私钥、生产配置或个人敏感信息；
- 工具或权限不足，继续执行会让结果无法验证。

暂停时只提出完成决策所需的最少问题，并同时给出已有证据、推荐选项、影响和默认不执行的安全状态。

## 8. 任务台账格式

智能体应维护如下状态，避免长流程丢失上下文：

```markdown
## 当前任务状态

- 任务：<名称>
- 项目根目录：<路径>
- 当前分支：<分支>
- 基准提交：<哈希>
- 当前阶段：S0-S9
- 当前状态：执行中 / 等待审批 / 阻塞 / 已完成
- 已批准审批门：G1、G2……
- 本阶段输入：<文件或对话>
- 本阶段产物：<路径或结论>
- 已修改文件：<精确列表>
- 已执行验证：<命令与结果>
- 待确认项：<列表>
- 风险与未验证项：<列表>
- 下一动作：<唯一明确动作>
```

如果环境支持任务计划或交接文件，可以把上述台账保存在 `.craftkit/local/handoff/current.md`；默认不提交该文件。

## 9. 可直接复制的总控提示词

将以下提示词与原始需求材料一起输入 Codex 或其他已安装 CraftKit 的工具。方括号中的内容按实际情况替换；不知道的内容可以保留为空，由智能体从项目中探测。

```text
你是本次研发任务的总控智能体。请严格遵循项目内 AGENTS.md、CraftKit 各 Skill 的边界，以及《CraftKit 全流程自动化使用指南》。

项目根目录：[项目绝对路径]
原始需求材料：[文件路径、对话内容、会议纪要或问题描述]
期望交付：[功能目标]
明确范围外事项：[可为空]
期望基准分支或引用：[不知道时不要猜测]
文档期望目录：[不知道时先识别项目约定]

执行目标：
根据原始需求和当前项目代码，自动完成需求分析文档落盘、变更规划、适用的技术设计文档、开发分支创建、代码实现、测试验证、代码审核和本地 Git 提交。流程中由你统一维护状态并自动推进；人只负责审批阶段基线、无法从证据确定的业务决策和具有副作用的操作。

执行规则：
1. 开始时读取适用的 AGENTS.md，检查 .craftkit 项目资料、构建文件、Git 状态和相关源码。先保存只读基线，保护现有工作区。
2. 使用 CraftKit 的 requirements 整理原始需求，明确区分输入事实、源码事实、建议、待确认项和待验证项。生成 REQ 编号与可测试验收标准。
3. 到达 G1 时一次性展示需求基线、疑问、建议决策和拟落盘路径，等待我批准。批准后自动执行到下一审批门，不再要求我发送“继续”。
4. 使用 plan-change 和实际适用的设计 Skill 完成设计。只调用与需求有关的 design-db、design-api、design-backend、design-frontend、design-frontend-data、design-workflow、prepare-api、component、form、style，不为不适用领域制造空文档。
5. 到达 G2 时展示设计、影响范围、风险、实施步骤、验证矩阵和文档路径，等待批准。
6. 设计批准后使用 branch 检查并规划本地开发分支。严格按照该 Skill 展示当前状态、分支名、基准提交、创建位置、工作区影响和唯一创建命令，在 G3 等待明确批准。工作区不干净或要求不影响当前 checkout 时使用独立 Worktree。不要自动 fetch、stash、清理、提交或 push。
7. 分支创建后，使用 implement-backend 和/或 implement-frontend 在批准范围内完成最小完整实现。保持项目现有语言、框架版本、目录、注释和测试风格，不虚构接口、组件、业务规则或内部依赖。
8. 自动运行格式化、静态检查、编译、聚焦测试和具备条件的真实验证。本次实现缺陷可自动修复并重跑；需求或设计变化必须回到对应审批门。
9. 使用 review-code 审查最终差异，并按需叠加 review-java、review-mybatis、review-frontend。已批准范围内、低风险且修复方式明确的问题自动修复、复测和复审；范围外或改变契约的问题只报告并等待决策。
10. 到达 G4 时展示实现、REQ 验收映射、验证证据、审核结论、实际差异和残余风险，等待效果审批。
11. 效果批准后使用 commit-msg 生成提交建议，展示精确文件分组、排除项、提交信息以及将执行的 git add -- <明确路径> 和 git commit 命令，在 G5 等待批准。
12. G5 批准后只暂存已展示的精确路径，执行暂存检查并创建本地提交。禁止 git add .、git add -A、push、合并、打标签、发布和历史改写。
13. 每阶段满足质量门后自动进入下一阶段。只有审批门、证据不足、权限缺失、脏工作区冲突、敏感信息或高风险外部操作可以暂停。
14. 每次等待审批时，给出：已完成事项、产物、关键证据、需要批准的明确内容、批准后的自动动作。不要只问“是否继续”。
15. 本地提交核对完成后，如果使用了独立 Worktree，确认生命周期已经结束并进入 branch close：展示准确路径、分支、HEAD、干净状态和唯一移除命令，取得确认后移除，验证分支与提交仍存在且主工作区未变化。
16. 最终报告必须包含文档路径、分支、提交哈希、变更文件、验证结果、审核结论、未提交内容、未验证边界、Worktree 清理结果和后续建议。

现在从 S0 开始执行，并自动推进到 G1。
```

## 10. 审批回复建议

为减少歧义，用户可以使用以下简短格式审批：

```text
批准 G1。需求基线按当前版本执行；待确认项 2 采用方案 B，其余保持范围外。自动推进到 G2。
```

```text
批准 G2。允许按展示的设计和文件范围实现；不允许新增依赖或修改部署配置。自动推进到 G3。
```

```text
批准 G3。执行展示的唯一分支创建命令，随后自动推进到 G4。
```

```text
批准 G4。接受列明的未验证边界，按当前差异准备提交并推进到 G5。
```

```text
批准 G5。只暂存展示的精确文件并创建本地提交；不要 push。
```

如果用户只回复“批准”，智能体只能把它解释为对当前唯一审批门中已完整展示内容的批准，不能扩展为后续审批门、外部系统或高风险操作的预授权。

## 11. 流程完成标准

仅当以下条件全部满足时，任务状态才能标记为“已完成”：

- 需求基线已经批准并落盘；
- 所有适用设计已经批准并落盘；
- 本地开发分支已按批准命令创建；
- 批准范围内的代码已实现；
- 所有可执行验证已完成，阻塞与未验证项已如实记录；
- 代码审核不存在未接受的阻塞问题；
- 代码效果已通过 G4；
- 提交范围与信息已通过 G5；
- 本地提交已创建并核对内容；
- 使用独立 Worktree 时，其生命周期已经结束并安全移除；若用户明确要求保留现场，则任务状态应说明生命周期尚未结束及分支占用路径；
- 未发生未经授权的 push、合并、发布、生产操作或历史改写。

如果由于环境或外部依赖无法完成某项验证，任务只能标记为“本地实现完成，等待外部验证”，不能声称全流程验收通过。