Neat Freak

洁癖 — Knowledge Base Neat-Freak

Cross-platform Agent Skill — Claude Code · OpenAI Codex · OpenCode · OpenClaw 通用。

跨平台 SKILL.md，遵循开放 Agent Skill 规范。

你是一个知识库编辑，不是记录员。记录员只会往后追加，编辑会审查全局、合并重复、修正过期、删除废弃。你的工作是让整个项目的知识体系始终保持干净、准确、对新人友好的状态——像有洁癖一样。

为什么这件事重要

在 AI 协作开发中，代码可以随时重写，但文档和记忆是跨会话、跨 Agent 的唯一桥梁。如果记忆里有过期信息，下一个 Agent（无论它是 Claude、Codex 还是别的）会基于错误前提做决策。如果 docs/ 混乱或缺失，接手者（尤其是下游项目的同事）会浪费大量时间搞清楚这套系统怎么用。

这个 Skill 的价值就在于：让知识体系的每一层都跟得上代码的变化。

关键概念：三类知识，三种受众

必须先理解这件事，否则你会只改 CLAUDE.md 就结束，把下游同事和其他 agent 晾在那儿。

这三层受众不同，职责不重叠。CLAUDE.md 里写"新增了 device flow 五个路由" ≠ docs/integration-guide.md 里"下游怎么接这套 flow" —— 前者是提醒自己，后者是教别人。两份都要写。

Agent 记忆系统的具体位置因平台而异（Claude Code 在 ~/.claude/projects/<...>/memory/，Codex 用 AGENTS.md，OpenCode 用 .opencode/，OpenClaw 用 ~/.openclaw/）。完整路径速查见 references/agent-paths.md。如果当前 agent 没有独立的记忆系统，直接跳过这一层，把功夫全花在 docs 和项目根 markdown 上。

记忆只增不改、docs 就地编辑——要靠「毕业」机制把知识往上泵（膨胀头号根因）

必须理解这条不对称，否则记忆永远在膨胀：docs 靠就地编辑收敛（系统改 10 次，还是那一份 ARCHITECTURE.md），而 agent 记忆天生只追加（每条教训生一个新文件，旧的不删）。没有反向阀门，memory 会一路堆到比 docs 还大，真正稳定的知识被困在几十个松散文件里——既进不了 prompt（索引 25KB 截断），也没沉淀成给别人看的文档。高速开发的项目尤其明显：每天 2-3 条教训 × 数周 = 上百个记忆文件。

反向阀门 = 毕业（promote）。 一条记忆满足下面任一条，就把它「毕业」：内容并进对应的 docs/ 或 CLAUDE.md，然后把原记忆文件删掉或缩成一行指针：

• 同一主题的教训反复出现到第 3 次 → 它已是稳定知识而非「最近踩的坑」，归 docs。
• 它讲的是「系统怎么工作」而非「我们踩过什么坑 / 做过什么决策」 → 本就是 docs 的职责，memory 顶多留指针。
• 它是「X 上线 / 落地 / 就位」的事件记录 → 现役事实进 docs，过程进 git log / docs/CHANGES.md，memory 不留常驻文件。

判据一句话：「下一个接手的人（不只是我自己）需要知道这件事吗？」需要 → 它属于 docs，不是 memory。

记忆文件若用类型前缀（如 feedback_=教训 / project_=决策事件 / reference_=速查），生命周期不同：reference_ 通常合法长期常驻；feedback_ 稳定后毕业；project_ 多数是事件记录，是优先毕业 / 删除的对象——决策结论进 docs，过程进 changelog。

CLAUDE.md / AGENTS.md 是规则手册，不是变更日志（重要）

最常见的 skill 翻车模式：每次开发完都在 CLAUDE.md 顶部加一段 blockquote 历史叙事——"2026-05-08 X 功能上线，详见 docs/Y.md"。一次很爽，半年后顶部就是 200 行 blockquote 把真正的规则推到看不见。这种叙事不属于 CLAUDE.md，它的归宿是 git log / /changelog 页 / docs/CHANGES.md。

判断一条信息该不该进 CLAUDE.md，问一句：下次 AI 写代码时如果没看到这条，会不会犯错？

✅ 该进 CLAUDE.md 的内容：硬边界规则、禁止事项、命令速查、权限模型、协作流程、深入文档指针表、踩坑警示。 ❌ 不该进的：历史叙事（"X 时刻起 Y 上线"）、详细机制说明、单次事故复盘、bug fix 流水账、"详见 docs/Z.md" 的指针句子（这个角色已经被「深入文档」指针表占掉了）。

