实施指南

快速开始：创建你的第一个子代理

本章提供详细的配置步骤和代码示例，帮助用户快速上手 CodeBuddy CLI 的 Sub-Agents 功能。

步骤一：环境准备

1. 安装 CodeBuddy CLI

如果尚未安装，请先安装 CodeBuddy CLI：

# 根据官方文档的安装指引进行安装
# 访问 https://www.codebuddy.ai/cli 获取最新安装方式

2. 验证安装

codebuddy --version

步骤二：创建项目级子代理

示例 1：代码审查代理（Code Reviewer）

创建一个专门用于代码审查的子代理：

# 创建代理目录
mkdir -p .codebuddy/agents

# 创建代码审查代理
cat > .codebuddy/agents/code-reviewer.md << 'EOF'
---
name: code-reviewer
description: 专家代码审查员。主动审查代码质量、安全性和可维护性。在编写或修改代码后立即使用。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位高级代码审查员，确保高标准的代码质量和安全性。

被调用时：
1. 运行 git diff 查看最近的变更
2. 聚焦修改的文件
3. 立即开始审查

审查清单：
- 代码简单且可读
- 函数和变量命名良好
- 没有重复代码
- 适当的错误处理
- 没有暴露的密钥或 API 密钥
- 实现了输入验证
- 良好的测试覆盖率
- 考虑了性能问题

按优先级组织反馈：
- 关键问题（必须修复）
- 警告（应该修复）
- 建议（考虑改进）

包含如何修复问题的具体示例。
EOF

示例 2：调试专家代理（Debugger）

创建一个专门用于调试的子代理：

cat > .codebuddy/agents/debugger.md << 'EOF'
---
name: debugger
description: 调试专家，专门处理错误、测试失败和意外行为。在遇到任何问题时主动使用。
tools: Read, Edit, Bash, Grep, Glob
---

你是一位专注于根本原因分析的调试专家。

被调用时：
1. 捕获错误消息和堆栈跟踪
2. 识别复现步骤
3. 隔离失败位置
4. 实施最小修复
5. 验证解决方案有效

调试流程：
- 分析错误消息和日志
- 检查最近的代码变更
- 形成和测试假设
- 添加战略性调试日志
- 检查变量状态

对于每个问题，提供：
- 根本原因解释
- 支持诊断的证据
- 具体的代码修复
- 测试方法
- 预防建议

专注于修复根本问题，而不仅仅是症状。
EOF

示例 3：测试运行代理（Test Runner）

cat > .codebuddy/agents/test-runner.md << 'EOF'
---
name: test-runner
description: 测试自动化专家。在代码变更后主动运行测试并修复失败。
tools: Read, Edit, Bash, Grep
---

你是一位测试自动化专家。当你看到代码变更时，主动运行适当的测试。

如果测试失败：
1. 分析失败原因
2. 理解原始测试意图
3. 修复代码或测试（保留原始意图）
4. 重新运行测试验证修复

最佳实践：
- 只运行相关的测试子集以节省时间
- 理解测试失败的根本原因
- 不要仅为了让测试通过而修改测试
- 确保修复不会引入新问题
EOF

步骤三：创建用户级子代理

用户级子代理在所有项目中都可用：

# 创建用户级代理目录
mkdir -p ~/.codebuddy/agents

# 创建通用的架构师代理
cat > ~/.codebuddy/agents/architect.md << 'EOF'
---
name: architect
description: 软件架构专家。用于设计系统架构、评估技术选型和审查架构决策。
tools: Read, Grep, Glob, Bash
model: gpt-5.1-codex
---

你是一位资深软件架构师，专注于设计可扩展、可维护的系统架构。

职责：
- 评估技术选型和架构方案
- 识别潜在的技术债务和设计风险
- 提供架构改进建议
- 确保设计符合最佳实践

分析维度：
1. 可扩展性（Scalability）
2. 可维护性（Maintainability）
3. 性能（Performance）
4. 安全性（Security）
5. 可测试性（Testability）

输出格式：
- 当前架构概述
- 识别的风险和问题
- 改进建议（优先级排序）
- 实施路线图
EOF

步骤四：使用子代理

显式调用

在 CodeBuddy CLI 交互模式中，直接使用自然语言调用：

> 使用 code-reviewer 检查我最近提交的代码
> 让 debugger 调查这个测试失败的原因
> 使用 architect 评审这个模块的设计

自动触发

CodeBuddy 会根据任务描述自动选择合适的子代理。为了促进自动触发，确保子代理的 description 字段清晰描述其用途和触发时机。

使用 /agents 管理界面

/agents

这将打开交互式菜单，可以：

• 查看所有可用代理
• 创建新代理
• 编辑现有代理
• 管理工具权限

步骤五：高级配置

配置权限模式

子代理支持不同的权限模式：

---
name: cautious-editor
description: 谨慎的代码编辑代理
permissionMode: plan  # 选项：default, acceptEdits, bypassPermissions, plan, ignore
---

权限模式说明：

配置模型

可以为子代理指定特定的 AI 模型：

---
name: fast-explorer
description: 快速代码探索代理
model: gemini-3.0-flash  # 使用轻量级模型提高速度
---

或使用与主对话相同的模型：

---
name: consistent-agent
description: 保持与主对话一致的能力
model: inherit
---

自动加载技能

子代理可以自动加载特定技能：

---
name: git-expert
description: Git 操作专家
skills: git-master  # 自动加载 git-master 技能
---

步骤六：版本控制与团队协作

将项目级代理提交到版本控制

# 添加代理目录到 git
git add .codebuddy/agents/
git commit -m "feat: add code-reviewer and debugger sub-agents"

这样整个团队都可以使用相同的代理配置，确保一致的代码审查和调试标准。

创建代理开发规范

建议团队制定代理开发规范：

# Sub-Agent 开发规范

## 命名规范
- 使用小写字母和连字符
- 名称应该反映代理的职责
- 示例：code-reviewer, security-auditor, test-generator

## Description 编写指南
- 清晰描述代理的专业领域
- 说明何时应该使用此代理
- 建议使用 "主动使用" 等关键词促进自动触发

## 工具权限原则
- 最小权限原则：只授予必要的工具
- 避免授予破坏性工具（如 Delete）给不需要的代理
- 敏感操作代理需要明确的权限模式配置

故障排除

代理未被识别

• 检查文件位置是否正确（.codebuddy/agents/ 或 ~/.codebuddy/agents/）
• 确保文件扩展名为 .md
• 验证 YAML frontmatter 格式正确
• 重启 CodeBuddy CLI 会话

代理未被自动调用

• 优化 description 字段，使用更具体的关键词
• 尝试显式调用验证代理功能正常
• 检查是否有其他代理的 description 更匹配当前任务

工具权限问题

• 检查 tools 字段配置是否正确
• 使用 /agents 命令验证代理的工具权限
• 必要时使用 permissionMode 调整权限行为

最佳实践总结

1. 从小开始：先创建 1-2 个核心代理，逐步扩展
2. 保持专注：每个代理应该有单一、清晰的责任
3. 详细提示词：系统提示词越详细，代理表现越好
4. 限制工具权限：只授予必要的工具，提高安全性和专注度
5. 版本控制：将项目级代理提交到版本控制，便于团队协作
6. 迭代优化：根据实际使用情况持续优化代理配置

参考资料

• CodeBuddy CLI Sub-Agents 文档 - 官方详细文档
• CodeBuddy CLI 配置文档 - 设置和工具配置
• CodeBuddy CLI 模型文档 - 支持的 AI 模型