大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



---

Harness = Agent - Model

Harness 是 AI 代理中除模型以外的一切：约束、工具、文档、反馈循环。优化 Harness 比优化 Prompt 更有效 — LangChain 仅靠改进 Harness 就从 Terminal Bench 2.0 的 52.8% 跃升至 66.5%。

核心哲学：人类掌舵，智能体执行（Human Steer, Agent Execute）

范式演进

提示词工程 (2023-2024) → 上下文工程 (2025) → 驾驭工程 (2026) 

当前推荐落地形态（2026）

推荐把 Harness Engineering 实现为：

• 一个 bootstrap-only 总入口 skill：.claude/skills/harness-engineering/
• 一组由它在项目初始化时生成的 项目本地子 skill
• 一套 repo 内共享的 状态板、handoff、guardrails、evals、observability 占位

典型调用方式：

/harness-engineering @技术文档 @PRD文档 

该入口 skill 不负责长期日常开发，而是负责在项目创建阶段一次性生成：

• AGENTS.md
• CLAUDE.md
• docs/harness-status.md
• docs/handoffs/
• .claude/hooks/
• .claude/skills/task-intake
• .claude/skills/review-fix
• .claude/skills/release-check
• .claude/skills/ui-verify
• .claude/skills/handoff
• scripts/bootstrap-verify.sh
• evals/
• observability/

---

综合 justin3go、Blake Crosley、celesteanders 等开源项目，Harness 可分为七层：

Layer 1: Project Setup（项目配置）

目标：让 Agent 能正确启动和运行项目。

关键原则：

• Agent 应该能通过一个清晰入口完成 Harness 初始化
• bootstrap 应是 一次性初始化动作，而不是长期日常命令
• 已初始化项目应通过 repair / upgrade 演进，而不是重复覆盖

Layer 2: Context Engineering（上下文工程）

目标：让 Agent 快速理解项目全貌，知道去哪找信息。

CLAUDE.md **实践（来自 242 个仓库分析）：

• 浅层级结构（一级标题 + 子节），不要深度嵌套
• 渐进式披露：CLAUDE.md 是目录，docs/ 是正文
• 包含可直接执行的命令，不要只写描述
• 保持 ~100 行，超出部分放 docs/

CLAUDE.md 推荐结构：

# Project Name — Harness Guide

Quick Reference (技术栈速查表)

Commands (可执行命令列表)

Project Structure (目录结构，带简要说明)

Architecture Constraints (不可违反的规则)

Key Patterns (核心设计模式)

Documentation Index (指向 docs/ 的链接表)

CIVC Feedback Loops (反馈循环命令)

Layer 3: Constraints & Rules（约束与规则）

目标：用机制而非提示词强制执行规范。

核心原则：能用机制检查的，就不要只写在文档里让 Agent “记住”。

ESLint 架构约束示例：

// eslint.config.js { rules: {

'no-restricted-imports': ['error', { patterns: [{ group: ['axios'], message: 'Use api/client.ts instead of importing axios directly.' }] }] 

} }

架构检查脚本示例：

#!/bin/bash # scripts/check-architecture.sh # 检查层级依赖方向：types/ 不能导入 api/、stores/ 等 VIOLATIONS=0 for file in src/types/*.ts; do if grep -qE “from [‘”]@/(api|stores|components|views)/“ ”$file“; then

echo "VIOLATION: $file imports from forbidden layer" VIOLATIONS=$((VIOLATIONS + 1)) 

fi done exit $VIOLATIONS

Layer 4: Feedback Loops（反馈循环）

目标：Agent 出错时自动获得纠正信号。

反馈速度层级（越快越好）：

PostToolUse Hook (毫秒) > pre-commit (秒) > CI (分钟) > 人工审查 (小时) 

Claude Code Hooks 配置 (.claude/settings.json)：

{ ”hooks“: {

"PostToolUse": [ { "matcher": "Edit|MultiEdit|Write", "hooks": [ { "type": "command", "command": "bash "$CLAUDE_PROJECT_DIR/.claude/hooks/posttooluse-format.sh"" } ] } ] 

} }

Hook 类型说明：

Hook 设计原则：

