# aifirst

**Repository Path**: bread_software/aifirst

## Basic Information

- **Project Name**: aifirst
- **Description**: 渐进式 SDD 端到端 AI 研发工作流。单一入口 /aifirst + 参数化阶段选择，五档 Profile 路由，四道脚本化门禁（G1 规格 / G2 构建 / G3 验收 / G4 发布），产物驱动、豁免治理、本地沙箱验收。适用于需要 AI 参与完成「需求→规格→实现→验收→发布→归档」全流程的项目。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-27
- **Last Updated**: 2026-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# aifirst

**AI 写代码，脚本说了算。**

aifirst 是给 AI 编码加“完工验收”的一套工作流。你只要说一句 `/aifirst 订单查询接口`，它就会带着 AI 从需求走到可发布：先把需求写清楚，再写代码，再拿运行证据验收，最后评审、走发布检查、归档。

它解决的不是“AI 写得慢”，而是“AI 说写完了，你不敢信”。

适合已经在用 AI 写代码、但不敢直接让它上线的团队；一次性脚本和纯问答用不上它。

## 它好在哪

- **一条命令，不用背流程。** 不用先初始化，不用记九个命令的顺序。`/aifirst <变更名>` 自己判断该走哪条路。
- **门禁由脚本判，不由 AI 自评。** 编译、测试、验收、审批，过没过看脚本输出，不看 AI 说“我检查过了”。
- **小改动快，大改动严。** 改文案走快车道，动核心链路自动加检查，不搞一刀切。
- **验收看运行证据。** 每条验收标准都要有请求、响应和断言结果。只回一个 HTTP 200 不算通过。
- **没有环境也能先跑。** 内置本地沙箱，先把验收链路跑通；真实环境接上后，证据格式不用改。
- **例外只能人开口。** 要跳过某项检查，必须由人写进豁免清单，写清原因、责任人和到期日。AI 在证据里给自己写“豁免”，直接判失败。
- **越用越有积累。** 每次归档会把本次规格并进项目规格库，下次不用从零开始。

## 5 分钟上手

### 最省事的方式：让 AI 带你走

把 `aifirst-skill/` 装进你的 AI 编码工具（支持 `SKILL.md` 的加载器），在项目根目录输入：

```text
/aifirst 订单查询接口
```

第一次运行会自己把骨架铺好（如果你的工具没有暴露 skill 脚本路径，先用下面的命令装一次）。它会先问你 7 个问题：影响面多大、涉不涉及数据迁移、要不要跨团队、回滚难不难……然后选一条合适的流程，开始干活。

你只需要做两个决定：

1. **规格确认**：AI 把需求、任务、验收标准写给你看，你说“可以”，它才写代码。
2. **验收结论**：AI 拿运行证据给你看，你确认能不能上线。

其他时间它可以自己跑：编译失败自己修，测试失败自己补，同一个问题反复修不好会停下来找你。

### 想先自己看一眼：三条命令

```bash
# 1. 铺骨架（在你的项目根目录执行）
python /path/to/aifirst-skill/code-copilot/scripts/sdd_install.py --target .

# 2. 建一个变更，看它给你排的路线
python code-copilot/scripts/sdd_flow.py route order-query --dims 1,1,1,1,1,1,1 --type feature

# 3. 看状态
python code-copilot/scripts/sdd_flow.py status order-query
```

第二条命令会输出类似：

```text
复杂度：C1（七维就高）
选中 Profile：express
阶段链：route  →  spec  →  build  →  verify  →  deliver  →  archive
```

看到这条链，说明跑通了。接下来把活交给 AI：

```text
/aifirst order-query
```

> 安装器如果提示静态检查/安全扫描命令没探测到，会以退出码 1 结束。这不是安装失败，按提示把命令补进 `code-copilot/rules/gate.yaml` 就行；不补的话，G2 构建门禁会一直拦着。

## 七个阶段，一条流水线

```mermaid
flowchart LR
  R[route 定路线] --> S[spec 写清楚]
  S -->|G1| B[build 写代码]
  B -->|G2| V[verify 真验收]
  V -->|G3| RV[review 评审]
  RV --> D[deliver 发布]
  D -->|G4| A[archive 归档]
```

