jimweller/documenter-plugin

更新项目文档

两个职责：

1. CLAUDE.md — 简洁的项目概览（始终加载）
2. .llmdocs/ — 详细的概念文档（按需加载）。此目录下的所有文件均为持久性设计文档。

---

1. CLAUDE.md — 地图

范围

找到项目中所有 CLAUDE.md 和 .llmdocs/ 目录并逐一更新。 注意子文件夹层级、范围和限界上下文。不要在 不同层级的文档之间泄漏概念。每个 CLAUDE.md 和 .llmdocs/ 只覆盖其所在目录层级及以下，绝不包含父级关注点。

如果用户提供了特定的指导或关注领域，在决定更新哪些文档以及强调什么内容时应用该上下文。

收集上下文

永远不要直接运行 git。此插件附带的基线脚本已涵盖此技能所需的所有 git 操作。从仓库根目录运行每个命令，并每次都写出脚本的完整路径，因为 shell 变量在命令之间不会持久化。

从计划开始。它会找到每个 CLAUDE.md 及其 .llmdocs/（包括尚不存在的必需文件），解析每个文档的基线，列出自基线以来发生的变化，并说明每个文档应如何处理。当用户的指导指定了要关注的目录时，在 llmdocs 之后传递它们。否则不传递任何内容。

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan llmdocs [<focus-dir>...]

计划为每个操作输出一个块。

• ## update 命名一个基线、一个范围以及共享该基线的文档，然后列出自该基线以来的提交、差异统计和状态。使这些文档保持最新。更改未影响到的文档保留其内容。
• ## new 列表出需要根据当前代码编写的新文档。它们不需要历史记录。
• ## unchanged 和 ## outside the focus 列出应保持完全不变的文档。

head none 表示仓库没有提交。每个文档都是新的。

对于更新块，统计其差异中的文件数。超过 20 个时，跳过完整差异，直接读取更改的文件。20 个或更少时，读取差异。未跟踪的文件（标记为 ??）不会出现在差异中，因此无论如何都需要直接读取它们。范围可以是块的整个范围或单个文件，因为它是一个 git pathspec。

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" diff <sha> <scope>

然后，对于每个有文档需要更新或编写的 CLAUDE.md/.llmdocs/ 对：

1. 读取当前的 CLAUDE.md 以及 .llmdocs/ 中的每个文件（如果存在）
2. 探索该目录层级及以下的代码库
3. 回顾对话历史，查找相关的决策、更改或经验教训
4. 使用更改和对话上下文来确定发生了什么变化。llmdocs 是当前状态规范，不是变更日志，不是决策日志，不是历史记录。永远不要记录历史信息或所做的选择，只记录编写 llmdocs 时当前的规范。

编写/更新 CLAUDE.md

目标：控制在 500 行以内。每一行都必须有其存在的价值。

# <名称>

<1-2 行说明此目录/组件的目的>

## 技术栈

<项目列表：语言、框架、与此层级相关的关键依赖>

## 布局

<此层级的关键目录及其内容>

## 命令

<构建、测试、代码检查、部署 — 仅命令>

## 约定

<样式、命名、模式 — 仅防止错误的内容>

## 关键概念

<领域术语、业务逻辑，Claude 在此层级必须了解的内容>

## LLM 文档

`.llmdocs/` 中的详细文档：

- @.llmdocs/architecture.md — <1 行描述>
- @.llmdocs/data-model.md — <1 行描述>

CLAUDE.md 规则

• 不要写冗长的解释 — Claude 会自行推断
• 不要重复 .llmdocs/ 的内容 — 只需引用并附上简短描述
• ## LLM Docs 部分必须列出所有 .llmdocs/ 文件，每个文件附带 1 行描述
• 如果在 ## Docs 下列出了 .llmdocs/ 文件的 CLAUDE.md 早于当前标题，请在你更新文件时将标题重命名为 ## LLM Docs
• 保留现有的自定义指令（git 工作流、环境变量等）
• 仅当代码与文档内容相矛盾时才删除内容，并在摘要中说明每项删除
• 当代码删除了某个函数、标志或模块时， grep 搜索此层级的所有文档中该名称的出现，然后重新读取每个搜索结果以及每个文档的目的行，检查是否有相同内容的通俗描述。仅从一个文档中删除名称是不够的

grep -rn '<已删除的名称>' <dir>/CLAUDE.md <dir>/.llmdocs

• 永远不要在您编写或编辑的文本中包含标记行。finish 会在写入后添加它。当编辑一个已以标记行结尾的文档时，保留该行不变
• 如果某个文档应始终加载，使用 @.llmdocs/filename.md 导入

---