• hook 可以快速失败，但不能静默吞错
• 日志应明确区分 SKIP / OK / ERROR
• Correct 环路必须提供真实失败信号，而不是伪装成功

反例：

npx prettier –write ”\(target_file" >/dev/null 2>&1 || true 

这会吞掉格式化失败，使日志与真实状态脱节。

推荐写法：

if npx prettier --write "\)target_file“ >/dev/null 2>&1; then printf ’%s OK %s via=prettier ‘ ”\((date -u +"%Y-%m-%dT%H:%M:%SZ")" "\)target_file“ else status=\(? printf '%s ERROR %s via=prettier exit=%s ' "\)(date -u +”%Y-%m-%dT%H:%M:%SZ“)” “\(target_file" "\)status” exit “$status” fi 

Layer 5: Verification（验证）

目标：多层验证确保代码质量。

验证层级：

确定性验证（快） 推理型验证（慢） ├── TypeScript 类型检查 ├── AI 代码审查 ├── ESLint 规则检查 └── Agent 交叉验证 ├── 单元测试 ├── 架构约束检查 └── 格式检查 

Pre-commit 配置（simple-git-hooks + lint-staged）：

// package.json { “simple-git-hooks”: {

"pre-commit": "pnpm lint-staged" 

}, “lint-staged”: {

"*.{vue,ts,tsx}": ["eslint --fix", "prettier --write"], "*.css": ["prettier --write"] 

} }

全量检查命令：

{ “scripts”: {

"check:all": "pnpm format:check && pnpm lint && pnpm check:arch && pnpm check:docs && pnpm build && pnpm test" 

} }

Harness 级验证不应只停留在 check:all。建议至少分三层：

1. 工程健康检查：build、lint、test、arch、docs
2. bootstrap 校验：入口文档、状态板、handoff、child skills、hooks 是否齐全
3. workflow eval：task intake → review fix → handoff 是否能闭环流转

Layer 6: Entropy Management（熵管理）

目标：对抗文档腐化和代码熵增。

OpenAI 的策略：持续小额偿还，而非集中处理 — 他们称之为“垃圾回收”。

文档新鲜度检查脚本：

#!/bin/bash # scripts/check-docs-freshness.sh # 检查文档中引用的 repo 路径是否仍然存在 stale=0 while IFS= read -r path; do clean=“\((printf '%s' "\)path” | sed -E ’s/^[<(]+//; s/[>)“,;:]+\(//; s/:[0-9]+\)//‘)” [ -z “\(clean" ] && continue if [ ! -e "\)clean” ]; then

echo "STALE: $clean referenced in docs but not found" stale=$((stale + 1)) 

