用 AI 高质量交付项目的工作方法

一份给「人 + AI」共同协作的工程方法论。

它不教你怎么写 prompt，而是教你怎么把一个项目从 0 到 1 交付得更稳、更快、更可维护。

元数据
版本 v1.0
更新 2026-05-09
适用 中长期 / 多人协作 / 生产级项目的 AI 协作开发
不适用 一次性脚本、临时 POC、小 bug 修复

目录

一、适用边界

在套用任何方法论之前，先判断该不该用。

✅ 建议使用本流程

  • 长期维护的项目、多人协作
  • 生产代码、对质量与可维护性有要求
  • 跨多次会话的复杂任务

⚠️ 不适用，建议简化或跳过

  • 一次性脚本（< 100 行）
  • 探索性 POC、明天就丢的实验
  • 单点 bug 修复 / 明确的小重构

重型流程套到轻量任务上是负担。 先判断场景，再决定流程深度。

二、全局视图

整套方法围绕「先规划 → 后执行；先骨架 → 后填肉；先验证 → 后推进」三条主线展开，共 7 步：

每一步都有明确产物（docs/NN-xxx.md）和完成标准（DoD），形成可审计、可交接的工作链。

三、方法与原则

0. 贯穿性原则

角色 职责
人 PM / 架构师 —— 定方向、做判断、做验收
AI 高级工程搭档 —— 生成候选、写代码、跑命令、写文档

四条贯穿全流程的铁律：

  1. AI 不替你做关键判断，只生成候选 + 解释取舍，等你拍板。
  2. 任何步骤完成后，必须有可审计的产物（md / 代码 / 日志 / commit）。
  3. 小步快跑 —— 优先把任务拆成几十分钟一个闭环，避免一次性几小时的大块改动。
  4. 可逆优于可塑 —— 宁可多走半步去拍照（commit / 文档 / 日志），也不要让状态难以回滚。

Step 1 · 需求澄清（人主导）

目标　把”我想做 X”变成”我要交付什么、怎么算成功”。

产物　docs/00-requirements.md

必须包含

  • 业务目标 / 用户故事（一句话能讲清）
  • 输入 → 输出（数据形态、接口形态）
  • 验收标准（功能 + 非功能：性能、并发、兼容、安全）
  • Out-of-Scope —— 明确不做什么，防止 AI 自由发挥
  • 约束（技术栈、部署环境、预算、时限）

DoD　上述六项均已写明，且人类已签字确认 Out-of-Scope。

💡 实操技巧　让 AI 先反问 5~10 个澄清问题，再开始写需求。
AI 提的问题越多，说明它越在认真理解；如果它一上来就开始写代码，是危险信号。

Step 2 · 方案设计（AI 起草，人定稿）

产物　docs/01-design.md

必须包含

  • 技术原理简述（让 AI 解释为什么这么选）
  • 架构图 / 模块划分（用 mermaid）
  • 关键接口 / 数据契约（函数签名、API、Schema）
  • 2~3 个候选方案对比表（优劣、成本、风险）
  • 已知风险 + 缓解措施
  • 里程碑切分（M1 / M2 / M3 …）

DoD　候选对比清晰、关键接口签名已固化、风险已识别。

🚩 红线　如果 AI 只给一个方案、没风险、没对比，让它重写。
单一方案往往意味着 AI 没真正思考，只是把第一直觉端上来了。

Step 3 · 项目骨架 + 契约先行

产物　目录树 + 空文件 + 类型 / 接口 / Schema 定义 + docs/02-skeleton.md

做法

  • 目录骨架由 AI 生成
  • 核心模块的接口先写出来（TypeScript 类型 / Python Protocol / OpenAPI / Pydantic 模型）
  • 每个模块写空函数 + docstring + TODO
  • 不写业务逻辑

DoD　目录与接口签名已确认，调用关系在 mermaid 中可视化。

💡 关键洞察　接口对了，后面 AI 写错也不会跑偏太远。
这是整个流程里”投入产出比”最高的一步。

Step 4 · 自动化护栏先于业务代码

产物　CI 配置、lint、format、test 框架、pre-commit + docs/03-guardrails.md

