Trellis：从 vibe coding 到 spec coding 的工程化实践#

1. 背景：vibe coding 的三类问题#

vibe coding 指把需求交给 AI、由它自主完成编码的工作方式。在模型能力足够强、任务足够简单时，这种方式效率很高。但项目一旦进入长期维护，就会持续受到三类问题的困扰。

其一，输出不稳定。 同一项需求，在不同会话里可能得到风格迥异的实现。代码是否遵循 lint、是否使用类型、命名是否统一，取决于当次对话的上下文，难以预测。

其二，上下文随会话丢失。 新会话开始时，AI 不记得上一次完成了什么，也不记得项目里已经约定过的规则。开发者需要反复解释相同的内容，协作成本随之上升。

其三，规范散落在代码库之外。 项目的约定通常存在于 PR 评论、即时通讯消息和资深成员的记忆里，AI 无法读取，只能依据自身的通用习惯进行编码，而这些习惯往往与团队的实际约定不一致。

由此得出的一个基本判断是：值得长期积累的资源不是代码本身，而是规范。

2. Agent = Model + Harness#

可以把一个 AI agent 拆成两个部分来理解。

Model：模型本身，负责理解、推理以及代码生成。
Harness：模型之外的一整套工程规范，包括项目规范存放在哪里、任务状态如何管理、上下文如何注入、经验如何沉淀、工具如何调用、边界如何划定。

现有讨论大多把注意力集中在 Model 一侧。但在实际项目中，Model 再强也无法得知几个月前团队为何作出某项设计决策。这类「项目事实」只能由 Harness 一层承载。

3. prompt / rules / skill 的局限#

为约束 AI 的行为，通常会维护规则类资源，但单独使用其中某几样都存在明显局限。

prompt 不持久。 会话结束后内容即消失，新会话需要重新说明，或让 AI 通过对比代码 diff 来推断上下文。这不仅消耗 token，也无法保证 AI 真正理解了既定的规范。
规则文件因工具而异。 AGENTS.md、CLAUDE.md、.cursorrules 等文件虽可持久生效，但 .cursorrules 属于 cursor、CLAUDE.md 属于 claude code，切换工具就需要重新配置。团队若混用多种工具，无法统一管理这些约束；当某个工具被限制使用时，对应的配置也会失效。
规则文件会不断膨胀。 新的规则持续加入，旧的规则又难以删除，最终文件过长，AI 读取时容易上下文过载，反而抓不住重点。此外，规则本质上是静态的，不知道当前任务进行到哪一步。

核心问题因此不在于「是否需要有规范」，而在于规范能否跨会话、跨工具、跟随任务走，并且能被反复校验与更新。

4. Trellis 的定位与核心概念#

Trellis 的解决思路，是把若干组件串成一条「项目级闭环」：spec（规范）、task（任务）、workspace / journal（记忆）、workflow-state（运行状态）、jsonl（上下文配置）、finish / update-spec（收尾与沉淀）。

它关注的重点不是某个命令是否好用，而是项目能否形成一套可供 AI 读取、可追溯、可持续演进的事实来源。也就是说，让 AI 在新会话中自行恢复「当前项目、项目规范、上次进行到何处」这三类信息。

Trellis 定义了四个跨平台一致的核心概念：

概念	路径	说明
Spec（规范）	`.trellis/spec/`	以 Markdown 记录的编码规约，按模块划分（frontend / backend / guides），AI 在改动前读取
Workspace（工作区）	`.trellis/workspace/`	每位开发者的会话日志（journal），用于维持跨会话的上下文连贯
Task（任务）	`.trellis/tasks/`	工作单元，包含 PRD、上下文配置与子任务，生命周期为创建 → 规划 → 执行 → 验证 → 归档
Skill（技能）	`.agents/skills/`	自动触发的工作流模块：brainstorm / before-dev / check / update-spec / break-loop

5. 一个需求的完整流程#

