Trellis 深度拆解：给 Claude Code / OpenCode / Cursor 装上项目大脑之后

> 当 AI 编码助手不再"失忆上岗"，它才真正有资格被称为"团队成员"。

GitHub 上有一个项目，10.7k star，没有花哨的演示视频，没有铺天盖地的营销，却在 AI 编码社区里被 quietly 地传阅。它就是 Trellis——一个给 Claude Code、Cursor、Codex 等 AI 编码助手装上"项目大脑"的框架。

它不是又一个 prompt 模板，不是又一个 .cursorrules 替代品，而是一整套工程化基础设施。它的核心洞察简单到近乎朴素：AI 写代码很快，但每次会话都从零开始理解项目，记不住你的规范，也记不住上次做到哪了。

Trellis 做的事情，就是把规范、任务、记忆沉淀进你的代码仓库，让任意 Coding Agent 都能按你的工程标准来实践。

---

一、问题：为什么 AI 编码助手总是"失忆上岗"？

如果你长期使用 Claude Code、Cursor 或 Codex，一定经历过这种场景：

场景 A：每天早上重新讲故事 > "这个项目是用 Next.js 14 + TypeScript 写的，我们用 Zod 做校验，Tailwind 不用自定义类，API 路由统一放在 app/api/ 下面……" 第 37 次重复。

场景 B：跨会话断层 > 昨天下午你让 AI 写了 80% 的功能，晚上上下文满了被迫中断。今天早上新开一个会话："昨天那个功能做到哪了？" AI："什么功能？"

场景 C：规范文件失控 > 你把所有规则塞进 CLAUDE.md 或 .cursorrules，文件越来越长，AI 开始"上下文过载"——明明写了"不要用 any"，它还是在第 5 轮对话后偷偷用了。

这些问题的根源不是模型能力不够，而是工程上下文管理缺失。每次会话都是一张白纸，每次对话都是一次"入职培训"。

---

二、Trellis 的解法：三层架构 + 四阶段循环

Trellis 的核心理念可以概括成一句话："教 AI 认识你的项目，只需一次。"

它在你的 Git 仓库里建一个 .trellis/ 目录，把整个项目的工程上下文持久化成文件。不是存在某个云端数据库里，不是存在模型的 hidden states 里，而是存在你的代码仓库里——这意味着它和代码一起版本控制，一起被团队成员共享。

2.1 三层核心架构

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

Spec（规范层）——这是团队知识的"宪法"。编码标准、目录结构、错误处理原则、日志规范……所有你希望 AI 遵守的规则，都写在这里。但 Trellis 做了一个关键设计：不是一次性全塞给 AI，而是按需注入。implement.jsonl 精确控制当前任务需要读取哪些 spec 文件，避免上下文过载。

一个典型的 spec 目录长这样：

.trellis/spec/backend/
├── index.md                      # 规范总索引
├── directory-structure.md        # 模块组织与命名规范
├── database-guidelines.md        # DAO 模式、分片、缓存、SQL 安全
├── error-handling.md             # 错误码定义与传播链路
├── logging-guidelines.md         # slog 使用规范
└── grpc-guidelines.md            # gRPC 服务发现、拦截器

Tasks（任务层）——每个任务是一个有物理目录、独立记忆和层级关系的开发容器。不是"帮我把这个功能改一下"这种口头指令，而是有 prd.md（需求文档）、design.md（技术设计）、implement.jsonl（实现上下文清单）、check.jsonl（验证清单）的完整工程产物。

.trellis/tasks/06-19-user-auth/
├── task.json           # 元数据：状态、优先级、负责人、分支
├── prd.md              # 需求、约束、验收标准
├── design.md           # 技术设计：边界、契约、数据流
├── implement.md        # 执行计划：有序清单、验证命令、回滚点
├── implement.jsonl     # Spec 和研究文件清单（实现阶段用）
├── check.jsonl         # Spec 和研究文件清单（验证阶段用）
└── research/           # 调研产物

