@tencent-ai/agent-sdk 0.3.99 → 0.3.100

package/cli/dist/web-ui/docs/cn/cli/best-practices.md

@@ -0,0 +1,554 @@
+# CodeBuddy Code 最佳实践
+
+> 从环境配置到并行扩展，掌握让 CodeBuddy Code 发挥最大效能的技巧与模式。
+
+CodeBuddy Code 是一个智能编程环境。与传统的问答式助手不同，CodeBuddy Code 能够读取文件、执行命令、修改代码，无论您是在旁观察、适时引导，还是离开去做其他事，它都能自主解决问题。
+
+这将改变您的工作方式——您不再需要自己编写代码然后请求审查，而是描述目标，让 CodeBuddy Code 去探索、规划并实现。
+
+本指南汇集了在各类代码库、语言和环境中经过验证的实践模式。
+
+
+## 给 CodeBuddy Code 验证自己工作的方法
+
+> **核心建议**：提供测试用例、截图或预期输出，让 CodeBuddy Code 能够自我检验。这是提升效果最立竿见影的方法。
+
+当 CodeBuddy Code 能够验证自己的工作时，表现会显著提升——无论是运行测试、对比截图，还是校验输出结果。
+
+如果没有明确的成功标准，它可能产出看似正确但实际无效的代码。这时您就成了唯一能发现问题的人，每个错误都需要您亲自排查。
+
+| 策略 | 改进前 | 改进后 |
+|------|--------|--------|
+| **提供验证标准** | *"写一个检查手机号格式的函数"* | *"写一个 validatePhone 函数。测试用例：13812345678 返回 true，12345 返回 false，138-1234-5678 返回 false。实现后运行测试"* |
+| **视觉验证 UI 变更** | *"优化一下这个表格的样式"* | *"[粘贴截图] 按这个设计稿实现。完成后截图对比原图，列出差异并修复"* |
+| **解决根本原因** | *"编译报错了"* | *"编译失败，错误信息：[粘贴错误]。找出根本原因并修复，不要只是绕过错误。修复后确认编译通过"* |
+
+验证手段可以是测试套件、linter，或者一个检查输出的 Bash 命令。花点时间让验证足够可靠，值得。
+
+---
+
+## 先探索，再规划，后编码
+
+> **核心建议**：把研究、规划和实现分开进行，避免解决错误的问题。
+
+直接让 CodeBuddy Code 动手写代码，可能产出解决错误问题的代码。使用计划模式，将探索与执行分离。
+
+推荐的工作流程分为四个阶段：
+
+### 1. 探索
+
+进入计划模式。CodeBuddy Code 只读取文件、回答问题，不做任何修改。
+
+```
+> 读一下 src/payment 目录，弄清楚我们是怎么处理订单和退款的。
+> 顺便看看支付相关的配置是怎么管理的。
+```
+
+### 2. 规划
+
+让 CodeBuddy Code 输出详细的实现计划。
+
+```
+> 我想接入微信支付。需要改哪些文件？支付流程是怎样的？给我一个详细计划。
+```
+
+按 `Ctrl+G` 在文本编辑器中打开计划，在 CodeBuddy Code 继续之前可以直接编辑。
+
+### 3. 实现
+
+切换回普通模式，让 CodeBuddy Code 按计划编码，边做边验证。
+
+```
+> 按你的计划实现微信支付流程。为回调通知写测试，跑一遍测试套件，有失败的就修。
+```
+
+### 4. 提交
+
+让 CodeBuddy Code 提交代码并创建 MR。
+
+```
+> 写个清晰的提交信息，然后开个 MR
+```
+
+> **注意**：计划模式很有用，但也有额外开销。对于范围明确、改动很小的任务（如修复拼写错误、加一行日志、重命名变量），直接让 CodeBuddy Code 执行即可。当您对方法不确定、变更涉及多个文件、或对要改的代码不够熟悉时，计划模式才最有价值。
+
+---
+
+## 在提示中提供具体上下文
+
+> **核心建议**：指令越精确，后续纠正就越少。
+
+CodeBuddy Code 能推断意图，但不会读心。引用具体文件，说明约束条件，指向示例代码。
+
+| 策略 | 改进前 | 改进后 |
+|------|--------|--------|
+| **限定任务范围** | *"给 user_service.py 加测试"* | *"给 user_service.py 写测试，重点覆盖用户注销的边缘情况，不要用 mock"* |
+| **指向来源** | *"为什么 OrderProcessor 的接口设计这么奇怪？"* | *"查一下 OrderProcessor 的 git 历史，总结这个接口是怎么演变成现在这样的"* |
+| **引用现有模式** | *"加一个搜索组件"* | *"看看 src/components 里现有组件是怎么写的，特别是 ProductCard.vue 这个例子。按同样的模式实现一个搜索组件，支持关键词高亮和历史记录。只用项目里已有的依赖"* |
+| **描述症状** | *"登录有 bug"* | *"用户反馈 token 过期后重新登录会失败。查一下 src/auth/ 的认证流程，重点看 token 刷新逻辑。先写个能复现问题的测试，再修复"* |
+
+模糊提示在探索阶段也有用，允许反复尝试。像 `"这个文件你觉得哪些地方可以改进？"` 这样的提示，往往能发现一些你没想到的问题。
+
+### 提供丰富内容
+
+> **核心建议**：用 `@` 引用文件，粘贴截图，或通过管道输入数据。
+
+您可以通过多种方式向 CodeBuddy Code 提供丰富的上下文：
+
+- **用 `@` 引用文件**：CodeBuddy Code 在回复前会先读取文件，不用您描述代码在哪
+- **直接粘贴图片**：复制/粘贴或拖放图片到输入框
+- **提供 URL**：文档和 API 参考的链接。用 `/permissions` 可以允许常用域名
+- **管道输入数据**：运行 `cat error.log | codebuddy` 直接把文件内容喂给它
+- **让 CodeBuddy Code 自己取**：告诉它用 Bash 命令、MCP 工具或读文件来获取所需上下文
+
+---
+
+## 配置您的环境
+
+一些简单的配置步骤，就能让 CodeBuddy Code 在所有会话中更加高效。
+
+### 设置首选语言
+
+如果您希望 CodeBuddy Code 始终使用特定语言回复（如简体中文），可以通过 `/config` 命令设置 Language 选项：
+
+```
+> /config
+# 选择 Language，输入您的首选语言，如"简体中文"
+```
+
+或者直接在 `~/.codebuddy/settings.json` 中配置：
+
+```json
+{
+  "language": "简体中文"
+}
+```
+
+设置后，CodeBuddy Code 会使用指定语言进行所有回复和解释，技术术语和代码标识符保持原样。留空则自动根据您的输入语言判断。
+
+### 编写有效的 CODEBUDDY.md
+
+> **核心建议**：运行 `/init` 基于当前项目结构生成初始 CODEBUDDY.md，然后逐步完善。
+
+CODEBUDDY.md 是 CodeBuddy Code 每次对话开始时都会读取的特殊文件，里面包含常用命令、代码风格和工作流规则。它为 CodeBuddy Code 提供了**无法从代码本身推断出的**持久上下文。
+
+`/init` 命令会分析您的代码库，检测构建系统、测试框架和代码模式，为您生成一个可以继续完善的基础版本。
+
+CODEBUDDY.md 没有固定格式，保持简短、易读就好。例如：
+
+```markdown
+# 代码风格
+- 使用 ES 模块语法 (import/export)，不用 CommonJS (require)
+- 导入时尽量解构 (如 import { foo } from 'bar')
+
+# 工作流
+- 改完代码记得跑一遍类型检查
+- 优先跑单个测试文件，别动不动就跑整个测试套件
+```
+
+CODEBUDDY.md 每次会话都会加载，所以只放那些普遍适用的内容。对于只在特定场景下才相关的领域知识或工作流，用 [Skills](skills.md) 代替——CodeBuddy Code 会按需加载它们，不会让每次对话都变得臃肿。
+
+保持精简。写每一行时问问自己：*"不写这行，CodeBuddy Code 会犯错吗？"* 如果不会，就删掉。CODEBUDDY.md 太长的话，CodeBuddy Code 反而会忽略你真正重要的指令。
+
+| 应该写 | 不应该写 |
+|--------|----------|
+| CodeBuddy Code 猜不到的命令 | 读代码就能搞清楚的东西 |
+| 和默认习惯不同的代码风格 | 标准的语言约定 |
+| 测试说明和首选的测试运行器 | 详细的 API 文档（放链接就行） |
+| 仓库规范（分支命名、MR 约定） | 经常变化的信息 |
+| 项目特有的架构决策 | 长篇大论的解释或教程 |
+| 开发环境的坑（必需的环境变量等） | 逐文件的代码描述 |
+| 常见陷阱或不明显的行为 | "写干净的代码"之类的废话 |
+
+如果 CodeBuddy Code 有规则却还是不照做，可能是文件太长、规则被淹没了。如果 CodeBuddy Code 问的问题明明 CODEBUDDY.md 里有答案，可能是措辞有歧义。像对待代码一样对待 CODEBUDDY.md：出问题就检查，定期精简，观察改动后 CodeBuddy Code 的行为是否真的变了。
+
+可以用强调词（如 "IMPORTANT" 或 "必须"）来提高遵守度。把 CODEBUDDY.md 提交到 git，让团队一起维护。这个文件的价值会随时间积累。
+
+CODEBUDDY.md 支持用 `@path/to/file` 语法导入其他文件：
+
+```markdown
+查看 @README.md 了解项目概述，@package.json 了解可用的 npm 命令。
+
+# 补充说明
+- Git 工作流：@docs/git-workflow.md
+- 个人配置：@~/.codebuddy/my-overrides.md
+```
+
+CODEBUDDY.md 可以放在多个位置：
+
+- **主目录 (`~/.codebuddy/CODEBUDDY.md`)**：对所有 CodeBuddy Code 会话生效
+- **项目根目录 (`./CODEBUDDY.md`)**：提交到 git 与团队共享；或命名为 `CODEBUDDY.local.md` 并加到 `.gitignore`
+- **父目录**：适合 monorepo，`root/CODEBUDDY.md` 和 `root/packages/foo/CODEBUDDY.md` 都会自动加载
+- **子目录**：当 CodeBuddy Code 处理该子目录的文件时，会按需加载
+
+### 配置权限
+
+> **核心建议**：用 `/permissions` 允许安全的命令，或用 `/sandbox` 启用系统级隔离。减少打断的同时保持控制。
+
+默认情况下，CodeBuddy Code 对可能修改系统的操作都会请求权限：写文件、执行命令、调用 MCP 工具等。虽然安全，但频繁确认很烦。批准到第十次的时候，你其实已经不看了，只是机械地点通过。有两种方法减少这种打断：
+
+- **权限白名单**：允许你确认安全的特定命令（如 `npm run lint` 或 `git commit`）
+- **沙箱模式**：启用系统级隔离，限制文件系统和网络访问，让 CodeBuddy Code 在定义好的边界内更自由地工作
+
+也可以用 `--dangerously-skip-permissions` 跳过所有权限检查，适合封闭的工作流，如修复 lint 错误或生成样板代码。
+
+> **警告**：让 CodeBuddy Code 随意执行命令可能导致数据丢失、系统损坏，或通过提示注入泄露数据。`--dangerously-skip-permissions` 只应在没有网络的沙箱环境中使用。
+
+详细了解[配置权限](settings.md)和[启用沙箱](bash-sandboxing.md)。
+
+### 使用 CLI 工具
+
+> **核心建议**：与外部服务交互时，让 CodeBuddy Code 使用 CLI 工具，如 `gh`、`glab`、`sentry-cli` 等。
+
+CLI 工具是与外部服务交互最省上下文的方式。如果您用 GitHub 或 GitLab，装好对应的 CLI 就行。CodeBuddy Code 知道怎么用它来创建 issue、开 MR、读评论。没有 CLI 的话，CodeBuddy Code 也能直接调 API，但未认证的请求很容易触发限流。
+
+CodeBuddy Code 也很擅长学习陌生的 CLI 工具。试试这样的提示：`先用 'some-cli --help' 了解一下这个工具，然后用它完成 X、Y、Z。`
+
+### 连接 MCP 服务器
+
+> **核心建议**：运行 `codebuddy mcp add` 连接外部工具，如 Notion、Figma 或数据库。
+
+通过 [MCP 服务器](mcp.md)，CodeBuddy Code 可以直接从 issue 系统拉取需求、查询数据库、分析监控数据、集成 Figma 设计稿，实现工作流自动化。
+
+### 设置 Hooks
+
+> **核心建议**：对于必须每次都执行、不能有例外的操作，用 hooks。
+
+[Hooks](hooks-guide.md) 会在 CodeBuddy Code 工作流的特定节点自动运行脚本。与 CODEBUDDY.md 里的指令不同（那些只是"建议"），hooks 是确定性的，保证一定会执行。
+
+CodeBuddy Code 可以帮您写 hooks。试试这样的提示：*"写一个 hook，每次编辑文件后自动跑 eslint"* 或 *"写一个 hook，阻止对 migrations 目录的写入"*。运行 `/hooks` 可以交互式配置，或者直接编辑 `.codebuddy/settings.json`。
+
+### 创建 Skills
+
+> **核心建议**：在 `.codebuddy/skills/` 目录下创建 `SKILL.md` 文件，给 CodeBuddy Code 补充领域知识和可复用的工作流。
+
+[Skills](skills.md) 可以用项目、团队或领域特定的信息来扩展 CodeBuddy Code 的能力。CodeBuddy Code 会在相关场景自动应用它们，您也可以用 `/skill-name` 手动调用。
+
+在 `.codebuddy/skills/` 下新建一个目录，放入 `SKILL.md` 即可创建技能：
+
+```markdown
+# .codebuddy/skills/api-conventions/SKILL.md
+---
+name: api-conventions
+description: 我们服务的 REST API 设计规范
+---
+# API 规范
+- URL 路径用 kebab-case
+- JSON 字段用 camelCase
+- 列表接口必须支持分页
+- API 版本放在 URL 路径里 (/v1/, /v2/)
+```
+
+Skills 也可以定义可重复执行的工作流：
+
+```markdown
+# .codebuddy/skills/fix-issue/SKILL.md
+---
+name: fix-issue
+description: 修复 GitLab issue
+disable-model-invocation: true
+---
+分析并修复 GitLab issue：$ARGUMENTS。
+
+1. 用 `glab issue view` 获取 issue 详情
+2. 理解问题描述
+3. 在代码库里搜索相关文件
+4. 实现修复
+5. 写测试并运行验证
+6. 确保 lint 和类型检查通过
+7. 写好提交信息
+8. 推送并创建 MR
+```
+
+运行 `/fix-issue 1234` 来调用。对于有副作用的工作流，加上 `disable-model-invocation: true`，确保只能手动触发。
+
+### 创建自定义子代理
+
+> **核心建议**：在 `.codebuddy/agents/` 中定义专门的助手，CodeBuddy Code 可以把特定任务委派给它们。
+
+[子代理](sub-agents.md)在独立的上下文中运行，有自己的工具权限集。适合需要读取大量文件或需要专注执行的任务，不会干扰您的主对话。
+
+```markdown
+# .codebuddy/agents/security-reviewer.md
+---
+name: security-reviewer
+description: 审查代码安全漏洞
+tools: Read, Grep, Glob, Bash
+model: claude-sonnet-4-20250514
+---
+你是一名资深安全工程师。审查代码时重点关注：
+- 注入漏洞（SQL 注入、XSS、命令注入）
+- 认证和授权缺陷
+- 代码中硬编码的密钥或凭据
+- 不安全的数据处理
+
+给出具体的行号和修复建议。
+```
+
+明确告诉 CodeBuddy Code 使用子代理：*"用子代理审查一下这段代码的安全问题。"*
+
+### 安装插件
+
+> **核心建议**：运行 `/plugin` 浏览插件市场。插件可以一键添加技能、工具和集成，无需额外配置。
+
+[插件](plugins.md)把技能、hooks、子代理和 MCP 服务器打包成一个可安装的单元，由社区和官方提供。如果您用的是类型化语言，可以安装代码智能插件，让 CodeBuddy Code 获得精确的符号导航能力，并在编辑后自动检测错误。
+
+关于如何在技能、子代理、hooks 和 MCP 之间做选择，请参阅[扩展 CodeBuddy Code](plugins.md)。
+
+---
+
+## 有效沟通
+
+您与 CodeBuddy Code 的沟通方式直接影响输出质量。
+
+### 向代码库提问
+
+> **核心建议**：像问一位资深工程师那样问 CodeBuddy Code。
+
+熟悉新代码库时，把 CodeBuddy Code 当作学习和探索的工具。您可以问它那些原本要问同事的问题：
+
+- 日志系统是怎么工作的？
+- 怎么新建一个 API 接口？
+- handler.go 第 78 行的 `defer func() { ... }()` 是干嘛的？
+- PaymentService 处理了哪些边缘情况？
+- 为什么这里调用的是 `processAsync()` 而不是 `processSync()`？
+
+这是很高效的入职方式——缩短上手时间，减少对同事的打扰。不需要什么特殊技巧，直接问就好。
+
+### 让 CodeBuddy Code 采访您
+
+> **核心建议**：做大功能之前，先让 CodeBuddy Code 采访您。从简短描述开始，让它用 AskUserQuestion 工具来深挖细节。
+
+CodeBuddy Code 会问一些您可能没想到的问题，涵盖技术实现、用户体验、边缘情况和各种取舍。
+
+```
+我想做一个 [简要描述]。用 AskUserQuestion 工具详细采访我。
+
+问技术方案、用户体验、边缘情况、潜在风险和权衡。别问显而易见的问题，深挖那些我可能没考虑到的难点。
+
+一直问到我们把所有方面都覆盖了，然后把完整的需求规格写到 SPEC.md。
+```
+
+规格写完后，开一个新会话来实现它。新会话有干净的上下文，可以专注于实现，而且您有书面规格可以随时参考。
+
+---
+
+## 管理您的会话
+
+对话是持久的，也是可回退的。善用这一点！
+
+### 及早纠正，经常纠正
+
+> **核心建议**：一发现 CodeBuddy Code 跑偏了，立刻纠正。
+
+好结果来自紧密的反馈循环。虽然 CodeBuddy Code 有时能一次搞定，但快速纠正往往能更快地得到更好的方案。
+
+- **`Esc`**：按 `Esc` 键可以中途打断 CodeBuddy Code。上下文会保留，您可以重新引导方向
+- **`Esc + Esc` 或 `/rewind`**：连按两次 `Esc` 或运行 `/rewind` 打开回退菜单，恢复到之前的对话和代码状态
+- **"撤销刚才的改动"**：让 CodeBuddy Code 回滚它的修改
+- **`/clear`**：在不相关的任务之间清空上下文。上下文里塞太多无关内容会拖慢效率
+
+如果同一个问题您已经纠正了两次还是不对，说明上下文里已经堆满了失败的尝试。这时候运行 `/clear`，用一个更清晰的提示重新开始，把学到的东西融入进去。干净的会话配上更好的提示，几乎总是比不断追加纠正的长会话效果更好。
+
+### 主动管理上下文
+
+> **核心建议**：任务切换时运行 `/clear` 清空上下文。
+
+当上下文快满的时候，CodeBuddy Code 会自动压缩对话历史，保留重要的代码和决策，释放空间。
+
+长会话中，CodeBuddy Code 的上下文窗口可能被无关的对话、文件内容和命令输出塞满。这会拖慢效率，有时还会分散它的注意力。
+
+- 任务之间多用 `/clear` 彻底清空上下文
+- 自动压缩触发时，CodeBuddy Code 会总结最重要的内容，包括代码模式、文件状态和关键决策
+- 想要更精细的控制，可以运行 `/compact <指令>`，比如 `/compact 只保留 API 相关的改动`
+- 也可以在 CODEBUDDY.md 里指定压缩规则，比如 `"压缩时，始终保留修改过的文件列表和测试命令"`，确保关键上下文不丢失
+
+### 用子代理做调研
+
+> **核心建议**：用 `"派个子代理调查一下 X"` 来委托调研任务。子代理在独立的上下文中工作，不会污染您的主对话。
+
+上下文是核心瓶颈，子代理是应对这一问题最强大的工具之一。当 CodeBuddy Code 研究代码库时，会读取大量文件，这些都在消耗您的上下文。子代理在独立的上下文窗口中运行，最后只返回摘要：
+
+```
+派个子代理调查一下我们的认证系统是怎么处理 token 刷新的，
+还有看看有没有现成的 OAuth 工具可以复用。
+```
+
+子代理会深入代码库，读取相关文件，然后汇报发现——整个过程不会干扰您的主对话。
+
+您也可以在 CodeBuddy Code 实现完某个功能后，用子代理来做验证：
+
+```
+派个子代理检查一下这段代码的边缘情况
+```
+
+### 利用检查点回退
+
+> **核心建议**：CodeBuddy Code 的每个操作都会创建检查点。您可以把对话、代码或两者一起恢复到任意历史状态。
+
+CodeBuddy Code 在做修改前会自动创建检查点。连按两次 `Escape` 或运行 `/rewind` 打开检查点菜单。您可以选择：只恢复对话（保留代码改动）、只恢复代码（保留对话）、或者两者都恢复。
+
+不需要小心翼翼地规划每一步——您尽可以让 CodeBuddy Code 尝试一些冒险的做法。如果不行，回退后换个思路再试。检查点跨会话持久化，所以您可以关掉终端，回来后仍然能回退。
+
+> **警告**：检查点只追踪 *CodeBuddy Code* 做的改动，不追踪外部进程。它不能替代 git。
+
+### 恢复对话
+
+> **核心建议**：运行 `codebuddy --continue` 继续上次的对话，或用 `--resume` 从最近的会话中选一个。
+
+CodeBuddy Code 会把对话保存在本地。当一个任务跨越多次工作时（比如开始做一个功能，被打断了，第二天回来继续），您不必从头解释上下文：
+
+```bash
+codebuddy --continue    # 继续最近的对话
+codebuddy --resume      # 从历史会话中选择
+```
+
+用 `/rename` 给会话起个有意义的名字（比如 `"支付重构"`、`"内存泄漏排查"`），方便以后找。像管理 git 分支一样管理会话——不同的工作线可以有各自独立、持久的上下文。
+
+---
+
+## 自动化与扩展
+
+当您能高效使用一个 CodeBuddy Code 之后，可以通过并行会话、无头模式和脚本编排来成倍提升产出。
+
+前面所有内容都假设是"一个人、一个 CodeBuddy Code、一个对话"的场景。但 CodeBuddy Code 可以水平扩展。这一节介绍如何做更多事。
+
+### 无头模式
+
+> **核心建议**：在 CI、pre-commit hooks 或脚本中使用 `codebuddy -p "prompt"`。加上 `--output-format stream-json` 可以获得流式 JSON 输出。
+
+用 `codebuddy -p "您的提示"` 可以无头运行 CodeBuddy Code，不需要交互式会话。这是把 CodeBuddy Code 集成到 CI 流水线、pre-commit hooks 或任何自动化工作流的方式。输出格式（纯文本、JSON、流式 JSON）让您可以程序化地解析结果。
+
+```bash
+# 一次性查询
+codebuddy -p "解释一下这个项目是做什么的"
+
+# 结构化输出，方便脚本处理
+codebuddy -p "列出所有 API 端点" --output-format json
+
+# 流式输出，实时处理
+codebuddy -p "分析这个日志文件" --output-format stream-json
+```
+
+### 多会话并行
+
+> **核心建议**：并行运行多个 CodeBuddy Code 会话，可以加速开发、做隔离实验，或启动复杂工作流。
+
+并行会话有两种主要方式：
+
+- **多终端窗口**：在不同目录启动多个 CodeBuddy Code 实例
+- **Git Worktrees**：每个会话在独立的 worktree 中工作
+
+除了并行加速，多会话还能实现质量导向的工作流。新鲜的上下文有助于代码审查——因为 CodeBuddy Code 不会对自己刚写的代码有偏见。
+
+例如，"写代码/审代码"模式：
+
+| 会话 A（写代码） | 会话 B（审代码） |
+|------------------|------------------|
+| `给 API 端点实现一个限流中间件` | |
+| | `审查 @src/middleware/rateLimiter.ts 里的限流器实现。找边缘情况、竞态条件，检查和现有中间件模式是否一致。` |
+| `这是审查意见：[会话 B 的输出]。处理一下这些问题。` | |
+
+测试也可以这样做：让一个 CodeBuddy Code 写测试，另一个写代码来让测试通过。
+
+### 脚本编排
+
+> **核心建议**：循环遍历任务列表，每个任务调用一次 `codebuddy -p`。用 `--allowedTools` 限制批量操作的权限范围。
+
+对于大规模迁移或批量分析，可以把工作分配给多个并行的 CodeBuddy Code 调用：
+
+**1. 生成任务列表**
+
+让 CodeBuddy Code 列出所有需要处理的文件（比如 `列出所有需要迁移的 2000 个 Python 文件`）
+
+**2. 写脚本循环处理**
+
+```bash
+for file in $(cat files.txt); do
+  codebuddy -p "把 $file 从 Class 组件迁移到 Hooks。返回 OK 或 FAIL。" \
+    --allowedTools "Edit,Bash(git commit *)"
+done
+```
+
+**3. 先小范围测试，再大规模运行**
+
+根据前几个文件的执行情况调整提示，然后跑完整列表。`--allowedTools` 限制 CodeBuddy Code 能用的工具，这在无人值守时很重要。
+
+也可以把 CodeBuddy Code 集成到现有的数据处理流水线里：
+
+```bash
+codebuddy -p "<您的提示>" --output-format json | your_command
+```
+
+开发时加 `--verbose` 方便调试，生产环境去掉。
+
+### 安全的自主模式
+
+用 `codebuddy --dangerously-skip-permissions` 可以跳过所有权限检查，让 CodeBuddy Code 不间断地工作。适合那些封闭的工作流，比如修复 lint 错误或生成样板代码。
+
+> **警告**：让 CodeBuddy Code 随意执行命令有风险——可能导致数据丢失、系统损坏，或通过提示注入泄露数据。为了降低风险，请在没有网络访问的容器中使用 `--dangerously-skip-permissions`。
+>
+> 启用沙箱 (`/sandbox`) 后，您可以获得类似的自主性，但安全性更好。沙箱提前划定边界，而不是绕过所有检查。
+
+---
+
+## 避免常见的坑
+
+这些是常见的失败模式。早点识别能省不少时间：
+
+### 1. 无关上下文干扰
+
+您从一个任务开始，中间问了 CodeBuddy Code 一些无关的事，然后又回到第一个任务。上下文里塞满了无关信息。
+
+**解决方法**：任务切换时用 `/clear`。
+
+### 2. 反复纠正
+
+CodeBuddy Code 做错了，您纠正，还是错，再纠正。上下文被失败的尝试污染了。
+
+**解决方法**：纠正两次还不行，就 `/clear` 然后写一个更好的提示，把学到的东西融入进去。
+
+### 3. CODEBUDDY.md 写太多
+
+CODEBUDDY.md 太长的话，CodeBuddy Code 会忽略一半，因为重要规则被淹没在噪音里了。
+
+**解决方法**：狠心精简。如果没有这条规则 CodeBuddy Code 也做对了，就删掉它或者转成 hook。
+
+### 4. 只信任不验证
+
+CodeBuddy Code 产出的代码看起来没问题，但其实没处理边缘情况。
+
+**解决方法**：始终提供验证手段（测试、脚本、截图）。验证不了的东西，别上线。
+
+### 5. 无边界的探索
+
+您让 CodeBuddy Code "调查一下"某个东西，但没限定范围。CodeBuddy Code 读了几百个文件，把上下文填满了。
+
+**解决方法**：缩小调查范围，或者用子代理——这样探索不会消耗主对话的上下文。
+
+---
+
+## 培养您的直觉
+
+本指南里的模式不是教条。它们是通常有效的起点，但未必是每种场景的最优解。
+
+有时您*应该*让上下文积累——因为您正在深挖一个复杂问题，历史记录是有价值的。有时您应该跳过计划直接让 CodeBuddy Code 自己摸索——因为任务本身就是探索性的。有时模糊的提示恰好合适——因为您想先看看 CodeBuddy Code 怎么理解问题，再加约束。
+
+留意什么方法有效。当 CodeBuddy Code 产出很棒的结果时，回想一下您做了什么：提示怎么写的、给了什么上下文、用的什么模式。当 CodeBuddy Code 表现挣扎时，问问为什么：上下文太乱？提示太模糊？任务太大一次吃不下？
+
+随着时间推移，您会培养出任何指南都无法替代的直觉。您会知道什么时候该具体、什么时候该开放，什么时候该计划、什么时候该探索，什么时候该清空上下文、什么时候该让它继续积累。
+
+---
+
+## 相关资源
+
+- **[快速入门](quickstart.md)** - 5 分钟上手
+- **[常见工作流](common-workflows.md)** - 调试、测试、MR 等场景的分步指南
+- **[CODEBUDDY.md 指令管理](memory.md)** - 存储项目约定和持久上下文
+- **[Skills 技能系统](skills.md)** - 扩展专业能力
+- **[配置参考](settings.md)** - 配置 CodeBuddy Code 的行为
+- **[CLI 命令参考](cli-reference.md)** - 完整的命令行参考
+
+---
+
+*掌握这些最佳实践，让 CodeBuddy Code 成为您最得力的编程搭档*