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

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

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

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

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

这段话你可能已经复制粘贴了几十次了。而且就算粘贴了，AI 在对话后期写代码时还是可能「忘记」，写出和项目风格不一致的东西。

Maestro 的 Spec 系统解决的就是这个问题。你只需要把这些规范录入一次，之后每次 AI 启动，Hooks 会自动把对应的规范注入到 AI 的上下文里。从此不用再手动粘贴，AI 自然知道该遵守什么约定。

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

在 Claude Code 里运行：

1

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

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

你可以根据规范的性质选择不同的分类：

举几个实际的例子：

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

# 编码规范
/spec-add coding "所有 API 路由统一使用 Hono 框架，不允许混用 Express"
/spec-add coding "禁止使用 TypeScript 的 any 类型，必须明确声明类型"
/spec-add coding "数据库操作统一使用 Drizzle ORM，禁止裸写 SQL 字符串"

# 架构约束
/spec-add arch "通知模块使用事件驱动架构，不允许直接调用通知服务"
/spec-add arch "所有外部 API 调用必须通过 services/ 目录下的封装，禁止在 controller 里直接 fetch"

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

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

录入完成后，Maestro 会输出一条确认信息，告诉你规范被写入了哪个文件，以及提取到了哪些关键词：

1
2
3
4
5

== spec-add 完成 ==
分类：coding
写入：.workflow/specs/coding-conventions.md
关键词：hono, api-routing, framework
验证：maestro spec load --keyword hono

1.3. 什么时候会自动生效

你不需要手动操作，Hooks 会处理注入时机。

每次你在 Claude Code 里触发一个 Agent（也就是让 AI 开始写代码或做分析时），spec-injector 这个 Hook 会在 Agent 启动的瞬间，根据当前 Agent 的类型，自动把对应分类的规范塞进它的 prompt 里。

比如驱动一个写代码的 Agent，它会拿到 coding 分类的规范；驱动一个专门做测试的 Agent，它会同时拿到 coding 和 test 分类的规范。这个匹配是自动的，你完全感知不到，但 AI 写出来的代码会天然地遵守你录入的规范。

1.4. 初次使用：让 AI 扫描代码库自动生成规范

如果你是把 Maestro 接入一个已有的项目，不想一条一条手动录入，可以让 Maestro 扫描你的代码库，自动识别技术栈和编码模式，生成初始规范文件：

1

/spec-setup

它会分析你项目里用了哪些框架、有没有 linter 配置、有没有测试框架，然后生成对应的 spec 文件。生成的内容可以直接用，也可以之后手动补充细节。

对于新项目，直接从 /spec-add 开始录入就好，不需要先跑 /spec-setup。

1.5. 按需检索规范

除了自动注入，你也可以手动检索规范内容，把它粘贴进当前对话：

1
2
3
4
5
6
7
8

# 把所有编码规范加载进来
/spec-load --category coding

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

# 组合使用：在编码规范里找和命名有关的条目
/spec-load --category coding --keyword naming

适合在需要 AI 参考完整规范背景时手动触发，比如做代码审查之前，或者开始一个涉及核心架构的新功能之前。

1.6. 本节小结

完成第一章后，你的项目已经有了一套持久化的规范库，AI 写代码时会自动遵守这些约定，不再需要每次对话都重新粘贴。

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

上一章讲的是如何让 AI 记住项目规范，避免写出风格不一致的代码。这一章换一个角度——当代码已经写出来了，怎么系统地发现其中的问题，然后有条不紊地修复它们。

Maestro 的 Issue 系统是一套独立的问题追踪机制，可以和主干流程并行运行。你在推进 Phase 的同时，发现问题就创建 Issue，修复完就关闭，两条线互不干扰。

2.1. 让 AI 主动帮你找问题

与其等到出了 bug 再去排查，不如定期让 AI 主动扫一遍。Maestro 提供了一个命令，从八个角度对你的代码库做一次全面的问题扫描：

1

/manage-issue-discover

这八个角度分别是：安全漏洞、性能问题、可靠性、可维护性、可扩展性、用户体验、可访问性、合规性。每个角度都会产出一批发现，去重之后自动写入 Issue 列表。

如果你不想全部扫，只想针对某个具体的关注点，可以用定向发现：

1

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

扫描完成后，Maestro 会列出所有发现的问题，每个问题带有严重程度（critical / high / medium / low）。

2.2. 手动记录一个问题

发现 bug 或者想法，不需要等扫描，直接记录：

1

/manage-issue create --title "登录接口在并发请求下偶发 500" --severity high

--severity 可以是 critical、high、medium、low，影响后续修复的优先级排序。

创建成功后会得到一个 Issue ID，比如 ISS-001，后续操作都用这个 ID 来引用。

查看当前所有未解决的问题：

1

/manage-issue list --status open --severity high

2.3. 分析 + 修复 + 关闭：标准四步走

有了 Issue 之后，修复流程分四步：

步骤 1：让 Maestro 分析根因

1

/maestro-analyze --gaps ISS-001

