feat: add cs-note skill for managing project fragment knowledge in AGENTS.md

cs-feat-accept/SKILL.md

@@ -224,7 +224,7 @@ req 是现状档案，本节是 req 落档 / 刷新的**唯一时机**。对照
 2. 长期约束 / 技术选型 → "需要归档决定吗？（`cs-decide`）"
 3. 接口变更 / 用户可见行为变更 → "需要更新指南吗？（`cs-guide`）"
 4. 库公开接口（组件 / 函数 / 命令）变了 → "需要更新 API 参考吗？（`cs-libdoc`）"
-5. 第 8 节有 AGENTS.md / CLAUDE.md 候选 → 逐条问"候选 X 加到 {AGENTS.md / CLAUDE.md} 吗？" 用户明确同意才写入；**不擅自合并多条一起加**
+5. 第 8 节有 AGENTS.md / CLAUDE.md 候选 → 逐条问"候选 X 加到 {AGENTS.md / CLAUDE.md} 吗？" 用户明确同意 → 触发 `cs-note` 走分节归类 / 查重 / 软上限检查（不在 accept 里手写，避免和 cs-note 各搞一套口径）；**一次一条**
 6. 最后问是否代为 scoped-commit
 
 收尾提交规则看 `shared-conventions.md` 第 4 节。提交范围：功能代码 + 方案 doc + 验收报告 + 本次实际更新的架构 doc / req doc / roadmap items.yaml + 主文档。

cs-feat-impl/SKILL.md

@@ -186,6 +186,8 @@ design 给的 `steps` 是 paradigm 维度切片（编排骨架 → 计算节点
 
 别自己顺手开始写验收报告——验收需要独立的 checklist 节奏，提前进入会让把关失效。
 
+**实现过程中如果踩到了项目通用的硬约束 / 命令陷阱 / 环境设置**（"啊原来这个项目要先 X 才能 Y"，一两行能讲清、下个 feature 的 AI 还会再撞一次）→ 在告诉用户去 accept 前**顺便提一句**："这次发现 {具体那条}，是不是要 `cs-note` 一下加到 AGENTS.md，免得下次再踩？"——单条即可，不连写多条；用户说"等 accept 一起处理" 就跳过，accept 第 8 节会兜底盘点。
+
 ---
 
 ## 容易踩的坑

cs-issue-fix/SKILL.md

@@ -123,7 +123,8 @@ issue-fix 比 feature-implement 更谨慎：**触发反射信号但结论是"该
 
 1. 暴露了值得复用的坑点 → "沉淀 learning？（`cs-learn`）"
 2. 沉淀出长期约束 / 规约 / 技术决定 → "归档决定？（`cs-decide`）"
-3. 最后问是否代为提交。同意时按收尾提交规则执行
+3. 这个 bug 暴露了项目通用的硬约束 / 命令陷阱 / 环境设置（一两行能讲清、AI 每次会话都该知道）→ "记到 AGENTS.md？（`cs-note`）"
+4. 最后问是否代为提交。同意时按收尾提交规则执行
 
 建议：把 issue 目录文件和代码改动放同一次提交方便追溯；"顺手发现"另开 `cs-issue-report` 处理别塞这个 PR。
 

cs-note/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: cs-note
+description: 把"短到不值得起一份文件、但 AI 每次都需要知道"的项目碎片知识追加到 AGENTS.md / CLAUDE.md 的固定分节里——比如编译特殊 flag、运行前要先起的服务、路径陷阱、命令别名、环境变量约定。触发：用户说"记一笔"、"加到 AGENTS"、"记到 CLAUDE.md"、"项目要 X 才能编译"、"以后每次都得 Y"，或刚踩到一个一句话能讲清的项目特殊设置。
+---
+
+# 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`（更通用），除非用户指定
+- 两个都没 → 提示用户："项目还没有 AGENTS.md / CLAUDE.md，要不要我先建一个 AGENTS.md？" 用户同意再建
+
+**不写到 codestable/ 下**——本技能的全部价值就是利用"自动加载"，写到 codestable/ 里就失去意义。
+
+---
+
+## 固定分节结构
+
+为了防止文件膨胀成另一个胖文件，分节**写死**一组（不在列表里的不开新节）：
+
+```markdown
+## 项目碎片知识
+
+<!-- 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 条 → 提示用户讨论是否新增固定分节
+
+只是**提示**，不替用户决定。
+
+---
+
+## 主动推荐时机
+
+不要每次都问。只在两个明确信号触发时推一句：
+
+1. **用户在对话中说出明显属于碎片知识的事实**——"哦对这个项目要先 X 才能 Y"、"我们这个用 Z 不用 W"——推："这条要不要 `cs-note` 一下？以后 AI 每次都能看到。"
+2. **AI 自己刚踩了一个一句话能讲清的项目特殊设置**（编译失败 / 命令不对 / 路径找错）——修复后推："这个坑是项目通用的吗？是的话 `cs-note` 记一笔，下次会话直接知道。"
+
+用户说"不用了"立刻跳过，不重复推。
+
+---
+
+## 容易踩的坑
+
+- 把详细背景 / 多步骤指南塞进 AGENTS.md——超过两行就该走 cs-learn
+- 写到 codestable/ 下——失去"自动加载"的价值，本技能就是为了写到根目录常驻文件
+- 默默新增分节——分节是写死的，新增要先和用户讨论
+- 看到一条就连带把其他几条也写进去——一次一条
+- 写"短期状态"（本周在做 X / 这个 sprint 的目标）——会过期但没人删，慢慢变误导
+- 不查重就追加——同一条事实被记 3 次后 AI 反而搞不清哪条是准的

cs/SKILL.md

@@ -76,6 +76,7 @@ codestable/
 | 技术选型 / 长期约束 / 编码规约 | `cs-decide` |
 | 踩坑回顾 / 经验总结 / "值得记下来" | `cs-learn` |
 | 可复用编程模式 / 库用法 / "以后做 X 就该这样" | `cs-trick` |
+| 一两行的项目硬约束 / 编译特殊设置 / 命令陷阱 / "记到 AGENTS.md" | `cs-note` |
 | 开发者指南 / 用户指南 | `cs-guide` |
 | 库 API 参考 | `cs-libdoc` |
 | 用户在 feature / issue 流程中间问"下一步" | 路由到对应入口（`cs-feat` / `cs-issue`），让该入口判断当前阶段 |
@@ -113,8 +114,9 @@ codestable/
 - 处方"以后做 X 就这样做" → `cs-trick`
 - 规定"全项目今后都按 X 来" → `cs-decide`
 - 调查"X 现在是什么样" → `cs-explore`
+- 一两行常驻提示"AI 每次都得知道 X" → `cs-note`（写到 AGENTS.md / CLAUDE.md）
 
-判不出问用户："这个你想记成 {踩坑回顾 / 复用处方 / 长期规约 / 调研存档} 哪一种？"
+判不出问用户："这个你想记成 {踩坑回顾 / 复用处方 / 长期规约 / 调研存档 / 常驻提示} 哪一种？"
 
 ---