Amp Maestro 实战指南

Posted on Mar 1, 2026

写在前面：本指南旨在通过 30 分钟的实战，带您从零开始开发一个 Todo CLI 工具。

快速开始

环境准备

工欲善其事，必先利其器。请确认您的开发环境：

# 必备工具
git --version          # 版本管理
node --version         # 建议 LTS 版本
npm --version          # 包管理
amp --version          # 核心工具
bd --version           # 任务管理

提示：如果是新环境，可以直接运行根目录的 install.sh 脚本一键安装依赖。

创建第一个任务

假设我们需要为项目添加一个 Todo CLI 工具。首先，我们从创建一个任务单元（Bead）开始：

amp
/bd-create

1. 交互式提问： 系统会像资深技术主管一样询问关键信息：

  • Description: “What is this task/issue about?”
  • Type: bug / feature / task / epic
  • Priority: 0 (critical) - 4 (backlog)
  • Dependencies: 是否依赖其他任务？

2. 确认执行： 在你回答完（如 “开发 Todo CLI 工具”）后，系统会生成具体的 bd create 命令并请求确认。

注意：如果是首次运行且未初始化数据库，系统会提示 Error: no beads database found。 此时只需同意系统的修复建议（运行 bd init），它会自动初始化并重试创建命令。

3. 生成结果： 成功后，你会看到类似这样的表格输出：

+-------+------------------------+
| 字段   | 值                     |
+-------+------------------------+
| ID    | amp_todo-7qn           |
| 标题   | 开发 Todo CLI 工具       |
| 类型   | feature                |
| 优先级 | 1 (高)                 |
| 状态   | open                   |
+-------+------------------------+

紧接着，系统会提示后续操作：

现在可以运行：
/context amp_todo-7qn - 加载任务上下文
/research amp_todo-7qn - 研究现有实现
/plan amp_todo-7qn - 制定开发计划
/implement amp_todo-7qn - 开始开发

4. 补充细节（Refinement）：

如果在创建时描述不够详细，或者有了新的想法，直接告诉 AI，它会帮你更新 Bead：

User: 关键要素：

System: $ bd update amp_todo-7qn --description="..."Updated bead: amp_todo-7qn最佳实践：Bead ID 是任务的唯一标识。在团队协作中，明确的 Bead 能有效避免工作冲突。

实战演练

我们将通过开发一个待办事项 CLI 工具来完整体验 Amp Maestro 工作流。

Idea：需求管理

1.1 明确需求

在编码之前，我们首先需要将想法转化为具体的任务单元（Bead）：

/bd-create

关键要素：

  • 目标：开发支持增删改查的 Todo CLI。
  • 存储：本地 JSON 文件（MVP 阶段方案）。
  • 验收标准：

生成的 Bead 结构：

{
  "id": "bd-todo-001",
  "title": "Implement todo CLI tool with basic CRUD operations",
  // ... 其他字段
  "acceptance": [
    "User can add new todos...",
    "User can list all todos...",
    // ...
  ]
}

经验：验收标准（Acceptance Criteria）是开发的"北极星"。定义得越清晰，后续的测试和审查就越高效。

1.2 领取任务

/bd-next

系统会将 bd-todo-001 分配给您，标志着工作的正式开始。

Setup：环境隔离

2.1 创建独立工作区

为了保证主分支的稳定性，我们使用 Worktree 进行环境隔离：

/branchlet-from-bead bd-todo-001

执行结果：

✓ Created worktree: /path/to/project/worktrees/bd-todo-001
✓ Switched to branch: feature/todo-cli-tool

原理：Branchlet 基于 Git Worktree，允许您在独立目录中开发功能，互不干扰。这比传统的单纯分支切换更安全、高效。

2.2 加载上下文

 /context bd-todo-001

此命令会执行以下操作：

  1. 加载 Bead 信息：自动运行 bd show ... --json 获取任务详情。
  2. 扫描项目结构：检查 package.json、tsconfig.json 等关键文件。
  3. 生成上下文报告：

输出示例：

✓ Thinking ▶
✓ Read
✓ Glob **/*.json
✓ Glob **/*.ts

🎯 Context: amp_todo-7qn

开发 Todo CLI 工具 | feature | Priority: 1

任务描述
开发支持增删改查的 Todo CLI...