Maestro 会读取这个 Issue 的描述，然后深入代码库找根因——是哪段代码有问题、影响范围有多大、可能的修复方向是什么。分析完后 Issue 状态变成 diagnosed（已诊断）。

步骤 2：生成修复计划

1

/maestro-plan --gaps

基于诊断结果，生成具体的修复任务清单，和主干流程的 plan 格式完全一样。Issue 状态变成 planned（已规划）。

步骤 3：执行修复

1

/maestro-execute

按照修复计划写代码，执行完成后 Issue 状态自动变成 resolved（已解决）。

步骤 4：关闭 Issue

确认修复生效后，手动关闭：

1

/manage-issue close ISS-001 --resolution "已修复，根因是并发场景下 Redis 锁未正确释放，commit: abc123"

--resolution 里记录修复说明，方便以后回溯。

2.4. 快速修一个小 bug

如果问题很明确、很简单，不需要走上面的四步流程，直接用最短路径：

1

/maestro-quick "修复登录页在 iPhone SE 上的样式错乱，底部按钮被键盘遮住"

/maestro-quick 跳过分析和规划，直接让 AI 理解问题然后开始修。适合界面小问题、配置错误、单文件的 bug 修复这类范围明确的任务。

2.5. 本节小结

Issue 系统和主干 Phase 管线是两条并行的轨道。推进功能开发走 Phase 流程，发现和修复问题走 Issue 流程，两者不相互阻塞。

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

代码执行完了，不等于功能做好了。验收这件事，Maestro 把它拆成三个不同角度的测试，每个角度回答不同的问题。理解这三者的分工，才能知道该跑哪个、跑完看什么。

3.1. 三种测试各管什么

1

/quality-business-test 1

1

/quality-test 1

1

/quality-test-gen 1

三个测试不是非此即彼，而是互补的。日常开发建议至少跑前两个，发布前把三个都跑一遍。

3.2. 测试失败了怎么办

测试跑出来有问题，不要慌，Maestro 提供了标准的修复流程。

如果是业务测试失败，先诊断根因：

1

/quality-debug --from-business-test 1

这个命令会读取业务测试的失败报告，用假设驱动的方式找出是哪段代码没有正确实现业务规则，输出一份诊断报告，里面会写清楚问题在哪、影响什么、建议怎么修。

然后生成修复计划并执行：

1
2
3

/maestro-plan 1 --gaps     # 基于诊断结果生成修复任务
/maestro-execute 1          # 执行修复
/quality-business-test 1 --re-run  # 只重跑之前失败的场景，不用全部重跑

--re-run 参数很实用，它只跑上次失败的测试场景，不重复跑已经通过的部分，节省时间。

如果是代码执行测试失败，流程类似：

1
2
3
4

/quality-debug --from-uat 1       # 诊断代码层面的失败原因
/maestro-plan 1 --gaps
/maestro-execute 1
/quality-test 1                   # 重跑完整测试确认修复

3.3. 代码审查

测试关注的是「功能对不对」，代码审查关注的是「代码写得好不好」。两件事都重要，只是时机不同。

1

/quality-review 1

默认是 standard 级别的审查，覆盖代码风格、潜在 bug、安全问题、性能隐患等常见维度。

如果只是想快速扫一眼有没有明显问题：

1

/quality-review 1 --level quick

如果是核心模块、发布前的严格审查：

1

/quality-review 1 --level deep

审查发现的 critical 或 high 级别问题，Maestro 会自动创建对应的 Issue，你可以用上一章的 Issue 流程来追踪和修复它们。

3.4. 推荐的验收顺序

把上面几个命令串起来，这是一个稳妥的验收顺序：

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

# Phase 1 执行完之后

/quality-business-test 1       # 先验业务规则
/quality-test 1                # 再验代码执行
/quality-review 1              # 做代码审查
/quality-test-gen 1            # 补充测试覆盖（可选，发布前建议跑）

# 如果有测试失败
/quality-debug --from-business-test 1
/maestro-plan 1 --gaps
/maestro-execute 1
/quality-business-test 1 --re-run

3.5. 本节小结

三种测试命令从不同角度保障代码质量，互相补充而不是替代。测试失败时有固定的修复流程，不用自己摸索。

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

前三章讲的都是在 Claude Code 里直接操作的场景。这一章介绍一个不同的思路——把任务异步地委托给另一个 AI 引擎（Gemini、Codex 等）去跑，你自己继续干别的，等它出结果再来取。

4.1. 为什么要委托给其他 AI

最直接的理由是不阻塞。

假设你让 Claude 分析整个代码库的安全漏洞，这个任务可能要跑十几分钟，在这段时间里你只能等着，什么都干不了。

如果改用 Delegate 模式，你把这个任务甩给 Gemini 异步跑，自己继续在 Claude Code 里写别的功能。等 Gemini 跑完，系统会通知你，你再去取结果。两件事并行完成，效率翻倍。

