核心用法
neat-freak 是一个跨平台 Agent Skill（支持 Claude Code、OpenAI Codex、OpenCode、OpenClaw），用于在开发会话结束时执行强制性知识库对齐。触发关键词包括 "sync up"、"/neat"、"整理文档"、"同步一下"、"新人能直接上手" 等暗示阶段性收尾的指令。
执行流程为五步走：
1. 机械式盘点 — 枚举 agent 记忆文件、项目根目录、CLAUDE.md/AGENTS.md、docs/ 下所有 markdown
2. 变更影响矩阵 — 识别代码变更波及的知识层级（API 路由→CLAUDE.md+integration-guide；环境变量→runbook+根文档；跨项目依赖→上下游 docs 同步）
3. 实际编辑 — 用 Edit/Write/删除工具修改文件，遵循「合并优于追加、删除优于保留、绝对时间优于相对时间」原则
4. 自检清单 — 强制逐项验证：路径真实性、矛盾消除、相对时间清零、跨项目影响已处理
5. 变更摘要 — 输出记忆/文档/未处理三部分结论
显著优点
- 三层知识隔离清晰：明确区分 agent 记忆（自复用）、CLAUDE.md（项目约定）、docs/（外部接入），避免「写一份就完事」的常见偷懒
- 跨平台通用：一份 SKILL.md 适配多 agent 生态，附赠各平台记忆路径速查表
- 防漏机制刚性：第一步「ls 再判断」和第四步「自检清单」形成双重保险，尤其强调跨项目改动时上下游文档必须同步
- 编辑哲学先进：明确「知识库编辑 ≠ 记录员」，推崇主动删除废弃信息而非被动堆积
潜在缺点与局限性
- 触发条件较宽："整理"、"tidy" 等单字指令在「有 prior dev context」时即触发，存在误触发风险
- 机械式盘点成本：强制要求 ls/find 遍历文件，在大型 monorepo 中可能产生显著 token 消耗
- 自检清单无法强制执行：虽然文档要求「哪条打不了勾就回去补」，但依赖 agent 自我约束，无硬性拦截
- 全局配置克制原则：用户若未明确表达「跨项目核心原则」，全局
~/.claude/CLAUDE.md不动，可能导致真正跨项目的通用知识沉淀不足
适合人群
- 多 AI agent 交替介入的复杂项目团队
- 需要「干净交接」给下游开发者或新同事的场景
- 文档腐败严重、存在大量「相对时间」（昨天、最近）遗留的历史项目
- 追求「阶段完成后即可让新人独立运行」的工程文化团队
常规风险
- 过度删除风险：「删除优于保留」原则若执行偏激，可能误删仍有价值的决策历史
- 跨项目漏同步：尽管文档反复强调，但实际执行中「改了上游忘下游」仍是最高频翻车点
- 平台路径漂移：agent 记忆路径可能随版本更新变化，references/agent-paths.md 若未及时同步会导致盘点失败