2026-05-27 · 预计阅读 60 min · 样板：gewoox-sleepal-app · 调研窗口 2025-11 → 2026-05
PRACTICAL GUIDE · 2026 EDITION

Harness Engineering 落地实践指南

以 gewoox-sleepal-app（一个真实运行的 Go 后端服务）为样板，分析其 Harness 落地的 12 项关键优势和 10 项实际不足，并沉淀 Harness Engineering 在工程项目中的落地方法论、关键取舍与渐进步骤。给只用过 Cursor / Codex / Claude Code 这类 IDE 的人看 — 让你理解每个组件的方法论、取舍，并能自行判断如何在自己项目中落地。评判维度只看实际效果，不看是否引入特定工具。

面向：Cursor / Codex 用户 基于：1100+ 行一手设计 + 36 个 archive 覆盖：9 职责 + 6 阵营 + 6 判断模型 含 2026-Q2 新增：Graphify · Karpathy LLM Wiki · GraphRAG · AgentLint

Part 0 · 三分钟摘要

  1. Harness Engineering ≠ 更长的 prompt，也 ≠ 一个向量库。它是把 LLM Agent 的工作环境（项目知识、任务流程、工具权限、反馈检查、状态恢复、人类决策点）当成一套显式的工程系统来设计，让 Agent 在真实代码库中少猜、少跑偏、可验证、可恢复。LangChain 公式定型为 Agent = Model + Harness，Mitchell Hashimoto 2026-02 命名这一学科，Martin Fowler 把它进一步定义为给 coding-agent 用户侧的外部工作台。
  2. 2026-Q1 → Q2 几件事让它成为独立学科：OpenAI 公开 "5 个月、3 个工程师、1M+ LOC、零人写代码" 的 Codex 实验；Anthropic 系列长任务 Harness 文章；Claude Code 源码 3-31 意外泄漏；Fowler 4-2 完整文章；Karpathy 4 月 LLM Wiki gist；Graphify 4 月发布 2 周 28k stars；AgentLint 推出；Thoughtworks 5 月 sensors 专文。
  3. Harness 至少回答 9 个职责：入口与意图、上下文选择、项目知识、任务生命周期、工具与权限、过程能力、反馈传感器、状态与恢复、学习与健康。Fowler 给出两条最有用的二分：guides（feedforward）+ sensors（feedback）；computational + inferential。
  4. 2026-Q2 涌现的一个重要新方向：把项目知识当 graph 而不是 vector。Graphify（Tree-sitter AST + LLM subagent + Leiden 社区检测 + PreToolUse hook 拦 grep）实测 71.5× 减少 token；GraphRAG 在多跳问题上准确率 86% vs vector RAG 32%；Karpathy 的 LLM Wiki 模式：不要让 LLM 当 search engine，让它当 wiki maintainer，三层架构 raw/ + wiki/ + CLAUDE.md；这些方法论跟传统 PARA + Zettelkasten 收敛——AI 时代图结构的知识库价值飙升。
  5. 样板项目 gewoox-sleepal-app 把 9 职责物理化为三层 Tier：AGENTS.md + HARNESS_DESIGN.md 是入口；.codex/ + openspec/ 是外部工具协议层（硬绑定）；.harness/ 是仓库自有的 8 个内部层。Phase A→H 演进，42 个 active owner，36 个 archived change，12 个 capabilities SKILL，2 个 packet-only 子代理。
  6. 参考项目按"实际效果"做了对的 12 件事，也有 10 项实际不足（Part 6 / 7）。本文评判标准只看实际效果，不看是否引入特定工具——如果自建机制达到了同等效果，"未引入业界工具"本身不构成不足。
  7. 落地不是"一次抄全套"。Part 8 给三阶段渐进式落地路线 + 6 个判断模型（M1 规模决定形态 / M2 guides vs sensors / M3 computational vs inferential / M4 file vs runtime / M5 何时跳过 / M6 何时 re-simplify）。不要从 GraphRAG 起步（Microsoft 自己的 LazyGraphRAG benchmark 显示传统 GraphRAG indexing 贵 1000×）。Harness 是手段，项目本身才是目的——花在 Harness 上的时间超过业务代码就是出了问题。

Part 1 · 从 IDE 体验出发，理解 Harness Engineering

1.1 你其实已经在做 Harness Engineering，只是没系统化

打开你用 Cursor / Codex / Claude Code 的项目，看看是不是出现过这些文件或行为：

