Trellis 技术文档 - 从理念到实践

前几天 Anthropic 发了一篇文章 Effective Harnesses for Long-Running Agents,介绍他们在内部实践的 AI 辅助开发模式——让 AI 拥有"长时记忆",能记住项目规范、过往决策和代码风格。这个思路很有启发性,但他们讲的比较理论化,没有给出太多实际落地的细节。

我们最近把这套思路落地成了一个开源工具 Trellis,并且为了适应真实的多人协作场景,做了不少扩展。这篇文章就来聊聊我们是怎么做的,遇到了哪些坑,以及最后搭出来的这套系统实际用起来是什么感觉。

一、起点:Anthropic 的理念与现实的距离

Anthropic 提出的核心想法是:不要每次都从零开始跟 AI 对话,而是让 AI 一开始就能看到项目的"记忆"。

这个"记忆"包括:

• 项目的技术栈和架构规范

• 代码风格约定

• 过去讨论过的设计决策

• 常见问题的解决方案

他们的做法是把这些内容整理成文档,放在项目里,然后在跟 AI 对话时,把相关文档的内容喂给 AI。这样 AI 就能像一个"了解项目背景的老员工"一样工作,而不是每次都得从头解释一遍。

听起来很简单,但真要在一个多人协作的真实项目里落地,会遇到很多实际问题:

• 多个开发者同时工作怎么办? 如果大家的进度都记在一个文件里,很容易冲突。

• 规范文档太长怎么办? 完整的前后端规范可能有几千行,全塞给 AI 会爆 token,而且大部分内容对当前任务其实没用。

• 怎么保证 AI 真的遵守规范? 即使在会话开始时读了规范,AI 在长对话中也会"遗忘"。

• 怎么保证代码质量? AI 写的代码不能直接合到主分支,得有人审核、测试。

• 怎么记录 AI 的工作? 如果出了问题,怎么回溯 AI 到底做了什么?

• 多个 AI 并行开发怎么隔离? 多个 Agent 同时工作容易互相冲突。

我们在 Trellis 里针对这些问题做了一些设计。

二、落地:八个核心设计决策

1. 多人协作:每个开发者有独立的进度文件夹

Anthropic 的文章里没怎么提多人协作的问题,但这在真实项目里是绕不开的。

我们的做法是:在 .trellis/workspace/ 目录下,给每个开发者创建一个独立的文件夹。

比如:

.trellis/
└── workspace/
    ├── index.md                 # 活跃开发者列表
    ├── taosu/                   # 开发者 taosu 的目录
    │   ├── index.md             # 个人会话索引
    │   └── journal-1.md         # 会话记录
    └── developer2/              # 开发者 developer2 的目录
        ├── index.md
        └── journal-1.md

每个开发者的 index.md 记录当前在做什么、做到哪一步了、遇到了什么问题。AI 在开始工作前会先读这个文件,了解上下文;工作结束后会更新这个文件,记录新的进度。

这样多个开发者可以同时工作,不会互相干扰。

2. 解决信息过载:模块化规范 + 按需注入

前面提到,完整的开发规范可能有几千行。在实践中,我们发现直接把完整文档喂给 AI 会带来几个问题:

为什么需要按需注入?

1. **信息过载问题:**当 AI 需要实现一个"用户认证功能"时,如果把完整的前后端规范全部读取,AI 会被大量无关内容干扰——比如"前端组件规范"、"性能优化规范"等。这些内容虽然重要,但对当前任务没有帮助,反而会降低 AI 的注意力集中度。

2. **Token 经济性问题:**在长对话中,如果每次都读取完整文档,token 消耗会迅速累积。

3. **上下文腐烂问题:**上下文过多会导致 AI 分心、混淆、冲突——这被称为"上下文腐烂(Context Rot)"。

我们的解决方案:模块化规范 + Hook 自动注入

我们把规范拆分成细粒度的文件:

.trellis/
└── spec/
    ├── backend/
    │   ├── index.md                 # 后端规范入口
    │   ├── database-guidelines.md   # 数据库规范
    │   ├── error-handling.md        # 错误处理
    │   └── logging-guidelines.md    # 日志规范
    ├── frontend/
    │   ├── index.md                 # 前端规范入口
    │   ├── component-guidelines.md  # 组件规范
    │   ├── hook-guidelines.md       # Hook 规范
    │   └── state-management.md      # 状态管理
    └── guides/
        ├── cross-layer-thinking-guide.md  # 跨层开发思考
        └── code-reuse-thinking-guide.md   # 代码复用思考

