本文整理自内部项目分享会，系统梳理了几种主流 AI Agent Harness 方案的对比，以及我们团队最终选择并落地 Trellis 框架的完整过程。

---

一、为什么需要 Harness？

随着 Claude Code、Cursor、Codex 等 AI 编程助手的广泛使用，开发者越来越明显地感受到一个问题：模型本身的能力在提升，但"用好模型"的工程问题并没有自动解决。

这些工程问题主要体现在三个方面：

• 会话失忆（Session Death）：每次开启新对话，AI 就遗忘了项目背景和上次进度，开发者不得不反复重新解释。
• 规则文件失控：把所有规范塞进单个 .cursorrules 或 CLAUDE.md，文件越来越臃肿，AI 容易出现"上下文过载"并忽略关键细节。
• 多任务并行冲突：让 AI 在同一分支下并发处理多个任务，极易互相覆盖代码或产生 Git 分支冲突。

Harness 正是为解决这些问题而生的一层"工程外壳"——它在模型能力之上构建系统约束，帮助 AI 更稳定、更规范地工作。

值得注意的是，Harness 的每个组件本质上都是对"模型还不能自己做到某件事"的假设。随着模型基础能力不断提升，这些假设需要持续被验证，过时的组件也应该及时精简。

“Every component in a harness encodes an assumption about what the model can’t do on its own, and those assumptions are worth stress testing.”
—— Anthropic 研究团队

---

二、三类主流 Harness 方案对比

目前社区中的 Harness 方案大致可以归为三类：

1. 流程强化型 —— Superpowers

Superpowers 将自己定位为 agentic skills framework & software development methodology，核心是把 brainstorming、plan、TDD、review 等流程串成一套有强约束的开发工作方式。它解决的问题是"Agent 应该按什么工程纪律做事"。

优点：

• 内置"头脑风暴"环节，有助于完善想法、暴露不成熟的问题
• worktree 独立工作区，减少 AI 误操作导致不可恢复的后果
• 合并了探索、需求草案、方案设计、todo 拆解，适合零基础用户快速 vibe 出原型

缺点：

• 哪怕是小任务，也会反复确认和追问，流程偏重，不够快捷
• 框架上下文注入量大，在长对话（如 5.4x high 倍率）下容易把上下文跑空，自动压缩后细节丢失
• 缺少持久化记忆，项目内的特化约定需要反复重新说明

2. 规格沉淀型 —— OpenSpec

OpenSpec 的核心是给 AI 开发增加一层 lightweight spec layer，强调"先对齐，再实现"。每次变更都组织成 proposal → spec → design → tasks 的结构化产物，并为每个改动创建独立文件夹，方便追踪和归档。

优点：

• 把项目规范写成结构化文档，让 AI 在编码前先读规范
• 将老成员经验中的隐性约定（目录结构、命名规范、错误处理原则）显式化
• 更容易让 AI 输出贴近团队既有风格的代码

缺点：

• 文档写出来后，AI 是否每次都读、是否真正遵守，仍然不确定
• 上下文变长后，spec 容易被"遗忘"
• 只关心文档，缺少类似头脑风暴这样帮助完善需求的配套 skill

3. 多 Agent 编排型 —— oh-my-claudecode

oh-my-claudecode 定位为 Multi-agent orchestration for Claude Code，在 Claude Code 之上封装了一层多 Agent 协作机制，让 planner、executor、reviewer、debugger 等不同角色分工处理复杂任务。

优点：

• 阶段式流水线更适合复杂任务的拆解与并行推进
• 提供 /autopilot、/team、magic keywords 等低门槛入口
• 支持 Claude、Codex、Gemini 等多模型协同，适合交叉评审

缺点：

• 编排层较重：官方参考文档包含 29 个 agents、35 个 skills、20 个 hooks、11 个生命周期事件，排查成本高
• 对 Claude Code Plugin 体系依赖较强，接入侵入性大
• 更适合复杂任务，对简单任务容易"过度编排"

