# Trellis 深度解析：原理、实现与使用

> 对照 Harness Engineering 教程体系与 claude-project-templates 手工模板的全面技术文档

---

## 目录

1. [Trellis 是什么](#1-trellis-是什么)
2. [核心原理：五大设计原则](#2-核心原理五大设计原则)
3. [架构全景：四大子系统](#3-架构全景四大子系统)
4. [工作流状态机：从理论到实现](#4-工作流状态机从理论到实现)
5. [Spec 注入系统：Context Engineering 的实践](#5-spec-注入系统context-engineering-的实践)
6. [任务系统：全生命周期管理](#6-任务系统全生命周期管理)
7. [跨会话连续性：Session Resolution 机制](#7-跨会话连续性session-resolution-机制)
8. [Sub-agent 协作：多 Agent 分工模型](#8-sub-agent-协作多-agent-分工模型)
9. [与教程体系的对应关系](#9-与教程体系的对应关系)
10. [与 claude-project-templates 的对应关系](#10-与-claude-project-templates-的对应关系)
11. [三者融合：最佳实践建议](#11-三者融合最佳实践建议)

---

## 1. Trellis 是什么

Trellis 是一个**开发工作流自动化引擎**（v0.5.0），安装在项目的 `.trellis/` 目录中。它解决的核心问题是：

> **AI 编码助手在长周期、多会话、多窗口的复杂项目中如何保持一致性和高质量？**

用一句话概括它的做法：

**通过一个有限状态机（workflow state machine）驱动开发流程，通过 JSONL 文件动态注入编码规范到 sub-agent，通过 session pointer 实现跨会话的自动恢复。**

### 在 Harness Engineering 分类中的位置

教程（insight #34）把 AI 编码系统分为三层：

```
Framework (框架层) → 提供 API 和抽象
Runtime (运行时)  → 执行和调度
Harness (治具层)  → 连接、保护、编排
```

**Trellis 是一个纯 Harness 层工具**——它本身不写代码（那是 sub-agent 的事），它负责：
- 告诉 AI **该做什么**（workflow breadcrumb）
- 给 AI **看什么规范**（spec injection）
- 记录 AI **做了什么**（workspace journal）
- 确保 AI **恢复上下文**（session resolution）

对应教程 insight #1 的核心洞见：*"Agent 质量的决定性因素不是模型能力，而是 harness 设计质量。"*

---

## 2. 核心原理：五大设计原则

Trellis 在 `workflow.md` 开头声明了五个 Core Principles：

### 2.1 Plan before code（先计划再编码）

**原理**：强制在 Phase 1 完成需求收集和 PRD 编写，才允许进入实现阶段。状态机通过 `task.py start` 命令做硬性分割——如果直接跳过 planning 进入 in_progress，breadcrumb 不会注入 brainstorm 引导。

**对应教程**：
- insight #4 (Spec-Driven Development): "规范才是主要产物，代码是规范的派生物"
- 文章 #24 (Kiro, spec-kit, Tessl): SDD 工具链的三层规范

**对应 Templates**：
- Templates 通过 CLAUDE.md 的"启动循环"做弱约束（文字指引，非强制）
- feature_list.json 预定义功能列表代替了 PRD 的角色

### 2.2 Specs injected, not remembered（规范注入，非记忆依赖）

**原理**：AI 的 context window 是有限资源。Trellis 不期望 AI "记住"项目规范，而是在每次任务执行时，通过 JSONL 文件精确选择需要的规范文件，由平台 hook 注入到 sub-agent 的 prompt 中。

**实现方式**：
```
implement.jsonl 列出 spec 文件路径
    ↓ (platform hook 读取)
hook 读取文件内容
    ↓ (注入到 sub-agent prompt)
sub-agent 带着最新 spec 开始编码
```

**对应教程**：
- insight #2 (Context Engineering): "每个 token 有 n² 计算成本"、"最小高信号 token 集合"
- 文章 #10 (Manus): context window 的稀缺资源管理
- 文章 #13 (Backpressure): 当 context 满时如何压缩

**对应 Templates**：
- Templates 把所有规范写死在 CLAUDE.md 里（400+ token），不管做什么任务都全量加载
- 没有动态选择机制，小任务也承受全量 context 成本

### 2.3 Persist everything（一切持久化）

**原理**：对话会被压缩（context condensation），但文件不会消失。所有决策、研究、教训都必须写入文件。

**体现**：
- 需求 → `prd.md`
- 研究 → `{task_dir}/research/*.md`
- 规范 → `.trellis/spec/`
- 会话记录 → `workspace/{developer}/journal-N.md`
- 任务元数据 → `task.json`

**对应教程**：
- 文章 #02 (Effective Harnesses for Long-Running Agents): 长时运行 agent 的外部化记忆
- 文章 #14 (OpenHands Context Condensation): 对话压缩后信息保留策略

**对应 Templates**：
- `claude-progress.md` = 会话日志
- `feature_list.json` = 功能状态
- `session-handoff.md` = 交接记录
- 理念完全一致，只是 Trellis 更系统化

### 2.4 Incremental development（增量开发，一次一件事）

**原理**：同时只有一个 active task。状态机强制执行：`task.py create` 后 session pointer 锁定到该任务，直到 `archive` 清除。

**对应教程**：
- 文章 #25 (12 Factor Agents): "Small, focused tools"
- insight #4: SDD 的增量交付模式

**对应 Templates**：
- "WIP=1" 规则：CLAUDE.md 明确写"一次只做一个功能"
- feature_list.json 的 `in_progress` 状态最多一个

### 2.5 Capture learnings（捕获知识）

**原理**：每完成一个任务，`trellis-update-spec` skill 强制审视"这次学到了什么"，并回写到 `.trellis/spec/`。形成闭环：spec → implement → 发现新知 → update spec → 下次 implement 更好。

**对应教程**：
- 文章 #32 (LangChain: Improving Deep Agents with Harness Engineering): 迭代改进
- insight #5: 评估驱动的持续优化循环

**对应 Templates**：
- **这是 Templates 唯一缺失的关键机制**。Templates 没有显式的"学习回写"步骤。

---

## 3. 架构全景：四大子系统

```
┌──────────────────────────────────────────────────────────┐
│                     .trellis/                             │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐    │
│  │  Workflow    │  │    Spec     │  │    Task      │    │
│  │  State      │  │   System    │  │   System     │    │
│  │  Machine    │  │             │  │              │    │
│  │             │  │ spec/       │  │ tasks/       │    │
│  │ workflow.md │  │ ├─frontend/ │  │ ├─task.json  │    │
│  │ (breadcrumb │  │ ├─backend/  │  │ ├─prd.md     │    │
│  │  source)    │  │ └─guides/   │  │ ├─*.jsonl    │    │
│  │             │  │             │  │ └─research/  │    │
│  └──────┬──────┘  └──────┬──────┘  └──────┬───────┘    │
│         │                 │                 │            │
│         ├─────────────────┼─────────────────┤            │
│         │                 │                 │            │
│  ┌──────▼──────────────────▼─────────────────▼───────┐   │
│  │              Session Resolution                    │   │
│  │                                                    │   │
│  │  .runtime/sessions/{context_key}.json             │   │
│  │  ├─ current_task → 哪个任务活跃                    │   │
│  │  ├─ platform → 哪个平台                           │   │
│  │  └─ last_seen_at → 最后活跃时间                    │   │
│  └────────────────────────────────────────────────────┘   │
│                                                          │
│  ┌────────────────────────────────────────────────────┐   │
│  │              Workspace System                      │   │
│  │                                                    │   │
│  │  workspace/{developer}/                           │   │
│  │  ├─ index.md     (个人仪表盘)                      │   │
│  │  └─ journal-N.md (会话日志)                        │   │
│  └────────────────────────────────────────────────────┘   │
│                                                          │
└──────────────────────────────────────────────────────────┘
```

---

## 4. 工作流状态机：从理论到实现

### 4.1 状态转换图

```
                    ┌──────────────┐
                    │   no_task    │ ← 初始状态
                    └──────┬───────┘
                           │ task.py create
                           ▼
                    ┌──────────────┐
                    │   planning   │ ← Phase 1
                    └──────┬───────┘
                           │ task.py start
                           ▼
                    ┌──────────────┐
                    │ in_progress  │ ← Phase 2 + Phase 3
                    └──────┬───────┘
                           │ task.py archive
                           ▼
                    ┌──────────────┐
                    │  completed   │ ← 立即归档 (目前不可达)
                    └──────────────┘
```

### 4.2 Breadcrumb 机制：如何"告诉 AI 现在该做什么"

这是 Trellis 最核心的实现技巧。它的工作流程：

1. **平台 Hook 触发**（每次用户发消息时）
2. Hook 调用 `task.py current --source` 获取当前活跃任务
3. 从 `task.json` 读取 `status` 字段
4. 从 `workflow.md` 中解析对应的 `[workflow-state:STATUS]` 块
5. 将该块的文本**注入到 AI 的 system prompt 中**

例如，当 status = `planning` 时，AI 收到的 breadcrumb 是：

```
Load the `trellis-brainstorm` skill and iterate on prd.md with the user.
Phase 1.3 (required, once): before `task.py start`, you MUST curate 
`implement.jsonl` and `check.jsonl`...
Then run `task.py start <task-dir>` to flip status to in_progress.
```

**这意味着 AI 在每一个 turn 都收到明确的指令，告诉它现在处于什么阶段、下一步该做什么。**

### 4.3 与教程的对应

| 教程概念 | Trellis 实现 |
|----------|-------------|
| Harness = "连接、保护、编排" (insight #1) | breadcrumb 编排每一步 |
| "约束越明确，可授予的自主权越大" (insight #3) | 状态机限定了每阶段可做的事 |
| "Context Engineering = 找最小高信号 token" (insight #2) | 每状态只注入该阶段需要的指令 |
| "12 Factor: Own your control flow" (#25) | workflow.md 是唯一 source of truth |

### 4.4 与 Templates 的对应

Templates 没有状态机。它用 **CLAUDE.md 的"启动循环"** 做软引导：

```
1. pwd → 2. 读 progress → 3. 读 feature_list → 4. git log → 5. init.sh → 6. 基线验证
```

这是一个**线性检查清单**，不是状态机。区别：
- Templates：AI 读到清单后自行决定跳到哪一步（可能跳过）
- Trellis：状态决定了 AI 收到什么指令（不可能跳过，因为看不到其他状态的指令）

---

## 5. Spec 注入系统：Context Engineering 的实践

### 5.1 Spec 目录结构

```
.trellis/spec/
├── frontend/              # 前端层规范
│   ├── index.md           # 入口：Pre-Dev Checklist + Quality Check
│   ├── component-guidelines.md
│   ├── hook-guidelines.md
│   ├── state-management.md
│   ├── quality-guidelines.md
│   └── type-safety.md
│
├── backend/               # 后端层规范
│   ├── index.md
│   ├── database-guidelines.md
│   ├── error-handling.md
│   └── logging-guidelines.md
│
└── guides/                # 跨层思维导引
    ├── index.md
    ├── code-reuse-thinking-guide.md
    └── cross-layer-thinking-guide.md
```

### 5.2 JSONL Curation：精确选择上下文

每个任务有两个 JSONL 文件：

**implement.jsonl**（给编码 agent 看）：
```jsonl
{"file": ".trellis/spec/frontend/index.md", "reason": "Component patterns needed"}
{"file": ".trellis/spec/guides/code-reuse-thinking-guide.md", "reason": "Avoid duplication"}
{"file": ".trellis/tasks/05-06-add-login/research/auth-comparison.md", "reason": "Library choice"}
```

**check.jsonl**（给审查 agent 看）：
```jsonl
{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Lint rules to verify"}
{"file": ".trellis/spec/guides/cross-layer-thinking-guide.md", "reason": "API boundary check"}
```

### 5.3 这解决了什么问题

**问题**：CLAUDE.md 把所有规范堆在一起，不管做什么任务都全量加载。

**解法**：JSONL curation 让每个任务只加载相关的 2-5 个 spec 文件，而非全部 15+ 个。

**数学**：
- Templates (CLAUDE.md 全量): ~400 行 → 每次都消耗
- Trellis (JSONL 精选): 2-5 个文件 × ~100 行 = 200-500 行，但只加载相关的

按教程 insight #2 的说法：**"找到最小的高信号 token 集合来最大化期望输出的概率。"**

### 5.4 Thinking Guides：不只是规范，更是思维模型

Trellis 的 `spec/guides/` 不是"怎么写代码"的规范，而是"写代码前怎么思考"的导引：

1. **Code Reuse Thinking Guide**：
   - "写新代码前先搜索是否已存在"
   - "复制粘贴是不一致 bug 的 #1 来源"
   - 提供具体的搜索命令模板

2. **Cross-Layer Thinking Guide**：
   - "大多数 bug 发生在层级边界，而非层内"
   - 要求在跨层功能前画数据流图
   - 提供边界检查清单

这对应教程文章 #21 (Anchoring AI to a Reference Application): **用具体的参考模式锚定 AI 的行为，而非抽象的"最佳实践"。**

---

## 6. 任务系统：全生命周期管理

### 6.1 任务目录结构

```
.trellis/tasks/05-06-add-login/
├── task.json           # 元数据 (status, branch, assignee, etc.)
├── prd.md              # 需求文档 (brainstorm 阶段产物)
├── implement.jsonl     # 编码 agent 需要的 spec 引用
├── check.jsonl         # 审查 agent 需要的 spec 引用
├── research/           # 研究产物
│   ├── auth-library.md
│   └── session-strategy.md
└── info.md             # 技术设计 (可选)
```

### 6.2 task.json Schema

```json
{
  "id": "05-06-add-login",
  "title": "Add Login Feature",
  "status": "in_progress",        // planning | in_progress | completed
  "dev_type": "feature",          // feature | bugfix | refactor | docs
  "scope": "authentication",      // PR title scope
  "package": "frontend",          // monorepo package
  "priority": "P1",
  "creator": "lili",
  "assignee": "lili",
  "createdAt": "2026-05-06",
  "branch": "task/add-login",
  "base_branch": "main",
  "pr_url": null,
  "subtasks": [],
  "parent": null,
  "relatedFiles": [],
  "notes": ""
}
```

### 6.3 CLI 命令速查

```bash
# 创建（进入 planning）
python3 .trellis/scripts/task.py create "Add login feature" --slug add-login

# 激活（进入 in_progress）
python3 .trellis/scripts/task.py start add-login

# 查看当前
python3 .trellis/scripts/task.py current --source

# 添加 spec 上下文
python3 .trellis/scripts/task.py add-context add-login implement \
    ".trellis/spec/frontend/index.md" "Component guidelines"

# 完成（清除 session pointer）
python3 .trellis/scripts/task.py finish

# 归档（移动到 archive/）
python3 .trellis/scripts/task.py archive add-login

# 列出所有活跃任务
python3 .trellis/scripts/task.py list

# 创建 PR
python3 .trellis/scripts/task.py create-pr --dry-run
```

### 6.4 与 Templates 的 feature_list.json 对比

| 维度 | Trellis task.json | Templates feature_list.json |
|------|-------------------|-----------------------------|
| 粒度 | 一个任务一个目录（含 PRD、研究、spec 引用） | 一个 JSON 数组的一个元素 |
| 状态模型 | planning → in_progress → completed | not_started → in_progress → passing |
| 附属信息 | prd.md, research/, info.md | 只有 validation_command 和 evidence |
| Git 集成 | branch, base_branch, create-pr | 无 |
| 多任务管理 | list, archive, subtask hierarchy | 平铺列表 |
| 自动化 | session pointer 自动跟踪 | 手动更新状态 |

**Templates 是轻量级的——适合"我已经知道要做什么，只是需要追踪进度"。Trellis 是重量级的——适合"我还不清楚要做什么，需要从需求到代码的完整管道"。**

---

## 7. 跨会话连续性：Session Resolution 机制

### 7.1 核心问题

> 你在 Cursor 窗口 A 做任务 X，Claude Code 窗口 B 做任务 Y。  
> 下次打开窗口 A 时，AI 怎么知道应该继续任务 X 而不是 Y？

### 7.2 解决方案：Per-Session Context Key

Trellis 为每个 AI 会话窗口分配一个稳定的 **context key**（会话标识符），并在 `.trellis/.runtime/sessions/{context_key}.json` 中存储该会话的 active task pointer。

```json
// .trellis/.runtime/sessions/claude_abc123.json
{
  "current_task": ".trellis/tasks/05-06-add-login",
  "platform": "claude",
  "last_seen_at": "2026-05-06T14:32:00Z"
}
```

### 7.3 Context Key 解析优先级

`active_task.py` 按以下顺序尝试获取 context key：

1. `TRELLIS_CONTEXT_ID` 环境变量（显式覆盖）
2. Hook input 中的 session_id / conversation_id / transcript_path
3. 平台原生环境变量：
   - Claude: `CLAUDE_SESSION_ID`, `CLAUDE_CODE_SESSION_ID`
   - Cursor: `CURSOR_SESSION_ID`
   - Codex: `CODEX_SESSION_ID`, `CODEX_THREAD_ID`
   - OpenCode: `OPENCODE_SESSION_ID`
   - Gemini: `GEMINI_SESSION_ID`
   - ... (支持 11+ 平台)
4. Cursor shell ticket（短期票据，TTL 30s，桥接 Cursor 的 shell 命令）
5. Fallback：如果只有一个 session 文件，使用它

### 7.4 与 Templates 的 session-handoff.md 对比

| | Trellis | Templates |
|---|---|---|
| **恢复方式** | 自动（hook 读取 session pointer） | 手动（AI 读 session-handoff.md） |
| **多窗口** | 每窗口独立 pointer | 不支持 |
| **信息丰富度** | task.json + prd.md + research/ | handoff.md 的文本摘要 |
| **可靠性** | 确定性（文件存在就有） | 依赖 AI 是否遵循"启动循环" |

### 7.5 对应教程

- 文章 #02 (Anthropic: Effective Harnesses for Long-Running Agents): 外部化状态存储
- 文章 #03 (Anthropic: Harness Design for Long-Running App Dev): 多会话上下文恢复
- insight #2: "conversations get compacted; files don't" 的工程实现

---

## 8. Sub-agent 协作：多 Agent 分工模型

### 8.1 三种 Sub-agent

| Agent | 职责 | 接收的 Context |
|-------|------|---------------|
| **trellis-implement** | 写代码 | prd.md + implement.jsonl 引用的 spec |
| **trellis-check** | 审查 + 修复 | check.jsonl 引用的 spec + 当前 diff |
| **trellis-research** | 调研 | 研究问题描述 |

### 8.2 为什么要分离 implement 和 check

**教程根据**：
- 文章 #20 (Assessing Internal Quality While Coding with an Agent): "自己验自己"的可靠性低
- insight #3: 约束即自由——check agent 只关注质量，不需要理解实现细节

**实际效果**：
- implement agent 带着编码规范写代码 → 聚焦于"如何正确实现"
- check agent 带着质量规范审查代码 → 聚焦于"是否符合标准"
- 两者的 context 不同（implement.jsonl ≠ check.jsonl），形成独立视角

**vs Templates**：Templates 用单 agent 做所有事。这等于让一个人既写代码又写测试——人类工程实践早已证明独立审查的价值。

### 8.3 Sub-agent Dispatch 协议

对于 Claude Code 等 Class-1 平台：

```
主 agent: "Dispatch trellis-implement sub-agent"
    ↓
平台 hook 自动:
    1. 读取 implement.jsonl
    2. 读取每行引用的 spec 文件
    3. 读取 prd.md
    4. 组装成 sub-agent 的初始 prompt
    ↓
trellis-implement sub-agent:
    带着完整 context 开始编码
```

对于 Codex 等 Class-2 平台（无 hook 注入能力）：

```
主 agent dispatch prompt 必须包含:
    "Active task: .trellis/tasks/05-06-add-login"
    ↓
sub-agent 自行:
    1. task.py current --source
    2. 读取 prd.md 和 implement.jsonl
    3. 手动 cat 每个 spec 文件
    4. 开始编码
```

### 8.4 对应教程

- insight #6 (Multi-Agent Architecture): "多 agent 并行化可压缩 90% 研究时间"
- 文章 #35 (Anthropic Multi-Agent Research): orchestrator-worker 架构
- 文章 #36 (Claude Agent SDK): sub-agent 的设计模式

---

## 9. 与教程体系的对应关系

### 9.1 教程 → Trellis 知识转化表

| 教程文章/洞见 | Trellis 的具体实现 |
|--------------|-------------------|
| **Insight #1**: Harness > Model (52.8→66.5%) | 整个 Trellis 就是"通过 harness 优化提升质量" |
| **Insight #2**: Context 是稀缺资源 (n² 成本) | JSONL curation 精选 spec，不全量加载 |
| **Insight #3**: 约束即自由 | workflow 状态机限定每步可做的事 |
| **Insight #4**: Spec-Driven Development | prd.md + spec/ = 可执行的规范 |
| **Insight #5**: 评估驱动迭代 | trellis-check sub-agent = 自动评估循环 |
| **Insight #6**: 多 Agent 架构 | implement/check/research 三种 sub-agent |
| **#02** Long-Running Agents | session resolution + workspace journal |
| **#03** Harness Design for Long-Running | 四阶段 workflow + 跨会话状态 |
| **#06** Building Effective Agents | skill routing table (brainstorm/implement/check) |
| **#10** Manus Context Engineering | JSONL 的"选择性注入"=精确 context 管理 |
| **#13** Backpressure | journal 自动 rotate (2000 行上限) |
| **#15** Writing a Good CLAUDE.md | workflow.md 的 breadcrumb = 动态版 CLAUDE.md |
| **#20** Quality with Agents | check agent 独立于 implement agent |
| **#21** Anchoring to Reference | spec/guides/ = 锚定 AI 的参考模式 |
| **#22** Humans and Agents in Loops | brainstorm 阶段的 HiL 交互 |
| **#24** SDD Tools | task = spec + prd + context = SDD 实践 |
| **#25** 12 Factor Agents | "Own your control flow" = workflow.md |
| **#32** Improving with Harness | trellis-update-spec = harness 持续改进 |

### 9.2 教程中 Trellis 尚未覆盖的概念

| 教程概念 | 状态 |
|----------|------|
| 沙箱安全 (insight #3, 文章 #16) | 不在 Trellis 范围（由平台提供） |
| 提示注入缓解 (#19) | 不涉及（Trellis 不处理外部输入） |
| Eval 基础设施 (#27-#33) | 只有 trellis-check，没有系统化 eval suite |
| 基础设施噪声量化 (#30) | 不涉及 |
| Token 经济学 (15× overhead) | 没有显式的 token 成本追踪 |

---

## 10. 与 claude-project-templates 的对应关系

### 10.1 文件级对应表

| Templates 文件 | Trellis 等效 | 差异 |
|---------------|-------------|------|
| `CLAUDE.md` (启动循环 + 规范) | `workflow.md` breadcrumb + `spec/` | Trellis 动态注入 vs Templates 静态全量 |
| `feature_list.json` | `task.json` + `tasks/` 目录 | Trellis 更丰富（PRD、research、spec 引用） |
| `claude-progress.md` | `workspace/{dev}/journal-N.md` | Trellis 自动 rotate，Templates 无限增长 |
| `session-handoff.md` | Session pointer (自动) | Trellis 无需手动写交接 |
| `init.sh` | 无等效 | Templates 有项目初始化，Trellis 假设项目已存在 |
| `docs/ARCHITECTURE.md` | `.trellis/spec/` | Trellis 按层/包组织，Templates 单文件 |
| `clean-state-checklist.md` | Phase 3.4 commit 流程 | Trellis 自动化提交流程 |
| `quality-document.md` | **无等效** | Templates 独有：量化质量评分 |
| `evaluator-rubric.md` | **无等效** | Templates 独有：六维评分卡 |
| `.claude/hooks.json` (pre-commit) | workflow breadcrumb (软约束) | Templates 硬约束（物理阻断）vs Trellis 软约束 |
| `.claude/commands/check.md` | `trellis-check` skill/sub-agent | 类似但 Trellis 的 check agent 有 spec 注入 |
| `.claude/commands/handoff.md` | `/trellis:finish-work` skill | 功能等价 |
| `scripts/check-architecture.sh` | `spec/guides/cross-layer-thinking-guide.md` | Templates 硬约束 vs Trellis 思维引导 |

### 10.2 工作流步骤对应

| Templates 工作流步骤 | Trellis Phase |
|---------------------|---------------|
| 1. pwd 确认目录 | （自动，hook 处理） |
| 2. 读 progress | Phase 1.0 自动恢复 active task |
| 3. 读 feature_list | Phase 1.1 读 prd.md |
| 4. git log | Phase 3.4 commit 前学习风格 |
| 5. init.sh | （无等效） |
| 6. 基线验证 | Phase 2.2 trellis-check |
| 选择功能 | task.py create |
| TDD 写测试 | （由 implement agent 遵循 spec） |
| 实现逻辑 | Phase 2.1 trellis-implement |
| 验证通过 | Phase 2.2 + 3.1 trellis-check |
| 记录证据 | prd.md 验收标准 + task.json |
| 更新 progress | workspace/journal 自动记录 |
| HiL 检查 (>20行) | Phase 1.1 brainstorm 交互 |
| 会话结束清理 | Phase 3.5 + /finish-work |

### 10.3 Templates 的独有优势（Trellis 可以借鉴）

1. **Pre-commit 物理阻断**
   ```json
   // .claude/hooks.json
   {"event": "pre-commit", "command": "python -m pytest --tb=short -q"}
   ```
   测试不过 → 提交被物理阻止。Trellis 只有"建议"，没有阻断。

2. **Quality Document（质量仪表盘）**
   按域/层评分（A/B/C/D），让人一眼看出哪里需要关注。Trellis 没有等效视图。

3. **Evaluator Rubric（六维评分卡）**
   正确性 / 验证 / 范围纪律 / 可靠性 / 可维护性 / 交接准备度。可以作为 trellis-check 的评分标准。

4. **渐进复杂度**
   core (4 files) → standard (9 files) → full (13+ files)。Trellis 没有"轻量模式"。

5. **HiL 协议的颗粒度**
   ">20行代码必须自我解释 + 风险评估 + 验证计划"——比 Trellis 的 brainstorm 阶段更细粒度。

---

## 11. 三者融合：最佳实践建议

### 11.1 定位分工

```
教程知识库 → 你脑子里的框架（为什么这样做）
Templates  → 初始化蓝图（新项目 Day 0 的文件骨架）
Trellis    → 运行时引擎（日常开发的自动化流程）
```

### 11.2 推荐的融合实践

#### A. 把 Templates 的硬约束加入 Trellis 生态

```bash
# 在 .claude/hooks.json 中加入 pre-commit 硬约束
# 这样即使 trellis-check 没发现问题，commit 时还有第二道防线
```

#### B. 把 Templates 的质量仪表盘纳入 Spec

在 `.trellis/spec/` 中创建 `quality-dashboard.md`，由 `trellis-update-spec` 在每次任务完成后更新评分。

#### C. 把 Templates 的 Evaluator Rubric 给 trellis-check 用

将 evaluator-rubric.md 的六维评分标准加入 `check.jsonl`，让 check agent 不仅检查"代码对不对"，还评估"工作质量如何"。

#### D. 把 Templates 的 HiL 协议写入 Spec

在 `.trellis/spec/guides/` 创建 `human-in-the-loop-guide.md`：
- >20 行代码必须自我解释
- 修改核心逻辑必须风险评估
- 验证计划必须包含具体命令

#### E. 保持教程知识库作为设计决策的参考

当需要修改 Trellis 配置或 Spec 时，回到教程找理论依据：
- 想优化 context 使用 → 重读 insight #2
- 想调整 agent 自主权 → 重读 insight #3
- 想改进评估 → 重读 insight #5

### 11.3 按场景选择

| 场景 | 推荐方案 |
|------|---------|
| 小脚本 (< 500 行) | Templates core 就够 |
| 中型项目 (单人) | Trellis + Templates 的 pre-commit hook |
| 大型项目 (多窗口/多人) | Trellis 全套 |
| 学习/理解 harness 设计 | 先读教程，再看 Trellis 如何实现 |
| 需要质量可视化 | Trellis + Templates 的 quality-document |
| 需要严格验收 | Trellis + Templates 的 evaluator-rubric |

---

## 总结

**Trellis 本质上是教程知识库中所有理论原则的工程化实现：**

- "Context 是稀缺资源" → JSONL curation
- "Harness > Model" → workflow state machine  
- "约束即自由" → breadcrumb 限定行为空间
- "Spec-Driven" → prd.md + spec/ + thinking guides
- "多 Agent 分工" → implement/check/research sub-agents
- "持久化一切" → task dir + workspace journal
- "跨会话连续" → session resolution mechanism

**而 claude-project-templates 是同样理论的另一种实现路径**——更轻量、更直接、更适合小项目，但缺少动态注入、学习闭环和多窗口支持。

三者的最佳用法：**教程指导设计决策，Templates 提供硬约束补充，Trellis 驱动日常开发流程。**