k-note

name	k-note
description	把"短到不值得起一份文件、但 AI 每次启动 kflow 技能都必须知道"的项目碎片知识追加到 `.kflow/attention.md` 的固定分节里——比如编译特殊 flag、运行前要先起的服务、路径陷阱、命令别名、环境变量约定。触发：用户说"记一笔"、"加到 attention.md"、"项目要 X 才能编译"、"以后每次都得 Y"，或刚踩到一个一句话能讲清的项目特殊设置。

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 / k-decide
频次	几乎每次会话都用得上	只在某类具体任务相关 → k-trick
稳定度	项目长期生效的硬约束	临时绕过 / 短期 workaround → 写到 issue spec 或 feature spec
拍板状态	已既成事实（不需要决策记录）	需要记选型理由 / 拒方案 → k-decide

✅ 典型该进：

• "编译要先 pnpm run gen 生成 schema"
• "Prisma schema 改动细节看 compound/2026-xx-xx-trick-prisma-schema.md"
• "本地起服务前必须 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 维护，新条目按下面分节追加 -->

### 编译与构建

### 运行与本地起服务

### 测试

### 命令与脚本陷阱

### 路径与目录约定

### 环境变量与凭证

### 其他

规则：

• 新条目去对应分节末尾追加，每条一行；需要解释时链接到 compound / architecture / requirement / feature / issue 文档
• 没有合适的分节 → 进"其他"。"其他"超过 5 条就停下来和用户讨论是否新增固定分节（不要默默加节）
• 分节为空时整段保留，不删（让 AI 看到这一节是有意义的）
• 注释行 <!-- k-note managed --> 是本技能的识别锚——找不到就在文件末尾插入整块结构
• 文件硬上限 50 条有效项目（不含标题 / 空行 / 注释）——达到上限就拒绝追加，要求先沉淀或合并旧条目

---

流程

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. 硬上限检查

写入前后都检查有效项目数（- 开头的条目）：

• ≥50 条 → 停止追加，提示用户先把详细内容迁到 k-learn / k-trick / k-decide / architecture，并在 attention 里只保留一行链接
• 40-49 条 → 允许本次写入，但提示尽快整理
• "其他"分节 ≥5 条 → 提示用户讨论是否新增固定分节

不要替用户决定迁哪条，但要明确拒绝把 attention.md 继续当知识库堆。

---

主动推荐时机

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

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

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

---

容易踩的坑

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