jimweller/documenter-plugin

ドキュメント作成

現在の会話コンテキストとフォルダの内容に基づいてマークダウンコンテンツを作成します。

READMEは人間のユーザー向けの現在の状態仕様であり、変更履歴、決定ログ、履歴記録ではありません。履歴情報や過去に行った選択を記録せず、READMEを作成する時点での仕様のみを記述します。

スコープ

プロジェクト内のすべてのREADME.mdファイルを検索し、それぞれを更新します。 フォルダの内容はREADMEと同じレベルおよび下位（兄弟とサブフォルダ）であり、上位（親）は含みません。 サブフォルダの階層、スコープ、境界コンテキストに注意してください。異なる階層のドキュメント間で概念を漏らさないでください。各READMEは自身のディレクトリレベルとその下位をカバーし、親の関心事は扱いません。

ユーザーから特定のガイダンスや重点領域が提供された場合は、そのコンテキストをドキュメントで強調する内容を決定する際に適用します。

コンテキスト収集

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

計画から始めます。計画はすべてのREADMEを検索し、ルートREADMEがない場合は作成し、各READMEのベースラインを解決し、そのベースライン以降の変更をリストアップし、各READMEに対して何をすべきかを示します。ユーザーのガイダンスがフォーカスするディレクトリを指定している場合は、readmeの後にそれらを渡します。それ以外の場合は何も渡しません。

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

計画はアクションごとに1つのブロックを出力します。

• ## update はベースライン、スコープ、READMEを示し、その後にそのベースライン以降のコミット、差分統計、ステータスが続きます。READMEを最新の状態に更新します。変更の影響を受けないREADMEはその内容を維持します。
• ## new は現在のコードから作成するREADMEをリストアップします。履歴は必要ありません。
• ## unchanged および ## outside the focus はそのまま変更しないREADMEをリストアップします。

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

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

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

次に、更新または作成する各READMEについて、そのディレクトリにスコープして以下の手順を実行します。

1. 現在のREADMEを読み取る（存在する場合）

2. そのディレクトリレベルおよび下位のコードベースを調査する

3. 会話履歴を確認し、関連する決定、変更、学んだ教訓を特定する

4. 変更と会話コンテキストを使用して、どのセクションを更新する必要があるかを特定する。コードをドキュメントに対して検証し、ドキュメントをコードに対して検証する。コードが関数、フラグ、モジュールを削除した場合、すべてのREADMEでその名前をgrep検索し、各ヒットと各READMEの概要を再読み取りして、同じものを平易な言葉で説明しているか確認する。

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

作成または編集するテキストにマーカー行を含めないでください。finishが書き込み後に追加します。既にマーカー行で終わっているREADMEを編集する場合は、その行はそのままにします。

READMEの更新を正当化する変更がない場合は、その旨を伝えて次に進みます。finishは依然として適用されます。

README.md アウトライン

README.mdのセクションの順序と内容。すべてのセクションは対象プロジェクトから埋めます。プロジェクトに関連するものがないセクションは省略します。

• # タイトル と最大5文の概要
• オプションの画像または動画
• ## アーキテクチャ - コンポーネントを箇条書きで、各コンポーネントの目的
• ## 前提条件 - アカウント、キー、認証情報、ツール、ランタイム、CLI。それぞれ必要とされる理由を添えて
• ## プロジェクト構造 - ファイルは含めずフォルダのみ。各フォルダの目的を一行で
• ## インストール - インストールするコマンド
• ## 使用法 - 実行するコマンド
• ## テスト - プロジェクトにテストがない場合は省略

500行未満を目標にします。長いREADMEは、詳細をそのコードの隣にあるネストされたREADMEに移動して分割します。

形状

# タイトル

簡潔な概要。最大5文。

<!-- オプションの画像または動画のハイライト -->
<img src="demo.png" alt="デモ" width="800"/>

## アーキテクチャ

高レベルコンポーネントと目的

- コンポーネント - 目的
- コンポーネント - 目的

## 前提条件

- 前提条件 - 説明と理由（アカウント、キー、認証情報、ツール、ランタイム、CLI）

## プロジェクト構造

フォルダ構造を表示します。ファイルは含めません。

```text
project/
├── src/
│   ├── component-a/     # 目的 - src/component-a/README.md を参照
│   └── component-b/     # 目的 - src/component-b/README.md を参照
├── scripts/             # 目的
└── tests/               # 目的
```

## インストール

```bash
# プロジェクトのインストール方法
<インストールコマンド>
```

## 使用法

```bash
# プロジェクトの実行方法
<実行コマンド>
```

## テスト

```bash
# テストの実行方法
<テストコマンド>
```

完了

毎回finishを実行します。何も書き込まなかった実行も含みます。planは計画ファイルを残し、finishだけがそれを削除します。そのため、finishをスキップした実行は状態を残し、次の実行で問題が発生します。

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

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

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