任务专用 Agent harness 五层搭法，不再持续往 CLAUDE.md 堆砌规则

任务专用 Agent harness 五层搭法的核心思路就是把规则、能力、校验、权限、观测拆成独立五层，不要把所有约束、流程、技能全部塞进 CLAUDE.md，CLAUDE.md 只保留少量全局基础约定，其余逻辑放到对应分层按需加载，避免上下文臃肿、token 浪费、模型忽略大量规则。很多开发者踩坑，习惯不断追加文本到 CLAUDE.md，文件越长，模型越容易漏掉后半段规则，还会拉高每次请求的 token 开销，缓存也容易失效；五层架构就是把固定全局约定、可复用技能、生命周期钩子、子代理编排、可观测校验分开管理，每层各司其职，只有任务需要的时候才加载对应内容，实现轻量化、可控、可调试的 Agent 运行底座，整套搭法落地之后，新增任务能力不用改 CLAUDE.md，只需要新增技能或者配置钩子、子代理。

一、五层架构每层职责说明

二、五层搭法落地步骤

1. 精简 CLAUDE.md：清理冗余内容，只保留全项目通用、每次会话都必须知道的基础约定，控制篇幅，不要持续追加规则。
2. 把任务流程、专项业务规则抽成独立 Skill 文件，按任务分类，支持按需检索调用。
3. 安全、强制校验类逻辑迁移到 Hook，绑定工具调用、文件修改、执行命令等生命周期事件，由运行时强制拦截，不靠模型自觉遵守。
4. 复杂、隔离的子任务封装成 Subagent，分配独立工具集和上下文，避免主会话信息污染。
5. 配置观测和验收闸门，记录每一步动作日志，设置验收条件，不达标就自动重试或者上报人工审核。

三、这种搭法对比全堆 CLAUDE.md 的优势

• 上下文 token 更低，缓存命中率更高，调用成本下降
• 规则不会因为文件太长被模型遗忘，强制校验交给钩子执行，稳定性更强
• 新增任务能力不用修改 CLAUDE.md，增量维护更简单
• 问题定位清晰，是约定、技能、钩子还是子代理出问题，分层排查
• 权限隔离，子代理可以分配最小可用工具，降低风险

【相关 FAQ】

问题 1：任务专用 Agent harness 五层搭法里，CLAUDE.md 还适合放哪些内容？

回答 1：任务专用 Agent harness 五层搭法里，CLAUDE.md 只放全局长期不变的基础约定，比如项目目录结构、基础编码规范、固定构建命令，专项流程、校验规则、复杂任务步骤都不能继续往 CLAUDE.md 里增加。

问题 2：任务专用 Agent harness 五层搭法，Skill 技能层和 Hook 钩子层有什么区别？

回答 2：任务专用 Agent harness 五层搭法里，Skill 技能层是任务流程、操作知识，需要模型主动调用读取；Hook 钩子层是运行时自动触发的强制拦截、校验逻辑，不需要模型主动阅读，独立执行安全管控。

问题 3：任务专用 Agent harness 五层搭法，子代理编排层适合用来解决什么场景？

回答 3：任务专用 Agent harness 五层搭法，子代理编排层适合处理独立复杂子任务，比如依赖审计、日志检索、自动化测试，子代理拥有独立上下文，执行细节不会污染主会话，只返回最终结论。

问题 4：任务专用 Agent harness 五层搭法，为什么不建议持续往 CLAUDE.md 追加规则？

回答 4：任务专用 Agent harness 五层搭法不建议持续往 CLAUDE.md 追加规则，因为 CLAUDE.md 全程加载，内容越多 token 开销越高，模型容易忽略长文本后面的规则，同时频繁修改会破坏缓存，Agent 稳定性下降。

【参考资料】

[2026-06-18]（Steering Claude Code: when to use CLAUDE.md, skills, hooks, and subagents）Anthropic 官方

[2026-05-19]（Standardise the Harness, Customise the Work: The 5-Layer Agent Architecture）Fractional Futurist

[2026-04-29]（2026 Agent Harness 实战：工具越少越准模型见顶，Harness 接棒）稀土掘金

[2026-04-01]（Harness Engineering: 基于 Claude Code 的完全指南）博客园

[2026-04-02]（Agent Harness Design: 3 Patterns for Harnessing Claude's Intelligence）Claude

【免责声明】

本文仅整理 Agent harness 五层架构的工程实践思路，不构成生产环境上线方案；不同 Agent 框架、Claude Code 版本对 Skill、Hook、子代理的支持能力存在差异；架构落地效果受 prompt 缓存策略、工具权限配置、任务复杂度影响，上线前建议做小范围评估验证。