核心用法
Neat-Freak 是一个面向 AI 协作开发的知识库治理 Skill，设计用于会话结束时的"洁癖级"文档与记忆同步。其执行流程分为五步：
1. 机械式盘点：强制枚举 Agent 记忆文件（Claude Code 的 ~/.claude/projects/.../memory/、Codex 的 AGENTS.md 等）、项目根目录 Markdown、docs/ 文件夹及全局配置，输出完整文件清单并标记状态。
2. 变更影响矩阵分析：识别本次对话的新事实（API 新增、环境变量变更、数据库表改动等），对照 references/sync-matrix.md 确定波及的文档层级——Agent 记忆（自用的跨会话事实）、CLAUDE.md/AGENTS.md（项目约定）、docs/ + README（外部受众的接入指南）。
3. 实际修改：使用 Edit/Write/Delete 工具直接操作文件，遵循"合并优于追加、删除优于保留、绝对时间优于相对时间"原则，顺序为先 docs（外部影响最大）→ 项目根 Markdown → 记忆。
4. 强制自检清单：12 项检查防止漏改，包括记忆链接有效性、路径/命令真实性、新增 API 在 integration-guide 和 architecture 双出现、跨项目影响对齐、相对时间清零等。
5. 变更摘要：按"记忆变更→文档变更（按项目分组）→未处理"结构输出，未改动的条目不列。
显著优点
- 三层知识分离清晰：明确区分 Agent 记忆、项目级约定、外部文档三种受众，避免"提醒自己"和"教别人"的内容混为一谈。
- 跨平台通用：原生支持 Claude Code、OpenAI Codex、OpenCode、OpenClaw，通过 references/agent-paths.md 适配不同记忆系统路径。
- 防漏机制严密："先做 ls 再做判断"的强制枚举、变更影响矩阵的映射参照、12 项自检清单，大幅降低"以为改了其实没改"的概率。
- 面向新人设计：docs/ 编辑要求"想象对方只有 5 分钟"，强调接入指南、运维手册、API 参考的实用性。
- 历史债务主动修复：发现过往同步遗漏时要求当场修补，而非推诿"不是本次对话的事"。
潜在缺点与局限性
- 执行成本较高：完整流程涉及大量文件读取、交叉验证和手动编辑，轻量改动场景可能显得"杀鸡用牛刀"。
- 无自动触发机制：依赖用户主动说出 "sync up"、"整理文档"、"/sync" 等触发词，存在"用户忘记同步"的风险。
- 跨项目对齐依赖人工判断：虽然提醒检查上下游影响，但实际识别"项目 B 依赖项目 A"仍需执行者经验。
- 记忆系统碎片化：不同 Agent 的记忆路径差异大（Claude Code 用目录、Codex 用单文件），维护 references/agent-paths.md 的准确性是持续负担。
适合人群
- 使用多 Agent（Claude、Codex 等）轮换开发同一项目的团队
- 需要向人类同事或下游系统提供清晰交接文档的开发者
- 厌恶文档腐烂、追求"代码-文档-记忆"三位一体同步的洁癖型技术负责人
- 运行周期长、会话频繁、历史决策容易丢失的中大型 AI 协作项目
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 误删有价值信息 | "删除优于保留"原则执行过激 | 自检清单要求逐项确认，矛盾项列"未处理"让用户裁决 |
| 跨平台路径错误 | Agent 升级导致记忆目录变更 | 执行前核对 references/agent-paths.md，发现不匹配及时更新 |
| 用户中断导致半同步 | 流程中途被打断，docs/ 已改但记忆未理 | 顺序设计为先 docs 后记忆，即使中断外部看到的也是最新状态 |
| 过度同步干扰 vibe coding | 早期原型阶段强行创建完整文档 | Skill 内置判断："有可运行代码"才创建，vibe 阶段主动跳过 |