你的做法它在 Harness 体系里叫什么
写过 .cursorrules / .cursor/rules/*.md / CLAUDE.md入口指南 + 行为约束
在 README 里写"先看 X 再做 Y"的执行约定过程指南（口头版）
在 prompt 里要 Agent 跑 lint / typecheck 再回报反馈传感器（手动版）
用 @file 把范例文件拽进 contextJIT 上下文加载（手动版）
把 API 描述放进 docs/api.md 然后让 Agent 读它项目知识管道（轻量版）
复制粘贴 prompt 模板复用过程能力 / Skill（口头版）
让一个 Agent review 另一个 Agent 的输出子代理 + 反馈
让 Agent 写 task list 然后逐条执行任务生命周期（轻量版）
在 prompt 里贴上次错误的截屏事件记忆（手动版）
i核心洞见
Harness Engineering 不是一种你完全没见过的高级概念，它是把这些散落的零件显式化、机械化、可版本化、可 review地组织成一个工程控制系统。每条"AI 不听话"的抱怨都对应 Harness 体系里的一个具体组件——本文会逐一讲清楚。

如果你撞上下面这些场景，就是缺特定 Harness 组件的信号：

你遇到的问题你缺的 Harness 组件
写了 200 行 .cursorrules，Agent 反而忽略关键规则缺路由 / 上下文选择——所有规则一次进 context，关键信号被噪声淹没（"context rot" / "lost in the middle"）
改了三遍 prompt，下次会话又忘了缺项目知识 / 跨会话记忆
Agent 跑了一会儿就跑偏，自评说"完成"实际没改对缺反馈传感器（机械检查）和完成定义
长任务中断后重启全靠聊天记录猜缺状态与恢复（checkpoint / resume）
同样的错误反复犯缺学习与沉淀机制（archive → owner 抽取）
多人同时让 Agent 改这个仓库，规则漂移缺显式 owner 边界 + 健康检查
一个 Agent 干所有事，context 越攒越脏缺子代理 packet-only 隔离
Agent 每次问问题都要把整个仓库 grep 一遍缺结构化检索（知识图谱 / LLM Wiki）
模型升级了你的项目反而出更多 bug缺re-simplify on model upgrade 的纪律

1.2 Harness Engineering 的一句话定义

Harness Engineering 是把 Agent 的工作环境当成一套工程系统来设计：把项目知识、任务流程、工具权限、反馈检查、状态恢复和人类决策点显式化，让 LLM Agent 在真实代码库里少猜、少跑偏、可验证、可恢复。

来自 LangChain 的简洁公式：

Agent = Model + Harness

Vivek Trivedy（LangChain）把它推到更绝对："If you're not the model, you're the harness."

Martin Fowler 把这个边界进一步限定到 coding agent 用户侧：Cursor / Codex / Claude Code 这些产品已经提供了内部 Harness（系统 prompt、工具调用、内置 RAG、token 计费策略），但你仍然需要为你自己的项目构建一层外部 Harness。

prompt engineering · 单次指令优化 context engineering · 上下文窗口规划 agent engineering · 跑 reason-act-observe harness engineering · 整个 Agent 系统的控制平面

1.3 它不是什么（避免常见误解）

容易误解为什么不准确
"就是写一个超长 prompt"超长 prompt 只解决入口指引，无法处理验证、状态、权限、长期维护，且会触发 context rot
"就是上一个向量库做 RAG"检索只是"上下文选择"这一职责的一种实现；Harness 还覆盖生命周期、工具、反馈、状态、学习；且 2026-Q2 业界已经在用图谱（GraphRAG / Graphify）取代部分 vector RAG
"就是搭一个多 Agent 平台"多 Agent runtime 是实现手段而非全部；很多场景文件 + git 就够了
"就是 OpenSpec 或 Spec Kit"Spec lifecycle 只覆盖"需求到实现"，无法单独承担项目知识、工具权限、资产健康
"就是目录规范 / 起名好看"目录是可维护载体，核心是 guides、sensors、state、gates、extraction 五件事的工程化
"等模型变强就不需要了"模型再强也无法替你做：项目知识有 owner、行为变更要 review、归档后经验要可检索

1.4 为什么 2026 年它变成一个独立话题

几件事在 2025-Q4 → 2026-Q2 密集发生（完整时间线见 .harness/knowledge/industry/HPI-KNW-002）：

2025-11 · Anthropic 长任务 Harness（首次成体系）
Effective Harnesses for Long-Running Agents
提出 Initializer + Coding Agent 两段式；Context Reset 模式；首次把 Harness 概念落到工程实践。
2026-02 · OpenAI 1M LOC + Hashimoto 命名 + Böckeler memo
Harness Engineering 学科正式定型
OpenAI 公开 1M+ LOC / 1500+ PRs / 0 人写代码实战；Mitchell Hashimoto 命名 "harness engineering"；Agent = Model + Harness 成业界共识；Birgitta Böckeler 在 Martin Fowler 站点发布 memo 建立 guides/sensors 词汇。
2026-03 · LangChain DeepAgents · Claude Code 源码泄漏 · Anthropic 第二轮
框架 + 实例 + Re-simplify 原则
LangChain 发表 The Anatomy of an Agent Harness + 推出 DeepAgents 开源 batteries-included harness；Claude Code 3-31 源码意外泄漏，业界首次看到生产 coding agent 完整 harness 实现；Anthropic 第二篇长任务文章提出 "Re-simplify on model upgrades"。
2026-04 · Fowler 完整文章 · Graphify 爆款 · Karpathy LLM Wiki · AgentLint
学科爆发月
  • 4-2 Fowler 发完整文章：guides+sensors / computational+inferential / 3 类调节目标
  • 4-3 Graphify 发布：Tree-sitter AST + LLM subagent + Leiden 社区检测 + PreToolUse hook 拦 grep；2 周 GitHub 28k stars / 71.5× 减少 token
  • 4 月 Karpathy 发 LLM Wiki gist：LLM 自己 build + maintain wiki；三层架构 raw//wiki//CLAUDE.md
  • 4 月 AgentLint 推出，第一个 harness-level linter（现 58 checks / 6 dimensions）
  • 4-8 Anthropic 发《Scaling Managed Agents》：提出 brain / hands / session 三分与 meta-harness，把"harness 不应 static"推进到平台级解耦
  • 4-16 Ryan Lopopolo 在 AI Engineer Europe Keynote 给出 OpenAI Codex 工程细节
  • 4-28 Addy Osmani 综述 Long-running Agents，并排提炼 Anthropic / Cursor / Google 三家收敛模式
2026-05 · Thoughtworks Sensors · harness templates · harness 产品化
学科已成型，进入工具化与产品化阶段
Thoughtworks 发表 sensors 专文，把 sensors 提升为一等组件；业界共识 "harness templates"（按 application type 预配的模板）成为下一步方向；5-6 Anthropic 在 Code with Claude SF 把 harness 层做成产品——Outcomes（rubric 评分托管 loop）/ Multi-Agent（≤20 并行 brain）/ Webhooks / Dreams，Dario "No new model today"。
2026-Q2 · harness 开始自动进化（AHE 论文）
Agentic Harness Engineering · arXiv 2604.25850
论文提出 base model 冻结、让 agent 自动进化 harness 的闭环：三个 observability 支柱（component / experience / decision），每次编辑配可证伪预测、无效即按文件回滚；GPT-5.4 上 10 轮把 Terminal-Bench 2 pass@1 69.7% → 77.0%，超过手写 Codex 71.9%，且冻结后可迁移到 SWE-bench + 4 个其他 base model。

这条线背后的趋势：模型在快速商品化，差异化越来越集中在 Harness 这一层。把 prompt engineering / context engineering / agent engineering 看做三个上一代关键词，harness engineering 把前三者吸纳为子模块。2026-Q2 又出现三个新方向：harness 被平台级解耦（brain / hands / session）、被产品化（verification / memory / orchestration 各成 SKU）、甚至开始自动进化（base model 冻结、agent 自己改 harness 并对每次改动做可证伪预测）。

Part 2 · 9 职责 + Fowler 二分法（核心方法论）

2.1 9 个职责

不看具体目录，一个能让 coding agent 真正干活的 Harness，至少回答 9 个职责。用 card-grid 一图就明白：

01
入口 / 意图
Agent 从哪里开始、本次是哪类任务
缺：一启动就乱读 / 过度读全仓库
02
上下文选择
这次该读哪些文件，不该读哪些
缺：关键 owner 被噪声淹没（context rot）
03
项目知识
长期事实、规则、边界存哪、怎么被检索
缺：新会话像新人重复犯错
04
任务生命周期
需求从 intake 到 archive 全流程
缺："顺手改"无法追溯，完成标准漂移
05
工具与权限
Agent 能调用什么、什么时候要审批
缺：写得动但不能安全验证，或权限过宽
06
过程能力 / Skills
重复工作沉淀成 SOP
缺：每次从零摸索，质量靠个人记忆
07
反馈传感器
输出如何被机械化检查 + 语义化 review
缺：错误要到人工 review 才发现
08
状态与恢复
当前进度、下一步、积压障碍
缺：长任务中断后只能靠聊天记录猜
09
学习与健康
经验如何沉淀、过期内容如何清理
缺：Harness 越用越厚，信号密度下降

2.2 Fowler 的两条二分法

2.2.1 Guides（feedforward）vs Sensors（feedback）

控制方向时机9 职责中的对应
Feedforward guides（预防）Agent 行动之前入口、上下文选择、项目知识、过程能力、生命周期前半段
Feedback sensors（纠正）Agent 行动之后反馈传感器、生命周期后半段
Continuous drift sensors（健康）跨任务累积学习与健康
✓诊断你缺哪一类
  • Agent 经常违规但你没察觉 → 缺 sensors
  • Agent 频繁犹豫 / 重新发明轮子 → 缺 guides
  • 单次任务都做对了但仓库越用越乱 → 缺 drift sensors
OpenAI 2026-02 原话："discipline shows up more in the scaffolding rather than the code." —— 这就是把 inferential guide（"日志要结构化"）升级成 computational sensor（lint 检查日志格式）的精神。

2.2.2 Computational vs Inferential Controls

类型适合做什么例子
Computational controls可确定判断、低成本、每次跑line budget、frontmatter schema、route anchor、tests
Inferential controls语义判断、架构 review、产品取舍reviewer agent、human design review、LLM-as-judge
!核心原则
能用 computational 的，不要交给 LLM 判断。只有语义、架构、产品取舍才用 inferential 或 human gate。

2.2.3 三类调节目标

调节目标当前成熟度推荐手段
Maintainability harness（代码质量）最成熟lint、tests、convention、命名 / 分层规则
Architecture fitness harness（架构对齐）部分成熟boundary gate、owner files、route table、reviewer subagent
Behaviour harness（业务行为对齐）仍是行业难题spec scenarios、focused tests、product docs、人工 review
!关键判断
Behaviour 永远不能完全自动化。AI 生成的测试通过 ≠ 产品行为对齐用户意图。这就是为什么参考项目对涉及行为变更的 change 强制要求 Boundary Human Review Gate（详见 Part 6 S5）。

Part 3 · 知识组织、维护、检索方法论（2026 完整谱系）

i本节定位
Harness 9 职责里"项目知识 + 上下文选择 + 状态与恢复 + 学习与健康"四块共同回答的是：Agent 怎么把项目知识组织好、维护好、检索好。本节系统对照 2026 业界的所有主流路线。完整 owner 见 .harness/knowledge/industry/HPI-KNW-004。

3.1 知识组织：三大方法论流派

3.1.1 PARA（Tiago Forte，"Building a Second Brain"）

四类 folder：Projects（有 deadline 的活跃任务）/ Areas（持续性责任）/ Resources（兴趣 / 参考）/ Archive（已完结）。

  • 优点：低学习曲线，结构清晰，面向"完成事情"
  • 局限：扁平 folder，跨类别检索弱，不强调原子化与互联
  • 2026 AI 集成评分：7/10——AI 把"知道东西在哪个 folder"的弱点削平了

3.1.2 Zettelkasten（Niklas Luhmann，1950s）

四条核心规则：Atomic notes（一 note 一想法）/ Own words（用自己的话）/ Dense linking（密集互联）/ Unique ID（唯一标识）。

  • 优点：天然形成知识图谱；AI 时代图结构正好是 LLM retrieval 的理想 fodder
  • 局限：高学习曲线，要求持续维护链接
  • 2026 AI 集成评分：9/10——MCP servers for Obsidian vault 让 LLM 沿 wikilink 链做 multi-hop reasoning

3.1.3 LLM Wiki（Karpathy 2026-04 提出 ⭐）

关键转变：不是 "你写 wiki，LLM 偶尔问"，而是 "LLM build & maintain wiki，你只 sourcing & 问问题"。出处：Karpathy 的 gist 2026-04。他自己用这个模式建了 100+ 文章、400k 字的研究 wiki，全由 agent 写成。

Layer 1
Raw sources（raw/） · 你扔东西，immutable
你的角色：扔 PDF / 网页 / 笔记进去。LLM 的角色：只读。
Layer 2
Wiki（wiki/） · LLM 完全拥有
你的角色：浏览 / 提问。LLM 的角色：完全拥有——entity pages、concept pages、syntheses、log、overview、index。
Layer 3
Schema（CLAUDE.md / AGENTS.md） · 配置 wiki 结构
你的角色：配置 wiki 结构、命名、ingestion 规则。LLM 的角色：严格遵守。

典型 wiki 目录（来自 llm-wiki-agent）：

raw/ # 你扔东西，immutable wiki/ # LLM 完全拥有 index.md # 目录 log.md # append-only 时序记录 overview.md # 活体 synthesis sources/<src>.md # 每个 source 的摘要 entities/<name>.md # 人 / 公司 / 项目 / 产品 concepts/<name>.md # 想法 / framework / 方法 / 理论 syntheses/<q>.md # 把你问过的好问题保存为 page

Ingestion 工作流：你扔 source → LLM 读 → 更新 index → 更新 overview → 更新 / 创建 entity & concept page → 加 wikilink → append log → 标矛盾。

the wiki is the codebase, LLM is the programmer, Obsidian is the IDE. — Andrej Karpathy, LLM Wiki gist 2026-04

3.1.4 业界主流 = PARA + Zettelkasten + LLM Wiki 三合一

2026 年最广泛复现的实践（educalvolopez 2026、Riz 的 second brain）：

PARA 当外层（folder 按 Projects/Areas/Resources/Archive 分） Zettelkasten 当内层（每个 note atomic + wikilink） Karpathy LLM Wiki 当工作流（LLM 维护）

3.2 检索方法论：从 RAG 到 Agentic RAG

"检索"本身在 2026 年也独立成了一个方法论谱系。每加一层都要测量收益，业界 2026 production 默认顺序：

Naive RAG (chunk + embed + top-k) ↓ Hybrid Search (BM25 + dense + RRF) ← 2026 production 起点 ↓ + Cross-encoder Re-ranking ← 提高 precision ↓ + HyDE / RAPTOR / 查询变换 ← 只对失败 case 加 ↓ + Query Router (单跳 / 多跳 / 结构) ← 分流到不同管道 ↓ Agentic RAG (retrieval-as-tool + 自评 + retry + 换策略) ↓ + GraphRAG / Knowledge Graph (结构化导航) ← 多跳 / 跨文档 thematic 才需要
技术一句话何时用代价
Hybrid Search (BM25 + dense + RRF)关键词 + 语义混合，Reciprocal Rank Fusion 合并2026 production 起点，目标 recall@10 ≥ 91%（VectorHub 基线）维护两个索引
Cross-encoder Re-rankingtop-N 用 cross-encoder 重排取 top-K提高 precision；hybrid 之后必加加延迟
HyDE (Hypothetical Document Embeddings)LLM 先生成"假设答案"，用假设答案 embedding 检索用户 query 跟文档语言风格差异大时1 次额外 LLM 调用
RAPTOR递归聚类摘要，多级查询既要事实又要主题概览indexing 成本
Self-RAG / CRAGretrieval 后自评，不行回头重检索容错与多策略多次 LLM 调用
Agentic RAGretrieval-as-tool；agent 选择何时检索 / 用哪个工具 / 评估结果 / 换策略多跳、复杂 query 主流多次 LLM 调用，调度复杂
Query Router小模型分类（单跳 / 多跳 / 结构）分发到不同管道混合 query 场景一次 ~50ms 分类，误路由率 < 5%
GraphRAG / LazyGraphRAG结构化导航，跨文档多跳vector RAG 失败的 case详见 4.3
✓2026 production 经验法则
按顺序加，每加一层都要测量收益：第一周 Hybrid + Rerank，目标 recall@10 ≥ 91%；第二周 加 Query Router，单跳走 naive 多跳走 agent loop；第三周 agent loop 用 max_iterations=1 跑，证明 routing 工作；之后才考虑 HyDE / RAPTOR / GraphRAG，且只对失败 case 加。
!千万不要从 GraphRAG 起步
Microsoft 自己的 LazyGraphRAG benchmark 显示传统 GraphRAG indexing 贵 1000×。除非已经在 Hybrid + Rerank 上撞到具体失败 case，否则不要上。

3.3 上下文工程：在 context window 里管理信息

3.3.1 Lost in the Middle 问题

iLiu et al. 2023 实证
Transformer 注意力呈 U 型曲线 —— 开头和结尾强、中间弱。500K context window 不等于 500K 等权工作记忆。

应对：把关键约束放 prompt 开头 + 结尾；中间放低信号文档；用结构化 summary 而不是流水账。

延伸：Chroma 对 18 个 LLM 的实测证实 context rot——性能在触到 token 上限之前就开始退化，且非均匀、任务相关。是架构问题（可预防），不是模型缺陷。

3.3.2 Token Budget 分配（业界标准）

内容大致预算（tokens）
System prompt500 - 2,000
Retrieved documents (RAG)2,000 - 20,000
Conversation history (compressed)1,000 - 5,000
Tool schemas500 - 3,000
Current task state500 - 2,000
Output headroom2,000 - 8,000

3.3.3 Compaction（压缩）vs SubAgents（分发）

维度Compaction（顺序）SubAgents（并行）
谁触发系统 reactive 或 model 自己（Tape）父代理调度
信息流老 context → summary → 新 context 头部子任务 → 子 context → 返回 summary
Cache 影响一次性 KV cache miss，之后稳定子代理独立 KV cache
何时用单线对话连续多个独立子任务并行

3.3.4 2026 新增的几个上下文管理手段

✓Compaction vs Summarization 优先级
compaction 是剥离别处已存在的冗余（可逆），summarization 是 LLM 压缩历史（有损）。原则：先用 raw history，再 compaction，summarization 只当最后手段。主动在约 60–70% 窗口利用率触发，别等错误出现或窗口耗尽（OpenAI 建议"重大里程碑后" compact）。好的 compaction 必须保留"哪些方案已失败 / 哪些文件已建 / 哪些假设已失效"这类仍约束未来动作的事实。
手段做法
Tool-result clearing抓取后把原始工具输出替换成占位符，保持窗口精简
Context foldingagent 分叉处理子任务，完成后"折叠"——折掉中间步骤、只留结果摘要
ARC（arXiv 2601.12030）把 context 当动态内部状态而非 append-only 记录，解耦"动作执行"与"上下文管理"，检测到错位就主动重组；BrowseComp-ZH 上比被动压缩 +11%

3.4 给读者的选型路线

你的项目推荐起步
个人 / 小团队 / 文档项目PARA folder + 偶尔 Zettelkasten 链接 + 主动 git 提交，不必上 LLM Wiki
中型代码库（10K-50K LOC）文件型 owner（markdown + git）+ grep 检索，够用
代码 + 文档混合，想减 token+ Graphify（一次性 setup）+ PreToolUse hook 拦 grep
跨多 source 持续做研究Karpathy LLM Wiki + Obsidian + Claude Code
企业级 multi-hop 问答 / 客服Hybrid RAG → 加 Re-ranker → 加 Query Router → 最后才 LazyGraphRAG
长会话 agent / 客服 bot+ memsearch 或 claude-mem 做跨 session 记忆

Part 4 · 业界工具与项目地图

按职责分组，覆盖 30+ 主流方案。完整盘点见 .harness/knowledge/industry/HPI-KNW-003。

4.1 入口与跨工具标准

4.2 Spec / Lifecycle 工具

工具强项链接
OpenSpec（~51.6k stars）OPSX 已成默认工作流：core（propose/explore/apply/sync/archive）+ expanded；schema-driven 自定义 artifact；delta spec 适合 brownfieldopenspec.dev
GitHub Spec Kitconstitution / specify / plan / tasks / implement；偏 greenfield、较重github.com/github/spec-kit
Superpowers（Anthropic 官方 plugin，~40.9k stars）把 SDLC 编排成可组合 skill：brainstorm → write-plan → execute-plan；subagent 两段 review + TDD ratchetobra/superpowers
i业界信号
OpenSpec 与 Superpowers 均被 Thoughtworks Technology Radar（2026-04）列为 "Assess"。

4.3 知识图谱型工具（2026-Q2 爆款）⭐

系统关键设计链接
Graphify ⭐ 截至 2026-06 约 57.6k stars / v0.8.27Tree-sitter AST + LLM subagent + NetworkX + Leiden 社区检测；PreToolUse hook 拦 grep；71.5× 减少 token；支持 16+ 工具safishamsi/graphify
code-review-graphblast-radius 分析；SQLite + Tree-sitter；34 MCP tools；6.8-49× 减少 tokentirth8205/code-review-graph
Microsoft GraphRAGknowledge graph + community summaries + 4 query 模式microsoft.github.io/graphrag
LazyGraphRAGGraphRAG 的 1000× 便宜版本benchmark

4.4 Memory / Knowledge 系统

系统关键设计
Karpathy LLM Wiki ⭐三层 raw / wiki / schema；LLM 自己 build + maintain；2026-Q2 跟进出 .brain/ 文件夹、hot.md 热缓存、LLM Wiki v2（typed knowledge graph）
llm-wiki-agentKarpathy gist 的可运行实现
memsearch ccplugin4 shell hook + markdown，跨工具
claude-memNode Worker + SQLite + Chroma + Web UI + MCP；progressive disclosure 3 层
claude-contextMilvus + BM25 + 向量 hybrid 代码搜索 MCP
Letta / MemGPT（2026 Letta V1）Memory blocks（核心 + 档案）；多 agent 共享 block；sleep-time agents（后台 agent 闲时整理记忆）
mem0LLM extraction + vector + entity + graph 混合
Zep / GraphitiTemporal knowledge graph
CogneeOntology + vector + graph + relational
Hermes AgentMEMORY.md + USER.md + SQLite FTS5 + skills

4.5 Agent Harness 库 / Runtime

库定位
LangChain DeepAgents"batteries-included agent harness"
LangGraphState graph + checkpointer + supervisor/handoff
CrewAI FlowsFlow state + persistence
AutoGenMulti-agent with termination conditions
OpenAI Agents SDKHandoffs / input filters / run context
Anthropic Claude Agent SDKInitializer + Coding agent 长任务模板
Anthropic Managed Agents（meta-harness，2026-04-08）brain / hands / session 三分；托管 long-horizon runtime；Outcomes / Multi-Agent / Webhooks / Dreams 把 harness 层产品化

4.6 Lint / 反馈传感器

工具关键设计
AgentLint（agentlint.app / 0xmariowu）第一个 harness-level linter；现 58 checks（51 core / 6 dimensions + 7 opt-in）；40,000-char 硬上限；每条 check 引一手 source；可 auto-fix
agentlint (pypi, AgentChute) — ⚠️ 同名不同项目runtime guardrail + 跨平台事件归一化（非 harness 配置审计）；v2.4.0 76 rules / 8 packs

4.7 Claude Code 上下文管理工具生态（2026 涌现）

来源：Milvus 2026 综述。

层工具解决
压缩命令输出RTKterminal 高频输出在进入 Claude 前压缩
沙箱原始工具输出Context Mode大型 log / DOM 隔离主对话
代码结构图code-review-graph依赖、blast radius 问题不靠 blind 文件读
渐进式读代码Token Savior先 symbol 摘要再展开
压缩 Claude 输出Caveman防 agent 自己的输出污染未来上下文
检索相关代码claude-context语义 / hybrid 代码搜索取代 grep
跨 session 记忆memsearch跨 session / agent / 模型

Part 5 · gewoox-sleepal-app 的 Harness 解剖

本节带你走一遍 gewoox-sleepal-app 项目的 Harness 设计——不是复述 HARNESS_DESIGN.md，而是从 Harness 真实流程切入。详细物理布局见 .harness/knowledge/reference-project/HPI-KNW-101。

5.1 项目背景

维度现状
语言 / 框架Go 1.26 + Gin + GORM + Redis + Nacos + Zap + Google Wire + Kafka/CloudEvents + Dify (AI) + AWS IoT (MQTT)
业务复杂度HTTP API + WebSocket 实时 + AI 对话 + MCP 工具 + 多区域部署 + 多设备同步
Harness 阶段2026-05-16 起系统化建设；截至 2026-05-23 已 archived 36 次 OpenSpec change、42 active owner、12 capabilities SKILL、2 packet-only 子代理；经历 8 个 Phase（A→H）

5.2 物理拓扑：三层 Tier

Tier 1
入口 / 人类层（仓库自有，reorg-safe）
AGENTS.md（27 行）— 跨工具 Agent 入口；HARNESS_DESIGN.md（~580 行）— 人类设计文档。
Tier 2
外部工具协议层（路径硬绑定，不可移动）
.codex/agents/*.toml — Codex CLI 子代理；.codex/skills/*/SKILL.md — Codex Skills；openspec/ — OpenSpec CLI 工作区。搬这些目录直接 break 外部 CLI。
Tier 3
Harness 内部层（仓库自有，subject to reorg）
.harness/STARTUP.md（§1 路由 §2 健康 §3 完成）+ 8 个子目录（governance / knowledge / cognition / capabilities / adapters / scripts / state）。
i三层划分的核心判断
外部工具有它的协议要求，本地 Harness 设计必须尊重这些硬约束。例如 .codex/skills/openspec-propose/SKILL.md 不能搬到 .harness/capabilities/ 下，因为 Codex CLI 启动时按固定路径读取这个文件。