执行流程

第零步：尺寸体检（防膨胀）

任何同步动作之前，先 wc -l 关键文件：

额外做一次「体量倒挂」体检：du -sh <memory 目录> 对比 du -sh docs/。健康态是 docs 厚、memory 薄——docs 是沉淀的权威层，memory 是流动的「最近教训 + 指针」层。若 memory 反而比 docs 大，几乎一定是「本该毕业进 docs 的稳定知识还赖在松散记忆文件里」，按「毕业」机制往上泵，别只在 memory 内部挪。

超尺寸是这个 skill 的最高优先级，大于"补本次会话漏掉的同步"。 原因：MEMORY.md 超 25KB 的部分根本不进上下文（静默丢失），超尺寸的 CLAUDE.md 让真正的规则被叙事段挤出 adherence——两种情况下，同步再补都徒劳。

执行顺序：先精简（破除膨胀）→ 再做本次会话增量同步（补漏）。两件事不能合并——精简时心态是"什么不该在这"，补漏时心态是"什么该补到这"，混着做会两头不到位。

第一步：盘点现状（强制机械式枚举，不能跳过）

先做 ls，再做判断。

1. 列出 agent 的记忆文件（如有）：

• Claude Code：ls ~/.claude/projects/<...>/memory/ 并读 MEMORY.md 及所有被引用的 .md
• Codex / OpenCode / 其他：找该 agent 的等价位置（见 references/agent-paths.md）

2. 对本次对话涉及的每一个项目：

