背景：为什么我们需要一套工程化体系来驾驭 AI Coding

AI Coding 的能力与风险

AI 编程助手（如 Cursor、Copilot、通义灵码等）已经具备强大的代码生成能力——给出一段需求描述，几秒钟内就能产出可运行的代码。但当我们真正在工程项目中使用 AI Coding 时，会面对一个核心矛盾：

AI 写代码很快，但它不知道你的项目长什么样。

一个新加入的 AI Agent，如果不给它任何项目上下文，它会按照自己的"常识"写代码：用 Jackson 序列化 JSON、用 @Autowired 注入 Mapper、用 @Transactional 管事务、用 RestTemplate 发 HTTP 请求。这些写法在通用场景下没有问题，但在我们的项目里全是违规的。

我们项目遇到的真实问题

在引入 AI Coding 的过程中，我们反复遇到以下问题：

问题	具体表现	根因
技术栈跑偏	AI 用了 Jackson 而非 FastJSON、用了 var 关键字（Java 9+ 语法）、用了 Spring 3.x 的 jakarta 包名	AI 不知道项目锁定了 JDK 1.8 + Spring Boot 2.3
架构违反	AI 把供应商代码写进了 business 层、跨层引用了 Mapper、反向依赖了上层模块	AI 不了解模块边界和依赖方向
跳过设计直接写代码	拿到需求就让 AI 开写，写完发现方向错了，全部返工	缺少"先设计再编码"的流程约束
文档和代码脱节	新增了错误码但 error-codes.md 没更新、设计文档还停留在 draft 状态、CHANGELOG 空白	缺少文档同步的强制机制
知识不可复用	每个 AI 会话都是"从零开始"，上一次踩过的坑下次还会踩	项目知识没有结构化沉淀
交付质量不可控	PR 提交了才发现没写测试、Linter 报错一堆、编译都没过	缺少交付前的自动检查门禁

这些问题的本质不是 AI 能力不够，而是我们没有给 AI 提供足够的上下文和约束。AI 像一个能力很强但不了解项目的新人——你不说，它就按自己的方式来。

解决思路：Harness Engineering（驾驭式工程化）

Harness Engineering 的核心理念是：

AI 生成，人类驾驭。

不是限制 AI 的能力，而是通过一套分层文档体系为 AI 提供充分的项目上下文和硬性约束，让 AI 在"正确的轨道"上发挥能力。同时通过人工确认门禁确保关键决策由人类把控。

传统 AI Coding                        Harness Engineering
─────────────                        ──────────────────
开发者 → AI → 代码                     开发者 → PRD
         ↑                                ↓
         └ 没有约束，各写各的             AI Agent（受 Rules 约束 + 按需加载 Wiki）
                                            ↓
                                         设计文档 → 人工评审门禁 → 代码 → 自检 → 交付

这套体系做了什么

我们在项目中构建了一套四层文档体系，将"如何让 AI 正确地写代码"这个问题拆解为四个层面：

层次	解决什么问题	类比
Rules 层	告诉 AI"什么能做、什么不能做"	新人入职的技术红线手册
Skills 层	告诉 AI"遇到什么场景该怎么做"	新人入职的操作 SOP
Wiki 层	告诉 AI"项目长什么样、有哪些资产可以复用"	新人入职的项目知识库
Changes 层	告诉 AI"改完代码后要检查什么、同步什么"	新人入职的交付 Checklist

这四层不是独立存在的，而是协同运作：Rules 全程约束行为，Skills 按场景提供操作手册，Wiki 提供项目上下文，Changes 管控变更质量。AI Agent 在开发流程中按步骤按需加载对应文档，既保证了上下文充分，又避免了 token 浪费。

PRD 驱动的标准工作流

在这个体系下，团队的开发方式从"开发者 + AI 自由协作"变成了标准化的 7 步流程：

PRD 输入 → 影响分析 → 技术设计 → 设计评审(人工门禁) → 代码生成 → 文档同步 → 交付自检
 Step 1     Step 2     Step 3      Step 4           Step 5      Step 6      Step 7

关键设计：

