3. 核心心法-上下文、模式、会话

来源：CodeBuddy

这一章没有实战案例，但它是整本书的分水岭。

用同一个工具，有人觉得"也就那样"，有人觉得离不开，差别几乎全在这一章：你给它的上下文够不够、你会不会分阶段喂、你知不知道什么时候该开新会话。

3.1 上下文决定质量

先记住一句话：它不知道的事情，它一定会猜。而猜的部分，就是错误的部分。

你给的上下文越具体，它猜的空间越小，输出越可用。这件事听起来理所当然，但绝大多数"AI 不好用"的抱怨，根源都是上下文没给够。

CodeBuddy 的上下文是分层的，一共五层，从全局到局部：

层级	位置	作用	要不要提交进 Git
用户记忆	~/.codebuddy/CODEBUDDY.md	你个人的通用偏好，所有项目都生效	不（在你家目录里）
用户规则	~/.codebuddy/rules/	你个人的通用规则	不
项目记忆	./CODEBUDDY.md 或 ./.codebuddy/CODEBUDDY.md	这个项目的背景、结构、约定	要，团队共享
项目规则	./.codebuddy/rules/	这个项目的具体规矩	要
本地记忆	CODEBUDDY.local.md	个人在这个项目里的临时偏好	不（自动进 gitignore）

这个分层设计的用意很清楚：能共享的共享（项目级，提交进仓库），不能共享的留本地（用户级和 local，自动忽略）。

你不需要现在就记住这张表。先知道两件事：

1. CODEBUDDY.md 是项目记忆，/init 生成的就是它，可以手动改，改完它立刻按新内容执行
2. 有些私人的东西（比如"我的测试数据库连接变量名（不填写密码或密钥）是 xxx"）绝对不要写进项目记忆，写进 CODEBUDDY.local.md

想看看当前的记忆状态，会话里敲：

/memory

它会列出加载了哪些记忆文件。觉得它忘了什么事，多半是那一层没写。

一份好的项目记忆长什么样

不是"这是一个 Python 项目"这种废话，是这些信息：

# 项目：订单服务

## 是什么
内部订单处理服务，给 App 和小程序提供订单接口。

## 技术栈
- Python 3.11 + FastAPI
- PostgreSQL 14，SQLAlchemy 2.0（不用 1.x 写法）
- pytest + pytest-cov，覆盖率门槛 80%

## 怎么跑
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload   # http://localhost:8000/docs

## 目录约定
app/api/      接口层，只做参数校验和转发
app/service/  业务逻辑，不允许直接写 SQL
app/model/    数据模型
tests/        测试，目录结构与 app/ 对应

## 规矩
- 所有接口必须有对应的单元测试
- 数据库操作一律走 service 层，禁止在 api 层直接查库
- 提交信息用 Conventional Commits 格式
- 不要修改 migrations/ 下已提交的迁移文件

注意最后那块"规矩"。你写的每条规矩，它都会当作约束遵守。 这是让 AI 稳定输出的最有效手段——比你在提示词里重复一百遍都管用。

3.2 怎么把材料喂给它

四种方式，按场景选。

一、@ 引用文件。 输入 @ 会弹出文件列表，或者直接打字：

@src/order/service.py 这个函数为什么在并发下会算错金额？

支持一次引用多个，也支持引用整个目录（@src/order/）。引用会触发 Tab 补全。

二、@import 语法。 在 CODEBUDDY.md 里用 @import 可以把别的文件引进来：

@import ./docs/api-convention.md
@import ./docs/db-schema.md

适合记忆文件太长、想拆开维护的情况。

三、直接粘贴。 报错日志、配置片段、一小段代码，直接粘进输入框最省事。长日志建议先存成文件再引用，免得刷屏。

四、管道。 这一条最容易被忽略，也最能体现 CLI 的优势：

# 把日志灌进去分析
cat error.log | codebuddy -p "找出根因，给出最可能的三个原因"

# 分析最近 20 个提交
git log --oneline -20 | codebuddy -p "哪些提交有风险，为什么"

# 分析依赖情况
pip list --format=freeze | codebuddy -p "哪些包版本过旧，哪些有已知漏洞"

选 @ 还是管道？ 规则很简单：内容在文件里就用 @（它还能顺带看文件的上下文），内容是命令的输出就用管道。

3.3 三种用法

交互式

codebuddy

进入对话，适合探索性的活——"这个项目怎么回事"、"帮我设计个方案"。大部分开发任务用这个。

单次执行（-p）

codebuddy -p "把这个目录下所有 .py 文件的 docstring 统一成 Google 风格"

跑完就退出，不进对话。适合塞进脚本和 CI。

需要它自己干活不想被权限拦住时，加 -y：

codebuddy -p "给 utils.py 补上单元测试" -y

-y 是跳过确认的意思，请谨慎。 我的习惯是：在容器里、CI 里、或者改动全在 Git 版本控制下的裸仓库里才敢加 -y。日常开发目录里不要加。