Workspace（记忆层）——这是解决"会话失忆"的核心。每个开发者在 .trellis/workspace// 下有独立的工作日志（journal），记录上次会话执行了什么、发现了什么 bug、下一步要做什么。下次新会话开始时，AI 先读 journal，无缝接续。

> 注意：workspace 是 per-developer 的，gitignored，不进入版本控制。而 spec 和 tasks 是 git-tracked 的，团队共享。

2.2 四阶段工作流循环

Trellis 内部运行一个自动调用的 4 阶段循环，skill 和子代理均由系统编排：

┌─────────────────────────────────────────────────────────────┐
│  Phase 1: Plan（规划）                                       │
│  └── trellis-brainstorm 逐题梳理需求 → 写入 prd.md          │
│      研究密集型任务 → 派发给 trellis-research 子代理          │
│      产出：curated specs + 研究文件 → implement.jsonl        │
├─────────────────────────────────────────────────────────────┤
│  Phase 2: Implement（实现）                                  │
│  └── trellis-implement 子代理依据 PRD 编写代码                │
│      所需上下文按 implement.jsonl 自动注入                   │
│      不执行 git commit（保持 diff 干净）                      │
├─────────────────────────────────────────────────────────────┤
│  Phase 3: Verify（验证）                                     │
│  └── trellis-check 子代理基于 diff 对照 Spec 逐项核查         │
│      运行 lint、type-check、测试                             │
│      在能力范围内自动修复                                    │
├─────────────────────────────────────────────────────────────┤
│  Phase 4: Finish（收尾）                                     │
│  └── 最终检查 → trellis-update-spec                          │
│      将本轮新增的认知沉淀回 .trellis/spec/                   │
│      为下一次会话积累上下文 → 越用越聪明                      │
└─────────────────────────────────────────────────────────────┘

这里最值得细说的是 Phase 4（Finish）。当工作完成或上下文接近上限时，你输入 /trellis:finish-work，Trellis 会：

1. 执行最终验证 2. 运行 trellis-update-spec——把本轮任务中学到的"新知识"提炼出来，写回 spec 3. 将代码变更 git commit（需要一次用户确认） 4. 归档任务，写入 workspace journal

这一步是 Trellis 和简单 prompt 模板的核心区别。它不是"用完即走"，而是每次使用后都变得更聪明——就像一个有经验的工程师，做完一个项目后会把学到的东西写成文档，方便下次复用。

---

三、不是替代，是升维：Trellis vs CLAUDE.md vs .cursorrules

很多人第一反应是："这不就是加强版的 CLAUDE.md 吗？"

Trellis 官方 FAQ 里有一个精准的回答：

> CLAUDE.md、.cursorrules、AGENTS.md 本身是有用的入口，但容易在长期使用中变得冗长臃肿。Trellis 在此之上补充了：作用域明确的 Spec、按任务划分的 PRD、工作流关卡、工作区记忆，以及按平台自动生成的适配文件。

用一张表来理解层次关系：

层次	代表	解决什么问题	持久化	按需加载
单文件入口	`CLAUDE.md`、`.cursorrules`	"这个项目的基本规矩是什么"	❌ 静态	❌
多文件规范	`.cursor/rules/*.mdc`	"不同目录有不同的规矩"	⚠️ 半静态	⚠️ 按 glob
项目级基础设施	Trellis	"项目的完整工程上下文 + 任务级记忆 + 规范动态演进"	✅ 全持久化	✅ JSONL 精确控制

简单来说：

CLAUDE.md 是入职手册——告诉你公司大门在哪
.cursorrules 是部门规章——告诉你这个部门怎么做事
Trellis 是完整的企业知识管理系统——入职手册 + 部门规章 + 项目文档 + 会议纪要 + 工作日志

