第一篇：装好 Maestro，跑通第一个项目

学习路径：第一章（搞清楚它是什么）→ 第二章（装好它）→ 第三章（跑通主干流程）→ 第四章（选择适合自己的启动姿势）

第一章. Maestro 是什么，能帮你做什么

1.1. 你现在用 Claude Code 可能遇到的三个痛点

假设你正在用 Claude Code 开发一个功能，你大概率遇到过这些情况：

第一个情况，每次开启新对话，都得重新告诉 AI「我们项目用 Hono 框架、命名规范是 camelCase、不要用 any 类型……」，整理这段上下文本身就要花几分钟，而且一旦忘了说，AI 写出来的代码风格就和项目格格不入。

第二个情况，一个功能做到一半，你不确定下一步该干什么。是先写测试？还是先做代码审查？还是直接进下一个模块？每次都要自己想，没有一个清晰的推进节奏。

第三个情况，多人协作的时候，两个人同时让 AI 改同一块代码，最后合并时才发现打架了。或者一个人做完的东西，另一个人完全不知道，重复做了一遍。

这三个问题本质上是同一件事：Claude Code 很擅长完成单次对话里的任务，但它没有能力跨对话持久化项目上下文、规划完整的推进节奏、协调多人的工作边界。

如果你研读过我的bmad 工作流，并亲身体验过，你就会发现在规划、探索流程中你是清晰的，但在执行的真实过程中他是混乱的，所以相比较 bmad

Maestro 就是来补这个缺口的。

1.2. Maestro 怎么解决这些问题

Maestro 是一套运行在 Claude Code 之上的工作流层，它做三件事：

第一件事，让 AI 永远记住你的项目规范。 你把项目的编码规范、架构约束、踩过的坑记录进 Spec 系统，之后每次 AI 启动，这些规范会自动注入到它的上下文里。不用你再重复说，AI 就知道「这个项目用 Hono、命名用 camelCase、分页从 1 开始不是从 0 开始」。

第二件事，给开发流程一个固定的推进节奏。 Maestro 把一个功能的开发拆成四个标准阶段：分析（analyze）→ 规划（plan）→ 执行（execute）→ 验证（verify）。每个阶段有明确的输入、产出和成功标准，做完一步再做下一步，不会迷失方向。

第三件事，用状态文件管理项目进度。 Maestro 把当前做到哪一步、已经完成了什么、还有什么待处理，全部记在 .workflow/ 目录下的文件里。换一台电脑、换一个对话窗口，打开这个项目，AI 立刻知道上次做到哪了，继续推进。

你会接触到三类工具：斜杠命令用在 Claude Code 对话里（比如 /maestro-execute 2），终端命令用在你的 shell 里（比如 maestro delegate "分析这段代码" --to gemini），Hooks 则完全在后台自动运行，不需要你操作。

1.3. 它和直接用 Claude Code 有什么不同

这个问题值得花一点时间想清楚，因为很多人看了一圈文档之后会问：我直接在对话里让 Claude 帮我分析、规划、执行不就好了，为什么要多一层 Maestro？

区别在于持久化和可重复性。

直接用 Claude Code，你每次对话都是从零开始的，上下文不会自动延续。Maestro 把每一步的产出（分析结果、规划文件、执行摘要）都存到文件里，下次打开直接接续，任何人、任何对话窗口都能看到同样的项目状态。

另一个区别是规范的强制注入。你手动告诉 Claude「请遵循我们的编码规范」，它可能遵循，也可能遵循一半，取决于上下文里规范说明的位置和清晰度。Spec + Hooks 是从技术层面保证规范在每次 Agent 启动时都出现在 prompt 最前面，不靠人工提醒。

第二章. 安装

2.1. 安装三步走

安装过程分三步，每步结束都有一个可以验证的成功现象。

步骤 1：安装 Maestro 本体

在终端里运行：

1
2

npm install -g maestro-flow 或 pnpm install -g maestro-flow
maestro install

这会进入一个交互式安装界面，它会问你要安装哪些组件。对于初次使用，直接选择全部安装即可。安装完成后，你的 Claude Code 对话框里就可以使用 /maestro-* 系列斜杠命令了，若实际体验不佳，maestro 也提供了一键卸载功能，所以不必担心

成功的标志：在 Claude Code 里输入 /maestro，能看到命令提示出现，而不是「命令不存在」的报错。

步骤 2：安装 Hooks 自动化

1

maestro hooks install --level standard

Hooks 是 Maestro 的自动化层，负责在你每次调用 AI Agent 时自动注入项目规范、监控上下文用量等后台工作。standard 级别包含日常开发需要的全部自动化能力，推荐首次使用就选这个。

成功的标志：运行下面这个命令，能看到各个 Hook 的安装状态都显示为 installed：

1

maestro hooks status

步骤 3：在项目里初始化 Maestro

进入你的项目目录，运行：

1

