Harness 五大组件 —— Context / 约束 / 编排 / 验证 / 观测

第 4 章我们介绍了 Harness Engineering 的核心思想。本章我们深入到组件层——Harness 由哪些具体组件构成，每个组件怎么设计。

我们先看一张完整的组件地图：

┌──────────────────────────────────────────────────────────────┐
│                      Harness 五大组件                          │
│                                                              │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐              │
│  │ Component1 │  │ Component2 │  │ Component3 │              │
│  │  Context   │  │ Constraint │  │Orchestration│              │
│  │  Manager   │  │   Layer    │  │   Layer    │              │
│  └────────────┘  └────────────┘  └────────────┘              │
│                                                              │
│  ┌────────────┐  ┌────────────┐                              │
│  │ Component4 │  │ Component5 │                              │
│  │Verification│  │Observability│                             │
│  │   Layer    │  │   Layer    │                              │
│  └────────────┘  └────────────┘                              │
│                                                              │
│   协同：Context 提供信息 → Constraint 划定边界                 │
│   → Orchestration 组织执行 → Verification 守门               │
│   → Observability 反馈 → 回到 Context 优化                   │
└──────────────────────────────────────────────────────────────┘

五大组件的协同关系是一个闭环反馈系统：

Context（信息）→ Constraint（边界）→ Orchestration（执行）
                                              ↓
Observability（反馈）← Verification（验证）← 输出
       ↓
  回到 Context 优化

关键洞察：五大组件不是并行的——它们组成一个单向流动的流水线，加上反向反馈的优化环。

5.2 组件 1 - Context Manager：AI 的"信息食谱"

5.2.1 Context Manager 的职责

Context Manager 决定AI 看到什么、看不到什么、以什么顺序看到。

它解决的核心问题：

1. 海量信息中，哪些对当前任务最相关？
2. AI 应该看多少信息（多了会 Lost in the Middle，少了会信息不全）
3. AI 应该什么时候刷新信息（静态 vs 动态）

5.2.2 Context 的分层模型

我们把 Context 分为 5 层：

关键设计原则：下层覆盖上层——L5（任务级）可以临时覆盖 L3（模块级），但不能覆盖 L1（系统级）。

5.2.3 主流 Context 文件对比

2026 年的趋势：

1. 从单文件到多文件：传统一个 .cursorrules 走天下，现在变成多 AGENTS.md 散布
2. 从纯文本到带 Schema：MDC、YAML Front Matter 等结构化格式成为主流
3. 从静态到动态：基于 Git diff、CI 状态动态调整 Context

5.2.4 Context 编写实战

我们用 Python Web 项目作为例子，展示一份高质量的 AGENTS.md。

# Project AGENTS.md - 编码规范与项目指南

## 1. 项目概述

**FastAPI + SQLAlchemy + PostgreSQL** 异步 Web 应用。

- 用途：电商平台后端 API
- 业务复杂度：中（订单、用户、支付、库存四大模块）
- 团队规模：8 人
- SLA：99.95%

## 2. 核心原则

1. **异步优先**：所有 I/O 操作必须是 async
2. **类型严格**：所有公共函数必须有完整 Type Hints
3. **错误显式**：不允许 bare except，不允许 silent failure
4. **测试驱动**：新功能必须有测试，PR 覆盖率不低于 85%

## 3. 模块边界

src/
├── core/ # 核心业务逻辑（订单、用户、支付）
├── lib/ # 工具函数（不依赖 core）
├── api/ # FastAPI 路由层（只做参数解析 + 调用 core）
├── models/ # SQLAlchemy 模型
├── schemas/ # Pydantic schemas
├── migrations/ # Alembic 迁移（只读历史）
└── tests/ # 测试（镜像 src/ 结构）

## 4. 命名约定

- 类名：PascalCase（`UserService`）
- 函数/变量：snake_case（`get_user_by_id`）
- 常量：UPPER_SNAKE_CASE（`MAX_RETRY_COUNT`）
- 私有方法：`_leading_underscore`
- 数据库表：复数 snake_case（`users`、`order_items`）
- 数据库列：单数 snake_case（`user_id`、`created_at`）

