核心用法
neat-freak 是一个面向 AI Agent 协作开发的知识库治理 Skill，触发关键词包括 "sync up"、"/sync"、"整理文档"、"收尾"、"audit the rules" 等。执行六步流程：
1. 尺寸体检 — 优先检查 CLAUDE.md (~15KB)、MEMORY.md (≤25KB) 等关键文件是否超限，超限则先精简再同步
2. 盘点现状 — 机械枚举 Agent 记忆文件、项目 docs/ 目录、层级规则文件（从项目根到全局配置）
3. 规范审计 — 核验命名约定、必备文件、同源约束（CLAUDE.md/AGENTS.md 软链）、红线规则等，安全修复直接执行，破坏性操作列入「待你拍板」
4. 识别变更 — 用「变更影响矩阵」判断新事实波及的文档层级，处理退役/改名/下线时的死引用清理
5. 实际修改 — 遵循「减优于加、合并优于追加、毕业优于内部挪腾」原则，记忆稳定知识「毕业」进 docs，过期开放项强制处置
6. 自检清单 — 逐项核对尺寸控制、规范执行、完整性、跨项目影响等 20+ 检查点
显著优点
- 三层知识架构清晰：区分 Agent 记忆（自用）、CLAUDE.md（AI 规则手册）、docs/（人类/下游开发者文档），避免混写
- 反膨胀机制创新：提出「毕业(promote)」机制，将稳定知识从记忆泵入 docs，解决记忆只增不改导致的 25KB 截断问题
- 规范可执行化：将散文规则转化为可机械核验的约定，同类违规反复出现时建议 hook 化根治
- 跨平台通用：支持 Claude Code、OpenAI Codex、OpenCode、OpenClaw，自动探测平台路径
- 退役处理完备：被删符号的非载荷引用在同一次同步中清理，避免死引用累积
潜在缺点与局限
- 触发条件较宽："整理"、"tidy" 等单字触发需结合前文开发语境判断，存在误触发或漏触发风险
- 破坏性操作依赖人工：目录重命名、分叉文件合并等需用户「拍板」，高频场景下可能增加交互负担
- 尺寸上限偏保守：MEMORY.md 25KB/200行硬限制针对 Claude Code 优化，其他平台截断阈值可能不同
- 跨项目依赖难自动发现：上下游项目文档同步依赖开发者主动声明，隐性依赖易遗漏
适合人群
- 使用多 Agent（Claude + Codex 等）协作开发的团队
- 项目知识库已出现「记忆里有过期信息、docs 混乱、规则成摆设」问题的开发者
- 需要向新成员或下游系统交接项目的场景
- 追求「代码可变、知识可追溯」治理理念的工程团队
常规风险
- 静默截断风险：MEMORY.md 超 25KB 部分会话开始时不加载，Skill 执行前若未体检修复，可能基于不完整记忆做决策
- 过度精简风险：「减优于加」原则执行过激时，可能删除仍有上下文价值的临时信息
- 软链误删风险：AGENTS.md 软链完整性检查若工具使用不当，可能破坏同源约束
- 跨平台路径漂移：新平台记忆路径变化时，references/agent-paths.md 若未及时更新会导致探测失败
来源可信度
本 Skill 文档来自官方 Skill 仓库，规范引用 Anthropic 官方 CLAUDE.md 使用建议，路径信息覆盖主流 Agent 平台，属于经过实践验证的最佳实践集合。