跳转到主要内容

​
附录 F：FAQ

​
Q1: 什么时候用 /start vs /parallel？

维度/start/parallel
任务复杂度简单到中等复杂，可拆分
预计时间< 30 分钟> 30 分钟
独立性单一任务多个独立子任务
隔离不需要需要（worktree）

​
Q2: 什么时候需要 /check-cross-layer？

必须用：修改涉及前端 + 后端 + 数据库的功能 建议用：修改 API 接口或数据库 schema 不需要：纯前端 UI 调整或纯后端内部逻辑

​
Q3: /break-loop 分析完之后怎么办？

/break-loop 做深度分析后，你应该手动将分析结果更新到 .trellis/spec/ 中的规范文件，然后 git push。下次会话 Hook 会自动注入更新后的规范。 
修复 Bug → /break-loop 深度分析 → 手动更新 spec → git push → 下次自动防止

​
Q4: 如何监控多 Agent 并行任务？

./.trellis/scripts/multi-agent/status.py                  # 概览
./.trellis/scripts/multi-agent/status.py --log <name>     # 查看日志
./.trellis/scripts/multi-agent/status.py --watch <name>   # 实时监控
日志位置：worktree 目录下的 .dispatch-log 和 .plan-log。

​
Q5: 会话历史存在哪里？

.trellis/workspace/
├── index.md              # 总索引（所有开发者）
└── {your-name}/
    ├── index.md          # 个人索引（会话总数、最后活跃、历史表）
    └── journal-N.md      # 会话日志（每个文件最多 2000 行）

​
Q6: Spec 应该写多详细？

200-500 行 / 文件，20-50 行 / 章节 原则：
  • 具体到有代码示例
  • 解释为什么，不只是什么
  • 简洁——一个概念一个章节
  • 可操作——AI 能直接照做
  • 时效性——发现过时立即更新

​
Q7: 多人使用 Trellis 会冲突吗？

不冲突：workspace（各人独立）、.developer（gitignored）、并行 worktree 可能冲突：spec 文件（通过 PR 审查解决）、任务管理（用 —assignee 明确指派）

​
Q8: 如何从现有项目迁移到 Trellis？

  1. npm install -g @mindfoldhq/trellis@latest
  2. trellis init -u your-name（自动创建 bootstrap 引导任务）
  3. 运行 /start，AI 自动检测 bootstrap 任务并帮你填充 spec
  4. 手动补充核心规范
  5. 将 .trellis/ 和 .claude/ 加入 Git
  6. 提交并推送，团队成员 pull 后执行 trellis init -u their-name

​
Q9: Ralph Loop 验证失败怎么办？

  1. Check Agent 会自动尝试修复（最多 5 次循环）
  2. 如果 5 次后仍然失败，Ralph Loop 强制放行并打印警告
  3. 你可以手动检查并修复，然后重新运行 check
  4. 如果 verify 命令本身有问题，调整 worktree.yaml 的 verify 配置

​
Q10: 如何更新 Trellis 而不丢失自定义配置？

# 先预览更新内容
trellis update --dry-run

# 执行更新
trellis update
# Trellis 会自动检测你修改过的文件
# 未修改的文件直接更新
# 修改过的文件提示你选择：覆盖/跳过/合并

​
Q11: 我用 Cursor，能享受和 Claude Code 一样的自动化吗？

不完全一样。Cursor 不支持 Hook 系统，因此：
  • 没有自动注入 — 需要手动运行 /start 加载上下文
  • 没有 Ralph Loop — 需要手动运行 /trellis-check-backend 等检查命令
  • 没有 Multi-Agent Pipeline — 不支持 /parallel 并行编排
  • 核心功能保留 — Spec 管理、Task 管理、跨会话记忆（通过 /start）、所有检查命令均可用
Cursor 用户通过手动调用命令可以达到 Claude Code 约 80% 的效果。详见 13.2 Cursor 集成。

​
Q12: Windows 用户如何安装 Trellis？

Trellis 脚本已全部迁移为 Python，原生支持 Windows： 
# 1. 确保已安装 Node.js 和 Python 3.8+

# 2. 安装 Trellis
npm install -g @mindfoldhq/trellis@latest

# 3. 正常初始化
cd your-project
trellis init -u your-name

​
Q13: 从 Cursor 切换到 Claude Code 需要重新配置吗？

不需要。trellis init 在初始化时同时生成 .claude/ 和 .cursor/ 配置。 如果项目中已有 .cursor/commands/ 但没有 .claude/，只需重新运行： 
trellis init -u your-name
Trellis 会自动检测环境并补全缺失的配置。你的 .trellis/ 目录（Spec、Workspace、Tasks）完全共享，无需重新创建。

​
Q14: Kilo Code 和 Claude Code 的多 Agent 有什么区别？

两者都支持多 Agent 并行，但机制不同：
维度Claude Code（Trellis）Kilo Code
隔离方式git worktree 物理隔离独立对话上下文（Orchestrator Mode）
编排方式Hook 驱动（dispatch → implement → check）模式切换（Code / Architect / Debug 等）
并行数量取决于 worktree 数量取决于模式和上下文
代码合并各 worktree 独立 PR → 合并同一工作区内
配置worktree.yaml + Hook 脚本内置，无需额外配置

​
Q15: Kiro 的 Spec 模式和 Trellis 的任务管理怎么配合？

Kiro 的 Spec-Driven Development 和 Trellis 的任务系统可以互补：
  1. 用 Trellis 创建任务：task.py create "新功能" 生成 prd.md
  2. 用 Kiro Spec 细化：在 Kiro 中选择 Spec 模式，基于 prd.md 自动生成 requirements.md → design.md → tasks.md
  3. Kiro 按 tasks.md 实现：Agent Hooks 在文件修改时自动触发检查
  4. 用 Trellis 记录：/record-session 记录会话，task.py finish 归档任务
Kiro 的 .kiro/specs/ 和 Trellis 的 .trellis/tasks/ 各管各的，互不冲突。

​
Q16: Kilo Code 的 Skills 和 Trellis 的 Skills 是同一个东西吗？

是的，它们遵循相同的 Agent Skills 开放标准。一个 SKILL.md 文件可以同时在 Kilo Code、Cursor、Claude Code 等支持该标准的平台上使用。 Kilo 的 Skills 存放在 .kilocode/skills/*/SKILL.md，Claude Code 的在 .claude/skills/ 或 .agents/skills/。格式兼容，可以互相复制使用。

​
Q17: OpenCode 和 Codex 的 Trellis 配置兼容吗？

部分兼容。两者共用 .agents/skills/ 目录。Codex 依赖 AGENTS.md 作为入口文件；OpenCode 则支持 session hook 自动注入上下文，命令使用 / 前缀（如 /start），体验更接近 Claude Code。