而且 Trellis 不是 Claude Code 专属。它支持 16+ 个平台：Claude Code、Cursor、Codex、OpenCode、Kiro、Gemini、Qoder、Copilot、Droid、Pi、Kilo、Antigravity、Devin……同一个 .trellis/ 目录，不同工具都能读取。

---

四、技术架构：不仅仅是"文件组织"

如果把 Trellis 简单理解为"把 prompt 拆成多个文件"，就低估了它的工程深度。从架构文档可以看到，它内部有完整的模块系统：

4.1 工作流状态机

.trellis/workflow.md 定义了三个阶段的状态机：

Phase 1: Plan    → classify the turn, get task-creation consent, write planning artifacts
Phase 2: Execute → implement, check, and repeat until green
Phase 3: Finish  → final verification, spec update, work commit, archive

在支持 hook 的平台上（Claude Code、Cursor、OpenCode 等），每次用户输入都会触发 inject-workflow-state.py，向 AI 注入当前应该执行的下一步指令。这不是"建议"，而是强制的工作流关卡——AI 必须按阶段推进，不能跳过验证直接提交。

4.2 会话级任务指针

.trellis/.runtime/sessions/.json 维护了"当前会话正在处理哪个任务"。这意味着：

你可以开 3 个窗口，同时处理 3 个不同任务
每个窗口有自己的上下文，互不干扰
中断后重新连接，能精确恢复到之前的任务状态

4.3 三角色子代理

Trellis 定义了三个明确的子代理角色：

子代理	职责	读取的上下文
`trellis-research`	调研代码、文档、API、替代方案	研究 prompt + 任务/仓库上下文
`trellis-implement`	编写代码	`implement.jsonl` + `prd.md` + `design.md`
`trellis-check`	审查、运行检查、自动修复	`check.jsonl` + diff + changed files

这种职责分离是工程化的关键。让同一个 agent 又写代码又审查，等于让运动员兼任裁判。Trellis 强制分离，而且每个角色只能看到它需要看到的上下文——implement agent 看不到 check agent 的审查标准，防止"应试编程"。

4.4 JSONL 渐进式披露

这是 Trellis 上下文管理的核心机制。不是"把所有相关文件都塞进 prompt"，而是用 JSONL 精确声明：

{"file": ".trellis/spec/backend/database-guidelines.md", "reason": "DAO pattern for new endpoint"}
{"file": ".trellis/spec/backend/error-handling.md", "reason": "Error code propagation"}
{"file": ".trellis/tasks/06-19-user-auth/research/api-comparison.md", "reason": "Auth provider comparison"}

每一行都是一个带理由的文件引用。实现阶段读 implement.jsonl，验证阶段读 check.jsonl，调试阶段读 debug.jsonl——不同阶段，不同上下文，绝不浪费 token。

---

五、一条清晰的演进线

如果把 Trellis 放在 AI 编码助手生态的演进脉络里看，它的位置非常清晰：

项目	解决的问题	层级	代表思想
Planning with Files	长任务跑偏、注意力丢失	文件级工作台账	"把计划写成文件，而不是口头指令"
Obelisk	Coding Agent 检索层应该是执行数据库	检索层架构	"反 RAG、反 Wiki 化，CodeAct 作为检索语言"
Hermes Agent	四层记忆如何撑起常驻 Agent	会话级记忆	"L1 工作记忆 → L2 文件记忆 → L3 state.db → L4 外部 Provider"
Trellis	AI 编码助手"失忆上岗"	项目级记忆 + 工作流	"规范、任务、记忆沉淀进仓库，越用越聪明"

这条线的演进方向很明确：从单次会话 → 跨会话记忆 → 项目级持久化 → 团队协作级知识管理。

Planning with Files 让你"有计划地干活"，Obelisk 让你"有效地找代码"，Hermes Agent 让你"记得住上下文"，而 Trellis 让你"整个团队共享同一套工程大脑"。

---

