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

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

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

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

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

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

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

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

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

如果你研读过我的 bmad 工作流，并亲身体验过，你就会发现在规划、探索流程中你是清晰的，但在执行的真实过程中它是混乱的。Maestro 就是来补这个缺口的。

1.2. Maestro 怎么解决这些问题

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

mindmap
  root(("Maestro 解决的三件事"))
    持久化项目规范
      Spec 系统
      Hooks 自动注入
      跨会话生效
    固定推进节奏
      analyze → plan → execute → verify
      Phase 阶段化
      里程碑收尾
    项目状态可恢复
      state.json 存档
      scratch 中间产物
      换电脑/换会话无缝接续

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

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

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

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

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

另一个区别是规范的强制注入。你手动告诉 Claude「请遵循我们的编码规范」，它可能遵循也可能遗忘；而 Spec + Hooks 是从技术层面保证规范在每次 Agent 启动时都出现在 prompt 最前面，不靠人工提醒。

第二章. 揭秘三层架构：你看到的命令只是冰山一角

这一章是整篇笔记最关键的一章。读完它，你后面看任何 Maestro 命令都会有完全不一样的视角。

2.1. 一句话总结：Maestro 是 LLM 的"任务调度操作系统"

如果你用大模型快速了解这个项目，他大概率只会告诉你「Maestro 提供了 50 多个 /maestro-* 斜杠命令」，然后开始一条一条教你敲。这种教法是错的，会把你引入歧途。

真相是：那 50 多个命令的真正使用者不是你，是 LLM 自己。

你只需要说一句自然语言，比如「帮我做一个用户登录功能」，剩下的事情是 LLM 自己读完项目状态、推断意图、然后自己拼出一条命令链来执行的。

flowchart TB
    subgraph 用户层["👤 用户层（你只在这一层）"]
        U1["自然语言意图<br/>'做一个登录功能'"]
    end

    subgraph 调度层["🧠 LLM 调度层（你看不见）"]
        D1["读 state.json<br/>当前 Phase / 已完成项"]
        D2["读 .workflow/specs<br/>项目规范"]
        D3["意图分析<br/>用户想干什么"]
        D4["拼接 DAG 命令链<br/>analyze→plan→execute→verify"]
        D1 --> D3
        D2 --> D3
        D3 --> D4
    end

    subgraph 执行层["⚙️ 执行层（自动跑）"]
        E1["/maestro-analyze N"]
        E2["/maestro-plan N"]
        E3["/maestro-execute N"]
        E4["/maestro-verify N"]
        E1 --> E2 --> E3 --> E4
    end

    subgraph Hook层["🔌 Hooks 自动化层（背景运行）"]
        H1["spec-injector<br/>每次 Agent 启动自动注入规范"]
        H2["verify-* gates<br/>变更超阈值自动触发审查"]
        H3["state 同步<br/>每步完成自动写入 state.json"]
    end

    U1 --> D1
    D4 --> E1
    Hook层 -.伴随每一步执行.-> 执行层

    style 用户层 fill:#e1f5ff
    style 调度层 fill:#fff4e1
    style 执行层 fill:#e8f5e9
    style Hook层 fill:#fce4ec

2.2. 三层各自在干什么

2.3. 核心调度 Skill 一览

Maestro 内部真正负责"决策"的 skill 不是那 50 个 /maestro-* 命令，而是几个特殊的"调度器"。它们才是 Maestro 的大脑：

mindmap
  root(("Maestro 调度大脑"))
    意图路由
      maestro
      读 state + 拼 DAG
      返回最优命令链
    闭环决策
      maestro-ralph
      读项目状态
      推断当前位置
      构建自适应链
    自然语言转 DAG
      maestro-composer
      解析自然语言
      生成 JSON 模板
      可复用
    DAG 模板执行
      maestro-player
      加载 JSON 模板
      绑定变量
      按 DAG 顺序执行
    缺陷信号收集
      maestro-amend
      扫描 artifacts
      生成 overlay 修补
    非侵入增强
      maestro-overlay
      不改原命令
      叠加自定义行为

这些调度器的存在意味着：/maestro 这一个命令背后，可能展开成 6-10 个子命令的执行链，全部由 LLM 自己决定怎么排。

2.4. 真实交互时序：你说一句话，幕后发生的全部事情

下面这张时序图，是你输入 /maestro -y "实现登录功能" 之后，幕后真实发生的事：