fi done < <( grep -rohE ’(.claude|docs|scripts|evals|observability|src)/[A-Za-z0-9_./:-]+‘ docs/*.md CLAUDE.md AGENTS.md | sort -u ) exit “$stale”

熵管理策略：

• 定期运行文档一致性检查
• CLAUDE.md 保持精简（~100 行），减少维护负担
• 让 Agent 在发现文档过期时主动更新
• 测试文件与源码同目录，减少漂移

Layer 7: Observability（可观测性）

目标：了解 Agent 的工作质量和效率。

---

CIVC 是 Harness 的运行时闭环，贯穿七层架构：

约束 (Constrain) → 告知 (Inform) → 验证 (Verify) → 纠正 (Correct)

 ↑ │ └────────────────────────────────────────────────────┘ 

---

OpenAI/Anthropic 团队实践中反复出现的四个模式：

1. 上下文工程（Context Engineering）

• Agent 只能推理它能看到的内容
• CLAUDE.md 是入口，不是百科全书
• 使用 @docs/xxx.md 引用深层文档
• 保持文档机器可读

2. 架构约束（Architecture Constraints）

• 严格的层级依赖模型（如 Types → Config → Repo → Service → Runtime → UI）
• 用 linter 和结构测试机械化执行，不依赖 Agent “记住”
• 跨切面关注点（认证、日志）通过单一接口注入

3. 反馈循环（Feedback Loops）

• 错误信息即 Prompt：linter 报错格式应为 问题 + 修复建议 + 文档链接
• 反馈越快越好：PostToolUse > pre-commit > CI > 人工
• Agent 审 Agent：用一个 Agent 验证另一个的输出

4. 熵管理（Entropy Management）

• 持续小额偿还技术债
• 定期文档一致性扫描
• 命名规范漂移检测
• 死代码清理

---

Phase 0: Bootstrap

• 创建 .claude/skills/harness-engineering/
• 以 /harness-engineering @技术文档 @PRD文档 作为初始化入口
• 写入 .claude/harness-bootstrap.json 防止重复初始化

Phase 1: Shared Context

• 生成 CLAUDE.md
• 生成 AGENTS.md
• 生成 docs/harness-status.md
• 生成 docs/handoffs/
• 生成 docs/execplans/
• 生成 docs/review-report/

Phase 2: Child Skills

• 生成 .claude/skills/task-intake/
• 生成 .claude/skills/review-fix/
• 生成 .claude/skills/release-check/
• 生成 .claude/skills/ui-verify/
• 生成 .claude/skills/handoff/

Phase 3: Guardrails + Hooks

• 配置 .claude/settings.json
• 配置 .claude/hooks/posttooluse-format.sh
• 创建 scripts/check-architecture.sh
• 创建 scripts/check-docs-freshness.sh
• 创建 scripts/bootstrap-verify.sh

Phase 4: Evals + Observability

• 创建 evals/harness/
• 创建 evals/regression/
• 创建 observability/README.md

Phase 5: Long-Running Workflow

• 规定 verified 必须绑定 fresh evidence

---

project-root/ ├── CLAUDE.md # AI 代理主入口（~100 行） ├── AGENTS.md # 跨代理通用指令 ├── README.md # 项目 README ├── .claude/ │ ├── settings.json # Claude Code hooks + 配置 │ ├── harness-bootstrap.json # bootstrap 标记与 profile │ ├── hooks/ │ │ └── posttooluse-format.sh # 自动纠偏，失败显式暴露 │ └── skills/ │ ├── harness-engineering/ # bootstrap-only 总入口 skill │ ├── task-intake/ # 任务接入 │ ├── review-fix/ # 审查修复 │ ├── release-check/ # 发布检查 │ ├── ui-verify/ # UI 验证 │ └── handoff/ # 交接沉淀 ├── docs/ │ ├── harness-status.md # 状态板 │ ├── handoffs/ # 交接文档 │ ├── execplans/ # 大任务计划 │ ├── review-report/ # findings / 复验 / 证据 │ ├── architecture.md # 系统架构 │ ├── conventions.md # 编码规范 │ ├── development-guide.md # 开发指南 │ ├── api-guide.md # API 文档（如适用） │ └── component-guide.md # 组件文档（如适用） ├── scripts/ │ ├── check-architecture.sh # 架构约束检查 │ └── check-docs-freshness.sh # 文档新鲜度检查 │ └── bootstrap-verify.sh # Harness 骨架校验 ├── evals/ │ ├── harness/ # Harness 级 eval │ └── regression/ # 历史问题回归 ├── observability/ │ └── README.md # 运行时证据与可观测性占位 ├── eslint.config.js # ESLint 配置（含架构规则） ├── .prettierrc # Prettier 配置（如需） └── package.json # scripts + git hooks + lint-staged 

---

核心文章

• OpenAI - Harness Engineering — 百万行代码实验报告
• Martin Fowler - Harness Engineering — 三大支柱定义
• LangChain - The Anatomy of an Agent Harness — Harness 解剖

实践指南

• justin3go - 七层 Harness 模型
• Blake Crosley - Context Is Architecture — 七层上下文架构
• Blake Crosley - 5 Production Hooks — Hooks 实战
• Sakasegawa - Best Practices
• Flashcat - CIVC 四大机制

GitHub 开源项目

• celesteanders/harness — **实践集合
• ai-boost/awesome-harness-engineering — 资源列表
• walkinglabs/awesome-harness-engineering — 工具与指南
• deusyu/harness-engineering — 中文学习指南

CLAUDE.md 专项

• The Definitive Guide to CLAUDE.md — 五层配置系统
• CLAUDE.md Progressive Disclosure Guide
• dotclaude.com — .claude 目录参考