关键创新:不是让 AI "记住"规范,而是在需要的时候自动注入

每个 Task 有三个 jsonl 文件,记录不同阶段需要读取的规范:

# 完整路径: .trellis/tasks/{MM}-{DD}-{name}/
# 示例:
.trellis/tasks/01-19-user-auth/
├── implement.jsonl   # Implement Agent 需要的规范
├── check.jsonl       # Check Agent 需要的规范
└── debug.jsonl       # Debug Agent 需要的规范

比如 implement.jsonl 可能是这样:

{"file": ".trellis/spec/backend/index.md", "reason": "后端开发规范"}
{"file": ".trellis/spec/backend/database-guidelines.md", "reason": "数据库操作规范"}
{"file": "src/api/auth.ts", "reason": "现有认证模式参考"}

工作原理:

当 Dispatch Agent 调用 Implement Agent 时,Hook 脚本 inject-subagent-context.py 会:

1. 读取 implement.jsonl

2. 把列出的所有文件内容注入到 Implement Agent 的 prompt 中

3. Implement Agent 启动时就带有完整的上下文,不需要自己去找规范

这样:

• 精准:AI 只看到当前任务相关的规范(比如 500 行而不是 3000 行)

• 可靠:规范是被注入的,不是靠 AI "记忆",不会遗忘

• 可追溯:jsonl 文件记录了用了哪些规范,出问题时可以追溯

3. 自动化会话初始化:SessionStart Hook

传统方式的问题:

在没有 Hook 的情况下,用户每次开始新会话都需要手动输入 /start 命令让 AI 读取上下文。这有几个问题:

• 容易忘记
• 额外的操作步骤
• 如果忘记了,AI 就不知道项目规范

我们的方案:SessionStart Hook 自动注入

Trellis 使用 Claude Code 的 Hook 机制,在每次新会话启动时自动注入上下文,用户不需要做任何操作。

当你打开 Claude Code 开始新会话时,session-start.sh 会自动执行,注入:

1. 当前状态:开发者身份、Git 分支、未提交文件、当前 Feature、Backlog 等
2. 工作流指南:workflow.md 完整内容
3. 规范索引:frontend/backend/guides 的 index.md
4. 会话指令:start.md 中定义的任务分类和 Feature Workflow

用户体验:

# 用户只需要直接说需求,不需要任何初始化命令
用户:帮我修复用户头像显示不正确的 bug

# AI 已经自动获得了所有上下文,可以直接开始工作
AI:好的,我看到当前分支是 fix/avatar-display,你已经修改了 UserAvatar.tsx。
   让我分析一下问题...

4. 封装最佳实践:Slash Command 系统

除了自动注入的上下文,我们还定义了一系列 Slash Command 用于特定操作:

• /parallel:启动多 Agent 并行开发流水线(复杂功能)

• /check-frontend / /check-backend:检查代码是否符合规范

• /finish-work:提交前检查清单

• /record-agent-flow:记录本次工作内容

Slash Command 是什么?

Slash Command 其实就是预定义的提示词模板。每个命令是一个 .md 文件。

为什么要用 Slash Command?

因为每次让 AI 做代码检查、记录进度这些事情,都得输入一大段详细的指令。如果这些指令写得不够详细,AI 的输出质量就会不稳定。

Slash Command 把这些最佳实践的提示词封装起来,开发者只需要输入一个简短命令,就相当于发送了一个精心设计的完整提示词,保证了指令的一致性和完整性。

而且 Slash Command 可以在团队间共享,新人也能直接用上团队积累的经验。

5. 任务生命周期:Backlog → Feature → Archive

在真实的团队开发中,任务有清晰的生命周期。Trellis 用 Backlog 和 Feature 两个概念来管理这个过程:

• Backlog:团队的任务池,记录待开发的功能和 bug
• Feature:正在执行的工作,包含需求文档、上下文配置、代码变更

关键点:它们是一体的。

当你创建一个 Task 时,task.sh create 命令会同时创建 Backlog 条目和 Task 目录,并通过 backlog_ref 字段关联:

# 执行命令
task.sh create "用户认证功能" -a taosu -p P1

# 同时创建:
.trellis/backlog/260119-user-auth.json     # Backlog 条目(任务池)
.trellis/tasks/01-19-user-auth/            # Task 目录(工作区)