sequenceDiagram
    participant U as 👤 你
    participant C as 🧠 Claude (LLM)
    participant M as 📋 maestro 调度 skill
    participant S as 💾 .workflow/state.json
    participant H as 🔌 Hooks
    participant CLI as ⚙️ Maestro CLI

    U->>C: "/maestro -y 实现登录功能"
    C->>M: 触发 maestro skill
    M->>S: 读取当前项目状态
    S-->>M: 当前 Phase=1, 未完成
    M->>M: 推断意图 = 全流程执行
    M->>C: 返回 DAG: analyze→plan→execute→verify

    Note over C,CLI: 执行链开始

    C->>H: PreToolUse 事件
    H->>H: spec-injector 注入项目规范
    H-->>C: 上下文已加固

    C->>CLI: /maestro-analyze 1
    CLI->>S: 写入 analysis.md
    CLI-->>C: 分析完成

    C->>CLI: /maestro-plan 1
    CLI->>S: 写入 TASK-*.json
    CLI-->>C: 计划生成完成

    C->>CLI: /maestro-execute 1
    Note over CLI: 真正写代码
    CLI->>S: 写入 .summaries
    CLI-->>C: 执行完成

    C->>CLI: /maestro-verify 1
    CLI-->>C: 验证报告 + Gap 列表

    alt 有 gap
        C->>CLI: /maestro-plan 1 --gaps
        C->>CLI: /maestro-execute 1
        C->>CLI: /maestro-verify 1
    end

    C->>U: ✅ Phase 1 完成

注意看这张图的箭头方向：用户只发了一条消息，下面密密麻麻的所有调用全部是 Claude 自己发起的。这才是 Maestro 真正的工作模式。

2.5. 你需要敲哪些命令？

回到现实问题——既然 LLM 自己会调度，你到底需要敲什么？

flowchart LR
    A["你需要敲的命令<br/>≈ 5 个"] --> A1["/maestro-init<br/>初始化项目"]
    A --> A2["/maestro<br/>启动调度器"]
    A --> A3["/maestro-quick<br/>快速小任务"]
    A --> A4["/spec-add<br/>录规范"]
    A --> A5["自然语言<br/>continue / 调整方向"]

    B["LLM 替你敲的命令<br/>≈ 45+ 个"] --> B1["analyze / plan / execute / verify"]
    B --> B2["manage-issue-* 系列"]
    B --> B3["quality-* 系列"]
    B --> B4["learn-* 系列"]
    B --> B5["milestone-audit / complete"]

    style A fill:#c8e6c9
    style B fill:#ffe0b2

结论：日常工作中你真正需要主动敲的命令不超过 5 个，剩下的全部由 LLM 决定。后续章节里我会列出每条命令，但你应该把它当作"参考字典"，而不是"操作手册"。

第三章. 安装

3.1. 安装三步走

flowchart LR
    S1["Step 1<br/>装本体"] --> S2["Step 2<br/>装 Hooks 自动化"]
    S2 --> S3["Step 3<br/>项目内初始化"]
    S3 --> Done["✅ 可以开始用了"]

    S1 -.验证.-> V1["/maestro 命令出现"]
    S2 -.验证.-> V2["maestro hooks status 全 installed"]
    S3 -.验证.-> V3[".workflow/ 目录生成"]

步骤 1：安装 Maestro 本体

1
2

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

这会进入一个交互式安装界面，对于初次使用，直接选择全部安装即可。

成功的标志：在 Claude Code 里输入 /maestro，能看到命令提示出现。

步骤 2：安装 Hooks 自动化

1
2

maestro hooks install --level standard
maestro hooks status

Hooks 是 Maestro 的"自动化神经"，它在你完全不知情的情况下做这些事：

flowchart TB
    A["Hooks 自动化层"] --> A1["spec-injector<br/>Agent 启动 → 注入规范"]
    A --> A2["state-sync<br/>命令完成 → 同步 state.json"]
    A --> A3["verify-gate<br/>代码变更超阈值 → 触发审查"]
    A --> A4["delegate-notify<br/>异步任务完成 → 通知你"]
    A --> A5["context-monitor<br/>上下文用量 → 提醒压缩"]

    style A fill:#fce4ec

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

1

/maestro-init

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

3.2. .workflow/ 目录结构与作用

flowchart TB
    Root[".workflow/"] --> S["state.json<br/>项目当前状态<br/>核心存档"]
    Root --> R["roadmap.md<br/>项目路线图"]
    Root --> P["project.md<br/>项目说明"]
    Root --> Specs["specs/<br/>规范库<br/>Hooks 注入源"]
    Root --> Sc["scratch/<br/>中间产物<br/>命令间通信"]

    Specs --> SC1["coding-conventions.md"]
    Specs --> SC2["arch-decisions.md"]
    Specs --> SC3["learning.md"]

    Sc --> SC4["analysis.md"]
    Sc --> SC5["TASK-*.json"]
    Sc --> SC6[".summaries/"]

    style S fill:#ffeb3b
    style Specs fill:#c8e6c9

