背景为什么我们需要一套工程化体系来驾驭 AI CodingAI 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遇到什么场景该怎么做新人入职的操作 SOPWiki 层告诉 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后续直接复用接下来的分享将分步展开四层文档体系详解Rules / Skills / Wiki / Changes 每一层管什么、团队怎么用PRD 驱动标准工作流7 步流程每一步做什么、读什么文档、产出什么无 Skill 场景的处理新功能模块没有现成操作手册时的兜底机制与沉淀策略团队执行约定哪些是硬性约定、谁负责什么、违反了怎么处理一、四层文档体系团队怎么用第一层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.md7 个维度逐项评审通过后才准写代码要对接新供应商add-vendor-adapter.md适配器三件套怎么写InputConvertor → HttpResultParser → PortResultConvertor要加新的数据库表add-entity-mapper.mdEntity → Mapper → Manager → XML → 单测7 步按序走要加新的 API 接口add-api-endpoint.mdController 和 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.md35 条 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.mdtraceId 传播方案参考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写代码之前分析改了哪些模块、影响范围多大变更后登记错误码/APIerror-codes.md / api.spec.yaml代码写完后同步更新提交前逐项自检pr-checklist.mdPR 提交前31 项清单逐条确认变更记录写入CHANGELOG.mdPR 合并后记录变更历史团队约定PR 未完成自检清单的Reviewer 有权直接 Request Changes。二、PRD 驱动开发团队标准工作流流程全景图开发者 AI Agent 文档体系 │ │ │ │ 1. 提交 PRD │ │ │ ───────────────────────────▶ │ │ │ │ 2. 加载 AGENTS.md │ │ │ prd-template.md │ │ │ ◀──────────────────────── │ │ │ 3. 加载 boundaries.md │ │ │ impact-analysis.md │ │ │ ◀──────────────────────── │ │ │ 4. 加载设计模板 │ │ │ >Step 7交付前自检最后一道关卡谁做AI Agent 逐项自检 自动治理巡检开发者确认交付读什么文档做什么pr-checklist.md31 项自检清单逐条确认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 matterdoc-gardening 定期扫描Linter 三要素Linter 报错消息含问题→修复→文档三要素AI Agent 看到报错可自动修复一句话总结Rules 层画红线Skills 层给手册Wiki 层供知识Changes 层管变更。PRD 进来走 7 步中间人工卡一次最后自检通过才交付。Harness Engineering的四层文档体系就完成了全部介绍。这四层文档体系架构就对应着Harness 三层编码体系项目一旦完成三个层次的文档建设就实现了AI Coding一站式开发了。文档划分如下## Harness 三层体系 | 层次 | 状态 | 说明 | |------|------|------| | **信息层** | ✅ 已完成 | AGENTS.md docs/architecture/conventions/design/plans/reference/changes| | **约束层** | ✅ 已完成 | Rules4 文件 Skills7 文件 LinterPMD/Checkstyle/ArchUnit/Maven Enforcer PR checklist | | **自动化层** | ✅ 已完成 | 后台清理 Agent Git Worktree 自动化 客观侧性接入 自动衰减检测 持续治理报告 |Q没有现成 Skill 时怎么办根据上面的总结在PRD 驱动开发中团队标准工作流中的第9步若开发的是新功能模块 不存在现成的skill使用那么应该怎么搞呢先看现状现有 3 个 Skill 覆盖了什么Skill覆盖场景add-entity-mapper.md新增数据库表Entity → Mapper → Manager → XMLadd-vendor-adapter.md新增供应商对接InputConvertor → HttpResultParser → PortResultConvertoradd-api-endpoint.md新增对外接口Controller / SOA Service如果 PRD 要求的是这三类之外的功能比如新增调度任务、新增事件处理器、新增缓存策略等确实没有现成 Skill 可加载。答案四道防线兜底不存在无人指导的情况即使没有匹配的 SkillAI Agent 依然有足够的上下文来正确生成代码因为体系设计了四道防线防线一设计文档本身就是临时 SkillStep 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但决策树告诉你 └─ 实现 EventHandlerC, E即使没有专门的 SkillAgent 通过这个决策树也能准确知道该继承哪个基类、实现哪个接口。防线三Rules 层始终约束代码质量无论有没有 Skill4 个 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-{模式名} skillAI Agent 自动Skill 创建后更新 AGENTS.md 快速导航表和 prd-to-code.md Step 5 的按需加载表AI Agent 自动举个例子假设团队第一次要新增一个调度任务类型的模块没有现成 Skill流程如下Step 3设计文档中写清楚需要继承BaseSchedulerCxtFactory、BaseScheduleContext等Step 4评审确认架构正确Step 5按设计文档 code-assets.md 决策树生成代码Rules 层保证质量Step 7自检通过交付沉淀创建.qoder/skills/add-scheduler-task.md把这次的模式记录下来下次再做调度任务时直接加载add-scheduler-task.md效率翻倍团队约定约定内容Skill 不是前提是沉淀没有现成 Skill 不阻断开发靠设计文档 决策树 Rules 兜底首次开发必须沉淀新类型功能交付后必须创建对应的add-{模式名}.mdSkill决策树同步更新新增 Skill 时必须同步更新 code-assets.md 的决策树Skill 评审纳入设计评审Step 4 评审时如果发现是无 Skill 的新模式评审报告中需标注建议沉淀 Skill一句话总结没有 Skill 不影响开发但开发完不沉淀 Skill 就是技术债。体系的设计是——第一次靠设计文档走通之后靠 Skill 提效。后续接下来我会通过后续6篇文章系统性的指导从零搭建 Harness Engineering 四层文档体系最终实现从 BRD/PRD 到代码交付的一站式 AI 开发与自检闭环