Claude Code 工作流：Maestro（二） 日常开发中最常用的场景

第二篇：日常开发中最常用的场景

适用环境：已完成第一篇的安装与初始化，Claude Code 最新版，Hooks 级别 standard 已安装

学习路径：第一章（让 AI 记住规范）→ 第二章（发现和修复问题）→ 第三章（代码验收）→ 第四章（委托其他 AI）→ 第五章（设置命令默认值）

沿用第一篇的视角：本篇讲的五个场景，用户真正手敲的命令仍然只占少数，绝大多数动作是 LLM 读完上下文之后自动调度的。每章我都会画一张时序图或状态机，让你看清"用户视角 vs LLM 视角"的真实差别。

第一章. 让 AI 记住你的项目规范

1.1. 为什么每次都要重新告诉 AI 规范

用 Claude Code 开发的人都体会过这个过程：新开一个对话窗口，先花几分钟粘贴一段话——「我们用 TypeScript 严格模式、API 框架用 Hono、数据库用 Drizzle ORM、命名规范是 camelCase、禁止使用 any……」。

这段话你可能已经复制粘贴了几十次了。而且就算粘贴了，AI 在对话后期写代码时还是可能「忘记」。

Maestro 的 Spec 系统解决的就是这个问题。你只需要把这些规范录入一次，之后每次 AI 启动，Hooks 会在你完全感知不到的情况下，自动把对应的规范注入到 LLM 的上下文里。

1.2. Spec 系统的三层模型

flowchart TB
    subgraph Layer1["📝 录入层（你只在这里操作一次）"]
        U["/spec-add coding "...""]
        U2["/spec-setup<br/>扫描已有项目"]
    end

    subgraph Layer2["💾 存储层（持久化）"]
        F1[".workflow/specs/<br/>coding-conventions.md"]
        F2[".workflow/specs/<br/>arch-decisions.md"]
        F3[".workflow/specs/<br/>learning.md"]
        F4[".workflow/specs/<br/>test-conventions.md"]
    end

    subgraph Layer3["🔌 注入层（LLM 启动时自动）"]
        H["spec-injector Hook<br/>PreToolUse 触发"]
        Match["关键词 + 分类匹配"]
        Inject["拼接到 Agent prompt 最前面"]
    end

    subgraph Layer4["🧠 消费层（LLM 自动遵守）"]
        Agent["Claude Agent<br/>启动 + 收到注入规范"]
    end

    U --> F1
    U --> F2
    U --> F3
    U2 --> F1
    U2 --> F2

    F1 --> H
    F2 --> H
    F3 --> H
    F4 --> H

    H --> Match
    Match --> Inject
    Inject --> Agent

    style Layer1 fill:#e1f5ff
    style Layer2 fill:#fff4e1
    style Layer3 fill:#fce4ec
    style Layer4 fill:#e8f5e9

1.3. 录入一条规范只需要一行命令

1
/spec-add coding "所有 API 路由统一使用 Hono 框架，不允许混用 Express"

coding 是这条规范的分类。Maestro 会自动从内容里提取关键词（比如 hono、api-routing、framework），然后把这条规范写入 .workflow/specs/coding-conventions.md 文件。

六大分类的归属关系：

mindmap
  root(("Spec 分类"))
    coding
      命名规范
      框架选型
      代码风格
      禁用写法
    arch
      模块边界
      层级约束
      架构决策
    test
      测试框架
      覆盖率要求
      测试命名
    debug
      已知坑
      根因记录
      排查技巧
    learning
      踩过的 bug
      经验教训
      边界条件
    review
      审查清单
      质量门槛

举几个实际的例子：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 编码规范
/spec-add coding "所有 API 路由统一使用 Hono 框架，不允许混用 Express"
/spec-add coding "禁止使用 TypeScript 的 any 类型，必须明确声明类型"

# 架构约束
/spec-add arch "通知模块使用事件驱动架构，不允许直接调用通知服务"

# 踩坑记录
/spec-add learning "分页参数 page 从 1 开始，不是 0，传 0 会导致 offset 计算错误"
/spec-add learning "Drizzle 的 .returning() 在 SQLite 下不支持，只能用 MySQL/PostgreSQL"

