Trellis 框架介绍

目标读者：全体开发人员、AI 协同编程工具（Cursor / Claude Code 等）使用者
项目地址：GitHub - mindfold-ai/Trellis: The best agent harness. · GitHub

1. 为什么我们需要 Trellis？

在日常开发中，我们广泛使用 Claude Code、Cursor 等 AI 编程助手，但也随之面临以下显著痛点：

1. “会话失忆”（Session Death）：由于上下文窗口限制，每次开启新对话时，AI 就会遗忘之前的进度和项目背景，开发者需要反复重新解释。
2. 规则文件逐渐失控：如果将所有代码规范、架构风格塞进单个 .cursorrules 或 CLAUDE.md 文件，会导致其变得臃肿无比，AI 容易出现“上下文过载”并忽略关键细节。
3. 多任务并行冲突：在同一分支或环境下让 AI 同时处理多个任务时，AI 极其容易相互覆盖代码或造成 Git 分支冲突。

Trellis 是一个高级 AI Agent 工作流与编排框架（Agent Harness）。它的核心理念是：“教 AI 认识你的项目，只需一次”。它通过分层的规范体系、任务上下文隔离以及工作区持久记忆，为所有 AI 工具提供了一个统一的“外接大脑”。

2. 核心概念

要熟练使用 Trellis，我们必须准确理解它定义的几个核心名词，它们与传统开发工具中的概念有本质区别。

2.1 Spec（规范/规约）

定义：在 Trellis 中，Spec（存放在 .trellis/spec/）指的是**“写给 AI 助手的项目规约与上下文记忆”**。它是一系列 Markdown 文件，涵盖了我们团队的编码标准、文件结构规则、错误处理风格以及 Code Review 习惯

作用机制 (按需注入、渐进式披露)：当你让 AI 开发新功能时，Trellis 不会把所有文件丢给 AI，而是像“人类开发前回忆规范”一样，将当前任务强相关的 Spec 提取出来，在 AI 开始写代码前精准注入到 Prompt 中

动态演进：它不是静态的。在一次需求开发完毕后，Trellis 会有专门的复盘流程去检查本次编码是否产生了新的最佳实践，并自动更新 Spec 文档(claude code专属，其他工具需要手动触发)，真正做到让 AI“越用越顺手”

2.2 Task（任务）与生命周期状态

在 Trellis 中，Task是一个具有物理目录、独立记忆和层级关系的开发容器（存放在 .trellis/tasks/ 下），由包含元数据的 task.json 和相关需求文档组成

它支持父子任务拆解（Subtasks / Parent-Children 树），并且在 Trellis 的底层设计中拥有严密的生命周期状态 (States)。熟悉这些状态有助于你利用 Trellis 的自动化钩子 (Hooks) 联动其他工具

• Created (已创建)
  • 含义：你刚刚通过指令创建了任务及其子任务，但尚未开始编写代码。
  • 行为：生成 task.json，可触发 after_create 钩子。
• Started / In Progress (进行中)
  • 含义：AI 被唤醒并投入该任务，配合 Git Worktrees 与 Work Journals (日志) 进行连续不断的编码与调试。
  • 行为：系统会持续追踪任务进度，并可触发 after_start 钩子。此时该任务上下文被标记为活跃 (Active)。
• Finished (已完成)
  • 含义：功能开发和 AI 自测结束。
  • 行为：触发 Code Review 和 after_finish 钩子。Trellis 会引导 AI 对照 Spec 中的标准检查代码，确保没有引入不符合团队规范的代码异味（Vibe coding 的通病）。
• Archived (已归档)
  • 含义：工作彻底结束或需要封存。你通过 /record-session 等配套指令让 AI 记录最终的成果总结，并结束会话。
  • 行为：任务被移出当前的高优先记忆区，防止污染未来新任务的上下文，并触发 after_archive 钩子。

2.3 json/jsonl配置文件

描述task信息的元数据结构

task.json Schema

