Harness Engineering
核心理念
Harness Engineering 的本质是为 AI Agent 构建可靠的"运行环境"——不是优化模型本身, 而是通过系统级工具链解决模型在真实环境中的状态管理、工具调用、任务漂移、结果验证等问题。 当 Agent 表现不佳时,优先审视环境支持是否充分,而非归咎于模型能力不足。
路由与编排
收到用户消息后,按以下顺序判定路由目标,必须读取对应子 skill 的 SKILL.md 再执行:
- 匹配维护类触发词 →
harness-gardening - 匹配生成类触发词(或默认) →
harness-generating - 无法判定 → 询问用户意图(生成规范 / 文档巡检)
| 路由目标 | 触发词(示例) | 调用方式 |
|---|---|---|
| 生成 | "生成 Harness 规范"、"AI 治理规范"、"修改架构约束"、"生成词汇表"、"生成开发地图" | harness-generating(mode=full 或 targeted) |
| 维护 | "文档园艺"、"文档巡检"、"检查文档一致性"、"harness gardening"、"扫描文档"、"更新开发地图" | harness-gardening |
harness-generating(生成类)
读取 harness-generating/SKILL.md,传入 mode(full / interactive / targeted)、target(定向修正时,如 context-engineering)、workspace_root。
| mode | 判定条件 |
|---|---|
full |
"生成 Harness 规范"、"创建 Agent 环境文档"、首次使用 |
interactive |
用户信息不足以生成完整规范 |
targeted |
指定修改某个组件,如"生成开发地图"(target=dev-map) |
harness-gardening(维护类)
读取 harness-gardening/SKILL.md,传入 mode(pr / full / targeted)、target(targeted 时必填)、workspace_root。
| mode | 判定条件 |
|---|---|
pr |
commit 后 hook / 用户指定轻量检查 |
full |
"文档巡检"、"检查文档一致性" / 默认全量扫描 |
targeted |
指定检查某个组件,如"更新开发地图"(target=dev-map)、"检查词汇表"(target=glossary) |
参考资源
| 文件 | 用途 | 读取方 |
|---|---|---|
harness-generating/SKILL.md |
规范文档生成流程(含 dev map) | 父 skill(生成类路由) |
harness-gardening/SKILL.md |
文档一致性巡检流程(含项目记忆等维度) | 父 skill(维护类路由) |
references/project-type-detection.md |
项目类型识别与 Skill 安装根检测 | 两个子 skill(执行前必读) |
references/skill-install-root.md |
Skill 安装根探测与推荐布局 | generating / doctor / 文档表述 |
references/agents-merge.md |
根 AGENTS 先理解再合并(保留项目记忆) | generating 第三步;gardening 记忆维度 |
references/agents-work-units.md |
工作单元 **/AGENTS.md 发现与根索引 |
generating 写根前;gardening 维度 12 |
references/project-owned-tools.md |
项目自有工具(git 跟踪 ∩ 安装布局,含 monorepo 子树) | tooling 分节;doctor 必查 |
scripts/harness-doctor.sh |
运行时探活(stdout,不入库) | generating 第一步;人工排查 |
references/tool-dependencies.md |
Agent 工具依赖权威清单 | generating(环境检查);gardening(维度 7) |
references/best-practices.md |
五大组件最佳实践详解 | 子 skill(生成/修复时) |
assets/ |
文档模板、dev-map.gitignore、技术规范预设库 |
子 skill(生成流程中) |
scripts/detect-standards.sh |
monorepo 技术栈 Level-1 探测(R2) | generating 第三步-B |