核心定位
neat-freak 是一款面向 AI 协作开发场景的知识基线同步 Skill，解决代码迭代过程中「文档滞后于实现」的系统性风险。它强制建立「代码 ↔ 记忆 ↔ 文档」的三层一致性检查，而非简单的日志追加。
核心用法
触发条件明确：当用户说出 "sync up"、"整理文档"、"收尾"、"新人能直接上手" 等里程碑信号，或发现文档过期、记忆冲突时自动激活。执行五步走：
1. 机械式盘点：强制 ls 枚举 Agent 记忆目录、项目根目录、docs/ 及所有 .md 文件，建立完整文件清单
2. 变更影响矩阵：对照 references/sync-matrix.md，识别新增 API、环境变量、数据库表等变更应波及的文档层级（记忆层/CLAUDE.md/外部 docs）
3. 实际修改：用 Edit/Write/Delete 真正改动文件，遵循「合并优于追加、删除优于保留、绝对时间优于相对时间」原则
4. 自检清单：12 项强制检查，包括跨项目影响、相对时间清零、记忆索引有效性等
5. 变更摘要：按「记忆-文档-未处理」结构化输出
显著优点
- 三层受众分离：明确区分 Agent 自用的记忆、项目内 AI 的配置 (CLAUDE.md)、以及人类同事的 docs/，避免「写一份就完事」的偷懒
- 跨平台兼容：Claude Code、OpenAI Codex、OpenCode、OpenClaw 统一适配
- 防漏机制：强制枚举 + 自检清单 + 变更矩阵三重保险，显著降低「改了代码忘改文档」的概率
- 新人友好：docs/ 面向外部读者，要求「5 分钟上手」标准，降低团队交接成本
潜在局限
- 执行成本：强制机械盘点在大型多项目会话中可能产生较多文件 IO
- 判断依赖：「是否跨项目影响」需要 Agent 主动识别依赖关系，复杂微服务架构下可能遗漏
- 无法解决根本矛盾：记忆冲突时仅标记「未处理」交用户决策，不提供仲裁逻辑
- 平台差异：Agent 记忆路径因平台而异，虽提供速查表但仍需人工确认
适合人群
- 长期迭代、多人/多 Agent 协作的 AI 原生项目
- 需要频繁交接给下游开发者或运维团队的系统
- 对「文档即代码」有洁癖，厌恶相对时间和重复信息的团队
常规风险
| 风险 | 场景 | 缓解 |
|------|------|------|
| 过度触发 | 用户随口说"整理一下"但实际无变更 | 结合对话上下文判断，bare "整理" 需 prior dev context |
| 误删有效信息 | 「删除优于保留」原则执行过激 | 自检清单要求逐项确认，关键删除需用户可见摘要 |
| 跨项目遗漏 | 改了上游 SDK 未同步下游集成文档 | 强制检查「跨项目影响」条目 |
| 平台路径错误 | 误读 Codex 记忆路径为 Claude Code 路径 | 严格遵循 `references/agent-paths.md` 速查 |
安全与可信度
本报告为系统生成的占位简介，未执行实际安全扫描。Skill 本身操作范围限于用户工作区的文档文件，不涉及网络外联或代码执行，理论上属低风险操作。但因其具备批量删除文件能力，建议在受控仓库（有 Git 历史）中使用。