概述
系列定位：本系列共 6 篇搭建指南 + 1 篇总览，指导从零搭建 Harness Engineering 四层文档体系，最终实现从 BRD/PRD 到代码交付的一站式 AI 开发与自检闭环。
本篇定位： 6 篇搭建指南的总览，通过本篇文章对搭建Harness Engineering 有一个整体的了解和概括
1. 系列文档作用说明
| 序号 | 文档 | 定位 | 核心产出 |
|---|---|---|---|
| 1 | 项目入口与架构基线 | 建立 AI Agent 的"第一印象"和架构知识底座 | AGENTS.md、README.md、architecture/ 4 文件 |
| 2 | Rules 层 --- 硬性约束体系 | 将架构基线转化为 AI 必须遵守的硬性规则 | .qoder/rules/ 4 文件（always-on / agent-workflow / java-code-style / java-testing） |
| 3 | Wiki 层 --- 编码规范与参考资料 | 建立人机共读的知识库，提供详细规范和模板 | docs/conventions/ 6 文件 + docs/reference/ 4 文件 + docs/design/_template.md |
| 4 | Skills 层 --- AI 操作手册 | 编写 AI Agent 的分步操作手册，连接 Rules 与 Wiki | .qoder/skills/ 8 文件（prd-to-code / flow-orchestration / design-review / add-* / doc-gardening / auto-governance） |
| 5 | Changes 层 --- 变更管理与迭代规划 | 建立变更管理机制，确保产出可追溯、可审查 | docs/changes/ 3 文件 + docs/plans/ 2 文件 + CHANGELOG.md |
| 6 | 总指南 + 自动化层 | 全局编织四层文档，建立 Linter 自动拦截和自动化治理 | docs/ai-coding-guide.md + build/linter/ 2 文件 + build/automation/scripts/ 6 文件 |
四层体系架构图
┌─────────────────────────────────────────────────────────┐
│ AGENTS.md │
│ 项目入口 · 技术栈基线 · 快速导航 │
├──────────────┬───────────────┬──────────────────────────┤
│ Rules 层 │ Skills 层 │ Wiki 层 (docs/) │
│ 硬性约束 │ 操作手册 │ 知识库 │
│ .qoder/ │ .qoder/ │ docs/ │
│ rules/ │ skills/ │ │
├──────────────┴───────────────┴──────────────────────────┤
│ Changes 层 (docs/changes/) │
│ 变更管理 · 影响分析 · PR 自检 │
├──────────────────────────────────────────────────────────┤
│ 自动化层 (build/) │
│ Linter 规则 · 治理脚本 · 客观数据采集 │
└──────────────────────────────────────────────────────────┘2. Harness Engineering 体系搭建流程
2.1 六步搭建顺序
搭建过程严格按序进行，每一步以前序产出为输入：
Step 1: 项目入口与架构基线（6 文件）
│ 定义"项目是什么"和"模块怎么分层"
│
▼
Step 2: Rules 层 --- 硬性约束（4 文件）
│ 将架构基线转化为"不可逾越的红线"
│
▼
Step 3: Wiki 层 --- 编码规范与参考资料（11 文件）
│ Rules 层的"详细展开版"，提供更丰富的上下文
│
▼
Step 4: Skills 层 --- AI 操作手册（8 文件）
│ 连接 Rules（约束）和 Wiki（知识），告诉 AI"具体怎么做"
│
▼
Step 5: Changes 层 --- 变更管理与迭代规划（6 文件）
│ 为 AI 产出建立质量保障机制
│
▼
Step 6: 总指南 + 自动化层（9 文件）
全局编织 + Linter 自动拦截 + 自动化治理闭环2.2 各步骤产出文件统计
| 步骤 | 产出文件数 | 关键文件 |
|---|---|---|
| Step 1 | 6 | AGENTS.md、overview.md、boundaries.md、data-flow.md、code-assets.md |
| Step 2 | 4 | always-on.md（13 条硬约束）、agent-workflow.md（7 步流程+门禁） |
| Step 3 | 11 | prd-template.md（Part A/B 分层）、_template.md（设计模板）、6 个 conventions |
| Step 4 | 8 | prd-to-code.md（主技能 7 步）、design-review.md（7 维度评审） |
| Step 5 | 6 | pr-checklist.md（6 维度自检）、impact-analysis.md、CHANGELOG.md |
| Step 6 | 9 | ai-coding-guide.md（全局索引）、pmd/checkstyle/ArchUnit、6 个 .ps1 脚本 |
| 合计 | ~44 | 含 6 篇搭建指南 |
2.3 步骤间的衔接关系
| 前序步骤 | 衔接内容 | 后续步骤 |
|---|---|---|
| Step 1 → Step 2 | boundaries.md 依赖方向图 → always-on.md §2 模块依赖方向 | Rules 层 |
| Step 1 → Step 2 | overview.md 技术栈表 → always-on.md §1 技术栈锁定 | Rules 层 |
| Step 2 → Step 3 | java-code-style.md 命名规则 → naming.md 详细命名表 | Wiki 层 |
| Step 2 → Step 3 | java-testing.md 测试规则 → testing.md 测试实践指南 | Wiki 层 |
| Step 3 → Step 4 | prd-template.md → 被 prd-to-code.md Step 1 加载 | Skills 层 |
| Step 3 → Step 4 | _template.md → 被 prd-to-code.md Step 3 加载 | Skills 层 |
| Step 4 → Step 5 | prd-to-code.md Step 2 → 加载 impact-analysis.md | Changes 层 |
| Step 4 → Step 5 | prd-to-code.md Step 7 → 加载 pr-checklist.md | Changes 层 |
| Step 5 → Step 6 | pr-checklist.md 门禁检查 → 依赖 automation 脚本产出 | 自动化层 |
3. 搭建完成后的使用操作流程
3.1 日常开发：PRD 驱动一站式开发
搭建完成后，开发者只需提交 PRD，AI Agent 自动执行 7 步流程：
开发者 AI Agent 文档体系
│ │ │
│ 1. 提交 PRD（参照 prd-template.md） │
│ ───────────────────────────▶ │ │
│ │ 2. Step 0: 环境检查 + PRD 校验 │
│ │ 3. Step 1: PRD 解析（加载 AGENTS.md + prd-template.md）│
│ │ 4. Step 2: 影响分析（加载 boundaries.md + impact-analysis.md）│
│ │ 5. Step 3: 生成设计文档（加载 _template.md + data-flow.md）│
│ 6. 设计评审报告 + 设计摘要 │ │
│ ◀─────────────────────────── │ │
│ 7. 人工确认「通过」 │ │
│ ───────────────────────────▶ │ ← ⚠️ 人工确认门禁 │
│ │ 8. Step 5: 代码生成（自底向上，遵守全部 Rules）│
│ │ 9. Step 5.5: 编译验证（mvn test-compile）│
│ │ 10. Step 6: 文档同步（error-codes.md + api.spec.yaml + CHANGELOG.md）│
│ │ 11. Step 7: 自检（自动治理巡检 + PR 自检清单）│
│ 12. 自检结果 + 交付 │ │
│ ◀─────────────────────────── │ │3.2 三处人工门禁
体系设计了 3 处人工确认门禁，确保关键决策由人类把控：
| 门禁位置 | 触发条件 | 人工动作 |
|---|---|---|
| Step 4 设计评审 | 设计文档生成后 | 审阅评审报告，确认「通过」/「需要修改」/「重新设计」 |
| Step 6 Nacos 配置 | 配置项生成后 | 在 Nacos 控制台手动添加配置项 |
| Step 7.1 评分门禁 | 衰减评分 < 60 分 | 确认是否允许交付 |
3.3 其他常见操作
| 场景 | 触发方式 | 加载的 Skill |
|---|---|---|
| 新增供应商对接 | PRD 中包含新供应商 | add-vendor-adapter.md（8 步） |
| 新增数据库表 | PRD 中包含新数据模型 | add-entity-mapper.md（7 步） |
| 新增 API 接口 | PRD 中包含新接口 | add-api-endpoint.md |
| 文档健康度检查 | PR 提交后 | doc-gardening.md（5 维度扫描） |
| 交付前自动治理 | Step 7 自动触发 | auto-governance.md（5 步巡检） |
| 断点恢复 | 某步失败后 | flow-orchestration.md（恢复机制） |
4. 搭建完成后的作用和效果
4.1 对 AI Agent 的约束效果
| 约束维度 | 没有 Harness | 有 Harness |
|---|---|---|
| JSON 库选择 | AI 可能用 Jackson | AI 必须用 FastJSON |
| 数据库访问 | AI 可能直接注入 Mapper | AI 必须用 DalManager.of() |
| 事务管理 | AI 可能用 @Transactional | AI 必须用 TransactionTemplate |
| 日志方式 | AI 可能用 LoggerFactory | AI 必须用 @Slf4j + 占位符 |
| 模块依赖 | AI 可能产生反向依赖 | AI 必须遵守依赖方向（ArchUnit 验证） |
| 开发流程 | AI 收到需求直接写代码 | AI 按 7 步流程执行，禁止跳步 |
| 代码质量 | 无客观验证 | 编译验证 + 测试执行 + Linter 拦截 |
4.2 对开发团队的效率提升
| 效率维度 | 提升 | 说明 |
|---|---|---|
| 需求到代码 | 从"人工编码"到"AI 生成 + 人工评审" | 开发者只需提交 PRD 和确认设计评审 |
| 代码规范 | 从"口头约定"到"Rules + Linter 强制" | 34 条 Linter 规则自动拦截 |
| 文档同步 | 从"经常遗漏"到"Step 6 强制同步" | error-codes.md / api.spec.yaml / CHANGELOG.md 自动更新 |
| 代码审查 | 从"全量人工"到"自动门禁 + 人工聚焦" | 自动化层处理编译/测试/风格，人工聚焦架构和业务逻辑 |
| 知识传承 | 从"口口相传"到"文档体系化" | 新成员读 AGENTS.md 即可了解项目全貌 |
4.3 对项目质量的保障效果
| 质量维度 | 保障机制 | 效果 |
|---|---|---|
| 架构合规 | Rules 层 + ArchUnit 架构测试 | 依赖方向不可逆，防止架构腐化 |
| 代码规范 | Rules 层 + PMD/Checkstyle Linter | 34 条规则自动拦截，CI 强制验证 |
| 测试覆盖 | java-testing.md 规则 + Step 7 自动执行 | 单元测试覆盖率 ≥ 95%，三分类（单元/集成/架构） |
| 文档一致性 | index-sync-check.ps1 + 文档全景索引 | 磁盘文件与索引一一对应，防止文档漂移 |
| 变更可追溯 | impact-analysis.md + CHANGELOG.md + pr-checklist.md | 每次变更可回答"为什么变、变了什么、影响了什么" |
| 文档健康度 | decay-detector.ps1 + doc-gardening.md | 自动检测过期(>90天)/orphan/索引不一致 |
5. 其他方面的好处
5.1 团队协作提升
| 好处 | 说明 |
|---|---|
| 统一语言 | AGENTS.md + conventions/ 为团队提供统一的术语和规范，减少沟通成本 |
| 角色分明 | Rules 约束 AI、Skills 指导 AI、Wiki 服务人机、Changes 管理变更，各层职责清晰 |
| 新人快速上手 | 新成员阅读 AGENTS.md 快速导航表即可了解项目全貌，无需口口相传 |
| 迭代可视 | current-sprint.md 和 backlog.md 让团队随时了解迭代进度和技术债务 |
5.2 知识资产沉淀
| 好处 | 说明 |
|---|---|
| 架构决策可追溯 | boundaries.md 记录模块边界决策，code-assets.md 记录基类复用决策 |
| 规范文档化 | 6 个 conventions 文件将团队约定从"口头"变为"文档"，避免规范随人员流动而丢失 |
| PRD 标准化 | prd-template.md Part A/B 分层让业务需求与技术实现解耦，业务人员可独立填写 Part A |
| 设计文档标准化 | _template.md 18 项自检清单确保每个设计文档覆盖全部规则 |
5.3 可移植与可复制
| 好处 | 说明 |
|---|---|
| 方法论可移植 | 6 篇搭建指南是方法论，可复制到其他 Java 项目（调整技术栈和模块名即可） |
| 模板可复用 | prd-template.md、_template.md 可直接复用，只需调整项目特定内容 |
| Linter 规则可移植 | pmd-exchange-ruleset.xml 和 checkstyle-exchange.xml 可作为其他项目的基础 |
| 自动化脚本可移植 | 6 个 PowerShell 脚本与项目耦合度低，稍作修改即可复用 |
5.4 持续演进能力
| 好处 | 说明 |
|---|---|
| 自动衰减检测 | decay-detector.ps1 定期检测文档过期和代码-文档漂移，防止知识库腐化 |
| 持续治理报告 | governance-report.ps1 汇总客观数据生成治理报告，为团队改进提供数据支撑 |
| 规则可扩展 | 新增规则只需在 always-on.md 添加条目 + 在 Linter 配置中映射，体系自动适配 |
| Skill 可扩展 | 新增开发场景只需在 .qoder/skills/ 添加 Skill 文件并在 AGENTS.md 注册 |
6. 快速开始
6.1 如果你的项目还没有 Harness 体系
按 Step 1 → Step 6 顺序阅读搭建指南，逐步创建文件。每步完成后运行该步的"完成验证清单"确认。
6.2 如果你的项目已有 Harness 体系
- 日常开发 ：参照 ai-coding-guide.md §3 PRD 驱动开发全链路
- 查规则 ：参照 .qoder/rules/always-on.md 13 条硬约束
- 查流程 ：参照 .qoder/rules/agent-workflow.md 7 步流程
- 查索引 ：参照 ai-coding-guide.md §5 文档全景索引
- 查搭建过程：阅读本系列 6 篇指南了解每步的设计意图
6.3 系列文档导航
| 步骤 | 文档 | 建议阅读时间 |
|---|---|---|
| Step 1 | 项目入口与架构基线 | 15 min |
| Step 2 | Rules 层 --- 硬性约束体系 | 20 min |
| Step 3 | Wiki 层 --- 编码规范与参考资料 | 20 min |
| Step 4 | Skills 层 --- AI 操作手册 | 20 min |
| Step 5 | Changes 层 --- 变更管理与迭代规划 | 15 min |
| Step 6 | 总指南 + 自动化层 | 25 min |