cs-note

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cs-note

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

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

cs-learn / cs-trick / cs-decide generate independent markdown files, which are accessed via retrieval; AGENTS.md / CLAUDE.md are persistent contexts that are automatically loaded in every session. These two types of information have different destinations — this skill is dedicated to managing the latter: appending short, stable, and "must-know-every-time" fragments to the resident files.

It does not replace knowledge-precipitation skills, but fills a previously missing entry point.

什么进 cs-note，什么不进

What Goes into cs-note, What Doesn't

判据：长度 + 频次 + 稳定度——三条都过才走 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。

Criteria: Length + Frequency + Stability — all three must be met to go into cs-note.

Item	Goes to cs-note	Goes elsewhere
Length	Can be explained in 1-2 lines	Exceeds half screen / requires background context → cs-learn
Frequency	Needed in almost every session	Only relevant to specific task types → cs-trick
Stability	Long-term hard constraints of the project	Temporary bypass / short-term workaround → write to issue spec or feature spec
Decision Status	Already a fact (no decision records needed)	Need to record selection reasons / rejected solutions → cs-decide

✅ Typical entries that should be added:

"Must run
```
pnpm run gen
```
to generate schema before compilation"
"Must start
```
docker compose up redis
```
before launching local services"
"The project uses yarn berry, do not use
```
npm install
```
"
"Test command is
```
bun test
```
, not
```
npm test
```
"
"src/legacy/ is historical code, consult before modifying"
"
```
OPENAI_KEY
```
is stored in 1Password, do not copy from .env.example"

❌ Typical entries that should NOT be added (will bloat AGENTS.md):

Fix for a specific bug (→ cs-learn pitfall)
Usage of a certain library (→ cs-trick library)
Architecture description (→ codestable/architecture/)
Short-term status like "Working on X this week" (→ do not record, will become outdated)
Content requiring more than 3 lines to explain (→ cs-learn knowledge)

If unsure, ask the user: "Should the AI know this in every future session?" If the answer is "Not necessarily" → it doesn't belong to cs-note.

目标文件

Target Files

按项目实际有的来，不主动新建：

项目根有
```
AGENTS.md
```
→ 写这里
没有但有
```
CLAUDE.md
```
→ 写这里
两个都有 → 默认写
```
AGENTS.md
```
（更通用），除非用户指定
两个都没 → 提示用户："项目还没有 AGENTS.md / CLAUDE.md，要不要我先建一个 AGENTS.md？" 用户同意再建

不写到 codestable/ 下——本技能的全部价值就是利用"自动加载"，写到 codestable/ 里就失去意义。

Follow the actual files in the project, do not create new files proactively:

If
```
AGENTS.md
```
exists in the project root → write here
If
```
AGENTS.md
```
doesn't exist but
```
CLAUDE.md
```
does → write here
If both exist → default to
```
AGENTS.md
```
(more universal), unless specified by the user
If neither exists → prompt the user: "The project doesn't have AGENTS.md / CLAUDE.md yet. Would you like me to create an AGENTS.md first?" Only create if the user agrees

Do not write under codestable/ — the entire value of this skill lies in leveraging "automatic loading"; writing under codestable/ would lose its purpose.

固定分节结构

Fixed Section Structure

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

markdown

undefined

To prevent the file from becoming bloated, the sections are fixed (do not create new sections outside the list):

markdown

undefined

项目碎片知识

Project Fragment Knowledge

编译与构建

Compilation & Building

运行与本地起服务

Running & Local Service Setup

测试

Testing

命令与脚本陷阱

Command & Script Pitfalls

路径与目录约定

Path & Directory Conventions

环境变量与凭证

Environment Variables & Credentials

其他

Others


**规则**：

- 新条目去对应分节末尾追加，每条一行（最多两行）
- 没有合适的分节 → 进"其他"。"其他"超过 5 条就停下来和用户讨论是否新增固定分节（不要默默加节）
- 分节为空时整段保留，不删（让 AI 看到这一节是有意义的）
- 注释行 `<!-- cs-note managed -->` 是本技能的识别锚——找不到就在文件末尾插入整块结构
- **整段长度软上限 ~150 行**——超过提示用户："碎片知识太多了，挑几条沉到 cs-learn / cs-decide 里？"

---


**Rules**:

- Append new entries to the end of the corresponding section, one entry per line (max two lines)
- If no suitable section exists → put in "Others". If "Others" has more than 5 entries, stop and discuss with the user whether to add a new fixed section (do not add sections silently)
- Keep empty sections intact, do not delete them (so the AI recognizes the section is meaningful)
- The comment line `<!-- cs-note managed -->` is the identification anchor for this skill — if not found, insert the entire structure at the end of the file
- **Soft upper limit for total length ~150 lines** — if exceeded, prompt the user: "There are too many fragment knowledge entries. Would you like to move some to cs-learn / cs-decide?"

