majiayu000 Sphinx ドキュメント更新スキル
このスキルは、コードベースの変更に応じてSphinxドキュメントを自動的に更新・同期します。
起動条件
以下の状況で自動的に起動します：
- API/インターフェース変更: 公開クラス、関数、メソッドのシグネチャが変更された
- 新機能追加: 新しいクラス、モジュール、重要な機能が追加された
- アーキテクチャ変更: システム設計や構造に影響する変更があった
- 明示的な依頼: ユーザーがドキュメント更新を明示的に依頼した
- ドキュメントの不整合: コードとドキュメントの内容が乖離している
動作プロセス
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]:
...
スキルの動作:
docs/architecture.mdにストリーミングモデルのセクションを追加docs/how-it-works.mdにストリーミングの仕組みを説明docs/index.mdのクイックスタートにストリーミングの使用例を追加
例2: APIシグネチャの変更
変更内容:
# 変更前
def __init__(self, model_name: str):
...
# 変更後
def __init__(self, model_name: str, timeout: int = 30, max_retries: int = 3):
...
スキルの動作:
docs/index.mdのクイックスタート例を更新- 新しいパラメータの説明を追加
- 既存コード例に新パラメータの使い方を追記（必要に応じて）
例3: アーキテクチャ変更
変更内容:
- Tool実行の仕組みをリファクタリング
- 新しい
ToolExecutorクラスを導入
スキルの動作:
docs/architecture.mdのアーキテクチャ図を更新- 新しいコンポーネントの説明を追加
docs/custom-tools-explained.mdのTool実行フローを更新
ガイドライン参照
重要: 詳細なドキュメント作成ガイドラインは .claude/docs.md を参照してください。
このファイルには以下の情報が含まれています：
- MyST構文の詳細
- トーンとスタイルのガイドライン
- 避けるべき表現（Phase/Milestone/Article表記、保証表現、感嘆符）
- コードブロックの注意点
- ビルド検証方法
注意事項
- 自動実行の制限: このスキルは更新を提案しますが、最終的な実行前に必ずユーザーの確認を求めます
- ビルドエラー: Sphinxビルドでエラーが発生した場合は、原因を報告し修正案を提示します
- 既存内容の保持: 既存のドキュメント内容を尊重し、必要最小限の変更を提案します
- 日本語対応: このプロジェクトのドキュメントは日本語で記述します