从Vibe Coding到Spec Coding：Trellis实践总结

背景

随着大语言模型能力的持续提升，越来越多的开发者采用“vibe coding”（随性编码）的方式——只需给 AI 一个大致要求，剩下的完全交由模型自主生成。这种模式在个人项目、快速原型中非常高效，甚至不需要借助复杂的提示词工程或工作流插件。然而，当项目规模扩大、迭代次数增多时，vibe coding 的局限性开始显现：每次修改只是局部最优解，长期积累会导致代码“屎山”——重复逻辑、风格漂移、隐藏 bug 大量堆积。即使后续交给 AI 修复，AI 也记不清当初的设计意图，只能继续“堆新屎”。

从团队协作的角度看，单纯的 vibe coding 几乎是灾难。不同开发者、不同会话之间缺乏统一的规范与上下文记忆，项目演变成不可维护的黑箱。因此，作者提出 AI 编码需要从 vibe coding 转向 spec coding（规范编码），即通过结构化的工程规范来引导 AI 持续、稳定地工作。Trellis 正是作者在实践中找到的、能有效支撑 spec coding 的脚手架工具。

核心内容

为什么 AI 写代码需要工程结构

很多人会认为：既然用了 AI，直接把需求丢给它，让它一路写到底不好吗？作者指出，这种思路在任务短且风险低的场景下确实没问题（如编写油猴脚本或个人项目），快速直接。但问题出在长期迭代上：每次修改时 AI 往往只解决眼前的局部问题，而不知道模块为何这样拆分、逻辑是否已经实现、当前改动是否会绕过架构约束、是否影响测试和文档、是否引入历史包袱。长期下来，代码中充斥着重复逻辑、特殊判断和隐藏 bug。

本质原因是，AI 缺少一个稳定的项目工程环境。开发者容易产生错觉：只要需求描述得足够清楚，AI 就应该做好。但实际项目中，AI 不知道项目长期以来的规划——规范在哪、任务进度到哪、该读哪些上下文、哪些历史决策不能推翻、做完后经验如何沉淀、下次新会话如何继续。每次新任务都像给 AI 重新介绍一个新同事，非常低效。

作者将当前的 AI coding 工具（如 Claude Code、Codex、Cursor）拆解为 Agent = Model + Harness。Model 是模型本体，负责推理和生成；Harness 是模型之外的一整套工程规范，包括项目规范存放位置、任务状态管理、上下文投喂、经验沉淀、工具调用边界等。模型虽然越来越强，但 harness 层面仍然存在问题：会话失忆、规则文件失控、跨工具配置不通用。

Prompt / Rules / Skill 的局限

Prompt 的局限

直接给 AI 输入需求，通过不断对话修正，效率高但不可持久。新开会话后，之前说的内容全部丢失，需要重新解释或让 AI 基于 diff 理解，浪费 token，且 AI 不一定了解之前的规范、需求和流程。Prompt 适合一次性临时需求，但不持久、不稳定、难复用。

AGENTS.md / CLAUDE.md / Rules 的价值与局限

开发者通常会在项目中维护规则文件（如 .cursorrules、CLAUDE.md、AGENTS.md），将构建命令、测试命令、编码风格、禁止事项等写进去，持有效果。但问题是：这些文件是平台专属的。例如 .cursorrules 只能在 Cursor 中使用，CLAUDE.md 只能在 Claude Code 中使用。团队工具不统一时，每个人都要各自配置，且不易提交到仓库统一管理。尽管 AGENTS.md 是开放标准，但它主要是静态项目说明，不负责 task、journal、workflow-state 等运行时状态。此外，规则文件会越写越长，导致上下文过载，AI 忽略关键细节；规则是否真正被 AI 遵守也不确定；规则是静态的，无法感知当前任务状态和临时判断。

Skill 的价值与局限

