| name | neat-freak |
| description | 当用户说"整理一下""同步文档""收尾""这个阶段做完了""/sync""/neat""新人能直接上手"或会话结束时使用。 对项目文档做洁癖级审查与同步。关键词：整理、同步、收尾、洁癖、文档更新、梳理。
|
neat-freak (文档洁癖)
触发词
整理一下、同步文档、同步一下、收尾、这个阶段做完了、/sync、/neat、洁癖审查、梳理一下、新人能直接上手、文档跟不上
概述
会话结束后对项目文档做系统性审查与同步，确保知识在所有载体间一致、准确、无冗余。你是知识编辑，不是知识记录仪 — 只保留对 agent 和开发者真正有用的信息，删除过时、合并重复、修正矛盾。
核心哲学：知识编辑 vs 知识记录仪
- ❌ 不是把会话内容原封不动复制到文档里
- ❌ 不是给每个细节都加一条记录
- ✅ 是判断哪些知识值得保留、以什么形式保留、放在哪里
- ✅ 是让下一个 agent 或新队友拿起文档就能上手，不需要再来问你
三类知识分层
| 类型 | 定义 | 存放位置 |
|---|
| 项目知识 | 关于项目结构、架构、约定的持久事实 | AGENTS.md |
| 功能知识 | 关于某个功能/工作流如何执行 | .agents/skills/*/SKILL.md |
| 操作知识 | 本次会话中的临时发现、变通方案 | 不持久化，除非有长期价值 |
反膨胀四原则（铁律）
- 只增不删是最大的技术债：过时信息比没有信息更危险
- 一处真相：同一事实只在一个地方维护，其他地方引用它
- 删除优先于注释：过时内容直接删，不要加"已废弃"标记
- 新增前先找归属：新信息应该放到已有文档的哪个位置？而不是新建文件
审查流程
第 1 步：扫描变更
回顾本次会话做了什么：
- 新增了哪些文件？（代码、脚本、配置）
- 修改了哪些文件？（特别是源码、
.agents/skills/、.agents/rules/）
- 删除了哪些文件？（是否有文档还引用了已删除的文件）
- 发现了什么新知识？（踩坑、变通方案、API 变化）
第 2 步：审查 AGENTS.md
逐项检查是否需要更新：
判断标准：只更新对 agent 或开发者有实际影响的信息。内部实现细节不写，除非它影响使用方式。
第 3 步：审查 Skill 文件
对每个本次会话涉及或影响的 skill（.agents/skills/*/SKILL.md）：
判断标准：skill 是给 agent 执行用的，工作流必须精确可执行。模糊的描述必须细化。
第 4 步：审查 _index.md
检查 .agents/skills/_index.md：
第 5 步：审查 SDD 产物
检查 .agents/specs/ 目录：
第 6 步：审查记忆文件
读取 .agents/memory/ 目录，列出所有 .json 文件：
- 逐个检查：
_description 是否准确？内容是否过期？是否还需要保留？
- 过期记忆直接删除文件
- skill 文件中写死的动态数据（如"已处理6条"）应迁移到记忆文件，skill 只保留工作流
- 检查
_updated_at 字段，超过 90 天未更新的记忆列入待确认清单
第 7 步：审查 WIP 留档
读取 .agents/wip/ 目录：
第 8 步：审查测试和配置
同步矩阵
修改一处必须检查其他处是否需要同步：
| 修改了 | 需要同步检查 |
|---|
.agents/skills/*/SKILL.md | .agents/skills/_index.md；如改了触发词还要看 AGENTS.md 主流程引用 |
.agents/skills/_index.md | 无需额外同步（唯一索引） |
| 新增源码模块 | AGENTS.md（项目结构）；测试文件 |
| 改接口/函数签名 | 对应 skill 的 SKILL.md（工作流+依赖）；_index.md；测试 |
AGENTS.md | 无需额外同步（这是终端文档） |
| 配置模板 | 配置加载代码（确保支持新配置） |
.agents/rules/*.md | AGENTS.md 中是否引用了该规则 |
.agents/specs/{feature}/ | 完成后归档；更新 .agents/memory/ 中相关进度记忆 |
同步铁律
.agents/skills/ 是唯一 skill 目录：所有 skill 文件夹都在 .agents/skills/ 下_index.md 是唯一索引：所有 skill 的索引只此一处- 接口变更三处同步：函数签名变了 → SKILL.md +
_index.md + 测试 都要更新
- 规则变更两处同步：
.agents/rules/ 改了 → AGENTS.md 引用 + 相关 skill 工作流
执行原则
做什么
- 删除过时信息：已删除的功能、已修复的 bug、已变更的接口
- 更新变化信息：新版本号、新路径、新参数、新约束
- 合并重复信息：同一事实出现在多处时，选一个权威位置，其他引用
- 补充缺失信息：新功能缺少文档、新约束没有记录
不做什么
- 不重写：只改需要改的，不要"顺手"重写整个文件
- 不添加代码注释：不在代码中添加解释性注释（除非是 WHY 类的非显然信息）
- 不创建新文档：除非确实需要新 skill 或新规则，否则不新建 .md
- 不记录临时状态：本次会话的调试过程、临时变通方案，除非有长期价值
- 不修改代码逻辑：文档审查只改文档，不改代码
修改粒度
- 精确修改：用 Edit 工具精确替换需要更新的内容
- 不要全文重写：即使文档需要多处修改，也逐处精确编辑
- 验证修改：每次修改后确认文件内容正确
输出格式
审查完成后向用户报告：
## 文档洁癖审查报告
### 变更概要
- 修改了 X 个文件，Y 处内容；删除 Z 处过时信息
### 具体变更
1. `AGENTS.md` — [具体修改内容]
2. `.agents/skills/xxx/SKILL.md` — [具体修改内容]
3. `.agents/skills/_index.md` — [具体修改内容]
...
### 已删除的过时信息
- [删除了什么，为什么删]
### 已检查但无需修改
- [列出检查过但无需修改的文件，让用户知道你检查过了]
### 待确认项
- [需要用户确认的变更，如有]
坑点清单（Gotchas）
- skill 文件夹改了但 _index.md 忘改：新增/删除/重命名 skill 后必须同步
_index.md，否则清单里展示的还是旧信息
- SDD 产物长期堆积：
.agents/specs/ 下已完成的功能 spec 不归档会越堆越多，定期标记完成或移到 specs/archive/
- 记忆文件互相重复：
preferences.json 和某个功能记忆里都写了用户偏好代码风格 — 只在 preferences.json 维护，其他地方引用
- AGENTS.md 项目结构与实际不一致：新增了目录但没更新 AGENTS.md，agent 会按旧结构找文件找不到
- 规则改了但 AGENTS.md 没引用：新增
.agents/rules/xxx.md 但 AGENTS.md 顶部没引用，agent 不会主动读
不要做
- 不要把会话日志原封不动塞进记忆文件 — 只提炼可复用的知识
- 不要"预防性"创建文档 — 没有实际需求不要新建 .md
- 不要在审查中顺手改代码逻辑 — 文档审查只改文档
- 不要重写整个文件 — 逐处精确编辑
关键规则
- 必须先扫描变更再开始审查，不要盲目通读所有文档
- 必须遵守反膨胀四原则：只增不删是技术债
- 绝不修改代码逻辑：本 skill 只动文档
- 必须输出审查报告让用户知道改了什么
输入/输出
- 输入：本次会话的变更上下文（隐式，通过回顾会话获得）
- 输出：同步后的文档文件 + 审查报告
依赖
| 依赖 | 路径 | 说明 |
|---|
| 项目指引 | AGENTS.md | 项目结构和规范（终端文档） |
| Skill 目录 | .agents/skills/ | skill 文件夹 |
| Skill 索引 | .agents/skills/_index.md | 所有 skill 的索引 |
| 规则目录 | .agents/rules/ | 编码准则、skill 设计规范等 |
| SDD 产物 | .agents/specs/ | 规约/计划/任务/分析文档 |
| 记忆目录 | .agents/memory/ | 跨会话记忆（JSON 文件） |
| WIP 目录 | .agents/wip/ | 未完成任务留档 |
| 测试目录 | tests/（或项目约定） | 测试文件 |
| 配置模板 | 项目配置模板文件 | 配置项模板 |