# 已知的调试技巧
/spec-add debug "登录失败时先检查 Redis 里的 session 是否过期，过期时间默认 7200s"

1.4. 注入时机的真实时序

sequenceDiagram
    autonumber
    participant U as 👤 你
    participant CC as 🖥️ Claude Code
    participant Hook as 🔌 spec-injector
    participant FS as 📁 .workflow/specs
    participant Agent as 🧠 Claude Agent

    U->>CC: "帮我写登录接口"
    CC->>Agent: 准备启动 Agent

    Note over Hook: PreToolUse 事件触发
    CC->>Hook: 拦截 Agent 启动
    Hook->>Hook: 识别 Agent 类型 = 写代码
    Hook->>FS: 加载 coding 分类规范
    Hook->>FS: 加载 learning 分类规范
    FS-->>Hook: 返回匹配的 spec 条目

    Hook->>Hook: 拼接到 system prompt 最前面
    Hook-->>CC: 上下文已加固

    CC->>Agent: 启动 (带规范)
    Agent->>Agent: 写代码<br/>自动遵守规范
    Agent-->>U: ✅ 符合规范的代码

    Note over U,Agent: 全程你只输入了一句话

1.5. 不同 Agent 类型的规范匹配规则

不是所有规范都会注入给所有 Agent。Hook 会根据 Agent 的"职责"来挑选：

flowchart LR
    Agent{"Agent 类型"} --> A1["写代码 Agent"]
    Agent --> A2["测试 Agent"]
    Agent --> A3["审查 Agent"]
    Agent --> A4["调试 Agent"]
    Agent --> A5["架构 Agent"]

    A1 --> S1["coding + learning + arch"]
    A2 --> S2["coding + test"]
    A3 --> S3["coding + review + arch"]
    A4 --> S4["debug + learning + coding"]
    A5 --> S5["arch + coding"]

    style Agent fill:#fff4e1

1.6. 主动检索规范（少数手动场景）

1
2
3
4
5
6
7
8
# 把所有编码规范加载进来
/spec-load --category coding

# 只加载和认证相关的规范
/spec-load --keyword auth

# 组合使用
/spec-load --category coding --keyword naming

适合在做代码审查之前、或者开始一个涉及核心架构的新功能之前，让 LLM 拿到完整规范背景。

1.7. 初次接入已有项目

1
/spec-setup

这条命令会让 LLM 自己扫一遍你的代码库，识别技术栈、读 lint 配置、读测试框架，然后自动调用 /spec-add 把识别出来的规范一条条录入。这又是一个典型的"LLM 自己调度子命令"的例子。

sequenceDiagram
    participant U as 👤 你
    participant LLM as 🧠 Claude
    participant FS as 📁 项目代码

    U->>LLM: /spec-setup
    LLM->>FS: 扫 package.json
    LLM->>FS: 扫 tsconfig.json
    LLM->>FS: 扫 eslint.config
    LLM->>FS: 扫测试目录
    FS-->>LLM: 技术栈识别完成

    loop 每条识别的规范
        LLM->>LLM: /spec-add coding "..."
        LLM->>LLM: /spec-add test "..."
        LLM->>LLM: /spec-add arch "..."
    end

    LLM->>U: ✅ 录入 N 条规范

1.8. 本节小结

要点何时使用关键动作
录入一条规范发现需要约束某个写法时/spec-add coding "规范内容"
扫描已有项目生成规范接入已有项目时/spec-setup（LLM 自动批量录入）
手动检索规范需要 AI 参考完整规范背景时/spec-load --keyword xxx

第二章. 发现问题、修复问题

Maestro 的 Issue 系统是一套独立的问题追踪机制，可以和主干流程并行运行。理解 Issue 系统的关键是看清它的状态机。

2.1. Issue 的完整状态机

stateDiagram-v2
    [*] --> open: /manage-issue create<br/>或 discover 自动产出

    open --> diagnosing: /maestro-analyze --gaps ISS-N
    diagnosing --> diagnosed: 根因报告产出

    diagnosed --> planning: /maestro-plan --gaps
    planning --> planned: 修复任务清单生成

    planned --> fixing: /maestro-execute
    fixing --> resolved: 代码修复完成

    resolved --> closed: /manage-issue close ISS-N
    resolved --> reopened: 验证未通过
    reopened --> diagnosing: 重新诊断

    open --> closed: 直接关闭<br/>(误报/不修)

    closed --> [*]

    note right of fixing
        每个状态切换都由
        LLM 监测 artifacts
        自动驱动
    end note