Backlog 结构:

{
  "id": "260119-user-auth",
  "title": "用户认证功能",
  "priority": "P1",
  "status": "in_progress",
  "assigned_to": "taosu",
  "created_by": "taosu",
  "created_at": "2026-01-19T10:00:00+08:00"
}

Task 目录结构:

.trellis/tasks/01-19-user-auth/
├── task.json             # Task 元数据(包含 backlog_ref 指向 Backlog)
├── prd.md                # 需求文档
├── implement.jsonl       # Implement Agent 需要的规范
├── check.jsonl           # Check Agent 需要的规范
└── debug.jsonl           # Debug Agent 需要的规范

完整的任务生命周期:

1. 创建任务
   task.sh create → 同时创建 Backlog(status: in_progress) + Task 目录

2. 开发过程
   SessionStart Hook 自动显示你的 Backlog:
   ## BACKLOG (Assigned to me)
   - [P1] 用户认证功能 (2026-01-19)

3. 归档任务
   task.sh archive user-auth →
   - Task 移到 archive/2026-01/
   - Backlog status 自动更新为 done

这样,Backlog 负责"要做什么",Task 负责"怎么做",归档时自动闭环。

6. 专门的 Agent 系统:各司其职

Trellis 定义了 6 种专门的 Agent,每个 Agent 只负责一件事:

| Agent | 职责 | 特点 | | --- | --- | --- | | Plan | 评估需求,规划任务,配置 Feature 上下文 | 可以拒绝不清晰的需求 | | Research | 搜索代码和文档,纯研究不修改 | 纯搜索,不修改任何文件 | | Dispatch | 纯调度器,按阶段调用子 Agent | 不读取规范,只负责调度 | | Implement | 按规范实现功能 | 规范通过 Hook 自动注入 | | Check | 检查代码并自行修复 | 受 Ralph Loop 控制 | | Debug | 深度分析和修复问题 | 不是默认流程,按需调用 |

为什么要分这么多 Agent?

因为不同阶段需要的能力和上下文是不同的:

• Plan 需要理解需求、分析代码库、规划任务,但不需要写代码

• Implement 需要专注实现功能,不需要分心去思考"这个需求合理吗"

• **Check **需要严格检查代码,不需要关心"为什么要这样实现"

每个 Agent 只做一件事,做好一件事。

7. 物理隔离:Git Worktree 解决并行冲突

当多个 Agent 并行开发时,如果都在同一个目录里工作,很容易产生文件冲突。

我们的方案:用 Git Worktree 创建独立的工作目录

your-project/              # 主仓库
../trellis-worktrees/      # Worktree 存储目录
├── feature-user-auth/     # Feature 1 的独立目录
└── feature-payment-fix/   # Feature 2 的独立目录

每个 Worktree 是一个完整的工作目录,有自己的分支、文件、依赖。多个 Agent 在各自的 Worktree 里工作,互不干扰。

工作原理:

1. 用户输入 /parallel,描述需求

2. Plan Agent 分析需求,创建 Feature 目录,配置 jsonl 文件

3. start.sh 脚本创建 Git Worktree,复制环境文件,运行初始化命令

4. Dispatch Agent 在 Worktree 中启动,按阶段调用 Implement -> Check

5. 任务完成后,create-pr.sh 自动创建 Draft PR

这样即使有 10 个 Feature 同时开发,也不会互相冲突。

8. 质量控制:Ralph Loop 强制验证

即使 AI 说"我检查完了,没问题",我们也不能完全相信。

我们的方案:Ralph Loop——一个质量控制循环

当 Check Agent 尝试结束时,ralph-loop.py Hook 会拦截:

Check Agent 尝试停止
        ↓
  是 [finish] 阶段?
   ├─ 是 → 直接允许停止(finish 是最终验证,不需要循环)
   └─ 否 → 进入 Ralph Loop
              ↓
         有 verify 配置?
         ├─ 是 → 执行验证命令(如 pnpm lint, pnpm typecheck)
         │       ├─ 全部通过 → 允许停止
         │       └─ 有失败 → 阻止停止,告知失败原因,继续修复
         └─ 否 → 检查 Agent 输出的完成标记
                 ├─ 标记齐全 → 允许停止
                 └─ 缺少标记 → 阻止停止,告知缺少哪些标记

最多循环 5 次(防止无限循环和成本失控)
状态超时 30 分钟后自动重置(防止状态文件过期)

