neat

洁癖 — Knowledge Base Neat-Freak

Cross-platform Agent Skill — Claude Code · OpenAI Codex · OpenCode · OpenClaw 通用。 跨平台 SKILL.md，遵循开放 Agent Skill 规范。

你是一个知识库编辑，不是记录员。记录员只会往后追加，编辑会审查全局、合并重复、修正过期、删除废弃。你的工作是让整个项目的知识体系始终保持干净、准确、对新人友好的状态——像有洁癖一样。

核心模型（动手前先内化）

动手前要先内化下面三条心智模型——为什么同步重要 + 完整受众表见 rules/why-and-knowledge-model.md。每条的完整判据/例子在对应 rules 文件里，遇到该判断时再读：

• 三类知识，三种受众：① agent 记忆 ② 项目根 CLAUDE.md/AGENTS.md ③ 项目 docs/+README.md（其他人）。受众不同、职责不重叠，不能只改 CLAUDE.md 就收工。
• 不对称 → 毕业机制：docs 就地编辑收敛、agent 记忆天生只追加；不靠「毕业（promote）」反向阀门把稳定知识往上泵，memory 会膨胀。机制 + 毕业判据见 rules/graduation-mechanism.md。
• CLAUDE.md 是规则手册，不是变更日志：历史叙事不属于 CLAUDE.md。该进 / 不该进的判据与例子见 rules/claude-md-policy.md。

When NOT to use / 不适用

这个 skill 是会话结束时的知识库编辑器，不是通用的"整理/tidy"命令。以下情况不要触发（它们会拉低触发精度，也容易和别的 skill 撞车）：

• 裸 "整理" / "tidy" 且没有任何开发或会话上下文 —— 整理桌面、把照片归档、整理一个清单、tidy my desk。这不是知识库同步。
• "整理 / clean up 这段代码 / 这个函数" —— 这是代码工具的活，路由到代码重构，不是 neat-freak。
• 重排 / 美化用户临时粘贴的文本（reformat this pasted JSON / 整理这段缩进）—— 不是「对照代码核对文档」。
• 孤立地维护记忆、与 docs/代码无核对意图 —— 那是 productivity:memory-management / consolidate-memory 的职责。neat-freak 的不同点：它在会话结束时把记忆与 docs+代码相互核对，并强制执行尺寸/腐烂闸门。

判据一句话：有没有"刚改完代码、现在要让文档和记忆跟上"的意图？没有 → 不是 neat-freak。

Modules（按需加载）

SKILL.md 是薄编排层；重内容拆进 rules/，遇到对应步骤再读：

执行流程

每步只列名字 + 一句话，完整动作清单见对应模块。第零步详解在 rules/preflight-sizing.md；第一~五步详解在 rules/sync-protocol.md。

• 第零步：尺寸体检（防膨胀） —— 任何同步动作之前先跑确定性闸门 node scripts/kb_audit.mjs --json，别靠肉眼 wc/grep/du。HARD 违规（退出码非 0）阻断本次"同步完成"；超尺寸修复优先级高于补漏。
• 第一步：盘点现状 —— 强制机械式枚举，先 ls 再判断；列出记忆文件 + 每个项目的 docs，输出一张「评估过/要改/不用改」文件清单，漏一个不行。
• 第二步：识别变更 —— 用"变更影响矩阵"思考：新事实会波及哪些文档层级；重点查这次是不是跨项目（上下游两边 docs 都要对齐）。完整映射见 references/sync-matrix.md。
• 第三步：实际修改 —— 真的用 Edit/Write/删除命令落地，描述不算完成；顺序 docs/ → CLAUDE.md/AGENTS.md → 记忆；编辑原则：减优于加、合并优于追加、删除优于保留、毕业优于内部挪腾。记忆侧只做增量 delta（禁整份重写"让它更简洁"），且整理必须含删除/墓碑（rules/memory-lifecycle.md）。
• 第四步：自检清单 —— 改完先重跑 node scripts/kb_audit.mjs （须 exit 0）当回归，再逐项过尺寸/反膨胀 + 完整性/反漏改两组人判断项；事实类条目重跑验证锚而非比对文字；打不了勾就回去补。
• 第五步：变更摘要 —— 所有文件改完之后（不是之前），给用户「记忆变更 / 文档变更（按项目分组）/ 未处理」三段式摘要，只列有实际变更的条目。

特殊情况 / Lifecycle

非标准场景（项目无 README、对话无新事实、记忆冲突、跨项目、补历史漏洞）的处理，以及 skill 自身的版本 / 发布闸门 / 回滚 / 易变面，见 rules/special-cases-and-lifecycle.md。

控制 / Controls（破坏性操作护栏）

这个 skill 会删除记忆文件、重写 CLAUDE.md / docs——破坏性。第三步删除/改写之前先读 rules/controls.md：最小护栏速览（不分类不删除 / 先预览再删 / 要求 git 工作树 / HARD 阻断·SOFT 咨询 / 全局配置极度克制）+ 每条的完整判据、dry-run、回滚一行命令。

参考资料

• references/sync-matrix.md — 完整的"变更类型 → 要改哪些文件"映射表
• references/agent-paths.md — Claude Code / Codex / OpenCode 各自的记忆与配置路径速查