2.2. Issue 与主干 Phase 是两条平行轨道

flowchart TB
    subgraph 主干轨道["主干 Phase 轨道"]
        P1["Phase 1<br/>analyze→plan→execute→verify"]
        P2["Phase 2<br/>analyze→plan→execute→verify"]
        P3["Phase 3"]
        P1 --> P2 --> P3
    end

    subgraph Issue轨道["Issue 修复轨道（并行）"]
        I1["ISS-001<br/>登录并发 bug"]
        I2["ISS-002<br/>样式错乱"]
        I3["ISS-003<br/>性能慢"]
    end

    Discovery["/manage-issue-discover<br/>八角度扫描"] --> I1
    Discovery --> I2
    Discovery --> I3

    Manual["/manage-issue create"] --> I1

    style 主干轨道 fill:#e3f2fd
    style Issue轨道 fill:#ffebee

2.3. 让 AI 主动帮你找问题

1
/manage-issue-discover

这条命令背后实际上是 LLM 自己启动了 8 个并行的扫描 Agent：

mindmap
  root(("manage-issue-discover<br/>八角度扫描"))
    安全漏洞
      SQL 注入
      XSS / CSRF
      鉴权绕过
    性能问题
      N+1 查询
      死循环
      内存泄漏
    可靠性
      错误处理
      重试机制
      幂等性
    可维护性
      代码异味
      重复代码
      过度耦合
    可扩展性
      硬编码
      架构瓶颈
    用户体验
      响应慢
      报错不友好
    可访问性
      键盘导航
      语义化标签
    合规性
      许可证
      数据隐私

定向扫描：

1
/manage-issue-discover by-prompt "检查所有 API 端点的错误处理，特别是 400 和 500 状态码是否都有对应处理"

2.4. 标准修复链路：用户视角 vs LLM 视角

官方文档教你的命令序列：

1
2
3
4
/maestro-analyze --gaps ISS-001    # 诊断根因
/maestro-plan --gaps               # 生成修复计划
/maestro-execute                   # 执行修复
/manage-issue close ISS-001 --resolution "修复说明"

真实发生的事：

sequenceDiagram
    autonumber
    participant U as 👤 你
    participant LLM as 🧠 Claude
    participant Issue as 📋 Issue Store
    participant FS as 📁 .workflow/

    U->>LLM: "修一下 ISS-001"

    Note over LLM: LLM 自己拼装链路

    LLM->>LLM: /maestro-analyze --gaps ISS-001
    LLM->>FS: 读 Issue 描述
    LLM->>FS: 深入代码找根因
    LLM->>Issue: 状态 → diagnosed
    LLM->>FS: 写诊断报告

    LLM->>LLM: /maestro-plan --gaps
    LLM->>FS: 生成 TASK-fix-*.json
    LLM->>Issue: 状态 → planned

    LLM->>LLM: /maestro-execute
    Note over LLM: 真正写修复代码
    LLM->>Issue: 状态 → resolved

    LLM->>U: 修复完成，需要确认关闭吗？
    U->>LLM: "确认关闭"
    LLM->>Issue: 状态 → closed

整个过程你只输入了两句话：“修一下 ISS-001” 和 “确认关闭”。

2.5. 手动记录 vs 快速修

flowchart TD
    Bug{"发现问题"} --> Q1{"改动大小?"}

    Q1 -->|改动很大<br/>需要诊断| Create["/manage-issue create<br/>--severity high"]
    Create --> Flow["走完整 Issue 流程"]
    Flow --> Diag["analyze --gaps"]
    Diag --> Plan["plan --gaps"]
    Plan --> Exec["execute"]
    Exec --> Close["close ISS-N"]

    Q1 -->|改动很小<br/>原因明确| Quick["/maestro-quick &quot;修复描述&quot;"]
    Quick --> Done["直接修完"]

    style Quick fill:#fff9c4
    style Flow fill:#bbdefb