.harness/ 内部 8 层职责

层位置唯一职责不能装什么
EntryAGENTS.md + STARTUP.md启动顺序、任务分类、完成检查长记忆、历史叙事
Governancegovernance/{catalog,lifecycle,discipline,standards}Harness 操作契约业务事实、patch 日志
Knowledgeknowledge/{architecture,conventions,domain}项目架构 + Go 约定 + 业务域Harness 治理契约、当前阻塞
Cognitioncognition/{decision,routing,graph,lifecycle,judgment}决策优先级、路由、关系图、抽取、判断模型项目事实、启动 checklist
Capabilitiescapabilities/{project,harness}/*/SKILL.md可重复 SOP通用记忆
Adaptersadapters/{openai,codex,...}把 capability SKILL 适配到具体工具capability 流程定义
Scriptsscripts/验证 + 索引工具（stdlib only）流程工作流
Statestate/*当前 checkpoint历史叙事

5.4 OpenSpec lifecycle：10 件 artifact

项目当前 active change refresh-harness-design-methodology 的目录结构（按依赖顺序）：

#Artifact解决什么问题
1intake.md + Prior Archive Search不查先例就重新发明
2proposal.md + Alternatives ≥ 2 (含"不做")一上来只给单一方案
3specs/*/spec.md需求不可验证
4design.md实现细节无取舍
5boundary.md + Implementation Gate不读 owner 就改
6design-review.md（人工审批 / 强 waiver）未经设计审查就实现
7tasks.md执行无法分步验证
8review.md + Reviewer Identity主代理自评冒充 review
9verification.md + Plan-Phase Activation Evidence"看起来完成"无证据
10knowledge-extraction.md + Reduction Proofarchive 变黑洞
✓三个核心设计点
  • Prior Archive Search：intake 必须先 grep 历史是否做过类似 change
  • Boundary Human Review Gate：boundary 完成后必须等用户明确 approval 或强 waiver "不需要我审核，你自动执行"，沉默 / 模糊委托都不算
  • Reduction Proof：归档时不只是"把目录移到 archive"，要给出 owner merge 证据表（Archive Section → Merged Into → Status），机器化堵死"archive 黑洞"

