Trellis AI 编程实战指南

AI 的能力像藤蔓一样生长——充满活力但四处蔓延。Trellis 提供结构，引导它沿着规范的路径前进。

为什么你的 AI 助手总是写出不符合规范的代码？

如果你正在使用 Claude Code、Cursor 或其他 AI 编程工具，大概率遇到过这些问题：

痛点一：代码质量不稳定

今天 AI 写的代码完美遵循了你的项目规范，明天却又回到了"野生状态"。你告诉它"我们用 Zustand，不用 Redux"，它可能记住了——但下次新会话又开始用 Redux。

痛点二：AI 容易"遗忘"规范

你精心编写的 CLAUDE.md、 .cursorrules、 AGENTS.md 看似有效，但在对话中段，AI 开始忘记这些规范。规范文件越长，AI 越容易"选择性失忆"。

痛点三：多人协作混乱

团队里每个人和 AI 的交互方式都不同，写出的代码风格迥异。A 同学的 AI 用了一套命名规范，B 同学的 AI 用了另一套。最终代码库变成了"百家争鸣"。

核心答案：因为规范只存在于"记忆"中，而非每次"注入"

这就是 Trellis 要解决的问题。

一、Trellis 是什么

Trellis 是 Claude Code 和 Cursor 的一站式 AI 开发框架，核心目标是让 AI 在每次对话中都能获得正确的上下文。

核心价值

快速开始

# 1. 全局安装
npm install -g @mindfoldhq/trellis@latest
# 2. 在项目目录初始化
trellis init -u your-name
# 3. 启动 Claude Code，开始干活

二、设计理念："注入而非记忆"

为什么"记忆"不可靠？

传统的 AI 编程工具依赖于 AI 的"记忆"——你告诉它规范，希望它一直记住。但这会导致上下文腐烂（Context Rot）：

• 分心（Distraction）：无关信息干扰决策
• 混淆（Confusion）：信息相互矛盾
• 冲突（Clash）：新旧指令打架

"注入"的优势

Trellis 采用声明式设计，像 Kubernetes 一样工作：

传统方式：
用户→告诉 AI 规范→ AI 记住→执行→可能忘记
Trellis方式：
规范存储在文件→Hook自动注入→ AI 带着完整上下文执行

核心哲学：不依赖 AI 的记忆，而是通过代码保证每次都注入正确的上下文。

用 K8s 的方式理解

如果你熟悉 Kubernetes，可以这样类比：

两者的共同点：

• 用户只声明"要什么"，不操心"怎么做"
• 系统持续调谐，直到实际状态符合期望
• 出现偏差时自动修复

三、Hook 自动注入系统

Hook 是 Trellis 的核心机制，它在关键时刻自动注入上下文，确保 AI 总是在正确的语境中工作。

三个 Hook 各司其职

1. session-start.py：会话启动注入

触发时机：每次 Claude Code 会话启动时

注入内容：

# 1. 当前状态（动态）
print("<current-state>")
# 执行 get-context.sh 获取：开发者身份、Git 状态、当前任务、任务队列
print("</current-state>")
# 2. 工作流指南
print("<workflow>")
# 注入 .trellis/workflow.md
print("</workflow>")
# 3. 规范索引
print("<guidelines>")
# 注入 frontend/index.md, backend/index.md, guides/index.md
print("</guidelines>")
# 4. 会话指令
print("<instructions>")
# 注入 start.md 命令内容
print("</instructions>")

设计要点：

• 多 Agent 脚本会设置 CLAUDE_NON_INTERACTIVE=1，跳过注入避免重复
• 只注入索引文件，不注入全部规范，防止上下文过载

2. inject-subagent-context.py：子 Agent 上下文注入

触发时机： PreToolUse - 在 Task 工具调用前

核心设计：

# Dispatch 只发送简单命令
# Hook 负责注入所有上下文
# 子 Agent 带着完整信息自主工作
# 1. 读取 .trellis/.current-task 定位任务目录
task_dir = get_current_task(repo_root)
# 2. 根据 Agent 类型读取对应的 JSONL 文件
if subagent_type =="implement":
    context = get_implement_context(repo_root, task_dir)
# 注入 implement.jsonl + prd.md + info.md
elif subagent_type =="check":
    context = get_check_context(repo_root, task_dir)
# 注入 check.jsonl + prd.md
# 3. 构建完整的 prompt
new_prompt = build_prompt(original_prompt, context)

各 Agent 注入内容对比：

3. JSONL 文件格式

JSONL 文件定义了每个 Agent 需要读取的文件：

{"file":".trellis/spec/backend/index.md","reason":"后端开发规范"}
{"file":"src/api/auth.ts","reason":"现有认证模式参考"}
{"file":"src/middleware/","type":"directory","reason":"中间件模式参考"}