2.6. 本节小结

要点何时使用关键动作
主动扫描发现问题阶段性代码质量检查时/manage-issue-discover
手动记录一个 bug发现具体问题时/manage-issue create --title "..." --severity high
完整修复链路问题原因不明确、需要深度分析analyze --gaps → plan --gaps → execute → close（LLM 自动串联）
快速修小 bug问题范围明确、改动很小/maestro-quick "修复描述"

第三章. 代码跑完之后怎么验收

代码执行完了，不等于功能做好了。Maestro 把验收拆成三个不同角度，每个回答不同的问题。

3.1. 三种验收测试的分工

flowchart TB
    Code["代码执行完成"] --> Q1{"需要验收什么?"}

    Q1 --> A1["业务规则<br/>/quality-business-test N"]
    Q1 --> A2["代码执行<br/>/quality-test N"]
    Q1 --> A3["覆盖率盲区<br/>/quality-test-gen N"]

    A1 --> R1["PRD 业务场景<br/>是否全部实现?"]
    A2 --> R2["接口能跑通?<br/>返回符合预期?"]
    A3 --> R3["有没有未测的<br/>边界条件?"]

    R1 --> Pass1{"通过?"}
    R2 --> Pass2{"通过?"}
    R3 --> Pass3{"通过?"}

    Pass1 -->|否| Debug["/quality-debug<br/>--from-business-test"]
    Pass2 -->|否| Debug2["/quality-debug<br/>--from-uat"]
    Pass3 -->|否| Gen["补充测试用例"]

    Debug --> Fix["plan --gaps → execute → re-run"]
    Debug2 --> Fix
    Gen --> Fix

    Pass1 -->|是| Final["全部通过 → 进入 review"]
    Pass2 -->|是| Final
    Pass3 -->|是| Final

    style A1 fill:#c8e6c9
    style A2 fill:#bbdefb
    style A3 fill:#ffe0b2

3.2. 推荐的验收顺序（甘特图视角）

gantt
    title Phase 1 完成后的验收时间线
    dateFormat X
    axisFormat %s

    section 验收链路
    quality-business-test 1   :crit, bt, 0, 3
    quality-test 1            :ut, after bt, 3
    quality-review 1          :rv, after ut, 4
    quality-test-gen 1 (可选) :tg, after rv, 3

    section 失败修复（如有）
    quality-debug             :db, after bt, 2
    plan --gaps               :pg, after db, 1
    execute                   :ex, after pg, 4
    re-run                    :rr, after ex, 2

3.3. 三种测试的细节

命令：/quality-business-test N

回答的问题：PRD 里写的业务规则，代码有没有全部实现？

LLM 内部行为：

  1. 读取 roadmap.md 里 Phase N 的验收标准
  2. 提取所有业务场景为 fixture
  3. 逐场景执行验证
  4. 输出场景通过率 + 失败场景详情

适合在什么时候跑：/maestro-execute 完成之后，首先跑这个。

命令：/quality-test N

回答的问题：代码本身能不能跑起来、接口能不能正确响应？

LLM 内部行为：

  1. 启动会话式 UAT
  2. 自动发现接口 / 入口
  3. 模拟真实用户操作
  4. 自动诊断失败 + 生成 gap-plan

适合在什么时候跑：业务测试通过之后，再跑这个验证代码层面的健康状况。

命令：/quality-test-gen N

回答的问题：有没有哪些场景我们没有测试到？

LLM 内部行为：

  1. 分析代码分支
  2. 识别未覆盖路径
  3. 用 TDD/E2E 分类
  4. RED-GREEN 方法生成补充测试

适合在什么时候跑：发布前用它扫一遍覆盖率盲区。

3.4. 测试失败的修复状态机

stateDiagram-v2
    [*] --> testing: /quality-business-test N
    testing --> passed: 全部通过
    testing --> failed: 发现失败场景

    failed --> debugging: /quality-debug<br/>--from-business-test N
    debugging --> diagnosed: 根因报告

    diagnosed --> planning: /maestro-plan N --gaps
    planning --> fixing: /maestro-execute 1
    fixing --> rerunning: /quality-business-test N --re-run

    rerunning --> passed: 全部通过
    rerunning --> failed: 仍有失败<br/>(回到 debugging)

    passed --> [*]