---

流程

Process

1. 判定该不该进

1. Determine Eligibility

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

Check against the "Criteria" table above. If any criterion is not met → guide to the corresponding other skill and end this round.

2. 选目标文件

2. Select Target File

按"目标文件"那节判，多文件 / 都没有的情况按规则处理。

Follow the rules in the "Target Files" section, handle cases with multiple files or no files accordingly.

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

3. Locate Position: Section Classification + Duplication Check

读目标文件，找
```

```
锚定位
找不到锚 → 在文件末尾追加整块"项目碎片知识"骨架
在"项目碎片知识"段内 grep 关键词查重——已有相似条目时不另起一条，问用户"是更新已有那条还是确实是另一条"
选好分节，没有合适分节进"其他"

Read the target file and locate the
```

```
anchor
If the anchor is not found → append the entire "Project Fragment Knowledge" skeleton at the end of the file
Search for keywords within the "Project Fragment Knowledge" section to check for duplicates — if a similar entry already exists, do not add a new one, ask the user: "Would you like to update the existing entry or add this as a separate one?"
Select the appropriate section, or use "Others" if no suitable section exists

4. 写一条进去

4. Add an Entry

每条格式：

- {一句话事实 + 必要时一句话原因}

例：

- 编译前要先 `pnpm run gen`，否则 schema 类型对不上
- 别用 `npm install`，项目锁文件是 yarn berry 的
- src/legacy/ 是 2023 前的老代码，改之前先和 @ldz 确认

写完用户 review 一句确认就退出。不主动连写多条——一次一条，避免顺手把没拍板的也塞进去。

Format for each entry:

- {one-sentence fact + one-sentence reason if necessary}

Examples:

- Must run `pnpm run gen` before compilation, otherwise schema types will not match
- Do not use `npm install`, the project's lock file is for yarn berry
- src/legacy/ is old code from before 2023, confirm with @ldz before modifying

Exit after the user reviews and confirms. Do not proactively add multiple entries at once — one entry per time, to avoid including unconfirmed content.

5. 触发软上限检查

5. Trigger Soft Upper Limit Check

写完看一眼"项目碎片知识"段总行数：

≥150 行 → 提示用户挑几条沉到 cs-learn / cs-decide
"其他"分节 ≥5 条 → 提示用户讨论是否新增固定分节

只是提示，不替用户决定。

After adding, check the total number of lines in the "Project Fragment Knowledge" section:

≥150 lines → prompt the user to move some entries to cs-learn / cs-decide
"Others" section has ≥5 entries → prompt the user to discuss adding a new fixed section

This is only a prompt, do not make decisions for the user.

主动推荐时机

Proactive Recommendation Timing

不要每次都问。只在两个明确信号触发时推一句：

用户在对话中说出明显属于碎片知识的事实——"哦对这个项目要先 X 才能 Y"、"我们这个用 Z 不用 W"——推："这条要不要
```
cs-note
```
一下？以后 AI 每次都能看到。"
AI 自己刚踩了一个一句话能讲清的项目特殊设置（编译失败 / 命令不对 / 路径找错）——修复后推："这个坑是项目通用的吗？是的话
```
cs-note
```
记一笔，下次会话直接知道。"

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

Do not ask every time. Only recommend when two clear signals are triggered:

The user mentions a fact that clearly belongs to fragment knowledge — "Oh right, this project requires X to do Y", "We use Z instead of W here" → recommend: "Would you like to
```
cs-note
```
this? The AI will see it every time in future sessions."
The AI just encountered a project-specific setting that can be explained in one sentence (compilation failure / incorrect command / wrong path) → after fixing, recommend: "Is this a universal pitfall for the project? If yes,
```
cs-note
```
it so the AI knows it directly in the next session."

If the user says "No thanks", skip immediately and do not repeat the recommendation.

容易踩的坑

Common Pitfalls

把详细背景 / 多步骤指南塞进 AGENTS.md——超过两行就该走 cs-learn
写到 codestable/ 下——失去"自动加载"的价值，本技能就是为了写到根目录常驻文件
默默新增分节——分节是写死的，新增要先和用户讨论
看到一条就连带把其他几条也写进去——一次一条
写"短期状态"（本周在做 X / 这个 sprint 的目标）——会过期但没人删，慢慢变误导
不查重就追加——同一条事实被记 3 次后 AI 反而搞不清哪条是准的

Putting detailed background / multi-step guides into AGENTS.md — content longer than two lines should go to cs-learn
Writing under codestable/ — loses the value of "automatic loading", this skill is designed to write to root directory resident files
Adding new sections silently — sections are fixed, discuss with the user before adding new ones
Adding multiple entries together when seeing one — add one entry at a time
Writing "short-term status" (working on X this week / sprint goals) — will become outdated and misleading over time
Appending without checking for duplicates — if the same fact is recorded 3 times, the AI will get confused about which is accurate