清单

  • 包管理 + 依赖锁定文件（uv.lock / package-lock.json 等，防止 AI 乱装包）
  • .env.example + .gitignore（防止密钥 / 产物入库）
  • lint + format + 类型检查
  • 测试框架（哪怕只跑一个空测试）
  • 一个最小的端到端冒烟测试（哪怕只验证 hello world）
  • pre-commit + CI 配置
  • 一条 make test / npm test 的入口命令

DoD　本地一条命令能跑完所有自动化检查，CI 在空仓上能绿。

🛡️ 价值　这一步是”给 AI 戴上安全带“。
CI 能抓住人眼容易漏的低级错误，让人类 review 聚焦在设计与逻辑上。

Step 5 · 垂直切片实现

核心做法　按特性切，不按层切。

  • ❌ 不要先写完所有 model，再写完所有 service，再写完所有 API
  • ✅ 选最核心的 1 个用户故事，从最上层到最底层打通一条最薄的路径（Walking Skeleton）

节奏

1
垂直切片 = 一次 commit + 一轮人类 review + 一次本地验证

每次提交前，让 AI 自己生成

  • 改了什么 / 为什么 / 影响面
  • 怎么验证（手动 + 自动）
  • 已知遗留 TODO

DoD　核心用户故事可端到端跑通；每个切片都通过 CI。

🚩 反模式　让 AI 一次写几百上千行，再让人类 review。
人审不动 = 实际无审查，AI 也藏 bug。

Step 6 · 逐步推进 + 可观测 + 会话治理

推进做法

  • 按 M1 → M2 → M3 推进，每个 M 结束跑一次完整冒烟
  • 关键路径加日志 / metrics
  • 失败时 AI 必须先 复述错误 → 给 2~3 种假设 → 选最可能的一种再动手，禁止无脑试错
  • 每完成一个里程碑，更新 docs/04-progress.md

会话治理（长项目必读）

  • 单 session 不要无限拉长，及时新开会话避免上下文污染
  • 用 docs/04-progress.md 当外部记忆，新会话以它作为入口
  • 模型分工　日常实现用快模型，方案 / 复盘 / 疑难调试用强模型或思考模型（详见 七、模型选择矩阵）

DoD　里程碑通过完整冒烟；进度 md 已更新。

Step 7 · 收尾与沉淀

产物

  • README.md —— 安装、运行、部署
  • docs/05-runbook.md —— 怎么跑、怎么调试、常见故障
  • docs/99-retrospective.md —— 踩坑记录、AI 哪里不靠谱、改进项
  • 把项目里**有效的 prompt 沉淀回 .cursor/rules/ 或 **AGENTS.md，下次复用

DoD　新成员（或新会话的 AI）凭 README + runbook 能独立把项目跑起来。

四、AI 常见失败模式与止损动作

# 失败模式 典型征兆 止损动作
1 幻觉 API / 不存在的库 引用查不到的函数名、版本号 让它贴官方文档链接；查不到就换方案
2 看似写完，跑不起来 自信满满给一大段代码但没运行 强制 “写完即跑 + 贴出输出”；进 Step 5 切片节奏
3 越改越糟（雪球 bug） 一个 bug 改出三个新 bug git stash / 回到上一绿色 commit，重走”复述→假设→动手”
4 过度工程化 100 行需求写出 10 个抽象层 让它对照 00-requirements.md 自审，砍 Out-of-Scope
5 沉默改了无关文件 一次改动悄悄碰了配置 / 其他模块 红线第 4 条触发；要求拆 commit + 解释每处原因
6 上下文污染（越聊越歪） 重复犯低级错、忘了之前的约定 触发”上下文管理”短语；新开会话 + 04-progress.md 接力
7 测试造假 改测试让代码通过，而不是改代码 红线项；要求贴”修改前 vs 修改后的测试断言 diff”
8 盲目重写 让它修小 bug，它把整个文件重写 要求 minimal diff；超过原文件 30% 改动必须先解释
9 隐藏失败 把异常 catch 掉、log 删掉让流程”通过” 红线项；review 时 grep except: / catch / // ignore
10 配置漂移 偷偷改 .env / 依赖版本 / CI 配置 这些文件加入 pre-commit 强保护；改动必须 PR 描述

📌 用法　项目复盘（Step 7）时，把本项目踩过的失败模式打勾，写入 docs/99-retrospective.md，并把对应的”止损短语”补到 Part B。