--re-run 参数是关键——只跑上次失败的场景，节省大量时间。

3.5. 代码审查（不同力度）

flowchart LR
    Review{"quality-review"} --> Q1{"力度?"}
    Q1 -->|快速扫一眼| Quick["--level quick<br/>明显问题"]
    Q1 -->|默认| Std["--level standard<br/>风格+bug+安全+性能"]
    Q1 -->|深度| Deep["--level deep<br/>核心模块/发布前"]

    Quick --> Out1["控制台报告"]
    Std --> Out2["控制台报告 + 自动建 Issue"]
    Deep --> Out3["详细报告 + 多并行 Agent"]

    Out2 -.critical/high.-> NewIssue["自动 /manage-issue create"]
    Out3 -.critical/high.-> NewIssue

    style Deep fill:#ffcdd2
    style Std fill:#fff9c4
    style Quick fill:#c8e6c9

注意：审查发现的 critical / high 问题，Maestro 会自动调用 /manage-issue create 把它们登记进 Issue 系统——又是一个典型的 LLM 内部串联。

3.6. 验收完整时序

sequenceDiagram
    autonumber
    participant U as 👤 你
    participant LLM as 🧠 Claude
    participant T as 🧪 测试引擎

    U->>LLM: "Phase 1 跑完了，验收一下"

    Note over LLM: LLM 自动决定跑哪些测试

    LLM->>T: /quality-business-test 1
    T-->>LLM: 业务通过率 95%（2 失败）

    LLM->>T: /quality-debug --from-business-test 1
    T-->>LLM: 根因报告

    LLM->>T: /maestro-plan 1 --gaps
    LLM->>T: /maestro-execute 1
    LLM->>T: /quality-business-test 1 --re-run
    T-->>LLM: ✅ 全部通过

    LLM->>T: /quality-test 1
    T-->>LLM: ✅ 通过

    LLM->>T: /quality-review 1 --level standard
    T-->>LLM: 发现 1 个 high 问题
    LLM->>LLM: 自动 /manage-issue create

    LLM->>U: 验收报告 + 新建 Issue ISS-N

3.7. 本节小结

要点何时使用关键动作
业务规则测试execute 完成后第一件事/quality-business-test N
代码执行测试业务测试通过后/quality-test N
覆盖率补充发布前、高质量要求时/quality-test-gen N
代码审查每个 Phase 执行后/quality-review N --level deep
测试失败修复任何测试报错时quality-debug → plan --gaps → execute → re-run

第四章. 把任务交给其他 AI 来做（Delegate）

前三章讲的都是在 Claude Code 里直接操作的场景。这一章介绍一个不同的思路——把任务异步地委托给另一个 AI 引擎（Gemini、Codex 等）去跑。

4.1. Delegate 的本质：异步消息总线

flowchart TB
    subgraph 主会话["🖥️ 主会话（Claude Code）"]
        U["👤 你"]
        Main["🧠 Claude 主线"]
    end

    subgraph Broker["🚌 Maestro Broker"]
        Queue["执行队列"]
        State["Job 状态机"]
        Inbox["消息收件箱"]
    end

    subgraph 委托执行["⚙️ 委托执行（异步进程）"]
        G["Gemini CLI"]
        C["Codex CLI"]
        Q["Qwen CLI"]
        OC["OpenCode"]
    end

    U -->|/maestro delegate| Main
    Main -->|发送任务| Queue
    Queue --> G
    Queue --> C
    Queue --> Q
    Queue --> OC

    G --> State
    C --> State
    OC --> State

    Main -->|查状态| State
    Main -->|注入消息| Inbox
    Inbox --> G

    State -.完成通知.-> Main
    Main -.通知.-> U

    style 主会话 fill:#e3f2fd
    style Broker fill:#fff4e1
    style 委托执行 fill:#e8f5e9

4.2. Job 完整生命周期

