Trellis + Claude Code + Codex 实用手册
版本：Trellis 0.4.0 | 日期：2026-04-17 | 开发者：ZQYuan
支持平台：Claude Code| Codex
更新记录：
2026-04-18 修正 Claude Code 续工防串仓库：
memory仅作候选线索，必须先核对当前仓库的AGENTS.md、.trellis/tasks/、.trellis/workspace/2026-04-18 补充 Codex 续工防串仓库：先核对
AGENTS.md、.trellis/tasks/、.trellis/workspace/，旧交接文档仅作可选增强材料2026-04-18 补充
trellis init仅用于首次初始化，日常开工直接使用claude/codex2026-04-18 扩充 4.5章【实战操作手册】和12章【记忆与上下文管理】
目录
1. Trellis 是什么
一句话： Trellis 是给 AI 编程助手（Claude Code / Codex 等）装的"项目记忆 + 规范管理"跨平台框架。
支持的平台： Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、Kilo、Kiro、Windsurf 等 13+
解决的核心问题：
| 问题 | Trellis 怎么解决 |
|---|---|
 AI 记不住上次做了什么 |
工作日志（Journal）自动记录，下次启动自动读取 |
 AI 不遵守你的编码规范 |
Spec 规范文件，每次自动注入给 AI |
 AI 修了 A 坏了 B |
检查员 AI 自动审核代码质量（Ralph Loop） |
 任务管理混乱 |
