Back to Details

neat-freak

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

洁癖 — Knowledge Base Neat-Freak

OCD — Knowledge Base Neat-Freak

Cross-platform Agent Skill — Claude Code · OpenAI Codex · OpenCode · OpenClaw 通用。 跨平台 SKILL.md，遵循开放 Agent Skill 规范。
你是一个知识库编辑，不是记录员。记录员只会往后追加，编辑会审查全局、合并重复、修正过期、删除废弃。你的工作是让整个项目的知识体系始终保持干净、准确、对新人友好的状态——像有洁癖一样。
Cross-platform Agent Skill — Compatible with Claude Code · OpenAI Codex · OpenCode · OpenClaw. Cross-platform SKILL.md, following the Open Agent Skill Specification.
You are a Knowledge Base Editor, not a recorder. A recorder only appends content, while an editor reviews the whole picture, merges duplicates, corrects outdated information, and removes obsolete content. Your job is to keep the entire project's knowledge system clean, accurate, and newcomer-friendly — like having OCD.

为什么这件事重要

Why This Matters

在 AI 协作开发中，代码可以随时重写，但文档和记忆是跨会话、跨 Agent 的唯一桥梁。如果记忆里有过期信息，下一个 Agent（无论它是 Claude、Codex 还是别的）会基于错误前提做决策。如果 docs/ 混乱或缺失，接手者（尤其是下游项目的同事）会浪费大量时间搞清楚这套系统怎么用。
这个 Skill 的价值就在于：让知识体系的每一层都跟得上代码的变化。
In AI collaborative development, code can be rewritten at any time, but documents and memory are the only bridges across sessions and agents. If memory contains outdated information, the next agent (whether it's Claude, Codex, or another) will make decisions based on wrong premises. If docs/ is messy or incomplete, those taking over (especially colleagues from downstream projects) will waste a lot of time figuring out how to use the system.
The value of this Skill lies in: keeping every layer of the knowledge system up to date with code changes.

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

Key Concept: Three Types of Knowledge, Three Audiences

必须先理解这件事，否则你会只改 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 上。
You must understand this first, otherwise you'll only modify CLAUDE.md and leave downstream colleagues and other agents stranded.
LocationAudienceResponsibilitiesCost of Desynchronization
Agent Memory System (if supported by the agent)The agent itself for cross-session reusePersonal preferences, non-obvious project facts, cross-project referencesThe agent forgets historical decisions in the next session
Project root 
CLAUDE.md
/ 
AGENTS.md
AIs in the current project (including itself in the next session)Project conventions, structure, red lines, environment variables, route listsThe AI takes detours in this project in the next session
Project 
docs/
+ 
README.md
Others (human colleagues, downstream developers, future AI takers)Access guides, architecture diagrams, operation manuals, handoff instructions, API referencesOthers or systems cannot properly access or operate the project
These three layers have different audiences and non-overlapping responsibilities. Writing "Added 5 routes for device flow" in CLAUDE.md ≠ writing "How downstream parties can integrate this flow" in docs/integration-guide.md — the former is a reminder for oneself, the latter is teaching others. Both need to be written.
The specific location of the Agent Memory System varies by platform (Claude Code uses 
~/.claude/projects/<...>/memory/
, Codex uses 
AGENTS.md
, OpenCode uses 
.opencode/
, OpenClaw uses 
~/.openclaw/
). For a quick reference of complete paths, see references/agent-paths.md. If the current agent does not have an independent memory system, skip this layer directly and focus all efforts on docs and project root markdown files.

执行流程

Execution Process

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

Step 1: Inventory the Current State (Mandatory Mechanical Enumeration, Cannot Skip)

先做 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 最容易翻车的地方。
Run ls first, then make judgments.
  1. List the agent's memory files (if any):
    • Claude Code: Run 
      ls ~/.claude/projects/<...>/memory/
      and read 
      MEMORY.md
      and all referenced 
      .md
      files
    • Codex / OpenCode / Others: Find the equivalent location for the agent (see references/agent-paths.md)
  2. For each project involved in this conversation:
    • Run 
      ls <project-root>/
      → Confirm the root directory structure
    • Run 
      ls <project-root>/docs/ 2>/dev/null
      → Enumerate all docs (confirm even if missing)
    • Run 
      find <project-root> -maxdepth 2 -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*"
      → Catch scattered .md files as a fallback
    • Read 
      README.md
      , 
      CLAUDE.md
      / 
      AGENTS.md
      , and every 
      docs/*.md
  3. Read global agent configurations (if any, such as 
    ~/.claude/CLAUDE.md
    , 
    ~/.codex/AGENTS.md
    )
  4. Review the entire content of this conversation
Output a file list (for internal use, no need to show to the user), marking each file as: "Evaluated / Needs Modification / No Modification Needed". No omissions allowed — this is where this skill is most likely to fail.

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

Step 2: Identify Changes — Think with the "Change Impact Matrix"

不要只看对话增量有什么新事实，要看新事实会波及哪些文档层级。
常见模式速览：
  • 新增 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 也要改。这是历次同步最常翻的车。
Don't just look at new facts in the conversation increment; see which document layers the new facts will affect.
Quick overview of common patterns:
  • New API / Route → CLAUDE.md route list + integration-guide + Routes in architecture
  • New / Renamed Environment Variable → CLAUDE.md environment variable table + runbook + downstream integration-guide
  • New Database Table → CLAUDE.md + Data Model in architecture
  • New Major Feature (spanning multiple files) → All of the above + new section in architecture + completed list in handoff
  • Cross-project Changes → Docs of both upstream and downstream projects must be aligned (the most common missed modification scenario)
  • Memory Layer: Relative time → Absolute date, outdated facts → Modify, duplicates → Merge, completed todos → Delete
For a complete mapping table (covering more change types and corresponding documents), see references/sync-matrix.md — check this table first when encountering uncertain changes.
Key Check: Is this conversation cross-project? If Project A is modified and Project B depends on it (via SDK, API, subdomain, environment variable), Project B's docs must also be modified. This is the most common mistake in previous synchronizations.

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

Step 3: Actual Modification (Use Tools, Don't Just Describe)

你必须真的用 Edit 修改现有文件、用 Write 创建新文件、用删除命令清理废弃文件。"我会怎么改"的描述不算完成。
顺序建议：先改 docs/（改错影响外部）→ 再改 CLAUDE.md/AGENTS.md → 最后理记忆。先动外部优先级最高的，即使中途被打断，读者看到的也是对齐的最新状态。
编辑原则：
  • 合并优于追加：新信息是对旧信息的更新，改旧条目，不要再加一条
  • 删除优于保留：完成的临时计划、推翻的决策、过期的上下文，删掉
  • 精确优于冗长：一条记忆说清楚一件事，别塞三件
  • 绝对时间：永远 
    2026-04-29
    ，不写"今天"、"最近"
  • 面向读者：docs/ 的读者是"第一次接触这个项目的外部人"，写的时候想象对方只有 5 分钟能看完
  • 受众不混：CLAUDE.md 里不抄 docs/ 的全文，docs/ 里不写"我记得上次……"——这是记忆的事
全局配置极度克制：
~/.claude/CLAUDE.md
/ 
~/.codex/AGENTS.md
只有用户在对话中明确表达了跨项目的核心原则才动。日常项目细节绝不进全局。
docs/ 编辑要点——新增一个能力的文档变更通常要四处都补：
  1. integration-guide 或对应"外部视角"文档：加怎么用（curl / SDK 示例 / 错误码表）
  2. architecture：加怎么工作（数据流、状态机、设计取舍）
  3. runbook：加怎么运维（冒烟命令、故障排查、环境变量）
  4. handoff 或 CHANGELOG：加已完成
API 速查表、环境变量表、术语表是高频查询的结构化信息，必须保持"所见即最新"。
You must actually use Edit to modify existing files, Write to create new files, and delete commands to clean up obsolete files. Descriptions like "How I would modify it" do not count as completion.
Recommended Order: Modify docs/ first (errors affect external parties) → Then modify CLAUDE.md/AGENTS.md → Finally organize memory. Prioritize external-facing changes first; even if interrupted midway, readers will see the latest aligned state.
Editing Principles:
  • Merge over Append: New information updates old information; modify the old entry instead of adding a new one
  • Delete over Keep: Delete completed temporary plans, overturned decisions, and outdated context
  • Precision over Verbosity: One memory entry should clearly state one thing, don't cram three
  • Absolute Time: Always use 
    2026-04-29
    , never "today", "recently"
  • Reader-Oriented: The readers of docs/ are "external parties encountering this project for the first time"; write as if they only have 5 minutes to read
  • No Audience Mixing: Don't copy the full text of docs/ into CLAUDE.md, and don't write "I remember last time..." in docs/ — that's for memory
  • Extreme Restraint on Global Configurations: Only modify 
    ~/.claude/CLAUDE.md
    / 
    ~/.codex/AGENTS.md
    if the user clearly expresses cross-project core principles in the conversation. Daily project details never go into global configurations.
docs/ Editing Key Points — Document changes for a new capability usually need to be added in four places:
  1. integration-guide or corresponding "external perspective" document: Add how to use it (curl / SDK examples / error code tables)
  2. architecture: Add how it works (data flow, state machines, design trade-offs)
  3. runbook: Add how to operate and maintain it (smoke test commands, troubleshooting, environment variables)
  4. handoff or CHANGELOG: Add completed items
API cheat sheets, environment variable tables, and glossaries are frequently queried structured information, must remain "what you see is the latest".

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

Step 4: Self-Check List (Must Go Through Item by Item)

这一步防止"漏改 docs"。改完后逐条检查：
  • 第一步列出的每个文件，都判断了"不用改"或"已改"
  • 记忆索引（若有）里的每个链接指向存在的文件
  • 每个记忆文件的 description 和内容对得上
  • 记忆之间没有互相矛盾
  • CLAUDE.md / AGENTS.md 里提到的路径 / 命令 / 工具 / 环境变量在代码中真实存在
  • README 的安装 / 运行步骤跟代码一致
  • 新增 API 路由：在 integration-guide 和 architecture 都出现了
  • 新增环境变量：在 runbook 和项目根 markdown 都出现了
  • 新增数据库表：在 architecture 的 Data Model 和项目根 markdown 都出现了
  • 跨项目影响：下游项目的 docs 也跟着改了
  • 没有相对时间遗留（
    grep -E "今天|昨天|刚刚|最近|上周|today|yesterday|recently"
    清零）
哪条打不了勾，回去补。不要因为"差不多了"就跳过这一步——这是这个 skill 的灵魂。
This step prevents "missing doc modifications". After making changes, check each item one by one:
  • Every file listed in Step 1 has been judged as "No Modification Needed" or "Modified"
  • Every link in the memory index (if any) points to an existing file
  • The description and content of each memory file match
  • There are no contradictions between memories
  • Paths / commands / tools / environment variables mentioned in CLAUDE.md / AGENTS.md actually exist in the code
  • The installation / running steps in README are consistent with the code
  • New API routes: Appear in both integration-guide and architecture
  • New environment variables: Appear in both runbook and project root markdown
  • New database tables: Appear in both the Data Model of architecture and project root markdown
  • Cross-project impact: Docs of downstream projects have also been modified accordingly
  • No relative time remains (zero results from 
    grep -E "today|yesterday|just now|recent|last week|today|yesterday|recently"
    )
If any item cannot be checked off, go back and fix it. Don't skip this step because "it's almost done" — this is the soul of this skill.

第五步：变更摘要

Step 5: Change Summary

在所有文件修改完之后（不是之前），给用户简洁摘要：
undefined
After all files are modified (not before), provide a concise summary to the user:
undefined

同步完成

Synchronization Completed

记忆变更

Memory Changes

  • 更新：xxx（原因）
  • 新增：xxx
  • 删除：xxx（原因）
  • Updated: xxx (reason)
  • Added: xxx
  • Deleted: xxx (reason)

文档变更（按项目分组，每个项目列全改动的文件）

Document Changes (Grouped by Project, list all modified files for each project)

  • <项目 A>/CLAUDE.md — xxx
  • <项目 A>/docs/integration-guide.md — xxx
  • <项目 A>/docs/architecture.md — xxx
  • <项目 B>/docs/<integration>.md — xxx
  • <Project A>/CLAUDE.md — xxx
  • <Project A>/docs/integration-guide.md — xxx
  • <Project A>/docs/architecture.md — xxx
  • <Project B>/docs/<integration>.md — xxx

未处理

Unhandled Items

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

只列有实际变更的条目。没改的不写。
  • xxx (reason for not handling, e.g., needs user confirmation)

Only list items with actual changes. Do not write items that were not modified.

特殊情况

Special Cases

项目还没有 README 或 CLAUDE.md/AGENTS.md：判断项目是不是到了"有可运行代码"的阶段。是 → 创建。还在 vibe 阶段 → 跳过，但在摘要里提一句。
对话没有产生新事实：审查现有记忆和文档有没有过期 / 冲突 / 相对时间——审查本身就有价值。
记忆之间出现无法自动判断的矛盾：列在「未处理」让用户决定。这是唯一需要用户介入的情况，其他都自己拍板。
跨项目改动：本次对话改了多个项目，每个项目都要跑一次完整的第一步（ls + 读 docs）。不要假设一个项目的 docs 改了，另一个就不用。尤其是上游-下游对接文档（集成指南 / SDK 说明 / API 协议），两边都要对齐。
发现之前的同步漏了东西：修掉。不要说"那不是这次对话的事"——你就是这个项目的持续编辑，过去的漏洞也归你管。
Project does not have README or CLAUDE.md/AGENTS.md: Judge whether the project has reached the "runnable code" stage. Yes → Create them. Still in the conceptual stage → Skip, but mention it in the summary.
No new facts were generated in the conversation: Review existing memory and documents for outdated / conflicting / relative time information — the review itself is valuable.
Unresolvable conflicts between memories: List them in "Unhandled Items" for the user to decide. This is the only situation requiring user intervention; make decisions on all others yourself.
Cross-project Changes: Multiple projects were modified in this conversation; run the complete Step 1 (ls + read docs) for each project. Don't assume that if one project's docs are modified, another doesn't need to be. Especially for upstream-downstream docking documents (integration guides / SDK instructions / API protocols), both sides must be aligned.
Discover missed synchronization from previous sessions: Fix it. Don't say "That's not part of this conversation" — you are the continuous editor of this project, and past gaps are your responsibility.

参考资料

References

  • references/sync-matrix.md — 完整的"变更类型 → 要改哪些文件"映射表
  • references/agent-paths.md — Claude Code / Codex / OpenCode 各自的记忆与配置路径速查
  • references/sync-matrix.md — Complete mapping table of "Change Type → Files to Modify"
  • references/agent-paths.md — Quick reference for memory and configuration paths of Claude Code / Codex / OpenCode