stateDiagram-v2
    [*] --> queued: maestro delegate "..."
    queued --> running: Broker 调度

    running --> input_required: 需要补充信息
    input_required --> running: delegate message <id>

    running --> completed: 任务完成
    running --> failed: 出错
    running --> cancelled: delegate cancel <id>

    completed --> [*]
    failed --> [*]
    cancelled --> [*]

    note right of running
        中途可注入消息
        --delivery inject
    end note

    note right of completed
        完成时若有 after_complete
        消息排队，自动重新启动
    end note

4.3. 三种典型用法

mindmap
  root(("Delegate 三种用法"))
    异步分散
      不阻塞主会话
      让大上下文模型跑大任务
      Gemini 1M context
    模型路由
      Gemini 大代码库分析
      Codex 后端实现
      Claude 复杂推理
      根据任务选模型
    任务串联
      analyze → fix 自动接力
      after_complete delivery
      多步骤工作流

4.4. 异步委托完整时序

sequenceDiagram
    autonumber
    participant U as 👤 你
    participant Claude as 🧠 主会话 Claude
    participant Broker as 🚌 Maestro Broker
    participant Gemini as 💎 Gemini

    U->>Claude: "让 Gemini 分析一下 src/auth 安全漏洞"
    Claude->>Broker: maestro delegate "..." --to gemini --async
    Broker-->>Claude: ID = gem-143022-a7f2

    par 主会话继续工作
        U->>Claude: "继续帮我写课程模块"
        Claude->>Claude: 写代码（不被阻塞）
        Claude-->>U: 课程模块完成
    and Gemini 异步执行
        Broker->>Gemini: 启动分析任务
        Gemini->>Gemini: 扫描 src/auth
        Gemini-->>Broker: 状态 → completed
    end

    Note over Broker,Claude: Hook 自动通知

    Broker-->>Claude: 任务 gem-143022-a7f2 完成
    Claude->>Broker: maestro delegate output gem-143022-a7f2
    Broker-->>Claude: 完整分析报告
    Claude->>U: 📋 Gemini 分析结果（含 N 个高危）

4.5. 任务串联：自动接力

1
2
3
4
5
6
7
8
# 第一步：启动分析任务
maestro delegate "找出所有高危安全漏洞" --to gemini --async
# 得到 ID：gem-143022-a7f2

# 第二步：排队后续任务
maestro delegate message gem-143022-a7f2 \
  "分析完成后，修复所有 critical 和 high 级别的漏洞" \
  --delivery after_complete
sequenceDiagram
    autonumber
    participant U as 👤 你
    participant Broker as 🚌 Broker
    participant G as 💎 Gemini (分析)
    participant C as 🧠 Claude (修复)

    U->>Broker: delegate "找漏洞" --to gemini --async
    Broker->>G: 启动分析

    U->>Broker: delegate message <id><br/>"修复漏洞" --delivery after_complete
    Broker->>Broker: 排队修复任务

    G->>G: 分析中...
    G->>Broker: ✅ 分析完成 + 报告

    Note over Broker: 触发 after_complete

    Broker->>C: 启动修复任务<br/>(以分析报告为上下文)
    C->>C: 修复中...
    C->>Broker: ✅ 修复完成

    Broker-->>U: 全链路完成通知

4.6. 中途注入与取消

1
2
3
4
5
# 中途追加上下文
maestro delegate message gem-143022-a7f2 "也检查 src/utils/sanitize.ts"

# 取消
maestro delegate cancel gem-143022-a7f2

注入两种模式：

模式行为适用
inject（默认）路由到正在运行的 worker stdin中途补充上下文
after_complete排队等当前任务完成任务串联

4.7. 支持的 AI 工具

flowchart LR
    Delegate{"maestro delegate"} --> T1["--to gemini<br/>大上下文分析"]
    Delegate --> T2["--to codex<br/>后端实现"]
    Delegate --> T3["--to claude<br/>另一会话 复杂推理"]
    Delegate --> T4["--to qwen<br/>通义千问"]
    Delegate --> T5["--to opencode<br/>OpenCode"]

    Delegate -.--role 指定能力.-> R["capability 路由<br/>analyze/explore/review/<br/>implement/plan/brainstorm"]

    style Delegate fill:#fff4e1

4.8. 本节小结

