llmdocs

STARTER_CHARACTER = 📐

更新项目文档

两项职责：

1. CLAUDE.md — 简明的项目概览（始终加载）
2. .llmdocs/ — 按概念组织的详细文档（按需加载）。此处的所有文件都是持久化设计文档。

---

1. CLAUDE.md — 地图

范围

查找项目中的所有 CLAUDE.md 和 .llmdocs/ 目录，并逐一更新。 注意子文件夹层级、范围和限界上下文。不要将不同层级文档中的概念混在一起。每个 CLAUDE.md 和 .llmdocs/ 都涵盖其所在目录层级及以下内容，不涉及父级关注点。

如果用户提供了具体指导或关注领域，在确定要更新哪些文档以及要强调什么内容时，请结合这些上下文。

收集上下文

对于找到的每组 CLAUDE.md/.llmdocs/，在其目录范围内：

1. 阅读现有的 CLAUDE.md（如果存在）
2. 计算文档上次更新后有哪些变化。包括已提交、已暂存、未暂存和未跟踪的工作：

TARGET_DIR=<directory containing CLAUDE.md and .llmdocs/>

BASELINE=$(git log -1 --format=%H -- "$TARGET_DIR/CLAUDE.md" "$TARGET_DIR/.llmdocs/" 2>/dev/null)
[ -z "$BASELINE" ] && BASELINE=$(git rev-list --max-parents=0 HEAD 2>/dev/null)
HEAD_SHA=$(git rev-parse --verify -q HEAD)

if [ -n "$BASELINE" ] && [ "$BASELINE" != "$HEAD_SHA" ]; then
  git log --oneline "$BASELINE"..HEAD -- "$TARGET_DIR"
  git diff "$BASELINE" --stat -- "$TARGET_DIR"
  git diff "$BASELINE" -- "$TARGET_DIR"
elif [ -n "$HEAD_SHA" ]; then
  git show --stat HEAD -- "$TARGET_DIR"
  git diff HEAD --stat -- "$TARGET_DIR"
  git diff HEAD -- "$TARGET_DIR"
fi

git status --short -- "$TARGET_DIR"

--stat 必须位于 -- 之前。若放在其后，git 会将其视为路径规格，并静默输出完整差异，而不是摘要。

先阅读 --stat 摘要，再据此决定是否运行完整差异。没有自身提交的文档会回溯到根提交，因此完整差异可能涵盖该目录的全部历史；在中型仓库中，这可能有数千行。摘要很长时，跳过完整差异，直接阅读变更文件。

差异中没有 ..HEAD，因此它涵盖基准状态到工作树的变化，并包含已暂存和未暂存的编辑。分支处理了四种状态：文档自身有提交、文档没有提交、仓库只有根提交，以及仓库完全没有提交。如果没有这些分支，空基准或与 HEAD 相同的基准会导致每条命令都没有输出，技能便会错误地得出没有内容需要记录的结论。

git status --short 会在一个视图中列出已暂存、未暂存和未跟踪的路径。未跟踪文件会显示为 ??，其内容不会出现在任何差异中，因此要直接阅读这些文件。整个过程中都会排除与 .gitignore 匹配的文件。

3. 探索该目录层级及以下的代码库
4. 查看对话历史中相关的决定、变更或经验教训
5. 使用差异和对话上下文来确定有哪些变化。llmdocs 是对当前状态的规范说明，不是变更日志、决策日志或历史记录。绝不要记录历史信息或曾做出的选择，只记录编写 llmdocs 时的现行规范。

编写/更新 CLAUDE.md

目标：少于 500 行。每一行都必须有存在的价值。

# <Name>

<1-2 line purpose of this directory/component>

## Stack

<bullet list: language, frameworks, key deps relevant to this level>

## Architecture

<key dirs and what they contain at this level>

## Commands

<build, test, lint, deploy — commands only>

## Conventions

<style, naming, patterns — only what prevents mistakes>

## Key Concepts

<domain terms, business logic Claude must know at this level>

## Docs

Detailed docs in `.llmdocs/`:

- @.llmdocs/architecture.md — <1-line description>
- @.llmdocs/data-model.md — <1-line description>

CLAUDE.md 规则

• 不要写冗长的解释——Claude 会自行推断
• 不要重复 .llmdocs/ 的内容——只需用简短描述引用
• ## Docs 部分必须列出所有 .llmdocs/ 文件，并为每个文件提供一行描述
• 保留现有的自定义指令（git 工作流、环境变量等）
• 删除任何现有内容前先征求同意
• 如果某份文档应始终加载，请使用 @.llmdocs/filename.md 导入

---

2. .llmdocs/ — 具体内容

流程

1. 评估：使用“收集上下文”中的差异，确定哪些文档受到影响
2. 识别：确定哪些现有文档受到影响，或是否需要新建文档
3. 提议：告知用户计划更新/创建哪些文档以及变更内容
4. 确认：写入前取得用户批准
5. 更新 CLAUDE.md：确保 ## Docs 部分列出所有新增文档文件

如果没有值得更新文档的变化，说明这一点后继续。

位置

使用现有 CLAUDE.md 中指定的路径；若未指定，则默认使用目标目录层级下的 .llmdocs/。项目中的任意目录层级都可以存在 CLAUDE.md 和 .llmdocs/。

结构

采用扁平结构，每个概念一个文件。前 6 个文件为必需文件，必须始终存在。根据需要创建其他概念文件。

.llmdocs/
  architecture.md    # Components, interactions, data flow (required)
  api.md             # Endpoints, request/response, authentication, authorization (required)
  data-model.md      # Schema, models, relationships (required)
  deployment.md      # Deploy process, environments (required)
  ops.md             # Maintenance, operations, runbooks (required)
  security.md        # Trust boundaries, secrets handling, authn/authz, threat model (required)
  <concept>.md       # Domain-specific as needed

文档文件格式

# <Concept>

<1-line purpose>

## <Section>

<content: headers, tables, code blocks — no prose paragraphs>

.llmdocs/ 规则

• 每个文件最多 500 行；超过时拆分文件
• 在适当位置注明文件路径和行号（src/auth/login.ts:42）
• 逐步更新现有文档，不要从头重写
• 如果文档准确且未受近期变更影响，则不要改动
• 准确性优先于覆盖范围：只记录可通过代码验证的内容

---

3. 摘要输出

运行后，输出：

• 已创建／修改的文件
• CLAUDE.md 的变更（新增／更新／删除的章节）
• 已更新／创建的文档（或“无需修改文档”）