cs-note
cs-learn / cs-trick / cs-decide 产出独立 markdown 文件，通过检索被读到；AGENTS.md / CLAUDE.md 是每次会话自动加载的常驻上下文。这两类信息归宿不同——本技能专管后者：把"短、稳、每次都要知道"的碎片追加到常驻文件里。
不替代沉淀类技能，是补一个之前缺的入口。
什么进 cs-note，什么不进
判据：长度 + 频次 + 稳定度——三条都过才走 cs-note。
| 项 | 进 cs-note | 走别处 |
|---|---|---|
| 长度 | 一两行能讲清 | 超过半屏 / 需要展开背景 → cs-learn |
| 频次 | 几乎每次会话都用得上 | 只在某类具体任务相关 → cs-trick |
| 稳定度 | 项目长期生效的硬约束 | 临时绕过 / 短期 workaround → 写到 issue spec 或 feature spec |
| 拍板状态 | 已既成事实（不需要决策记录） | 需要记选型理由 / 拒方案 → cs-decide |
✅ 典型该进：
- "编译要先
pnpm run gen生成 schema" - "本地起服务前必须
docker compose up redis" - "项目用 yarn berry，别用
npm install" - "测试命令是
bun test，不是npm test" - "src/legacy/ 是历史代码，改之前先问"
- "
OPENAI_KEY走 1Password，别从.env.example 复制"
❌ 典型不该进（会让 AGENTS.md 膨胀）：
- 某个 bug 的修法（→ cs-learn pitfall）
- 某个库怎么用（→ cs-trick library）
- 一段架构说明（→ codestable/architecture/）
- "本周在做 X"这种短期状态（→ 别记，会过期）
- 需要 3 行以上才讲清的（→ cs-learn knowledge）
判不准就反问用户一句："这条以后是不是每次会话都要让 AI 知道？"答"不一定" → 不是 cs-note。
目标文件
按项目实际有的来，不主动新建、不替用户拍偏好：
- 项目根只有一个（
AGENTS.md或CLAUDE.md）→ 写已有的那个，不问 - 两个都有 → 问用户 "本次写到
AGENTS.md还是CLAUDE.md？" 等用户回复再动 - 两个都没 → 问用户 "项目还没有常驻上下文文件，要建哪个？
AGENTS.md/CLAUDE.md/ 其他文件名（如.cursorrules）？" 用户答复后再建
不主动定默认——AI 工具自己注入的提示词会告诉模型该读哪个，工具偏好该由用户和工具决定，cs-note 不替用户预设。
不写到 codestable/ 下——本技能的全部价值就是利用"自动加载"，写到 codestable/ 里就失去意义。
固定分节结构
为了防止文件膨胀成另一个胖文件，分节写死一组（不在列表里的不开新节）：
## 项目碎片知识
<!-- cs-note managed: 用 cs-note 维护，新条目按下面分节追加 -->
### 编译与构建
- ...
### 运行与本地起服务
- ...
### 测试
- ...
### 命令与脚本陷阱
- ...
### 路径与目录约定
- ...
### 环境变量与凭证
- ...
### 其他
- ...规则：
- 新条目去对应分节末尾追加，每条一行（最多两行）
- 没有合适的分节 → 进"其他"。"其他"超过 5 条就停下来和用户讨论是否新增固定分节（不要默默加节）
- 分节为空时整段保留，不删（让 AI 看到这一节是有意义的）
- 注释行
<!-- cs-note managed -->是本技能的识别锚——找不到就在文件末尾插入整块结构 - 整段长度软上限 ~150 行——超过提示用户："碎片知识太多了，挑几条沉到 cs-learn / cs-decide 里？"
流程
1. 判定该不该进
按上面"判据"表对一遍。任一项不过 → 引导到对应别的技能，本轮结束。
2. 选目标文件
按"目标文件"那节判，多文件 / 都没有的情况按规则处理。
3. 找位置：分节归类 + 查重
- 读目标文件，找
<!-- cs-note managed -->锚定位 - 找不到锚 → 在文件末尾追加整块"项目碎片知识"骨架
- 在"项目碎片知识"段内 grep 关键词查重——已有相似条目时不另起一条，问用户"是更新已有那条还是确实是另一条"
- 选好分节，没有合适分节进"其他"
4. 写一条进去
每条格式：
- {一句话事实 + 必要时一句话原因}例：
- 编译前要先 `pnpm run gen`，否则 schema 类型对不上
- 别用 `npm install`，项目锁文件是 yarn berry 的
- src/legacy/ 是 2023 前的老代码，改之前先和 @ldz 确认写完用户 review 一句确认就退出。不主动连写多条——一次一条，避免顺手把没拍板的也塞进去。
5. 触发软上限检查
写完看一眼"项目碎片知识"段总行数：
- ≥150 行 → 提示用户挑几条沉到 cs-learn / cs-decide
- "其他"分节 ≥5 条 → 提示用户讨论是否新增固定分节
只是提示，不替用户决定。
主动推荐时机
不要每次都问。只在两个明确信号触发时推一句：
- 用户在对话中说出明显属于碎片知识的事实——"哦对这个项目要先 X 才能 Y"、"我们这个用 Z 不用 W"——推："这条要不要
cs-note一下？以后 AI 每次都能看到。" - AI 自己刚踩了一个一句话能讲清的项目特殊设置（编译失败 / 命令不对 / 路径找错）——修复后推："这个坑是项目通用的吗？是的话
cs-note记一笔，下次会话直接知道。"
用户说"不用了"立刻跳过，不重复推。
容易踩的坑
- 把详细背景 / 多步骤指南塞进 AGENTS.md——超过两行就该走 cs-learn
- 写到 codestable/ 下——失去"自动加载"的价值，本技能就是为了写到根目录常驻文件
- 默默新增分节——分节是写死的，新增要先和用户讨论
- 看到一条就连带把其他几条也写进去——一次一条
- 写"短期状态"（本周在做 X / 这个 sprint 的目标）——会过期但没人删，慢慢变误导
- 不查重就追加——同一条事实被记 3 次后 AI 反而搞不清哪条是准的