trellis实战

AI交流专区
1

Trellis 从 0 到实战

这篇教程是写给这样一类人的：

  • 你已经会用 claude 或 codex

  • 你已经知道怎么让 AI 帮你改代码

  • 但你还不会把 Trellis 用成一套稳定的项目工作流

所以这篇文章不重点讲终端入门，也不重点讲怎么安装 Claude/Codex，而是重点讲 4 件事：

  • Trellis 到底补了什么

  • trellis init、claude/codex、/trellis:start、$start 分别在什么阶段用

  • 日常开工、续工、收工应该怎么走

  • 哪些地方最容易误用

如果你想把 AI 从“会聊天的写代码工具”升级成“更稳的项目协作者”，这篇就是写给你的。

一句话理解 Trellis

你可以把 Trellis 理解成一套“项目级 AI 协作操作系统”：

  • 用 AGENTS.md 约束 AI 怎么工作

  • 用 .trellis/tasks/ 管任务过程

  • 用 .trellis/workspace/ 记录每次开发 journal

  • 用 .trellis/spec/ 沉淀项目规则和长期知识

它的重点不在于“让 AI 更聪明”，而在于“让 AI 在项目里更稳定”。

Trellis 到底补了什么

如果你已经会用 Claude/Codex，那你大概已经体验过它们的强项：

  • 写代码很快

  • 理解局部问题很强

  • 改小功能时反馈很直接

但一旦项目稍微拉长一点，问题就出来了：

  • AI 容易忘上下文

  • 多轮开发容易断层

  • 换模型或换工具后，协作体验不连续

  • 做完一轮没有沉淀，下次又要重新解释

Trellis 主要就是在补这几块：

  • 上下文：让 AI 先看项目文件，而不是只靠聊天记录

  • 任务：把“这轮要做什么”固定下来

  • 记录：把“上轮做到哪了”写进 journal

  • 规范：把“这个项目该怎么做”沉淀进 spec

所以 Trellis 不是替代 Claude/Codex，而是给它们加一层项目工作流。

先分清 3 类动作

这是整篇最重要的地方之一。很多人用不顺 Trellis，不是因为不会写 prompt，而是因为把不同阶段的动作混在一起了。

1. 首次接入项目

这是给一个项目第一次装上 Trellis：

 git init
 npm install -g @mindfoldhq/trellis@latest
 trellis init -u 你的名字 --claude --codex --skip-existing

这一步只在“第一次接入”时做。

2. 日常打开工具

如果项目已经接入过 Trellis，平时开工通常是先打开你要用的工具：

 claude

或者：

 codex

这一步只是“进入工作现场”。

3. 在会话里启动 Trellis 工作流

工具打开之后，再在对话里让它读取当前项目上下文。

Claude：

 /trellis:start

Codex：

 $start

这一步才是“正式开始按 Trellis 工作”。

你可以把三者记成：

  • trellis init：第一次接入项目

  • claude / codex：打开工具

  • /trellis:start / $start：在会话里拉起项目工作流

一个很重要的底线：仓库事实优先

这是 Trellis 最值得提前记住的一条原则：

不要把“AI 记得什么”当成“当前仓库真的有什么”。

如果你在续工、排查、补文档，建议按这个顺序判断信息可信度：

  1. 先看 AGENTS.md

  2. 再看 .trellis/tasks/ 里的当前任务

  3. 再看 .trellis/workspace/ 里的最新 journal

  4. 再看当前仓库里真实存在的 spec、workflow、交接文档

  5. 最后才把旧对话、AI memory、外部描述当辅助线索

一句大白话就是：

  • 仓库文件是证据

  • AI 记忆只是线索

这条规则会直接决定你后面续工是不是稳。

日常工作主线：开工、进行中、收工

如果你想真正把 Trellis 用顺，最值得记住的不是单个命令，而是一条固定工作流。

开工