## 5. 必读规范

- 写新接口前先读 `src/api/v1/README.md`
- 改 schema 前先读 `src/schemas/README.md`
- 加 migration 必须有对应的 down 迁移
- 涉及金额的所有计算必须用 `Decimal`，不用 `float`

## 6. 禁止操作

- ❌ 不允许修改 `migrations/versions/` 下已存在的文件
- ❌ 不允许直接连接生产数据库
- ❌ 不允许在代码中硬编码 URL、密钥
- ❌ 不允许使用 `print()` 做日志，统一用 `src/lib/logger.py`
- ❌ 不允许在测试中 sleep，必须用 mock

## 7. 提交纪律

- Commit message 格式：`<type>(<scope>): <description>`
- type: feat / fix / refactor / test / docs / chore
- 涉及 DB / 权限 / 支付的改动，commit message 必须追加 `【需人工复核】`
- PR 描述必须包含：改了什么 / 为什么 / 影响面 / 测试方法

## 8. 必读模块

新成员必读（按顺序）：

1. `src/core/users/README.md` - 用户模块
2. `src/core/orders/README.md` - 订单模块
3. `src/core/payments/README.md` - 支付模块
4. `src/lib/errors.py` - 错误体系
5. `docs/architecture.md` - 整体架构

## 9. 常见问题

- Q: 怎么加新的 API endpoint？
  A: 先在 `src/schemas/` 加 Pydantic schema，再在 `src/api/v1/` 加路由，最后在 `src/core/` 加业务逻辑
- Q: 怎么加新的数据库表？
  A: 在 `src/models/` 加 SQLAlchemy 模型，运行 `alembic revision --autogenerate` 生成 migration
- Q: 怎么 mock 外部 API？
  A: 使用 `pytest-httpx`，参考 `tests/conftest.py`

这份 AGENTS.md 的关键设计：

• ✅ 有结构（9 个章节）
• ✅ 有原则（4 条核心原则）
• ✅ 有边界（模块边界图）
• ✅ 有禁止清单（5 条禁止操作）
• ✅ 有流程（提交纪律、常见问题）

5.2.5 Context 的常见反模式

5.3 组件 2 - Constraint Layer：AI 的"红线"

5.3.1 Constraint 的分类

Constraint 决定AI 能做什么、不能做什么。

5.3.2 约束的实现方式

方式一：声明式约束（推荐）

写在配置文件中，让 harness 自动执行：

# .harness/constraints.yaml
forbidden_files:
  - "migrations/versions/**"
  - ".env*"
  - "**/secrets.*"
  - "**/credentials.*"

forbidden_commands:
  - "rm -rf /"
  - "git push --force"
  - "DROP DATABASE"

required_checks:
  - "ruff check src/"
  - "mypy src/"
  - "pytest tests/ --cov=src/ --cov-fail-under=85"

required_approvals:
  - path: "src/core/payments/**"
    approver: "senior-engineer"
  - path: "**/migrations/**"
    approver: "dba-team"

方式二：编程式约束（高级）

用代码实现约束逻辑：

# .harness/hooks/pre_commit.py
def pre_commit_hook(changes: list[FileChange]) -> Result:
    """提交前检查"""
    
    for change in changes:
        # 文件级约束
        if change.path.startswith("migrations/versions/"):
            if change.is_modification():
                return Result.fail(
                    f"禁止修改历史 migration: {change.path}"
                )
        
        # 内容级约束
        if "TODO" in change.content and not change.path.startswith("tests/"):
            return Result.fail(
                f"生产代码不允许 TODO: {change.path}"
            )
        
        # 安全级约束
        if "api_key" in change.content.lower():
            return Result.fail(
                f"代码中不允许出现 api_key 字样: {change.path}"
            )
    
    return Result.ok()

方式三：Hook 式约束（事件驱动）