• 全流程只有一个人工卡点（Step 4 设计评审），其余步骤 AI 自动执行——兼顾效率与可控性
• 每一步按需加载文档，单步 token 控制在 3000 以内——避免上下文膨胀导致生成质量下降
• 每一步有明确的产出物——流程可追溯、可审查、可回退
• 交付前必须通过 31 项自检 + 自动治理巡检——不达标不准交付

这套体系带来的价值

维度	之前	之后
开发效率	AI 会话从零开始，每次都要重新解释项目	AI 加载 Rules + Wiki 即获得完整上下文，直接开工
代码质量	依赖人工 Review 发现问题	Rules + Linter 35 条规则 + 交付自检三层拦截
设计质量	没有设计环节，直接写代码	强制设计文档 + 7 维度评审门禁
知识沉淀	知识在老员工脑子里	结构化存入 Wiki 层，人机共读
变更可控	PR 不知道改了什么、影响多大	影响分析 + 文档同步 + CHANGELOG 全链路追溯
Skill 复用	每次踩的坑下次还会踩	首次开发沉淀 Skill，后续直接复用

接下来的分享将分步展开：

1. 四层体系详解：Rules / Skills / Wiki / Changes 每一层管什么、团队怎么用
2. PRD 驱动标准工作流：7 步流程每一步做什么、读什么文档、产出什么
3. 无 Skill 场景的处理：新功能模块没有现成操作手册时的兜底机制与沉淀策略
4. 团队执行约定：哪些是硬性约定、谁负责什么、违反了怎么处理

一、四层体系：团队怎么用

第一层：Rules — 技术红线（不可触碰）

定位：项目的技术宪法，AI Agent 上下文自动注入，全程生效，无需手动加载。

团队执行要求：所有新增代码必须通过以下 4 项硬性约束，违反即视为不合格代码：

约束文件	管什么	一句话记忆
always-on.md	技术栈版本、依赖方向、JSON/HTTP/数据库/线程池/事务选型	"JDK 1.8、FastJSON 唯一、OkHttp3 统一、DalManager.of() 访问、TransactionTemplate 事务"
agent-workflow.md	开发流程顺序、设计文档要求、评审门禁、按需加载	"PRD → 设计 → 评审 → 编码 → 自检，一步都不能跳"
java-code-style.md	包结构、类命名、Lombok 使用、异常处理	"类名见名知义、Lombok 优先、异常不吞不裸抛"
java-testing.md	测试框架、Mock 策略、覆盖率	"JUnit 5 + Mockito、DalManager 必须 mockStatic、覆盖率 ≥ 95%"

团队约定：PR Review 时，Reviewer 有权直接拒绝违反 Rules 层的代码，不需要额外讨论理由。

---

第二层：Skills — 标准操作手册（按场景触发）

定位：当遇到特定开发场景时，AI Agent 按需加载对应的操作手册，确保产出符合规范。

团队执行要求：以下场景必须触发对应的 Skill，不得"凭感觉"写代码：

场景	加载哪个 Skill	它告诉你什么
收到 PRD 要开发	prd-to-code.md	从 PRD 到交付的完整 7 步流程，每步读什么文档、产出什么
需要全流程编排	flow-orchestration.md	流程的失败处理、重试策略、断点恢复机制
设计文档写好了	design-review.md	7 个维度逐项评审，通过后才准写代码
要对接新供应商	add-vendor-adapter.md	适配器三件套怎么写：InputConvertor → HttpResultParser → PortResultConvertor
要加新的数据库表	add-entity-mapper.md	Entity → Mapper → Manager → XML → 单测，7 步按序走
要加新的 API 接口	add-api-endpoint.md	Controller 和 SOA Service 两种暴露方式怎么选
提交前检查文档	doc-gardening.md	扫描所有 .md 的元信息，发现过期/无主/草稿文档
交付前治理巡检	auto-governance.md	读构建/测试/Linter 客观结果，自动修复简单问题，生成治理报告

团队约定：提交 PR 时，Commit Message 中注明触发了哪些 Skill（如 feat: 新增百行适配器 [prd-to-code, add-vendor-adapter]），方便 Reviewer 追溯。

---

第三层：Wiki — 项目知识库（人机共读）

定位：项目的"大脑"，存放架构、规范、设计文档。AI Agent 和团队成员都从这里获取上下文。

团队执行要求：以下知识库文档需保持与代码同步，每次变更后同步更新：

架构知识（团队需要了解"系统长什么样"）

