cs-note

启动必读

开始任何判断或动作前，先检查 .codestable/attention.md：存在就读取；缺 .codestable/ 就提示先运行 cs-onboard；只有 attention.md 缺失时，本技能可以先创建固定分节骨架再写入。不要回退到外部 AI 入口文件。

cs-learn / cs-trick / cs-decide 产出独立 markdown 文件，通过检索被读到；.codestable/attention.md 是 CodeStable 技能启动时的强制必读上下文。这两类信息归宿不同——本技能专管后者：把"短、稳、每次都要知道"的碎片追加到 attention 文件里。

不替代沉淀类技能，是补一个之前缺的入口。

什么进 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 复制"

❌ 典型不该进（会让 attention.md 膨胀）：

• 某个 bug 的修法（→ cs-learn pitfall）

• 某个库怎么用（→ cs-trick library）

• 一段架构说明（→ .codestable/architecture/）

• "本周在做 X"这种短期状态（→ 别记，会过期）

• 需要 3 行以上才讲清的（→ cs-learn knowledge）

判不准就反问用户一句："这条以后是不是每次会话都要让 AI 知道？"答"不一定" → 不是 cs-note。

目标文件

目标文件固定为 .codestable/attention.md。不再兼容 AGENTS.md / CLAUDE.md / .cursorrules 等外部 AI 工具入口。

• .codestable/ 不存在 → 本仓库还没接入 CodeStable，先提示用户运行 cs-onboard

• .codestable/attention.md 不存在 → 视为骨架缺失，先创建最小骨架再写入

• AGENTS.md / CLAUDE.md 即使存在也不读取、不写入、不询问用户偏好

attention.md 是 CodeStable 自己的启动注意事项入口，价值来自所有 CodeStable 技能都明确要求读取它，而不是依赖外部工具的自动注入。

固定分节结构

为了防止文件膨胀成另一个胖文件，分节写死一组（不在列表里的不开新节）：

## 项目碎片知识

<!-- cs-note managed: 用 cs-note 维护，新条目按下面分节追加 -->

### 编译与构建

### 运行与本地起服务

### 测试

### 命令与脚本陷阱

### 路径与目录约定

### 环境变量与凭证

### 其他

规则：

• 新条目去对应分节末尾追加，每条一行（最多两行）

• 没有合适的分节 → 进"其他"。"其他"超过 5 条就停下来和用户讨论是否新增固定分节（不要默默加节）

• 分节为空时整段保留，不删（让 AI 看到这一节是有意义的）

• 注释行 <!-- cs-note managed --> 是本技能的识别锚——找不到就在文件末尾插入整块结构

• 整段长度软上限 ~150 行——超过提示用户："碎片知识太多了，挑几条沉到 cs-learn / cs-decide 里？"

流程

1. 判定该不该进

按上面"判据"表对一遍。任一项不过 → 引导到对应别的技能，本轮结束。

2. 确认 attention 文件

检查 .codestable/attention.md。缺 .codestable/ 就停止并提示先 cs-onboard；只缺 attention.md 就创建本技能的固定分节骨架。

3. 找位置：分节归类 + 查重

• 读 .codestable/attention.md，找 <!-- 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 记一笔，下次会话直接知道。"

用户说"不用了"立刻跳过，不重复推。

容易踩的坑

• 把详细背景 / 多步骤指南塞进 attention.md——超过两行就该走 cs-learn

• 写到 AGENTS.md / CLAUDE.md——CodeStable 不再兼容这些外部入口

• 默默新增分节——分节是写死的，新增要先和用户讨论

• 看到一条就连带把其他几条也写进去——一次一条

• 写"短期状态"（本周在做 X / 这个 sprint 的目标）——会过期但没人删，慢慢变误导

• 不查重就追加——同一条事实被记 3 次后 AI 反而搞不清哪条是准的