常见工作流

本章介绍 AggRoot 日常使用中最常见的工作流，每个工作流都包含分步操作和实用技巧。

探索新项目

当你拿到一个陌生的代码库时，AggRoot 可以快速帮你建立全局理解。

步骤

获取项目结构 — 使用 DirectoryTree 快速浏览目录树：
```
请用 DirectoryTree 列出项目结构，深度为 3 层
```

并行探索关键目录 — 启动多个 explore 子代理分别探索不同模块：

请并行启动 3 个 explore 子代理，分别探索：
- src/domain/ — 领域层核心逻辑
- src/plugins/ — 插件实现
- src/infrastructure/ — 基础设施层

阅读入口文件 — 读取 AGGROOT.md、README.md、package.json 了解项目元信息：
```
读取 AGGROOT.md 和 package.json，总结项目的核心架构和依赖
```
梳理关键模块 — 针对感兴趣的模块，使用 CodeAnalyze 分析符号和依赖：
```
对 src/domain/agent/ 执行 CodeAnalyze，列出所有导出符号
```

Tips: 先用 DirectoryTree 获取全局视图，再针对性深入。避免一上来就读大量文件浪费 Token。子代理返回的结果可以直接信任，无需重复读取。

修复 Bug

步骤

分享错误信息 — 将完整的错误堆栈粘贴给 AggRoot：

我遇到了这个错误，请帮我排查：
TypeError: Cannot read properties of undefined (reading 'config')
    at AgentAggregate.connect (src/domain/agent/aggregate.ts:45:32)

定位根因 — 使用 /debug 技能或手动搜索：
```
/debug TypeError: Cannot read properties of undefined (reading 'config')
```
AggRoot 会自动搜索相关代码、分析调用链，找到问题根源。

应用修复 — 使用 Edit 工具精确修改问题代码：

在 aggregate.ts 第 45 行添加空值检查，确保 config 存在后再访问

验证修复 — 运行测试确认修复有效：

运行相关测试验证修复是否生效：npm run test:run -- tests/domain/agent/

Tips: 提供完整的错误信息（包括堆栈追踪）比只描述"报错了"效率高得多。如果错误难以复现，可以请求 AggRoot 帮你编写最小复现代码。

重构代码

步骤

识别遗留代码 — 使用 CodeAnalyze 找出复杂度高、重复度大的代码：
```
分析 src/plugins/core-tools/ 的代码复杂度和重复模式
```

制定重构计划 — 进入 Plan Mode 规划重构步骤：

进入计划模式，为 core-tools 插件制定重构方案：
1. 提取公共基类
2. 消除重复逻辑
3. 改善命名

逐步应用变更 — 使用 Edit 工具逐步修改，每次改动保持小范围：
```
按照重构计划第一步，提取公共方法到 base-tool.ts
```
运行测试 — 每完成一个重构步骤后运行测试：
```
运行测试确保重构未破坏功能：npm run test:run
```

Tips: 重构时优先保持小步前进，每步修改后立即测试。使用 GitStash 在重大变更前保存当前状态。AggRoot 的 CodeRefactor 工具支持提取函数、重命名等常见重构操作。

编写测试

步骤

识别未测试代码 — 使用 Glob + Grep 找到缺少对应测试的源文件：
```
找出 src/domain/ 下所有 .ts 文件中没有对应测试文件的
```
生成测试脚手架 — 使用 /test 技能快速生成测试框架：
```
/test src/domain/agent/aggregate.ts --framework vitest
```

补充边界用例 — 手动补充边界条件和错误处理场景：

为 aggregate.ts 的测试补充以下边界用例：
- 空输入
- 并发访问
- 超大文件

运行并验证 — 执行测试并确保全部通过：

运行 vitest 测试，检查覆盖率：npm run test:coverage

Tips: /test 技能会生成遵循 AAA 模式（Arrange-Act-Assert）的测试模板。对于复杂逻辑，优先测试 Happy Path，再逐步补充边界用例。

创建 PR