5.5 路由系统：27 个 Route Family

.harness/cognition/routing/GSA-COG-100 定义大约 27 个 Route Family。举几个：

Route触发信号Read Order（默认读包）Execution Gate
intake-gate任何不是简单问题 / 小修补STARTUP §1 + GSA-GOV-100 + openspec/README证明 fast path 或路由到 OpenSpec
go-code在 internal/ / cmd/ 改 Go 代码GSA-KNW-001 + GSA-KNW-104 + go-service-workflow SKILLPre-Impl Evidence Gate；Automatic Quick Gate
change-lifecycle业务需求 / 多步骤 / 高风险openspec README + GSA-GOV-100 + GSA-COG-300Intake Gate 后创建 OpenSpec change
episodic-search用户说"上次怎么决定 X"episodic-search SKILL + GSA-GOV-300make episodic-search QUERY="..."
i关键设计点：路由表本身要被 review
修改 GSA-COG-100 触发 route-table-review capability，必须跑一遍专门的 packet-only review。把"路由"当一等工程对象。

5.6 Frontmatter + Plan-Phase Activation：渐进式披露

每个 owner 文件都有一段 YAML frontmatter，8 必填 + 4 可选：

---
id: GSA-COG-100
layer: cognition/routing
owner_role: Route families mapping task signals to owner files
decision_role: route
load_condition: Loaded after GSA-COG-001 identified active layers
route_family: [general-decision, correction-learning]
triggers: [route family, knowledge routing, task signal]
max_lines: 120
paths: ["internal/**/*.go"]    # 可选
supersedes: [GSA-LRN-002]      # 可选
---

