从 Vibe Coding 到 Spec Coding：用 Trellis 搭一套项目级 AI 工作台
现在用 AI 写代码，很多时候是"一把梭"：给一个需求指令，剩下的交给 AI。模型能力越来越强，有时候甚至不用 skill 这类工作流插件也能写得很规范。这种 vibe coding 已经很普遍了，只要能满足需求就行。
但问题是，项目长期这样堆下去，基本都会变成屎山级别，越来越难维护。就算继续交给 AI 改，AI 也不记得当初为什么这么写，只能在屎山上继续堆新屎。不管用 Claude Code、Cursor 还是 Codex，不管模型是哪一代，纯 vibe 写出来的代码风格都差不多——一个人写还能凑合，团队用基本是灾难。
这就是为什么 AI 编码不能长期停留在临时对话式开发。Trellis 是我实际用下来，觉得值得在个人开发和团队协作里用的一套脚手架，它能帮我们逐渐从 vibe coding 过渡到 spec coding。这篇不是 Trellis 的安装教程，而是想讲清楚：为什么要往 spec coding 转，以及 Trellis 具体是怎么做到的。
为什么 AI 写代码需要工程结构
直接把需求丢给 AI、让它一路写到底，在很多场景下确实没问题——前提是任务短且风险低。写一个油猴脚本、做个人项目，能跑起来就行，这时候 vibe 反而是最舒服的方式。哪怕后面出 bug 或要加功能，也可以继续让 AI 改，哪里报错改哪里。
真正的麻烦在于，AI 每次修改时解决的更多是眼前这个局部问题。它能看到当前报错、理解这次需求、顺着现有代码补一段逻辑，但它不一定知道：这个模块原本为什么这样拆？这段逻辑是不是已经在别处实现过？这次改法会不会绕开原有的架构约束？这次需求应该影响哪些测试和文档？为了跑通临时加的兼容，会不会变成后面的历史包袱？
所以本质问题不是 vibe coding 不能迭代，而是长期只靠这种方式堆代码，每次修改可能都只是局部最优解。单次看没问题，几轮之后，重复逻辑、特殊判断、风格漂移、隐藏 bug 都会越堆越多。AI 结合强模型写代码确实省心，但它缺的是一个稳定的项目工程环境——很多问题不是"需求描述清楚"就能解决的，而是 AI 根本不知道这个项目长期以来是怎么规划的：规范放在哪、当前任务做到哪一步、这次改动该读哪些上下文、哪些历史决策不能推翻、做完之后哪些经验该沉淀下来。
每次开新会话，都像重新带一个刚入职的新同事——很厉害，写代码也快，但项目里的规矩、历史包袱、架构边界、测试习惯，都得重新讲一遍。可以把现在的 AI coding 工具理解成：
Agent = Model + Harness
Model 负责理解、推理、生成代码；Harness 则是模型之外那一整套让 AI 真正按流程干活的工程规范——项目规范放哪里、任务状态怎么管、上下文怎么投喂、经验怎么沉淀、工具怎么调用、边界在哪里。真正让 AI 能在项目里稳定工作的，其实是 harness 这一层。而模型再强，实际使用中依然会遇到会话失忆、规则文件失控、跨工具配置不通用这些局限。
Prompt / Rules / Skill 解决了什么，局限在哪里
Prompt 的局限在于不持久。新开一个会话，之前说的就都没了，要么重新说一遍情况，要么让 AI 去翻上一轮的 diff，既浪费 token，AI 也不一定真的理解之前的规范和需求。Prompt 只适合临时一次性的需求。
AGENTS.md / CLAUDE.md / rules 的价值和局限：这类文件能把项目规范、构建命令、测试命令、编码风格写进去，持久生效，AI 写代码前会先读。但问题不在文件本身，而在工具切换——.cursorrules、CLAUDE.md 这类文件偏平台专属，团队里如果有人用 Claude Code、有人用 Cursor、有人用别的工具，每个人都要配一遍，也不好统一提交管理。而且 rules 文件会随项目发展越写越长，新规范加进去、旧规范不敢删，最后变得臃肿，文件太长后 AI 容易上下文过载，忽略关键细节；rules 也是静态规则，不天然知道当前任务状态，临时判断和经验不会自然沉淀回规则。
Skill 的价值和局限：Skill 能把某类操作方法固化下来，比如需求澄清、debug、review、写测试、发布前检查，比 rules 更灵活，也能训练 AI 的行为模式。但模型越强，通用型 skill 的边际价值就越低——很强的模型本来就懂通用流程。真正有价值的是项目型、领域型、团队型 skill，它固化的是项目约定、团队流程、领域知识,解决的是上下文和一致性问题，不是模型智商问题。致命问题同样是跨平台格式不统一：换个工具，项目级 skill 就要重新适配一遍。
Prompt、rules、skill 各自解决局部问题，组合起来用确实能更好地辅助 AI 写工程化代码，但仍有三个共同的硬伤：
- 会话失忆——每次新开会话，AI 就忘记之前的进度和背景。
- 绑定具体工具——换个 agent，所有项目级配置就要重新弄一遍，团队里工具不统一就没法共享。
- 缺少项目级闭环——没有任务资产，没有跨会话记忆，也没有规范演进机制，更多是在解决"这一次对话里 AI 怎么写代码"，而不是"整个项目怎么用 AI 持续演进"。
为什么 Trellis 适合做 spec coding 的落地方案
Trellis 不是单纯的 prompt 包，也不是单纯的 skill 集合，而是一个项目级的 AI 工作台。它的核心理念不是让我们每次都重新解释项目，而是把项目规范、任务记录和工作记忆沉淀到 .trellis/ 目录里。之后不管新开会话、换什么工具、做什么任务，AI 都能从项目结构里读到需要的上下文；项目继续迭代时，新的稳定经验再通过 update-spec 之类的流程写回 spec，让这套项目知识持续更新。
对应前面的三个问题，Trellis 分别给出了应对：
缓解会话失忆——通过 task、workspace、journal、启动上下文来恢复项目知识。上次做到哪里、遇到了什么问题、下一步要做什么，都记在 journal 里；新会话启动时，AI 从 .trellis/ 文件里重新加载。这不等于 AI 有了真正的长期记忆,但项目知识被持久化到了文件系统里，每次都能重新读取。
跨平台共享核心——.trellis/ 的核心是跨平台的：spec / task / workflow 是团队共享的事实源，workspace / journal 是按开发者隔离的工作记忆。每个工具需要单独的适配层（比如 trellis init --claude 或 --cursor），但核心规范和任务是同一套。团队里有人踩过一个坑,把经验写进 .trellis/spec/ 提交到仓库,其他人不管用什么工具拉取代码后,AI 都能读到这条新规范。
形成完整的项目级闭环——Trellis 把 spec（长期规范）、task（当前任务）、workflow（当前阶段）、journal（工作记忆）组织成闭环，任务收尾时还会引导判断哪些经验值得长期复用、写回 spec。它不会把所有规范一次性塞给 AI,而是通过 spec index 和任务级 context manifest,让当前任务只加载相关的 spec / research,减少上下文过载——前提是 spec 本身要短、准、可检索。
当然 Trellis 也不是完美方案,需要前期投入、维护习惯和学习成本。如果项目已经到了 vibe coding 撑不住的阶段,需要更稳定的 AI 协作方式,Trellis 是目前比较完整的一个尝试。
Trellis 机制拆解：一次任务的八步走
Trellis 靠几块机制一起转起来：规范、任务、工作流、上下文、记忆，以及最后的经验反哺。
第一步·恢复项目上下文：新会话启动时，Trellis 会先给 AI 一份紧凑的项目上下文，让它至少不用面对一个完全陌生的仓库——上次做了什么、有没有活跃任务、当前开发者是谁、接下来大概该往哪走。不同平台的启动入口不完全一样：有 SessionStart hook 或插件的平台通常会自动注入，怀疑没加载时可以让 AI 读一次 trellis-start skill；用 Codex 的话，主要靠仓库根目录的 AGENTS.md 做 prelude,再通过 UserPromptSubmit hook 注入 workflow-state,需要在 ~/.codex/config.toml 里确认 features.hooks = true 并在 /hooks 里审批。
第二步·每轮 prompt 带着当前状态：只在会话启动时恢复一次并不够，AI coding 大多是多轮对话。Trellis 用 workflow-state 解决这个问题——支持 hook 的平台上，每条 prompt 进来时都会带上当前任务处于哪个阶段（澄清需求、实现中、检查中、收尾中），避免 AI 跳步骤。
第三步·判断当前 turn 要不要建 task：只是问一个技术问题，或者改一个很小的 bug，当前对话就能说清楚，可以直接走 inline,不需要建 task。只有任务涉及多文件、多模块、需要设计、需要复盘时，Trellis 才会建议创建 task——这一点比一些偏重流程的方案更轻，不会把所有事情都流程化。
第四步·planning 把临时需求变成任务资产：进入 planning 阶段后，Trellis 会把类似"帮我做一个登录功能"这种一句话需求，转成可持续推进的任务资产——登录失败怎么处理、token 怎么过期、是否支持第三方登录、老用户数据怎么兼容,这些关键问题会先问清楚,再写进任务目录（产出通常是 prd.md、design.md、implement.md 之类）。这样哪怕今天做到一半、明天换个会话继续，AI 也不用从聊天记录里猜。
第五步·execute 按任务资产和 spec 做事：Planning 完成后任务进入 in_progress，AI 开始实现,但不是只看最后一句 prompt,而是综合任务上下文顺序执行。这是 Trellis 和普通 rules 文件的区别——rules 只告诉 AI 项目里有哪些长期规则,Trellis 还会告诉 AI 当前任务要做什么、为什么这么做、哪些上下文必须读、现在执行到哪一步。spec/ 也不会一次性全塞给 AI,默认模板按 backend/、frontend/、guides/ 分类,AI 按任务需要选相关规范。
第六步·check 对照规范复核：很多 AI 编码流程的检查最后只是跑一下 lint 和 test，但有些问题测试抓不到——接口错误格式不符合约定、权限校验漏了、目录结构不符合团队习惯、模块依赖方向反了。Trellis 的 check 阶段更接近一次小型 code review：看当前 diff，也读 check.jsonl 里声明的 spec / research，对照规范检查代码，把检查标准从临时感觉变成任务和规范里明确写下来的东西。
第七步·update-spec 只沉淀稳定经验：任务做完后，Trellis 会引导判断哪些经验值得长期复用——比如某类接口必须统一返回错误格式、某个模块不能直接依赖另一个模块、某类数据库 migration 必须带回滚说明、某个坑已经踩过应该写进规范。像具体接口路径这种信息更适合留在 task 里，而不是塞进 spec。这一步的重点是筛选，避免 spec 变成堆积材料。
第八步·finish-work 做归档和 journal：/trellis:finish-work 不负责提交业务代码——按官方流程,功能代码要先 commit,只有工作 commit 已经存在后才应该运行它;如果还有未提交的业务改动,它会拒绝执行并提醒先处理。Journal 记录这次任务做了什么、提交了什么、遇到什么问题、下一步是什么，放在 workspace/ 里按开发者隔离，不会互相覆盖，但进 git 后团队仍然可以回看，新人也能借此了解项目是怎么一步步做起来的。
把这八步串起来看，Trellis 机制的重点已经从"AI 会不会写代码"转到了"AI 写代码时有没有稳定的项目上下文、任务状态、检查标准和收尾机制"。Vibe coding 更像一段对话往前冲，Trellis 则是把这段对话变成一个有状态、有材料、有检查、有沉淀的任务流程。
和其他 Harness 思路的区别
不同方案没有绝对的谁更好，更多是设计取向不同：
- 流程强化型（比如一些偏流程约束的 skill / rules 方案）：强调 AI 做事方法——先澄清需求、先写计划、先 TDD、再 review。适合把原始想法梳理成可执行计划，也适合防止 AI 上来就乱写，但比较重，小任务反复追问、反复 review 会很啰嗦；如果没有项目级 task / spec / journal 资产，流程跑完经验还是可能散在聊天记录里。
- 规范管理型（比如 spec-first 思路）：强调先对齐再实现，每次变更围绕 proposal、spec、design、tasks 推进,能把隐性的团队约定显式化,对复杂需求和长期系统很有帮助。但规范写出来后，AI 是否每次都读、读对、真正遵守，还需要额外机制兜住；任务状态、工作记忆、跨平台适配不一定是它的重点。
- 多 agent 编排型：把 planner、executor、reviewer、debugger 拆成不同角色分工处理复杂任务，适合需要规划、执行、评审、调试分开的场景，但编排层容易变重，agent、skill、hook 一多，排查成本就上来了，简单任务用这套容易过度编排。
- 项目闭环型（Trellis 属于这一类）：把 spec、task、workflow-state、journal、finish / update-spec 串成一套项目级闭环，关心的不只是某个命令好不好用，而是项目能不能形成一套 AI 可读取、可追溯、可持续演进的事实源——规范怎么沉淀、任务怎么追踪、会话怎么接续、经验怎么回流、不同工具怎么共享同一套项目上下文。
想快速约束 AI 行为，skill / rules 可能更轻；重点在规范先行，spec-first 方案可能更对口；想增强某个特定平台的体验，多 agent 编排可能更直接；想要项目级闭环、让规范任务记忆经验都沉淀到项目里，Trellis 是目前比较完整的尝试。
对个人开发者的价值
很多人觉得 spec coding 只在团队协作时才有必要，个人项目做久了其实也会遇到类似问题：
- 会话失忆：个人 vibe 的项目停几个月再回来，上次做到哪、为什么这样设计基本全忘了，得重新翻代码、翻聊天记录，甚至干脆重写。
- 工具切换：换一次 agent 工具，就要把之前配的规范重新写一遍，
AGENTS.md能缓解一部分，但项目级的 rules / skill 依然不通用。 - 多项目混乱：同时维护多个技术栈不同的项目时，如果规范都散在会话里，AI 很容易被上一段上下文或通用习惯带偏。
- 给自己挖坑：让 AI 按当时的想法快速写完代码，几个月后回来完全不知道为什么这样写——当时的权衡取舍只存在聊天记录里，压缩过后更难追溯。
Spec coding 对个人开发者的价值不在于多一套流程，而是解决这些真实问题——顺手留下必要文档，给未来的自己留一条能接上的线。个人开发者通常不需要复杂的协作流程，但同样需要基本的工程结构。
对团队的价值
团队协作时 spec coding 的价值会更明显：
团队成员可以用不同工具开发——不必强制统一 agent 工具，Trellis 核心跨平台、适配层各自独立，同事 A 用 Cursor、同事 B 用 Claude Code、新人 C 用 Codex，三个人可以共享同一套 .trellis/。
哪些进 git、哪些不进：建议进 git 的有 .trellis/spec/（团队规范，和代码一样走 PR review）、.trellis/tasks/（任务目录：PRD、设计、调研，属于项目资产）、.trellis/workspace/{name}/（各开发者的 journal）；不需要共享的有 .trellis/.developer（记录当前开发者名）和 .trellis/.runtime/（会话运行时状态），这两者应该 gitignore。Spec 和 task 进 git 意味着规范改动要像代码一样走 review,重要的接口设计、测试约定、架构约束应该让团队看得到、讨论得起来;任务目录也可能冲突,团队里最好通过明确的负责人分工来避免两人同时改同一个任务。新人加入时,也能通过这些记录更快理解项目是怎么演进过来的。
规范不是一成不变的——项目做了大变更、引入新测试框架，spec 都要更新，但重要的 spec 改动应该在 PR review 里讨论，像团队代码一样维护，这样规范演进才是可控、可追溯的。
适用边界与使用成本
Trellis 不是每个人、每个项目都需要：
- 一次性脚本：类似油猴脚本，直接 vibe 就行，不需要过度复杂化。
- 没有长期维护价值的项目：求快是重点，建任务、写 PRD、沉淀经验反而是负担。
- 团队不愿意维护 spec：Trellis 提供的是工程结构，不是免维护的自动化——spec 需要人写、人更新、人清理。团队人少（比如两三个人）又不愿意维护，强行上 Trellis 只会留下一堆空模板或过时规范，反而更乱。
使用成本也是实打实的：前期要理解 .trellis/ 下 spec/、tasks/、workspace/、workflow.md、.runtime/ 各自管什么；要习惯 plan / execute / finish 这套更强调先澄清、再实现、再检查、再收尾的流程，比直接开写更慢；spec 需要随技术栈、架构、团队约定的变化持续维护，过时的 spec 会误导 AI；task 粒度要控制,太大 AI 容易迷失,太小又变成流程负担；不同平台的 hook、command、sub-agent 能力不一样，接入是一回事,体验是否完整是另一回事,用之前最好确认一下自己常用工具的支持方式。
判断标准很简单：短任务、小脚本、自己的小项目，直接 vibe 就行；项目会长期维护、业务规则多、团队多人协作、经常换 AI 工具、希望经验进入仓库，Trellis 就很合适。Spec coding 的重点在于沉淀长期有复用价值的项目事实，不在于把每件事都流程化。
实践建议：常用命令
初始化：
npm install -g @mindfoldhq/trellis@latest
cd your-project
trellis init -u your-name已经初始化过的项目，新成员一般也是跑 trellis init -u your-name，给自己这台设备设置开发者身份。初始化后不要急着做功能，先把 bootstrap 任务跑完，让 AI 从真实代码里提取第一版 spec，否则 .trellis/spec/ 里大多还是空模板，读了也没什么价值。
Codex 需要额外开 hook：在 ~/.codex/config.toml 里开启
[features]
hooks = true然后在 TUI 里跑一次 /hooks，审批 Trellis 安装的 UserPromptSubmit hook。不开的话，/ 菜单里可能看不到 Trellis 的命令，workflow-state 也不会自动注入——虽然还有 fallback，但体验会差很多。
日常使用：不需要先纠结要不要建 task，直接描述需求，是否创建 task 交给 Trellis 和 AI 判断，它问的时候确认一下就行。常用命令只有三个：/trellis:start（少数需要手动启动上下文的平台才用得到，有 SessionStart hook 的平台通常已自动 orient）、/trellis:continue（最常用，任务规划完/实现完/检查完都用它推进下一步）、/trellis:finish-work（任务收尾用，功能代码要先 commit，它只负责归档 task 和写 journal）。
总结
Vibe coding 写脚本、做个人项目确实快，但项目一旦要长期维护，规范怎么保存、任务怎么接续、经验怎么沉淀、新会话怎么不从零开始，这些问题就会变得复杂且必要。是否要在自己的项目里上 Trellis，可以根据具体习惯和判断来定，但如果已经感觉到 vibe coding 撑不住了，它是目前比较完整的一个尝试方向。