| 阶段 | 做什么 | 产出 | 怎么进下一步 |
|---|---|---|---|
| **route** | 判断这个需求该走哪条流程 | `state.json` | 自动进入下一阶段 |
| **spec** | 把需求写成能验收的规格，拆任务 | `spec.md`、`tasks.md`、`acceptance.yaml`、`log.md` | G1 通过：写得清楚、验得出来 |
| **build** | 在独立工作区写代码、补测试 | 代码、测试、`sdd/<变更名>` 分支 | G2 通过：编译、测试、扫描都过 |
| **verify** | 部署后逐条跑验收，留下证据 | `evidence/<AC>.json` | G3 通过：证据齐、断言真 |
| **review** | 先看证据，再看代码 | `review.md` | 评审结论“通过” |
| **deliver** | 发布前检查评审、复验、审批 | `release.md`、`approvals.yaml` | G4 通过 |
| **archive** | 把本次规格并进项目规格库 | `specs/`、归档目录 | 流程结束 |

**衔接方式很简单：上一阶段的产物，就是下一阶段的入场券。**

每次标记完成，引擎都会查两件事：该有的文件在不在，该过的门禁过没过。AI 说“我做完了”不算数，文件齐了、门禁过了才算数。比如 build 做完，`spec.md` 还是 draft，或者任务清单还有没勾的，流程不会往下走。

## 五挡流程，按需求大小换挡

不是所有需求都值得走全套。aifirst 有五挡：

| 挡位 | Profile | 什么时候用 | 怎么走 |
|---|---|---|---|
| 1 挡 | **express** | 改文案、改配置、单文件小改动 | route → spec → build → verify → deliver → archive，跳过评审 |
| 2 挡 | **standard** | 常规业务需求，一个团队能搞定 | 七个阶段全走 |
| 3 挡 | **enterprise** | 核心链路、跨团队、合规、数据迁移 | 七个阶段全走，每道门禁停下来让人确认 |
| 倒挡 | **bugfix** | 修缺陷 | 跳过 spec，直接复现 → 根因 → 修复 → 验收 → 评审 → 发布 → 归档 |
| 应急挡 | **hotfix** | 线上故障，先止血 | route → build → verify → deliver → archive，跳过 spec 和 review |

怎么选挡？默认由 AI 按七个维度打分，哪一维最严重就按哪一维算，**就高不就低**。你也可以直接指定：

```bash
python code-copilot/scripts/sdd_flow.py route order-query --profile standard --type feature
```

做到一半发现比预想的大，可以重新路由到更高的挡位。

## 实际工程里怎么用

| 场景 | 你可以这么说 | 系统会怎么走 |
|---|---|---|
| 做一个新接口 | `/aifirst 订单查询接口` | 打分选挡 → 写规格 → 你确认 → 写代码 → 验收 → 评审 → 发布 |
| 改个文案 | `/aifirst 首页文案调整` | 通常走 express，快进快出 |
| 修一个 bug | `/aifirst 修复订单金额计算错误` | 通常走 bugfix，跳过规格，直接复现和修 |
| 线上出故障 | `/aifirst 支付回调超时` | 按 hotfix 处理，先止血，事后补评审 |
| 只想看进度 | `/aifirst 订单查询接口 --status` | 列出每个阶段的状态和卡点 |
| 只重跑验收 | `/aifirst 订单查询接口 --stage verify` | 只做验收和 G3 门禁 |
| 跑一段区间 | `/aifirst 订单查询接口 --from spec --to verify` | 从规格跑到验收 |

团队想看整体数据，跑 `python code-copilot/scripts/sdd_metrics.py`，能看到周期、挡位分布、门禁通过率和豁免欠账。

### 一个需求走完，你会拿到什么

```text
code-copilot/changes/order-query/
├── spec.md            需求和方案，人和 AI 都看这份
├── tasks.md           任务拆解，每个任务对应哪条验收标准
├── acceptance.yaml    机器可读的验收标准
├── evidence/          每条验收标准的运行证据
├── review.md          评审结论
├── release.md         发布记录和真实环境复验
└── approvals.yaml     谁批准发布的
```

