跳转到主要内容

​
通用

Skills 是可选的 — AI 可能跳过它们，导致质量不一致。Trellis 通过注入来强制执行规范。不管 AI “想不想”，每次会话都会拿到规范。
AI 通常根据你的指示来生成规范。但当你有 AI 无法独立弄明白的架构洞察时，你应该参与进来 — 比如”我们用这个错误格式是因为 X 历史原因”或者”这个模式存在是因为 Y 约束”。
那些格式每次都加载全部内容。如果你有 50 页规范，每个会话都读全部 50 页。Trellis 用分层架构和上下文压缩。JSONL 文件指定哪个任务加载哪些规范。你的认证功能加载认证规范。你的 UI 组件加载前端规范。噪音少，信号多。
不会。每个团队成员在 .trellis/workspace/{name}/ 有隔离的工作区。你的日志是你的。队友的日志是他们的。规范是共享的，这正是重点 — 所有人遵循同样的约定。
用 /trellis:record-session 让 AI 把摘要写到日志文件。下次会话开始时，它读取最近的日志和 git 信息来恢复上下文。这不是魔法记忆。是明确的日志记录。你控制什么被记住。
核心系统（specs、tasks、workspace）能用。你读规范文件然后遵循它们。Hooks：Cursor 已原生支持 hooks，但 Trellis 还没做 Cursor 的 hook 适配（后续计划中）。目前每次会话开始你仍需手动引用规范文件。Multi-Agent（同目录多 agent）：有限支持，需手动协调。Multi-Session（worktree 隔离）：不支持。

​
Specs 规范

短到能在 30 秒内扫完。如果更久，拆成多个文件。AI 会读整个规范，但规范太长时每部分得到的注意力就少。
常见原因：
  1. 太模糊 — “用好的错误处理”没意义。加上带代码例子的具体模式。
  2. 没例子 — 放实际代码。AI 从例子学比从描述学更有效。
  3. 路径过时 — 如果你引用的文件不存在了，规范就让人困惑。
  4. 规则冲突 — 两个规范说了不同的事。选一个。
测一下：开新会话，让它写规范覆盖的代码，看规则有没有被遵循。
可以。文档风格、commit message 格式、PR 模板、API 设计模式 — 任何你想保持一致的东西。

​
Tasks 和 Workspace

不用。任务在需要追踪和上下文隔离时有帮助。快速修复不需要任务。多天的功能开发有任务会受益。
会话在没有任务特定上下文的情况下运行。规范还是会从默认值加载，但 AI 不知道你的 PRD 或任务特定的文件。做任务相关的工作时，先用 /trellis:start 命令开始会话。
每行指定一个要包含的文件：
{"file": ".trellis/spec/backend/index.md", "reason": "后端编码规范"}
{"file": "src/api/users.ts", "reason": "API 实现上下文"}
不同 agent 拿到不同的文件。implement agent 可能比 check agent 需要更多上下文。

​
多 Agent

没有硬性限制，但实际受限于：
  • API 额度（每个 agent 消耗 token）
  • 你审查输出的能力
3-5 个 agent 可控。再多就难跟踪了。
取决于运行模式：
  • Multi-Agent（同目录）：agent 共享同一目录，可能产生冲突。规划任务时避免文件重叠。
  • Multi-Session（worktree）：每个 agent 在独立的 Git worktree 工作，开发过程不冲突。合并 PR 时再解决冲突。

​
问题排查

Trellis 在后台工作。没有 UI 变化。验证：
  1. .trellis/ 目录存在
  2. .claude/settings.json 有 hook 配置
  3. 开个会话 — 规范应该出现在上下文里
可能的原因：
  1. 规范没加载：检查 .trellis/spec/ 和 JSONL 上下文文件的路径
  2. 对话太长：AI 可能在长对话中「忘记」规范。开新会话或提醒它
  3. 规范清晰度：具体的规范比模糊的更有效
Trellis 能提升一致性，但不是银弹。AI 仍然会犯错。
先更新 CLI：
npm install -g @mindfoldhq/trellis@latest
然后更新项目：
trellis update
这只动没改过的文件，你改的东西不会丢。改动前会自动创建备份到 .trellis/.backup-{时间戳}/。有破坏性改动（比如目录结构调整）时，加 --migrate：
trellis update --migrate
这会执行文件迁移 — 重命名和删除旧文件来适配新结构。改过的文件会先问你再动。