五、推荐的项目模板仓库结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
ai-project-template/
│
├── README.md                       # 模板使用说明
├── AGENTS.md                       # 给 AI 的全局协作规则（重要）
│
├── .cursor/
│   └── rules/
│       ├── workflow.mdc            # 强制 AI 按 7 步走
│       ├── commit-style.mdc        # commit 规范
│       └── code-review.mdc         # 自审清单
│
├── docs/
│   ├── 00-requirements.md          # 需求 + 验收标准
│   ├── 01-design.md                # 方案对比 + 风险 + 契约
│   ├── 02-skeleton.md              # 骨架说明
│   ├── 03-guardrails.md            # 护栏与本地一键验证
│   ├── 04-progress.md              # 里程碑 / 进度日志（持续更新）
│   ├── 05-runbook.md               # 怎么跑、怎么调试
│   └── 99-retrospective.md         # 复盘
│
├── src/                            # 业务代码
├── tests/                          # 测试（先于业务代码）
│   └── smoke/                      #   端到端冒烟
│
├── scripts/
│   ├── bootstrap.sh                # 一键初始化
│   └── verify.sh                   # 一键自检
│
├── .github/workflows/ci.yml        # CI 护栏
├── .pre-commit-config.yaml
├── .env.example
├── Makefile                        # make test / make lint / make run
└── .gitignore

📐 命名一致性原则　文件命名在「方法与原则」「Prompt」「目录树」三处必须一致。
如需新增文档，沿用 NN-name.md 编号。

六、Prompt

Part A · 项目章程 Prompt（开局喂一次）

复制下方代码块，整段粘贴给 AI；
或保存为 .cursor/rules/workflow.mdc / AGENTS.md 让其常驻。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
# 角色与协作契约

你是我的高级工程搭档。我是 PM + 架构师，负责定方向、做判断、做验收；
你是执行者，负责生成候选方案、写代码、跑命令、写文档。
请严格遵守以下协作契约，任何一条违反请主动停下并提示我。

## 一、根本原则
1. 先规划，后执行；先骨架，后填肉；先小步验证，后全量推进。
2. 你不替我做关键判断，只生成候选 + 解释取舍 + 等我拍板。
3. 任何阶段完成后，必须有可审计的产物（md / 代码 / 日志 / commit）。
4. 每一步动手前，先用 3~5 行说明"我打算怎么做"，等我确认后再执行。
5. 单次改动不超过 3 个文件、不超过约 200 行；超出请主动拆分。
6. 不臆造 API、库、文件路径、版本号；不确定就先查证或问我。
7. 报错时：先复述错误 → 给 2~3 种假设 → 选最可能的一种再动手，禁止无脑试错。

## 二、七步工作流
按以下 7 步推进，每一步都要产出对应文档，统一存放在 `docs/`。

### Step 1｜需求澄清
- 动笔前，先抛 5~10 个澄清问题（业务目标、输入输出、性能、边界、技术约束等）。
- 我回答后，产出 `docs/00-requirements.md`，包含：
  - 业务目标（一句话）
  - 用户故事 / 使用场景
  - 输入 → 输出（数据形态、接口形态）
  - 验收标准（功能 + 非功能）
  - Out-of-Scope（明确不做什么）
  - 约束（技术栈、部署环境、预算、时限）

### Step 2｜方案设计（给我对比，不要单选）
产出 `docs/01-design.md`，包含：
- 技术原理简述（为什么这么选）
- 架构图 + 模块划分（用 mermaid）
- 关键接口 / 数据契约（函数签名 / API / Schema）
- 2~3 个候选方案对比表（优劣、成本、风险）
- 已知风险 + 缓解措施
- 里程碑切分（M1 / M2 / M3 …）
- 如果你只能给一个方案、或没风险分析，请明确说明原因。

### Step 3｜项目骨架 + 契约先行
- 生成目录树 + 空文件
- 核心模块的接口 / 类型 / Schema 必须先写
  （TS 类型 / Python Protocol / OpenAPI / Pydantic）
- 每个模块写空函数 + docstring + TODO
- 产出 `docs/02-skeleton.md`：目录树 + 模块职责说明
- 此步骤不写业务逻辑，等我确认骨架。

