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 看到什么、看不到什么、以什么顺序看到。

它解决的核心问题：

5.2.2 Context 的分层模型

我们把 Context 分为 5 层：

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

5.2.3 主流 Context 文件对比

2026 年的趋势：

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，是顺序还是并行，是同步还是异步。

它解决的核心问题：

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 的行为是否可被记录、分析、回放。

它解决的核心问题：

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 思考题

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