From 138663c64cfb1c7b376347d99a3ab29bf0797f49 Mon Sep 17 00:00:00 2001 From: liuzhengdong <735083049@qq.com> Date: Wed, 29 Apr 2026 15:03:31 +0800 Subject: [PATCH] feat: add cs-note skill for managing project fragment knowledge in AGENTS.md --- cs-feat-accept/SKILL.md | 2 +- cs-feat-impl/SKILL.md | 2 + cs-issue-fix/SKILL.md | 3 +- cs-note/SKILL.md | 164 ++++++++++++++++++++++++++++++++++++++++ cs/SKILL.md | 4 +- 5 files changed, 172 insertions(+), 3 deletions(-) create mode 100644 cs-note/SKILL.md diff --git a/cs-feat-accept/SKILL.md b/cs-feat-accept/SKILL.md index a20bdbe..5b92da9 100644 --- a/cs-feat-accept/SKILL.md +++ b/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 + 主文档。 diff --git a/cs-feat-impl/SKILL.md b/cs-feat-impl/SKILL.md index 7b130bd..80f1f4d 100644 --- a/cs-feat-impl/SKILL.md +++ b/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 节会兜底盘点。 + --- ## 容易踩的坑 diff --git a/cs-issue-fix/SKILL.md b/cs-issue-fix/SKILL.md index 82b12f8..f18bda8 100644 --- a/cs-issue-fix/SKILL.md +++ b/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。 diff --git a/cs-note/SKILL.md b/cs-note/SKILL.md new file mode 100644 index 0000000..98f2b51 --- /dev/null +++ b/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 +## 项目碎片知识 + + + +### 编译与构建 +- ... + +### 运行与本地起服务 +- ... + +### 测试 +- ... + +### 命令与脚本陷阱 +- ... + +### 路径与目录约定 +- ... + +### 环境变量与凭证 +- ... + +### 其他 +- ... +``` + +**规则**： + +- 新条目去对应分节末尾追加，每条一行（最多两行） +- 没有合适的分节 → 进"其他"。"其他"超过 5 条就停下来和用户讨论是否新增固定分节（不要默默加节） +- 分节为空时整段保留，不删（让 AI 看到这一节是有意义的） +- 注释行 `` 是本技能的识别锚——找不到就在文件末尾插入整块结构 +- **整段长度软上限 ~150 行**——超过提示用户："碎片知识太多了，挑几条沉到 cs-learn / cs-decide 里？" + +--- + +## 流程 + +### 1. 判定该不该进 + +按上面"判据"表对一遍。任一项不过 → 引导到对应别的技能，本轮结束。 + +### 2. 选目标文件 + +按"目标文件"那节判，多文件 / 都没有的情况按规则处理。 + +### 3. 找位置：分节归类 + 查重 + +- 读目标文件，找 `` 锚定位 +- 找不到锚 → 在文件末尾追加整块"项目碎片知识"骨架 +- 在"项目碎片知识"段内 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 反而搞不清哪条是准的 diff --git a/cs/SKILL.md b/cs/SKILL.md index ec1e3d0..1ec7296 100644 --- a/cs/SKILL.md +++ b/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） -判不出问用户："这个你想记成 {踩坑回顾 / 复用处方 / 长期规约 / 调研存档} 哪一种？" +判不出问用户："这个你想记成 {踩坑回顾 / 复用处方 / 长期规约 / 调研存档 / 常驻提示} 哪一种？" ---