追溯价值：

• 记录了每个任务用了哪些规范
• 出问题时可以追溯是否缺少必要的规范引用
• 规范本身是否不够清晰

四、多 Agent 协作架构

Trellis 定义了 6 个专业 Agent，各司其职：

Agent 职责详解

Dispatch 的设计哲学

Dispatch Agent 是纯调度器，它只负责调用子 Agent，不读取任何规范：

# Dispatch Agent 只做这些事：
1.读取.trellis/.current-task 定位任务目录
2.读取 task.json 的 next_action 数组
3.按阶段顺序调用子Agent
4.处理超时和失败
# Hook 负责注入所有上下文
# 行为由代码控制，而非 prompt

这种设计的好处：

• 调度逻辑简单明确，不会出错
• 上下文注入由代码保证，不依赖 AI 的"记忆"
• 每个 Agent 专注于自己的任务

五、Ralph Loop 质量控制

Ralph Loop 是 Trellis 的质量门禁，它拦截 Check Agent 的停止请求，确保代码真正通过了验证。

工作原理

两种验证模式

模式 1：程序化验证（推荐）

在 worktree.yaml 配置 verify 命令：

verify:
- pnpm lint
- pnpm typecheck

Ralph Loop 执行这些命令，全部通过才放行。这种方式：

• 不依赖 AI 输出，由程序强制验证
• 更可靠，lint 通过就是通过

模式 2：完成标记验证（回退方案）

从 check.jsonl 的 reason 字段生成完成标记：

{"file":"...","reason":"TypeCheck"}→ TYPECHECK_FINISH
{"file":"...","reason":"Lint"}→ LINT_FINISH

Check Agent 必须实际执行检查并输出对应标记。Ralph Loop 检查所有标记是否都在 Agent 输出中。

阻止消息示例

当验证失败时，Ralph Loop 会返回清晰的提示：

Iteration2/5.Missing completion markers: LINT_FINISH, TYPECHECK_FINISH.
IMPORTANT:You must ACTUALLY run the checks,not just output the markers.
-Did you run lint?What was the output?
-Did you run typecheck?What was the output?
-Did they actually passwith zero errors?
Only output a marker (e.g., LINT_FINISH) AFTER:
1.You have executed the corresponding command
2.The command completed with zero errors
3.You have shown the command output in your response

安全机制

• 最大迭代次数：5 次，防止无限循环和成本失控
• 超时重置：30 分钟超时自动重置状态
• 跳过 finish 阶段：finish 阶段已经在 check 阶段验证过，无需再次验证

六、会话持久化

Trellis 通过 Journal 系统记录工作历史，让 AI 能够跨会话记住项目上下文。

Journal 系统

.trellis/workspace/{developer}/
├── index.md           # 个人会话索引（自动更新）
├── journal-1.md# 会话记录（最多 2000 行）
├── journal-2.md# 自动创建新文件
└──.agents/
└── registry.json  # 运行中的 Agent 注册表

会话记录格式

## Session N: 实现用户认证功能
**Date**:2026-01-29
**Task**: user-auth
### Summary
实现了基于 JWT 的用户认证系统...
### Main Changes
- src/api/auth.ts:新增登录接口
- src/middleware/auth.ts:认证中间件
### Git Commits
- feat(auth): add JWT authentication
- fix(auth): handle token expiration
### Testing
-单元测试通过
-手动测试登录流程
### Status
已完成
### Next Steps
-添加刷新 token 机制

Session ID 机制

用于恢复中断的会话：

# 1. Agent 启动时生成 UUID
echo "a1b2c3d4-e5f6-7890-abcd-ef1234567890">.session-id
# 2. 注册到 registry.json
{
"agents":[{
"id":"user-auth",
"worktree_path":"/path/to/worktree",
"pid":12345,
"started_at":"2026-01-29T10:00:00+00:00",
"task_dir":".trellis/tasks/01-29-user-auth"
}]
}
# 3. 恢复会话
claude --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890

七、实战工作流

/trellis:start 流程

/trellis:parallel 多 Agent 流水线

完整的并行开发流程：

用户:/trellis:parallel
用户:实现用户注册功能，包括邮箱验证
↓
┌─────────────────────────────────────────┐
│Plan阶段（主仓库）│
├─────────────────────────────────────────┤
│1. plan.sh 启动PlanAgent│
│2.PlanAgent评估需求│
│3.调用ResearchAgent分析代码库│
│4.创建任务目录：│
│- task.json（元数据）│
│- prd.md（需求文档）│
│- implement.jsonl / check.jsonl       │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│Worktree创建│
├─────────────────────────────────────────┤
│1. start.sh 创建GitWorktree│
│2.复制环境文件（worktree.yaml 的 copy）│
│3.运行初始化命令（post_create）│
│4.启动DispatchAgent│
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│Implement→Check→Finish→Create-PR  │
├─────────────────────────────────────────┤
│Hook自动注入上下文│
│RalphLoop控制Check质量│
│最终创建Draft PR                        │
└─────────────────────────────────────────┘
↓
用户:/trellis:record-session（记录会话）