通过 PreToolUse / PostToolUse 拦截工具调用：

# .harness/hooks/pre_bash.py
def pre_bash_hook(command: str) -> Result:
    """Bash 命令前检查"""
    
    dangerous_patterns = [
        r"rm\s+-rf\s+/",
        r"git\s+push\s+--force",
        r"sudo\s+",
        r":\(\)\{.*\|\:&.*\};:",  # fork bomb
        r"curl\s+.*\|\s*bash",    # 远程执行
    ]
    
    for pattern in dangerous_patterns:
        if re.search(pattern, command):
            return Result.fail(
                f"危险命令被拦截: {command}",
                suggestion="请使用更安全的方式"
            )
    
    return Result.ok()

5.3.3 约束的粒度

约束不能太粗（“代码要高质量”），也不能太细（“函数不超过 20 行”）。

推荐粒度：

5.3.4 约束的反模式

5.4 组件 3 - Orchestration Layer：AI 的"分工表"

5.4.1 Orchestration 的职责

Orchestration 决定AI 怎么组织执行——是单 agent 还是多 agent，是顺序还是并行，是同步还是异步。

它解决的核心问题：

1. 复杂任务如何拆解？
2. 多个 agent 怎么协作？
3. 谁做什么、谁不做什么？

5.4.2 Orchestration 的五种范式

5.4.3 Sub-agent 设计

Sub-agent 是 Claude Code 的核心编排能力。它的设计模式：

# .claude/agents/test-writer.md
---
name: test-writer
description: 专门写测试的 sub-agent
model: sonnet
tools:
  - Read
  - Write
  - Bash
  - Grep
---

# Test Writer Agent

## 职责
为新功能生成单元测试和集成测试。

## 工作流
1. 读取被测代码
2. 分析函数签名、边界条件
3. 生成 pytest 测试用例
4. 验证测试能跑过
5. 报告覆盖率

## 限制
- 只能在 tests/ 目录写文件
- 不允许修改被测代码
- 不允许 mock 真实数据库

调用方式：

# 在主 agent 中
> 用 test-writer 为 src/core/payments/service.py 写测试

主 agent 会自动派发：

[主 agent] 检测到任务：写测试
   ↓
[派发] sub-agent: test-writer
   ↓
[执行] test-writer 读取 service.py
   ↓
[执行] test-writer 写 tests/core/payments/test_service.py
   ↓
[执行] test-writer 跑 pytest
   ↓
[报告] test-writer 报告覆盖率
   ↓
[主 agent] 接收结果，继续

5.4.4 Skill 体系

Skill 是"可复用的 agent 流程包"——把"做完一件事"的所有步骤打包。

Skill 的目录结构：

.claude/skills/db-migration/
├── SKILL.md              # 主描述
├── examples/             # 示例
│   ├── add_column.md
│   └── create_index.md
├── scripts/              # 脚本
│   └── verify_migration.py
└── templates/            # 模板
    └── migration.py.tmpl

SKILL.md 范本：

---
name: db-migration
description: 生成安全的数据库 migration
when_to_use: 当用户说"加字段"、"建表"、"改 schema"时
---

# Database Migration Skill

## 用途
生成符合项目规范、包含 up/down、可回滚的 Alembic migration。

## 工作流

### 1. 读取当前 schema
```bash
alembic current

2. 生成 migration 草稿

alembic revision --autogenerate -m "<description>"

3. 补充内容

• 加上 downgrade() 函数
• 加上数据迁移逻辑（如需）
• 加上 index 优化

4. 验证

alembic upgrade head
alembic downgrade -1
alembic upgrade head

5. 报告

• 显示新文件路径
• 显示影响范围
• 列出潜在风险

限制

• 只能创建新文件，不能修改 migrations/versions/ 下的历史文件
• 必须有完整的 down 迁移
• 必须包含 unit test

### 5.4.5 Slash Command

Slash Command 是用户显式调用的命令——`/review`、`/refactor` 等。

```markdown
# .claude/commands/review.md
---
description: 审查当前 PR
---

