k-note

k-note

启动必读

开始任何判断或动作前，先检查 .kflow/attention.md：存在就读取；缺 .kflow/ 就提示先运行 k-onboard；只有 attention.md 缺失时，本技能可以先创建固定分节骨架再写入。

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

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

---

什么进 k-note，什么不进

判据：长度 + 频次 + 稳定度——三条都过才走 k-note。

项	进 k-note	走别处
长度	一两行能讲清	超过半屏 / 需要展开背景 → k-learn
频次	几乎每次会话都用得上	只在某类具体任务相关 → k-trick
稳定度	项目长期生效的硬约束	临时绕过 / 短期 workaround → 写到 issue spec 或 feature spec
拍板状态	已既成事实（不需要决策记录）	需要记选型理由 / 拒方案 → k-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 的修法（→ k-learn pitfall）
• 某个库怎么用（→ k-trick library）
• 一段架构说明（→ .kflow/architecture/）
• "本周在做 X"这种短期状态（→ 别记，会过期）
• 需要 3 行以上才讲清的（→ k-learn knowledge）

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

---

目标文件

目标文件固定为 .kflow/attention.md。

• .kflow/ 不存在 → 本仓库还没接入 kflow，先提示用户运行 k-onboard
• .kflow/attention.md 不存在 → 视为骨架缺失，先创建最小骨架再写入

attention.md 是项目注意事项的唯一权威源。跨平台 AI 通过 AGENTS.md（k-onboard 生成）发现并读取它。

---

固定分节结构

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

## 项目碎片知识

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

### 编译与构建

### 运行与本地起服务

### 测试

### 命令与脚本陷阱

### 路径与目录约定

### 环境变量与凭证

### 其他

规则：

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

---

流程

1. 判定该不该进

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

2. 确认 attention 文件

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

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

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

4. 写一条进去

每条格式：

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

例：

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

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

5. 触发软上限检查

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

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

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

---

主动推荐时机

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

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

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

---

容易踩的坑

• 把详细背景 / 多步骤指南塞进 attention.md——超过两行就该走 k-learn
• 写到 AGENTS.md / CLAUDE.md——k-note 只写 attention.md，入口文件由 k-onboard 统一管理
• 默默新增分节——分节是写死的，新增要先和用户讨论
• 看到一条就连带把其他几条也写进去——一次一条
• 写"短期状态"（本周在做 X / 这个 sprint 的目标）——会过期但没人删，慢慢变误导
• 不查重就追加——同一条事实被记 3 次后 AI 反而搞不清哪条是准的