要点何时使用关键动作
异步委托一个任务耗时分析、不想等结果时maestro delegate "..." --to gemini --async
查看任务状态想知道任务跑完没maestro delegate status <id>
取回结果任务完成后maestro delegate output <id>
串联后续任务分析完自动触发修复maestro delegate message <id> "..." --delivery after_complete
中途补充上下文任务进行中想追加信息maestro delegate message <id> "补充内容"

第五章. 不想每次都手打参数（Config）

用了一段时间 Maestro 之后，你会发现有些参数几乎每次都要加，比如 /maestro-execute 后面总是要带 --auto-commit。Maestro 的 Skill 默认值配置就是解决这个问题的。

5.1. 默认值配置的本质

flowchart LR
    subgraph 没配置默认值
        U1["/maestro-execute 1"] --> Cmd1["执行<br/>无额外参数"]
    end

    subgraph 配置了默认值
        U2["/maestro-execute 1"] --> Hook2["config-merger Hook"]
        Hook2 -->|读取 config| Merge["合并默认参数"]
        Merge --> Cmd2["/maestro-execute 1<br/>--auto-commit --method auto -y"]
    end

    style Hook2 fill:#fce4ec

本质上：默认值就是一组 LLM 在执行命令前自动叠加的参数，由 Hook 完成合并，你完全感知不到。

5.2. 配置作用域

flowchart TB
    Cfg["maestro config set"] --> Q{"作用域?"}
    Q -->|加 -g| Global["全局配置<br/>~/.maestro/config.json<br/>所有项目生效"]
    Q -->|不加 -g| Project["项目配置<br/>.workflow/config.json<br/>仅当前项目"]

    Global --> Order["优先级合并"]
    Project --> Order
    CLI["命令行手写参数"] --> Order

    Order --> Final["最终参数<br/>命令行 > 项目 > 全局"]

    style CLI fill:#c8e6c9
    style Project fill:#bbdefb
    style Global fill:#e1bee7

5.3. 设置一次，永久生效

1
2
3
4
5
6
7
8
9
10
# 让 execute 每次都自动提交代码、自动选择执行方式
maestro config set maestro-execute auto-commit true -g
maestro config set maestro-execute method auto -g
maestro config set maestro-execute y true -g

# 让代码审查默认用深度模式
maestro config set quality-review level deep -g

# 让 analyze 默认自动确认
maestro config set maestro-analyze y true -g

5.4. TUI 可视化配置

1
maestro config

打开后是一个终端界面，列出所有 51 个命令。操作方式：

journey
    title TUI 配置体验
    section 进入界面
      maestro config: 5: 你
      看到命令列表: 4: 你
    section 选择命令
      方向键定位: 5: 你
      Enter 进入编辑: 5: 你
    section 修改参数
      空格切换 boolean: 5: 你
      空格循环枚举: 4: 你
    section 保存
      g 保存全局: 5: 你
      p 保存项目: 5: 你

5.5. 三种工作模式预设

1
2
3
4
maestro config set maestro-execute auto-commit true -g
maestro config set maestro-execute y true -g
maestro config set maestro-execute method auto -g
maestro config set maestro-analyze y true -g

适合：信任 AI 全流程，减少手动确认。

1
2
maestro config set quality-review level deep -g
maestro config set maestro-plan auto true -g

适合：发布前使用，保证代码质量。

1
2
3
maestro config set maestro-execute y true -g
maestro config set maestro-plan auto true -g
maestro config set maestro-analyze c true -g

适合：快速出结果，减少一切确认。

5.6. 查看与重置

1
2
3
4
5
6
7
8
9
# 查看
maestro config show
maestro config show maestro-execute

# 取消单个默认值
maestro config unset maestro-execute method -g

# 清空命令的全部默认配置
maestro config reset maestro-execute -g

5.7. 本节小结

要点何时使用关键动作
设置一个默认参数某个参数几乎每次都要加maestro config set <命令> <参数> <值> -g
可视化配置不想记命令maestro config 打开 TUI
查看已有配置确认设置是否生效maestro config show
临时覆盖默认值某次需要不同参数命令行手写优先级最高

本篇总结

五大场景的全景图