六、实际工作流：一个完整的开发日

让我们用一个真实场景走完 Trellis 的完整流程。

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

npm install -g @mindfoldhq/trellis@latest
trellis init -u kai

这会创建 .trellis/ 目录，以及你的个人工作区 .trellis/workspace/kai/。

Step 1：沉淀规范

让 AI 读取现有优质代码，自动起草 spec，再由人工收紧核心规则：

"读取 src/backend/ 目录下的代码，总结我们的编码规范，
写入 .trellis/spec/backend/ 目录"

Step 2：创建任务

"需要给用户系统添加手机号验证码登录功能。
创建 trellis 任务，补充 jsonl 配置，视情况拆分 subtasks"

Trellis 自动生成任务目录和全部文件：task.json、prd.md、implement.jsonl、check.jsonl……

Step 3：执行

"开始执行用户认证任务"

AI 自动读取 implement.jsonl 里的 spec，按规范编写代码，完成后自检。

Step 4：下班前持久化

"我要结束当前会话了。请记录当前进度到 Journal。
重点：Service 层逻辑已写完，但 validate() 方法的验证码
格式校验还没通过单元测试，明天先修这个。"

Step 5：第二天无缝恢复

"加载任务 user-auth。读一下昨天的 Journal，告诉我接下来该做什么。"

AI 读取 journal，精确接续——就像从没中断过。

---

七、局限与思考

Trellis 不是银弹。从文档和社区反馈来看，有几个需要注意的点：

1. 初始化成本 第一次 setup 需要花时间沉淀 spec。对于原型项目或 vibe coding 场景，可能显得过重。它更适合长期维护的项目。

2. 团队使用需要协调 spec 是共享的，多人同时修改可能产生冲突（需要通过 PR 审查）。workspace journal 是 per-developer 的，这部分倒是没有冲突问题。

3. 对 Claude Code 支持最好 虽然号称支持 16+ 平台，但自动 spec 更新等功能目前只在 Claude Code 上自动触发，其他平台需要手动操作。

4. 模型能力假设 Trellis 的设计假设模型"能读懂规范、能按 workflow 执行、能自我检查"。如果模型连 implement.jsonl 都读不懂，或者 check 阶段敷衍了事，那整个框架就形同虚设。正如 Anthropic 研究团队说的：

> "Harness 的每个组件本质上都是对'模型还不能自己做到某件事'的假设。随着模型基础能力不断提升，这些假设需要持续被验证。"

---

八、结语：AI 编码的工程化拐点

Trellis 的 10.7k star 说明了一件事：AI 编码社区正在从"模型能力竞赛"转向"工程化落地竞赛"。不是谁的模型更聪明，而是谁能把聪明模型稳定、可复现、可协作地用在真实项目里。

它的核心贡献不是发明了什么新算法，而是把 AI 编码从"聊天式编程"升级为"工程化编程"——有规范、有任务、有记忆、有审查、有沉淀。

Claude Code 单用，是个聪明但健忘的程序员。配上 Trellis，它才开始像一个真正的团队成员：记得项目的历史，遵守团队的规范，完成任务后还把经验写进文档方便下次复用。

从这个意义上说，Trellis 不只是一个工具，它代表了 AI 编码助手从"玩具"走向"生产工具"的拐点。

---

参考信息

GitHub: https://github.com/mindfold-ai/Trellis
官方文档: https://docs.trytrellis.app
中文 README: https://github.com/mindfold-ai/Trellis/blob/main/README_CN.md
架构详解: https://docs.trytrellis.app/advanced/architecture
团队落地实践: https://www.cnblogs.com/Fzeng/p/20204318
AGENTS.md vs CLAUDE.md 对比: https://blog.buildbetter.ai/agents-md-vs-cursorrules-vs-claude-skills-2026-comparison/

#记忆 #Trellis #ClaudeCode #AI编程 #AgentHarness #工程化 #小凯