### Step 4｜自动化护栏先行
在写业务代码之前，先搭好：
- 包管理 + 依赖锁定文件
- `.env.example` + `.gitignore`
- lint + format + 类型检查
- 测试框架（哪怕只跑一个空测试）
- 一个最小的端到端冒烟测试
- pre-commit + CI 配置
- 一条 `make test` 或 `npm test` 的入口命令
- 产出 `docs/03-guardrails.md`：如何本地一键验证

### Step 5｜垂直切片实现（不是按层写）
- 按特性切，不按层切：选最核心的 1 个用户故事，
  从最上层到最底层打通一条最薄的路径（Walking Skeleton）。
- 每个切片 = 一次 commit + 一轮我审 + 一次本地验证通过。
- 每次提交前，自动生成：
  - 改了什么 / 为什么 / 影响面
  - 怎么验证（手动步骤 + 自动测试）
  - 已知遗留 TODO

### Step 6｜逐步推进 + 可观测
- 按 M1 → M2 → M3 推进，每个 M 结束跑一次完整冒烟。
- 关键路径加日志 / metrics。
- 失败时严格走"复述 → 假设 → 动手"流程。
- 每完成一个里程碑，更新 `docs/04-progress.md`。
- 当本会话上下文较长时，主动提示我"建议新开会话，并以 04-progress.md 为入口"。

### Step 7｜收尾与沉淀
- `README.md`：安装 / 运行 / 部署
- `docs/05-runbook.md`：怎么跑、怎么调试
- `docs/99-retrospective.md`：踩坑记录、AI 哪里不靠谱、改进项
- 把有效的 prompt 沉淀回 `.cursor/rules/` 或本文件

## 三、硬性红线（违反即停止）
- 不写测试就交付业务代码
- 一次性写超过约 200 行而不分段确认
- 跳过 Step 1~3 直接动手写业务代码
- 改动跨 3 个以上文件不主动拆 commit
- 报错后不分析直接重试
- 编造不存在的 API / 文件 / 命令

例外：紧急 hotfix / 一次性脚本 / 我明确说"先跑通再说"时，
可临时跳过 Step 1~3，但事后必须补 `docs/00-requirements.md` 简版。

## 四、沟通格式
你的每次回复尽量用以下结构（简单确认除外）：
- 当前所在步骤：Step X
- 本轮我打算做：…
- 预期产物：…
- 我需要你先确认：…（如有）

——以上为我们的协作契约，请确认你已理解，并准备好进入 Step 1：开始向我提澄清问题。

Part B · 推进过程中的触发短语（按需复制）

长会话里 AI 容易”自由发挥”，用下面这些短小、明确的短语强制拉回正轨。

▸ 进入下一步

1
进入 Step 2：基于已确认的需求，输出 2~3 个候选方案对比，等我拍板。
1
进入 Step 3：先生成目录骨架 + 接口/Schema 契约，不要写业务逻辑。
1
进入 Step 4：搭自动化护栏，本地能一键 lint/test/冒烟。
1
进入 Step 5：选第一个垂直切片（最核心的用户故事），打通一条最薄的端到端路径。

▸ 拉回正轨

1
停。你正在违反协作契约第 X 条。请回到上一步，先做 [澄清/方案/骨架/测试]，再动手。
1
你这次改动超过了 3 个文件 / ~200 行，请拆成多次提交，每次先告诉我打算怎么改。
1
请按"复述错误 → 列 2~3 种假设 → 选一种"的格式重新分析这个报错，再动手。

▸ 强制产出

1
请把刚才的讨论结论沉淀到 docs/0X-xxx.md，并列出本轮的 DoD（验收标准）。
1
请给这次改动写一段 commit message：what / why / impact / how-to-verify。

▸ 上下文管理

1
2
当前会话上下文已较长。请把项目状态总结到 docs/04-progress.md，
我将在新会话中继续，你将以那份 md 作为外部记忆。

七、模型选择矩阵

不同任务用不同模型，能显著提升质量 / 节省成本。

原则　便宜的做体力活，贵的做脑力活。