state.json 是最核心的文件——LLM 调度器每次决策前都会读它，用来推断「当前进度 + 接下来该干什么」。可以理解成 Maestro 的"主存"。

版本控制建议：.workflow/ 目录建议加入 git，团队成员可以共享项目状态；scratch/ 子目录可以选择加进 .gitignore。

第四章. 跑通第一个项目

我们用「在线教育平台」这个假想项目来完整走一遍。先看官方意义上的"标准六步"，然后揭秘每一步幕后的真实发生。

4.1. 主干流程的状态机视角

每个 Phase 在 Maestro 内部是一个状态机，状态流转由 LLM 自动驱动：

stateDiagram-v2
    [*] --> created: /maestro-roadmap
    created --> analyzing: /maestro-analyze N
    analyzing --> analyzed: 产出 analysis.md
    analyzed --> planning: /maestro-plan N
    planning --> planned: 产出 TASK-*.json
    planned --> executing: /maestro-execute N
    executing --> executed: 代码已写入
    executed --> verifying: /maestro-verify N

    verifying --> passed: 无 gap
    verifying --> gap_found: 发现缺口

    gap_found --> planning: /maestro-plan --gaps
    note right of gap_found
        LLM 自动判断是否
        循环修复，无需手动决定
    end note

    passed --> [*]: Phase 完成

    state Phase完成 {
        [*] --> 等待下一个Phase
    }

4.2. 标准六步对应命令

gantt
    title 一个 Phase 的标准推进时间线
    dateFormat X
    axisFormat %s

    section 初始化（一次性）
    /maestro-init           :init1, 0, 1
    /maestro-roadmap        :init2, after init1, 2

    section Phase 1
    /maestro-analyze 1      :a1, after init2, 3
    /maestro-plan 1         :p1, after a1, 2
    /maestro-execute 1      :crit, e1, after p1, 8
    /maestro-verify 1       :v1, after e1, 2

    section Phase 2
    /maestro-analyze 2      :a2, after v1, 3
    /maestro-plan 2         :p2, after a2, 2
    /maestro-execute 2      :crit, e2, after p2, 8
    /maestro-verify 2       :v2, after e2, 2

    section 里程碑收尾
    /maestro-milestone-audit    :ma, after v2, 2
    /maestro-milestone-complete :mc, after ma, 1

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

1

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

-y 参数表示自动确认，不需要你逐步审批。Maestro 会自动把这个项目拆分成若干个 Phase。

幕后真相：这一步 LLM 内部其实做了三件事——读取 .workflow/specs/ 里的项目约束、调用 roadmapper 子模块拆分阶段、写入 roadmap.md。

4.4. 第二步到第五步：四步流转

sequenceDiagram
    autonumber
    participant U as 👤 你
    participant LLM as 🧠 Claude
    participant M as ⚙️ Maestro
    participant FS as 📁 .workflow/

    U->>LLM: "推进 Phase 1"
    LLM->>M: /maestro-analyze 1
    M->>FS: 读 roadmap.md + state.json
    M->>FS: 写 scratch/analysis.md
    M-->>LLM: ✓ 分析完成

    LLM->>M: /maestro-plan 1
    M->>FS: 读 analysis.md
    M->>FS: 写 TASK-001.json … TASK-N.json
    M-->>LLM: ✓ 计划完成（共 N 个任务）

    LLM->>M: /maestro-execute 1
    loop 每个 TASK
        M->>M: 驱动 Agent 写代码
        M->>FS: 写 scratch/.summaries/<task>.md
    end
    M-->>LLM: ✓ 全部任务完成

    LLM->>M: /maestro-verify 1
    M->>FS: 读 roadmap 验收标准
    M->>M: 比对实际产出
    alt 有 gap
        M-->>LLM: ⚠️ 发现 X 个缺口
        Note over LLM: LLM 自主决定是否循环修复
    else 无 gap
        M-->>LLM: ✅ 验证通过
    end

    LLM->>U: Phase 1 完成报告

4.5. 第六步：里程碑收尾

1
2

/maestro-milestone-audit       # 跨 Phase 集成审计
/maestro-milestone-complete    # 归档 + 推进到下一里程碑

里程碑审计这一步会做的事：

