fusion-package-scribe

Package Scribe

実験的な機能に関する注意

このスキルは実験段階であり、まだ安定していません。動作、構成、出力はバージョン間で変更される場合があります。

使用する場面

TypeScript パッケージ全体にわたって、ドキュメントを体系的に追加または改善する必要がある場合に使用します。モノレポ全体を対象とする場合も、単一のパッケージを対象とする場合も含まれます。

一般的なきっかけ：

• 「すべてのパッケージのドキュメントを作成して」
• 「packages/utils/observable のドキュメントを改善して」
• 「このパッケージのすべての公開エクスポートに TSDoc を追加して」
• 「このパッケージの README を書き直して」
• 「モノレポ全体のドキュメントを見直して」
• 「このパッケージの TSDoc の品質を確認して」

暗黙的なきっかけ：

• パッケージに、TSDoc が未記述または仮の内容になっている公開エクスポートがある
• パッケージの README が古い、一貫性がない、または標準的なセクションが不足している
• 複数のパッケージを対象とするドキュメントの見直しが計画されている

使用しない場面

• ランタイムコードの変更（ドキュメントコメントと README ファイルのみが対象です）
• API リファレンスサイトや TypeDoc の出力の生成
• TypeScript 以外の言語（初期段階では TS/TSX のみが対象です）
• PR の自動マージやレビューワークフローの回避
• セキュリティ脆弱性のスキャンやパフォーマンスのプロファイリング
• 既存の CI ベースのドキュメント生成パイプラインの置き換え

必須入力

必須入力が不足している場合や曖昧な場合は、作業を始める前に確認してください。

• 対象範囲：モノレポのルートパス、または特定のパッケージパス
• モード：single（1 つのパッケージ）または sweep（複数のパッケージ）

条件付き入力

• パッケージフィルター：一部のパッケージを処理する場合の glob またはリスト
• README テンプレートのパス：組み込みのデフォルトを使用しない場合の、リポジトリ固有のテンプレート（例：.github/instructions/ 内）
• 追跡課題：ライフサイクルの更新（割り当て、ステータス変更、クローズ）に使用する課題番号
• コミット形式：リポジトリ固有の Conventional Commit 形式（デフォルトは docs(<package>): ）
• バッチサイズ：sweep モードで 1 バッチあたりに処理するパッケージ数（デフォルトは 5）

デフォルト

• モード：single（パッケージパスが 1 つだけ指定された場合）
• コミットプレフィックス：docs(<package-name>):
• バッチサイズ：sweep モードでは 1 バッチあたり 5 パッケージ
• README の構成：references/readme-template.md にある組み込みテンプレート
• レビュー評議会：有効（各パッケージの処理後に実行）

優先順位と標準の確認

このスキルは、対象リポジトリ独自の標準を確認し、それに従います。

1. リポジトリの指示 — .github/instructions/ 内の該当ファイル、CONTRIBUTING.md、contribute/
2. ツール設定 — tsconfig.json、biome.json、.editorconfig
3. 連携スキル — TSDoc のルール、命名規則、意図の品質に関する fusion-code-conventions（インストールされている場合）
4. 組み込みのデフォルト — references/tsdoc-checklist.md と references/readme-template.md

リポジトリレベルの標準が常に優先されます。リポジトリに標準がない場合は、組み込みのデフォルトを適用します。

エージェントモード

エージェント	役割	有効になる場面
agents/orchestrator.agent.md	バッチコーディネーター	sweep モード — バッチを計画し、トークン予算を管理し、進捗を追跡します
agents/documenter.agent.md	パッケージごとのライター	すべてのパッケージ — API サーフェスを調査し、TSDoc を生成し、README を書き直します
agents/reviewer.agent.md	レビュー評議会	各パッケージの処理後 — 意図、理解しやすさ、検索適性を検証します

単一エージェントのランタイムでは、3 つの役割すべてが順番にインラインで実行されます。

手順

ステップ 1 — リポジトリの標準を確認する

ドキュメントを生成する前に：

1. リポジトリレベルのドキュメントに関する指示を検索します：
   • .github/instructions/ 内の該当ファイル
   • CONTRIBUTING.md、contribute/
2. モジュール構成、パスエイリアス、strict モードの設定を把握するため、tsconfig.json を読みます
3. スタイルの要件を確認するため、biome.json または同等のリンター設定を読みます
4. fusion-code-conventions が利用できるか確認します。利用できる場合は、references/typescript.conventions.md にある TSDoc ルールに従います
5. リポジトリレベルの標準がない場合は、品質の基準として references/tsdoc-checklist.md を使用します

Step 2 — パッケージを検出する

1. 単一モードの場合：指定されたパッケージパスが存在し、TypeScript のソースファイルがあることを検証します
2. 一括処理モードの場合：
   • ルートの package.json またはワークスペース設定（pnpm-workspace.yaml、lerna.json、turbo.json）を読み込み、すべてのパッケージを検出します
   • 指定された glob／リストで絞り込みます
   • バッチ計画のために、推定サイズ（ファイル数）順にパッケージを並べ替えます
   • 検出結果の概要を .tmp/scribe-discovery-<context>.md に書き込みます

Step 3 — 実行計画を立てる（一括処理モードのみ）

agents/orchestrator.agent.md を有効にする（またはインラインで実行する）：