/maestro-init

这个命令会在项目根目录下创建 .workflow/ 目录，这是 Maestro 用来存放所有状态文件的地方。

成功的标志：项目根目录下出现 .workflow/ 文件夹，里面有 state.json 文件。

2.2. .workflow/ 目录是干什么的

装好之后你会发现项目里多了一个 .workflow/ 目录，里面有一些文件。你不需要手动编辑这些文件，但大概知道它们是干什么的会有帮助。

1
2
3
4
5
6

.workflow/
├── state.json          # 项目当前状态：做到哪个阶段、完成了哪些 Phase
├── roadmap.md          # 项目路线图：拆分成了哪些阶段
├── project.md          # 项目说明：技术栈、背景信息
├── specs/              # 项目规范：你录入的编码规范、架构约束、踩坑记录
└── scratch/            # 工作区：每次分析、规划、执行的产物文件

state.json 是最核心的文件，它记录了项目当前做到哪一步。Maestro 的每个命令在运行前都会读这个文件，知道接下来该做什么。你可以把它理解成项目的「当前进度存档」。

scratch/ 目录下的文件是 Maestro 自动生成的，每次分析、规划、执行都会在这里留下产物。这些文件是各命令之间传递信息的载体，不需要你去读它们，但如果某个步骤出了问题需要排查，可以来这里看中间产物。

.workflow/ 目录建议加入版本控制（git commit 进去），这样团队所有人可以看到同样的项目状态。scratch/ 目录下的内容是临时工作产物，可以选择加进 .gitignore。

第三章. 跑通第一个项目

我们用「在线教育平台」这个假想项目来完整走一遍主干流程。不管你实际要做什么项目，这个流程是一样的。

3.1. 第一步：告诉 Maestro 你要做什么

完成 /maestro-init 之后，下一步是创建路线图，让 Maestro 知道这个项目要做什么、分几个阶段推进。

在 Claude Code 里运行：

1

/maestro-roadmap "在线教育平台，包含用户系统、课程管理、视频播放和支付功能" -y

-y 参数表示自动确认，不需要你逐步审批每个决策，直接生成完整路线图。

Maestro 会自动把这个项目拆分成若干个 Phase（阶段）。比如：

• Phase 1：用户系统（注册、登录、权限管理）
• Phase 2：课程管理（课程 CRUD、分类、搜索）
• Phase 3：视频播放（上传、转码、进度记录）
• Phase 4：支付功能（接入支付宝/微信）

成功的标志：.workflow/roadmap.md 文件被创建，里面有清晰的阶段划分。

如果项目需求比较复杂，或者你希望先头脑风暴再确认方向，可以在 roadmap 之前先跑 /maestro-brainstorm "在线教育平台"，多角色讨论完再生成路线图。

3.2. 第二步：分析第一个阶段

路线图有了，接下来开始推进 Phase 1（用户系统）。

1

/maestro-analyze 1

数字 1 表示只分析 Phase 1。Maestro 会读取路线图和项目信息，分析这个阶段需要做什么、有哪些技术决策需要确认、依赖关系是什么。

产出是两个文件，都在 scratch/ 目录下：context.md（分析这个阶段需要的上下文）和 analysis.md（具体的分析结论）。你不需要去读这两个文件，它们是给下一个命令用的。

成功的标志：命令运行完毕，没有报错，Maestro 提示你可以运行 /maestro-plan 1 了。

3.3. 第三步：规划任务清单

1

/maestro-plan 1

Maestro 读取上一步的分析结果，生成具体的任务清单。每个任务是一个独立的工作单元，有明确的目标和完成标准。

产出是一组 TASK-*.json 文件，记录了 Phase 1 需要完成的所有具体任务，比如「实现用户注册 API」「实现 JWT 登录验证」「编写用户表 migration」等。

成功的标志：Maestro 输出一个任务列表预览，你能看到 Phase 1 被拆分成了多少个具体任务。

3.4. 第四步：执行

1

/maestro-execute 1

这是真正开始写代码的阶段。Maestro 会按照规划好的任务清单，逐个驱动 AI Agent 完成每个任务。

执行过程中，你会看到 AI 在写代码、创建文件、修改配置。每个任务完成后，Maestro 会在 scratch/.summaries/ 目录下记录一个执行摘要，说明这个任务做了什么，供后续验证使用。

这个步骤耗时最长，取决于 Phase 包含多少任务。执行期间你可以做别的事情，不需要一直盯着。

成功的标志：Maestro 提示所有任务已完成，并建议你运行 /maestro-verify 1。

3.5. 第五步：验证

1

/maestro-verify 1

执行完之后，Maestro 检查这个阶段的产出是否符合路线图里定义的目标。它会逐项核对「应该完成的事情」是否真的完成了，发现缺口（gaps）会明确告诉你。

如果验证通过，Phase 1 就完成了。如果发现缺口，你有两个选择：

