概述系列定位本系列共 6 篇搭建指南 1 篇总览指导从零搭建 Harness Engineering 四层文档体系最终实现从 BRD/PRD 到代码交付的一站式 AI 开发与自检闭环。本篇定位 6 篇搭建指南的总览通过本篇文章对搭建Harness Engineering 有一个整体的了解和概括1. 系列文档作用说明序号文档定位核心产出1项目入口与架构基线建立 AI Agent 的第一印象和架构知识底座AGENTS.md、README.md、architecture/ 4 文件2Rules 层 — 硬性约束体系将架构基线转化为 AI 必须遵守的硬性规则.qoder/rules/ 4 文件always-on / agent-workflow / java-code-style / java-testing3Wiki 层 — 编码规范与参考资料建立人机共读的知识库提供详细规范和模板docs/conventions/ 6 文件 docs/reference/ 4 文件 docs/design/_template.md4Skills 层 — AI 操作手册编写 AI Agent 的分步操作手册连接 Rules 与 Wiki.qoder/skills/ 8 文件prd-to-code / flow-orchestration / design-review / add-* / doc-gardening / auto-governance5Changes 层 — 变更管理与迭代规划建立变更管理机制确保产出可追溯、可审查docs/changes/ 3 文件 docs/plans/ 2 文件 CHANGELOG.md6总指南 自动化层全局编织四层文档建立 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 16AGENTS.md、overview.md、boundaries.md、data-flow.md、code-assets.mdStep 24always-on.md13 条硬约束、agent-workflow.md7 步流程门禁Step 311prd-template.mdPart A/B 分层、_template.md设计模板、6 个 conventionsStep 48prd-to-code.md主技能 7 步、design-review.md7 维度评审Step 56pr-checklist.md6 维度自检、impact-analysis.md、CHANGELOG.mdStep 69ai-coding-guide.md全局索引、pmd/checkstyle/ArchUnit、6 个 .ps1 脚本合计~44含 6 篇搭建指南2.3 步骤间的衔接关系前序步骤衔接内容后续步骤Step 1 → Step 2boundaries.md 依赖方向图 → always-on.md §2 模块依赖方向Rules 层Step 1 → Step 2overview.md 技术栈表 → always-on.md §1 技术栈锁定Rules 层Step 2 → Step 3java-code-style.md 命名规则 → naming.md 详细命名表Wiki 层Step 2 → Step 3java-testing.md 测试规则 → testing.md 测试实践指南Wiki 层Step 3 → Step 4prd-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 5prd-to-code.md Step 2 → 加载 impact-analysis.mdChanges 层Step 4 → Step 5prd-to-code.md Step 7 → 加载 pr-checklist.mdChanges 层Step 5 → Step 6pr-checklist.md 门禁检查 → 依赖 automation 脚本产出自动化层3. 搭建完成后的使用操作流程3.1 日常开发PRD 驱动一站式开发搭建完成后开发者只需提交 PRDAI 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 >3.2 三处人工门禁体系设计了 3 处人工确认门禁确保关键决策由人类把控门禁位置触发条件人工动作Step 4 设计评审设计文档生成后审阅评审报告确认「通过」/「需要修改」/「重新设计」Step 6 Nacos 配置配置项生成后在 Nacos 控制台手动添加配置项Step 7.1 评分门禁衰减评分 60 分确认是否允许交付3.3 其他常见操作场景触发方式加载的 Skill新增供应商对接PRD 中包含新供应商add-vendor-adapter.md8 步新增数据库表PRD 中包含新数据模型add-entity-mapper.md7 步新增 API 接口PRD 中包含新接口add-api-endpoint.md文档健康度检查PR 提交后doc-gardening.md5 维度扫描交付前自动治理Step 7 自动触发auto-governance.md5 步巡检断点恢复某步失败后flow-orchestration.md恢复机制4. 搭建完成后的作用和效果4.1 对 AI Agent 的约束效果约束维度没有 Harness有 HarnessJSON 库选择AI 可能用 JacksonAI 必须用 FastJSON数据库访问AI 可能直接注入 MapperAI 必须用 DalManager.of()事务管理AI 可能用 TransactionalAI 必须用 TransactionTemplate日志方式AI 可能用 LoggerFactoryAI 必须用 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 Linter34 条规则自动拦截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 minStep 2Rules 层 — 硬性约束体系20 minStep 3Wiki 层 — 编码规范与参考资料20 minStep 4Skills 层 — AI 操作手册20 minStep 5Changes 层 — 变更管理与迭代规划15 minStep 6总指南 自动化层25 min