这些东西不是为了交差，是为了下次出问题时能查：当时怎么想的、验了什么、谁签的字。

## 命令清单

### 主入口：`/aifirst`

```text
/aifirst <变更名>                          从当前进度推进到链尾
/aifirst <变更名> --status                 查看这个变更的状态
/aifirst <变更名> --next                   只推进下一个阶段
/aifirst <变更名> --stage verify           只跑一个阶段
/aifirst <变更名> --from verify            从某阶段起推进到链尾
/aifirst <变更名> --to review              从链首推进到某阶段（含）
/aifirst <变更名> --until review           同 --to
/aifirst <变更名> --from spec --to verify  跑一个区间
/aifirst <变更名> --profile standard       跳过七维打分，直接指定挡位
/aifirst --list                            列出全部变更
```

阶段名固定七选一：`route`、`spec`、`build`、`verify`、`review`、`deliver`、`archive`。

几个常用组合：

```text
/aifirst 订单查询接口                          正常推进
/aifirst 订单查询接口 --status                 只看进度
/aifirst 订单查询接口 --stage verify           只重跑验收
/aifirst 订单查询接口 --from spec --to verify  从规格跑到验收
/aifirst 订单查询接口 --next                   一步一步走
```

### 阶段执行体

`/aifirst` 是总入口，下面这些命令是各阶段的执行体。平时不用记顺序，`/aifirst` 会在对应阶段调用它们；需要单独重跑某个阶段时，也可以直接说。

| 命令 | 做什么 |
|---|---|
| `/propose` | 先澄清需求和方案，再产出 `spec.md`、`tasks.md`、`acceptance.yaml` |
| `/apply` | 按确认后的规格写代码，使用 worktree、TDD 和真实验证 |
| `/verify` | 部署后逐条验收，产出 `evidence/` 运行证据 |
| `/review` | 先审证据，再审规格符合性，最后审代码质量 |
| `/fix` | 按评审或调试结论小步修正 |
| `/archive` | 合并活体规格、沉淀知识、归档变更 |
| `/finish` | 归档后做 merge / PR / keep / discard / worktree 清理 |
| `/test --plan` | 只生成或完善 `test-spec.md`，不改业务代码 |
| `/test --补测` | 按评审和测试缺口补测试，原则上只改测试文件 |
| `/test --tdd` | 明确要求时走 Red / Green |
| `/spec-init` | 显式初始化项目上下文，可选 |

`/test` 不写参数时等价于 `/test --plan`。

### 引擎命令

需要写进 CI、脚本，或者不想经过 AI 时，直接用这些：

| 命令 | 用途 |
|---|---|
| `python code-copilot/scripts/sdd_install.py --target .` | 铺骨架、探测构建命令 |
| `python code-copilot/scripts/sdd_flow.py route <变更名> --dims ... --type ...` | 路由并落状态 |
| `python code-copilot/scripts/sdd_flow.py plan <变更名> --from A --to B` | 看执行计划 |
| `python code-copilot/scripts/sdd_flow.py status <变更名>` | 看状态 |
| `python code-copilot/scripts/sdd_flow.py list` | 列出全部变更 |
| `python code-copilot/scripts/sdd_flow.py next <变更名>` | 看下一阶段能不能进 |
| `python code-copilot/scripts/sdd_flow.py can <变更名> <阶段>` | 检查某阶段准入 |
| `python code-copilot/scripts/sdd_flow.py enter <变更名> <阶段>` | 记录进入阶段 |
| `python code-copilot/scripts/sdd_flow.py done <变更名> <阶段>` | 标记完成，触发门禁 |
| `python code-copilot/scripts/sdd_gate.py all <变更名>` | 链式跑 G1→G2→G3→G4 |
| `python code-copilot/scripts/sdd_gate.py g1/g2/g3/g4 <变更名>` | 单独跑某道门禁 |
| `python code-copilot/scripts/sdd_sandbox.py verify <变更名>` | 本地沙箱验收 |
| `python code-copilot/scripts/sdd_sandbox.py serve <变更名>` | 起常驻沙箱，供人工 curl |
| `python code-copilot/scripts/sdd_verify.py verify <变更名> --env test` | 真实环境验收 |
| `python code-copilot/scripts/sdd_verify.py check --env test --probe` | 检查环境配置 |
| `python code-copilot/scripts/sdd_specmerge.py <变更名>` | 把本次规格并入 `specs/` |
| `python code-copilot/scripts/sdd_metrics.py --root .` | 采集度量 |
| `python code-copilot/scripts/sdd_guard.py check` | 检查治理文件修改者 |
| `python code-copilot/scripts/sdd_guard.py install-hook` | 安装提交前拦截钩子 |