# Review Command

## 步骤
1. 读取最新的 PR diff
2. 用 5 个维度审查：
   - 代码风格
   - 测试覆盖
   - 安全风险
   - 性能影响
   - 文档完整性
3. 输出 Markdown 格式报告
4. 如果发现问题，自动开 issue

## 输出格式
```markdown
## Review Report

### 总体评价
[优秀/良好/需要修改/存在风险]

### 优点
- ...

### 问题
- [P0] ...
- [P1] ...
- [P2] ...

### 建议
- ...

调用方式：

```bash
> /review

5.4.6 Routines（例程）

Routines 是"watch 任务队列的 agent"——Anthropic Claude Code 2026.06 的核心实践。

# .claude/routines/pr-watcher.md
---
name: pr-watcher
trigger: "新 PR 开启"
schedule: "每 5 分钟检查一次"
---

# PR Watcher Routine

## 职责
监控新开启的 PR，自动跑测试、审计、给评论。

## 工作流
1. 检查新 PR（过去 5 分钟内）
2. 跑测试套件
3. 用 review agent 审计
4. 如果通过：贴 ✅ 评论
5. 如果失败：贴 ❌ 评论 + 自动加 label
6. 记录所有操作到 logs/

## 升级条件
- PR 涉及 payments/ 目录：通知 senior-engineer
- PR 涉及 migrations/ 目录：通知 dba-team
- 测试覆盖率下降 > 5%：开 issue

5.4.7 Multi-Agent State Machine

复杂的 multi-agent 协作需要状态机驱动——第 9 章会详细讨论。

[Plan Agent] → [Code Agent] → [Test Agent] → [Review Agent]
       ↑                                    ↓
       └────────── [如果失败则回退] ──────────┘

5.5 组件 4 - Verification Layer：AI 的"质检员"

5.5.1 Verification 的四个层次

5.5.2 四层验证的协同

代码生成
   ↓
[语法层] ruff / mypy / prettier
   ↓ 通过
[行为层] pytest / jest
   ↓ 通过
[安全层] bandit / snyk / gitleaks
   ↓ 通过
[业务层] e2e / benchmark
   ↓ 通过
[合并] 自动 merge

任何一层失败，流程立即停止。

5.5.3 自动审计（AI-as-Judge）

2026 年的新趋势：用 AI 来 review AI 生成的代码。

# .harness/audit/review_agent.py
async def review_pr(pr: PullRequest) -> ReviewResult:
    """用 AI 审计 PR"""
    
    # 1. 收集 PR 信息
    diff = pr.get_diff()
    context = pr.get_context()
    
    # 2. 派发 review agent
    review = await claude.review(
        diff=diff,
        context=context,
        criteria=[
            "代码是否符合 AGENTS.md 规范",
            "测试是否充分",
            "是否有安全风险",
            "是否有性能问题",
            "是否影响向后兼容",
        ]
    )
    
    # 3. 输出结构化结果
    return ReviewResult(
        passed=review.score >= 0.8,
        issues=review.issues,
        suggestions=review.suggestions,
    )

5.5.4 验证层反模式

5.6 组件 5 - Observability Layer：AI 的"黑匣子"

5.6.1 Observability 的职责

Observability 决定AI 的行为是否可被记录、分析、回放。

它解决的核心问题：

1. AI 做了什么？
2. 为什么这么做？
3. 代价是什么（token、时间、金钱）？
4. 怎么回放？

5.6.2 Observability 的四个维度

5.6.3 Trajectory 记录

Trajectory 是 AI 一次任务的完整操作序列——Harness 自演化的关键数据。