为什么叫 Ralph Loop?

这个名字来自 Anthropic 的文章,他们提到了一个叫 Ralph 的质量控制机制。我们借用了这个名字。

两种验证方式:

1. 程序化验证(推荐):在 worktree.yaml 配置 verify 命令,Ralph Loop 执行这些命令验证代码。不依赖 AI 输出,由程序强制验证,更可靠。

2. 完成标记验证(回退方案):从 check.jsonl 的 reason 字段生成完成标记。生成规则是 {REASON.toUpperCase().replace(' ', '_')}_FINISH,例如 "TypeCheck" → "TYPECHECK_FINISH","Cross Layer" → "CROSS_LAYER_FINISH"。Check Agent 必须实际执行检查并输出对应标记。

这样即使 AI 想"偷懒",也过不了 Ralph Loop 这一关。

三、实战:一个完整的开发流程

前面讲了一堆设计理念,可能还是有点抽象。下面用两个真实的例子,展示完整的开发流程。

场景 1:简单任务——直接说需求

背景:

我要修复一个前端 bug:用户头像显示不正确。我已经在本地创建了一个 Git 分支 fix/avatar-display。

第 1 步:直接描述需求

打开 Claude Code,直接说需求,不需要任何初始化命令:

我:用户头像在某些情况下显示不正确,需要检查一下 UserAvatar 组件的逻辑。

背后发生的事(用户无感知):

SessionStart Hook 在会话启动时已经自动注入了以下上下文:

1. 当前状态(通过 get-context.sh 获取):

   ## DEVELOPER INFO
   Name: taosu
   Current Branch: fix/avatar-display
   Base Branch: main
      
   ## UNCOMMITTED CHANGES
   M  src/components/UserAvatar.tsx
      
   ## RECENT COMMITS
   - feat: add user profile page (2 hours ago)
      
   ## BACKLOG (Assigned to me)
   - [P1] Fix avatar display bug (2026-01-19)

2. 工作流指南(workflow.md 完整内容)

3. 规范索引(frontend/backend/guides 的 index.md)

4. 会话指令(start.md 的任务分类和 Feature Workflow 定义)

所以 AI 已经知道你是谁、在哪个分支、项目的开发规范是什么。

第 2 步:AI 自动执行 Feature Workflow

AI 做的事:

1. 判断这是一个"开发任务"(涉及逻辑修改),启动 Task Workflow

2. 调用 Research Agent 分析代码库,找出相关规范

3. 创建 Task 目录(task.sh create)

4. 配置上下文(task.sh init-context, task.sh add-context)

5. 写 prd.md 需求文档

6. 激活 Task(task.sh start)——设置 .current-task 让 Hook 能注入上下文

7. 调用 Implement Agent 实现修复(规范通过 Hook 自动注入)

8. 调用 Check Agent 检查代码(规范通过 Hook 自动注入)

AI 的回复:

我分析了一下,发现问题在于:
- UserAvatar 组件在处理 null 值时逻辑有误
- 缺少 fallback 图片

我已经修复了这个问题,并添加了单元测试。
文件改动:
- src/components/UserAvatar.tsx
- src/components/__tests__/UserAvatar.test.tsx

你可以本地运行看看效果。

第 3 步:本地测试

我在本地运行项目,测试各种情况,确认头像显示正常。

第 4 步:提交前检查

我:/finish-work

AI 根据 /finish-work 命令执行检查:

• 代码质量:lint、type-check、test 通过

• 文档同步:规范是否需要更新

• 跨层验证:数据流、错误处理、类型一致性

AI 的回复:

检查完成,所有项目通过:
✓ Lint 通过
✓ Type-check 通过
✓ 测试通过
✓ 无 console.log
✓ 无类型断言

可以提交了。

第 5 步:提交代码

git add .
git commit -m "fix: correct avatar display logic"
git push origin fix/avatar-display

第 6 步:记录流程

我:/record-agent-flow

AI 按照模板指引执行:

1. 总结本次工作内容

2. 将信息追加到 .trellis/workspace/taosu/journal-1.md

3. 更新 index.md

AI 的回复:

已记录本次工作流程。

主要内容:
- 修复了 UserAvatar 组件的 null 值处理逻辑
- 添加了 fallback 图片
- 添加了单元测试
- 已提交到分支 fix/avatar-display

场景 2:复杂功能——用 /parallel

