每日一个开源项目（第145篇）：Trellis - 把项目记忆、规范和任务上下文持久化进代码仓库

引言

"AI 编码 10% 是写代码，90% 是重新解释你的技术栈。Trellis 解决了 AI Agent 最糟糕的问题：失忆。"

这是"每日一个开源项目"系列的第145篇文章 。今天的主角是 Trellis------一个把项目规范、任务上下文和会话记忆持久化进代码仓库的 AI 编程 Harness 框架。

你用 Claude Code 开发一个项目，把规范讲清楚、上下文建立好、调出好的结果。关掉终端。第二天打开，重新开始：重新解释技术选型，重新说明代码风格，重新描述当前任务的背景......

这个问题有个名字：Agent 失忆症。每次会话都是新开始，之前所有建立起来的上下文全部消失。

Trellis 的解法是把该记住的东西存进仓库：.trellis/spec/ 存规范，.trellis/tasks/ 存任务和 PRD，.trellis/workspace/ 存会话日志。Agent 启动时自动读取，不需要每次重新解释。

你将学到什么

.trellis/ 三目录系统的设计逻辑：spec / tasks / workspace 各司其职
4 阶段工作流：Plan → Implement → Verify → Finish 的完整闭环
Trellis Skill：四个内置工作流模块的具体作用
与 CLAUDE.md / AGENTS.md 的对比：为什么单文件方案会变成单体文件
团队场景：spec 提交到 Git 后如何让整个团队受益
支持的 16 个平台和初始化方式

前置知识

使用过 Claude Code、Cursor 或类似 AI 编程工具
熟悉基本的 Git 工作流
了解 CLAUDE.md 或 .cursorrules 的基本概念

项目背景

项目简介

Trellis 是一个 AI 编程 Agent Harness 框架，定位是"AI 的脚手架，引导它沿着你的规范路径工作"。

"Harness"（驭套）这个词在 2026 年的 AI 编码语境里越来越重要------不是 Agent 本身，而是围绕 Agent 的约束、记忆和工作流结构。Trellis 是这个领域里最系统的开源实现之一，有学术论文引用（OpenReview 上的"Agent Harness Engineering: A Survey"）。

核心设计决策：把所有持久化信息存进 Git 仓库。规范可以被 Code Review，会话记忆可以被团队共享，任务上下文可以跨工具使用。这不只是文件路径的选择，而是把 AI 工作方式纳入工程管理体系的设计取向。

作者/团队介绍

组织 : Mindfold AI（mindfold-ai）
文档 : docs.trytrellis.app
License: AGPL-3.0
技术栈: TypeScript 67.9% / Python 25.8%

项目数据

⭐ GitHub Stars: 11,300+
🍴 Forks: 641+
💻 支持平台: 16 个 AI 编程平台
📄 License: AGPL-3.0

主要功能

三目录系统

Trellis 在仓库根目录下维护一个 .trellis/ 目录，三个子目录各有职责：

arduino 复制代码

.trellis/
├── spec/           ← 项目规范（提交进 Git）
│   ├── coding-standards.md
│   ├── architecture.md
│   ├── tech-stack.md
│   └── team-conventions.md
│
├── tasks/          ← 任务和 PRD（提交进 Git）
│   ├── active/
│   │   └── feature-auth/
│   │       ├── prd.md
│   │       ├── implementation-context.md
│   │       └── review-context.md
│   └── completed/
│
└── workspace/      ← 会话日志（可选择 .gitignore）
    └── your-name/
        └── journal.md

spec/：这是核心。所有你不想每次都对 Agent 重复解释的内容：技术栈选型的理由、代码风格规定、架构约束、命名约定、已知的坑。这些文件提交进 Git，被 Trellis 在每次会话开始时自动注入到 Agent 的上下文里。

tasks/：任务不只是一行描述，而是完整的工作单元：PRD（需求文档）、实现上下文（Agent 开始编码前需要知道的一切）、审查上下文（检查代码改动时需要对照的内容）。

workspace/：每个开发者的会话日志。记录了"这次会话做了什么，遇到了什么问题，下次继续时需要知道什么"。Agent 在新会话启动时读取这个文件，知道上次在哪里停下。

4 阶段工作流

Trellis 定义了一个完整的工作循环：

复制代码

Plan → Implement → Verify → Finish
  ↑                                ↓
  └──────── spec 更新 ←────────────┘

阶段一：Plan（trellis-brainstorm）

不是直接开始写代码，而是先把需求想清楚：

bash 复制代码

启动 trellis-brainstorm
    ↓
Agent 逐问题引导你澄清需求：
  "这个功能的成功标准是什么？"
  "有没有需要遵守的技术约束？"
  "哪些边界情况需要处理？"
    ↓
生成 prd.md（产品需求文档）
复杂的调研子任务 → 分配给子 Agent
    ↓
PRD 存入 .trellis/tasks/active/[task-name]/

阶段二：Implement（trellis-implement）

执行时自动注入上下文：

bash 复制代码

启动 trellis-implement
    ↓
自动读取：
  - .trellis/spec/ 里的相关规范
  - .trellis/tasks/active/[task-name]/prd.md
  - .trellis/workspace/[your-name]/journal.md
    ↓
按 PRD 编写代码，遵守 spec 约束

阶段三：Verify（trellis-check）

代码写完后的自动审查：

markdown 复制代码

启动 trellis-check
    ↓
对比 spec：改动是否符合规范？
运行 lint、类型检查、测试
发现问题 → 尝试自动修复
修复失败的问题 → 汇报给开发者

阶段四：Finish（trellis-update-spec）