把各个环节串联起来，一个需求从描述到收尾的执行过程如下。

会话启动。 恢复项目上下文，并在每轮对话中向提示词注入 workflow-state。
判断是否建立 task。 若只是单个技术问题或改动很小，直接在当前对话中处理即可；只有涉及多文件、多模块、需要设计与复盘时，才建议创建 task。Trellis 因此不会把所有事务都流程化。
Planning。 将临时需求整理成可持续推进的任务资产。例如只描述「做一个登录功能」，它会先明确登录失败如何处理、token 过期策略、是否支持第三方登录、旧用户数据如何兼容等问题，并写入 prd.md。后续新会话可直接读取。
Execute。 实现时依据任务资产与按需读取的相关 spec，而非仅依据最后一句 prompt。spec 不会一次性全部注入，而是按任务需要选取，比单个超长规则文件更易维护。
Check。 这一步相当于一次小型代码审查：查看 diff，读取 check.jsonl 中声明的 spec / research，再对照规范检查。接口错误格式不符合约定、权限校验遗漏、依赖方向错误等问题，通常难以被 lint 或单测发现。
Update-spec。 判断是否有经验值得沉淀。需要避免把所有内容都写入 spec——spec 若收录一切，将沦为信息杂乱的文件。只有具备长期复用价值的规则才应写入，例如「某类接口必须统一错误格式」「某一模块不得直接依赖另一模块」；而像「登录接口改为 /api/v2/login」这类信息，保留在 task 中即可。
Finish-work。 归档任务并写入 journal。该命令不会提交业务代码——功能代码需先完成 commit，它只处理 .trellis/ 内部的归档与 journal；若存在未提交的业务改动，会拒绝执行。

综合来看，Trellis 的落点已从「AI 能否写出代码」转移到「AI 写代码时是否具备稳定的项目上下文、任务状态、检查标准与收尾机制」。

6. 与其他 harness 方案的对比#

现有方案没有绝对优劣，区别主要在于设计取向，大致可分为四类。

流程强化型，以 superpowers 为代表。强调 AI 的执行流程：先澄清、再计划、TDD、最后审查。价值在于把模糊想法整理成可执行计划。问题在于流程重，小任务反复追问与审查会较繁琐；且没有项目级的 task / spec / journal 支撑，流程结束后经验仍散落在对话记录中。
规范管理型，以 openspec 为代表。采用 spec-first，先对齐后实现，变更围绕 proposal、spec、design、tasks 推进，适合复杂需求与长期系统。但规范生成后，AI 是否每次读取、是否读对、是否遵守，仍需要额外机制保障；任务状态、工作记忆与平台适配并非其重点。
多 Agent 编排型，以 oh-my-claudecode 为代表。将 planner、executor、reviewer、debugger 拆分为多个 agent。适合复杂任务，但编排层越重，agent、skills、hooks 越多，排查成本越高，简单任务容易过度编排。
项目闭环型，以 Trellis 为代表。将规范、任务、workflow-state、jsonl、journal 以及 finish / update-spec 串成项目级闭环，重点在于全链路落地：规范如何沉淀、任务如何追踪、会话如何接续、经验如何回流、不同工具如何共享同一套项目上下文。

7. 适用场景与使用成本#

Trellis 提供的是工程结构，并非免维护的自动化能力——spec 需要人工编写、更新与清理。以下场景不宜使用：

一次性脚本（如油猴脚本），直接以 vibe 方式完成即可，无需复杂化。
没有长期维护价值的项目，追求速度时，创建 task、编写 PRD、沉淀经验反而是负担。
团队不愿维护 spec 时。成员较少（两三人）的小团队强行使用，容易留下空模板或过时规范，反而更乱。

适用场景为：项目需长期维护、业务规则较多、多人协作、经常更换 AI 工具、希望经验进入仓库。

使用成本同样需要评估：

