| 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/(或项目约定) | 测试文件 |
| 配置模板 | 项目配置模板文件 | 配置项模板 |