/trellis:record-session 会话记录

# 1. 获取当前上下文
./get-context.sh
# 2. 记录会话
./add-session.sh --title "实现用户认证"--commit "abc123"
# 3. 自动追加到 journal-N.md
# 4. 自动更新 index.md
# 5. 如果任务完成，归档到 archive/

八、并行开发 - Worktree 隔离

Git Worktree 架构

每个任务在独立的 Git Worktree 中工作，物理隔离：

project/# 主仓库
├──.trellis/
│└── tasks/
│└──01-29-user-auth/# 任务目录
│
../trellis-worktrees/# Worktree 目录
├── feature/user-auth/# 任务 A 的 Worktree
├── feature/payment/# 任务 B 的 Worktree
└── feature/dashboard/# 任务 C 的 Worktree

worktree.yaml 配置

# Worktree 存储目录（相对于项目根目录）
worktree_dir:../trellis-worktrees
# 需要复制到 Worktree 的文件
copy:
-.env
-.trellis/.developer
# Worktree 创建后运行的初始化命令
post_create:
- pnpm install --frozen-lockfile
# Check Agent 结束前必须通过的验证命令
verify:
- pnpm lint
- pnpm typecheck

Agent Registry

追踪运行中的 Agent：

{
"agents":[
{
"id":"user-auth",
"worktree_path":"/path/to/worktree/feature/user-auth",
"pid":12345,
"started_at":"2026-01-29T10:00:00+00:00",
"task_dir":".trellis/tasks/01-29-user-auth"
}
]
}

查看状态：

# 查看所有任务状态
./status.sh
# 查看详细信息
./status.sh --detail
# 监控模式
./status.sh --watch

九、最佳实践 - Spec 库配置

目录结构

.trellis/spec/
├── backend/# 后端开发规范
│├── index.md             # 后端规范入口
│├── directory-structure.md
│├── database-guidelines.md
│├── error-handling.md
│├── quality-guidelines.md
│└── logging-guidelines.md
├── frontend/# 前端开发规范
│├── index.md             # 前端规范入口
│├── component-guidelines.md
│├── hook-guidelines.md
│├── state-management.md
│└── type-safety.md
└── guides/# 思考指南
├── index.md
├── cross-layer-thinking-guide.md
└── code-reuse-thinking-guide.md

规范文件模板

一个好的规范文件应该包含：

# 组件设计规范
## 概述
简要描述这个规范的目的和适用范围。
## 规则
### 1. 命名规范
-组件使用PascalCase
-文件名使用 kebab-case
### 2. 结构规范
-Props接口定义在组件文件顶部
-使用函数式组件+Hooks
## 代码示例

tsx // 正确示例 interface ButtonProps { label: string; onClick: () => void; }

export const Button = ({ label, onClick }: ButtonProps) => { return{label}; };

## 常见错误
### 错误 1：使用 any 类型

tsx // ❌ 错误 const Button = (props: any) => { ... }

// ✅ 正确 const Button = (props: ButtonProps) => { ... }

## DO / DON'T
| DO | DON'T |
|----|-------|
| 使用 TypeScript Props 接口 | 使用 any 类型 |
| 函数式组件 | class 组件 |

Thinking Guides

Thinking Guides 帮助发现"没想到的问题"——大多数 bug 来自思考不周全，而非技能不足。

触发时机：

核心理念：30 分钟的思考可以节省 3 小时的调试。

规范沉淀循环

AI 按规范执行→发现问题→更新.trellis/spec/→下次执行更好→规范越用越好

用 /trellis:break-loop 命令可以进行深度 bug 分析，跳出"修复 bug → 忘记 → 后续又写出同样 bug"的循环，并将经验记录到 Thinking Guides 中。

十、总结

Trellis 的核心设计思想可以总结为：

声明式而非命令式

传统方式：一步步指挥 AI 干活
Trellis：声明期望状态，系统自动调谐

注入而非记忆

传统方式：告诉 AI 规范，希望它记住
Trellis：Hook自动注入，代码保证

程序化质量控制

传统方式："请检查代码质量"→ AI 说"检查过了"
Trellis：RalphLoop执行 lint →通过才放行

物理隔离并行

传统方式：多任务在同一目录，互相干扰
Trellis：GitWorktree隔离，物理分离

附录：命令速览

更多资源

• 完整技术文档
• 用 K8s 理解 Trellis
• 上下文开销分析
• GitHub 仓库
• Discord 社区