三类方案横向对比

维度	Superpowers	OpenSpec	oh-my-claudecode
核心解决的问题	工程流程纪律	规格沉淀与对齐	复杂任务编排
上手门槛	低	中	中
系统复杂度	中	低	高
持久化记忆	✗	部分	✗
适合场景	原型/小团队	规范化团队	复杂多 Agent 任务

---

三、Trellis：全链路落地框架

项目地址：https://github.com/mindfold-ai/Trellis

Trellis 是一个高级 AI Agent 工作流与编排框架（Agent Harness）。它的核心理念是：“教 AI 认识你的项目，只需一次。”

通过分层的规范体系、任务上下文隔离以及工作区持久记忆，Trellis 为所有 AI 工具提供了一个统一的"外接大脑"。

1. 三层核心架构

.trellis/
├── spec/          # 规范层：编码标准、目录规则、Code Review 习惯
├── tasks/         # 任务层：结构化 PRD、实现上下文、任务状态
└── workspace/     # 记忆层：工作日志，解决"会话失忆"问题

spec/ 规范层：按需加载，只向 AI 注入与当前任务相关的规范，避免一次性塞入所有内容导致上下文过载。规范文件支持动态演进——每次需求完成后，Trellis 会检查是否产生了新的最佳实践并自动更新（Claude Code 专属，其他工具需手动触发）。

tasks/ 任务层：每个 Task 是一个有物理目录、独立记忆和层级关系的开发容器，由 task.json（元数据）和相关需求文档组成，支持父子任务拆解（subtasks）。

workspace/ 记忆层：这是解决"会话失忆"的核心。工作日志（Journals）记录上次会话执行了什么、发现了什么 bug、下一步要做什么。每次新会话开始时，AI 先读取日志，无缝接续上次的思考逻辑。

2. Task 生命周期

Trellis 对任务状态有严密的生命周期设计，每个阶段都可以触发对应的自动化钩子（Hooks）：

Created → Started / In Progress → Finished → Archived
  ↓              ↓                    ↓           ↓
生成文件      持续追踪进度         Code Review   移出高优先记忆区
after_create  after_start          after_finish  after_archive

• Created：任务创建，生成 task.json，可触发 after_create 钩子
• In Progress：AI 投入任务，配合 Git Worktrees 与工作日志持续编码
• Finished：功能开发完成，触发 Code Review，对照 Spec 检查代码规范
• Archived：任务封存，防止污染未来新任务的上下文

3. JSONL 上下文配置

Trellis 用 JSONL 文件精确控制每个 Agent 需要读取哪些文件，实现"渐进式披露"而非一股脑注入：

文件	用途	典型内容
implement.jsonl	实现阶段	workflow.md + 相关 spec + 代码模式示例
check.jsonl	代码检查阶段	finish-work.md + check 命令 + 相关 spec
debug.jsonl	调试阶段	相关 spec + check 命令

---

四、实际工作流演示

以一个真实开发场景为例，展示完整的 Trellis 使用流程。

Step 0：初始化（仅需一次）

# Claude Code / Cursor
trellis init -u your-name

# Codex
trellis init --codex -u your-name

your-name 会成为你的开发者身份标识，并创建个人工作区 .trellis/workspace/your-name/。

Step 1：沉淀项目规范

初始化后，利用 AI 读取现有的优质代码模块，自动起草规范草案，再由资深开发人员用 /update-spec 微调核心架构规则（数据库约定、组件复用逻辑等），保存至 .trellis/spec/。

以我们的后端项目为例，spec 目录最终沉淀了以下规范文件：

.trellis/spec/backend/
├── index.md                      # 规范总索引
├── directory-structure.md        # 模块组织与命名规范
├── database-guidelines.md        # DAO 模式、分片、缓存、SQL 安全
├── error-handling.md             # 错误码定义与传播链路
├── logging-guidelines.md         # slog（新）vs tlog（废弃）使用
├── grpc-guidelines.md            # gRPC 服务发现、拦截器
├── middleware-routing-guidelines.md  # Gin 中间件、路由分组
└── quality-guidelines.md         # Lint、测试、Code Review 规范