Plan-Phase Activation Rules：非 fast-path 任务在 plan 阶段，Agent 先按 description → triggers → paths → route_family 顺序匹配 SKILL 和 owner，只读匹配到的。这是 Claude Skills 风格的渐进式披露在本地 markdown 上的实现。

5.7 子代理：packet-only 模式

.codex/agents/packet_reviewer.toml（只有 11 行）：

name = "packet_reviewer"
description = "Packet-only no-startup reviewer..."
model_reasoning_effort = "low"
project_doc_max_bytes = 0
sandbox_mode = "read-only"
developer_instructions = """
You are a packet-only reviewer...
Do not run repository startup, do not inspect AGENTS.md,
do not read files, and do not call tools.
"""
✓为什么 packet-only
通用 subagent（Codex 默认 explorer / worker）会自动跑仓库 startup、读 AGENTS.md，等于复制一份父代理上下文。packet-only 模式把 review 当成一次纯函数调用：输入是 packet，输出是发现，没有副作用。主代理始终拥有最终判断、文件写入、状态更新、用户响应的所有权。

5.8 三件脚本工具：lint / index / episodic

.harness/scripts/ 严守一个原则：Python 3.10+ stdlib only，不调 LLM，不动 owner 文件正文。

工具产出边界
harness-indexstate/index.json + STARTUP Budget Header不动 lint 输出
harness-lintexit 0/1/2 + JSON/text 报告不动 index / episodic
harness-episodicstate/episodic.db (SQLite + FTS5)只读 archive，不读 active