文档	团队用途	维护责任
overview.md	新人入职第一份阅读材料，了解系统整体架构	架构变更时同步更新
boundaries.md	写代码前确认"这个类该放哪个模块"，依赖方向是否合规	模块调整时同步更新
code-assets.md	设计新功能时先查这里：有哪些基类/接口可以复用，避免重复造轮子	新增基类/接口时同步更新
data-flow.md	理解同步/异步/文件三种数据流转路径，设计功能时参考	流转路径变更时同步更新

编码规范（团队需要知道"代码怎么写"）

文档	团队用途	维护责任
README.md	规范总入口，快速定位到具体规范	—
naming.md	包/类/方法/变量/数据库五类命名标准	—
error-handling.md	异常怎么抛、错误码怎么定、事务怎么回滚	—
testing.md	测试怎么写、Mock 怎么做、覆盖率多少达标	—
logging.md	日志用什么框架、traceId 怎么传、敏感信息怎么脱敏	—
linter-rules.md	35 条 Linter 自动检查规则，报错消息含"问题→修复→文档"三要素	新增禁止规则时同步更新

功能设计文档（团队需要知道"这个功能怎么设计的"）

文档	团队用途
_template.md	所有设计文档的标准模板，新增功能必须基于此模板
feature-sync-single-request.md	同步单笔请求的设计参考
feature-async-batch-sharding.md	异步批量分片的设计参考
feature-vendor-adapter.md	供应商适配器框架设计参考
feature-rate-limiting.md	限流方案设计参考
feature-scheduler-framework.md	调度框架设计参考
feature-trace-propagation.md	traceId 传播方案参考
feature-high-concurrency-query.md	高并发查询设计参考（PRD 全流程实战案例）
feature-automation-layer.md	自动化层设计，自我验证与自我修复能力

参考资料（团队需要知道"参考资料在哪"）

文档	团队用途
prd-template.md	写 PRD 的标准模板，所有人按此格式提需求
prd-high-Single-request.md	一份完整的 PRD 示例，学习正确写法
error-codes.md	错误码登记表，新增错误码必须在此登记

迭代计划（团队需要知道"当前在做什么"）

文档	团队用途
current-sprint.md	当前 Sprint 任务看板
backlog.md	未来迭代待办池

---

第四层：Changes — 变更管理（每次变更必须走）

定位：确保每次代码变更可追溯、影响可控、交付有标准。

团队执行要求：每个 PR 必须完成以下 3 项变更管理动作：

动作	对应文档	什么时候做
变更前做影响分析	impact-analysis.md	写代码之前，分析改了哪些模块、影响范围多大
变更后登记错误码/API	error-codes.md / api.spec.yaml	代码写完后同步更新
提交前逐项自检	pr-checklist.md	PR 提交前，31 项清单逐条确认
变更记录写入	CHANGELOG.md	PR 合并后记录变更历史

团队约定：PR 未完成自检清单的，Reviewer 有权直接 Request Changes。

---

二、PRD 驱动开发：团队标准工作流

流程全景图

开发者                        AI Agent                      文档体系
  │                              │                            │
  │  1. 提交 PRD                 │                            │
  │ ───────────────────────────▶ │                            │
  │                              │  2. 加载 AGENTS.md         │
  │                              │     + prd-template.md     │
  │                              │ ◀──────────────────────── │
  │                              │  3. 加载 boundaries.md    │
  │                              │     + impact-analysis.md  │
  │                              │ ◀──────────────────────── │
  │                              │  4. 加载设计模板           │
  │                              │     + data-flow.md        │
  │                              │  5. 生成设计文档 (draft)    │
  │                              │ ────────────────────────▶ │
  │                              │  6. 加载 design-review     │
  │                              │ ◀──────────────────────── │
  │  7. 评审报告 + 设计摘要       │                            │
  │ ◀──────────────────────────  │                            │
  │                              │                            │
  │  8. 人工确认「通过」          │                            │
  │ ───────────────────────────▶ │                            │
  │                              │  9. 加载 add-*.md skill   │
  │                              │ ◀──────────────────────── │
  │                              │  10. 生成代码 + 测试        │
  │                              │  11. 同步文档              │
  │                              │ ────────────────────────▶ │
  │                              │  12. 加载 pr-checklist    │
  │                              │ ◀──────────────────────── │
  │  13. 自检结果 + 交付          │                            │
  │ ◀──────────────────────────  │                            │