> 引擎脚本默认把 `code-copilot/` 的上一级当作项目根。用 skill 目录里的脚本操作另一个项目时，记得加 `--root <目标项目>`。
>
> `--dims` 的七维顺序：核心中台影响、产品形态、跨团队范围、数据迁移、合规、并发、回滚难度，每维 1–4 分，就高不就低。

## 四道门禁，卡住四类问题

| 门禁 | 卡什么 | 一句话 |
|---|---|---|
| **G1 规格** | 需求含糊、验收标准没法判定 | “说不清楚，就别写代码” |
| **G2 构建** | 编译不过、测试不过、扫描有红线 | “代码没跑通，别往下走” |
| **G3 验收** | 没证据、证据造假、只回 HTTP 200 | “没验过，就是没验过” |
| **G4 发布** | 没评审、没复验、没审批 | “手续不全，不许上线” |

门禁结果只有几种：通过、失败、没验成、跳过、提醒。**“没验成”和“失败”一样会挡住流程**，区别是失败要改代码，没验成通常要补环境或补配置。

确实做不了的检查，由人写进 `waivers.yaml`，写清检查项、原因、责任人和到期日。AI 不能自己给自己豁免，在证据里写“豁免”会直接判失败。

## 接入团队，先做三件事

1. **填构建命令。** 打开 `code-copilot/rules/gate.yaml`，把构建、测试、静态检查、安全扫描四条命令填上。安装器能自动识别 Maven、Gradle、Node、Python，识别不到会提示你补。空着不填，对应门禁会一直拦。
2. **决定要不要接真实环境。** 不接也能用，验收走本地沙箱；要接就配 `code-copilot/rules/env.yaml`，填网关地址、查库命令、查日志命令。配好后验收会优先走真实环境。
3. **锁定治理文件。** 把能改 `gate.yaml` 和 `waivers.yaml` 的人写进 `code-copilot/rules/governance.yaml` 的 `owners`，然后装提交钩子：

```bash
python code-copilot/scripts/sdd_guard.py install-hook
```

以后不在 `owners` 名单里的提交者，改门禁或改豁免会被拦下来。门禁和豁免如果谁都能改，整套东西就是摆设。

## 几条边界，提前说清楚

- **沙箱不是生产验收。** 它能证明请求发对了、断言能跑、证据格式没问题；不能证明你的实现真的对。沙箱证据会被标出来，发布前要在真实环境复验。
- **构建和扫描命令要按项目补。** 框架不猜你的项目怎么构建。探测不到就留空，留空就是“没验过”，不会假装通过。
- **查库和查日志要自己封小脚本。** 不同公司的数据库和日志平台不一样，框架只约定“输入什么、输出一个整数”，具体怎么查由你写。
- **它不替代 CI，也不替代人的判断。** CI 负责跑构建和测试，它负责判定结果、留证据、卡流程；发布窗口和风险接不接受，还是人决定。

## 文档

| 文档 | 看什么 |
|---|---|
| `aifirst-skill/SKILL.md` | skill 入口和适用场景 |
| `docs/设计文档.md` | 为什么这么设计、七阶段和门禁的细节 |
| `docs/上手操作.md` | 使用者视角的操作手册和常见问题 |
| `aifirst-skill/commands/*.md` | 每个阶段 AI 要遵守的纪律 |
| `aifirst-skill/code-copilot/workflows/*.md` | 五挡流程的具体定义 |

---

**一句话总结：让 AI 干活，让脚本验收，让人做决定。**