项目已经接入 Trellis 后，日常开工建议这样走：

  1. 先打开 claude 或 codex

  2. 在会话里跑 start

  3. 让 AI 先读取 AGENTS.md、当前任务、最新 journal、相关 spec

例如：

 继续当前项目，先核对 AGENTS.md、当前任务和最新 journal，再开始做功能。

start 的意义不是立刻写代码，而是先把上下文补齐，包括：

  • 当前开发者是谁

  • 当前仓库状态如何

  • 有没有活动任务

  • 相关 spec 该读哪些

进行中

进入实现阶段后，最稳的节奏通常是这样：

1. 需求不清，先收敛

Claude：

 /trellis:brainstorm

Codex：

 $brainstorm

或者直接说：

 帮我先梳理一下需求，再给我一个最小可行方案。

这一步的目标不是“多想一点”，而是把需求收敛到：

  • 目标是什么

  • 这一轮只做什么

  • 哪些先不做

  • 验收标准是什么

2. 真正动手前，先确认改动范围

这是非常值得养成的习惯。

例如：

 按刚才的方案实现。开始前先告诉我会创建或修改哪些文件；做完后告诉我如何手动验收。

这会大幅减少“它改了一堆你没预期的东西”的情况。

3. 实现时始终以当前仓库为准

如果你想防止 AI 脑补，下面这句很有用：

 先读当前仓库事实，再做修改；如果要参考旧上下文，只采用能被当前仓库文件印证的信息。

收工

一轮工作做完后，不要直接结束对话，最好按 Trellis 的收工链路走。

1. 先做完工检查

Claude：

 /trellis:finish-work

Codex：

 $finish-work

这一轮主要是确认：

  • lint / typecheck / test 是否通过

  • 有没有漏掉 spec 更新

  • 有没有跨层改动没核对

  • 手动验收点是否清楚

2. 你确认没问题后，再记录本轮工作

Claude：

 /trellis:record-session

Codex：

 $record-session

它的核心价值不是“记笔记好看”，而是：

  • 下次能快速接上

  • 不用重新回忆做到哪

  • 重要结论能留在项目里

一句话说，record-session 是收工动作，不是可有可无的装饰动作。

续工时怎么避免串仓库

这是 Trellis 特别值得用起来的场景。

如果你隔了一天、一周，甚至更久再回来，最稳的做法不是让 AI “回忆一下上次做了什么”，而是重新建立这次会话的证据链。

推荐直接这样说：

 先确认当前仓库身份：读取 AGENTS.md、.trellis/tasks 当前任务、.trellis/workspace 最新 journal。如果当前仓库里确实存在相关 spec、workflow 或交接文档，再补读它们。最后只采用那些能被当前仓库文件印证的背景信息。

这段话的价值很大，因为它能有效避免两种问题：

  • 把别的项目上下文串进来

  • 把旧记忆误当成当前现实

一句话概括就是：

续工不是“回忆昨天”，而是“重新确认今天这个仓库的事实”。

一条完整的 Trellis 实战主线

如果你想把 Trellis 真正跑顺，可以把一轮工作简化成这条主线：

start -> brainstorm -> implement -> finish-work -> record-session

用最简单的 Todo List 场景举例：

  1. 先 start，让 AI 读当前项目上下文

  2. 如果需求还模糊，先 brainstorm

  3. 开始实现前，先让 AI 说清楚准备改哪些文件

  4. 做完后先 finish-work

  5. 你确认没问题后，再 record-session

这条链路的重点不是“命令很多”，而是把一轮开发变成可接续、可检查、可沉淀的过程。

AI 在背后大概做了什么

很多人第一次接触 Trellis，会以为它只是“多了几条命令”。其实它真正有价值的地方，在于把一轮 AI 开发拆成了更清楚的分工。

你可以先粗略理解成这样：

  • 你提需求

  • Trellis 帮 AI 先拉上下文

  • AI 再去看 AGENTS.md、任务、journal、spec

  • 真正实现前先尽量把需求收敛

  • 做完后再走检查和记录

