Neat Freak

SKILL.md

---
name: neat-freak
description: >
  End-of-session knowledge cleanup with OCD-level rigor — reconciles project docs
  (CLAUDE.md, README.md, docs/) and agent memory against the code, and audits whether
  the workspace's own rules are being followed (naming conventions, required files,
  CLAUDE.md/AGENTS.md symlink integrity, dead references inside rule files).
  会话结束后对项目文档和记忆进行洁癖级审查与同步，并审计规范执行情况。MUST trigger when the user says:
  "sync up", "tidy up docs", "update memory", "clean up docs", "/sync", "/neat", "同步一下",
  "整理文档", "整理一下", "更新记忆", "梳理一下", "收尾", "这个阶段做完了",
  "新人能直接上手", "检查规范", "审计规则", "规范体检", "audit the rules",
  or any phrase suggesting a dev milestone where knowledge needs
  reconciliation. Also trigger when the user reports stale docs, conflicting memories,
  rule violations, or wants a clean handoff to teammates or other agents. Bare "整理" / "tidy" with
  prior dev context counts — do not under-trigger. Cross-platform: works on Claude Code,
  OpenAI Codex, OpenCode, and OpenClaw.
---

# 洁癖 — 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 晾在那儿。**

| 位置 | 受众 | 职责 | 不同步的代价 |
|------|------|------|--------------|
| **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 在 `~/.codex/AGENTS.md`【手改、权威】+ `~/.codex/memories/`【机器生成、勿手改】，OpenCode 用 `.opencode/`，OpenClaw 用 `~/.openclaw/`）。完整路径速查见 [references/agent-paths.md](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。**

**效用信号辅助毕业/淘汰判断**：同步时给本次会话实际引用过的记忆条目在索引行补「最后引用 `YYYY-MM-DD`」；连续多次同步未被引用且非 `reference_` 类的条目列为淘汰候选。记忆的价值在被用到——实证研究表明「只增不删」的记忆库会直接拖低任务成功率，长期没人引用的记忆是负资产。

> 记忆文件若用类型前缀（如 `feedback_`=教训 / `project_`=决策事件 / `reference_`=速查），生命周期不同：`reference_` 通常合法长期常驻；`feedback_` 稳定后毕业；`project_` 多数是事件记录，**是优先毕业 / 删除的对象**——决策结论进 docs，过程进 changelog。`reference_` 类视为**只读参考层**：日常会话不动它，变更只经由本 skill 的同步流程。
>
> **毕业的去向只有两个：docs/ 或 CLAUDE.md。本 skill 永远不把记忆毕业成 skill，也永远不新建任何 skill——这是用户的明确约定，任何情况下不要提议突破。**

### 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？ | 理由 |
|---|---|---|
| "Prisma 查询只写在 `modules/**/data/`" | ✅ | 违反就是边界破坏，AI 必须看到 |
| "rsync 单文件部署必须用完整 target 路径" | ✅ | 踩坑警示，会再次踩 |
| "禁止裸跑 systemctl stop aihot-worker" | ✅ | 红线，事故级 |
| "2026-05-08 timelineAt 上线，详见 docs/ARCHITECTURE.md §5.4" | ❌ | 详细机制在 docs；AI 改到这块自然会读 docs；「深入文档」指针表已做这件事 |
| "2026-04-30 起公网开放，匿名可访 /、/all" | ❌ | 既是历史也是事实，但事实归 docs/ARCHITECTURE.md §8 + 项目概览一句话足矣 |
| "5/8 修了 X bug 的复盘细节" | ❌ | 单次事故记忆，归 memory 或干脆删 |

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

### 规则层也是知识——它同样会烂

全局指令、工作空间 CLAUDE.md、项目 CLAUDE.md 构成一个层级规则体系。规则不是只读背景：它引用的项目会被删掉（死引用）、它定的约定会被后来的实践悄悄违反（漂移）、上下两级会互相打架（矛盾）。没人审计的规则会退化成装饰品。

处理规则层有一条铁律：**规则的真身永远在层级 CLAUDE.md 里，本 skill 不复制任何具体规则内容**——复制会制造两处真相，规则一改副本就烂，这正是洁癖要消灭的头号病。所以你的做法永远是：**现场读规则 → 提取可核验项 → 核对实践 → 处置**（具体流程在第二步）。

## 执行流程

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

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

| 文件 | 上限 | 超过怎么办 |
|---|---|---|
| `CLAUDE.md` / `AGENTS.md` | ~300 行 / ~15KB（软） | 先精简：扫顶部 blockquote / 历史叙事段 → 删 / 迁 docs；项目概览只留 1-3 行 + 速查表，不做"提醒下次会话"用。（CLAUDE.md 每会话全量常驻加载，不会被截断，但它占用的是最贵的注意力预算——只配放普遍适用的内容，这也是 Anthropic 官方判据） |
| 记忆索引 `MEMORY.md` | **≤200 行 且 ≤25KB（硬）** | Claude Code 只加载 `MEMORY.md` 的前 200 行或前 25KB（先到先算），**超出部分在会话开始时静默不加载——等于没记**。务必压在 ~150 行 / ~18KB 留缓冲。压法不是硬删，是下面的「毕业」机制：详细机制提升进 docs、索引只留一行指针 |
| 单条 memory 文件 | ~100 行（软） | 通常在塞多件事 / 写成事故复盘 → 拆 / 删；**若是稳定机制说明，提升进 docs 再把记忆缩成 reference 指针** |
| `docs/<single>.md` | ~1500 行（软） | 切分成多文件，加目录索引 |

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

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

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

体检读数（行数 / 字节数 / 距上限百分比）记下来，最后要进变更摘要——用户看不到读数，就永远不知道自己离静默截断有多近。

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

**先做 ls，再做判断。**

0. **平台探测**：`ls -d ~/.claude ~/.codex ~/.config/opencode ~/.openclaw 2>/dev/null`——只盘点真实存在的平台，不存在的平台整层跳过（别按想象中的路径空跑）。
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. **向上收集规则文件**：从项目根往上走到工作空间根（如 `~/code`），把沿途每一级的 `CLAUDE.md` / `AGENTS.md` 都读了，再读全局配置（`~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md`，若存在）。这些是第二步规范审计的依据。
4. 回顾本次对话全部内容

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

### 第二步：规范执行审计（规则 → 实践）

拿着第一步收集的层级规则文件，做两个方向的审计。范围默认是**当前项目 + 它的直接上级工作空间**；用户明确说「审全部」才做全仓扫描。

**方向一：实践有没有跟上规则。** 从规则文件里提取「可机械核验的约定」——特征是谈论文件、目录、命名、必备内容的祈使句。常见类别（以现场读到的规则为准，不要背这张清单）：

- **命名约定**：如目录必须 kebab-case → `ls` 核对当前项目及同级项目名
- **必备文件**：如每个项目必须有 CLAUDE.md、线上项目必须在顶部声明 URL → 检查存在性和内容
- **同源约束**：如 AGENTS.md 必须是指向 CLAUDE.md 的软链 → `readlink` 核对
- **红线**：如 `.gitignore` 必须含 `.env*`、密钥不进代码 → grep 核对
- **目录纪律**：如根目录不允许裸放文件 → `ls` 核对

**处置分级**（关键，别一把梭）：

| 类型 | 例子 | 处置 |
|---|---|---|
| 安全、可逆、纯补齐 | 补 AGENTS.md 软链；给缺 CLAUDE.md 的项目按模板建脚手架；`.gitignore` 补 `.env` 条目 | **直接修**，摘要里报告 |
| 破坏性、有外部影响 | 目录重命名（会破坏 git remote、部署脚本、Syncthing 路径、他人引用）；删除文件；合并两份内容不一致的 CLAUDE.md/AGENTS.md（要先人工确认哪边是权威） | **不动手**，列入摘要「待你拍板」，附影响说明和建议 |

**同类违规反复出现 → 建议 hook 化**：同一条规则在多个项目或多次同步中反复被违反，说明散文规则挡不住它——散文规则是建议性的，hook 是确定性的。在「待你拍板」里建议用户把这条规则转成 hook（事中强制拦截），从「每次事后修」升级为「一次性根治」。本 skill 只建议，不代配 hook。

**方向二：规则文件本身有没有烂。** 规则也是文档，用同样的洁癖标准审它：

- **死引用**：规则里提到的路径 / 项目 / 命令还存在吗？（grep 出路径 → `ls` 核验）项目确认已删的，把引用清掉；拿不准的列「待你拍板」
- **矛盾**：上下两级规则打架、规则与 skill 的指引打架、同一文件内自相矛盾 → 能判断哪边是现行事实的直接改，判断不了的列出来
- **漂移**：规则说 X，但所有项目实际都在做 Y 且运转良好 → 这可能是规则过时而非实践错误，列「待你拍板」建议改规则

**对全局配置（`~/.claude/CLAUDE.md` 等）的克制要分清方向**：克制的是**新增内容**——日常项目细节绝不写进全局；但**清理是减法**，死引用、过期事实、矛盾照样要修或上报，别拿「克制」当不审计的借口。

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

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

常见模式速览：
- 新增 API / 路由 → CLAUDE.md 路由清单 + integration-guide + architecture 的 Routes
- 新增 / 改名 环境变量 → CLAUDE.md 环境变量表 + runbook + 下游 integration-guide
- 新增数据库表 → CLAUDE.md + architecture 的 Data Model
- 新增大特性（跨多文件） → 以上全部 + architecture 新章节 + handoff 已完成清单
- 跨项目改动 → 上下游两边的 docs **都要对齐**（最常见的漏改场景）
- **退役 / 改名 / 下线** → `git show <删除 commit> --stat` 取被删的路由/导出符号/字段/枚举名，对每个跑 `grep -rn '<symbol>' docs/ <本 agent 记忆目录>`（Codex 还要 grep `~/.codex/AGENTS.md` + `~/.codex/memories/skills/`），**在同一次同步里清掉非载荷引用（示例代码/历史案例/枚举列举）**，别留到事后的「补漏」commit。死 skill 目录整个删。
- 记忆层面：相对时间→绝对日期、过期事实→改、重复→合并、已完成待办→删
- **过期开放项扫描**：grep 记忆里同时带「开放项标记（待办/未决/暂缓/搁置/待评估/仍未/观察期再评估/TODO）」**且**「绝对日期早于今天」的行（别裸扫日期——绝对日期满天飞、大多是正确历史；marker 同行才是信号）。每条强制处置：① 已落地→链接 commit 并删；② 没落地→从「计划」降级为「未决，未排期，触发条件=X」，别让它再冒充已排期承诺；③ 已放弃→删。**写「已完成」前先对照真实代码与产物核实**，别假设已上线。

完整映射表（覆盖更多变更类型与对应文档）见 **[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.md 与 AGENTS.md 必须同源（软链，CLAUDE.md 为真身）。永远只编辑 CLAUDE.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，回去毕业

**规范执行（第二步的产出核对）**：
- [ ] 层级规则文件从项目根读到了工作空间根 + 全局
- [ ] 可核验约定逐条核对过：每条违规要么已修（安全类），要么进了摘要「待你拍板」（破坏类）——没有第三种"看见了但没记录"
- [ ] AGENTS.md 与 CLAUDE.md 同源（软链完好，没有内容分叉的两份文件）
- [ ] 规则文件里引用的路径 / 项目在现实中存在（死引用已清或已上报）

**完整性 / 反漏改（再查这组）**：
- [ ] 第一步列出的每个文件，都判断了"不用改"或"已改"
- [ ] 记忆索引（若有）里的每个链接指向存在的文件
- [ ] 每个记忆文件的 description 和内容对得上
- [ ] 记忆之间没有互相矛盾
- [ ] **没有过期开放项冒充活计划**：带「待办/未决/暂缓」且日期早于今天的行，都已核实落地与否并处置（链 commit 删 / 降级为未决 / 删）
- [ ] **退役类改动**：被删 symbol 在 docs/ + 记忆（含 Codex `~/.codex/`）里的非载荷引用已清，死 skill 目录已删
- [ ] 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
- <项目 B>/docs/<integration>.md — xxx

### 规范审计
- 自动修复：xxx（如：补了 AGENTS.md 软链）
- 待你拍板：xxx（为什么破坏性 / 建议怎么处理）

### 体检读数（仅在逼近上限时列出）
- <项目> MEMORY.md：N 行 / N KB —— 已达上限的 N%，建议毕业 xxx

### 未处理
- xxx（为什么没处理）
```

只列有实际变更 / 需要行动的条目。没改的不写；体检读数只在超过上限 70% 时展示（低于就静默）——摘要是行动引导，不是巡检日志。

## 特殊情况

**项目还没有 README 或 CLAUDE.md/AGENTS.md**：判断项目是不是到了"有可运行代码"的阶段。是 → 创建（工作空间规则有模板就按模板）。还在 vibe 阶段 → 跳过，但在摘要里提一句。

**对话没有产生新事实**：审查现有记忆和文档有没有过期 / 冲突 / 相对时间，并跑一遍第二步规范审计——审查本身就有价值。

**需要用户介入的情况只有两类**：① 记忆 / 规则之间出现无法自动判断的矛盾；② 破坏性的规范修复（重命名、删除、合并分叉文件）。这两类列进「待你拍板」，其他都自己拍板。

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

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

## 参考资料

- **[references/sync-matrix.md](references/sync-matrix.md)** — 完整的"变更类型 → 要改哪些文件"映射表
- **[references/governance.md](references/governance.md)** — 规范执行审计的可核验约定类别与处置细则
- **[references/agent-paths.md](references/agent-paths.md)** — Claude Code / Codex / OpenCode / OpenClaw 各自的记忆与配置路径速查