任务类型 推荐模型档次 理由
Step 1　需求澄清 / 反问 强模型（含思考） 需要从模糊需求中识别隐藏假设、提出关键追问
Step 2　方案设计 / 候选对比 强模型（含思考） 涉及架构权衡、风险预判，最不该省钱的环节
Step 3　骨架 + 接口契约 中等模型 模式化工作，但需理解整体设计
Step 4　护栏 / CI / 模板 快模型 高度模式化，看示例就会写
Step 5　垂直切片实现 中等模型为主 大多数业务代码
Step 5　遇到疑难 bug 切换到强模型 / 思考模型 调试需要推理能力
Step 6　日常推进 / 小改动 快模型 重复劳动
Step 6　跨模块重构 / 性能优化 强模型 需要全局视角
Step 7　复盘 / 文档总结 中等到强模型 需要抽象与提炼
commit message / changelog 快模型 模式化输出
code review（自审或互审） 强模型 review 比写代码更需要思考

升档信号　出现以下情况立刻升档：

  • 同一个 bug 修了 2 次没修对
  • AI 反复要求”再多给点上下文”还说不清
  • 一个改动牵涉到 3 个以上模块的设计取舍
  • 出现 失败模式图鉴 中第 3 / 6 / 10 条

八、使用建议

  1. 第一次喂 Part A —— AI 应主动反问澄清问题，别让它跳过这步。
  2. 每次切换阶段用 Part B 的”进入下一步”短语 —— 比模糊地说”继续”靠谱得多。
  3. AI 走偏时立刻用”拉回正轨”短语 —— 越早纠偏成本越低。
  4. 在 Cursor 中：
    • Part A 存为 .cursor/rules/workflow.mdc（项目级，自动加载）
    • 或放到 AGENTS.md（仓库根目录，全局生效）
  5. 项目结束做 Step 7 复盘时 —— 把本次有效的 Part B 短语补回这份文档，让方法论持续进化。

九、多人协作约定

团队场景下价值很大；个人项目可以省略本节。

1. 共享 prompt 资产

所有 prompt / rules 进 git，跟代码一起 review。路径约定：

路径 用途
.cursor/rules/ Cursor 项目级规则
AGENTS.md 通用 AI 协作规则（Cursor / Codex / Claude Code 等都读）
docs/prompts/ 一次性、场景化的 prompt 片段（如”重构 X 模块的 prompt”）

2. 修改 prompt 必须走 PR

  • 任何对 AGENTS.md / .cursor/rules/ 的修改 = 修改”团队工作规则”
  • 必须有人 review，并在 PR 里说明：为什么改、改后预期 AI 行为有何不同

3. AI 产物的标记

  • AI 生成且未经人类深度审核的代码 / 文档，commit message 加前缀 [AI-DRAFT]
  • 经人类审核确认后，正常提交不加前缀
  • 这样 git log --grep="AI-DRAFT" 可以快速找到”待复审债务”

4. 任务交接

中途交接任务给同事 / 新会话时，必须更新到 docs/04-progress.md：

  • 当前在哪一步 / 哪个里程碑
  • 已完成什么（带 commit hash）
  • 卡在哪里 / 待决策事项
  • 接手人 / AI 应该读哪些文件、跑哪些命令

这份 md 就是”项目的状态机快照”。

5. 冲突仲裁

当两个 AI（或两个人 + AI）给出不同方案时：

  • ❌ 不要让 AI 自己投票
  • ✅ 由人类按 01-design.md 的”候选对比表”格式重新评估
  • 写入决策记录 docs/decisions/NNNN-title.md（轻量级 ADR）

6. 安全与合规

AI 不得碰：

  • .env / 任何密钥文件
  • 生产数据库
  • CI/CD 部署密钥

在 .cursor/rules/ 中写明禁区，并用 pre-commit hook 拦截。

结语

本文档本身就是一份”活文档“。

每次项目复盘后，把新踩到的坑、新有效的 prompt、新发现的失败模式补回来，让方法论持续迭代。

真正能让 AI 协作变好的，不是某个神奇的 prompt，而是一套被你和团队反复打磨过的、属于你们自己的工作方法。

杂谈
#AI #工程思维 #Cursor #项目管理
用 AI 高质量交付项目的工作方法
http://baikelwang.github.io/2026/06/14/AI-协作工作方法/
作者
北海
发布于
2026年6月14日
许可协议