Anthropic 近期发布的 Claude Code 正在重新定义 Coding Agent 的边界 - 它不再是一个「编码助手」，而是一个把环境设计、知识管理和渐进式披露做到极致的工程操作系统。这套设计理念恰好印证了 OpenAI Harness Engineering 的核心主张：环境 > 模型，知识进版本库 > 对话记忆。

核心架构：CLAUDE.md 四层知识体系

Claude Code 的知识管理不是靠对话记忆（那太不可靠了），而是靠一套分层的 Markdown 文件体系。这套设计的核心洞察是：好的 Agent 不需要记住你说了什么，它需要在每次启动时自动获取正确的上下文。

四层文件架构

  • Organization CLAUDE.md（/etc/claude-code/）：组织级标准，IT/DevOps 管理，覆盖编码规范、安全策略、合规要求
  • Project CLAUDE.md（./CLAUDE.md）：项目级指令，入版本库，团队共享 - 架构决策、构建命令、测试约定
  • User CLAUDE.md（~/.claude/CLAUDE.md）：个人偏好，所有项目通用 - 代码风格、工具快捷方式
  • Local CLAUDE.md（./CLAUDE.local.md）：个人项目偏好，不入版本库 - 沙箱地址、测试数据偏好

AGENTS.md 的跨工具兼容

Claude Code 原生读的是 CLAUDE.md，但如果你的仓库已经有 AGENTS.md（给其他 Coding Agent 用的），可以用 @import 语法桥接。一份 AGENTS.md 可以同时被 Claude Code、Gemini CLI、Copilot Agent 读取 - 知识入版本库，多工具共享，这是 Harness Engineering 的核心主张之一。

关键设计模式一：渐进式披露

CLAUDE.md 不是越详细越好，而是有严格的约束：每个文件建议 200 行以内，超过就拆分。同时支持 .claude/rules/ 目录做模块化组织，还支持 frontmatter 条件加载 - 只在操作特定路径的文件时才把对应规则注入上下文。

设计洞察：渐进式披露不是「给 Agent 少一点信息」，而是「在正确的时机给正确的信息」。这和 SWE-CI 论文的 feedback harness 设计理念完全一致 - 不是把所有 CI 输出都丢给 Agent，而是做结构化过滤和条件加载。

关键设计模式二：环境作为约束

Claude Code 的最佳实践里反复强调一个理念：给 Agent 验证自己工作的能力（linter、测试套件、截图对比）。这不是「让 Agent 跑测试」这么简单，而是把环境本身变成护栏 - Agent 每次修改后可以自检，不需要人类当唯一的反馈回路。

具体实践：构建命令写进 CLAUDE.md（npm test、cargo build），Linter 作为 pre-commit hook，UI 改动用截图对比验证，错误信息要求定位根因不是临时 hack。

Harness Engineering 对应原则：「黄金原则编码」- 把团队的编码规范、测试要求、安全检查点直接编码进 Agent 的环境约束里，而不是靠 prompt 嘱咐「记得写测试」。prompt 会忘，环境约束不会。

关键设计模式三：Plan Mode 的四阶段工作流

Claude Code 推荐的工作流：1) Explore：Plan Mode 下只读文件，理解上下文；2) Plan：生成详细实施方案；3) Implement：切回 Normal Mode，按计划编码 + 自动验证；4) Commit：自动生成描述性 commit message + 创建 PR。

这和 TDAD（Test-Driven Agent Development）的思路高度一致 - 先探索、规划、再编码，而不是让 Agent 跳过规划直接动手。Plan Mode 的价值在于：它强制把「理解问题」和「解决问题」分开，避免 Agent 解决了错误的问题。

关键设计模式四：Auto Memory（自动记忆）

除了人工编写的 CLAUDE.md，Claude Code 还有 Auto Memory 机制 - Agent 在纠正中学到的偏好会自动写入笔记，每次新 session 自动加载。这是「Agent 自学习」的雏形：不是靠 fine-tuning，而是靠结构化的记忆文件。

但 Auto Memory 有严格的边界：每棵工作树独立，上限 200 行/25KB，防止记忆膨胀。这和经典的 MEMORY.md + daily memory 分层设计异曲同工 - 长期记忆要精炼，短期记忆自动滚动。

对工程实践的启示

  1. 知识入版本库，不靠对话记忆：CLAUDE.md 进 git，团队共享，版本管理。这比每次 session 都重新解释架构可靠一万倍。
  2. 环境做护栏，不做保姆：linter、测试、截图对比 - 让环境告诉 Agent「错了」，而不是人类来判断。这是 Harness Engineering 的核心：设计好的约束环境，比训练更大的模型更有效。
  3. 分层加载，条件注入：200 行上限 + frontmatter 条件规则 + 目录层级继承。不是一股脑把所有信息塞给 Agent，而是按需加载。这和 SWE-CI 的 structured feedback 设计完全一致。
  4. 跨工具标准化：AGENTS.md 可以同时被 Claude Code、Gemini CLI 等工具读取。一份知识，多工具复用 - 这正是 Harness Engineering 提出的「知识进版本库」愿景。

相关阅读

  • Claude Code Memory 官方文档：https://code.claude.com/docs/en/memory
  • Claude Code Best Practices：https://code.claude.com/docs/en/best-practices
  • SWE-CI 论文（阿里+中大）：Agentic Harness for Real-World Compilers
  • TDAD（Test-Driven Agent Development）：环境反馈的质量决定 Agent 的上限

逍遥云初 | 2026.04.08