这是闭环里最有价值的部分：

bash 复制代码

启动 trellis-update-spec
    ↓
分析本次任务中发现的新模式、新约定、新规则
把这些学习结果提升进 .trellis/spec/
    ↓
下一次会话从这里出发，比这次更智能

与 CLAUDE.md / AGENTS.md 的对比

objectivec 复制代码

CLAUDE.md / .cursorrules 的问题：
  单一文件 → 随时间增长变成"什么都有"的大杂烩
  全量注入 → 不管任务是什么，所有内容都进上下文
  无任务结构 → 没有 PRD，没有实现/审查上下文的分离
  无持久记忆 → 会话结束，一切归零

Trellis 的做法：
  模块化 spec → 按任务相关性按需注入
  任务上下文 → PRD + 实现上下文 + 审查上下文分层管理
  workspace 记忆 → 跨会话的连续性
  Finish 阶段 → 每次任务结束 spec 自动更新

Trellis 不是要替换 CLAUDE.md，而是围绕它建立更系统的结构。你仍然可以有 CLAUDE.md，Trellis 的 spec 文件补充它。

项目详细剖析

安装和初始化

bash 复制代码

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

# 基本初始化（自动检测安装了哪些 AI 工具）
trellis init -u your-name

# 指定平台初始化
trellis init --claude-code --cursor --codex -u your-name

trellis init 会：

创建 .trellis/ 目录结构
根据检测到的平台生成对应的配置文件
创建初始 spec 模板（可以让 AI 基于现有代码分析生成）
在 .gitignore 里根据偏好处理 workspace 目录

初始 spec 生成（现有项目）：

arduino 复制代码

在 Claude Code 里：
"分析这个项目的代码，为它生成 .trellis/spec/ 的初始内容，
 包括技术栈说明、代码风格、架构约束"

然后人工审查和精炼生成的 spec 文件

平台支持

Trellis 支持 16 个 AI 编程平台，生成平台特定的配置文件：

已确认支持的：Claude Code、Cursor、OpenCode、Codex、GitHub Copilot、Devin 等

对于 Claude Code，Trellis 生成 CLAUDE.md 的 Trellis 结构化版本和相应的 Skill 文件，让 Claude Code 知道在什么时候使用 trellis-brainstorm、trellis-implement 等工作流。

Trellis Skill 系统

4 个内置 Skill 定义了工作流的入口：

Skill	触发时机	核心行为
`trellis-brainstorm`	开始新任务时	引导需求澄清，输出 PRD
`trellis-implement`	开始编码时	注入上下文，执行实现
`trellis-check`	代码完成后	对照规范审查，自动修复
`trellis-update-spec`	任务完成后	提升新学习结果进规范

这些 Skill 遵循 agentskills.io 开放标准，和 android/skills 等项目使用同一套格式。

团队使用场景

spec 文件提交到 Git 后，整个团队受益于同一套规范：

bash 复制代码

场景：新团队成员加入
传统方式：文档在 Confluence，可能过时；问老人；踩坑
Trellis 方式：
  git clone 后 → .trellis/spec/ 里有完整的技术栈说明和约定
  AI Agent 自动遵守这些规范
  加入者一天内就能用上团队标准的 AI 辅助工作流

sql 复制代码

场景：团队新发现一个最佳实践
传统方式：口头传递，或者更新某个可能没人读的文档
Trellis 方式：
  某个人跑完 trellis-update-spec 后 spec 文件更新
  提交 PR，团队 review
  合并后，所有人的后续 AI 会话都自动使用新规范

workspace journal 格式

会话日志让 Agent 知道上次在哪里停下：

markdown 复制代码

# Journal - your-name

## 2026-06-28
### 会话摘要
- 完成了 auth 模块的 JWT 验证逻辑
- 发现 refresh token 在并发请求下有竞态条件
- 暂时用 Redis 加分布式锁解决，但觉得应该有更好的方案

### 下次继续时需要知道的
- refresh token 竞态问题的修复方案需要进一步评估
- 需要写 auth 模块的集成测试
- Edge case: 同一用户多设备同时 refresh token

### 悬而未决的问题
- 要不要引入 rotating refresh token？需要确认产品需求

下次会话时，Agent 读到这个 journal，知道背景，不需要重新解释。

快速开始

bash 复制代码

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

# 进入你的项目目录
cd your-project

# 初始化（自动检测 Claude Code 等工具）
trellis init -u your-name

# 开始第一个任务
# 在 Claude Code 里说：
# "用 trellis-brainstorm 开始一个新任务：为用户认证模块添加 MFA 支持"

项目地址与资源

🌟 GitHub : mindfold-ai/Trellis
📖 文档 : docs.trytrellis.app
🏢 Mindfold AI : github.com/mindfold-ai

总结

Trellis 解决的是 AI 编程工具链里一个系统性的问题：每次会话都从零开始，AI 不知道这个项目的上下文、这个团队的约定、上次任务的进展。

把规范、任务上下文和会话记忆存进 Git 仓库是一个设计决策，不只是实现细节。这意味着 AI 的工作方式被纳入了工程管理体系：规范可以被审查，记忆可以被共享，改动可以被追踪。

4 阶段工作流的闭环设计（尤其是 Finish 阶段把学习结果回写进规范）让系统随着使用积累变得更好，而不是每次都从同样的起点出发。

11.3k Stars 说明这个方向有真实需求。对于在多个项目或多个工具之间切换的开发者，或者团队里希望统一 AI 辅助开发标准的 Tech Lead，Trellis 值得认真评估。

探索 PrimeSkills ------ 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。