背景:

我要实现一个完整的用户认证功能,包括注册、登录、JWT 验证、邮箱验证。这是一个复杂的跨层功能,涉及前端、后端、数据库。

第 1 步:启动并行流水线

我:/parallel

AI 询问:

请描述你要实现的功能。我会启动 Plan Agent 进行需求分析和任务规划。

第 2 步:描述需求

我:实现用户认证功能:
1. 用户可以通过邮箱注册
2. 注册后发送验证邮件
3. 用户可以登录,返回 JWT token
4. 后端 API 需要 JWT 验证
5. 前端需要登录页面和注册页面

后台发生的事(用户看不到):

注意: /parallel 有两种模式:

• Option A(推荐): 使用 plan.sh 让 Plan Agent 自动分析需求、配置上下文
• Option B: 手动配置 Feature 目录(适合需求已经非常明确的简单功能)

下面展示的是 Option A 的完整流程。

1. plan.sh 脚本在后台启动 Plan Agent

2. Plan Agent 评估需求:

   • 需求是否清晰明确?✓

   • 范围是否合理?✓

   • 是否有足够的上下文?✓

3. Plan Agent 调用 Research Agent 分析代码库:

   • 现有的认证模式

   • 相关的数据库 Schema

   • 前端组件结构

4. Plan Agent 创建 Task 目录:

   .trellis/tasks/01-19-user-auth/
   ├── task.json             # Task 元数据
   ├── prd.md                # 需求文档
   ├── implement.jsonl       # Implement Agent 需要的规范
   ├── check.jsonl           # Check Agent 需要的规范
   └── debug.jsonl           # Debug Agent 需要的规范

5. Plan Agent 写入 prd.md:

   # 用户认证功能
      
   ## 需求概述
   实现完整的用户认证系统,包括注册、登录、JWT 验证、邮箱验证。
      
   ## 技术方案
   - 后端:使用 JWT 进行身份验证
   - 数据库:创建 users 表,存储用户信息和验证状态
   - 邮件服务:使用 SendGrid 发送验证邮件
   - 前端:实现登录页和注册页
      
   ## 实现步骤
   1. 数据库 Migration:创建 users 表
   2. 后端 API:注册、登录、验证接口
   3. 中间件:JWT 验证中间件
   4. 前端页面:登录页、注册页
   5. 前端 Hook:useAuth、useLogin、useRegister

6. Plan Agent 配置 implement.jsonl:

   {"file": ".trellis/spec/backend/index.md", "reason": "后端开发规范"}
   {"file": ".trellis/spec/backend/database-guidelines.md", "reason": "数据库操作规范"}
   {"file": ".trellis/spec/backend/error-handling.md", "reason": "错误处理规范"}
   {"file": ".trellis/spec/frontend/index.md", "reason": "前端开发规范"}
   {"file": ".trellis/spec/frontend/hook-guidelines.md", "reason": "Hook 开发规范"}
   {"file": "src/api/", "type": "directory", "reason": "现有 API 模式参考"}

AI 的回复(Plan 完成后):

需求分析完成。我已经创建了 Feature 目录并规划了实现步骤。

现在启动并行开发流水线...

第 3 步:并行开发流水线自动执行

后台发生的事:

1. start.sh 创建 Git Worktree:

   git worktree add -b feature/user-auth ../trellis-worktrees/feature/user-auth

2. 复制环境文件(根据 worktree.yaml 的 copy 字段):

   cp .env ../trellis-worktrees/feature/user-auth/
   cp .trellis/.developer ../trellis-worktrees/feature/user-auth/.trellis/

3. 运行初始化命令(根据 worktree.yaml 的 post_create 字段):

   cd ../trellis-worktrees/feature/user-auth
   pnpm install --frozen-lockfile

4. 启动 Dispatch Agent(在 Worktree 中)

5. Dispatch Agent 读取 task.json 的 next_action 数组:

   "next_action": [
     {"phase": 1, "action": "implement"},
     {"phase": 2, "action": "check"},
     {"phase": 3, "action": "finish"},
     {"phase": 4, "action": "create-pr"}
   ]

6. Phase 1: Implement

   • Dispatch 调用 Implement Agent

   • Hook inject-subagent-context.py 触发,读取 implement.jsonl,注入规范和代码文件

   • Implement Agent 按规范实现功能:

     • 创建数据库 Migration

     • 实现后端 API(注册、登录、验证)

     • 实现 JWT 中间件

     • 实现前端页面和 Hook

   • Implement Agent 运行 lint 和 typecheck

