oo-component-documentation

OO コンポーネントのドキュメント

現在の実装を分析して、オブジェクト指向コンポーネントのドキュメントを新規作成するか、既存のコンポーネントドキュメントファイルを更新します。

最初にモードを決定する

何かを書く前に、ワークフローを選択します。

1. ユーザーが既存のドキュメント Markdown ファイルを提供した場合、ドキュメントのパスを指定した場合、または既存のドキュメントの更新や改訂を明示的に依頼した場合は、更新モードを使用します。references/update-mode.md に従ってください。
2. ユーザーがソースファイルまたはフォルダーを提供した場合、コンポーネントのパスを指定した場合、またはコードからドキュメントを生成するよう依頼した場合は、作成モードを使用します。references/create-mode.md に従ってください。
3. コードと既存のドキュメントファイルの両方が提供された場合は、既存のドキュメントファイルを出力先とし、現在のソースコードを信頼できる情報源として使用します。
4. 依頼が曖昧な場合は、可能であればパスの種類からモードを推定します。既存の Markdown ドキュメントファイルなら更新モード、ソースやコンポーネントのパスなら作成モードです。

ドキュメントの基準

• DOC-001：C4 モデルのドキュメントレベル（コンテキスト、コンテナー、コンポーネント、コード）に従います。
• DOC-002：Arc42 ソフトウェアアーキテクチャドキュメントテンプレートに準拠します。
• DOC-003：IEEE 1016 ソフトウェア設計記述標準に準拠します。
• DOC-004：アジャイルドキュメントの原則に従い、価値をもたらす必要十分なドキュメントを作成します。
• DOC-005：主な読者として開発者と保守担当者を想定します。

共通の分析ガイダンス

• ANA-001：主要なコンポーネントの境界と、入力がフォルダー、ファイル、既存のドキュメントのいずれに該当するかを判断します。
• ANA-002：ソースコードファイルを調べ、クラス構造、継承、コンポジション、インターフェースを確認します。
• ANA-003：設計パターン、アーキテクチャ上の決定、統合ポイントを特定します。
• ANA-004：パブリック API、インターフェース、依存関係、使用パターンを記述または更新します。
• ANA-005：メソッドのパラメーター、戻り値、非同期動作、例外、ライフサイクルに関する考慮事項を記録します。
• ANA-006：パフォーマンス、セキュリティ、信頼性、保守性、拡張性の特性を評価します。
• ANA-007：データフロー、連携パターン、周辺コンポーネントとの関係を推定します。
• ANA-008：ドキュメントの根拠を実装に置き、コードで裏付けられない動作を作り上げないようにします。

共通の出力要件

• assets/documentation-template.md を、標準的なセクション一覧と基本構成として使用します。
• 明確な見出し階層を設け、必要に応じて表、例を示すコードブロック、アーキテクチャ上の関係を視覚化する Mermaid 図を使用し、Markdown 形式で出力します。
• 例やインターフェースの説明は、汎用的なプレースホルダーではなく、現在の実装に合わせます。
• コード、プロジェクト構造、設定、または明示された仮定によって裏付けられる情報のみを含めます。
• ソースの調査範囲が不完全な場合は、推測せず、その制約を明記します。

言語別の最適化

• LNG-001：C#/.NET - async/await、依存性注入、構成、破棄処理、オプションパターン
• LNG-002：Java - Spring フレームワーク、アノテーション、例外処理、パッケージ化、依存性注入
• LNG-003：TypeScript/JavaScript - モジュール、非同期パターン、型、npm 依存関係、ランタイム境界
• LNG-004：Python - パッケージ、仮想環境、型ヒント、テスト、依存関係管理

エラー処理

• ERR-001：パスが存在しない場合は、想定されていたパスと、このスキルにソースパスと既存のドキュメントファイルのどちらが必要なのかを説明します
• ERR-002：関連するソースファイルが見つからない場合は、その不足を記録し、次に確認すべきと思われる場所を提案します
• ERR-003：リクエストからドキュメントの対象を推測できない場合は、曖昧な点を説明し、推測できないときに限り、不足しているパスを尋ねます
• ERR-004：コードで標準的でないアーキテクチャパターンが使われている場合は、一般的なパターンに無理に当てはめず、独自のアプローチを記録します
• ERR-005：ソースへのアクセスが不完全な場合は、入手可能な情報に基づいて作業を続け、根拠のないセクションを明確に示します

ワークフロー

1. タスクが新規作成モードか更新モードかを判断します。
2. コンポーネントの公開範囲と内部構造を理解するために、実装と関連ファイルを確認します。
3. 共通のドキュメントのひな形として、assets/documentation-template.md を使用します。
4. references/create-mode.md または references/update-mode.md に記載された、モード固有のルールを適用します。
5. 図、例、インターフェース、依存関係、品質特性が現在の実装を反映するように、ドキュメントを作成または改訂します。

完了基準

• ドキュメントに、コンポーネントの目的、アーキテクチャ、インターフェース、実装の詳細、使用パターン、品質特性、参考資料が明確に記載されています。
• 選択したモードに対して、フロントマターフィールドが正確です。
• 例と図が実装と一致しています。
• 不明点、不足、前提が明示されています。