OO コンポーネントドキュメンテーション

共有テンプレートとモード固有のガイダンスを使用して、オブジェクト指向コンポーネントの新規ドキュメンテーションを作成するか、既存のコンポーネントドキュメンテーションファイルを更新します。

まずモードを決定する

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

1. ユーザーが既存のドキュメンテーション Markdown ファイルを提供している場合、docs パスを指定している場合、または既存ドキュメンテーションの更新や修正を明示的に依頼している場合は、update モードを使用します。references/update-mode.md に従ってください。
2. ユーザーがソースファイルまたはフォルダを提供している場合、コンポーネントパスを指定している場合、またはコードからドキュメンテーションを生成するよう依頼している場合は、create モードを使用します。references/create-mode.md に従ってください。
3. コードと既存ドキュメンテーションファイルの両方が提供されている場合、既存ドキュメンテーションファイルを出力ターゲットとして扱い、現在のソースコードを信頼できる情報源として使用します。
4. リクエストが曖昧な場合、可能な限りパスタイプからモードを推測します: 既存の Markdown ドキュメンテーションファイルは update モード、ソース/コンポーネントパスは create モードを意味します。

ドキュメンテーション標準

• DOC-001: C4 モデルドキュメンテーションレベル (Context、Containers、Components、Code) に従う
• DOC-002: Arc42 ソフトウェアアーキテクチャドキュメンテーションテンプレートに整合させる
• DOC-003: IEEE 1016 Software Design Description 標準に準拠する
• 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. タスクが create モードか update モードかを判断します。
2. コンポーネント実装とパブリック表面領域および内部構造を理解するために必要な関連ファイルを検査します。
3. assets/documentation-template.md を共有ドキュメンテーションスカフォルドとして使用します。
4. references/create-mode.md または references/update-mode.md のモード固有のルールを適用します。
5. ダイアグラム、例、インターフェース、依存関係、品質属性が現在の実装を反映するようにドキュメンテーションを作成または修正します。

完了基準

• ドキュメンテーションはコンポーネントの目的、アーキテクチャ、インターフェース、実装の詳細、使用パターン、品質属性、参照を明確に識別します。
• フロントマターフィールドは選択されたモードに対して正確です。
• 例とダイアグラムは実装と一致します。
• 未知のもの、ギャップ、仮定は明示的に指摘されます。