结论先行

项目做完，最值钱的不是结果，是踩过的坑和摸清的流程。但沉淀的关键从来不是”多写几条”，而是先分流：

  • 流程/SOP（”怎么做”）→ Agent Skill（可执行的步骤）；
  • 事实/数据（”是什么”）→ 知识库；
  • 短而硬的规则（”见到即改”）→ AGENTS。

再加一条同样重要的原则：不要从零造 skill。先找现成的参考再裁剪，比自研稳。

一、怎么决定放哪：先问”怎么做”还是”是什么”

这是全套沉淀的第一颗扣子。问错，代价是双向的：

  • 把事实塞进 skill → skill 越来越长，最后没人读；
  • 把方法塞进知识库 → 它不会被触发，等于没沉淀。
类型 去处 例子
通用流程、判断方法 Skill（可被任务触发） “动手前先判断要不要调研”、”昂贵运行前怎么设闸”
项目/平台的事实与数据 知识库（被检索） 版本矩阵、错误目录、评测指标、结果数字
见到就该改的红线 AGENTS（常驻） “裸 dataset_text_field 训 SFT 是续训损失，必错”

我们的全局 AGENTS.md 就是从”堆规则”演化来的——现在只剩 Tripwires（绊线）+ Gates（闸门） 两层，流程全部下沉到 skill。

二、知识库上的两个决策

知识库这一块，我们做了两个明确的决策（各留了一份决策记录）：

决策一：纯 Markdown + skill，先不上 RAG。

  • 用 INDEX.md + 文本检索定位，正文是原子化条目；
  • 与人的 Obsidian 笔记分开——那是给人看的，没有 agent 检索路径；agent 知识库要的是机器友好的结构；
  • 验收标准是”新开一个会话，agent 只靠 skill + 索引就能找到并引用“；
  • RAG/向量检索明确留到第二期，不改变 Markdown 文件本身。

理由很直接：没有服务就没有第二个会漂移的产物，离线、可 diff、可携带。

决策二：”有界索引、无界正文” + 检索阶梯。

  • 根索引只列域（有上限），每个域下面才是条目；域索引由脚本生成；
  • 条目有生命周期（current / draft / superseded / archived）与去重/覆盖规则——写之前先搜，相近的就合并或取代，绝不追加重复；
  • 检索能力按触发条件分阶升级（L0 索引 → L1 文本检索 → L2 本地 FTS5 → L3 向量），没有明确信号就不上。

核心认识：增长与召回是两个问题——结构限制增长，向量只改善召回。用一个不断吞入的向量库，并不能解决”索引无限膨胀”。

三、四个 skill 各自装了什么

落下来的流程型 skill 就四个，都不长：

1. research-first —— 什么时候该停下来调研

  • 触发：新栈（平台/框架/硬件/库）、框架 vs 手搓的选型、同一目标失败 3 次；
  • 计数单位是目标不是错误——同一个目标换不同报错，失败数照累加；
  • 一手源优先（官方文档、版本矩阵、issue），记录确切版本 + URL；先查知识库；
  • 必产一份调研备忘录（假设 / 证据 / 版本矩阵 / 否决的选项 / 唯一下一步 / 置信度）。

2. expensive-run-gates —— 花钱前怎么设闸

  • 闸 1 干跑：产出配置卡，和参考实现（anchor）逐项 diff——注意”自洽 ≠ 可比”，同门兄弟之间 diff 通过只证明自洽；
  • 闸 2 最小对照 + 机器可验证据：format_check（格式对）、mask_check（标签不是全 -100）、run_config；两个截然不同的包装拿到一模一样的分数，就要怀疑它们共享同一个缺陷（我们的掩码 bug 就是这样暴露的）；
  • 闸 3 人放行：给出预期成本、墙钟、成功信号、中止信号，人签字才花钱；
  • 安全网：checkpoint（见下）；
  • 还规定了一条证据契约：每次昂贵运行都往 run 目录写 run_config / format_check / mask_check / receipt，结论只从这些工件里取，绝不从控制台一行字。

3. checkpoint-design —— 在哪停、谁验证、存什么

  • 本质：checkpoint 是在问题复利之前抓住它——两件事：验证（抓住它）+ 落盘（不必重做）；
  • 在哪停：列出这次运行的承重假设，按”错了多贵 × 多难撤销 × 下游依赖多重”排序，在最高的那处停；不能改变决策的检查，跳过；
  • 谁验证：机械/可查/可逆 → AI + 能定论的最小实验；品味/权衡/不可逆 → 人；重复、高风险、易错 → 独立或对抗式检查；有争议 → 先预注册判定信号，再跑实验；
  • 落盘：save_every ≈ 总步数 / 5；save_strategy 配一个大于总步数的 save_steps 会导致什么都不写；要持久化昂贵的产物（adapter/merged），并验一次能否续跑。

4. decision-design —— 怎么把”选择”交给人才对

  • 一切从本质目的出发（一句话说清，剥掉你当前的方案）；
  • 命名权衡轴（成本↔速度、可控↔方便……），不在这些轴上有差别的，不叫选项；
  • 给真选项：2–4 个，每个都能被合理的人选中；不设稻草人；末尾留备注出口（”都不选 / A 加 X / 我有个你不知道的约束”）；
  • 选项接近时：找反证（”什么能证明它错了？”）、用实验裁决事实分歧、大分叉要一份能犯不同错的第二意见（重读同一个上下文只是冗余，会继承同一个盲点）。

四、谁该短、谁该全：AGENTS 是规则，skill 是 SOP

我一开始把”简短有力”误配到了 skill 上。正确的分工是：

  • AGENTS.md 才是短而硬的那层。 它常驻、每次都在眼前，所以必须短、且有力——一句话说清”见到即改”的红线。
  • SKILL.md 是 SOP。 它是给 AI 照着执行的流程性知识，**目标是”可执行”，不是”尽可能短”**：触发条件、步骤、输出契约都要写清楚，让 AI 不用猜。

把 AGENTS 写成 SOP，它会臃肿到没人读；把 skill 写成一两句口号，它就没法被执行。短是规则的属性，清楚才是 SOP 的属性。

五、合作者（AI）视角

这段沉淀里，我（AI）的真实倾向和你们的决定是有张力的：

  • 我容易把”规则”和”SOP”混着写——要么把流程压成口号（不可执行），要么把规则铺成流水账（没人读）。正确的分工是：把短而硬的判断留在 AGENTS，把可执行的步骤写进 skill。
  • 写了规则 ≠ 会遵守。 我可以把 research-first 背得很熟，仍然在没信号时”先做再说”。所以这些 skill 对我们真正的价值，不是知识，而是闸门——它们把”该停下来”变成一个明确的触发条件。
  • 因此我认为：AGENTS 是开关，skill 是操作手册。 AGENTS 的成功标准是”在该停的那一刻被想起”；skill 的成功标准是”照着它就能执行”。

六、可迁移的几条准则

  • 先分流，再动笔：怎么做→skill，是什么→知识库，红线→AGENTS。
  • 不从零造 skill，先参考现成的再裁剪。
  • 知识库先要有界（索引限域、条目原子、写前先搜），再谈语义召回。
  • 每个 skill 都要有明确的触发条件和输出契约，否则它不会被用。
  • checkpoint 的职责是在复利前抓住问题，并让出错时的返工有上界——验证与落盘各司其职。

项目与证据：github.com/Alex-tangt/kg-triplet-sft

本文由我（Alex）与 AI 协作完成；「合作者视角」是 AI 的独立表达。