一是让 Maestro 自动生成修复计划来补齐缺口：

1
2
3

/maestro-plan 1 --gaps
/maestro-execute 1
/maestro-verify 1   # 重新验证

二是手动检查验证报告，判断缺口是否需要在这个阶段处理，还是留到后续迭代。

成功的标志：Maestro 输出验证报告，显示 Phase 1 的所有目标都已覆盖，或者明确列出还剩哪些缺口。

3.6. 第六步：收尾一个里程碑

当一个里程碑的所有 Phase 都跑完了 analyze → plan → execute 的完整链路之后，运行：

1

/maestro-milestone-audit

这个命令做最终审计，检查整个里程碑有没有遗漏的东西，Phase 之间有没有集成问题。审计通过后：

1

/maestro-milestone-complete

这个命令把这个里程碑的所有工作产物归档，并把项目状态推进到下一个里程碑，你就可以开始推进 Phase 2、Phase 3……了。

成功的标志：Maestro 提示里程碑已归档，state.json 里的当前里程碑已更新到下一个。

3.7. 整个流程一览

把上面六步用命令串起来看：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 初始化（只做一次）
/maestro-init
/maestro-roadmap "项目描述" -y

# Phase 1 完整推进
/maestro-analyze 1
/maestro-plan 1
/maestro-execute 1
/maestro-verify 1

# Phase 2、3、4 重复同样的步骤
/maestro-analyze 2
/maestro-plan 2
# ...

# 里程碑收尾
/maestro-milestone-audit
/maestro-milestone-complete

每个 Phase 的四步（analyze → plan → execute → verify）是固定的节奏，不管做什么功能都是这个流程，熟悉一次之后后面每次都一样。

第四章. 三种启动方式，按需选择

第三章走的是「逐步精控」的标准流程，每一步都手动触发，确认再继续。但 Maestro 还支持另外两种方式，适合不同的场景。

4.1. 想偷懒：一键全自动

如果你对项目的方向很清楚，不想一步步确认，可以直接把任务甩给 Maestro：

1

/maestro -y "实现用户认证系统，包含注册、登录、JWT 刷新和权限校验"

-y 参数让 Maestro 跳过所有交互式确认，自动串联 init → roadmap → analyze → plan → execute → verify → review → test → milestone-audit 整条链路，你去喝杯咖啡，回来就有结果。

适合的场景：需求明确、项目规模不太大、你对 AI 的判断有足够信心。

不适合的场景：需求还在探索阶段、有复杂的架构决策需要人工参与、你希望每个阶段都过一遍再继续。

4.2. 想控制节奏：逐步推进

这就是第三章讲的标准方式，按 Phase 编号逐步推进。这种方式让你在每个阶段都有机会检查产出、调整方向、手动介入。

推进到某一步发现方向不对，可以直接重新运行那一步的命令，不影响已完成的其他 Phase。

适合的场景：需求复杂、对质量要求高、你想深度参与每个阶段的决策。

4.3. 临时任务不想建项目：直接分析

有时候你只是想让 Maestro 帮你分析一个具体问题，或者快速修一个 bug，不需要建完整的项目结构。这时不用 init，不用 roadmap，直接：

1

/maestro-analyze "给现有的 Express API 加上 rate limiting"

Maestro 会自动以「独立任务」的模式处理，产物存在 scratch/ 里，不影响主项目的状态。用完即走，非常轻量。

或者更快的方式，用快速任务命令：

1

/maestro-quick "修复登录页在移动端的样式错乱"

/maestro-quick 是所有命令里路径最短的，省略了一切可选步骤，直接到执行。适合明确的小任务，比如修 bug、加一个小功能、改一段配置。

/maestro-quick 还有两个变体：加上 --full 会在执行后多一个规划验证步骤，加上 --discuss 会在执行前先讨论方案并提取决策点。需要更严谨一点的时候可以选这两个。

4.4. 三种方式对比

1

/maestro -y "你的需求描述"

1
2
3
4

/maestro-analyze 1
/maestro-plan 1
/maestro-execute 1
/maestro-verify 1

1
2

/maestro-quick "具体任务描述"
/maestro-analyze "你想分析的主题"  # 纯分析不需要执行

第五章. 本篇总结

这一篇我们从零开始，完整走了一遍「装好 Maestro、跑通第一个项目」的全过程。

安装只需要三步：maestro install 装本体，maestro hooks install --level standard 装自动化，/maestro-init 在项目里初始化。

主干流程的节奏是固定的：roadmap 规划 → analyze 分析 → plan 规划任务 → execute 执行 → verify 验证，每个 Phase 都走这五步，做完一个 Phase 再做下一个，最后 milestone-audit + milestone-complete 收尾一个里程碑。

三种启动方式各有适用场景，日常开发推荐逐步推进，需要快速出结果用一键全自动，临时小任务直接用 /maestro-quick。

5.1 本篇速查卡