三件互不调用、各自只写自己的输出文件。这是把"软件工程"形态用到 scripts 层而非"脚本拼盘"。

5.9 知识抽取：archive → owner

完成一次 change 后，durable 经验通过 knowledge-extraction.md 流向 active owner：

archive (process evidence) ─── knowledge-extraction.md ───┐ ▼ ┌───────────────────────────────────────────┴───────────────────────────────────────────┐ │ │ 知识 owner (per category) capabilities/SKILL ├── 项目架构 → knowledge/architecture/ ├── 项目约定 → knowledge/conventions/ ├── 业务域 → knowledge/domain/ ├── Harness 契约 → governance/ └── 决策/路由/图/lifecycle → cognition/
i这套机制的本质
把 OpenAI 案例里 "repo knowledge is system of record" 用 owner 边界 + Reduction Proof 工程化了。archive 是过程证据；active owner 是 source of truth；同一条规则不会同时存在两份。

Part 6 · 参考项目 12 项关键优势（按实际效果评估）

i评估纪律
本节只看"对实际工作的可观察影响"。不以"做了什么手段"为优势——以"实际效果"为优势。每条都给可观测的证据 / 现象。完整 owner 见 .harness/knowledge/reference-project/HPI-KNW-102。
S1
owner 边界 lint 机械化
效果：8 phase 演进中从未出现同一规则在多 owner 漂移；新 reviewer 不会在多处看到矛盾规则；harness-lint --pointer-only / --duplicate-only 实际拦截到 N 次粘贴重复
S2
Plan-Phase 双激活
效果：context 不被噪声淹没；非 fast-path 任务平均只读 5-12 个 owner（vs 全仓库 42 个）；按 frontmatter triggers / paths 自动召回
S3
三套工具独立 / stdlib only
效果：新机器零依赖立刻可用；单工具故障（如 episodic-index 失败）不传染到 lint 和 index；脚本总计 ~1500 行 Python，可读、可维护
S4
OpenSpec 10 件 artifact + 6 道 Gate
效果：6 类常见失败模式（重复发明 / 单方案 / 跳 owner / 跳审批 / 自评通过 / archive 黑洞）有具体 archive 证据被拦截。这是 OpenSpec 原生没有、本地扩展才有的
S5
Boundary Human Review Gate
效果：高风险变更不会被 LLM 自评放行；强 waiver 是逃生口；schema enforce 而不只是文档约定
S6
Packet-only 子代理
效果：subagent 不复制父代理上下文（project_doc_max_bytes = 0）；review 是纯函数无副作用；主代理始终拥有最终判断 / 文件写入 / 状态更新所有权
S7
Reduction Proof + Post-Archive Finalization
效果：36 个 archive 中每个都有 Reduction Proof 表；Post-Archive Checklist 7 项强制；没有出现"archive 黑洞"——每条 durable lesson 都有可追溯的 active owner 落脚
S8
SQLite FTS5 archive 检索
效果：历史决定可机器检索（make episodic-search QUERY="..."）；与 git 友好（数据库 gitignored，事实文件版本化）；不引入外部依赖
S9
路由表本身被 review
效果：8 次 phase 重命名后 routes 仍 0 broken anchor；route-table-review capability 专门 review 路由变更；避免"路由越改越乱"的渐进退化
S10
Methodology Incubation Contract
效果：8 个 phase 演进保持 archive 完整可追溯；guardrail "不要把一个仓库的局部形状误当通用模板" 让 onboarding skill 至今没被过早抽出
S11
Migration Map 强制
效果：Phase E 大重命名（CTL/LRN → GOV/COG）+ Phase G 删除 GOV-400/401 后，所有 archive 引用零 broken；harness-lint --check-migration-coverage 硬强制
S12
Asset Health Trigger-driven
效果：不是 noisy 定时跑，按真实信号触发（lint warning ≥ 10 / state > 60 行 / 3+ archive 无 gardening）；每次 gardening 平均削减 ≥ 50% lint warning（作为 Reduction Proof 强制）
✓12 项优势的核心共性
全部是"把工程经验机械化成契约 + lint + schema"——让经验不再依赖个人记忆。Hashimoto 公式 Agent = Model + Harness 的实质就是这个：模型可以变，但你这套机械化经验是项目的真正资产，模型升级后还能用。

Part 7 · 参考项目 10 项实际不足（按可观察影响，非工具兼容性）

!评估纪律
本节不以"是否引入特定工具（Graphify / AgentLint / Hooks / DeepAgents）"作为评分维度——工具用不用不是判断标准，效果好不好才是。如果自建机制达到了同等效果，"未引入业界工具"本身不构成不足。只列"对实际工作有可观察影响"的项。

当前痛（现在用就会感到）