验收标准：
• ✅ 支持添加任务 `todo add`
• ✅ 支持查看列表 `todo list`
...

项目状态
现状：空白项目（无 package.json、无源码）

需要做的：
1. 初始化项目结构
2. 实现 CLI 框架
...

下一步
执行以下命令之一：
• /research amp_todo-7qn - 研究最佳实践
• /plan amp_todo-7qn     - 制定详细计划
• /implement amp_todo-7qn - 开始实现

Research：深度研究

3.1 构建知识库（新项目建议）

如果是首次接手项目，建议先构建知识库：

/kb-build

系统会扫描项目架构、设计模式和代码约定，生成 .beads/kb/ 知识库。这是 AI 理解项目的基石。

3.2 生成规格说明 (可选)

对于复杂需求，建议先生成详细规格书：

/spec bd-todo-001

这将生成 spec.md，帮助挖掘隐性需求和边界条件。

3.3 执行深度研究

这是关键的一步：

 /research bd-todo-001

AI 将深度分析代码库、查找相关文档甚至进行联网搜索，寻找最佳实现方案。

输出示例：

✓ Thinking ▶
✓ Read AGENTIC_WORKFLOW.md
✓ Web Search Compare Node.js CLI frameworks...
✓ Web Search Best practices for handling JSON file storage...

📄 Research Complete: amp_todo-7qn

已完成 Todo CLI 工具的深度研究，生成 research.md 文档。

核心发现

CLI 框架：推荐 commander.js
• 2.13 亿周下载，产销环境验证
• 零依赖，TypeScript 友好

存储方案：fs.promises + JSON
• 使用现代异步 API (async/await)
• 原子写入防止数据丢失

数据结构：
{
  "tasks": [
    { "id": "timestamp", "text": "task", "completed": false }
  ]
}

已识别风险
1. 并发写入 → 实现操作队列化
2. 大文件性能 → MVP 不考虑，后期迁移数据库

下一步
运行 /plan amp_todo-7qn 制定实现计划。

核心原则：Research 的目的是"模式发现"（Pattern Discovery）。遵循现有模式不仅能保持代码一致性，还能显著降低 Code Review 的阻力。

Plan：架构规划

4.1 架构对齐

在编码前，Amp 会通过架构访谈确认设计思路：

 /plan bd-todo-001

系统会基于 Research 结果，自动生成详细的实施计划。

输出示例：

✓ Thinking ▶
✓ Create .beads/artifacts/amp_todo-7qn/plan.md +410
...

✅ Plan Complete: amp_todo-7qn

详细实现计划已生成到 plan.md。

架构决策
• CLI 框架：commander.js
• 存储：JSON + fs.promises (原子写入)
• 语言：TypeScript (strict mode)

4 个命令实现
+---------------------+----------------+----------+
| 命令                | 逻辑           | 估计时间 |
+---------------------+----------------+----------+
| todo add <text>     | 读→追加→写     | 15 min   |
| todo list           | 读→格式化→输出 | 15 min   |
| todo complete <id>  | 读→更新→写     | 15 min   |
| todo delete <id>    | 读→过滤→写     | 15 min   |
+---------------------+----------------+----------+

工作量评估
• 存储层：45 min
• 4 个命令：60 min
• CLI 集成：30 min
• 测试：45 min
• 总计：4-5 小时 （Atomic, 无需拆分）

验收标准
✓ 编译通过 (npm run build)
✓ 所有测试通过 (npm run test)
✓ Lint 通过 (npm run lint)
✓ 4 个命令功能完整
✓ 数据持久化

下一步： /implement amp_todo-7qn 开始开发

提示：Plan 中定义的测试命令（如 test:unit）就是后续质量门禁的标准。

4.2 任务拆分 (可选)

如果 Oracle 分析发现任务过于复杂（如涉及大量文件变更），会建议拆分：

/split bd-todo-001

这将把复杂的 Bead 拆解为多个可管理的原子任务（Child Beads），便于并行开发。

4.3 生成实施计划

确认无误后，系统生成 plan.md，包含：

  • Context: 任务背景
  • Steps: 详细实施步骤
  • Tests: 验证方案

Code：实现与验证

5.1 交互式编程

准备就绪后，开始编码：

/implement amp_todo-7qn

您将体验类似 Driver/Navigator 的结对编程流程：

  1. 提案：系统建议创建目录结构。