7. Phase 2: Check

   • Dispatch 调用 Check Agent

   • Hook 注入 check.jsonl 中的规范

   • Check Agent 检查代码:

     • git diff 获取代码变更

     • 对照规范检查每个文件

     • 自动修复发现的问题

   • Ralph Loop 触发:

     • 执行 worktree.yaml 的 verify 命令:

       pnpm lint
       pnpm typecheck

     • 全部通过 → 允许 Check Agent 结束

     • 有失败 → 阻止结束,告知失败原因,继续修复

8. Phase 3: Finish

   • Dispatch 调用 Check Agent(带 [finish] 标记)

   • Hook 注入轻量级的提交前检查清单

   • Check Agent 执行最终验证

9. Phase 4: Create PR

   • create-pr.sh 脚本执行:

     git add -A
     git commit -m "feat(auth): implement user authentication system"
     git push origin feature/user-auth
     gh pr create --draft --base main --title "feat: User Authentication System"

   • 更新 task.json:

     {
       "status": "review",
       "pr_url": "https://github.com/your-org/your-repo/pull/123"
     }

AI 的回复(整个流程完成后):

用户认证功能开发完成!

实现内容:
- 数据库:创建 users 表,包含邮箱、密码哈希、验证状态
- 后端 API:
  - POST /api/auth/register - 用户注册
  - POST /api/auth/login - 用户登录
  - POST /api/auth/verify - 邮箱验证
  - GET /api/auth/me - 获取当前用户
- 中间件:JWT 验证中间件
- 前端页面:登录页(/login)、注册页(/register)
- 前端 Hook:useAuth、useLogin、useRegister

所有检查通过:
✓ Lint 通过
✓ Type-check 通过
✓ 测试通过

已创建 Draft PR:#123
分支:feature/user-auth

第 4 步:人工审核和测试

我切换到 Worktree 目录,本地运行项目:

cd ../trellis-worktrees/feature/user-auth
pnpm dev

测试各种场景:

• 注册新用户

• 邮箱验证

• 登录

• JWT token 验证

• 错误处理

确认功能正常后,在 GitHub 上 review PR,合并到主分支。

第 5 步:清理 Worktree

./.trellis/scripts/multi-agent/cleanup.sh feature/user-auth

或者让 AI 帮忙:

我:/record-agent-flow

AI 会:

1. 记录本次工作流程

2. 询问是否归档 Task

3. 如果归档,执行 task.sh archive user-auth:

   • 将 Task 目录移到 archive/2026-01/

   • 更新关联的 backlog status 为 done

   • 清理 Worktree(如果还存在)

四、踩过的坑与解决方案

问题 1:Slash Command 的学习成本

新人刚开始用这套系统时,需要学习有哪些 Slash Command、每个命令是干什么的。

解决方案:

我们提供了 /onboard-developer 命令来引导新人。新人只需要运行这个命令,AI 就会按照预设的引导流程,介绍整个工作流系统、常用的 Slash Command、以及如何开始第一个任务。

问题 2:AI 在长对话中会"遗忘"规范

即使在会话开始时通过 SessionStart Hook 注入了规范索引,但随着对话轮次增加、上下文变长,AI 可能会逐渐"淡忘"最初读取的开发规范细节。

解决方案:

不依赖 AI "记住"规范,而是在需要的时候自动注入。

这就是为什么我们要用 Hook 机制:

• Implement Agent 启动时,Hook 自动注入 implement.jsonl 中的规范

• Check Agent 启动时,Hook 自动注入 check.jsonl 中的规范

规范不是靠 AI 的"记忆",而是靠代码强制注入,所以不会遗忘。

问题 3:多个 Agent 并行时如何避免冲突

最开始我们尝试让多个 Agent 在同一个目录里工作,结果经常出现文件冲突、依赖版本不一致等问题。

解决方案:

用 Git Worktree 创建物理隔离的工作目录。每个 Agent 在自己的 Worktree 里工作,有自己的分支、文件、依赖,互不干扰。

问题 4:如何保证 AI 真的执行了检查

有时候 AI 会说"我检查完了,没问题",但实际上可能没有真的运行 lint 或 typecheck。

解决方案:

Ralph Loop——一个质量控制循环。

