如何将编程书籍中的建议整理成 VSCode AI agent 可用的上下文？
可以先把书中希望采用的建议整理成简短、可执行的项目规则，再在具体任务中提供相关解释和示例。这类需求通常可以先从整理上下文入手，无需一开始就训练或微调模型。
你没有说明使用的是哪款 VSCode AI agent，因此需要根据该工具支持的能力选择文件加载方式，例如手动粘贴、附加文件、读取工作区文件，或使用它支持的项目指令机制。
为什么整本 PDF 未必能直接解决问题？
你的目标是让 agent 在编写和修改 C++20 代码时采用书中的一些建议。书中包含背景、论证、示例，以及不同条件下的取舍。即使提供全文，也不能保证 agent 会为当前任务选出合适的建议。
即使工具支持读取 PDF，也需要区分哪些内容是必须遵守的项目约束，哪些是特定场景下可以考虑的设计方案。整理清楚这些内容，比单纯转换文件格式更有帮助。
1. 先提取与你的项目有关的内容
从最希望落实的几条建议开始，不必一次处理两本书。
如果 PDF 中的文字可以选中，可以提取相关章节；如果是扫描件，需要先做 OCR。提取后要检查代码、缩进、模板参数和特殊符号，尤其是 <、>、& 等容易识别错误的字符。
可以按资源管理、接口设计或某一种设计模式等主题整理笔记。每条笔记保留以下信息：
- 建议是什么，以及希望解决什么问题。
- 适用条件与不适用条件。
- 一个简短示例。
- 书名、章节或可核对的页码。
只记录能够确认的出处，不要让模型补写不存在的引文或页码。如果先让模型生成摘要，应对照原文检查是否遗漏了例外条件。
2. 把建议改写成可以检查的规则
“遵循书中的最佳实践”过于宽泛。包含触发条件、具体动作和检查方法的规则，agent 更容易执行。
下面是一份自行编写的规则格式示例，用于说明整理方式，不代表上述两本书的原文或结论：
# C++ 项目规则
## 资源管理
适用条件：
- 本次修改涉及文件、内存或其他需要释放的资源。
要求：
- 优先使用能表达资源生命周期的 RAII 类型。
- 新增裸指针时，说明它是否拥有所指对象。
- 引入共享所有权前，说明为何需要多个所有者。
检查：
- 检查提前返回和异常路径上的资源释放。
- 检查是否存在不清晰的所有权转移。
例外：
- 与现有 C API 交互时，可以在边界处处理原始资源句柄，
但应尽可能将释放责任封装到管理资源的类型中。整理设计模式时尤其需要保留适用条件。不要把“理解并考虑某种模式”改写成“所有代码都必须使用这种模式”。
3. 分开保存常用规则和详细笔记
可以采用下面这样的目录结构；这些文件名只是示例，没有通用的自动加载含义：
project/
docs/
ai-context/
project-rules.md
resource-management.md
interface-design.md
design-pattern-notes.md
project-rules.md 保存简短、经常适用的规则。其他文件保存解释、示例、适用条件和出处，按当前任务提供。
如果 agent 支持项目指令文件，应按照该工具规定的文件名、位置和作用范围配置。普通 Markdown 文件即使放在仓库中，也不能据此认定它会自动进入模型上下文。
4. 在具体任务中明确如何使用这些材料
如果工具支持读取工作区文件，可以使用类似下面的提示；否则，将对应内容粘贴或附加到对话中：
请修改指定的 C++ 代码，完成以下需求：
[填写本次需求]
开始前请阅读：
- docs/ai-context/project-rules.md
- docs/ai-context/resource-management.md
这些文件是本次任务的项目约束。
请只应用与本次修改有关的规则。
如果规则与现有接口或需求冲突，请指出具体冲突。
完成后说明采用了哪些规则，并列出需要人工确认的地方。
如果无法读取文件，请明确说明。
建议先用一个小任务验证，检查 agent 是否正确概括了规则，以及代码是否实际符合要求。它声称“已遵循规则”只能作为检查线索，不能替代代码审查、编译和必要的测试。
5. 资料多了以后，再考虑检索
当笔记多到不方便手动选择时，可以考虑检索增强生成，也就是 RAG：按当前任务找到相关片段，再把这些片段作为上下文提供给模型。
切分材料时，尽量让一条规则、它的适用条件和相关示例保持在一起。若只检索到结论，遗漏了限制条件，仍然可能导致错误应用。是否值得搭建检索流程，取决于资料量和 agent 支持的接入方式；少量项目规则通常可以先手动维护。
在对话中提供材料，并不代表模型永久学会了这些建议，也不代表新会话会自动记住。需要长期使用的规则，应保存在可维护的项目文件中，并确认每次任务确实加载了它们。
备注：内容仅供参考。