{
  "task_id": "feat-1234",
  "session_id": "sess-abc",
  "agent": "claude-opus-4-8",
  "start_time": "2026-06-17T10:00:00Z",
  "end_time": "2026-06-17T10:15:00Z",
  "duration_seconds": 900,
  "steps": [
    {
      "step": 1,
      "action": "read_file",
      "input": "src/core/users/service.py",
      "output_length": 3000,
      "duration_ms": 50
    },
    {
      "step": 2,
      "action": "edit_file",
      "input": "src/core/users/service.py",
      "output_length": 500,
      "duration_ms": 200,
      "success": true
    },
    {
      "step": 3,
      "action": "run_command",
      "input": "pytest tests/core/users/",
      "output": "5 passed",
      "duration_ms": 5000,
      "success": true
    }
  ],
  "token_usage": {
    "input_tokens": 15000,
    "output_tokens": 3000,
    "cache_creation_tokens": 1000,
    "cache_read_tokens": 5000
  },
  "outcome": "success",
  "verification_passed": true
}

5.6.4 Token 成本追踪

2026 年，Token 成本是 Harness 的重要监控指标：

# .harness/observability/cost_tracker.py
class CostTracker:
    def __init__(self):
        self.daily_budget = 100.0  # USD
        self.used_today = 0.0
    
    def track(self, usage: TokenUsage, model: str):
        cost = self.calculate_cost(usage, model)
        self.used_today += cost
        
        if self.used_today > self.daily_budget * 0.8:
            logger.warning(
                f"Token 预算使用 80%: ${self.used_today:.2f}"
            )
        
        if self.used_today > self.daily_budget:
            logger.error(
                f"Token 预算超限: ${self.used_today:.2f}"
            )
            raise BudgetExceededError()
    
    def calculate_cost(self, usage, model):
        prices = {
            "claude-opus-4-8": {
                "input": 0.015,       # $/1K tokens
                "output": 0.075,
                "cache_creation": 0.01875,
                "cache_read": 0.0015,
            }
        }
        p = prices[model]
        return (
            usage.input_tokens / 1000 * p["input"]
            + usage.output_tokens / 1000 * p["output"]
            + usage.cache_creation_tokens / 1000 * p["cache_creation"]
            + usage.cache_read_tokens / 1000 * p["cache_read"]
        )

5.6.5 行为画像

行为画像是 AI 在不同任务上的表现统计：

# .harness/observability/behavior_profile.yaml
agent: claude-opus-4-8
profile_date: 2026-06-17

performance_by_task:
  - task: "code_generation"
    success_rate: 0.92
    avg_turns: 3.2
    avg_tokens: 8000
    
  - task: "code_review"
    accuracy: 0.85
    false_positive_rate: 0.08
    false_negative_rate: 0.07
    
  - task: "refactor"
    success_rate: 0.88
    regression_rate: 0.04
    avg_tokens: 12000

performance_by_module:
  - module: "core/users"
    success_rate: 0.95
    
  - module: "core/payments"
    success_rate: 0.82  # 较低，需要更多 harness 约束
    
  - module: "core/orders"
    success_rate: 0.90

5.6.6 Observability 反模式

5.7 五大组件的协同设计

5.7.1 启动序列

Harness 启动时按以下顺序初始化：

1. 加载 Context（AGENTS.md、CLAUDE.md）
   ↓
2. 应用 Constraint（forbidden files、required checks）
   ↓
3. 注册 Orchestration（Sub-agents、Skills、Commands）
   ↓
4. 配置 Verification（lint、test、audit）
   ↓
5. 启动 Observability（trajectory、token、behavior）

5.7.2 任务执行流

Harness 处理一个任务时：

[用户输入] task prompt
   ↓
[Context] 注入 AGENTS.md、相关 module context
   ↓
[Constraint] 检查 prompt 是否触发 forbidden patterns
   ↓
[Orchestration] 决定走单 agent / sub-agent / multi-agent
   ↓
[Agent 执行] 工具调用 → 受 Constraint 约束
   ↓
[Verification] 每步后跑 lint/test
   ↓
[输出] PR
   ↓
[Observability] 记录 trajectory、token、behavior
   ↓
[Feedback] 反馈到 Context 优化

5.7.3 失败处理流

[Agent] 失败
   ↓
[Verification] 拦截（test fail / lint error / audit reject）
   ↓
