跳转到主要内容

​
附录 F：FAQ

​
Q1: 每次开会话要先跑点什么吗？

有 SessionStart hook 的平台（Claude Code、Cursor、OpenCode、Gemini CLI、Qoder、CodeBuddy、Copilot、Droid——以及开了 codex_hooks = true 的 Codex）上下文自动注入，直接描述任务就行。没有 SessionStart hook 的平台（Kiro、Kilo、Antigravity、Windsurf）跑 /trellis:start（Kiro 是 @trellis:start）加载完整上下文报告。

​
Q2: 怎么让 AI 在我 commit 前验证质量？

这是 trellis-check sub-agent 的工作。实现阶段之后，主会话 spawn 它（没有 sub-agent 的平台则 skill 内联跑）。它读相关 spec，跑 lint / typecheck / test，对照质量 checklist 比对 diff，自修复违规。不涉及外部重试循环。

​
Q3: trellis-break-loop 分析完 bug 后要做什么？

skill 分析根因并提出预防机制。把结论走 trellis-update-spec skill，它会写进 .trellis/spec/。下次任何人在这个领域工作，更新后的 spec 会自动注入。

​
Q4: 会话历史存在哪？

.trellis/workspace/
├── index.md              # 所有开发者的主索引
└── {your-name}/
    ├── index.md          # 个人索引
    └── journal-N.md      # 会话日志（约每 2000 行新起一个文件）

​
Q5: spec 写多细？

每文件 200-500 行、每小节 20-50 行。具体代码例子比抽象规则有用。发现过时立即更新。

​
Q6: 多人用 Trellis 会冲突吗？

按开发者隔离（workspace/{name}/、.developer、.current-task）。共享状态是 .trellis/spec/ 和 .trellis/tasks/，走 PR review。建任务时用 --assignee 避免撞车。

​
Q7: 怎么把已有项目迁到 Trellis？

  1. npm install -g @mindfoldhq/trellis@beta
  2. 项目根下 trellis init -u your-name（自动建 bootstrap 任务）。
  3. 跑 /trellis:start，brainstorm skill 帮你填初始 spec。
  4. 按团队约定手动补充核心 spec。
  5. 把 .trellis/ 和你用的 .{platform}/ 目录 add 并 commit。
  6. 队友 pull 后各自 trellis init -u their-name。

​
Q8: 更新 Trellis 时怎么不丢自定义内容？

trellis update --dry-run   # 预演
trellis update             # 应用
Trellis 在安装时对每个模板文件算 hash。update 时发现你改过的文件：未改的自动覆盖，改过的会询问（覆盖 / 跳过）。用 -f 全部强制覆盖、-s 全部跳过。 大版本时加 --migrate 应用 migration manifest 里的 rename / delete。不加 --migrate 碰到破坏性 manifest 会打印说明并退出，不静默重命名。

​
Q9: Cursor 用户能拿到和 Claude Code 一样的自动化吗？

大部分能。Cursor 没有 SessionStart hook，但 .cursor/rules/trellis.mdc 是 alwaysApply 规则，把 Trellis prelude 带进每次对话。Cursor 没有 sub-agent，原本在 trellis-implement / trellis-check 里跑的工作会在主会话里内联。Skill 以 rules 内容形式交付，由 Cursor 的规则系统匹配。

​
Q10: Windows 用户怎么装 Trellis？

所有脚本都是 Python，跨平台： 
# 1. 装 Node.js 18+ 和 Python 3.10+
# 2. 装 Trellis
npm install -g @mindfoldhq/trellis@beta
# 3. 初始化
cd your-project
trellis init -u your-name
trellis init 会自动把 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 写进 .claude/settings.json（0.5.0-beta.8 起）。这个环境变量让 Bash 工具的 cwd 保持稳定，hook 脚本在 Windows 上也能正确解析路径——不需要手动配。

​
Q11: 切换 AI 编码工具时要重配吗？

不用。trellis init 带多个平台 flag 能一次写多份。已经用了 Cursor 后来想加 Claude Code： 
trellis init -u your-name --claude
.trellis/ 跨工具共享，只是多写一个 .{platform}/ 目录。

​
Q12: command / skill / sub-agent 有什么区别？

原语触发者典型用途
Command用户（/trellis:*）会话边界（start、finish-work、continue）
Skill平台自动匹配阶段工作流（brainstorm、before-dev、check、update-spec、break-loop）
Sub-agent主会话 spawn隔离角色（implement、check、research）
选型指南见第 9–12 章。

​
Q13: .agents/skills/ 共享目录还有吗？

有。Codex configurator 把 Trellis 五个 skill 都写到 .agents/skills/ 作为跨平台共享层，遵循 agentskills.io 规范。任何读这个位置的 agent（Amp、Cline、Deep Agents、Firebender、Kimi Code CLI、Warp 等）都能直接用，不需要单独出一个 configurator。

​
Q14: 0.4 → 0.5 改了什么？

主要变化：
  • Skill-first：brainstorm / before-dev / check / update-spec / break-loop 从 slash 命令改为 auto-trigger skill，由平台根据用户意图自动匹配。
  • workflow.md 是单一事实源：Phase 定义、skill 路由、每轮 workflow-state 提醒都在 .trellis/workflow.md 里。Fork 工作流 = 改一个 markdown 文件，不用动 Python、不用改 hook（见第 8 章）。
  • 每轮 workflow-state 面包屑：新增 inject-workflow-state.py hook，每条用户消息触发一次，按当前任务 status 注入 <workflow-state> 块，帮 AI 稳定走完 Plan → Execute → Finish 三阶段。
  • 3 个 sub-agent 取代 6 个：trellis-research / trellis-implement / trellis-check；dispatch / plan / debug 移除；Ralph Loop 和它的 SubagentStop hook 也移除（check sub-agent 自带重试循环）。
  • 7 个平台升级为 agent-capable：Cursor / OpenCode / Gemini CLI / Qoder / CodeBuddy / Copilot / Droid 都拿到了 sub-agent + hook；.trellis/ 核心跨 13 个平台保持一致。
  • Multi-Agent Pipeline、/parallel、worktree.yaml 移除：现代 agent CLI 的原生 worktree 支持已经替代它。
  • 强制迁移 gate：破坏性版本必须加 --migrate，没加会 exit 并打印说明，不再静默留下半迁移状态。
完整清单见 v0.5.0-beta.0 changelog。