各步骤详解

Step 0：环境检查与工作区隔离（开始前 5 分钟）

谁做：AI Agent 自动执行

做什么：

• 检查 JDK 1.8 / Maven 3.6+ / Git 是否就绪
• 创建 Git Worktree 隔离工作区，避免污染主分支
• 校验 PRD 完整性，缺失章节则暂停等待补充

团队约定：环境不通过则阻断流程，不允许"先写着回头再修环境"。

---

Step 1：PRD 解析（理解需求）

谁做：AI Agent 加载文档，开发者确认解析结果

读什么：

文档	为什么读
AGENTS.md	了解项目技术栈基线，确保不跑偏
prd-template.md	对照模板结构化解析需求
code-assets.md	查看有哪些基类可以复用，避免重复造轮子

产出：需求解析摘要，标记缺失信息为"待补充"。

---

Step 2：影响分析（确定改动范围）

谁做：AI Agent 分析，开发者确认影响范围

读什么：

文档	为什么读
boundaries.md	确认功能该放哪个模块、依赖方向是否合规
impact-analysis.md	用影响分析模板，输出模块影响矩阵

产出：影响分析报告——改哪些模块、新增哪些文件、修改哪些文件、数据库是否变更、配置是否变更、有哪些回归风险。

---

Step 3：技术设计文档生成（写设计）

谁做：AI Agent 基于模板生成，开发者审阅

读什么：

文档	为什么读
_template.md	设计文档标准模板，保证格式统一
data-flow.md	参考数据流转路径，确保设计符合系统流转模式
feature-*.md（1~2 个相似的）	参考已有功能设计，保持一致性

产出：docs/design/feature-{功能名}.md，状态标记为 draft，包含目标、范围、分层设计、数据库约束、API 约定、测试要求、风险对策。

---

Step 4：设计评审（人工确认门禁 — 全流程唯一的人工卡点）

谁做：AI Agent 执行 7 维度评审，开发者做最终决策

读什么：

文档	为什么读
design-review.md	7 维度评审检查清单

评审 7 维度：

维度	检什么	不通过的典型问题
架构合规	模块归属对不对、依赖方向对不对	把供应商代码写进了 business 层
类设计	基类复用对不对、注解规范不对	没继承已有的 BasePortTrigger
数据库	表名前缀对不对、标准字段全不全	漏了 create_time / update_time
API	路径风格对不对、错误码登记没有	API 路径不符合 /api/v1/ 规范
测试方案	覆盖场景全不全、Mock 策略对不对	只测了正常路径没测异常路径
配置文档	Nacos 配置加没有、文档更新标注没有	忘了在 design 文档标注需要新增的配置项
风险评估	技术风险有没有、回归风险有没有	大表加索引没评估锁表风险

门禁规则：

• 开发者确认「通过」→ 设计文档 status 改为 active，继续 Step 5
• 开发者要求修改 → 修复后重新评审
• 开发者要求重新设计 → 回到 Step 3

禁止在未获得开发者确认前自动进入代码生成阶段。

---

Step 5：代码生成（按规范写代码）

谁做：AI Agent 按依赖方向自底向上生成，开发者验证

触发什么 Skill：

如果 PRD 要求	加载这个 Skill
新增数据库表	add-entity-mapper.md
新增供应商对接	add-vendor-adapter.md
新增 API 接口	add-api-endpoint.md

代码生成顺序（严格遵守，不可乱序）：

dal 层 → business 层 → ext 层 → app 层 → runner/soa 层 → 测试代码

关键约束（违反即返工）：

• 每个类必须有中文注释 + @author
• JSON 用 FastJSON，HTTP 用 OkHttp3
• 数据库用 DalManager.of()，不用 @Autowired 注入 Mapper
• 事务用 TransactionTemplate，不用 @Transactional
• 必须同步生成单元测试，覆盖率 ≥ 95%

---

Step 6：配置与文档同步（代码写完了别忘更新文档）

谁做：AI Agent 自动同步

读什么：

文档	同步什么
error-codes.md	新增的错误码登记
api.spec.yaml	新增/修改的 API 定义
CHANGELOG.md	变更记录