!W1 · Onboarding 成本：新人 30 分钟+ 才能动手
现象：8 子层 + 3 套编号 + 27 routes + 10 cognition model + 10 件 OpenSpec artifact。
实际影响：跨项目复用受限（知识只能由 1-2 人维护）；团队扩张时新人前两周大概率不敢动 .harness/；外部 contributor 几乎不可能参与。
何时不痛：稳定 2-3 人核心团队、Harness 演进基本完成、不追求外部贡献。
!W2 · 内部术语过多：外部读者难解码
现象："Pre-Implementation Evidence Gate"、"System Surface Consumer Model"、"Plan-Phase Activation Evidence"、"Reduction Proof"、"Boundary Human Review Gate" 等自创术语没有对应业界标准词。
实际影响：owner 文件可读性低（外部读者读 30 行不知道在说什么）；跨项目迁移 ramp-up 慢；内部新 reviewer 难加入。
何时不痛：内部稳定团队、术语已经内化、不追求对外解释。
!W3 · Lint 输出对 agent 不友好：自动修复率低
现象：harness-lint 输出形如 ERROR missing-frontmatter file:1 owner file is missing required YAML frontmatter。告诉了什么错，没告诉怎么修。
实际影响：agent 看到 lint error 后必须自己 reason（重新读 frontmatter 标准、参考其他 owner 模仿），每次浪费几百到几千 token；自动修复成功率明显低于"先 read 标准再 fix"。
何时不痛：lint 主要给人看、agent 出错后人介入修。
!W4 · Behaviour harness 仍依赖人工 review
现象：参考项目自己也明确承认。spec scenarios + product docs + 人工 review 是当前唯一行为对齐手段。
实际影响：AI 生成的测试 pass 不代表产品行为对齐用户意图；任何"用户体验是否更好"的判断都必须有真实用户 / 产品经理介入；高风险变更的 boundary review 时间长。
注：这是行业难题，不是参考项目特有不足。所有面向用户产品都共享。

未来痛（特定条件下才显现）

iW5 · 跨 context window 长任务无内建支持
现象：所有任务用同一主代理；没有 Initializer / Coding agent 分离；没有 context reset 模式。
实际影响：6+ 小时 autonomous 任务（如大型 refactor）超出当前架构能力——主代理 context 会爆炸。
当前场景：本项目定位是 IDE-driven 短任务（30 分钟到 2 小时一个 session），此不足在当前场景完全不痛。
iW6 · 跨 change drift 监控偏被动
现象：Asset Health 是 trigger-driven，不是持续监测。
实际影响：可能 lint warning 累积到 9 个时还没触发，第 10 个时才触发 gardening——期间 drift 已经发生 N 个 change；跨 change 累积熵增没有自动指标。
何时痛：高频 change 项目（每周 5+ archived）、多人并行 agent 改同一仓库。
iW7 · 没有"成本可见性"
现象：每个 route 的 token 估算了，但每条规则的"维护成本"没有量化（review 时间、lint 耗时、subagent 调用频次、archive 体量、人力成本）。
实际影响：难判断哪些 owner 是"高维护成本低收益"的；累积冗余难发现（owner 可能从来没被路由命中、agent 从来没读过，但还在那里）。
何时痛：Harness 已经存活 1+ 年、accumulated 多次 phase、想做 ROI 评估。
iW8 · Archive 的"surprising connections"没自动暴露
现象：archive search 是 BM25 keyword-based。Agent 要主动 grep 才能发现相似先例。
实际影响：archive 数量多了后（>50），"上次我们在某个相似但用不同关键词描述的场景怎么决定的"很难被自动发现；Prior Archive Search 段的填写质量依赖主代理的查询能力。
何时痛：archive > 50 个、跨业务域共享决定。
iW9 · 累积 entropy 没量化指标
现象：行数有 hard cap，但"知识系统总体熵"（owner 之间 cross-reference 图复杂度、平均跳转深度、orphan owner 数）没有量化。
实际影响：Plan-Phase Activation 准确性可能随 owner 数增加渐进下降但无法量化；长期可能某些 owner 实际不再被任何 route 命中（"死 owner"）但行数 / lint 不会报警。
何时痛：Harness 已经存活 6+ 个月、owner 数 ≥ 40。
iW10 · 没有"模型升级 → 简化 Harness"的实际演练
现象：governance/lifecycle 提到 "Re-simplify on model upgrades"，但 36 个 archive 中没有一次"删除某条规则因为模型变强了不需要了"。
实际影响：某些为旧模型设计的规则（如显式 context reset 提示、明确防 hallucination 检查）可能在 Opus 4.5 / GPT-5.2 时代已多余但还在；Harness 越用越厚，其中一部分是"对当前模型已经无效的脚手架"。
何时痛：项目周期长（>6 个月）跨过 1+ 次模型大升级、token 成本敏感。

综合评价

#不足类别实际影响范围
W1Onboarding 成本高当前痛跨项目复用、新人扩张
W2内部术语过多当前痛文档可读性、外部 contributor
W3Lint 输出对 agent 不友好当前痛agent 自动修复率、token 浪费
W4Behaviour harness 依赖人工当前痛行业共性，非参考项目特有
W5跨 context window 长任务无支持未来痛当前场景不痛（IDE 短任务）
W6跨 change drift 监控被动未来痛高频 change 项目
W7没有"成本可见性"未来痛Harness 存活 1+ 年
W8Archive surprising connections 没自动暴露未来痛archive > 50 个
W9累积 entropy 没量化指标未来痛Harness 存活 6+ 个月
W10无 re-simplify 演练未来痛跨过模型大升级
→给读者的判断指引
  • 团队预期 3 → 10 人 → 防 W1 / W2
  • 希望开源 / 跨项目复用 → 防 W1 / W2 / W7
  • Agent 自动修复程度要求高 → 防 W3
  • 6h+ autonomous 任务 → 防 W5
  • 多人并行高频 change → 防 W6 / W9
  • 项目周期 > 1 年 → 防 W7 / W9 / W10
  • Archive 数将 > 50 → 防 W8
  • 面向用户产品 → 防 W4
核心纪律：不要拿参考项目"少了 Graphify / AgentLint / Hooks / DeepAgents"作为不足——这些都是手段。只看实际效果：当前的 6 类失败模式（重复发明 / 单方案 / 跳 owner / 跳审批 / 自评 / archive 黑洞）参考项目通过 OpenSpec 10 件 artifact + 6 道 Gate 已经全部拦住，且有 archive 证据。这才是评判 Harness 好坏的真标准。

Part 8 · 落地路径与取舍判断框架

8.1 第一步：自检

不要看到 gewoox-sleepal-app 有 42 个 owner、36 个归档就想立刻照抄。先做自检：

自检问题如果回答"是"，说明你需要
同一个仓库被 Agent 改超过 50 次（不只 1 次跑通）入口 + 路由 + state
同一种错误 Agent 反复犯项目知识 + 学习沉淀
长任务中断后无法恢复状态与恢复
多人同时让 Agent 改这个仓库显式 owner 边界
你想把同一套规则应用到第二个仓库capabilities + adapters
review 时反复发现同类问题computational sensor + inferential reviewer
Agent 自评说"完成"实际没做对完成定义 + verification
同一个文件被反复改回原样git history 不够，需要 owner + archive
经验只在某个工程师脑子里system of record（项目知识）
Agent 每次跨 session 都要 grep 一遍仓库Graphify / LLM Wiki / 持久 memory
模型升级了但还是同样烂Harness 问题，不是模型问题
!解读规则
"是" ≤ 2：最小版（入口 + 一两个 SKILL）就够；"是" ≥ 5：开始投入；"是" ≥ 8：跳过 Stage 1-2，直接到 Stage 3。

