lsa03/neat-freak-person/skill

洁癖 — 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 / AGENTS.md 就结束，把下游同事和其他 agent 晾在那儿。

CLAUDE.md / AGENTS.md vs README.md：受众不同，职责不同

CLAUDE.md / AGENTS.md 告诉 AI "你应该怎么做事"——就像给一位聪明但完全不了解项目背景的 AI 新同事写的"入职手册 + 行为准则"，用具体、可执行的语言，把"项目是什么、怎么跑、怎么写代码、绝对不能做什么"一次性说清楚。

README.md 告诉人类 "这个项目能做什么"——优秀的 README 是对读者时间的尊重，用最短的时间让人说"我懂了，这有用"，并给出清晰的下一步。始终站在新手的视角，让它能复制、能运行、能看懂。

两者受众不同、内容不重叠。CLAUDE.md 里写"Prisma 查询只写在 modules/**/data/" ≠ README 里写"快速开始：npm install && npm run dev"——前者是告诉 AI 行为约束，后者是告诉人怎么用。两份都要有，不能互相替代。

CLAUDE.md 和 AGENTS.md 功能等价，只维护一个即可。 如果项目同时被多个 agent 平台使用，一份主文件 + 另一份用一行 See CLAUDE.md 跳转。同时维护两份只会导致信息不一致。

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 / AGENTS.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 / AGENTS.md 顶部加一段 blockquote 历史叙事——"2026-05-08 X 功能上线，详见 docs/Y.md"。一次很爽，半年后顶部就是 200 行 blockquote 把真正的规则推到看不见。这种叙事不属于 CLAUDE.md / AGENTS.md，它的归宿是 git log / /changelog 页 / docs/CHANGES.md。

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

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

文档规范基线

初始化和常规同步都以这组基线为"尺子"衡量文档质量。完整的 CLAUDE.md / AGENTS.md（11 个板块）、README.md（11 个板块）、docs/ 目录规范基线见 [references/doc-standards.md](references/doc-standards.md)。

核心原则（审查时牢记）：

• CLAUDE.md / AGENTS.md 和 README.md 的板块为必须；docs/ 的规范为建议，项目实际情况不满足时以用户要求为准
• CLAUDE.md / AGENTS.md 不是变更日志——不含历史叙事、不含"详见 docs/X.md"的 blockquote
• README 不与 CLAUDE.md / AGENTS.md 重复——README 告诉人"能做什么"，CLAUDE.md / AGENTS.md 告诉 AI"怎么做事"
• docs/ 按角色分层——每个文件专注一个主题、命令可执行、内容与代码同步更新

执行流程

流程入口：初始化模式检测

进入技能后，先判断走初始化还是常规同步。判断按以下优先级，先命中先走：

优先级 1 — 用户显式意图（最高）：

• 用户明确要求初始化（按语义匹配，不按精确字符串匹配。"初始化项目" / "初始化下项目" / "初始化一下" / "项目初始化吧" / "init project" / "首次梳理" / "从头整理" / "bootstrap docs" 等均算——只要意图是"从零建立项目知识体系"即可）→ 走初始化
• 用户明确要求同步（"同步一下" / "sync up" / "整理一下" / "tidy up" / "/sync" / "/neat" / "搞一下文档" / "搞一下" 等）→ 走常规同步，即使项目缺少文档也不自动切到初始化——用户要的是"对齐现状"，不是"从零建"

优先级 2 — 自动检测条件（仅在用户未显式表态时生效）： 满足任一即走初始化：

• CLAUDE.md 和 AGENTS.md 均不存在或为空
• docs/ 不存在或为空
• README.md 不存在

优先级 3 — 辅助信号（不独立触发，只用于增强判断）：

• 项目根目录无 neat-freak 初始化标记（<!-- neat-freak: initialized at ... -->）——单独不触发初始化，只在优先级 2 的条件部分满足时作为"倾向初始化"的辅助判据。一个文档完善但没用过 neat-freak 的项目不应因此被判定为需要初始化。

冲突解决原则：用户显式意图 > 自动检测条件 > 辅助信号。任何冲突都按此优先级裁决。

初始化流程

Step 0-init：代码事实提取

初始化的核心是检查代码与文档的一致性，所以第一步是从代码中提取事实，作为比对的基准。

从代码中提取以下事实，产出代码事实清单（内部用，供 Step 1-init 比对）：

1. 项目类型 — Web 服务 / 库 / CLI / Monorepo / Skill 类项目 / 其他。Skill 类项目识别：根目录或 skill/ 子目录下有 SKILL.md 即判定为 Skill 类项目。此类项目的文件分两类，应按目录分层存放：