步骤

总结变更 — 查看当前工作区的变更摘要：
```
用 GitStatus 和 GitDiff 总结当前所有变更
```
生成提交信息 — 使用 /commit 技能自动生成规范的提交信息：
```
/commit
```
提交代码 — 确认提交信息后完成提交：
```
确认提交，并推送到远程 feature 分支
```

创建 Pull Request — 使用 Shell 工具通过 gh CLI 创建 PR：

使用 gh pr create 创建 PR，标题和描述基于变更总结

Tips: /commit 技能会自动分析 diff 生成符合 Conventional Commits 规范的提交信息。提交前确保所有测试通过（npm run test:run）。

编写文档

步骤

发现未文档化代码 — 搜索缺少注释的公共 API：

搜索 src/domain/ 下所有 export 的函数和类，找出缺少 JSDoc 注释的

生成文档 — 使用 /document 技能自动生成文档：
```
/document src/domain/agent/aggregate.ts --format tsdoc
```

审阅结果 — 检查生成的文档是否准确、完整：

审阅刚才生成的文档，确保参数描述和返回值与实际代码一致

Tips: /document 支持 jsdoc、tsdoc、markdown 三种格式。生成后务必人工审阅，AI 可能对业务逻辑理解不够深入。

并行探索

当需要同时了解多个不相关的模块时，可以并行启动探索任务。

步骤

使用 Git Worktree — 在不同目录创建工作树：
```
git worktree add ../aggroot-feature feature/new-feature
```
然后在两个终端窗口分别运行 AggRoot，互不干扰。

多终端会话 — 启动多个 AggRoot 实例：

# 终端 1 — 探索前端代码
aggroot --model deepseek-v4-flash

# 终端 2 — 探索后端代码
aggroot --model glm-5.2

子代理并行 — 在同一会话中启动多个 explore 子代理：

并行启动以下子代理任务：
- explore: 分析 src/plugins/core-tools/ 的工具定义
- explore: 分析 src/infrastructure/mcp/ 的连接管理
- explore: 分析 src/domain/skill/ 的技能注册机制

Tips: 子代理的结果会直接汇总到主对话中，无需手动整合。Git Worktree 适合需要并行修改代码的场景。

委托子代理

子代理是 AggRoot 的核心能力之一，适合将探索性任务委托出去，保持主对话上下文干净。

步骤

识别可委托的任务 — 以下任务适合委托给子代理：
- 探索代码库结构（explore 代理）
- 制定执行计划（plan 代理）
- 审查代码质量（code-reviewer 代理）

启动子代理 — 使用自然语言描述任务：

使用 explore 子代理找出 src/plugins/ 下所有插件的注册入口

信任子代理结果 — 子代理返回的结果包含"Files Accessed by Subagent"列表，主代理不会重复读取这些文件。
保持主上下文干净 — 只将子代理的结论引入主对话，避免引入大量中间细节。

Tips: explore 代理快速且轻量，适合快速了解代码结构。plan 代理会生成详细的执行计划，适合复杂任务。code-reviewer 代理会进行专业的代码审查，给出改进建议。

常见工作流速查表

工作流	关键步骤	常用工具/技能
探索新项目	DirectoryTree → 并行 explore → CodeAnalyze	DirectoryTree, explore, CodeAnalyze
修复 Bug	分享错误 → /debug → Edit → 测试	/debug, Edit, Shell
重构代码	识别遗留 → Plan Mode → Edit → 测试	CodeAnalyze, EnterPlanMode, Edit
编写测试	找未测试代码 → /test → 补充用例 → 验证	/test, Grep, Shell
创建 PR	GitDiff → /commit → 推送 → gh pr create	/commit, GitTools, Shell
编写文档	找未文档化代码 → /document → 审阅	/document, Grep
并行探索	Worktree 或多终端	GitWorktree, explore
委托子代理	识别任务 → 启动代理 → 信任结果	explore, plan, code-reviewer

← 上一篇

网络工具

最佳实践