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/<name>/ 下有独立的工作日志（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 是部门规章——告诉你这个部门怎么做事
• 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/<session-key>.json 维护了"当前会话正在处理哪个任务"。这意味着：

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

4.3 三角色子代理

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

这种职责分离是工程化的关键。让同一个 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 让你"有效地找代码"，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 #工程化 #小凯