jimweller/documenter-plugin

プロジェクトドキュメントの更新

2つの責務:

1. CLAUDE.md — 簡潔なプロジェクト概要（常に読み込まれる）
2. .llmdocs/ — 詳細な概念ごとのドキュメント（オンデマンドで読み込まれる）。このディレクトリ内の全ファイルは永続的な設計ドキュメントです。

---

1. CLAUDE.md — 地図

範囲

プロジェクト内のすべてのCLAUDE.mdおよび.llmdocs/ディレクトリを見つけ、それぞれを更新します。 サブフォルダの階層、スコープ、境界コンテキストに注意してください。異なる階層のドキュメント間で概念を漏らさないでください。 各CLAUDE.mdと.llmdocs/は、自身のディレクトリ階層とそれ以下のみをカバーし、親の関心事には決して触れません。

ユーザーから特定のガイダンスやフォーカス領域が提供された場合は、そのコンテキストを適用して、どのドキュメントを更新し、何を強調するかを決定します。

コンテキストの収集

git を直接実行しないでください。このプラグインに付属するベースラインスクリプトが、このスキルに必要なgit関連のすべてをカバーします。各コマンドはリポジトリルートから実行し、スクリプトのフルパスを毎回記述してください。シェル変数はコマンド間で永続化されないためです。

プランから始めます。プランはすべてのCLAUDE.mdとその.llmdocs/（まだ存在しない必須ファイルを含む）を見つけ、各ドキュメントのベースラインを解決し、それ以降に変更された内容をリストアップし、各ドキュメントをどう処理すべきかを示します。ユーザーのガイダンスがフォーカスするディレクトリを指定している場合は、llmdocs の後にそれらを渡します。それ以外の場合は何も渡しません。

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

プランはアクションごとに1ブロックを出力します。

• ## update は、ベースライン、スコープ、およびそれを共有するドキュメントを指定し、その後にそのベースライン以降のコミット、差分統計、ステータスが続きます。これらのドキュメントを最新の状態に更新します。変更の影響を受けないドキュメントはその内容を維持します。
• ## new は、現在のコードから作成するドキュメントをリストします。履歴は不要です。
• ## unchanged および ## outside the focus は、そのまま変更せずに残すドキュメントをリストします。

head none はリポジトリにコミットがないことを意味します。すべてのドキュメントが新規です。

updateブロックの場合、その統計内のファイル数をカウントします。20を超える場合は、完全な差分をスキップし、変更されたファイルを直接読み取ります。20以下の場合は、差分を読み取ります。追跡されていないファイル（?? とマーク）は差分に現れないため、どちらの場合も直接読み取ります。スコープはブロックのスコープでも単一ファイルでも構いません。これはgitのパススペックであるためです。

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し、各ヒットと各ドキュメントの目的行を再読み取りして、同じものの平易な説明がないか確認する。1つのドキュメントから名前を削除するだけでは不十分

grep -rn '<削除された名前>' <dir>/CLAUDE.md <dir>/.llmdocs

• 作成または編集するテキストにマーカー行を決して含めない。finish は書き込み後にそれを追加します。すでにマーカー行で終わっているドキュメントを編集する場合は、その行はそのままにしておく
• 常に読み込むべきドキュメントがある場合は @.llmdocs/filename.md インポートを使用する

---

2. .llmdocs/ — 領域

プロセス

必須の7ファイルを超える概念ファイルは自由に追加できます。プランはそれを決して指定しません。finish は、実行中に作成されたこの階層の他のすべてのドキュメントと同様に、それをスタンプします。

1. 評価: プランのupdateブロックを使用して、影響を受けるドキュメントを特定する
2. 特定: 影響を受ける既存のドキュメント、または新しいドキュメントが必要かどうかを判断する
3. CLAUDE.mdの更新: ## LLM Docs セクションに新しいドキュメントファイルがリストされていることを確認する

ドキュメントの更新を正当化するような変更がない場合は、その旨を伝えて次に進みます。

場所

CLAUDE.mdの ## LLM Docs 見出し（またはそれ以前のCLAUDE.mdの ## Docs 見出し）の下にある最初のインポートが指定するパスを使用します。それ以外の場合は、対象ディレクトリ階層の .llmdocs/ をデフォルトとします。CLAUDE.mdと.llmdocs/はプロジェクトの任意のディレクトリ階層に存在できます。

構造

フラット構造、概念ごとに1ファイル。最初の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

finish は、プランが new または update とマークしたすべてのドキュメント、およびプラン以降に作成されたドキュメント（例: testing.md）を、プランがチェックしたHEADでスタンプします。スタンプはドキュメント末尾のマーカー行であり、そのコミットを指定するHTMLコメントです。finish は、変更されていないドキュメントとフォーカス外のドキュメントはそのままにし、リポジトリにコミットがない場合は何もスタンプしません。終了コード4は、計画されたドキュメントが見つからないことを意味します。それを作成し、finish を再実行してください。

• stamp を直接呼び出したり、マーカー行を手動で作成または編集したりしないでください。finish がそれを書き込みます。
• マーカーはメタデータです。履歴を記録しないというルールはこれには適用されません。

---

4. サマリー出力

実行後、このサマリーを出力します。実行から各行を埋め、リストが空の場合は "none" と記述します。Stamped の下には、finish 自身の行をそのまま、ドキュメントごとに1行コピーします。そこにshaを決して書き込まず、finish が出力しなかった単語を追加しないでください。

機能を削除するために言い換えられた文は削除です。削除された表現を Removed の下に記述します。同じ行がまだ存在している場合でも同様です。

記入例（コードが文字カウントを削除した実行から）:

Files created: none
Files modified: CLAUDE.md, .llmdocs/api.md
CLAUDE.md sections added, updated, or removed: Key Concepts updated
Removed because the code contradicts it:
- CLAUDE.md: "or characters" from the purpose line, and the --chars key concept
- .llmdocs/api.md: the count_chars row
Stamped:
- stamped CLAUDE.md (marker)
- stamped .llmdocs/api.md (marker)

変更がドキュメントの更新を正当化しない場合は、サマリーの上に "no doc changes needed" と記述します。