Sphinx ドキュメント更新スキル

このスキルは、コードベースの変更に応じてSphinxドキュメントを自動的に更新・同期します。

起動条件

以下の状況で自動的に起動します：

1. API/インターフェース変更: 公開クラス、関数、メソッドのシグネチャが変更された
2. 新機能追加: 新しいクラス、モジュール、重要な機能が追加された
3. アーキテクチャ変更: システム設計や構造に影響する変更があった
4. 明示的な依頼: ユーザーがドキュメント更新を明示的に依頼した
5. ドキュメントの不整合: コードとドキュメントの内容が乖離している

動作プロセス

1. 変更内容の分析

まず、以下の情報を収集します：

• 変更されたファイルとその内容
• 新規追加されたクラス、関数、モジュール
• 変更されたAPIシグネチャ
• docstringの内容

2. 影響を受けるドキュメントの特定

プロジェクトのドキュメント構成を分析し、更新が必要なファイルを特定：

• docs/index.md: クイックスタート、概要
• docs/architecture.md: アーキテクチャ設計
• docs/how-it-works.md: 動作原理
• docs/custom-tools-explained.md: カスタムツールの説明
• 新規ページの必要性判断

3. ドキュメント更新案の作成

ドキュメント作成ガイドラインは .claude/docs.md を参照してください。

重要なポイント：

• MyST構文を使用
• 内部表記を避ける（Phase/Milestone/Article表記等）
• 保証表現を避ける（「完全サポート」等）
• 感嘆符を使用しない
• プロフェッショナルで簡潔な技術文書として記述

4. ユーザーへの確認

更新内容を提示し、以下を確認：

• 変更の妥当性
• 追加すべき情報の有無
• ドキュメント構成の適切性

5. 更新の実行

承認後、以下を実行：

• ドキュメントファイルの更新
• 必要に応じて新規ページの作成
• docs/index.mdのtoctreeへの追加（新規ページの場合）

6. ビルド検証

最後にSphinxビルドでエラーがないことを確認：

uv run sphinx-build -M html docs docs/_build

使用例

例1: 新しいクラスを追加

変更内容:

class ClaudeCodeCLIStreamingModel:
    """ストリーミング対応のClaudeモデル"""

    def __init__(self, model_name: str):
        ...

    async def stream(self, messages: list[dict]) -> AsyncIterator[str]:
        ...

スキルの動作:

1. docs/architecture.mdにストリーミングモデルのセクションを追加
2. docs/how-it-works.mdにストリーミングの仕組みを説明
3. docs/index.mdのクイックスタートにストリーミングの使用例を追加

例2: APIシグネチャの変更

変更内容:

# 変更前
def __init__(self, model_name: str):
    ...

# 変更後
def __init__(self, model_name: str, timeout: int = 30, max_retries: int = 3):
    ...

スキルの動作:

1. docs/index.mdのクイックスタート例を更新
2. 新しいパラメータの説明を追加
3. 既存コード例に新パラメータの使い方を追記（必要に応じて）

例3: アーキテクチャ変更

変更内容:

• Tool実行の仕組みをリファクタリング
• 新しいToolExecutorクラスを導入

スキルの動作:

1. docs/architecture.mdのアーキテクチャ図を更新
2. 新しいコンポーネントの説明を追加
3. docs/custom-tools-explained.mdのTool実行フローを更新

ガイドライン参照

重要: 詳細なドキュメント作成ガイドラインは .claude/docs.md を参照してください。

このファイルには以下の情報が含まれています：

• MyST構文の詳細
• トーンとスタイルのガイドライン
• 避けるべき表現（Phase/Milestone/Article表記、保証表現、感嘆符）
• コードブロックの注意点
• ビルド検証方法

注意事項

• 自動実行の制限: このスキルは更新を提案しますが、最終的な実行前に必ずユーザーの確認を求めます
• ビルドエラー: Sphinxビルドでエラーが発生した場合は、原因を報告し修正案を提示します
• 既存内容の保持: 既存のドキュメント内容を尊重し、必要最小限の変更を提案します
• 日本語対応: このプロジェクトのドキュメントは日本語で記述します