最佳实践
本章汇总使用 AggRoot 的最佳实践和技巧，帮助你更高效地完成日常工作。
提示词技巧
具体明确
模糊的提示词会导致模糊的结果。尽量提供具体信息：
| 不推荐 | 推荐 |
|---|---|
| "改一下那个文件" | "修改 src/config.ts 第 23 行的超时值为 60000" |
| "帮我看看代码" | "分析 src/domain/agent/aggregate.ts 的依赖关系" |
| "优化一下" | "重构 src/plugins/core-tools/implementations/ 中的重复代码" |
指定文件路径
始终提供完整的文件路径，让 AggRoot 精确定位：
请读取 src/domain/mcp/connection-manager.ts，分析重连逻辑的实现
分步处理复杂任务
将大任务拆分为多个小步骤：
请分步完成以下任务：
1. 先读取 src/plugins/ 下所有插件的 index.ts
2. 列出每个插件注册的工具
3. 找出哪些工具缺少风险等级标记
提供上下文
提供足够的背景信息让 AggRoot 理解你的意图：
我们正在将项目从 CommonJS 迁移到 ES Modules。
请检查 src/infrastructure/ 下的所有文件，
找出使用 require() 的地方并替换为 import。
Tips: 好的提示词 = 明确目标 + 具体路径 + 预期结果。如果第一次结果不理想，可以补充信息让 AggRoot 调整方向。
上下文管理
先用 DirectoryTree 建立全局视图
在深入探索之前，先获取项目结构：
请用 DirectoryTree 列出项目目录，排除 node_modules 和 dist，深度为 3
这比直接读取大量文件更节省 Token。
避免重复搜索
如果子代理已经探索了某个目录，其结果会包含"Files Accessed by Subagent"列表。主代理不会重复读取这些文件，你也无需再次请求。
善用 AGGROOT.md
AGGROOT.md 是项目级别的上下文文件，AggRoot 启动时会自动加载。将项目的关键信息放在这里：
- 代码结构和架构决策
- 非标准的构建/测试命令
- 代码风格规则和例外情况
- 常见的陷阱和注意事项
控制对话长度
长对话会消耗更多 Token。可以通过以下方式控制：
- 使用
/reset重置会话，开始新话题 - 使用
/sessions管理多个会话 - 将探索任务委托给子代理，避免主对话膨胀
工具选择
优先使用专用工具
| 场景 | 推荐 | 不推荐 |
|---|---|---|
| 读取文件 | Read |
cat (Shell) |
| 编辑文件 | Edit |
sed (Shell) |
| 创建文件 | Write |
echo > (Shell) |
| 搜索文件名 | Glob |
find (Shell) |
| 搜索文件内容 | Grep |
grep (Shell) |
| Git 操作 | GitStatus 等 |
git (Shell) |
| 目录结构 | DirectoryTree |
ls -R (Shell) |
Shell 工具的使用场景
仅在以下情况使用 Shell 工具：
- 运行构建/测试命令（
npm run build、npm test） - 安装依赖（
npm install） - 执行系统命令（
docker、kubectl） - 专用工具无法完成的一站式操作
Edit vs Write
Edit— 修改现有文件的部分内容，最小化 Token 消耗Write— 创建新文件或完全重写文件内容
优先使用 Edit，它只需提供旧文本和新文本，不需要传输整个文件。
并行调用
当多个工具调用之间没有依赖关系时，可以在一条消息中并行发起：
请同时执行以下操作：
1. 读取 src/config.ts
2. 读取 src/constants.ts
3. 搜索所有 TODO 注释
AggRoot 会在一次响应中并行执行这些调用，大幅减少等待时间。
适用场景：
- 读取多个不相关的文件
- 同时搜索不同模式
- 并行启动多个 explore 子代理
不适用场景：
- 后续操作依赖前一步的结果
- 对同一文件的顺序修改
Tips: 并行调用的效率提升非常明显——3 个独立的文件读取，并行只需 1 次往返，串行需要 3 次。
子代理使用
何时使用子代理
| 任务类型 | 推荐代理 | 说明 |
|---|---|---|
| 探索代码结构 | explore |
快速扫描，轻量级 |
| 制定执行计划 | plan |
生成详细的步骤计划 |
| 代码审查 | code-reviewer |
专业审查，给出改进建议 |
| 复杂通用任务 | general-purpose |
通用代理，处理复杂逻辑 |
信任子代理结果
子代理返回的结果已经包含了它读取的所有文件信息。主代理不会重复读取这些文件——你也无需再次请求 AggRoot 读取子代理已处理的文件。
保持主上下文干净
将探索性、研究性的任务委托给子代理，只在主对话中保留结论和决策。这样可以让主对话的上下文更加精炼，减少 Token 消耗。
YOLO 模式
启用 YOLO 模式
/yolo
✅ YOLO mode enabled - tools will auto-execute
启用后，所有工具调用将自动执行，无需人工确认。
适用场景
- 熟悉的、低风险的操作（读取文件、搜索代码）
- 自动化脚本执行
- 批量操作
应避免的场景
- 删除文件或不可逆操作
- 向远程仓库推送代码
- 修改生产环境配置
- 执行不确定的 Shell 命令
安全边界
即使开启 YOLO 模式，AggRoot 的安全控制仍然生效：
DANGEROUS_COMMANDS黑名单中的命令仍会被拦截SAFE_MODE仍会限制代码执行范围- 高风险等级（
high）的工具仍需确认
Tips: 对于日常开发，建议在安全操作时开启 YOLO 模式提高效率，但在执行破坏性操作前关闭或手动确认。
AGGROOT.md 配置
AGGROOT.md 是项目级别的上下文文件，AggRoot 启动时自动加载。保持它简洁且实用：
应该包含的内容
- 项目概述 — 一段话说明项目是什么
- 代码结构 — DDD 分层和关键目录说明
- 非标准命令 — 独特的构建/测试/部署命令
- 代码风格例外 — 与默认不同的规则（如
noUnusedLocals: false） - 已知陷阱 — 容易踩坑的地方
不应该包含的内容
- 可以从代码自动推断的信息
- 频繁变化的临时状态
- 过于详细的实现细节
使用 /init 自动生成
/init
AggRoot 会扫描项目并自动生成 AGGROOT.md，你可以在此基础上修改。
记忆管理
添加重要记忆
使用 /memory 命令保存跨会话的重要信息：
/memory add 项目使用 Vitest 测试框架，不是 Jest
/memory add 前端代码在 src/ui/ 下，使用 React
查看和搜索记忆
/memory list # 列出所有项目记忆
/memory search 测试 # 搜索包含"测试"的记忆
记忆最佳实践
- 添加：项目特定的约定、重要的架构决策、非显而易见的配置
- 避免：临时状态、可从代码推断的信息、频繁变化的细节
- 定期清理：过时的记忆应删除，避免误导
Tips: 好的记忆是那些"即使换了会话也希望记住"的信息。如果某个信息只在当前对话中有用，不需要保存为记忆。