{ "id": "02-27-user-login", "name": "user-login", "title": "添加用户登录", "description": "实现 JWT 登录流程", "status": "in_progress", "dev_type": "backend", "scope": "auth", "priority": "P1", "creator": "alice", "assignee": "alice", "createdAt": "2026-02-27T10:00:00Z", "completedAt": null, "branch": "feature/user-login", "base_branch": "main", "worktree_path": null, "current_phase": 1, "next_action": [ { "phase": 1, "action": "implement" }, { "phase": 2, "action": "check" }, { "phase": 3, "action": "finish" }, { "phase": 4, "action": "create-pr" } ], "commit": null, "pr_url": null, "subtasks": [], "relatedFiles": [], "notes": "" }

JSONL（JSON Lines）文件定义了每个 Agent 需要读取哪些文件。每行是一个 JSON 对象：

字段说明：

三种 JSONL 文件：

implement.jsonl

{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"} {"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"} {"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"} {"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"} {"file": ".trellis/spec/backend/quality.md", "reason": "Code quality requirements"}

check.jsonl

{"file": ".claude/commands/trellis/finish-work.md", "reason": "Finish work checklist"} {"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"} {"file": ".claude/commands/trellis/check-backend.md", "reason": "Backend check spec"}

3. 核心架构与目录解析

Trellis 的核心结构集中在项目根目录的 .trellis/ 文件夹中。它取代了传统的单体规则文件，将 AI 的认知环境科学地拆分为三个维度：

• .trellis/spec/ (规范层)
  用于存放 Markdown 格式的编码标准、目录结构规则、评审习惯等。Trellis 的机制是按需加载，它只会向 AI 注入与当前任务相关的规范，而不是一次性塞入所有内容。
• .trellis/tasks/ (任务层)
  存放结构化的 PRD（产品需求）、实现上下文以及任务当前状态。这能确保 AI 的产出始终紧扣业务目标，不偏离任务轨道。
• .trellis/workspace/ (记忆与工作区)
  这是解决“会话失忆”的核心。这里存放工作日志 (Journals)。它会记录上一次会话执行了什么、发现了什么 bug、下一步要做什么。每次新会话开始时，AI 会先读取工作区日志，无缝接续上次的思考逻辑。

目录结构全貌

your-project/ ├── .trellis/ # Trellis 核心目录 │ ├── .developer # 开发者身份 (gitignored) │ ├── .current-task # 当前活跃任务指针 │ ├── .version # Trellis 版本号 │ ├── .template-hashes.json # 模板文件哈希 (用于 update) │ ├── workflow.md # 开发工作流指南 │ ├── worktree.yaml # Multi-Agent worktree 配置 │ │ │ ├── spec/ # 项目规范库 │ │ ├── frontend/ # 前端规范 │ │ │ ├── index.md # 规范索引 │ │ │ ├── component-guidelines.md │ │ │ ├── hook-guidelines.md │ │ │ ├── state-management.md │ │ │ ├── type-safety.md │ │ │ ├── quality-guidelines.md │ │ │ └── directory-structure.md │ │ ├── backend/ # 后端规范 │ │ │ ├── index.md │ │ │ ├── database-guidelines.md │ │ │ ├── error-handling.md │ │ │ ├── logging-guidelines.md │ │ │ ├── quality-guidelines.md │ │ │ └── directory-structure.md │ │ └── guides/ # 思维指南 │ │ ├── index.md │ │ ├── cross-layer-thinking-guide.md │ │ └── code-reuse-thinking-guide.md │ │ │ ├── workspace/ # 开发者工作区 │ │ ├── index.md # 工作区总索引 │ │ └── {developer-name}/ # 每人独立目录 │ │ ├── index.md # 个人索引 │ │ └── journal-N.md # 会话日志 │ │ │ ├── tasks/ # 任务目录 │ │ ├── {MM-DD-task-name}/ # 活跃任务 │ │ │ ├── task.json # 任务元数据 │ │ │ ├── prd.md # 需求文档 │ │ │ ├── info.md # 技术设计 (可选) │ │ │ ├── implement.jsonl # Implement Agent 上下文 │ │ │ ├── check.jsonl # Check Agent 上下文 │ │ │ └── debug.jsonl # Debug Agent 上下文 │ │ └── archive/ # 已归档任务 │ │ └── {YYYY-MM}/ │ │ │ └── scripts/ # 自动化脚本 │ ├── task.py # 任务管理 (14 个子命令) │ ├── get-context.py # 获取会话上下文 │ ├── get-developer.py # 获取开发者身份 │ ├── init-developer.py # 初始化开发者 │ ├── add-session.py # 记录会话 │ ├── common/ # 公共库 │ │ ├── paths.py │ │ ├── developer.py │ │ ├── git-context.py │ │ ├── task-utils.py │ │ ├── task-queue.py │ │ ├── phase.py │ │ ├── registry.py │ │ └── worktree.py │ └── multi-agent/ # 并行开发脚本 │ ├── plan.py │ ├── start.py │ ├── status.py │ ├── create-pr.py │ └── cleanup.py │ ├── .claude/ # Claude Code 配置 │ ├── settings.json # Hook 和权限配置 │ ├── commands/ # Slash 命令 │ │ └── trellis/ # Trellis 命令集 │ │ ├── start.md │ │ ├── parallel.md │ │ ├── record-session.md │ │ ├── finish-work.md │ │ ├── onboard.md │ │ ├── before-backend-dev.md │ │ ├── before-frontend-dev.md │ │ ├── check-backend.md │ │ ├── check-frontend.md │ │ ├── check-cross-layer.md │ │ ├── break-loop.md │ │ ├── create-command.md │ │ └── integrate-skill.md │ ├── agents/ # Agent 定义 │ │ ├── dispatch.md │ │ ├── plan.md │ │ ├── implement.md │ │ ├── check.md │ │ ├── debug.md │ │ └── research.md │ ├── hooks/ # Hook 脚本 │ │ ├── session-start.py │ │ ├── inject-subagent-context.py │ │ └── ralph-loop.py │ └── skills/ # Skill 目录 │ ├── .cursor/ # Cursor 配置 │ └── commands/ │ └── trellis-*.md # Cursor 版命令集 │ ├── AGENTS.md # Codex 入口文件 ├── .agents/ # Agent Skills (Codex / OpenCode) │ └── skills/ │ ├── .kilocode/ # Kilo Code 配置 │ ├── rules/ # 项目规则（所有模式通用） │ ├── workflows/ # Workflow 命令 │ └── skills/ # Agent Skills │ └── .kiro/ # Kiro 配置 ├── steering/ # 项目上下文（Steering 系统） ├── hooks/ # Agent Hooks（事件驱动自动化） ├── prompts/ # 自定义提示词 └── specs/ # Spec-Driven Development 文档

4. 团队接入与配置指南

4.1 编写规范 (Specs)

最佳实践：不要人工从零手写所有规范文件！ 在初始化Trellis后，会自带一个初始任务：00-bootstrap-guidelines，专门用来初始化规范，所以更高效的做法是：利用 AI 读取现有的优质代码模块，让 AI 自动起草规范草案，然后再由资深开发人员使用 /update-spec 命令微调最核心的架构规则（如数据库约定、组件复用逻辑等），保存至 .trellis/spec/。

4.2 规范沉淀即资产

如果某个团队成员在开发中摸索出了一套绝佳的工作流，或解决了一个容易让 AI 踩坑的顽疾，只需将这段经验写入 Spec 文件并提交到代码库。团队中其他人的 AI 助手拉取代码后，就能立刻“学会”这个新技能。

可以使用/break-loop命令触发Bug分析流程，AI会深度分析这个Bug出现的原因，最后更新到spec约束中，防止下次再犯。

4.3 多开发者协作

为了更好的多人协作，.trellis文件夹需要纳入git管理

不冲突的部分（各人独立）：

• workspace/{name}/ — 每人独立目录
• .developer — gitignored，每人独立
• 并行任务的 worktree — 物理隔离

可能冲突的部分（需要协调）：

• spec/ — 多人可能同时修改同一规范
• tasks/ — 多人可能操作同一任务

最佳实践：

• Spec 修改通过 PR 审查
• 重要的 spec 变更在团队会议上讨论

5. 工作流程

以实际场景为例讲清楚如何使用Trellis：

项目背景

我们的 MES 系统采用典型的前后端分离架构（如 Spring Boot + Vue 3）。现在需要新增一个功能：工单质检录入。要求 AI 助手协助完成从数据库表设计到前端页面的全过程。

Spec 0：初始化Trellis（仅初始化一次即可）

初始化命令根据你使用的平台选择：

• Claude Code：trellis init -u your-name

• Cursor：trellis init -u your-name

• Codex：trellis init --codex -u your-name

• OpenCode：trellis init --opencode -u your-name

• Kilo：trellis init --kilo -u your-name

• Kiro：trellis init --kiro -u your-name

your-name 会成为你的开发者身份标识，并创建个人工作区 .trellis/workspace/your-name/。

Spec1：设定“项目规范”

在开发开始前，.trellis/spec/ 中已经沉淀了 MES 系统的核心开发规范。这让 AI 懂得如何写出符合项目规范的代码。

• spec/mes-db-conventions.md：规定所有 MES 表必须包含 tenant_id（多租户）、created_by、update_time 字段。
• spec/mes-api-style.md：规定 API 必须返回统一的 Result<T> 封装格式，错误码需参考 MES-ERR-XXX 标准，支持多语言等。
• spec/mes-ui-patterns.md：规定使用 Element Plus 组件库，表格必须支持流式响应式布局。

效果：当你对 AI 说“帮我写个接口”时，你不必每次都重复“记得带上租户 ID 和统一返回体”，Trellis 会自动将这些 Spec 注入 AI 的上下文。

Spec2：拆解并启动任务

现在我们要正式做功能了。

Prompt示例

现在需要改动xxx功能，需求是这样的：xxxx，这是相关的文件 @文件1 @文件2 创建trellis任务，同时补充jsonl配置文件，视情况拆分为subtasks

Trellis 动作：

• 自动创建 .trellis/tasks/任务名/task.json、.trellis/tasks/任务名/prd.md、.trellis/tasks/任务名/check.jsonl、.trellis/tasks/任务名debug.jsonl、.trellis/tasks/任务名/implement.jsonl。

如果需求不明确，可以使用/brainstorm命令进行头脑风暴

Spec3：遵循规范的编码

在任务细节确定好后，可以新开一个会话，执行/start进行初始化，选择要执行的命令

Prompt示例：

现在开始执行xxx任务

AI在写代码之前，会调用skill获取对应的spec，然后才开始写代码。写完代码后，会再次调用工具验证代码是否符合规范。

能否在正确的时机调用skill取决于你使用的模型，如果模型不够智能，可以在开始写前端/后端代码之前，手动运行 /before-frontend-dev 或 /before-backend-dev，指示 AI 读取 .trellis/spec/ 下的代码规范。

Spec4：代码检查

在代码完成开发后，使用 /check-frontend 与 /check-backend 检查写的代码是否符合 .trellis/spec 下的代码规范

使用比较聪明的模型时，他们在写代码时就会执行自检

Spec5：会话中断与持久化

场景：你写完 Service 层代码后，由于当前窗口上下文达到上限，或者你今天下班了，必须关闭当前对话窗口。

用户 Prompt（断开前）：

“我要结束当前会话了。请使用 Trellis 记录当前进度到 Journal。 记录重点：Service 层逻辑已写完，但 validate() 方法中关于‘工单状态检查’的逻辑还没通过单元测试，明天需要先修这个。”

Trellis 动作：

• 在 .trellis/workspace/journals/ 下生成一份带时间戳的日志。

Spec6：恢复上下文

场景：第二天，你开启了一个全新的空白对话窗口。

用户 Prompt（开始时）：

“加载任务 feat-quality-inspection。读一下昨天的 Journal，告诉我接下来该做什么。”

AI会读取之前的记忆和任务进度，继续执行。