效果：当你说"帮我写个读取 xxx 数据的接口"时，不需要每次重复"要用 slog 打日志，数据库遍历用游标不要执行耗时操作"——Trellis 会自动将相关 Spec 注入上下文。

Step 2：创建并拆解任务

现在需要改动 xxx 功能，需求是这样的：xxxx，这是相关的文件 @文件1 @文件2
创建 trellis 任务，同时补充 jsonl 配置文件，视情况拆分为 subtasks

Trellis 会自动创建任务目录下的所有文件：task.json、prd.md、implement.jsonl、check.jsonl、debug.jsonl。

如果需求不明确，可以先用 /brainstorm 命令进行头脑风暴。

Step 3：遵循规范的编码

新开会话，执行 /start 注入 Trellis 上下文（Claude Code 无需此步骤），然后开始任务：

现在开始执行 xxx 任务

AI 在写代码前会先调用 skill 获取对应的 spec，写完后再次调用工具验证是否符合规范。

Step 4：代码检查

/check-backend    # 检查后端代码
/check-frontend   # 检查前端代码

使用较强模型时，AI 在写代码过程中就会执行自检；模型能力有限时，可手动触发。

Step 5：会话中断与持久化

当上下文窗口接近上限，或你准备下班时：

我要结束当前会话了。请使用 Trellis 记录当前进度到 Journal。
记录重点：Service 层逻辑已写完，但 validate() 方法中
关于"工单状态检查"的逻辑还没通过单元测试，明天需要先修这个。

Trellis 会在 .trellis/workspace/journals/ 下生成带时间戳的工作日志。

Step 6：恢复上下文

第二天，打开全新的空白对话窗口：

加载任务 feat-quality-inspection。读一下昨天的 Journal，告诉我接下来该做什么。

AI 读取记忆和任务进度，无缝继续执行——就像从没中断过一样。

---

五、团队协作最佳实践

文件管理原则：

文件/目录	协作方式
workspace/{name}/	每人独立目录，互不干扰
.developer	gitignored，完全个人化
并行任务的 worktree	物理隔离，杜绝冲突
spec/	多人可能同时修改，通过 PR 审查
tasks/	多人可能操作同一任务，需要协调

规范沉淀即资产：当团队成员解决了一个容易让 AI 踩坑的问题，只需将这段经验写入 Spec 并提交代码库，其他人的 AI 助手拉取代码后就能立刻"学会"这个新技能。这是 Trellis 最核心的团队价值之一。

也可以使用 /break-loop 命令触发 Bug 分析流程——AI 会深度分析 bug 根因，并自动更新 spec 约束，防止下次再犯。

---

六、总结

从 Superpowers 的流程强化、OpenSpec 的规格沉淀，到 oh-my-claudecode 的多 Agent 编排，再到 Trellis 的全链路落地，各方案侧重不同，选择取决于团队当前最迫切的痛点：

• 流程混乱、缺乏规范 → Superpowers 或 Trellis
• 规范存在但难以传递给 AI → OpenSpec 或 Trellis
• 任务复杂、需要多 Agent 分工 → oh-my-claudecode

目前 AI Coding 整体仍处于探索阶段，业界尚未形成统一范式。模型能力在快速演进，工具链在持续迭代，今天的最佳实践明天可能就会被更简单的方式替代。

但有一件事不会随范式变化而过时：从现在开始积累属于自己业务线的数据资产。 无论是代码规范、架构决策、任务拆解记录，还是 AI 与人协作过程中沉淀下来的 spec 文档，这些资产都是迁移到任何新范式时最快的起跑线。

模型会换，工具会换，但对业务上下文的深度理解是无法被替代的护城河。