# HumanLayer: Skill Issue — Harness Engineering for Coding Agents

> 原文链接：https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents
> 作者/来源：HumanLayer
> 阅读日期：2026-04-02

## 一句话总结
HumanLayer 认为 coding agent 的失败主要源于**配置问题而非模型局限**——"模型可能没问题，这只是一个技能问题（skill issue）"，并系统梳理了 harness 的六大配置杠杆。

## 核心论点
文章的核心论点极具挑衅性：**不要等待更好的 AI 模型，而是优化你的 agent harness**。大多数 coding agent 的失败不是因为模型不够聪明，而是因为工程师没有正确配置运行环境。这与标题"skill issue"的双关语相呼应——既指 agent 的"技能"问题，也暗示是工程师的"技能"问题。

文章延续了 "coding agent = AI model(s) + harness" 的基本公式，将 harness 的配置面分解为六大杠杆：CLAUDE.md/AGENTS.md 文件、MCP Servers、Skills、Sub-Agents、Hooks 和 Back-Pressure Mechanisms。每个杠杆都有具体的最佳实践和反模式。

文章还引用了 ETH Zurich 的研究，证明 **LLM 生成的 agent 配置文件反而会损害性能，同时多消耗20%的 token**。Chroma 的 context rot 研究则表明，性能随 context 长度增加而显著退化，尤其当查询与 context 之间的语义相似度低时。这些研究为"少即是多"的配置哲学提供了实证支持。

## 关键概念
- **Configuration Surface（配置面）**：agent 性能的主要调优空间不在模型层，而在包围模型的 harness 配置——system prompt、tools、sub-agents、skills 和验证机制。
- **Progressive Disclosure（渐进式披露）**：不在启动时加载所有工具和知识，而是在需要时才激活。CLAUDE.md 应控制在60行以内，避免信息过载。
- **Context Firewall（context 防火墙）**：通过 sub-agent 将离散任务隔离，防止中间噪声在父线程中积累。这既维护了连贯性，又节约了 context 空间。
- **Back-Pressure（反压机制）**：测试、类型检查和覆盖率报告作为 agent 自我验证的机制。关键要求：**必须 context 高效——抑制冗余输出**。
- **Hooks（钩子）**：自动化验证机制，在成功时静默运行、仅在出错时暴露信息。这体现了"异常导向"的反馈设计。
- **Skill Issue（技能问题）**：文章标题的双关语——agent 的性能问题本质上是工程师配置 harness 的技能问题。

## 实践建议
1. **CLAUDE.md 保持精简（60行以内）**：避免自动生成，手动精心编写。过长的配置文件反而降低性能并增加 token 消耗。
2. **从简单开始，仅在失败时添加配置**：预先设计"理想"配置是一个反模式。让实际失败驱动配置的演进。
3. **控制工具数量**：不要"以防万一"安装大量工具。过多工具会将 agent 推向更差的表现。仅连接可信的 MCP server。
4. **使用 sub-agent 创建 context 防火墙**：为离散子任务创建独立的 agent 上下文，防止噪声积累，并可以使用更便宜的模型。
5. **优化迭代速度而非单次成功率**：不要在每次变更后运行完整测试套件，而是设计快速反馈循环。
6. **将经过实战检验的配置在团队内分发**：好的 harness 配置是可复用的团队资产。

## 独到观点
这篇文章最独特的贡献在于**引用了学术研究来支持实践建议**。ETH Zurich 关于 LLM 生成配置文件损害性能的研究是一个反直觉但重要的发现——这意味着让 AI 自己写配置不如人类手动编写。此外，"context firewall" 概念虽然本质上就是 sub-agent 隔离，但这个命名更加形象地传达了其价值。文章还提供了最具体的"失败模式→教训"映射（什么不管用 vs 什么管用），对于刚开始实践的工程师非常有指导价值。

## 与其他文章的关联
- "模型没问题，是配置问题"的观点与 [OpenAI: Harness Engineering](01-openai-harness-engineering.md) 中"环境设计比模型更重要"的理念高度一致。
- Progressive disclosure 与 [LangChain: Anatomy of Harness](04-langchain-anatomy-of-harness.md) 中的 "progressive skill disclosure" 概念相同。
- Context firewall 与 [Anthropic: Building Effective Agents](06-anthropic-building-effective-agents.md) 中 orchestrator-workers 模式的关注点分离相关。
- Back-pressure 机制与 [OpenAI](01-openai-harness-engineering.md) 中的 mechanical enforcement 和 feedback loops 对应。
- CLAUDE.md 精简原则与 OpenAI 的 AGENTS.md（约100行索引文件）理念一致。
- 与 [HumanLayer: Advanced Context](12-humanlayer-advanced-context.md) 是同一来源的系列文章，本文侧重 harness 配置，后者侧重 context 优化。