自动创建任务、跟踪进度、归档 |
2. 新项目完整配置流程
前置条件
确保已全局安装 Trellis：
npm install -g @mindfoldhq/trellis@latest
trellis --version # 确认版本号
新项目三步走
在 终端（PowerShell / CMD / Git Bash） 中操作：
# ① 进入你的项目目录（必须已有代码或准备写代码的文件夹）
cd C:\Users\21906\Desktop\你的项目名
# ② 初始化 Git（如果还不是 git 仓库）
git init
# ③ 初始化 Trellis（同时配置 Claude Code 和 Codex）
trellis init -u ZQYuan --claude --codex --skip-existing
平台选择提示：
--claude= 配置 Claude Code
--codex= 配置 Codex（会同时生成.codex/和.agents/skills/）两个可以同时加，不冲突
只用一个平台就只加一个 flag
初始化时会让你选模板。如果你的项目不是 Web 前端项目，直接选from scratch (default)回车即可。
trellis init 只用于首次初始化
重要：
trellis init不是日常开工命令。它只在以下场景使用：
第一次给项目接入 Trellis
旧项目第一次补装 Claude 或 Codex 支持
明确要重建 / 修复 Trellis 初始化配置
后续每天开工、新开窗口、继续昨天的任务时，都不要再跑 trellis init。
日常正确做法是：
cd C:\Users\21906\Desktop\你的项目名
claude # 或 codex
为什么不能拿它当日常启动命令？
因为 trellis init 的职责是初始化配置，不是恢复会话。
它通常不会直接清空 .trellis/workspace/、.trellis/tasks/ 或已有记忆（尤其加了 --skip-existing 时会尽量跳过已有文件），但：
-
它可能重新检查 / 生成配置文件
-
它可能处理
.claude/、.codex/、.agents/skills/等初始化内容 -
重复乱跑会增加环境混乱风险
trellis init= 装系统 / 首次接入
claude/codex= 每天开工 / 继续项目
trellis update= Trellis 升级后同步模板
Developer: ZQYuan
Creating workflow structure…
Configuring Claude Code…
Configuring Codex…
Tracking XX template files for updates
### 🚀 然后启动 AI 工具
```bash
# 用 Claude Code
claude
# 或者用 Codex
codex
启动后 Trellis 会自动注入项目上下文（你不需要做任何事），AI 已经知道：
-
你是谁（ZQYuan）
-
项目当前状态
-
最近的 Git 提交
-
有哪些规范文件
从这一刻起，你就在 AI 工具的对话框里操作了，不需要回终端。
3. Claude Code 与 Codex 双平台使用
核心概念：Spec / Tasks / Journal 是共享的
你的项目/
├── .trellis/ ← ✅ 共享！两个平台读同一套
│ ├── spec/ ← ✅ Claude 写的规范，Codex 也遵守
│ ├── tasks/ ← ✅ 任务状态互通
│ └── workspace/ ← ✅ 日志互通
├── .claude/ ← Claude Code 专属配置
├── .codex/ ← Codex 专属配置
├── .agents/skills/ ← Codex 的 skills（Cursor/Gemini 等也读这里）
└── AGENTS.md ← 多平台共用的 Agent 入口
Codex 额外配置（已配好）
Codex 的 hooks 是实验性功能，需要在全局配置里手动开启：
# 文件位置：~/.codex/config.toml（即 C:\Users\21906\.codex\config.toml）
[features]
codex_hooks = true
config.toml在你的用户目录下（~/.codex/），
不在项目的.codex/里。所以：
~/.codex/config.toml，加上上面两行）
trellis init不会自动帮你加这个，需要手动编辑
两个平台的差异对比
| 特性 | Claude Code | Codex |
|---|---|---|
| Hooks（自动注入上下文） | 原生支持 |
需手动开启 codex_hooks = true |
| 斜杠命令前缀 | /trellis:xxx |
/xxx（没有 trellis: 前缀） |
| 斜杠命令来源 | .claude/skills/ |
.codex/skills/ + .agents/skills/ |
| Spec 规范 | 共享 .trellis/spec/ |
共享 .trellis/spec/ |
| 任务管理 | 共享 .trellis/tasks/ |
共享 .trellis/tasks/ |
| 工作日志 | 共享 .trellis/workspace/ |
共享 .trellis/workspace/ |
| Session Start Hook | .claude/settings.json |
.codex/hooks/session-start.py |
suppressOutput |
不适用 | 尚未生效（实验性限制） |
最大区别：Codex 不支持斜杠命令！
Claude Code 可以直接输 /trellis:xxx 触发 Skill。
Codex 没有斜杠命令功能，需要用自然语言描述。
Codex 启动时 session-start hook 已经自动注入了 Trellis 工作流上下文，
AI 知道怎么操作 .trellis/ 目录，只是你得用人话告诉它。
| 功能 | Claude Code（斜杠命令） | Codex（自然语言替代） |
|---|---|---|
| 开始工作 | /trellis:start |
自动注入，不需手动 |
| 理清需求 | /trellis:brainstorm |
"帮我梳理一下这个需求" |
| 完工检查 | /trellis:finish-work |
"帮我做完工检查清单" |
| 记工作日志 | /trellis:record-session |
"把这次工作记录到 journal 日志里" |
| 复盘 bug | /trellis:break-loop |
"分析一下刚才这个 bug 的根因" |
| 沉淀经验 | /trellis:update-spec |
"把这条经验写进 spec 规范" |
| 代码检查 | /trellis:check |
"检查一下代码是否符合规范" |
| 并行开发 | /trellis:parallel |
"帮我同时开两个任务并行开发" |
双平台协作场景
场景 1：白天用 Claude，晚上用 Codex
上午：cd 项目 → claude → 写功能 → /trellis:record-session → 退出
晚上：cd 项目 → codex → Codex 自动读到上午的日志 → 继续开发
场景 2：Claude 做主开发，Codex 做并行任务
Claude 主会话做核心功能
同时开另一个终端 → codex → 让 Codex 跑独立的辅助任务
两边的 spec 和 tasks 自动同步
场景 3：用 Claude 写规范，Codex 也自动遵守
在 Claude 里：/trellis:update-spec → 写入新规范
之后用 Codex 开发时，Codex 的 session-start hook 自动加载同一套规范
4. 每天的日常工作流程
开始工作
trellis init。
如果这个项目早就接入过 Trellis，那么日常开工时只需要cd到项目目录后启动claude或codex，不要重复执行trellis init。
# 终端里两条命令（选一个平台启动）
cd C:\Users\21906\Desktop\你的项目名
claude # 或 codex
进入 AI 工具后，Trellis 自动注入上下文，你直接说需求就行。
工作中的完整流程
┌─────────────────────────────────────────────────────────┐
│ 启动 claude 或 codex（Trellis 自动注入上下文） │
│ │ │
│ ▼ │
│ 需求没想清楚？ → 输入 /trellis:brainstorm（AI帮你理清） │
│ │ │
│ ▼ │
│ 用大白话说需求 → AI 自动创建任务 + 写代码 + 检查 │
│ │ │
│ ▼ │
│ 输入 /trellis:finish-work（完工检查） │
│ │ │
│ ▼ │
│ 跟 AI 说"帮我提交代码"（AI 执行 git commit） │
│ │ │
│ ▼ │
│ 输入 /trellis:record-session（记工作日志）★ 每次必做 │
│ │ │
│ ▼ │
│ 修了 bug？ → /trellis:break-loop（复盘分析根因） │
│ 学到新经验？ → /trellis:update-spec（写进规范） │
│ │
└──── 收工，明天 AI 自动接着干 ─────────────────────────────┘
三步口诀（核心中的核心）
做之前 → /trellis:brainstorm 理清需求
做完后 → /trellis:finish-work 完工检查
走之前 → /trellis:record-session 记工作日志 ★
/trellis:record-session
不记 = 下次 AI 从零开始；记了 = 下次 AI 无缝接续。
4.5 
实战操作手册：完整命令流程
这一节是全手册最实用的部分。 三个场景、两条路径，照着敲就行。
约定：
终端 $表示在系统终端（PowerShell / Git Bash）里输入；AI >表示在 AI 对话框的>提示符后输入。
场景一：开工（启动 AI + 加载项目记忆）
Claude Code 路径
# ① 系统终端：进入项目目录 + 启动 Claude
终端 $ cd C:\Users\21906\Desktop\嵌赛
终端 $ claude
# ② Claude 对话框：Trellis 会自动注入上下文（SessionStart Hook）
# 通常你什么都不用做，直接说需求即可
# 如果清过屏（/clear）或感觉上下文丢了，手动补一次：
AI > /trellis:start
# ③ 开始干活：直接说需求
AI > 帮我改造 Web 前端控制台，加翻页和亮度控制面板
自动加载的内容：
-
~/.claude/CLAUDE.md（全局规则 + 人设） -
~/.claude/projects/.../memory/（Claude 专属详细记忆，可能混有同路径下其他项目的旧条目，不能直接当当前仓库事实） -
AGENTS.md（项目精简上下文，当前仓库第一信源） -
.trellis/的任务状态、日志、规范（通过 Hook 注入，续工时优先看tasks/和workspace/）
Codex 路径
# ① 系统终端：进入项目目录 + 启动 Codex
终端 $ cd C:\Users\21906\Desktop\嵌赛
终端 $ codex
# ② Codex 对话框：session-start hook 已自动注入 Trellis 上下文
# Codex 会先读 AGENTS.md + .trellis/ 注入内容，通常可以直接开始
AI > 继续做 Web 控制台改造，先查看当前任务和项目上下文
# ③ 如果你还有额外交接文档，再作为增强材料补充给它（可选，不是必需）
AI > 再读一下「第二阶段新会话交接.md」，补充完整背景
自动加载的内容：
-
AGENTS.md（项目主入口，Codex 跨工具记忆核心） -
.trellis/的任务状态、日志、规范（通过 Hook 注入，续工时优先看tasks/和workspace/） -
Claude memory（Codex 看不到）
结论：
没有交接文档也没关系。只要
AGENTS.md写得好，Codex 就能继续工作。
关键原则
-
Claude 的 auto-memory 不是当前仓库的绝对事实。 它可能混入同一路径名下其他项目的旧记忆，所以只能当“候选线索”。
-
Codex 虽然看不到 Claude memory，但一样可能串仓库。 常见来源是错误提示词、旧交接文档、写错的
AGENTS.md，或把别的项目日志当成当前仓库日志。 -
续工时，当前仓库的第一信源永远是：
AGENTS.md→.trellis/tasks/当前任务 →.trellis/workspace/最新 journal →.trellis/spec/。 -
只有当外部材料能被当前仓库实际文件印证时，才能把它当成当前项目事实。
-
交接文档（如
第X阶段新会话交接.md）仍然是增强材料，但也必须先确认它确实存在于当前项目中。
场景二：收工（保存记忆 + 为下次交接做准备）
Claude Code 路径
# ① 完工检查
AI > /trellis:finish-work
# ② 如果需要提交代码（可选，看你是否改了代码）
AI > 帮我提交代码
# ③ 记录工作日志 ★★★ 每次必做
AI > /trellis:record-session
# ④ 让 Claude 把重要上下文存入记忆（项目有重大变更时）
AI > 把今天的架构决策存到 memory 里，同时更新 AGENTS.md
# ⑤ 如果修了 bug，做复盘（可选但推荐）
AI > /trellis:break-loop
# ⑥ 如果学到新经验，写进规范（可选但推荐）
AI > /trellis:update-spec
保存去向：
| 你说的话 | 保存到哪 | 谁能读 |
|---|---|---|
/trellis:record-session |
.trellis/workspace/日志 |
Claude Codex |
存到 memory 里 |
~/.claude/.../memory/ |
仅 Claude |
更新 AGENTS.md |
项目根目录 AGENTS.md |
Claude Codex |
/trellis:update-spec |
.trellis/spec/ |
Claude Codex |
Codex 路径
# ① 完工检查（用自然语言代替斜杠命令）
AI > 帮我做完工检查清单
# ② 如果需要提交代码
AI > 帮我提交代码
# ③ 记录工作日志 ★★★ 每次必做
AI > 把这次工作记录到 journal 日志里
# ④ 更新共享上下文（项目有重大变更时）
AI > 把今天的改动要点更新到 AGENTS.md 里
# ⑤ 如果修了 bug
AI > 分析一下刚才这个 bug 的根因，写进 spec 规范
关键区别：Codex 没有 /trellis:xxx 斜杠命令，全部用自然语言描述。
场景三：续工（新窗口恢复上次的记忆）
Claude Code 新窗口
# ① 系统终端：进入同一个项目目录 + 启动
终端 $ cd C:\Users\21906\Desktop\嵌赛
终端 $ claude
# ② Claude 自动加载项目上下文，通常直接说需求即可
AI > 继续昨天在电赛工程里的车模控制优化
# ③ 如果感觉 AI 状态不对 / 清屏后 / 忘了上下文：
AI > /trellis:start
# ④ 如果 AI 还是对项目细节不清楚（正确补救方式）：
AI > 先根据当前仓库的 AGENTS.md、.trellis/tasks、.trellis/workspace 最新 journal 确认这是哪个项目；如果项目里存在交接文档，再补读交接文档；最后只把能被当前仓库文件印证的 memory 条目当作参考
Codex 新窗口
# ① 系统终端：进入同一个项目目录 + 启动
终端 $ cd C:\Users\21906\Desktop\嵌赛
终端 $ codex
# ② Codex 自动读 AGENTS.md + Trellis Hook 注入，通常可直接续工
AI > 继续昨天的 Web 控制台改造，先看一下当前任务、规范和日志
# ③ 如果 Codex 对细节还不够清楚，再让它按当前仓库优先级补读
AI > 先确认当前仓库身份：读 AGENTS.md、.trellis/tasks 当前任务、.trellis/workspace 最新 journal 和相关 spec
AI > 如果项目里确实存在交接文档，再补读交接文档
AI > 只采用那些能被当前仓库文件印证的背景信息
三场景速查卡
╔═══════════════════════════════════════════════════════════════╗
║ 🎮 三场景完整命令速查 ║
╠═══════════════════╦═══════════════════╦═══════════════════════╣
║ ║ Claude Code ║ Codex ║
╠═══════════════════╬═══════════════════╬═══════════════════════╣
║ 🟢 开工 ║ cd 项目 ║ cd 项目 ║
║ (启动+加载记忆) ║ claude ║ codex ║
║ ║ (自动加载全部， ║ (自动读 AGENTS.md + ║
║ ║ 但先以仓库文件 ║ Trellis 上下文) ║
║ ║ 为准) ║ ║
╠═══════════════════╬═══════════════════╬═══════════════════════╣
║ 🔴 收工 ║ /finish-work ║ "做完工检查" ║
║ (保存记忆) ║ /record-session ║ "记录到journal日志" ║
║ ║ "存memory+更新 ║ "更新AGENTS.md" ║
║ ║ AGENTS.md" ║ ║
╠═══════════════════╬═══════════════════╬═══════════════════════╣
║ 🔵 续工 ║ cd 项目 ║ cd 项目 ║
║ (新窗口恢复记忆) ║ claude ║ codex ║
║ ║ (自动恢复；先核 ║ (自动恢复 AGENTS.md + ║
║ ║ 对 AGENTS/tasks/║ Trellis；先核对 ║
║ ║ journal) ║ AGENTS/tasks/ ║
║ ║ 失忆→/trellis: ║ journal) ║
║ ║ start ║ 不清楚→再读 spec / ║
║ ║ ║ 交接文档（需确认存 ║
║ ║ ║ 在） ║
╚═══════════════════╩═══════════════════╩═══════════════════════╝
Claude 续工防串仓库规则（新增）
为什么会串仓库？
Claude Code 会自动加载 ~/.claude/projects/.../memory/。这个 memory 是 Claude 专属记忆池，有时会按路径聚合出历史项目条目；如果多个项目被归到同一个 memory 目录，里面可能混入别的工程记录。
所以正确规则是：
-
当前仓库第一信源：
AGENTS.md -
第二信源：
.trellis/tasks/当前任务 -
第三信源：
.trellis/workspace/最新 journal -
第四信源：
.trellis/spec/相关规范 -
Claude memory：只能作候选线索，必须被当前仓库文件印证后才能采信
-
交接文档：只有在当前项目里确实存在时才补读，不能凭 memory 里提到过就默认存在
推荐补救提示词：
先确认当前仓库身份：读取 AGENTS.md、.trellis/tasks 当前任务、.trellis/workspace 最新 journal。
如果项目里存在交接文档，再补读交接文档。
最后再参考 memory，但只能采用那些能被当前仓库实际文件印证的条目。
不要再这样说：
看看 memory/ 里的文件，如果项目里还有交接文档，再补读交接文档，回忆一下
因为这句话默认把 memory 当主来源，容易把别的项目记忆误当成当前仓库上下文。
Codex 续工防串仓库规则（新增）
为什么也会串仓库？
Codex 虽然看不到 Claude 的 memory/，但仍然可能因为 错误提示词、旧交接文档、写错的 AGENTS.md、混杂的 task/journal 记录，把别的项目背景误套到当前仓库。
所以正确规则是：
-
当前仓库第一信源：
AGENTS.md -
第二信源：
.trellis/tasks/当前任务 -
第三信源：
.trellis/workspace/最新 journal -
第四信源：
.trellis/spec/相关规范 -
交接文档：只能作增强材料，必须先确认它真实存在于当前项目中
-
外部描述 / 旧对话 / 历史交接内容：只能作候选线索，必须被当前仓库文件印证后才能采信
推荐补救提示词：
先确认当前仓库身份：读取 AGENTS.md、.trellis/tasks 当前任务、.trellis/workspace 最新 journal 和相关 spec。
如果项目里确实存在交接文档，再补读交接文档。
最后只采用那些能被当前仓库实际文件印证的背景信息。
不要再这样说：
看看上次的交接文档，回忆一下，然后继续做昨天那个项目
因为这句话没有先限定当前仓库身份，Codex 很容易先被旧交接内容带偏。
5. 斜杠命令速查表
这些命令是在终端里输入
claude启动 Claude Code 之后，在>提示符后面输入的。
不是在系统命令行（C:\xxx>）里输入的，而是在 Claude Code 的>对话界面里输入的。
日常必用（3 个）
| 命令 | 作用 | 什么时候用 |
|---|---|---|
/trellis:brainstorm |
AI 一步步帮你理清模糊需求 | 需求没想清楚时 |
/trellis:finish-work |
完工检查清单 | 代码写完、准备提交前 |
/trellis:record-session |
记录工作日志 | 每次收工时必用 |
按需使用（4 个）
| 命令 | 作用 | 什么时候用 |
|---|---|---|
/trellis:start |
初始化工作会话 | 一般自动执行，/clear 清屏后手动补一次 |
/trellis:break-loop |
分析 bug 根因 + 预防建议 | 修完 bug 后做复盘 |
/trellis:update-spec |
把经验沉淀为规范 | 发现好模式或踩坑后 |
/trellis:check |
检查代码是否符合规范 | 写完代码想快速校验时 |
进阶功能（3 个）
| 命令 | 作用 | 什么时候用 |
|---|---|---|
/trellis:parallel |
多个 AI 并行开发 | 有 2+ 个独立功能要同时做 |
/trellis:before-dev |
开发前读取相关规范 | 开始复杂任务前 |
/trellis:check-cross-layer |
跨层检查 | 涉及前后端交互时 |
6. 跟 AI 对话的正确姿势
正确示例
/trellis:xxx，Codex 一般用自然语言，不要生搬斜杠命令。
说需求（直接用大白话）：
帮我做一个 UART 串口通信模块，115200 波特率，支持 DMA 收发
让 AI 理清需求：
/trellis:brainstorm
我想给项目加个蓝牙功能，但不确定用什么模块
做完后：
/trellis:finish-work
提交代码（跟 AI 说就行）：
帮我提交代码
记录日志（每次收工前）：
/trellis:record-session
踩坑后沉淀经验：
/trellis:break-loop
/trellis:update-spec
不需要做的事
-
不需要跟 AI 说"我的项目用了什么技术"（Trellis 自动告诉它了）
-
不需要解释"上次做到哪了"（日志自动读取）
-
不需要复制粘贴代码给 AI（它能直接读你的文件）
-
不需要手动执行
/trellis:start（启动时自动执行）
对话技巧
-
需求描述越具体越好
-
差：
帮我写个定时器 -
好：
帮我用 TIM2 配置一个 1ms 的定时器中断，用于系统心跳计数
-
-
可以分步提需求
-
第一轮：
先帮我做基本的 UART 收发 -
AI 做完后：
再加上 DMA 传输功能 -
再之后：
加个空闲中断接收不定长数据
-
-
发现问题时
-
这里编译报错了：xxx（贴错误信息） -
UART 发送没反应，帮我排查一下
-
7. Spec 规范管理
规范文件在哪
你的项目/.trellis/spec/
├── frontend/ # 前端规范（如果有）
├── backend/ # 后端规范（如果有）
└── guides/ # 通用指南
初始状态
初始化后 spec 里都是 空模板，不用急着填。
三种填充方式
方式 1：让 AI 帮你生成（最推荐）
在 Claude Code 里说：
"根据我现在的代码，帮我生成 backend 的代码规范"
方式 2：边做边补
今天踩了个坑 → /trellis:update-spec → AI 自动把经验写进规范
方式 3：手动编辑
直接用编辑器打开 .trellis/spec/ 下的 .md 文件，写你的规范
一份好的规范长什么样
# UART 通信规范
## 必须遵守
- 波特率配置必须与硬件设计文档一致
- DMA 传输必须配置 Half Transfer 和 Transfer Complete 双回调
- 禁止在中断中调用 printf
## 好的例子
void USART1_Init(uint32_t baudrate) {
// 完整的初始化代码...
}
## 坏的例子（禁止）
// ❌ 硬编码波特率
USART1->BRR = 0x1D4C; // 不知道这是多少
## 常见错误
- ❌ 忘记开启时钟 → ✅ 先 RCC_APBxPeriphClockCmd
- ❌ DMA 通道冲突 → ✅ 查手册确认通道映射
规范飞轮效应
Day 1: 写代码
Day 3: 踩坑 → 写进 spec
Day 5: AI 自动读到这条 spec → 不再犯同样的错
Day 30: spec 越来越完善 → AI 写的代码越来越像"老员工"
8. 并行开发（进阶）
什么时候用
你有 2 个以上互不相关的功能 要同时做。
例如：
-
功能 A：UART 通信模块
-
功能 B：OLED 显示模块
怎么用
在 Claude Code 对话框里输入：
/trellis:parallel
帮我同时做两个功能：
1. UART 通信模块
2. OLED 显示驱动
AI 会自动：
-
创建两个独立任务
-
为每个任务创建独立的 Git 分支和代码副本（worktree）
-
启动两个独立的 Claude Code Agent 并行开发
-
各自完成后自动创建 PR
每个 Agent 的自动流程
① implement（写代码）→ ② check（检查质量）→ ③ finish（最终验证）→ ④ create-pr（创建PR）
你只需要最后审核合并 PR 就行。
9. 目录结构说明
Trellis 在项目里生成的文件
你的项目/
├── .trellis/ # 🌿 Trellis 核心目录（Claude 和 Codex 共享）
│ ├── config.yaml # 配置文件
│ ├── workflow.md # 工作流定义
│ ├── worktree.yaml # 并行开发配置
│ ├── spec/ # 📏 规范文件（最重要！两个平台共享）
│ │ ├── frontend/ # 前端规范
│ │ ├── backend/ # 后端规范
│ │ └── guides/ # 通用指南
│ ├── tasks/ # 📋 任务管理（两个平台共享）
│ │ └── [日期-任务名]/ # 每个任务一个文件夹
│ │ ├── task.json # 任务信息
│ │ └── prd.md # 需求文档
│ ├── workspace/ # 📝 工作区（两个平台共享）
│ │ └── ZQYuan/ # 你的工作空间
│ │ └── journal-1.md # 工作日志（record-session 写这里）
│ └── scripts/ # 🔧 内部脚本（不用管）
├── .claude/ # 🟠 Claude Code 专属配置
│ ├── settings.json # 含 Trellis 的 hooks 配置
│ └── skills/ # Claude 的斜杠命令
├── .codex/ # 🟢 Codex 专属配置
│ ├── hooks/ # Codex hooks
│ │ └── session-start.py # 启动时自动注入 Trellis 上下文
│ └── skills/ # Codex 的斜杠命令
├── .agents/ # 🔵 共享 Agent 配置（Codex/Cursor/Gemini 等读取）
│ └── skills/ # 共享的斜杠命令
└── AGENTS.md # 多平台 Agent 入口文件
你需要关心的文件
| 文件/目录 | 你需要做什么 |
|---|---|
.trellis/spec/ |
逐步填写你的项目规范（或让 AI 帮你生成） |
.trellis/workspace/ZQYuan/journal-*.md |
自动生成的日志，不用手动改 |
.trellis/tasks/ |
AI 自动创建和管理，不用手动改 |
| 其他文件 | 不用管，Trellis 自动维护 |
10. 常见问题 FAQ
Q: trellis init 报 “not a git repository”
A: 先运行 git init，再运行 trellis init。
Q: trellis init 的交互选择界面在 CMD 里显示异常
A: 建议用 Git Bash 或 Windows Terminal 代替原生 CMD。或者用非交互命令：
trellis init -u ZQYuan --claude --skip-existing
Q: 已有 CLAUDE.md 会冲突吗？
A: 不会。Trellis 生成的文件在 .trellis/ 和 .claude/ 目录下，不影响你的 CLAUDE.md。
Q: Spec 模板都是空的怎么办？
A: 三个办法：
-
让 AI 帮你写：
"根据我的代码帮我生成规范" -
边做边补：踩坑后用
/trellis:update-spec -
用社区模板：
trellis init --template electron-fullstack
Q: 中途清了对话（/clear）怎么办？
A: 输入 /trellis:start 重新加载上下文即可。
Q: 换了台电脑怎么办？
A: .trellis/ 目录跟着 Git 仓库走。新电脑上 git clone 下来后全局装一遍 Trellis，直接 claude 就能接着干。
Q: Trellis 怎么升级？
A: 分两步，作用不同：
# 第 1 步：升级 Trellis 程序本身（全局，在哪都能跑，只需跑一次）
npm install -g @mindfoldhq/trellis@latest
# 第 2 步：更新某个项目里的 .trellis/ 模板文件（每个项目各跑一次）
cd 你的项目
trellis update
第 2 步是把项目里的旧模板同步到新版，必须 cd 到项目里才行。
如果你有多个项目，每个项目都要进去跑一次trellis update。
Q: 多人团队怎么用？
A: 每人用自己的名字初始化 -u 名字。Spec 共享（通过 Git），Journal 各自独立。
Q: Codex 的 hooks 不生效怎么办？
A: 确认两点：
-
~/.codex/config.toml里有[features]下的codex_hooks = true -
Codex CLI 版本 >= 0.116.0（hooks 是实验性功能，需要较新版本）
Q: Claude 和 Codex 同时用会冲突吗？
A: 不会。它们共享 .trellis/（spec/tasks/journal），但各有独立的配置目录（.claude/ 和 .codex/）。可以同时在两个终端窗口分别跑 claude 和 codex。
Q: 已有项目只配了 Claude，想加上 Codex 支持？
A: 在项目目录里重新跑一次 init，加上 --codex：
cd 项目目录
trellis init -u ZQYuan --claude --codex --skip-existing
然后确保全局 ~/.codex/config.toml 里开启了 codex_hooks = true。
11. 终端命令速查
这些是在 系统终端 里输的，不是 Claude Code 对话框。
| 命令 | 说明 | 什么时候用 |
|---|---|---|
trellis --version |
查看版本 | 确认安装/升级 |
trellis init -u 名字 --claude --codex --skip-existing |
初始化项目（双平台） | 新项目第一次配置 |
trellis init -u 名字 --claude --skip-existing |
初始化项目（仅Claude） | 只用 Claude Code 时 |
trellis update |
更新项目里的 Trellis 文件 | Trellis 发布新版后 |
claude |
启动 Claude Code | 每天开始工作时 |
codex |
启动 Codex | 用 Codex 开发时 |
cd 项目路径 && claude |
进入项目并启动 Claude | 最常用的组合 |
cd 项目路径 && codex |
进入项目并启动 Codex | 用 Codex 时 |
极简速查卡
╔══════════════════════════════════════════════════════╗
║ 🌿 Trellis 日常操作（Claude Code + Codex 通用） ║
║ ║
║ 📦 新项目： ║
║ cd 项目 → git init ║
║ → trellis init -u ZQYuan --claude --codex ║
║ ║
║ 🌅 每天开工： ║
║ cd 项目 → claude（或 codex） ║
║ ║
║ 💬 工作中（> 提示符后输入）： ║
║ /trellis:brainstorm 理清需求 ║
║ /trellis:finish-work 完工检查 ║
║ /trellis:record-session 记日志 ★必做 ║
║ ║
║ 🔧 按需： ║
║ /trellis:break-loop 复盘 bug ║
║ /trellis:update-spec 沉淀经验 ║
║ /trellis:parallel 并行开发 ║
║ ║
║ 🔑 口诀：做前 brainstorm ║
║ 做完 finish-work ║
║ 走前 record-session ║
║ ║
║ ⚙️ Codex 额外配置（一次性）： ║
║ ~/.codex/config.toml → [features] ║
║ codex_hooks = true ║
╚══════════════════════════════════════════════════════╝
12. 记忆与上下文管理（跨工具持久化）
记忆层级总览
┌──────────────────────────────────────────────────────────┐
│ 记忆持久化层级 │
├──────────┬───────────────┬───────────┬───────────────────┤
│ 层级 │ 存储位置 │ Claude │ Codex │
├──────────┼───────────────┼───────────┼───────────────────┤
│ 全局规则 │ ~/.claude/ │ ✅ 自动 │ ❌ 看不到 │
│ │ CLAUDE.md │ │ │
├──────────┼───────────────┼───────────┼───────────────────┤
│ Claude │ ~/.claude/ │ ✅ 自动 │ ❌ 看不到 │
│ 专属记忆 │ projects/ │ │ │
│ │ .../memory/ │ │ │
├──────────┼───────────────┼───────────┼───────────────────┤
│ 双平台 │ 项目根目录/ │ ✅ 自动 │ ✅ 自动 │
│ 共享入口 │ AGENTS.md │ │ │
├──────────┼───────────────┼───────────┼───────────────────┤
│ Trellis │ .trellis/ │ ✅ Hook │ ✅ Hook │
│ 共享数据 │ spec/tasks/ │ 自动注入 │ 自动注入 │
│ │ workspace/ │ │ │
├──────────┼───────────────┼───────────┼───────────────────┤
│ 交接文档 │ 项目根目录/ │ ✅ 需指引 │ ✅ 需指引 │
│ (最完整) │ *交接*.md │ │ │
└──────────┴───────────────┴───────────┴───────────────────┘
关键原则
三层存储策略：
| 存哪里 | 存什么 | 谁能读 |
|---|---|---|
AGENTS.md |
精简版项目上下文（架构、团队、关键文件） | 所有 AI 工具 |
~/.claude/projects/.../memory/ |
详细版（参数、风险、教训、用户偏好），仅供 Claude 参考，且必须先核对当前仓库是否匹配 | 仅 Claude |
交接文档（如 第二阶段新会话交接.md） |
最完整版（全部材料清单、时间线、决策记录），可选增强，且必须先确认文件真实存在于当前项目 | 任何工具（需手动指引） |
日常维护清单
每当项目上下文发生重大变更时（新阶段、新架构决策、关键人员变动等）：
-
更新交接文档（最完整的信息源）
-
更新
AGENTS.md（精简版，供 Codex 等工具自动读取） -
如果用 Claude，让它更新 memory 文件（详细版）
实际操作示例
在 Claude Code 里让它存记忆：
把我们刚才的架构决策存到 memory 里，同时更新 AGENTS.md
在 Codex 里恢复上下文：
先读一下 AGENTS.md、.trellis/tasks 当前任务和 .trellis/workspace 最新 journal；如果项目里确实存在交接文档，再补读交接文档，然后帮我做 XXX
新开 Claude Code 会话时：
/trellis:start
Claude 会自动加载 memory + AGENTS.md + Trellis 上下文，但续工时必须先以当前仓库文件为准，再把 memory 当辅助参考。
万一 AI "失忆"了：
先确认当前仓库身份：读取 AGENTS.md、.trellis/tasks 当前任务、.trellis/workspace 最新 journal；如果项目里存在交接文档，再补读交接文档；最后只参考那些能被当前仓库文件印证的 memory 条目
环境踩坑经验
以下是实际踩过的坑，已写入全局规则防止复发。
| 坑 | 现象 | 解决 |
|---|---|---|
python3 是假的 |
Windows 上 python3 是 MS Store 占位符，exit code 49 |
用 python 代替 |
| 系统路径不准 | AI 拿到的 platform/路径元数据可能错误 | 每次先 pwd 确认真实路径 |
| Claude memory 不跨工具 | 存在 ~/.claude/ 下的记忆 Codex 读不到 |
关键信息同步写入 AGENTS.md |
| Claude memory 可能串仓库 | memory 中可能混入同路径下其他项目旧条目 | 续工先核对 AGENTS.md、.trellis/tasks/、.trellis/workspace/，再参考 memory |
参考资源：