同步清单：

改了什么	必须同步更新
新增错误码	error-codes.md + CodeEnum.java
新增 API	api.spec.yaml
新增功能	feature-.md（status → active）+ CHANGELOG.md |

改了模块结构	boundaries.md
改了数据流转	data-flow.md

---

Step 7：交付前自检（最后一道关卡）

谁做：AI Agent 逐项自检 + 自动治理巡检，开发者确认交付

读什么：

文档	做什么
pr-checklist.md	31 项自检清单逐条确认
auto-governance.md	读构建/测试/Linter 客观结果，自动修复简单问题
doc-gardening.md	扫描文档健康度（过期/无主/草稿检测）

自检 5 维度：

维度	检什么
规则合规	依赖方向、日志、注入、Entity 注解、JSON、HTTP、数据库、线程池、事务、限流、traceId、配置
代码质量	类注释、方法注释、空 catch、异常日志格式、import、单文件行数
测试检查	JUnit 5 + Mockito、命名、覆盖场景、Mock 策略、无外部依赖
文档同步	错误码、API、设计文档 status、last_updated、CHANGELOG
提交规范	commit message 格式、PR 粒度、Git hooks

团队约定：自检全通过后方可交付，任一项不通过则修复后重新自检。

---

三、团队执行约定总结

约定	内容	执行方式
PRD 驱动	所有新功能必须从 PRD 开始，禁止"直接写代码"	开发者提交 PRD → AI Agent 执行 7 步流程
设计先行	代码生成前必须有设计文档，且通过评审	Step 3 产出 draft 设计 → Step 4 评审门禁
人工卡点	设计评审是全流程唯一的人工确认点，其他步骤 AI 自动执行	开发者确认「通过」后方可写代码
Rules 不可违反	4 个 Rules 文件定义的技术约束是红线	Reviewer 有权直接拒绝违规代码
文档同步	代码变更必须同步更新受影响的文档	Step 6 文档同步清单
交付前自检	PR 提交前必须完成 31 项自检 + 自动治理巡检	Step 7 自检全通过方可交付
文档元信息	所有 .md 文件头部必须有 YAML front matter	doc-gardening 定期扫描
Linter 三要素	Linter 报错消息含"问题→修复→文档"三要素	AI Agent 看到报错可自动修复

一句话总结：Rules 层画红线，Skills 层给手册，Wiki 层供知识，Changes 层管变更。PRD 进来走 7 步，中间人工卡一次，最后自检通过才交付。

Q：没有现成 Skill 时怎么办

根据上面的总结，在PRD 驱动开发中：团队标准工作流中的第9步，若开发的是新功能模块， 不存在现成的skill使用，那么应该怎么搞呢

先看现状：现有 3 个 Skill 覆盖了什么

Skill	覆盖场景
add-entity-mapper.md	新增数据库表（Entity → Mapper → Manager → XML）
add-vendor-adapter.md	新增供应商对接（InputConvertor → HttpResultParser → PortResultConvertor）
add-api-endpoint.md	新增对外接口（Controller / SOA Service）

如果 PRD 要求的是这三类之外的功能（比如新增调度任务、新增事件处理器、新增缓存策略等），确实没有现成 Skill 可加载。

答案：四道防线兜底，不存在"无人指导"的情况

即使没有匹配的 Skill，AI Agent 依然有足够的上下文来正确生成代码，因为体系设计了四道防线：

---

防线一：设计文档本身就是"临时 Skill"

Step 3 产出的 docs/design/feature-{功能名}.md 已经包含了完整的分层设计：

目标 → 范围 → 分层设计 → 数据库约束 → API 约定 → 配置项 → 测试要求 → 风险对策

Step 4 评审通过后，这份设计文档就是代码生成的"操作手册"。AI Agent 按照 Step 5 的通用代码生成顺序执行即可：

dal 层 → business 层 → ext 层 → app 层 → runner/soa 层 → 测试代码

prd-to-code.md 中 Step 5 的原文也说明了这一点：

按以下顺序生成代码（严格遵守 Rules 层全部规则）

也就是说，Skill 是锦上添花，不是必需品。没有 Skill 时，设计文档 + Rules 层约束 + 通用生成顺序就足够了。

---