管道

上一节说过了。管道本质是把 -p 和 stdin 结合起来，适合一次性分析。

怎么选？ 需要来回讨论 → 交互式；确定性的批处理任务 → -p；分析命令输出 → 管道。

3.4 会话管理

几个命令，用熟了效率差很多：

命令	作用	什么时候用
/clear	清空上下文重新开始	换了一件事
/resume	找回之前的会话	昨天的活接着干
/compact	压缩历史对话，保留要点	上下文快满了、它开始"失忆"
/context	看当前占用了多少上下文	感觉它变笨了
/cost	花了多少	心里有数
/branch	从当前位置开一个分支会话	想试两条路，不想互相污染

/compact 值得单独说。 当一轮对话聊了几十轮，上下文会接近上限，它开始忘记前面说过的话。这时候 /compact 会把历史压缩成一份摘要，质量不会明显下降，但空间腾出来了。

判断标准：敲 /context 看占用比例，超过七成就该 /compact 或者 /clear 了。

3.5 让它先想清楚

这一条我单独拿出来讲，因为它是区分新手和熟手的分水岭。

新手拿到任务是直接说"帮我重构这个文件"。熟手会先说：

先不要改任何代码。读一遍 src/order/service.py，
告诉我：它现在有哪几个职责、哪几块耦合最严重、
你会怎么拆、每一步的风险是什么。给我一个三到五步的方案。

拿到方案，你看一眼，觉得对，再说"按第一步来"。

为什么要多这一步？ 三个理由：

1. 方案错了，改起来零成本；代码错了，改起来很贵。 它改完三百行你才发现方向不对，比看三行方案累一百倍。
2. 你能借机发现它理解错了。 比如它以为那个字段是必填的，其实可以为空。在方案阶段说清楚，比在代码阶段返工强。
3. 方案给你验收的依据。 后面每一步你都有东西可以对照。

配合 plan 模式用效果更好：按 Shift+Tab 切到 plan 模式，它在里面只能出方案不能动手，物理上杜绝了"说着说着就改了"。

"先给方案"这句话怎么写？ 记住这个句式：

先不要改代码。先做A，然后给我B。

A = 读什么、分析什么；B = 输出什么格式的方案。越具体越好，比如"给我三到五步的方案，每步标注改动的文件和验证方式"。

3.6 验收三步

它说"完成了"，只是开始。每次都要走这三步：

第一步：看它动了什么。

git status
git diff

重点看有没有动到你不让它动的文件。它会顺手"优化"一些你没要求的东西，这是常见行为。

第二步：跑一遍。

# 按项目自己的方式
pytest
# 或 npm test / make test / go test ./...

测试过了再看下一步。项目没测试？那正好是下一章的事。

第三步：自己读关键改动。

不是逐行 review，而是看这几处：

• 它加了什么依赖？（package.json / requirements.txt 有没有多出没必要的包）
• 它删了什么？（有没有顺手删掉你不让删的）
• 边界处理对不对？（空值、异常、并发）
• 有没有硬编码的东西混进来（路径、密钥、端口号）

这三步加起来两三分钟。跳过它，出问题的概率会高很多。

3.7 好习惯清单

后面七个案例反复会用到这几条，先列在这里：

1. 动手前先有 Git 快照。 新项目 git init，老项目确认工作区干净，改大东西先开分支。
2. 先要方案，再要代码。 尤其是重构、删除、批量操作。
3. 一件事一个会话。 换事就 /clear。
4. 干完必看 git status 和 git diff。
5. 报错整段复制给它，不要自己转述。
6. 不满意就接着说哪里不对，不要重开——它记得上下文，重开等于丢掉所有背景。
7. 危险操作（rm、--force、git push、改数据库）永远手动确认。
8. 把重复的规矩写进 CODEBUDDY.md，不要每次在提示词里重说。
9. 它联网查到的东西，自己验一遍。 版本号、API 签名、配置项，它都有可能记错。
10. 上下文超过七成就 /compact。

常见坑

它总是忘了我说过的话。 两可能：一是上下文满了（/compact），二是你把它写在了对话里而不是 CODEBUDDY.md。对话里的规矩会随着 /clear 消失，写进记忆文件的不会。

它改了一堆我没让它改的文件。 提示词里明确加一句"只改 X，其他文件一个都不要动"。并且事后一定要 git status 检查。

同一个任务每次结果都不一样。 说明你的提示词约束不够。把输出格式、边界条件、不允许的做法都写死，它才会稳定。

它说"已完成"但我跑不起来。 把报错粘给它。90% 的情况它缺的是运行环境信息——Python 版本、依赖版本、当前工作目录。在 CODEBUDDY.md 里写清楚这些，这类问题会少一大半。

---

从下一章开始，全是实战。第一个案例就是最常遇到的：接手一个陌生仓库。

个人记忆也会进入模型上下文。凭据用环境变量或密钥管理器提供，不写进记忆、提示词或日志。