概述
系列定位：本系列共 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 体系
6.3 系列文档导航
0
0
已为社区贡献4条内容
所有评论(0)