需先理解 .trellis/ 下 spec / tasks / workspace / workflow.md / .runtime 各自的职责，否则难以判断 AI 的行为。
需适应 plan / execute / finish 的节奏。vibe 是边说边写，Trellis 是先澄清、再实现、再检查、再收尾，更稳妥但更慢，小任务使用会较繁琐。
spec 需要维护。技术栈、架构、约定变化时须同步更新，过时的 spec 会误导 AI。
task 颗粒度需控制。过大则 AI 易迷失，过小则成为流程负担。合适的粒度是任务确需复盘、涉及多个文件或多个决策、且希望后续能继续查看。
平台体验存在差异。官方支持平台较多，但各平台的 hook、command、sub-agent 能力不同，能接入与体验完整是两回事。

8. 对个人与团队的价值#

个人项目同样会遭遇与团队类似的问题：

会话失忆。 项目搁置数月后，无法回忆上次进度与设计原因，需要重新翻阅代码与对话记录。
工具切换。 从 claude code 切换到 codex、cursor 时，之前配置的规范需要重新编写。
多项目混乱。 同时维护多个项目（如 Go 后端、React 前端、静态博客）时，规范各不相同；在同一个 agent 工具中来回切换，AI 容易受到上一段上下文的影响。
决策不可追溯。 当时按临时想法完成的代码，数月后难以判断原始设计意图，相关权衡与取舍只存在于聊天记录中，且多已压缩，无法追溯。

spec coding 对个人的价值，在于完成任务的顺手保留必要文档，为后续续接留下线索。

团队场景下的价值更为明显：成员可以不必统一使用同一工具。 Trellis 采用「核心跨平台、适配层各自独立」的设计——有人用 cursor、有人用 claude code、新人用 codex，可以共享同一套 .trellis/ 上下文。

9. git 目录划分#

哪些内容应纳入版本管理，建议如下：

纳入 git：.trellis/spec/（团队规范，与代码一样走 PR 审查）、.trellis/tasks/（任务目录，属于项目资产）、.trellis/workspace/{name}/（各开发者的 journal）。
置于 gitignore：.trellis/.developer（当前开发者名）、.trellis/.runtime/（会话运行时状态）。

将 spec 和 task 纳入 git，意味着规范变更需要像代码一样经过审查，重要的 API 设计、测试约定与架构约束对团队可见、可讨论；会话级临时状态则无需纳入版本控制。任务目录纳入 git 后可能存在冲突，建议通过 --assignee 明确负责人。

10. 安装与初始化#

安装与初始化操作简单：

1
npm install -g @mindfoldhq/trellis@latest
2
cd your-project && trellis init -u your-name

初始化后应先完成 bootstrap 任务，让 AI 从真实代码中提取第一版 spec，否则 .trellis/spec/ 中多为空模板，读取价值有限。

若使用 codex，需要在 ~/.codex/config.toml 中开启 hook，并在 TUI 中执行一次 /hooks，批准 Trellis 安装的 UserPromptSubmit hook；否则 / 菜单可能不显示 Trellis 命令，workflow-state 也不会自动注入。

日常使用时无需预先判断是否建立 task，直接在对话中描述需求，由 Trellis 与 AI 判断；询问是否创建 task 时确认即可。常用命令有三个：

/trellis:start：少数平台需要手动启动上下文时使用；支持 SessionStart hook 的平台在打开终端时已自动完成初始化。
/trellis:continue：最常用，当前任务规划、实现或检查完成后，用于推进下一步。
/trellis:finish-work：任务收尾，需先 commit 功能代码，再执行归档 task 与写入 journal。

11. 结语#

vibe coding 在脚本编写与个人项目中具有明显效率优势。但项目进入长期维护后，需要解决规范保存、任务接续、经验沉淀以及新会话上下文恢复等问题。

Trellis 将这些「项目事实」组织为可供 AI 读取、可供团队审查、并可持续演化的结构。是否采用取决于项目情况与使用习惯：对临时需求与小项目而言，并无必要。

详细说明可参考官方文档：Trellis 官方文档