Skill 可以将特定工作流固化（如需求澄清、debug、review、写测试、发布前检查），比 Rules 更灵活。但随着模型变强，通用型 Skill 的效果下降，项目型、领域型、团队型 Skill 才更有价值——它们解决的是上下文和一致性问题，而非模型智商。但项目级 Skill 每个平台的格式不同，从 Claude Code 转到 Codex 需要重新适配。

本质问题：会话失忆、绑定工具、缺少闭环

综合来看，Prompt、Rules、Skill 各有价值，但共同存在三个无法解决的根本问题：

1. 会话失忆：新开会话后 AI 忘记之前进度和背景。
2. 绑定具体工具：只要换一个 Agent，所有项目级规范配置就要重做，团队无法统一。
3. 缺少项目级闭环：没有任务资产、跨会话记忆、规范演进机制，这些配置只解决单次对话怎么写代码，而不是项目如何持续演进。

Trellis：spec coding 的实践方案

Trellis 被作者视为一个项目级的 AI 工作台，而不是单纯的 prompt 包或 skill 集合。它的核心理念是将项目规范、任务记录和工作记忆都沉淀到项目根目录下的 .trellis/ 文件夹中。这样无论新开会话、更换什么工具、做什么任务，AI 都可以从项目结构中读取需要的上下文。项目迭代时，新的稳定经验通过 update-spec 等流程写回 spec，实现知识持续更新。

第一个优势：显著缓解会话失忆

Trellis 通过 task、workspace、journal、启动上下文来恢复项目知识。上次做到哪里、遇到什么问题、下一步做什么，都会记录在 journal 里。新会话启动时，AI 可以从 .trellis/ 文件重新加载项目知识。虽然 AI 本身没有持续记忆，但项目知识被持久化到文件系统，每次启动可重新读取。在支持启动上下文或 hook 的平台上，新会话能读取 journal 和活跃任务信息，更容易接着上次的思路继续，减少重复梳理的时间成本。

第二个优势：跨平台共享核心，团队可用不同工具

.trellis/ 核心是跨平台的。其中 spec、task、workflow 是团队共享的事实源；workspace、journal 按开发者隔离。每个工具只需单独配置适配层（如 trellis init --claude 或 --cursor），但核心规范和任务同一套。团队成员即使使用不同的 Agent 工具，也能共享同一套 .trellis/ 事实源。例如有人解决了一个常见坑，只需将经验写入 .trellis/spec/ 并提交代码库，其他人拉取后，无论用 Claude Code 还是 Cursor，AI 都能读取到这条新规范。

第三个优势：形成完整的项目级闭环

Trellis 将 Spec（长期规范）、Task（当前任务）、Workflow（当前阶段）、Journal（工作记忆）组织成完整闭环：

• Spec 管理长期规范
• Task 管理当前任务
• Workflow 管理当前阶段
• Journal 管理工作记忆

任务收尾时，AI 会引导判断哪些经验值得长期复用，再把稳定规则写回 Spec。它不是只解决 AI 怎么写代码，而是解决项目如何用 AI 持续演进。

关键要点

• Vibe coding 的适用边界：短任务、低风险场景（如个人脚本）适合 vibe coding；长期项目则会导致代码质量失控。
• AI 编码的错觉：仅仅清晰描述需求并不够，AI 需要知道项目长期规划、架构约束、历史决策等上下文。
• Agent 的 Harness 层是关键：模型本身强，但真正让 AI 在项目里稳定工作的是 Harness 部分（规范、任务管理、上下文投喂、经验沉淀）。
• 现有工具的三大缺陷：Prompt 不可持久、Rules 平台专属且臃肿、Skill 跨工具不通用；共同根本问题是会话失忆、绑定工具、缺少项目级闭环。
• Trellis 的核心理念：将项目知识持久化到 .trellis/ 目录，使 AI 在新会话中也能读取上下文。
• Trellis 的三个核心优势：
  1. 通过 journal 和 task 缓解会话失忆。
  2. 跨平台共享 spec/task/workflow，团队成员可用不同工具。 3