元规则：按需建档机制¶
类型：rule（操作指南 — 关于规则本身的规则） 描述：用户首次描述某工具用法/工作流时，AI 必须立即落档，杜绝重复描述 最后更新：2026-05-26 触发场景：用户描述操作步骤时 / 描述工具用法时 / 描述外部 API 调用时 优先级：⭐⭐⭐ 最高（这是关于"如何建规则"的规则）
为什么有这条¶
用户的时间 ≠ 无限。AI 的记忆 = 本次会话。两者结合 → 如果不主动落档： - 用户说一次 picgo 怎么用 → 下次又得说 - 用户说一次 git push 时机 → 下次又得说 - 同一个工具的踩坑会反复出现
核心理念：用户描述一次，AI 落档；后续 AI 自己查。
什么时候触发¶
只要用户描述了以下任何一种，立即触发：
| 用户消息特征 | 应建文档类型 |
|---|---|
| 「我希望加 X 功能」/「能不能做个 X」（新需求） | docs/raw/inbox/YYYY-MM-DD-<标题>.md（粘原话，等评估） |
| 用户截图反馈 UI 问题（feedback） | docs/raw/feedback/YYYY-MM-DD-<标题>.md |
| 架构 / 工作流讨论（重要对话） | docs/raw/conversations/YYYY-MM-DD-<标题>.md |
| 评估 raw 后决定要做 → 转规格 | docs/specs/active/SPEC-XXX-<标题>.md（数据模型 + API + 任务） |
| "用 X 工具的接口 / SDK / 命令做 Y" | docs/rules/<X-用法>.md |
| "什么情况下应该 / 不应该做 Y" | docs/rules/<Y-时机>.md |
| "做 X 的标准流程是 ..." | docs/rules/<X-流程>.md |
| "我们的 X 设计是 ...因为 ..." | docs/wiki/<X-架构>.md |
| "X 字段实际是 Y，不是字面意思" | docs/wiki/<字段语义>.md 增条目 |
| "X 不工作 / 卡死 / 出错"（bug 报告） | docs/issues/<编号>-<标题>.md（必建） |
| 每次修完 bug | 同时落档到 docs/issues/（强制） |
| 每次实现 spec | 移到 docs/specs/done/ + 更新 frontmatter status |
| "踩过的坑：X 时要小心 Y" | 增进 更新规则.md 第七章 + 对应 issue + wiki |
标准动作（AI 收到此类指令时）¶
当下立即执行（不要等"以后整理"，因为不会有以后）：
- 判断类型：rule（操作指南）还是 wiki（知识沉淀）？
- 复制模板：
cp docs/<类型>/_template.md docs/<类型>/<主题>.md - 填写内容：
- 头部元数据完整填（描述/最后更新/触发场景）
- 用户原话尽量保留（用引用块标记），自己的整理放下方
- 留
TODO:给用户补的细节，但结构必须完整 - 更新 INDEX：在
docs/<类型>/INDEX.md新增一行 - 回复用户：「已落档到
docs/<类型>/<主题>.md，下次用到我直接查这里」
何时不要建档¶
避免文档膨胀：
- ❌ 用户一句闲聊 / 临时讨论 → 不落档
- ❌ 已经被现有文档覆盖 → 在现有文档加条目，别新建
- ❌ 仅本次一次性的"这次帮我做 X" → 不落档
- ✅ 用户明确说"以后做 X 都按这个" → 必落档
- ✅ 工具用法 / 工作流规则 → 必落档（哪怕用户没强调）
文档"够不够好"的标准¶
下一次新的 AI 实例（无任何上下文）打开这份文档，能不再需要用户解释就执行。
如果不能 → 文档不够。补 prerequisites / 命令示例 / 示例输出。
提交前必做（v0.10.25 SPEC-003）¶
每次完成版本/改文档后，必须：
docs:check 退出码 1 = 有 ERROR → 不允许 commit。退出码 0 + WARNING → 可 commit 但建议修。
校验规则见 SPEC-003-文档治理自动化。
已有先例¶
- 用户说「中文标点 Edit 踩坑」 → 落档到
更新规则.md第七章 C 节 +docs/issues/0005-*（v0.10.13） - 用户说「v0.10.0 是共享队列架构」 → 落档到
docs/wiki/shared-queue-architecture.md（v0.10.14） - 用户说「按需建档机制」 → 本文件（v0.10.14）
- 用户说「卡在登录骨架屏」 →
docs/issues/0002-popup-loading-deadloop.md（v0.10.16） - 用户说「点登录无反应」 →
docs/issues/0001-login-button-no-response.md（v0.10.17） - 用户说「问题与改进方案都要记录」 → 建
docs/issues/体系（v0.10.17）
完成后必做¶
-
docs/<类型>/INDEX.md同步更新 - 头部元数据完整
- 留
TODO:的地方用户能一眼看到 - 回复中告知用户文档路径