Harness Engineering（驾驭/护栏工程）是一套围绕自主AI Agent构建完整执行环境的工程方法论，不止局限于提示词与上下文优化，还包含标准化工具集、强约束规则、校验闭环、自我修正反馈机制，让AI智能体在生产环境稳定运行，大幅降低幻觉、逻辑错误、架构偏离问题。本文基于企业内部RAG+微调AI平台落地案例，完整拆解通过AGENTS.md、ARCHITECTURE及配套分层规范文档管控编码Agent的整套落地流程，形成可追溯、可审计、防幻觉的开发体系。
一、Harness Engineering核心定义与项目背景
Harness Engineering核心思路：为自主AI智能体搭建完整可控运行环境，通过标准化文档、强制架构约束、多层校验、反馈修正闭环，避免AI脱离项目规范自行发挥。本次落地项目为企业内部问答系统，依托OEM厂商白皮书、设备手册构建检索增强生成与微调能力，员工提问后系统返回带来源的专业回答，并根据用户反馈持续迭代优化，解决无依据幻觉、架构错乱、权限失控等痛点。
项目遵循OpenAI官方推荐的仓库目录规范，所有约束文档纳入版本管理，形成统一可信规则源，完整目录结构分为应用代码、分层规范文档、执行计划、配置资源四大模块：
- 根目录核心规范：AGENTS.md（Agent总行为纲领）、ARCHITECTURE.md（系统架构骨架）、CLAUDE.md（Claude Code专属引导）、Makefile；
- apps目录：前后端业务完整代码，分为API后端、Web前端；
- docs分层文档库：设计规范、产品需求、安全规则、执行计划、自动生成库、厂商参考资料；
- 辅助配置：skills-lock技能锁定文件、容器编排脚本。
整套体系下Agent不会随意变更技术栈、数据流向、权限校验逻辑，所有开发动作留有文档记录，每一轮修改均可追溯设计依据。阿里云部署AI Agent：OpenClaw/Hermes Agent全网最简单，只需两步，详情👉访问阿里云OpenClaw/Hermes一键部署专题页面了解。
Token Plan Token最便宜/支持多模型切换：👉访问订阅阿里云百炼Token Plan AI大模型服务 。支持多模型切换，用于多模态模型灵活调用，实现多模型、多工具、多场景下的额度共享与统一管理，兼顾灵活性、稳定性与安全性，大幅降低企业使用大模型的门槛与成本。
二、两大核心顶层规范文档作用解析
1. AGENTS.md：编码Agent唯一可信行为总纲
作为整个仓库Agent操作最高标准，所有AI编码工具（Claude Code、GitHub Copilot/Codex）启动时优先读取，明确三大核心信息：项目产品目标、完整仓库目录执行流程、每类操作的完成标准。
核心约束维度：
- 产品边界：仅企业内网访问，Ollama本地模型调度、RAG检索范围、权限体系、观测指标统一规定；
- 阅读顺序：强制Agent修改代码前先读取架构、产品、安全相关文档；
- 开发行为规则：优先小粒度可评审PR、需求模糊先记录假设、修改接口同步更新文档、所有数据边界强制校验；
- 交付验收标准：检索内容必须标注来源、权限全链路拦截、主/异常路径全覆盖测试、可观测指标完整埋点。
AGENTS.md统一跨工具标准，一份规范适配多款AI编码IDE，无需为不同工具单独维护规则。
2. ARCHITECTURE.md：系统固定架构骨架文档
专门定义完整数据流、分层依赖、技术栈、模型调度策略、数据安全边界，杜绝AI随意调整模块调用关系。
- 完整数据流链路：React前端→Python API服务→认证层→文档检索→LLM编排→本地Ollama模型集群；
- 分层强制依赖规则：types→config→repository→service→runtime→API，禁止反向循环依赖；
- 模型选型约束：区分问答、快速摘要、深度推理场景绑定固定模型版本，禁止随意切换大尺寸模型；
- 数据安全四大边界：不可信上传文档、检索文本、模型输出、外部接口全部强制校验；
- 基础设施统一规范：向量库、缓存、观测组件固定选型。
Agent开发任何功能前必须读取本文件，不会出现前后端交互逻辑混乱、模型调度不合理问题。
三、docs分层配套规范文档体系
仅依靠两份顶层文档无法覆盖安全、质量、产品细节，项目在docs目录拆分多份细分约束，实现按需加载，避免上下文冗余：
- DESIGN.md / FRONTEND.md：产品交互、UI组件、页面视图硬性规范；
- PRODUCT_SENSE.md：区分有效/无效AI输出，定义幻觉判定标准；
- QUALITY_SCORE.md：开发质量打分体系，无测试、无来源引用直接低分；
- SECURITY.md：JWT、RBAC、文档粒度权限、注入拦截完整安全规则；
- exec-plans执行计划目录：active存放待开发任务，完成后移入completed，遗留技术债务统一记录；
- generated目录：数据库表结构等自动生成文档，代码变更同步刷新；
- product-specs：后台、文档 ingestion等各模块产品详细需求。
开发时Agent只会读取当前任务对应的细分文档，不会一次性加载全部规则，节省上下文窗口，提升规则遵循率。
四、编码Agent完整标准化工作流
依托整套文档形成闭环开发流程，全程可审计：
1 读取前置规范：AGENTS.md→ARCHITECTURE.md→对应产品/安全/前端细分文档；
2 在exec-plans/active创建/更新本次执行计划，记录需求假设；
3 最小粒度实现功能，不做无关重构；
4 执行类型检查、单元测试、静态扫描；
5 本地API/页面手动验证效果；
6 自动刷新数据库等生成类文档；
7 在执行计划记录决策、遗留风险；
8 开发完成将计划归档至completed目录。
全程所有决策、修改点、风险全部写入文档，任何人查看仓库均可复现开发思路。
五、多IDE兼容适配方案
1 Claude Code适配
根目录CLAUDE.md作为工具专属引导，第一行强制读取AGENTS.md，限定开发流程，冲突时停止操作向开发者确认，不会擅自执行违规逻辑。
2 GitHub Copilot/Codex适配
在.github目录放置统一指令文件，VS Code开启指令文件读取开关，每次生成代码前自动加载顶层规范，限制架构与权限相关错误生成。
3 统一兼容原则
所有工具共用AGENTS.md一份总规则，通过软链接、目录映射实现复用，不维护多份冲突规范，降低团队维护成本。
六、防幻觉与生产安全核心设计
1 多层数据校验：上传文档、检索片段、模型返回、外部接口四层拦截，任何未校验数据不进入业务链路；
2 来源强制标注：所有AI回答必须绑定文档ID、段落索引，无检索素材需明确告知不确定性；
3 权限粒度管控：文档级RBAC，无访问权限的素材直接过滤，不会泄露涉密内容；
4 可观测全埋点：模型调用Trace、Token消耗、检索命中率、告警日志全部自动生成；
5 幻觉反馈闭环：用户反馈错误内容直接存入执行计划，同步更新规范文档，同类问题不再重复出现。
七、落地价值总结
1 架构可控：AI无法随意改动系统分层、数据流、模型选型，线上架构长期统一；
2 大幅减少幻觉：检索溯源、多层校验、文档约束三重机制，无依据输出显著下降；
3 开发可追溯：所有功能开发计划、决策、风险归档，代码评审效率大幅提升；
4 跨工具统一标准：一套AGENTS.md适配主流AI编码工具，团队规范统一；
5 安全合规：权限、注入、数据泄露风险提前拦截，满足企业内部数据管控要求。
整套Harness Engineering文档体系不依赖复杂平台，仅通过版本化Markdown文件即可搭建约束闭环，适合RAG、微调、本地模型调度等各类AI后台项目，是生产环境管控编码Agent的轻量化落地方案。