mindmap
  root(("Maestro 日常五场景"))
    Spec 系统
      录入一次永久生效
      Hooks 自动注入
      六大分类
      LLM 自动遵守
    Issue 系统
      与 Phase 并行
      八角度自动扫描
      状态机驱动
      LLM 自动串联修复
    Quality 验收
      业务规则测试
      代码执行测试
      覆盖率盲区
      失败自动 debug
    Delegate 异步
      不阻塞主会话
      模型路由
      任务串联
      消息注入
    Config 默认值
      Hook 自动合并
      全局 vs 项目
      TUI 可视化
      工作模式预设

用户视角 vs LLM 视角对照

flowchart LR
    subgraph 用户视角["👤 用户视角"]
        UV1["spec-add 一次"]
        UV2["maestro-quick 修 bug"]
        UV3["验收一下"]
        UV4["让 Gemini 跑一下"]
    end

    subgraph LLM视角["🧠 LLM 视角"]
        LV1["Hook 注入<br/>每次 Agent 启动"]
        LV2["analyze→plan→execute<br/>自动串联"]
        LV3["business-test→test→<br/>review→test-gen"]
        LV4["delegate→message→<br/>after_complete→output"]
    end

    UV1 -.触发.-> LV1
    UV2 -.触发.-> LV2
    UV3 -.触发.-> LV3
    UV4 -.触发.-> LV4

    style 用户视角 fill:#e1f5ff
    style LLM视角 fill:#fff4e1
要点何时使用关键动作
录入项目规范发现需要约束某个写法时/spec-add coding "规范内容"
扫描发现问题阶段性代码质量检查时/manage-issue-discover
修复一个 bug问题明确、改动小时/maestro-quick "修复描述"
完整 Issue 修复流程需要深度分析时LLM 自动串联 analyze --gaps → plan --gaps → execute → close
业务规则验收execute 完成后/quality-business-test N
测试失败修复任何测试报错时LLM 自动串联 quality-debug → plan --gaps → execute → re-run
异步委托任务不想等、让别的 AI 跑maestro delegate "..." --to gemini --async
设置命令默认参数某参数每次都要手打maestro config set <命令> <参数> <值> -g

本篇速查卡

我想做什么用这个命令用户敲 / LLM 敲
扫描代码库自动生成规范/spec-setup👤 + 🧠（LLM 自动批量调 spec-add）
录入一条编码规范/spec-add coding "规范内容"👤
录入一条踩坑记录/spec-add learning "经验教训"👤
检索和认证相关的规范/spec-load --keyword auth👤（少数情况）
让 AI 主动找代码问题/manage-issue-discover👤
手动记录一个 bug/manage-issue create --title "..." --severity high👤
分析一个 Issue 的根因/maestro-analyze --gaps ISS-001🧠 自动
生成 Issue 修复计划/maestro-plan --gaps🧠 自动
关闭一个 Issue/manage-issue close ISS-001👤
快速修一个小 bug/maestro-quick "修复描述"👤
验收业务规则/quality-business-test N🧠 自动
验收代码执行/quality-test N🧠 自动
补充测试覆盖率/quality-test-gen N🧠 自动
做代码审查/quality-review N --level deep🧠 自动
测试失败找根因/quality-debug --from-business-test N🧠 自动
只重跑失败的测试/quality-business-test N --re-run🧠 自动
异步委托任务给 Geminimaestro delegate "..." --to gemini --async👤
查看委托任务状态maestro delegate status <id>👤 / 🧠
取回委托任务结果maestro delegate output <id>🧠 自动（Hook 通知后）
串联后续任务maestro delegate message <id> "..." --delivery after_complete👤
打开参数配置 TUImaestro config👤
设置命令默认参数maestro config set <命令> <参数> <值> -g👤

写在最后：你应该把哪些命令记在脑子里？

读完两篇你会发现，Maestro 的命令多达 50+，但你需要记的不超过 8 个：

mindmap
  root(("你只需要记住这 8 个"))
    初始化与启动
      /maestro-init
      /maestro -y "需求"
    日常开发
      /maestro-quick "小任务"
      /spec-add coding "规范"
    问题管理
      /manage-issue-discover
      /manage-issue create
    委托与配置
      maestro delegate --to gemini
      maestro config

剩下的 40+ 个命令，全都交给 LLM 自己去拼。 这就是 Maestro 真正的设计哲学。