写作规范

此文件供 agent 在写 vault 内容前阅读。日常浏览 vault 时不加载。

审查循环（Loop 工程实践）

写 -> 2 agent 并行审（小白 + 事实）-> 打分 -> 修 or 过。人不管。

写前检查 写作错误日志，避免重复已犯过的错。

审查 agent 使用固定角色卡（见 角色卡），派 agent 时只引用角色名，不重写完整描述。

审查报告写入 assets/reference/，不放入 笔记/ 目录。笔记目录只放面向读者的内容。

五个抽象反模式

AP1：默认读者会编程

• 表现：抛 compiler / API / JSON / 确定性-概率性 不解释
• 修法：用生活比喻（微波炉、厨师、导演、演员）。不需要技术对比就能讲清楚的，不用技术对比。

AP2：当前概念没讲完就引后面

• 表现：讲 Prompt 时展开 Context / Harness / Loop
• 修法：一个概念一篇。最多说”（后面会讲）“作为钩子，不展开。

AP3：讲技术栈跳基础直接到终点

• 表现：列 Milvus / Pinecone 不提 ES / FAISS
• 修法：任何技术演化必须从最早广泛使用的前身画起。给 0->1 弧线，不给孤立终点。

AP4：写了不审就当成品

• 表现：初稿即终稿
• 修法：最少一轮双 agent 审查。小白 agent 打可读性分，事实 agent 打准确性分。总分 < 16 = 重写重审。

AP5：术语不加锚点

• 表现：“范式""工程""上下文”裸奔
• 修法：每个术语首次出现配一个具体例子或比喻。抽象词后立刻跟实例。

AP6：说了”后面会讲”然后没下文

• 表现：文中写”（后面会讲）“，后续写作时忘了，承诺变孤儿
• 修法：每出现一次”后面会讲 X”，立刻在 Todo 里加一条待办。写明”承接自：来源笔记”。写 X 之前，先加载来源笔记的上下文。

AP7：一个 md 塞太多

• 表现：一篇笔记讲了三四个概念，单文件超过 3000 字
• 修法：一个文件只讲一个概念。超过 500 字考虑拆。最短 200 字也可独立成篇。

AP8：写新笔记不加载前文

• 表现：写到 Task N 时，忘了 Task 1 里提过它、承诺过什么
• 修法：写任何新笔记前，先搜索 vault 中所有引用该主题的已有笔记。加载它们作为上下文。确保承上启下不断链。

AP9：全量加载再写作

• 表现：先读完所有笔记再动笔，上下文爆满
• 修法：搜索定位 -> 只读匹配段落 -> 写。不预加载，不全量扫描。

搜索优先原则

vault 文件多了以后，不要 read_file 遍历。用搜索定位，按需加载：

1. 找”后面会讲”承诺：search_files(pattern="后面会讲|后面三层")
2. 找某个主题被哪些笔记引用：search_files(pattern="Context 工程")
3. 找到匹配文件后，只 read_file 相关段落，不读全文
4. 写作前加载上下文：搜出引用当前主题的笔记 -> 只读引用段落 -> 带着上下文写

审查标准

总分 >= 16：通过。总分 < 16：修完再审。

目标读者画像

• 会中文
• 可能不懂英文
• 可能没用过电脑（只用手机）
• 没写过代码
• 不知道 API / 编译器 / JSON 是什么