2. .llmdocs/ — 领域

流程

除必需的七个文件之外的概念文件由您自行添加，计划永远不会命名它。finish 仍然会对其进行标记，以及在本次运行期间创建的该层级的所有其他文档。

1. 评估：使用计划的更新块来确定哪些文档受影响
2. 识别：确定哪些现有文档受影响，或者是否需要新建文档
3. 更新 CLAUDE.md：确保 ## LLM Docs 部分列出了任何新文档文件

如果没有需要文档更新的更改，请说明并继续。

位置

使用 CLAUDE.md 的 ## LLM Docs 标题下第一个导入所命名的路径，或者对于早于该标题的 CLAUDE.md，使用其 ## Docs 标题下的路径。否则默认为目标目录层级的 .llmdocs/。CLAUDE.md 和 .llmdocs/ 可以存在于项目的任何目录层级。

结构

扁平结构，每个概念一个文件。前 7 个文件是必需的并且必须始终存在。当项目有测试套件时创建 testing.md，没有时则省略。根据需要创建其他概念文件。

.llmdocs/
  architecture.md    # 组件、交互、数据流（必需）
  api.md             # 端点、请求/响应、认证、授权（必需）
  data-model.md      # 模式、模型、关系（必需）
  deployment.md      # 部署流程、环境（必需）
  ops.md             # 操作手册、维护、故障排除（必需）
  observability.md   # 日志、指标、跟踪、健康检查、仪表盘、告警（必需）
  security.md        # 信任边界、秘密处理、认证/授权、威胁模型（必需）
  testing.md         # 测试布局、运行器、夹具、如何运行测试套件（当项目有测试时）
  <concept>.md       # 根据需要的领域特定文件

文档文件格式

# <概念>

<1 行目的>

## <部分>

<内容：标题、表格、代码块 — 不包含散文段落>

.llmdocs/ 规则

• 每个文件最大 500 行 — 如果更大则拆分
• 在有用时包含文件路径和行引用（src/auth/login.ts:42）
• 增量更新现有文档，不要从头重写
• 如果某个文档是准确的且不受最近更改的影响，保持其内容不变。finish 仍然会更新其标记。
• 准确性优于覆盖率：只记录从代码中可验证的内容
• observability.md 包含系统发出的信号，ops.md 包含操作员执行的操作。健康端点、日志格式或告警属于 observability.md。没有指标或跟踪的项目仍在该文件中记录其 stdout、stderr 和退出码。
• 永远不要在您编写或编辑的文本中包含标记行。finish 会在写入后添加它。您创建的概念文件是这里的陷阱，因为您刚刚读取的每个同级文件都以一个标记行结尾。复制该行会写入一个旧的 sha，声称文档已根据一个从未见过的提交进行了检查。在最后一个内容行结束新文件，让 finish 添加标记。

---

3. 完成

每次运行 finish，即使运行没有写入任何内容。plan 在后台留下了一个计划文件，只有 finish 会删除它，因此跳过 finish 的运行会留下状态，导致下一次运行出现问题。

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" finish llmdocs

它会给计划标记为 new 或 update 的每个文档，以及自计划以来创建的每个文档（例如 testing.md），标记上计划检查时的 HEAD。标记是文档末尾的一行，一个命名该提交的 HTML 注释。finish 会保留未更改的文档和关注范围外的文档，当仓库没有提交时不会进行任何标记。退出码 4 表示计划中的文档丢失。编写它并重新运行 finish。

• 永远不要直接调用 stamp，也永远不要手动编写或编辑标记行。finish 会编写它。
• 标记是元数据。关于不记录历史的规则不适用于它。

---

4. 摘要输出

运行后，输出此摘要。根据运行结果填写每一行，如果某个列表为空，则写入 "none"。在 "Stamped" 下，逐字复制 finish 自己的输出行，每个文档一行。永远不要在那里写入 sha，也永远不要添加 finish 未打印的词。

如果一个句子被改写以删除某个能力，那就是一项删除。在 "Removed" 下列出该删除，包括被删除的措辞，即使同一行仍然存在。

填充示例，来自代码删除了字符计数的运行。

Files created: none
Files modified: CLAUDE.md, .llmdocs/api.md
CLAUDE.md sections added, updated, or removed: Key Concepts 已更新
Removed because the code contradicts it:
- CLAUDE.md: 从目的行中删除了 "or characters"，并删除了 --chars 关键概念
- .llmdocs/api.md: 删除了 count_chars 行
Stamped:
- stamped CLAUDE.md (marker)
- stamped .llmdocs/api.md (marker)

当更改不需要文档更新时，在摘要上方写入 "no doc changes needed"。