flowchart TB
    Start["/maestro-milestone-audit"] --> A1["扫描所有已完成 Phase"]
    A1 --> A2["检查跨 Phase 依赖"]
    A2 --> A3["检查接口一致性"]
    A3 --> A4["检查测试覆盖盲区"]
    A4 --> Decision{"发现问题?"}
    Decision -->|是| Fix["生成 gap 修复计划"]
    Decision -->|否| Done["/maestro-milestone-complete"]
    Fix --> Loop["重新 plan→execute→verify"]
    Loop --> Done
    Done --> Archive["归档到 .workflow/archive/"]
    Archive --> Next["推进到下一里程碑"]

4.6. 整个流程一览

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

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

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

# Phase 2、3、4 重复同样的步骤

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

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

5.1. 三种姿势的体验差异

journey
    title 三种启动方式的用户体验旅程
    section 一键全自动 /maestro -y
      输入需求: 5: 你
      喝咖啡: 5: 你
      审查报告: 4: 你
    section 逐步推进
      analyze: 4: 你
      检查产出: 5: 你
      plan: 4: 你
      检查产出: 5: 你
      execute: 3: 你
      verify: 5: 你
    section 快速任务 /maestro-quick
      描述任务: 5: 你
      看结果: 4: 你

5.2. 决策树：什么时候用哪种

flowchart TD
    Start{"你要做的事"} --> Q1{"需求是否明确?"}
    Q1 -->|不明确| BS["/maestro-brainstorm"]
    BS --> Q1
    Q1 -->|明确| Q2{"规模大小?"}

    Q2 -->|小任务<br/>修 bug/单文件| Quick["/maestro-quick"]
    Q2 -->|中等以上| Q3{"是否需要严格把控每步?"}

    Q3 -->|信任 AI 全流程| Auto["/maestro -y<br/>一键全自动"]
    Q3 -->|需要逐步检查| Step["逐步推进<br/>analyze→plan→execute→verify"]

    Quick --> End("[完成]")
    Auto --> End
    Step --> End

    style Quick fill:#fff9c4
    style Auto fill:#c8e6c9
    style Step fill:#bbdefb

5.3. 一键全自动

1

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

这是 Maestro 调度能力最完整的体现——一句自然语言，自动串联 init → roadmap → analyze → plan → execute → verify → review → test → milestone-audit 整条链路。

幕后真相：/maestro 这个 skill 本质上是一个"意图路由器"。它读取项目当前状态，分析你的自然语言，然后从内部的命令字典里挑出一条最优执行路径。

sequenceDiagram
    participant U as 👤 你
    participant Router as 🧠 maestro 路由器
    participant State as 💾 state.json
    participant DAG as 🔗 命令链

    U->>Router: /maestro -y "需求"
    Router->>State: 读取项目状态
    State-->>Router: 项目空 / 已有 Phase / 进行中

    alt 项目空
        Router->>DAG: init→roadmap→analyze→plan→execute→verify
    else 已有 Phase 但未推进
        Router->>DAG: analyze→plan→execute→verify
    else Phase 进行中
        Router->>DAG: 从断点续推
    end

    DAG-->>U: 自动执行全链路

5.4. 逐步推进（标准方式）

适合复杂功能、对质量要求高、希望每个阶段都过一遍。这就是第四章讲的方式。

5.5. 快速任务

1

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

/maestro-quick 是所有命令里路径最短的，省略了 init、roadmap、analyze 等步骤，直接进入执行。/maestro-quick 还有两个变体：

5.6. 三种方式对比

1

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

1
2
3
4

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

1

/maestro-quick "具体任务描述"

第六章. 本篇总结

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

你应该已经理解了 Maestro 的真实形态：它不是一个"命令工具集"，而是一个 LLM 调度层。 你看到的那些 /maestro-* 命令大多数情况下是 Claude 自己拼出来的执行链，你的真实接口只有自然语言 + 几个高频命令。

mindmap
  root(("第一篇核心要点"))
    安装
      maestro install
      hooks install --level standard
      /maestro-init
    三层架构
      用户层 自然语言
      LLM 调度层 隐式
      执行层 50+ 命令
      Hooks 层 后台
    主干流程
      analyze
      plan
      execute
      verify
      milestone-audit/complete
    三种启动姿势
      一键 /maestro -y
      逐步 analyze→plan→execute→verify
      快速 /maestro-quick
    你只需要敲
      /maestro-init
      /maestro
      /maestro-quick
      /spec-add
      自然语言

6.1. 本篇速查卡

下一篇我们会用同样的视角，深入「日常开发中最常用的五个场景」——你会看到 Spec 注入、Issue 状态机、Quality 测试链、Delegate 异步消息总线，每一个背后都是 LLM 在替你做决策。