• Skill 运行时文件（应放在 skill/ 子目录）：SKILL.md、references/、tools/、examples/、assets/ — 这些是 Skill 的核心交付物，是 Agent 运行时读取的文件，不是"文档"，不应被当作需要迁移到 docs/ 的散落 .md
• 开发与治理文件（应放在根目录）：README.md、AGENTS.md、LICENSE、CHANGELOG.md、test-prompts.json、.gitignore — 面向人类开发者和项目治理，与 Skill 运行时无关
• 开发文件（如有）：src/、tests/ 等 — 按普通项目规范处理，放在根目录
• 关键原则：Skill 类项目不强制建 docs/ 目录。SKILL.md 是核心文档，references/ 是详细文档，已构成完整文档体系。强行建 docs/ 反而让结构复杂化。目录结构检查：Skill 运行时文件应在 skill/ 子目录下，开发与治理文件应在根目录下——发现运行时文件散落在根目录时在审查报告中标注为 🟡 中，建议迁移到 skill/ 子目录。

1. 技术栈 — 语言版本、框架及版本、数据库、构建工具、部署方式（从 package.json / go.mod / pyproject.toml / Cargo.toml / Dockerfile 等提取）
2. 目录结构 — 每个顶层目录及关键子目录的职责推断。Skill 类项目：按"项目类型"中定义的分层规则检查（运行时文件在 skill/ 子目录、开发与治理文件在根目录），未分层的项目（运行时文件散落在根目录）在审查报告中标注为 🟡 中，建议迁移到 skill/ 子目录。两类分开评估，不混为一谈
3. 可用命令 — install / dev / test / build / deploy / lint 等所有可用命令（从 package.json scripts / Makefile / CI 配置等提取）
4. 环境变量 — 代码中实际使用的所有环境变量（grep process.env / os.Getenv / dotenv 等）
5. API / 路由 — 所有 API 端点、HTTP 方法、路径（从路由注册代码提取）
6. 数据模型 — 数据库表/模型定义、关键字段
7. 入口文件 — 主入口、启动流程
8. 测试结构 — 测试框架、测试目录、测试命令
9. 代码规范配置 — ESLint / Prettier / Ruff 等配置中的规则
10. 依赖关系 — 核心外部依赖及版本
11. 开源协议 — LICENSE 文件内容
12. 配置文件 — .env.example / .env.*、docker-compose.yml、Dockerfile、tsconfig.json、nginx.conf、vite.config.* 等配置文件的实际内容（服务列表、端口、构建选项、路径别名等）
13. CI/CD 配置 — .github/workflows/*.yml、.gitlab-ci.yml、Jenkinsfile、Makefile 中的构建步骤、测试命令、部署目标、触发条件
14. 项目元数据 — package.json（description / keywords / homepage / repository / engines / scripts）、pyproject.toml（description / requires-python / classifiers）、go.mod（module / go version）等元数据字段

提取原则：只记录代码中实际存在的事实，不推断意图。每条事实要具体到可以与文档逐条比对——"代码中有 12 个 API 端点"比"代码有 API"有用；"环境变量 DATABASE_URL 在 src/config.ts:5 被引用"比"有数据库配置"有用。

代码逻辑与设计文档一致性提取：除了上述静态事实，还需关注代码实际行为与 docs/architecture.md（如有）描述之间的偏差——数据流方向是否与架构图一致、模块间的调用关系是否符合设计文档描述的分层、状态机流转是否与设计文档中的状态图匹配。这类偏差不在提取阶段做判断，但在 Step 1-init 审查时作为专项检查列出。

Step 1-init：代码与文档一致性审查（只审查不动手）

这是初始化的核心步骤。 拿 Step 0-init 提取的代码事实清单，逐条与现有文档比对，找出不一致、过时、缺失。

审查分两个维度，一致性优先：

维度一：一致性检查（核心） — 文档中的描述与代码事实是否一致

维度二：完整性检查（辅助） — 文档是否覆盖了代码事实（用规范基线的板块清单做框架）

对 CLAUDE.md / AGENTS.md、README.md、docs/ 中的每个板块，标注状态（✅ 合格 / ⚠️ 不一致 / ⚠️ 不完整 / ❌ 缺失 / — 不适用，详见模板文件）。

审查报告格式：见 [references/init-report-template.md](references/init-report-template.md)——包含完整的项目概况、一致性问题表、CLAUDE.md / AGENTS.md / README.md / docs/ 各板块审查、散落 .md 文件审查的示例。

Step 2-init：用户确认

初始化必须等用户确认后才动手——这是与常规同步的核心区别。

基于审查报告，输出操作清单供用户逐项确认。操作清单按优先级排列：先修不一致（🔴 高），再补缺失，最后优化。

## 待执行操作清单
 
### 🔴 修复不一致（优先）
- [ ] `README.md` — 修正启动命令 `npm start` → `npm run dev`
- [ ] `README.md` — 补充遗漏的 5 个环境变量
- [ ] `docs/api-reference.md` — 补充遗漏的 7 个 API 端点
- [ ] `DEPLOY.md` — 更新部署方式 PM2 → Docker
 
### 🟡 新建文件
- [ ] `CLAUDE.md / AGENTS.md` — 从零创建，包含 11 个板块
- [ ] `docs/index.md` — 文档索引入口
- [ ] `docs/architecture.md` — 架构说明
- [ ] `docs/getting-started.md` — 本地开发指南
- [ ] `docs/api-reference.md` — API 参考
- [ ] `docs/CHANGELOG.md` — 变更日志
- [ ] `docs/faq-troubleshooting.md` — 常见问题与排错
 
### 修改文件
- [ ] `README.md` — 补充功能特性/许可证/文档索引
 
### 迁移文件
- [ ] `CONTRIBUTING.md` → `docs/contributing.md`
 
请确认以上操作，或告诉我需要调整的地方。你可以：
- 全部确认 → 我按清单执行
- 部分确认 → 只执行你勾选的
- 调整方案 → 告诉我哪里要改
- 取消 → 不执行任何操作

只有收到用户明确确认后才进入 Step 3-init 执行。 用户部分确认则只执行确认的部分；用户要求调整则修改方案后重新确认。

Step 3-init：执行变更

用户确认后，按确认清单执行。执行顺序：

1. 修复不一致（🔴 高优先级 — 错误信息比缺失信息危害更大）
2. docs/ 目录和文档（外部受众）
3. CLAUDE.md / AGENTS.md（AI 受众 — 只建一个）
4. README.md（全人类受众）
5. 迁移和清理

每个文件创建/修改后，立即做一致性校验：确认文档中的每条事实都与代码一致。

Step 4-init：一致性终检 + 写入标记 + 变更摘要

1. 一致性终检（必须逐条过）：

• [ ] 代码中的每个命令 → 在 CLAUDE.md / AGENTS.md 和/或 README.md 中准确记录
• [ ] 代码中的每个环境变量 → 在文档中有说明
• [ ] 代码中的每个 API 端点 → 在 docs/ 中有记录
• [ ] 文档中的每个命令 → 代码中真实可用
• [ ] 文档中的每个路径 → 文件真实存在
• [ ] 文档中的每个技术栈/版本 → 与依赖文件一致
• [ ] 审查报告中的每个 🔴 项 → 已修复或用户确认跳过
• [ ] 审查报告中的每个 ⚠️ 项 → 已处理或用户确认跳过

1. 写入初始化标记：在 CLAUDE.md / AGENTS.md 末尾加 <!-- neat-freak: initialized at <执行当天日期 YYYY-MM-DD> -->（用执行当天的日期，不要照抄示例）。若 CLAUDE.md / AGENTS.md 不存在，则写入 README.md 末尾。

• 审查红线：CLAUDE.md / AGENTS.md 和 README.md 至少存在一个，否则项目连最基本的说明文件都没有，应在 Step 1-init 审查报告中标为 🔴 高优先级缺失，必须在 Step 2-init 操作清单中优先补建。
• 若初始化审查后无需任何变更（文档已完善）→ 仍写入标记，记录"已审查，无需变更"

1. 输出变更摘要（与常规第五步格式一致）

常规同步流程

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

任何同步动作之前，先用 Read 工具读取关键文件检查行数和体积（跨平台：不要依赖 wc -l / du 等 Unix 命令，Windows 不可用）：

额外做一次「体量倒挂」体检：对比 <memory 目录> 与 docs/ 的总体积（用 Glob 列出文件后逐个 Read 统计，或用 ls -la / Windows 的 dir，不要依赖 du -sh）。健康态是 docs 厚、memory 薄——docs 是沉淀的权威层，memory 是流动的「最近教训 + 指针」层。若 memory 反而比 docs 大，几乎一定是「本该毕业进 docs 的稳定知识还赖在松散记忆文件里」，按「毕业」机制往上泵，别只在 memory 内部挪。

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

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

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

先做 ls，再做判断。