Grill与Trellis工作流衔接实战指南

背景

随着 AI 编程助手（如 Claude、Gemini、Gork）能力的提升，开发者面临的挑战从“如何写代码”转变为“如何管理复杂的开发流程”。传统的 Prompt 工程往往缺乏上下文持久化和任务状态管理，导致 AI 在长周期项目中容易遗忘决策或陷入混乱。

本文分享了一种结合 Trellis（任务管理与状态追踪框架）与 Grill（需求澄清与决策记录工具）的工作流。该工作流旨在将“人脑的架构决策”与“AI 的长上下文执行能力”解耦。通过标准化的流程，开发者只需像 Technical Lead 一样进行技术选型和需求确认，而将具体的代码实现、测试和归档工作交给 AI 自动执行，从而提升开发效率并确保代码质量的可追溯性。

核心内容

该工作流的核心在于通过两个阶段的协作，将模糊的需求转化为可执行、可验证的原子化任务。整体流程分为环境初始化、需求澄清、任务移交与执行四个主要步骤。

1. 环境初始化与规范建立

在开始编码前，必须建立标准化的项目结构和决策记录机制。

• 安装与初始化：
  • 全局安装 @mindfoldhq/trellis。
  • 在项目根目录执行 trellis init，生成 .trellis 文件夹，其中包含 specs、tasks、workspace 等核心目录。
• 安装 Skills：
  • 安装 grill-doc-me 技能，将其放入 .claude/skills/ 目录下，用于辅助需求澄清。
• 引导规范（Bootstrap）：
  • 初始化后立即运行 00-bootstrap-guidelines 任务。
  • 此步骤旨在完善项目的 spec 规范，记录已做出的真实架构决策，避免 AI 进行推测性架构设计。
  • 完成规范后，结合 Grill-with-Docs 进一步讨论技术栈和产品需求。

2. 需求澄清（使用 Grill）

此阶段的目标是通过交互式问答，消除需求中的模糊点，形成明确的领域共识。

• 交互模式：开发者向 AI 提出模糊需求（例如：“写一个 FastAPI 后端，接收病人 ID，查 MySQL 并清洗数据”）。
• AI 主动提问：AI 会针对技术细节（如同步/异步、错误处理策略、边界条件）提出选择题或判断题。
• 决策记录：开发者的回答将被记录，直到所有边界条件、异常处理和核心逻辑达成一致。
• 产出物：生成 CONTEXT.md（定义领域术语）和 docs/adr/ 目录下的架构决策记录（ADR），作为后续任务执行的“真理来源”。

3. 移交与任务创建（Handoff to Trellis）

当需求完全清晰后，需将决策资产转化为具体的开发任务。这一步是工作流的关键转折点，不同 AI 模型的提示词策略略有不同，但核心逻辑一致：

• 核心指令：要求 AI 基于 CONTEXT.md 和 ADR，将方案拆解为 3-12 个原子化任务（Atomic Tasks）。
• 任务标准：
  • 垂直切片：按功能模块拆分（如“用户登录”），而非按技术层拆分（如“所有 Controller”）。
  • 可验证性：每个任务必须包含具体的验收标准（Acceptance Criteria），如“POST /login 返回 token”，而非模糊的“实现登录功能”。
  • 独立性：每个任务应能独立 Demo 和验证，工作量控制在 30-90 分钟。
• 执行流程：
  1. AI 输出任务拆分表（包含序号、名称、Slug、依赖关系、验收标准）。
  2. 开发者 Review 并确认。
  3. AI 执行 task.py create 命令，创建父任务（史诗）和子任务。
  4. 为每个子任务生成 prd.md，包含目标、范围、关键约束（链接到具体 ADR/Spec）、验收标准等。
  5. 使用 task.py list 查看树形结构，并清空当前指针。

4. Trellis 工作流执行

任务创建完成后，进入标准的 Plan → Implement → Verify → Finish 循环。

• 激活任务：
  • 使用命令 python3 ./.trellis/scripts/task.py start $TASK_DIR 激活特定任务。
  • 或在对话中描述任务，AI 自动识别并激活。
• 执行与推进：
  • /trellis-brainstorm：完善任务 PRD。
  • /trellis:continue：最常用指令，推进代码实现或进入下一阶段。
  • AI 会自动处理代码编写、测试运行等步骤。
• 结束与归档：
  • 任务完成后，必须执行 /trellis:finish-work。
  • 此步骤会生成 Journal（日志），归档任务，更新 Spec，并提交代码到 Git。
  • 定期提交 CONTEXT.md、.trellis/spec/ 和 ADR 到版本控制，保持上下文同步。

常见问题与误区

• 任务未细化：如果 tasks 目录下只有归档文件而无具体任务，通常是因为未正确执行“移交”步骤，或 AI 未按要求生成垂直切片。
• 跳过 Bootstrap：未运行 00-bootstrap-guidelines 会导致 AI 缺乏项目规范，产生推测性代码。
• 验收标准模糊：如果任务只能验证“文件存在”或“能编译”，说明拆分过粗，需进一步拆解为可测的业务逻辑单元。

关键要点

• 解耦决策与执行：人类负责架构决策和需求澄清（Grill 阶段），AI 负责具体实现和状态管理（Trellis 阶段）。
• 原子化任务拆分：任务必须满足“一次能验收”标准，即每个任务都有明确、可测试的验收标准（如接口返回特定数据），而非仅验证代码结构。
• 垂直切片优于技术分层：按功能闭环拆分任务（如“微信登录”包含 DTO、Service、Controller、测试），确保每个任务都能独立运行和演示。
• 约束链接而非复述：在任务 PRD 中，通过链接 docs/adr/ 和 spec/ 文件来引用约束，保持单一真相源，避免信息不同步。
• 标准化命令流：
  • 需求澄清：/grill-doc-me [需求]
  • 任务激活：task.py start [task_dir]
  • 任务推进：/trellis:continue
  • 任务归档：/trellis:finish-work
• 记忆与上下文：利用 CONTEXT.md 和 ADR 作为长期记忆，确保 AI 在不同会话中保持对项目架构和术语的一致性理解。

意义与影响

这套工作流解决了 AI 辅助编程中的两个核心痛点：上下文丢失和任务失控。

1. 提升代码质量与一致性：通过强制性的需求澄清和架构决策记录（ADR），确保代码实现严格遵循既定规范，减少因 AI 幻觉或理解偏差导致的架构漂移。
2. 降低认知负荷：开发者无需记忆复杂的命令或维护庞大的 Prompt，只需关注业务逻辑和技术选型。AI 自动处理任务拆解、代码生成、测试验证和文档更新。
3. 增强可追溯性：每个任务都有独立的 PRD、验收标准和执行日志（Journal），使得开发过程透明可控，便于后期维护和团队协作。
4. 标准化开发流程：将非结构化的创意过程转化为结构化的工程流程，使 AI 辅助开发从“随机生成”走向“可控工程”，特别适用于中大型项目的迭代开发。

通过遵循“想需求 -> 做决策 -> 建物化 -> 放手干”的心法，开发者可以更