[Orchestration] 决定：
   - 重试 (transient failure)
   - 升级 (permanent failure)
   - 回退 (state machine)
   ↓
[Observability] 记录失败原因
   ↓
[Context 优化] 把失败模式加到 AGENTS.md / 约束

5.8 一份 Harness 设计 checklist

我们用一份 checklist 帮你快速审视自己的 Harness：

5.8.1 Context Manager Checklist

• 项目根有 AGENTS.md
• 关键模块有局部 AGENTS.md
• AGENTS.md 有结构（原则、边界、禁止、流程）
• AGENTS.md 字数 < 5000（避免 Lost in the Middle）
• AGENTS.md 有版本和最近更新日期
• AGENTS.md 有"如何贡献"的说明

5.8.2 Constraint Layer Checklist

• forbidden_files 列表完整
• forbidden_commands 列表完整
• required_checks 在 pre-commit 中执行
• 关键目录有 required_approvals
• 安全相关约束通过 Hook 强制

5.8.3 Orchestration Layer Checklist

• 至少有一个 Sub-agent（如 test-writer）
• 至少有一个 Skill（如 db-migration）
• 至少有一个 Slash Command（如 /review）
• Routine 任务用 Cron 或 watch 触发
• 复杂任务用 Multi-agent state machine

5.8.4 Verification Layer Checklist

• 语法层：Lint + Type Check
• 行为层：Unit + Integration Test
• 安全层：Secret Scan + SAST
• 业务层：E2E Test
• 至少有一个 AI-as-Judge 审计

5.8.5 Observability Layer Checklist

• 记录每个 task 的 trajectory
• 记录 token 消耗
• 设置 daily/monthly budget
• 行为画像按月更新
• 观测数据用于 harness 自优化

5.9 常见误区

5.9.1 误区一：“五大组件都要齐全”

部分错误。

最小可行 Harness 只需要 3 个组件：

• Context（必选）
• Constraint（必选）
• Verification（必选）

Orchestration 和 Observability 是进阶组件，根据项目规模逐步加。

5.9.2 误区二：“五大组件各自独立”

错误。

五大组件是有机协同的——Constraint 定义在 Context 之上，Verification 检查 Orchestration 的输出，Observability 反馈到 Context。

把它们当独立模块来设计 = 设计失败的 Harness。

5.9.3 误区三：“Harness 一次设计就够”

错误。

Harness 必须持续演化：

• 新的失败模式 → 加 Constraint
• 新的可复用任务 → 加 Skill
• 新的安全风险 → 加 Verification
• 新的成本压力 → 优化 Context

Harness 是"养"出来的，不是"建"出来的。

5.10 本章小结

Harness 五大组件是 Harness Engineering 的具体载体。本章我们详细讲解了每个组件的设计原则、实现方式、常见反模式。

下一章（第 6 章）我们将进入工具链实战——用 Claude Code、Cursor、Trae IDE 等主流工具搭建一个完整的 Harness。

5.11 思考题

1. 你的项目目前有 Harness 五大组件中的哪几个？缺哪些？
2. 你的 AGENTS.md 写得好吗？用 5.2.4 的范本对比一下，差距在哪里？
3. 你的 Verification 是哪几层？缺哪一层？补上它需要多少工作量？

5.12 参考资料

• Anthropic, “Effective Context Engineering for AI Agents”, 2024.12
• Anthropic, “Building Effective Agents”, 2024.03
• OpenAI, “Harness engineering: leveraging Codex in an agent-first world”, 2026.02
• Mitchell Hashimoto, “Harness Engineering”, 2026.02.05
• Boris Cherny, Sequoia AI Ascent 2026 演讲, 2026.05
• The Neuron, “Boris Cherny and Cat Wu: One Year of Claude Code”, 2026.06.09
• HarnessX 论文, arxiv 2606.14249, 2026.06.15
• CSDN, “Harness Engineering：AI Agent 落地企业的工程化核心”, 2026.06.13