8.2 渐进式落地路径（三阶段）

Stage 1：最小可用 Harness（半天 ~ 1 天）
目标：Agent 知道这个项目是干嘛的，知道哪些事不能做
做这些：
  • 创建 AGENTS.md（≤ 50 行）：项目一句话定位 + 启动顺序 + 高风险命令 + 完成定义
  • docs/architecture.md（≤ 100 行）：分层、命名约定、生成文件列表
  • AGENTS.md 指向 docs/architecture.md
不做这些：30 条 lint rule、向量库、OpenSpec、子代理、Graphify、反思流程
达标信号：Agent 接到陌生需求时不再上来就乱读全仓库
Stage 2：项目知识 + 简单生命周期（3 ~ 5 天）
目标：Agent 能复用 SOP，能产出可 review 的产物
做这些：
  • docs/ 拆 3-5 个 owner 文件
  • 加 frontmatter（至少 id / triggers / paths / max_lines）
  • .harness/capabilities/<workflow>/SKILL.md（≤ 150 行）
  • 任务分类：fast path vs lifecycle
  • 5 件 artifact 模板：intake / tasks / review / verification / extraction
  • 5-10 行 shell 脚本做最小 lint
不做这些：OpenSpec CLI、27 个 route family、packet-only 子代理
Stage 3：路由 + 反馈 + 子代理 + 图谱化（2 ~ 4 周）
目标：Harness 自己能扛跨任务漂移，review 不靠纯人力
做这些：
  • 正式 lifecycle 工具（OpenSpec）+ 自定义 schema
  • 正式路由表（≥ 5 个 route family）
  • packet-only 子代理做 Quick Gate review
  • 项目级 lint 用 Python/shell 实现（最关键 3-5 条规则）
  • state/current-status.md + state/resume.md（≤ 60 行）
  • 全部 SKILL / owner / route table 加 frontmatter
  • 简单 episodic search（grep / ripgrep）
  • CI 加 agentlint scan（2026-Q2 新工具）
  • 代码库 ≥ 30K LOC 且常 grep 时：跑 Graphify 试一次
Stage 3 之后：trigger-driven 维护
不是阶段升级，而是日常维护
按真实信号触发：lint warning 累积 ≥ 10 / state 超 60 行 / 3 个 change 归档但 archive 没人回头读 / 两个 owner 内容重复 / 命令反复手敲 / 重命名后 archive 旧引用找不到 / 同种 review 发现反复出现 / 模型升级跑 re-simplify sweep / 代码 grep 频繁 token 高。

8.3 六个判断模型（取舍判断框架）

遇到新组件 / 新工具 / 新方法时不用从头思考，按这 6 个模型筛一遍就能做决策：

M1
Scale-Driven Form（规模决定形态）
个人 POC ≤ 1K LOC → AGENTS.md + 1 SKILL 停。中型 10K-50K → 3 owner + 简单 lint。大型 50K+ → 完整 lifecycle + subagent + Asset Health。不要把大型项目的 Harness 套到小项目，反之亦然。
M2
Guides vs Sensors Balance（双轴平衡）
Agent 反复犯规 → 缺 sensors；频繁犹豫 / 重新发明轮子 → 缺 guides；单次对但长期变烂 → 缺 drift sensors。Fowler 2026-05 强调："sensors 是被低估的那一半"。
M3
Computational vs Inferential
能用 computational（lint / tests / structural checks）的，不要交给 LLM 判断。只有语义、架构、产品取舍才用 inferential 或 human gate。
M4
File vs Runtime Memory
项目工程纪律应该可 diff / review / cherry-pick → 文件型（markdown + git）。只有动态、多用户、跨会话对话 agent 记忆才需要 runtime 型。
M5
When to Skip（什么时候跳过）
业界都说 X 重要要不要做？问：① 不做会怎样？不会怎样就不做。② 边际成本 vs 边际收益？看数据不看声誉。③ 维护负担？YAGNI 在 Harness 上同样适用。
M6
When to Re-Simplify
Anthropic 2026-03 原则。触发：① 模型升级（Sonnet 4.5 → Opus 4.5 让 context anxiety 消失）② route 长期不命中 ③ 规则 ≥ 3 owner 重复 ④ lint warning 累积。注释掉一个组件跑一周，看会不会出问题。
→用法：遇到新东西按 M1→M6 顺序筛
  1. M1：我项目规模匹配吗？不匹配 → 跳过
  2. M5：跳过代价大吗？代价小 → 推迟
  3. M2：我现在最痛是缺 guide 还是 sensor？不是这个解决的 → 推迟
  4. M3：computational 还是 inferential？选合适形态
  5. M4：file 还是 runtime？选合适存储
  6. 落地后：用 M6 反思是否到了 re-simplify 时机

8.4 不要犯的常见错误

错误后果怎么避免
把所有规则塞进 AGENTS.mdcontext rot，关键 rule 被淹AGENTS.md 只做指针
复制粘贴同一规则到多个 ownerdrift一个 canonical owner，其它指针
让 owner 自己长上千行维护成本爆炸max_lines 预算 + lint 强制
state 写成历史流水账启动浪费 token每行必须改变下一步动作
把 archive 当 owner经验永远不会被检索knowledge-extraction.md + Reduction Proof
子代理跑仓库 startup浪费 token、误读父代理状态packet-only
完成定义靠"看起来对"自评通过实际跑偏acceptance ↔ verification 一对一映射
路由表越加越多检索负担上升加新 route 前看能不能扩展现有 route
Harness 越来越厚没 GC信号密度下降Asset Health triggers + gardening
一开始就抽 meta-skill局部形态当通用规则至少 2-3 个仓库验证后再抽
从 GraphRAG 起步indexing 贵 1000×先 Hybrid + Rerank，再加图
模型升级后 harness 一动不动不必要的复杂度累积每次升级跑 re-simplify sweep

8.5 什么时候该 stop（不做 Harness 反而对）

!这些场景做最少 Harness 就够
  • 项目还是 demo / POC，3 天就废：用最小 AGENTS.md 就够
  • 项目只有 1 工程师 + 1 Agent，没有跨人 / 跨会话复用需求：state 文件可能就够
  • 项目没有清晰"完成定义"（创意类、研究类）：先把完成定义想清楚再谈 Harness
  • 团队对 Agent 还没建立工作流：Harness 是"放大器"，没有工作流的话只会放大混乱

附录 A · 一手资料与开源项目链接

A.1 核心方法论文章

A.2 知识图谱型工具（2026-Q2 ⭐）

A.3 检索方法论

A.4 知识管理方法论

A.5 文件型 / coding-agent 实践

A.6 Memory / Spec / Runtime

— Harness Engineering 落地方案专家
2026-06-01