xingfanxia 洁癖 — Knowledge Base Neat-Freak
Cross-platform Agent Skill — Claude Code · OpenAI Codex · OpenCode · OpenClaw 通用。 跨平台 SKILL.md，遵循开放 Agent Skill 规范。
你是一个知识库编辑，不是记录员。记录员只会往后追加，编辑会审查全局、合并重复、修正过期、删除废弃。你的工作是让整个项目的知识体系始终保持干净、准确、对新人友好的状态——像有洁癖一样。
定位（2026-07-08 起）：backstop，不是主机制。 知识同步的主机制是 in-flight——让文档过期的那次编辑应当在同一批工作里顺手更新文档（见
rules/workflow.md→ Knowledge sync）。本 skill 是收尾兜底：理想情况下扫描结果应该是零发现。如果扫出了非琐碎的漂移，说明本次任务的 in-flight 纪律失守——修完后顺带记一句什么漏了、为什么漏。
为什么这件事重要
在 AI 协作开发中，代码可以随时重写，但文档和记忆是跨会话、跨 Agent 的唯一桥梁。如果记忆里有过期信息，下一个 Agent（无论它是 Claude、Codex 还是别的）会基于错误前提做决策。如果 docs/ 混乱或缺失，接手者（尤其是下游项目的同事）会浪费大量时间搞清楚这套系统怎么用。
这个 Skill 的价值就在于：让知识体系的每一层都跟得上代码的变化。
关键概念：三类知识，三种受众
必须先理解这件事，否则你会只改 CLAUDE.md 就结束，把下游同事和其他 agent 晾在那儿。
| 位置 | 受众 | 职责 | 不同步的代价 |
|---|---|---|---|
| Agent 记忆系统（若 agent 支持） | Agent 自己跨会话复用 | 个人偏好、非显而易见的项目事实、跨项目 reference | 下次会话 Agent 忘记历史决策 |
项目根 CLAUDE.md / AGENTS.md |
当前项目里的 AI（下次会话自己） | 项目约定、结构、红线、环境变量、路由清单 | 下次 AI 在这个项目里走弯路 |
项目 docs/ + README.md |
其他人（人类同事、下游开发者、未来接手的 AI） | 接入指南、架构图、运维手册、交接说明、API 参考 | 其他人或系统无法正确接入或运维 |
这三层受众不同，职责不重叠。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 上。
执行流程
第一步：盘点现状（强制机械式枚举，不能跳过）
先做 ls，再做判断。
- 列出 agent 的记忆文件（如有）：
- Claude Code：
ls ~/.claude/projects/<...>/memory/并读MEMORY.md及所有被引用的.md - Codex / OpenCode / 其他：找该 agent 的等价位置（见 references/agent-paths.md）
- Claude Code：
- 对本次对话涉及的每一个项目：
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
- 读全局 agent 配置（若有，如
~/.claude/CLAUDE.md、~/.codex/AGENTS.md） - 回顾本次对话全部内容
输出一张文件清单（内部用，不用给用户看），对每个文件标：「评估过 / 要改 / 不用改」。漏一个不行——这是这个 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——遇到不确定的改动先查这张表。
关键检查：这次对话是不是跨项目的？如果改了项目 A 且项目 B 依赖它（通过 SDK、API、子域、环境变量），项目 B 的 docs 也要改。这是历次同步最常翻的车。
第三步：实际修改（用工具，不只是描述）
你必须真的用 Edit 修改现有文件、用 Write 创建新文件、用删除命令清理废弃文件。"我会怎么改"的描述不算完成。
顺序建议：先改 docs/（改错影响外部）→ 再改 CLAUDE.md/AGENTS.md → 最后理记忆。先动外部优先级最高的，即使中途被打断，读者看到的也是对齐的最新状态。
编辑原则：
- 合并优于追加：新信息是对旧信息的更新，改旧条目，不要再加一条
- 删除优于保留：完成的临时计划、推翻的决策、过期的上下文，删掉
- 精确优于冗长：一条记忆说清楚一件事，别塞三件
- 绝对时间：永远
2026-04-29，不写"今天"、"最近" - 面向读者：docs/ 的读者是"第一次接触这个项目的外部人"，写的时候想象对方只有 5 分钟能看完
- 受众不混：CLAUDE.md 里不抄 docs/ 的全文，docs/ 里不写"我记得上次……"——这是记忆的事
全局配置极度克制：~/.claude/CLAUDE.md / ~/.codex/AGENTS.md 只有用户在对话中明确表达了跨项目的核心原则才动。日常项目细节绝不进全局。
docs/ 编辑要点——新增一个能力的文档变更通常要四处都补：
- integration-guide 或对应"外部视角"文档：加怎么用（curl / SDK 示例 / 错误码表）
- architecture：加怎么工作（数据流、状态机、设计取舍）
- runbook：加怎么运维（冒烟命令、故障排查、环境变量）
- handoff 或 CHANGELOG：加已完成
API 速查表、环境变量表、术语表是高频查询的结构化信息，必须保持"所见即最新"。
第四步：自检清单（必须逐项过一遍）
这一步防止"漏改 docs"。改完后逐条检查：
- 第一步列出的每个文件，都判断了"不用改"或"已改"
- 记忆索引（若有）里的每个链接指向存在的文件
- 每个记忆文件的 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（为什么没处理，比如需要用户确认）
只列有实际变更的条目。没改的不写。
第五步补充：下一会话起手卡（仅在 handoff 语义触发时输出）
何时输出：用户的触发词带 "handoff" / "交接" / "让接班 agent 接手" / "下一个会话能直接上手" / 类似含义时。普通的 /sync / 整理一下 / 更新记忆 不需要这一段——它是给"下一会话"看的便携小抄，不是日常同步的产物。
输出形式：纯聊天文本，不写文件。绝不创建 HANDOFF.md / STATUS.md / NEXT-SESSION.md 之类——这类文件会被 autonomous-grind hooks 直接拦截，而且和 auto-memory 职责重叠。起手卡是"用户复制到新会话粘贴一次就丢"的瞬时上下文。
模板（在第五步摘要之后追加输出）：
## 下一会话起手卡（复制到新会话即可）
**当前状态**：1 句话——分支 / PR / CI / 阻塞点等具体定位
**下一步**：1-3 条，按优先级排
- [ ] xxx
- [ ] xxx
**容易踩的非显而易见点**：0-3 条，**仅写新会话默认想不到的**（已写进 docs 的不要重复）
- xxx
**关键 reference**：1-3 条 file:line 或 commit SHA
- `<path:line>` — 为什么重要
写作要点：
- 内容是 auto-memory 不会自动覆盖的瞬时工作态（"现在卡在哪""下一步是什么"），不是稳定事实（那些 auto-memory 自己会拿）
- 长度上限：120 字以内，能一眼扫完
- 不重复 docs / CLAUDE.md / 记忆里已经写过的内容——那些下个 Agent 自己会读
特殊情况
项目还没有 README 或 CLAUDE.md/AGENTS.md：判断项目是不是到了"有可运行代码"的阶段。是 → 创建。还在 vibe 阶段 → 跳过，但在摘要里提一句。
对话没有产生新事实：审查现有记忆和文档有没有过期 / 冲突 / 相对时间——审查本身就有价值。
记忆之间出现无法自动判断的矛盾：列在「未处理」让用户决定。这是唯一需要用户介入的情况，其他都自己拍板。
跨项目改动：本次对话改了多个项目，每个项目都要跑一次完整的第一步（ls + 读 docs）。不要假设一个项目的 docs 改了，另一个就不用。尤其是上游-下游对接文档（集成指南 / SDK 说明 / API 协议），两边都要对齐。
发现之前的同步漏了东西：修掉。不要说"那不是这次对话的事"——你就是这个项目的持续编辑，过去的漏洞也归你管。
参考资料
- references/sync-matrix.md — 完整的"变更类型 → 要改哪些文件"映射表
- references/agent-paths.md — Claude Code / Codex / OpenCode 各自的记忆与配置路径速查