第二个理由是让合适的模型做合适的事。不同 AI 模型各有所长，Gemini 擅长大上下文的代码分析，Codex 适合精确的代码实现，你可以根据任务特点选择最合适的工具。

4.2. 委托一个任务，拿回结果

第一步：发出委托

1

maestro delegate "分析 src/auth/ 目录下所有接口的安全漏洞，重点关注 SQL 注入和权限校验" --to gemini --async

--to gemini 指定由 Gemini 来执行，--async 表示异步运行，命令会立刻返回一个执行 ID，比如 gem-143022-a7f2。

第二步：去做其他事情

这段时间你完全可以继续用 Claude Code 开发其他功能，不受影响。

第三步：收到通知，取回结果

Delegate 任务完成后会通过 Hook 通知你。你也可以主动查状态：

1

maestro delegate status gem-143022-a7f2

确认任务已完成（completed）后，取回完整结果：

1

maestro delegate output gem-143022-a7f2

4.3. 串联两个任务：分析完自动触发修复

一个更进阶的用法是任务链——让 Gemini 分析完漏洞之后，自动触发 Claude 去修复它们，全程不需要你手动接力。

1
2
3
4
5
6

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

# 第二步：排队一个后续任务，等分析完自动执行
maestro delegate message gem-143022-a7f2 "分析完成后，修复所有 critical 和 high 级别的漏洞" --delivery after_complete

--delivery after_complete 的意思是：把这条消息排队，等 gem-143022-a7f2 这个任务完成之后，自动用它的输出结果作为上下文，启动修复任务。

你完全不需要守在旁边等，两个任务会自动串联起来执行。

4.4. 如果任务跑偏了，中途补充上下文

任务已经在跑了，但你突然想到还有一些额外的信息要补充：

1

maestro delegate message gem-143022-a7f2 "另外也检查一下 src/utils/sanitize.ts，这个文件之前有过 XSS 问题"

这条消息会被注入到正在运行的任务里，Gemini 会把这个补充信息纳入分析范围。

如果任务跑错了方向，直接取消：

1

maestro delegate cancel gem-143022-a7f2

4.5. 支持的 AI 工具

Delegate 支持的 AI 工具取决于你本地安装了哪些，通过 --to 参数指定：

如果不确定用哪个，可以不指定 --to，Maestro 会自动选择你本地第一个可用的工具。

4.6. 本节小结

Delegate 的核心价值是「不阻塞」——把耗时任务甩出去，自己继续干活，结果出来了再取。任务链（after_complete）则让多步骤的工作流完全自动化。

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

用了一段时间 Maestro 之后，你会发现有些参数几乎每次都要加，比如 /maestro-execute 后面总是要带 --auto-commit，/quality-review 总是要带 --level deep。每次手打很烦，忘了还会漏掉。

Maestro 的 Skill 默认值配置就是解决这个问题的——你设置一次，以后调用这个命令就自动带上这些参数。

5.1. 设置一次，永久生效

在终端里运行：

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

-g 表示全局生效，对所有项目都有效。不加 -g 则只对当前项目生效。

设置完之后，你再调用 /maestro-execute 1，Maestro 会自动在后台把配置的默认参数加上，等同于你手打了 /maestro-execute 1 --auto-commit --method auto -y。

如果某次你想临时覆盖默认值，直接在命令里手动写参数就行，手动写的参数优先级更高，默认值会自动让位。

5.2. 用可视化界面来配置

如果不喜欢记命令，可以打开 TUI 界面来配置：

1

maestro config

这会打开一个终端界面，列出所有 51 个命令，显示每个命令当前配置了哪些默认参数。用方向键选中一个命令，按 Enter 进入编辑，用空格切换 boolean 参数的开关，对于枚举参数（比如 method 支持 agent/codex/gemini/cli/auto）空格会循环切换选项。

保存时会问你是存到全局还是项目级，按 g 全局，按 p 项目级。

5.3. 查看当前配置了什么

1
2
3
4
5

# 看所有已配置的命令和参数
maestro config show

# 看某个具体命令的配置
maestro config show maestro-execute

5.4. 取消某个默认值

1
2
3
4
5

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

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

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

严格审查模式（发布前使用，保证代码质量）：

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. 本节小结

默认值配置是一个小功能，但积累下来节省的手打时间不少，更重要的是不会因为「忘了加 --auto-commit」而出错。

本篇总结

这一篇覆盖了日常开发里最常用的五个场景，每个场景都有独立的命令体系，互相配合又各自独立。

Spec 系统解决的是「规范只说一次，永久生效」的问题，把编码约定和踩坑记录沉淀下来，AI 下次写代码自然遵守。Issue 系统解决的是「问题从发现到关闭有人跟」的问题，既能让 AI 主动找问题，也能手动记录和追踪。验收测试三个维度各管各的，业务规则、代码执行、覆盖率一个都不落。Delegate 让耗时任务不再阻塞你的工作节奏，还能串联成自动化的任务链。最后的默认值配置虽然是小功能，但用久了会发现是降低使用摩擦最有效的方式之一。

本篇速查卡