• 简体中文

    • Harness 反模式与修复指南

    反模式 1：过度膨胀的 CLAUDE.md

    症状：规则超过 100 行；Claude 开始忽略其中部分规则 原因：把所有约定都塞进一个文件，把「应该遵守」和「必须执行」混在一起 修复：

    • 删减至 <60 行
    • Claude 已正确执行的规则直接删除（减少 Token 消耗）
    • 复杂规则移入 Hook（确定性强制）
    • 详细说明移入 docs/ 子目录，CLAUDE.md 中用链接指向

    诊断问题：每条规则问自己——「如果删掉这条，Agent 会犯错吗？最近 4 周犯过吗？」

    反模式 2：滥用 MCP

    症状：接入 20+ MCP Server；Agent 经常选错工具；基线 Token 消耗过高 原因：每个工具都用 MCP 接入，包括 Agent 已有内置知识的工具（每个 MCP Server 约注入 3000-9000 Token） 修复：

    • 每个工具接入前问「这个任务没它能完成吗？」
    • 模型已知的 CLI（git, npm, docker, gh）直接用 CLI
    • 只用 3 个操作的工具 → 写 CLI 封装 + CLAUDE.md 说明（约 100 Token）
    • 用 20+ 操作的工具 → 才用 MCP Server

    反模式 3：全量测试输出

    症状：测试成功时输出 4000 行日志；Agent 开始讨论测试文件而非继续任务 原因：Hook 中没有处理成功的静默逻辑，或直接把 pnpm test 输出传给 Agent 修复：

    # 错误做法
TEST_OUTPUT=$(pnpm test 2>&1)
echo "$TEST_OUTPUT"  # 把 4000 行日志全部输出

# 正确做法
TEST_OUTPUT=$(pnpm test 2>&1)
if [ $? -ne 0 ]; then
  echo "测试失败：" >&2
  echo "$TEST_OUTPUT" | head -50 >&2
  exit 2
fi
# 成功 = 完全静默，不输出任何内容

    反模式 4：过度定制 Subagent

    症状：为每类任务定义 Specialist；Agent 无法整体推理跨域变更；修改 API 端点时不知道对所有下游消费者的影响 原因：Lead-Specialist 架构过于刚性，Specialist 只能看到自己的上下文 修复：

    • 改用 Master-Clone 架构（主 Agent 用 Task(...) 克隆自身）
    • 克隆的 Agent 包含全量 CLAUDE.md，可跨域推理
    • 只在需要权限隔离的安全敏感任务时使用预定义 Specialist

    反模式 5：「巨型」单会话

    症状：一个会话处理 10+ 功能；上下文超 100k 后输出质量下滑；Agent 开始过早宣布「已完成」 原因：上下文焦虑——模型在接近上下文限制时学会了「整理并收尾」的行为 修复：

    • 每个功能一个会话
    • 用 /harness:dump 保存进度到 claude-progress.json
    • 新会话启动时读取进度文件重建状态
    • 「上下文重置 > 上下文压缩」——新 Agent 没有「已工作很久」的感知

    反模式 6：依赖 Compaction 保持记忆

    症状：跨窗口时 Agent 开始猜测「上次做了什么」；长任务中期开始出现错误决策 原因：压缩是把较早的对话历史摘要化，但 Agent 仍然「知道」自己已工作很久，焦虑状态持续存在 修复：

    • 改用结构化进度文件（claude-progress.json）
    • Agent 启动时主动读取进度文件，而不是依赖对话历史
    • 进度文件用 JSON 格式，Agent 对结构化数据的尊重程度显著高于纯文本

    反模式 7：所有约定放 CLAUDE.md

    症状：「必须」的行为放 CLAUDE.md，但被偶尔忽略；关键质量检查依赖 Agent 的理解和判断 原因：混淆了软约束（引导）和硬约束（强制）的边界 修复：

    「必须执行，不论 Claude 判断如何」 → Hook（确定性强制）
「应该遵守，解释为什么」          → CLAUDE.md（引导性建议）
「确定的系统配置」                 → settings.json（不依赖 Agent 判断）

    三者协同才是完整防护：只有 CLAUDE.md 是软约束；只有 Hook 是硬约束但缺上下文；两者结合效果最佳。

    反模式 8：ADR 只写结论，不写被否决的选项

    症状：Agent 「好心」地把代码改成它认为更好的方式，破坏了当初刻意为之的设计 原因：ADR 只记录了「我们选了 Redis」，但没有记录「为什么不用 JWT」 修复：

    • ADR 必须列出所有被否决的选项及其原因
    • 「后果」部分用「❌ 禁止 X，必须走 Y」格式
    • 保留「已废弃」状态的 ADR，不要删除——让 Agent 知道「这条路走过、放弃了」

    反模式 9：初始化时制定过多规则

    症状：第一天就写满了 CLAUDE.md，但规则都是假设的，没有基于真实失败 原因：想一次性把所有情况都覆盖到 修复：

    • 先用两周时间在真实工作上运行 Agent，记录每次需要人工干预的情况
    • 围绕实际观察到的失败模式构建约束
    • 「先观察，再约束」——假设的失败模式比真实的失败模式代价更高

    来自旧金山工程领袖田野调查（2026.04）的核心建议：不要在第一天就标准化。先观察，再约束。