防线二：code-assets.md 的决策树告诉你"继承谁"

code-assets.md 第 9 节有一个完整的基类选择决策树，覆盖了超出现有 Skill 范围的场景：

PRD 需要新增什么？
│
├─ 新增数据库表/字段 → 参考 add-entity-mapper skill
├─ 新增供应商适配器 → 参考 add-vendor-adapter skill
├─ 新增 SOA 服务接口 → 参考 add-api-endpoint skill
│
├─ 新增调度任务           ← 没有现成 Skill，但决策树告诉你：
│  ├─ 上下文工厂 → 继承 BaseSchedulerCxtFactory
│  ├─ 调度上下文 → 继承 BaseScheduleContext
│  ├─ 调度配置 → 继承 BaseSchedulerConfig
│  └─ 触发器 → 实现 Trigger 接口
│
├─ 新增 REST Controller → 参考 add-api-endpoint.md 场景一
│
└─ 新增事件处理           ← 没有现成 Skill，但决策树告诉你：
   └─ 实现 EventHandler<C, E>

即使没有专门的 Skill，Agent 通过这个决策树也能准确知道该继承哪个基类、实现哪个接口。

---

防线三：Rules 层始终约束代码质量

无论有没有 Skill，4 个 Rules 文件始终生效：

Rules 文件	保证什么
always-on.md	技术栈不跑偏、依赖方向不违反、JSON/HTTP/数据库/事务选型正确
agent-workflow.md	流程不跳步、设计文档必须有、评审门禁不跳过
java-code-style.md	包结构对、类命名对、Lombok 用对、异常处理对
java-testing.md	测试框架对、Mock 策略对、覆盖率达标

---

防线四：Step 4 设计评审 + Step 7 交付自检兜底

• Step 4 评审：7 维度评审会检查架构合规性、类设计合理性，如果设计有问题，在这里就会被拦下来
• Step 5.5 即时编译：代码写完立刻编译，编译不过不准往下走
• Step 7 自检：31 项 PR 自检清单 + 自动治理巡检，Linter 35 条规则自动检查

---

但这还不够：团队应该建立"Skill 沉淀机制"

四道防线能保证代码质量不出问题，但如果同类型功能反复开发，每次都靠设计文档指导就太低效了。团队的执行约定应该是：

第一次做新类型功能         第二次做同类型功能
    │                         │
    ▼                         ▼
靠设计文档 + 决策树走完    加载沉淀下来的 Skill
    │                         │
    └───── 沉淀 ──────────────┘
          创建新 Skill

具体做法：

时机	动作	谁做
新类型功能首次开发完成、自检通过后	将本次开发过程中的模式提炼成 .qoder/skills/add-{模式名}.md	开发者 + AI Agent 协作
Skill 创建后	更新 code-assets.md 决策树，标注"参考 add-{模式名} skill"	AI Agent 自动
Skill 创建后	更新 AGENTS.md 快速导航表和 prd-to-code.md Step 5 的按需加载表	AI Agent 自动

举个例子：假设团队第一次要新增一个调度任务类型的模块，没有现成 Skill，流程如下：

1. Step 3：设计文档中写清楚需要继承 BaseSchedulerCxtFactory、BaseScheduleContext 等
2. Step 4：评审确认架构正确
3. Step 5：按设计文档 + code-assets.md 决策树生成代码，Rules 层保证质量
4. Step 7：自检通过，交付
5. 沉淀：创建 .qoder/skills/add-scheduler-task.md，把这次的模式记录下来
6. 下次：再做调度任务时，直接加载 add-scheduler-task.md，效率翻倍

---

团队约定

约定	内容
Skill 不是前提，是沉淀	没有现成 Skill 不阻断开发，靠设计文档 + 决策树 + Rules 兜底
首次开发必须沉淀	新类型功能交付后，必须创建对应的 add-{模式名}.md Skill
决策树同步更新	新增 Skill 时必须同步更新 code-assets.md 的决策树
Skill 评审纳入设计评审	Step 4 评审时，如果发现是"无 Skill 的新模式"，评审报告中需标注"建议沉淀 Skill"

一句话总结：没有 Skill 不影响开发，但开发完不沉淀 Skill 就是技术债。体系的设计是——第一次靠设计文档走通，之后靠 Skill 提效。