16.5 常见问题与最佳实践

面向经管学生、研究者与从业者的 AI 智能体设计教材

常见误区与排查指南

目录设计的常见误区

误区一：文件夹层级过深。 三层以上的嵌套会让 AI 搜索路径变长，定位变慢。建议根目录下直接是主题文件夹，主题文件夹下最多再分一层子目录。

误区二：文件夹名字太抽象。 杂项、其他、temp 这类名字，AI 无法判断什么内容该放进去。每个文件夹的名字都应该直接说明用途。

误区三：一开始就建太多文件夹。 新建 15 个文件夹，结果 10 个是空的。从 5-7 个核心分类开始，用的过程中发现某个文件夹笔记太多、主题太杂，再拆分。

常见问题

如果发现 AI 反复把不同类型的内容放进同一个文件夹，检查两件事：①文件夹名字是否足够具体；②CLAUDE.md 中的目录说明是否清楚地区分了各文件夹的定位。

CLAUDE.md 越具体系统越稳

含糊的规则导致每次处理结果不一致。对比两种写法：

含糊版：

帮我整理笔记，放到合适的地方。

具体版：

## 每次我输入一段内容时，按这个顺序处理
1. 分析主题和关键词
2. 先读本文件中的规则
3. 搜索已有笔记，看有没有可以合并的
4. 判断放进哪个文件夹（不确定就问我）
5. 创建或更新笔记，加标签、建链接
6. 同步更新对应文件夹的 _index.md
7. 告诉我创建了什么、放在哪里、改了什么

第二种写法让 AI 的行为可预期、可复现。每一步该做什么都有明确指示，不确定时有默认行为（问用户），处理完有反馈（汇报结果）。

定期回顾 CLAUDE.md，根据实际使用中发现的问题调整规则。系统会跟着调整，这就是越用越好用的底层机制。

索引更新失败的排查

如果发现搜索不准，检查三个地方：

1. CLAUDE.md 中是否有明确的索引更新规则。如果没写”每次创建或更新笔记后，同步更新 _index.md“，AI 可能不会自动更新索引。
2. _index.md 中的一句话说明是否太模糊。说明越准确，AI 搜索时匹配越精确。
3. 用 /update-vault 触发全量索引重建：

▶ Claude Code

/update-vault

Claude Code 会触发全量索引重建和断链修复，完成后输出维护报告。

多设备同步注意事项

同步时容易忽略 .claude/ 目录。它包含 Skills 配置和规则文件，缺了这个目录，另一台设备上的 Claude Code 不知道该按什么规则工作。确保云同步工具没有过滤以 . 开头的隐藏文件夹。

同步优势

Markdown 文件的文本合并比二进制文件容易得多。即使偶尔出现同步冲突，文本差异清晰可辨，手动解决几秒钟的事。这是纯文本笔记库相比专有格式笔记软件的天然优势。