当 Check Agent 尝试结束时,Ralph Loop 会拦截,强制执行 worktree.yaml 中定义的验证命令。只有全部通过,才允许结束。

这样即使 AI 想"偷懒",也过不了 Ralph Loop 这一关。

问题 5:规范文件太多,AI 不知道该读哪个

最开始我们把所有规范都放在一个 doc.md 里,有几千行。AI 要么读不完,要么读完了也不知道重点在哪。

解决方案:

1. 模块化:把规范拆分成细粒度的文件(如 database-guidelines.md、component-guidelines.md)

2. 按需注入:Plan Agent 或 Research Agent 提前分析需求,找出相关规范,写入 jsonl 文件。Hook 在调用 Agent 时只注入需要的规范。

3. Thinking Guides:提供思考清单(如 cross-layer-thinking-guide.md),帮助 AI 在编码前进行全面思考,减少逻辑漏洞。

五、系统架构:文件和目录的作用

前面讲了很多概念,可能还是有点抽象。这里用一张图和一些具体例子,说明 Trellis 的文件结构和各部分的作用。

目录结构

your-project/
├── AGENTS.md                    # 轻量级 AI 指令(兼容 agents.md 协议)
├── .trellis/                    # 工作流和规范中心
│   ├── workflow.md              # 开发流程指南(核心文档,新会话首读)
│   ├── worktree.yaml            # 多 Agent 流水线配置
│   ├── .developer               # 开发者身份(git-ignored)
│   ├── spec/                    # 开发规范(核心知识库)
│   ├── workspace/               # 会话记录和开发者工作区
│   ├── tasks/                   # 任务目录
│   ├── backlog/                 # 需求池
│   └── scripts/                 # 自动化脚本
├── .claude/                     # Claude Code 专用配置
│   ├── commands/                # Slash Commands(13 个)
│   ├── agents/                  # Agent 定义(6 个)
│   ├── hooks/                   # Hook 脚本(3 个)
│   └── settings.json            # Hook 触发配置
└── .cursor/                     # Cursor 专用配置
    └── commands/                # Slash Commands(12 个)

核心文件说明

1. AGENTS.md(约 18 行)

遵循 agents.md 协议的轻量级指令文件。指向 .trellis/workflow.md,SessionStart Hook 会自动注入完整上下文。

2. .trellis/workflow.md(核心文档)

AI Agent 新会话的首读文档。包含:

• Quick Start(开发者身份初始化、上下文获取)

• 开发流程

• 会话记录

• 最佳实践

3. .trellis/spec/(开发规范)

项目的开发规范,是团队的知识资产。AI 在实现和检查代码时会参考这些规范。

spec/
├── backend/
│   ├── index.md                 # 后端规范入口
│   ├── database-guidelines.md   # 数据库规范
│   └── error-handling.md        # 错误处理
├── frontend/
│   ├── index.md                 # 前端规范入口
│   ├── component-guidelines.md  # 组件规范
│   └── hook-guidelines.md       # Hook 规范
└── guides/
    ├── cross-layer-thinking-guide.md  # 跨层开发思考
    └── code-reuse-thinking-guide.md   # 代码复用思考

4. .trellis/workspace/(开发者工作区)

记录所有开发者的工作历史,支持多开发者协作。

workspace/
├── index.md                     # 活跃开发者列表
└── taosu/
    ├── index.md                 # 个人会话索引
    └── journal-1.md             # 会话记录

5. .trellis/tasks/(任务目录)

存放所有正在进行的任务。

tasks/
├── 01-19-user-auth/             # 活跃 Task
│   ├── task.json                # Task 元数据
│   ├── prd.md                   # 需求文档
│   ├── implement.jsonl          # Implement Agent 上下文配置
│   └── check.jsonl              # Check Agent 上下文配置
└── archive/                     # 已归档 Task

6. .trellis/backlog/(任务池,与 Task 联动)

团队共享的任务池。注意:Backlog 和 Task 是一体的——task.sh create 会同时创建 Backlog 条目和 Task 目录,归档 Task 时会自动关闭关联的 Backlog。

backlog/
├── 260119-user-auth.json    # P1 - 用户认证功能
└── 260120-payment-fix.json  # P2 - 支付 bug 修复

SessionStart Hook 会自动显示分配给当前开发者的 Backlog 任务。详见"第 5 节:任务生命周期"。

7. .trellis/scripts/(自动化脚本)

支撑整个工作流运转的脚本。