所以它不只是“让 AI 写代码”，而是让 AI 更像在按项目流程工作。

这也是为什么 Trellis 经常会让人感觉比普通聊天式 AI 更稳：

  • 它更依赖项目文件

  • 它更强调任务过程

  • 它更强调做完后的检查和沉淀

什么时候用 update-spec

如果某一轮开发过程中，你发现了稳定可复用的规则、坑点、设计决策，就不要只留在聊天记录里，要沉淀到 .trellis/spec/。

Claude：

 /trellis:update-spec

Codex：

 $update-spec

适合更新 spec 的典型场景：

  • 刚修完一个容易反复出现的 bug

  • 刚确定一个以后都要遵守的实现约定

  • 刚理清一条跨层数据流规则

  • 刚发现一个新人或 AI 很容易踩的坑

parallel 什么时候用

parallel 的思路是让多个 AI 并行处理多个相互独立的工作项。

前提是这些任务之间不要强耦合，比如：

  • 一个在改文档

  • 一个在补测试

  • 一个在做独立页面

如果几个任务彼此共享同一批核心文件、同一条数据流、同一组接口定义，那就不适合并行开太多 agent，不然最后很容易互相打架。

MCP 和 Skills 怎么理解

MCP

MCP 可以理解成 AI 的“外接手脚”，让 AI 有能力去调浏览器、软件、页面、外部系统。

它适合做的事情通常包括：

  • 打开网页

  • 操作某个工具

  • 读取外部界面信息

Skills

Skill 更像是“项目内的可复用工作流说明书”。

它通常比 MCP 更轻，重点不是去操作外部世界，而是告诉 AI：

  • 这个场景该怎么做

  • 要读哪些文件

  • 按什么顺序做

简单说：

  • MCP 偏“能力扩展”

  • Skill 偏“流程复用”

常见误区

1. 把 trellis init 当成每天启动按钮

这是最常见的误用之一。

trellis init 是首次接入项目时用的初始化命令，不是日常续工命令。日常开工应该是进入项目后启动 claude 或 codex，再让它读取当前仓库上下文。

2. 只靠 memory 或旧对话续工

不建议。

memory 可以当线索，但不能替代当前仓库事实。否则最容易出现“它记得一个以前讨论过的版本，但仓库现在已经不是那个状态了”。

3. 不看 AGENTS.md 就直接开写

这样最容易丢项目约定，也最容易越改越偏。

4. 做完不记 journal

短期看像是省了一步，长期看是把下一次续工的上下文直接丢掉了。

Claude / Codex 对照速查表

如果你只是临时忘了某个命令怎么叫，直接看这张表就够了：

场景 Claude Codex
开始一个会话 /trellis:start $start
梳理需求 /trellis:brainstorm $brainstorm
完工前检查 /trellis:finish-work $finish-work
记录本轮工作 /trellis:record-session $record-session
沉淀长期规则 /trellis:update-spec $update-spec
跨层检查 /trellis:check-cross-layer 对应 skill 存在时用 $check-cross-layer
复盘顽固 bug /trellis:break-loop 对应 skill 存在时用 $break-loop

常见错误写法对照

错误写法 正确写法 为什么错
$star $start 少了一个 t
$update_spec $update-spec 这里用的是连字符，不是下划线
$trellis:record-session $record-session Codex 不是 /trellis: 这一套前缀
/start /trellis:start Claude 这里通常是命名空间命令

一套实用心法

如果你只记住几条，记下面这些就够了：

  • trellis init 只管第一次接入，不管日常开工

  • 开工先 start，不要直接上来改

  • 需求不清先 brainstorm

  • 真正动手前，先确认要改哪些文件

  • 做完先 finish-work

  • 提交并人工确认后记得 record-session

  • 续工先看仓库事实，不要先信 AI 记忆

最后用一句话收住全文：

Trellis 的价值，不是让 AI 更像聊天助手，而是让 AI 更像一个能接续、能检查、能沉淀的项目协作者。