• ls <project-root>/ → 确认根目录结构
• ls <project-root>/docs/ 2>/dev/null → 枚举所有 docs（缺失也要确认）
• find <project-root> -maxdepth 2 -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" → 兜底抓散落的 .md
• 读 README.md、CLAUDE.md / AGENTS.md、每一个 docs/*.md

3. 读全局 agent 配置（若有，如 ~/.claude/CLAUDE.md、~/.codex/AGENTS.md） 4. 回顾本次对话全部内容

输出一张文件清单（内部用，不用给用户看），对每个文件标：「评估过 / 要改 / 不用改」。漏一个不行——这是这个 skill 最容易翻车的地方。

第二步：识别变更——用"变更影响矩阵"思考

不要只看对话增量有什么新事实，要看新事实会波及哪些文档层级。

常见模式速览：

• 新增 API / 路由 → CLAUDE.md 路由清单 + integration-guide + architecture 的 Routes
• 新增 / 改名 环境变量 → CLAUDE.md 环境变量表 + runbook + 下游 integration-guide
• 新增数据库表 → CLAUDE.md + architecture 的 Data Model
• 新增大特性（跨多文件） → 以上全部 + architecture 新章节 + handoff 已完成清单
• 跨项目改动 → 上下游两边的 docs 都要对齐（最常见的漏改场景）
• 记忆层面：相对时间→绝对日期、过期事实→改、重复→合并、已完成待办→删

完整映射表（覆盖更多变更类型与对应文档）见 [references/sync-matrix.md](references/sync-matrix.md)——遇到不确定的改动先查这张表。

关键检查：这次对话是不是跨项目的？如果改了项目 A 且项目 B 依赖它（通过 SDK、API、子域、环境变量），项目 B 的 docs 也要改。这是历次同步最常翻的车。

第三步：实际修改（用工具，不只是描述）

你必须真的用 Edit 修改现有文件、用 Write 创建新文件、用删除命令清理废弃文件。"我会怎么改"的描述不算完成。

顺序建议：先改 docs/（改错影响外部）→ 再改 CLAUDE.md/AGENTS.md → 最后理记忆。先动外部优先级最高的，即使中途被打断，读者看到的也是对齐的最新状态。

编辑原则：

• 减优于加（最重要）：每次同步动作结束后，CLAUDE.md / AGENTS.md 净涨幅 > 30 行就是红灯——很可能在写历史叙事而不是补规则。回头审：这条加的是"下次 AI 写代码时必须看到"的规则，还是"上次会话告诉下次会话发生了什么"的便条？后者就是病。能删的先删，不能删的迁去 docs，最后剩下的才是规则。
• 合并优于追加：新信息是对旧信息的更新，改旧条目；新加条目前先 grep 同关键字，看现有条目能不能并
• 删除优于保留：完成的临时计划、推翻的决策、已被新版本取代的项目记忆、单次事故的流水账复盘——删
• 毕业优于内部挪腾（针对 memory）：一条记忆稳定、复用、或本属「系统怎么工作」时，别在 memory 里搬来搬去——并进 docs / CLAUDE.md，原文件缩成一行指针或删。这是把 memory 压回「薄」的唯一治本手段（见上「毕业」机制）
• 精确优于冗长：一条记忆说清楚一件事，别塞三件
• 绝对时间：永远 2026-04-29，不写"今天"、"最近"
• 面向读者：docs/ 的读者是"第一次接触这个项目的外部人"，写的时候想象对方只有 5 分钟能看完
• 受众不混：CLAUDE.md 里不抄 docs/ 的全文，docs/ 里不写"我记得上次……"——这是记忆的事
• 指针不重复：同一条事实如果 docs/ 里已详写，CLAUDE.md 只在「深入文档」指针表里出现一次，不在概览段再叙事一次

全局配置极度克制：~/.claude/CLAUDE.md / ~/.codex/AGENTS.md 只有用户在对话中明确表达了跨项目的核心原则才动。日常项目细节绝不进全局。

docs/ 编辑要点——新增一个能力的文档变更通常要四处都补： 1. integration-guide 或对应"外部视角"文档：加怎么用（curl / SDK 示例 / 错误码表） 2. architecture：加怎么工作（数据流、状态机、设计取舍） 3. runbook：加怎么运维（冒烟命令、故障排查、环境变量） 4. handoff 或 CHANGELOG：加已完成

API 速查表、环境变量表、术语表是高频查询的结构化信息，必须保持"所见即最新"。

第四步：自检清单（必须逐项过一遍）

这一步同时防止"漏改 docs" + "误把叙事塞进 CLAUDE.md"。改完后逐条检查：

尺寸 / 反膨胀（先查这组，不达标的话回头先精简）：

• [ ] CLAUDE.md / AGENTS.md 净涨幅 ≤ 30 行（超了就是塞了历史叙事，回去删 / 迁 docs）
• [ ] 没新增 "X 起 Y 上线，详见 docs/Z.md" 这种 blockquote 历史叙事条目
• [ ] 没在 CLAUDE.md 里抄 docs/ 已有的详细机制说明
• [ ] 单条 memory 文件没超 ~100 行（超了拆 / 删 / 改成 reference）
• [ ] 记忆索引 `MEMORY.md` ≤ 25KB 且 ≤ 200 行（wc -c 实测；超出部分会话开始时静默不加载 = 等于没记）
• [ ] 体量没倒挂：du memory 不应大于 du docs/；倒挂了说明有该毕业进 docs 的知识赖在 memory，回去毕业

完整性 / 反漏改（再查这组）：

• [ ] 第一步列出的每个文件，都判断了"不用改"或"已改"
• [ ] 记忆索引（若有）里的每个链接指向存在的文件
• [ ] 每个记忆文件的 description 和内容对得上
• [ ] 记忆之间没有互相矛盾
• [ ] CLAUDE.md / AGENTS.md 里提到的路径 / 命令 / 工具 / 环境变量在代码中真实存在
• [ ] README 的安装 / 运行步骤跟代码一致
• [ ] 新增 API 路由：在 integration-guide 和 architecture 都出现了
• [ ] 新增环境变量：在 runbook 和项目根 markdown 都出现了
• [ ] 新增数据库表：在 architecture 的 Data Model 和项目根 markdown 都出现了
• [ ] 跨项目影响：下游项目的 docs 也跟着改了
• [ ] 没有相对时间遗留（grep -E "今天|昨天|刚刚|最近|上周|today|yesterday|recently" 清零）

哪条打不了勾，回去补。不要因为"差不多了"就跳过这一步——这是这个 skill 的灵魂。

第五步：变更摘要

在所有文件修改完之后（不是之前），给用户简洁摘要：

## 同步完成

### 记忆变更
- 更新：xxx（原因）
- 新增：xxx
- 删除：xxx（原因）

### 文档变更（按项目分组，每个项目列全改动的文件）
- <项目 A>/CLAUDE.md — xxx
- <项目 A>/docs/integration-guide.md — xxx
- <项目 A>/docs/architecture.md — xxx
- <项目 B>/docs/<integration>.md — xxx

### 未处理
- xxx（为什么没处理，比如需要用户确认）

只列有实际变更的条目。没改的不写。

特殊情况

项目还没有 README 或 CLAUDE.md/AGENTS.md：判断项目是不是到了"有可运行代码"的阶段。是 → 创建。还在 vibe 阶段 → 跳过，但在摘要里提一句。

对话没有产生新事实：审查现有记忆和文档有没有过期 / 冲突 / 相对时间——审查本身就有价值。

记忆之间出现无法自动判断的矛盾：列在「未处理」让用户决定。这是唯一需要用户介入的情况，其他都自己拍板。

跨项目改动：本次对话改了多个项目，每个项目都要跑一次完整的第一步（ls + 读 docs）。不要假设一个项目的 docs 改了，另一个就不用。尤其是上游-下游对接文档（集成指南 / SDK 说明 / API 协议），两边都要对齐。

发现之前的同步漏了东西：修掉。不要说"那不是这次对话的事"——你就是这个项目的持续编辑，过去的漏洞也归你管。

参考资料

• [references/sync-matrix.md](references/sync-matrix.md) — 完整的"变更类型 → 要改哪些文件"映射表
• [references/agent-paths.md](references/agent-paths.md) — Claude Code / Codex / OpenCode 各自的记忆与配置路径速查

Agent 记忆与配置路径速查

不同 agent 平台的记忆系统和项目配置文件位置不一样。执行第一步盘点时按你正在使用的平台查这张表。

Claude Code

记忆文件用 YAML frontmatter:name、description、type(user / feedback / project / reference)。

OpenAI Codex

Codex 没有独立的"记忆文件 + 索引"机制,所有跨会话信息都直接写在 AGENTS.md 里。同步时把"项目事实"那部分内容统一放 AGENTS.md。

发现项目里有 TEAM_GUIDE.md 或 .agents.md 也要看——这是 Codex 的 fallback 文件名。

OpenClaw

加载优先级：workspace > project-agent > personal-agent > managed/local > bundled > extra dirs。同名 skill 高优先级覆盖低优先级。

OpenClaw 没有独立的"记忆文件 + 索引"机制，跨会话信息可放在项目根的 markdown（CLAUDE.md / AGENTS.md / 等价文件）里，参照 Codex 的做法。frontmatter 支持 metadata.openclaw 字段做加载时的 gating（按 OS、环境变量、二进制依赖筛选），但不是 neat-freak 必需的。

OpenCode

OpenCode 同时读取 Claude Code 和 Codex 的目录,所以同一个 skill 装在 ~/.claude/skills/ 下的话三家都能识别。OpenClaw 走自己的 ~/.openclaw/skills/，需要单独装一份（或用符号链接）。

如果当前 agent 没有独立记忆系统

跳过"记忆"那一层,把功夫全花在:

• 项目根 markdown(CLAUDE.md / AGENTS.md / 本平台等价文件)
• README.md
• docs/

仍然是有效的同步——记忆是锦上添花,docs 才是项目知识的最低保障。

跨平台共存策略

如果一个项目同时被 Claude Code 用户和 Codex 用户使用,推荐:

• 项目根同时放 `CLAUDE.md` 和 `AGENTS.md`,内容可以互相 symlink 或在两边维护
• 或者一份内容主文件 + 另一份用一行 See CLAUDE.md 跳转
• docs/ 和 README 是平台中立的,不需要分两份

变更影响矩阵

遇到不确定"这次改动要同步哪些文件"时查这张表。两个方向都要查：补漏（加到哪些文件）+ 防膨胀（应该从哪些文件删）。

反向：哪些信息该从 CLAUDE.md / 记忆里删除

CLAUDE.md / AGENTS.md 不是变更日志。下面这些反模式发现了就删 / 迁：

判断标准：这条信息在下次 AI 写代码时如果没看到，会犯错吗？ 不会就删 / 迁。

代码层变更 → 文档层变更

记忆层变更

跨项目影响检查

最容易漏改的场景:

• 上游 API 变了 → 下游 SDK 文档:协议变化必须两边对齐
• 共享子域 / 路由 / 环境变量改了 → 所有 consumer 项目的 setup 文档
• 认证中台变更 → 所有接入应用的 integration guide
• 公共组件 / 基础设施 升级 → 各项目的 operator-runbook 提及版本号的地方

判断方法:这次改的东西有没有 SDK、子域、共享配置、跨进程协议?有就要在所有依赖项目里搜一遍提到这件事的文档。

文档结构通用约定

新增一个能力(API、flow、特性)的标准动作是四处都补:

1. integration-guide / 外部视角文档:怎么用(curl / SDK 示例 / 错误码) 2. architecture:怎么工作(数据流、状态机、设计取舍) 3. runbook:怎么运维(冒烟命令、故障排查、环境变量) 4. handoff / CHANGELOG:已完成

API 速查表、环境变量表、术语表是高频查询的结构化信息,必须保持"所见即最新"。