scripts/
├── get-context.sh               # 获取会话上下文
├── task.sh                      # Task 管理
├── add-session.sh               # 记录会话
└── multi-agent/                 # 多 Agent 流水线脚本
    ├── plan.sh                  # 启动 Plan Agent
    ├── start.sh                 # 创建 Worktree 并启动 Dispatch Agent
    ├── create-pr.sh             # 创建 PR
    └── cleanup.sh               # 清理 Worktree

7. .claude/agents/(Agent 定义)

定义 6 个专门的 Agent,各司其职。

agents/
├── plan.md          # Plan Agent
├── research.md      # Research Agent
├── dispatch.md      # Dispatch Agent
├── implement.md     # Implement Agent
├── check.md         # Check Agent
└── debug.md         # Debug Agent

8. .claude/hooks/(Hook 脚本)

三个 Hook 脚本实现自动化:

• session-start.sh:SessionStart Hook,在会话启动时自动注入工作流、规范索引、当前状态等上下文

• inject-subagent-context.py:PreToolUse Hook,在 Task 调用前自动注入上下文到子 Agent

• ralph-loop.py:SubagentStop Hook,拦截 Check Agent 的结束请求,强制验证

9. .claude/commands/ 和 .cursor/commands/(Slash Commands)

用户通过 Slash Command 与 Trellis 交互。

常用命令:

• /parallel:启动并行流水线(复杂功能)

• /check-frontend / /check-backend:检查代码

• /finish-work:提交前检查

• /record-agent-flow:记录会话

注意: 不再需要 /start 命令,SessionStart Hook 会自动在会话启动时注入上下文。

六、总结和展望

Anthropic 的"AI 长时记忆"理念很有价值,但要真正落地到多人协作的实际项目中,需要解决很多工程问题。

我们在 Trellis 里的实践,核心做了这几件事:

• 多人协作支持:每个开发者有独立的进度文件夹

• 自动化会话初始化:SessionStart Hook 自动注入上下文,用户无需手动初始化

• 规范按需注入:模块化规范 + Hook 自动注入,不依赖 AI "记忆"

• Slash Command 系统:封装最佳实践,提高开发效率

• 任务生命周期管理:Backlog 和 Feature 联动,创建到归档自动闭环

• 专门的 Agent 系统:6 种 Agent 各司其职

• 物理隔离:Git Worktree 解决并行冲突

• 质量控制循环:Ralph Loop 强制验证,确保代码质量

这套系统目前还在不断完善中,但已经能明显感受到开发效率的提升。

接下来可能会做的改进:

• **更智能的规范匹配:**让 AI 根据任务描述自动匹配相关规范,而不需要 Research Agent 手动分析

• 团队知识库:把团队讨论过的设计决策、踩过的坑等,也整理成文档,让 AI 能学习到这些经验

• 更好的可视化:提供 Web UI,可视化展示 Feature 的进度、Agent 的工作状态、代码质量指标等

如果你也在尝试用 AI 辅助开发,希望这篇文章能给你一些启发。欢迎交流。

快速开始

1. 安装

npm install -g @mindfoldhq/trellis@latest

2. 初始化项目

cd your-project
trellis init -u your-name

3. 配置 Worktree(如需使用 /parallel)

编辑 .trellis/worktree.yaml:

# Worktree 存储目录
worktree_dir: ../trellis-worktrees

# 需要复制到 Worktree 的文件
copy:
  - .env
  - .trellis/.developer

# Worktree 创建后的初始化命令
post_create:
  - pnpm install --frozen-lockfile

# Check 阶段必须通过的验证命令(Ralph Loop 使用)
verify:
  - pnpm lint
  - pnpm typecheck

4. 开始使用

Claude Code 工作流:

简单任务(SessionStart Hook 自动注入上下文,无需手动初始化):

直接说需求 → /finish-work → 提交 → /record-agent-flow

复杂功能(多 Agent 流水线):

/parallel → 说需求 → 等待流水线完成 → Review PR

Cursor 工作流:

直接说需求 → /before-frontend-dev 或 /before-backend-dev → 实现 → /check-frontend 或 /check-backend → /finish-work → /record-agent-flow

附:相关资源

• Anthropic 长时运行 Agent 工程实践:Effective Harnesses for Long-Running Agents

• Anthropic Agent 构建研究:Building effective agents

• Trellis GitHub:https://github.com/mindfoldhq/trellis