1. パッケージを設定されたバッチサイズごとにグループ化します
2. バッチの順序を決めます：早い段階での処理量を最大化するため、ソースファイル数の少ないパッケージから並べます
3. パッケージごとのトークン予算を推定します：読み込みにソースファイルあたり約 100 トークン、TSDoc 生成にエクスポートあたり約 200 トークン
4. 1 つのパッケージが推定コンテキストウィンドウの 60% を超える場合は、特別な対応が必要であることを示します（最初にバレルエクスポートを処理し、内部モジュールは後回しにします）
5. 実行計画を .tmp/scribe-plan-<context>.md に書き込みます

Step 4 — 各パッケージを処理する

各パッケージについて agents/documenter.agent.md を有効にする（またはインラインで実行する）：

4a — 公開 API の範囲を調査する

1. バレルエクスポートファイル（index.ts、index.tsx、または package.json の main フィールド）を見つけます
2. すべての再エクスポートをたどり、公開 API の全範囲を特定します
3. エクスポートを分類します：関数、クラス、型／インターフェース、定数、フック、列挙型
4. 優先順位を設定します：最初にバレルエクスポート、次に直接の公開エクスポート、その後に内部で使用されているがエクスポートされている項目

4b — TSDoc を生成または改善する

各公開エクスポートについて：

1. 既存の実装を読み、意図、パラメーター、戻り値、エラー経路、副作用を理解します
2. 既存の TSDoc を確認します。すでにある場合は置き換えずに改善します
3. TSDoc チェックリスト（リポジトリの規約、または references/tsdoc-checklist.md）を適用します：
   • 要約行：単に「何をするか」だけでなく、「なぜ」や「どの問題を解決するか」を説明します
   • 意味のある説明を添えて、すべてのパラメーターに @param を付けます
   • 戻り値が void ではないすべての関数に @returns を付けます
   • すべてのジェネリック型パラメーターに @template を付けます
   • 意味のあるエラー経路に @throws を付けます
   • ユーザー向けの API および自明でない公開 API に @example を付けます
   • 該当する場合は、置き換え方法を示す @deprecated を付けます
4. 「名前をそのまま説明に繰り返す」パターン（例：/** Gets the value. */ getValue()）を特定し、書き直します
5. 実行時コードは変更せず、ドキュメントコメントのみを変更します

4c — README を書き直す、または改善する

1. 既存の README があれば読み、有用な内容を維持します
2. リポジトリの指示または references/readme-template.md の README 構成を適用します：
   • パッケージ名と説明
   • 機能／主要なエクスポート
   • インストール
   • コード例を使った使用方法
   • API リファレンス（主要なエクスポートの概要とリンク、またはインラインドキュメント）
   • 設定（該当する場合）
3. 初めてパッケージを見つけた開発者にとって有用な README にします
4. 検索性を高めるため、明確な見出し、キーワードを含む説明、具体例を使用します

Step 5 — レビュー会議

各パッケージの処理後に agents/reviewer.agent.md を有効にする（またはインラインで実行する）：

1. 意図の抽出 — TSDoc はコードが「何を」「なぜ」行うかを正確に説明していますか？関数名や型名を単に言い換えているだけのコメントに印を付けます。
2. コードの理解度 — 複雑なアルゴリズム、状態機械、副作用は説明されていますか？新しい開発者はドキュメントだけでコードを理解できますか？
3. ユーザー向けの品質 — README は初めてパッケージを見つけた人にとって有用ですか？動作する例はありますか？
4. 検索適性 — ドキュメントは RAG／セマンティック検索で適切にヒットしますか？見出しや要約に重要な用語が含まれていますか？

レビュー担当者は、各基準について合格／不合格を判定します。不合格の場合、該当するパッケージについて Step 4 に戻ります。

Step 6 — コミット

パッケージがレビュー会議を通過したら：

1. ドキュメントファイルのみをステージングします（TSDoc の変更では .ts／.tsx ファイル、README の変更では README.md）
2. リポジトリの規約に沿ったコミット形式を使います。デフォルトは次のとおりです：

   docs(<package-name>): improve TSDoc and README documentation
   

3. プッシュはしないでください。ユーザーまたは PR のワークフローに任せます

Step 7 — 報告

すべてのパッケージの処理が終わったら：

1. .tmp/scribe-report-<context>.md に概要を記載します：
   • 処理したパッケージとステータス（合格／不合格／スキップ）
   • ドキュメントを付けたエクスポートの合計数
   • 基準ごとのレビュー会議の合格率
   • 手動レビューの対象としてフラグを付けたパッケージ
   • 作成したコミット
2. トラッキング課題が指定されている場合は、概要を追記します

期待される出力

• 処理対象パッケージのすべてのパブリックエクスポートに付けた TSDoc コメント
• 処理対象パッケージごとに一貫性のある README
• ドキュメントの変更のみを含む、パッケージごとに 1 つのコミット
• .tmp/ 内の概要レポート
• トラッキング課題の更新（課題番号が指定されている場合）

安全性と制約

このスキルはリポジトリを変更できます。指示が競合する場合は、インラインのガイダンスよりもリポジトリ内のワークフロー指示を優先してください。

• ドキュメントコメントと README ファイルのみを変更してください。実行時コードには絶対に手を加えないでください
• コミットをプッシュしないでください。プッシュするかどうかはユーザーに任せてください
• PR を自動マージしたり、レビューのワークフローを回避したりしないでください
• API の動作を捏造せず、コードで実際に確認できる内容のみを記載してください
• 既存の価値あるドキュメントを削除または置き換える場合は、その内容を保持してください
• トラッキング課題が参照されている場合、明示的な確認を得てから更新してください
• .gitignore を尊重し、.tmp/ 内の一時ファイルをコミットしないでください
• レビュー会議でパッケージが 2 回不合格になった場合、無期限に繰り返さず、手動レビューの対象としてフラグを付けてください