ソフトウェア設計説明書

IEEE 1016にインスパイアされた構造を使用しながら、プロジェクトコンテキストに対して実用的なSDDを作成またはレビューします。

リソース

• 完全性のゲートと必須コンテンツ範囲についてはreferences/sdd-completeness-checklist.mdを使用してください。
• references/document-set/以下のテンプレートを標準的なSDDドキュメントセット構造として使用してください。
• ビューポイントを選択し、具体的なビューにマッピングするにはreferences/viewpoint-mapping.mdを使用してください。
• 著作権/標準のガードレールについてはreferences/copyright-safety.mdを使用してください。
• 品質属性シナリオについてはreferences/quality-attribute-scenarios.mdを使用してください。
• scripts/check_sdd_structure.pyを使用して、標準的なSDDドキュメントセット全体で必須ファイル、見出し、リンク、およびコア形式化セクションを検証してください。
• scripts/check_doc_artifacts.pyを使用して、.agent-doc-skills/以下の日付付きギャップと乖離アーティファクト履歴を検証してください。
• scripts/count_text_size.pyを使用してファイルサイズをすばやく検査してください(chars、words、lines)。オプションでMarkdown見出し別の内訳(--by-heading)も利用できます。

必須のプリフライトシーケンス:

1. 利用可能なコンテキストをまず読み込みます(リクエストに関連するPRD/SDD/リポジトリドキュメント)。
2. 大規模なドキュメントセットの場合、オプションでサイズチェックを実行します: python3 scripts/count_text_size.py --glob "<sdd-root>/**/*.md" --by-heading。
3. そのコンテキストからモード、詳細プロファイル、および出力ルートを推奨します。
4. ドラフト作成前にユーザー確認を要求します。

ユーザーが明示的に/fastまたは/assumeを使用しない限り、プリフライト確認を受け取るまでドラフト作成を開始しないでください。

著作権および標準安全性(必須)

• IEEE 1016-2009を概念的な参照のみとして扱います。
• 生成されたすべての出力で元の表現を使用します。
• 著作権で保護された標準テキスト、表、図を複製したり、密接に言い換えたりしないでください。
• リクエストに応じて条項テキストを提供せず、セクション整合ガイダンスを提供し、ユーザーに規範的な表現について彼らのライセンスを受けた標準コピーを参照するよう求めてください。
• IEEE構造を参照する場合、セクション識別子のみを引用してください(例:Clause 4)。規範的なテキストは引用しないでください。
• 免責事項が必要な場合、1行の簡潔な免責事項のみを含めてください(例: IEEE 1016にインスパイアされた内部ガイダンス、非公式。)。

デフォルト

• モード: draft+review。
• 完全性の厳密さ: pragmatic。
• 詳細プロファイル: ieee-pragmatic。
• コードベース検査: リポジトリコンテキストが利用可能な場合は有効。
• 標準的な出力ルート: docs/sdd/
• アーティファクトルート: .agent-doc-skills/
• 標準的な出力ファイル:
  • docs/sdd/index.md
  • docs/sdd/01-introduction.md
  • docs/sdd/02-03-system-context-and-concerns.md
  • docs/sdd/04-architecture-overview.md
  • docs/sdd/05-viewpoints-and-views.md
  • docs/sdd/06-design-elements-and-constraints.md
  • docs/sdd/07-08-traceability-and-rationale.md
  • docs/sdd/09-10-risks-and-summary.md
• レビューアーティファクトファイル:
  • .agent-doc-skills/sdd/gaps/YYYY-MM-DD.md
  • .agent-doc-skills/sdd/drift/YYYY-MM-DD.md

ユーザーが異なるモードを指定した場合、ユーザーの優先度に従います。 ユーザーが異なる標準的な出力ルートまたはアーティファクトルートを指定した場合、プロジェクトフォルダ内の安全な相対ディレクトリのみを受け入れます。

ユーザープロンプトで受け入れられるモードショートカット:

• /deまたは/draft+review -> draft+review
• /dまたは/draft-only -> draft-only
• /rまたは/review-only -> review-only
• /dcまたは/drift-check -> drift-check

モード解決の優先順位:

1. プロンプト内の明示的なショートカットトークン(/de、/d、/r、/dc、または長形式)
2. 明確な自然言語の意図(例: review only)
3. デフォルトはdraft+review

インタラクションオプション:

• /ask(デフォルト): ドラフト作成前にスコープ/モード/入力を確認し、重要な情報の不足を要求します。
• /fast: 合理的な仮定ですぐに進行し、出力に仮定をリストアップします。
• /assume: 入力が不完全な場合でも仮定を続行し、仮定ベースのセクションを明確にマークします。

詳細プロファイルオプション:

• ieee-pragmatic(デフォルト): 厳密なベース構造と簡潔な実装ガイダンス。
• implementation-deep: すべてのベースセクションを保持し、より深い実装ファイルを追加します。

ユーザーがdetailed、implementation handoff、architecture deep dive、ERD/data dictionary、またはfull design packageを求める場合、implementation-deepを使用します。

出力ルート安全性(必須)

• 出力はリポジトリルート(プロジェクトフォルダ)内にのみ書き込みます。
• リポジトリ内に留まる場合、カスタム標準的なルートまたはアーティファクト親ルートを許可します(例: docs/architecture/sdd/または.agent-doc-artifacts/)。
• 絶対パスと親トラバーサル(..)を含むパスを拒否します。
• 機密パス(例: .git/、.github/workflows/、/etc/、ホームディレクトリ)に書き込まないでください。
• ユーザー提供のパスをインターポレートしてシェルコマンドを構築しないでください。

入力契約

少なくとも1つを予想します:

• プロジェクト要件/PRDコンテキスト、または
• レビュー/更新するための既存のSDDドキュメントセットルートまたはindex.md、または
• 標準的なドキュメントセットに変換するレガシー単一ファイルSDD。

いずれも利用できない場合、ドラフト作成前に不足している入力を要求して停止します。 プロジェクト固有のアーキテクチャの詳細を作成しないでください。

便利なオプション入力:

• アーキテクチャの制約、
• テクノロジースタック制約、
• 必須ビューポイント、
• 完全性の厳密さのオーバーライド、
• プロジェクトフォルダ内の明示的な出力ルート。
• プロジェクトフォルダ内の明示的なアーティファクトルート。

ドラフト作成前に、インテークチェックを実行します:

1. モード、詳細プロファイル、出力ルートを確認します。
2. リポジトリ検査を使用するかどうかを確認します。
3. 重要な入力の不足を特定します(PRDコンテキスト、既存SDD入力、主要制約)。

重要な入力が不足している場合は、最初に簡潔な説明質問をします。 ユーザーが明示的に/fastまたは/assumeを使用した場合のみ説明をスキップします。

モード

draft+review(デフォルト)

1. docs/sdd/以下の標準的なドキュメントセットを作成またはアップデートします。
2. 完全性/ギャップ分析を実行します。
3. SDDファイルをdocs/sdd/に書き込み、日付付きギャップレポートを.agent-doc-skills/sdd/gaps/に書き込みます。

draft-only

1. docs/sdd/以下の標準的なドキュメントセットを作成またはアップデートします。
2. リクエストされない限りギャップレポートをスキップします。

review-only

1. 既存のドキュメントセットSDDルートまたはindex.mdを入力として受け入れます。
2. ユーザーが求めない限りソースファイルを書き直しません。
3. ドキュメントセットの具体的な修復アクションを含む日付付きギャップレポートを.agent-doc-skills/sdd/gaps/に作成します。

drift-check

1. 既存のドキュメントセットSDDルートまたはindex.mdとリポジトリコンテキストを受け入れます。
2. 入力SDD開始点index.mdからDoc Baseline Commitを読み込み、gitの履歴、差分サマリー、および変更ファイルの対象差分を使用して<baseline>..HEADを比較します。
3. 差分をスコープ境界として使用します: 変更されたファイルを検査し、それらの変更がSDD要求に影響を与えるかを理解するために必要な直接関連の隣接ファイルのみを検査します。
4. ベースラインが不足している場合、無効である場合、または到達不可能である場合は停止し、ユーザーにベースラインソースを確認するよう要求します。タイムスタンプまたは近くのコミットからベースラインを推測しないでください。
5. 変更された領域、影響を受ける可能性のあるSDDファイル/セクション、および推奨される次のアクションを含む日付付き乖離レポートを.agent-doc-skills/sdd/drift/に作成します。
6. このモードで乖離レポートを確認した後、ユーザーが明示的に要求しない限り、標準的なSDDファイルを書き直しません。

必須ワークフロー

1. コンテキストを発見する

• デフォルトでリポジトリドキュメントと主要なコード構造を検査します。
• 利用可能なアーティファクトを特定します: PRD、既存ドキュメントセットSDDファイル、レガシー単一ファイルSDD、アーキテクチャノート、API、スキーマ。

2. ステークホルダーと懸念事項を特定する

• 明示的および暗黙的な設計ステークホルダーを抽出します。
• 要件/リスク/NFRを設計懸念に変換します。

3. ビューポイントを選択する

• 特定された懸念事項に対処するビューポイントのみを選択します。
• 省略されたビューポイントを正当性付きでNot Applicableとマークします。

4. SDDドキュメントセットを作成またはアップデートする

• references/document-set/を標準的なテンプレートライブラリとして使用します。
• ソースがレガシー単一ファイルSDDの場合、その検証済みコンテンツを標準的なドキュメントセットに再配置し、古いレイアウトを保持しません。
• index.mdはドキュメント開始点であり、ドキュメント管理メタデータと標準的な順序での生成されたセクションファイルへのリンクを含める必要があります。
• ドキュメントセット乖離メタデータはindex.mdにのみ格納します。セクションファイル全体で重複させないでください。
• リポジトリコンテキストが利用可能な場合、## Document ControlにDoc Baseline CommitとLast Reviewed Onを含めます。
• 元の表現を使用します。著作権で保護された標準テキストを引用したり、ミラーリングしたりしないでください。
• セクション所有権をファイル別に保留します。
• コアアーキテクチャセクションをアーキテクチャ抽象レベル(レイヤー/コンポーネント/責任)に保持し、ファイル別のリスト実装はしません。
• 必要に応じて、実装指向ファイルまたは付録に具体的なファイル/モジュールパスを配置します。
• 明確性が向上する場合はMermaid図を含めます。
• つねにコア3つの形式的アーティファクトを含めます:
  • 04-architecture-overview.mdの## 4. Architecture Overview
  • 05-viewpoints-and-views.mdの### 5.1 Viewpoint-to-View Mapping
  • 06-design-elements-and-constraints.mdの### 6.1 Design Element Catalog (Formal Definitions): フィールド Component、Responsibility、Inputs、Outputs、Dependencies、Public Functions
• オプションの強化:
  • 品質懸念が重要である場合、Stimulus、Environment、Response、Measurementを使用した品質属性シナリオを含めます。
  • 永続データが現在不在/静的である場合、06-design-elements-and-constraints.mdおよび/または11-data-design.mdに短い将来進化ノートを含めます。
  • オプションの強化が省略された場合、簡潔なN/A rationaleを追加します。
• 詳細プロファイルがimplementation-deepの場合、拡張ファイルを含めます:
  • 11-data-design.md
  • 12-component-design.md
  • 13-human-interface-design.md
  • 14-requirements-traceability-matrix.md
  • 15-appendices.md
  • 16-design-decisions-locked.md

5. 実用的な完全性パスを実行する

• 標準テキストを複製することなく、IEEE にインスパイアされた構造テーマに対するカバレッジを確認します。
• 懸念事項からビューカバレッジと不足している決定を確認します。
• アーキテクチャ/ビューポイント/要素の形式化がファイル全体で明示的かつ検査可能であることを確認します。
• 用語、コンポーネント名、バージョン参照、および引用されたアーティファクトの一貫性をドキュメントセット全体で確認します。
• index.mdがすべての生成されたセクションファイルにリンクしていることを確認します。
• プロジェクトスケールの正当化された簡略化を許可します。

6. モードがdrift-checkの場合、乖離評価を実行する

• index.mdからDoc Baseline Commitを読み込みます。
• ベースラインが不足している場合、無効である場合、またはgit履歴で到達不可能な場合は停止し、ユーザーに確認されたベースラインソースを選択するよう要求します:
  • SDDベースラインとして使用する特定のコミット/参照、
  • SDDが最後にレビューされたコミット、
  • 以前の変更で乖離比較がない新しいベースラインとしての現在のHEAD。
• ファイル変更時刻、アーティファクト日付、または近くのコミットからベースラインを推測しないでください。ただし、ユーザーがそのヒューリスティックを明示的に承認した場合は除きます。
• git log、git diff --stat、および変更されたファイルの対象git diff出力を使用して<baseline>..HEADを比較します。
• 差分をスコープ境界として使用します: 変更されたファイルを検査し、変更された動作を理解するために必要な直接関連の隣接ファイルのみを検査します。
• ユーザーが明示的に要求しない限り、リポジトリ全体の現在のコード監査を実行しません。
• 変更された領域をSDDインパクト別に分類します: アーキテクチャ、コンポーネント責任、インターフェース/API、データモデル/ストレージ、ランタイム/デプロイ、依存性、品質属性、リスク、またはSDDインパクトなし。
• 影響を受けるSDDセクションを、スコープされた現在の実装証拠と比較します。
• 変更されたファイルに結びついた場合、または直接関連の証拠がある場合にのみ、古い、サポートされていない、または不足しているSDDコンテンツを報告します。
• 変更された領域を、影響を受ける可能性のあるSDDファイル/セクションにマッピングします。
• 出力は示唆的に保ちます。標準的なSDDファイルを自動的に更新しないでください。

7. 出力を書き込む

• 親ディレクトリが存在することを確認します。
• リポジトリルート内のみで安全に標準的な出力ルートとアーティファクト親ルートを解決します。
• draft+reviewまたはdraft-onlyの場合、docs/sdd/または承認されたカスタム標準的なルート以下に標準的なセクションファイルを書き込みます。
• draft+reviewまたはreview-onlyの場合、.agent-doc-skills/sdd/gaps/または承認されたカスタムアーティファクト親ルート以下に日付付きギャップレポートを書き込みます。
• drift-checkの場合、.agent-doc-skills/sdd/drift/または承認されたカスタムアーティファクト親ルート以下に日付付き乖離レポートを書き込みます。
• review-onlyおよびdrift-checkでは、明示的に要求されない限り、ソースSDDファイルを変更しないでください。

8. 標準的な出力を検証する

• python3 scripts/check_sdd_structure.py --mode <draft+review|draft-only|review-only|drift-check> --docs-dir <canonical-output-root> --profile <ieee-pragmatic|implementation-deep>を実行します。
• evals/CI厳密性については、--require-all-subsectionsで実行します。
• セクション完全性はデフォルトで厳密です。セクションチェックが勧告的であるべき場合のみ--allow-soft-sectionsを使用してください。
• review-onlyまたはdrift-checkでは、CI/evalsが不足している標準的な入力ファイル、不足しているドキュメントマップリンク、または確認されたSDDセット内の不足している必須見出しで失敗すべき場合、--strict-review-inputを追加します。
• チェッカーは標準的なSDDドキュメントセットのみを検証します。ギャップまたは乖離アーティファクトファイルは検証しません。
• チェッカーのハードフェール結果をブロッカーとして扱い、最終化前に出力を修正します。

9. 日付付きアーティファクト出力を検証する

• draft+reviewまたはreview-onlyの場合、python3 scripts/check_doc_artifacts.py --artifact-root <artifact-root> --doc-kind sdd --artifact-kind gapsを実行します。
• drift-checkの場合、乖離チェックが有効な到達可能なベースラインで完了し、乖離レポートを生成した場合にのみpython3 scripts/check_doc_artifacts.py --artifact-root <artifact-root> --doc-kind sdd --artifact-kind driftを実行します。
• アーティファクトチェッカーは日付付きMarkdownファイルが存在し、YYYY-MM-DD.md命名を使用することを強制します。
• その分岐で対象アーティファクトタイプが予想される場合、evals/CI内の不足している必須アーティファクト履歴をブロッカーとして扱います。

標準的なベースファイルセット

これらのファイルをデフォルトドキュメントシーケンスとして使用します:

1. index.md
2. 01-introduction.md
3. 02-03-system-context-and-concerns.md
4. 04-architecture-overview.md
5. 05-viewpoints-and-views.md
6. 06-design-elements-and-constraints.md
7. 07-08-traceability-and-rationale.md
8. 09-10-risks-and-summary.md

ギャップレポート形式

これらの見出しを順序で使用します:

1. # SDD Gap Report
2. ## Scope and Inputs
3. ## Missing Required Content
4. ## Weak or Implicit Rationale
5. ## Traceability Gaps
6. ## Recommended Fixes (Priority Ordered)
7. ## Coverage Summary

.agent-doc-skills/sdd/gaps/YYYY-MM-DD.mdに日付付きギャップレポートを書き込みます。

乖離レポート形式

これらの見出しを順序で使用します:

1. # SDD Drift Report — YYYY-MM-DD
2. ## Scope and Baseline
3. ## Changed Since Last Review
4. ## Recommended SDD Files and Sections to Revisit
5. ## Suggested Next Action

トップ付近に次のメタデータ箇条書きを含めます:

• SDD Root:
• Baseline Commit:
• Current Commit:
• Commits Since Baseline:
• Checked On:

.agent-doc-skills/sdd/drift/YYYY-MM-DD.mdに日付付き乖離レポートを書き込みます。

実用的な完全性ルール

• マッピングされたコアコンテンツ領域を、本当にスコープ外でない限り必須として扱います。
• コアアーキテクチャ/ビュー/要素形式化(04、5.1、6.1の正式フィールド付き)を必須として扱います。
• 品質シナリオと将来進化ノートを推奨される強化として扱います。簡潔なN/A rationaleを使用して省略を許可します。
• 項目が省略されている場合、短いN/A rationaleを提供します。
• 儀式的な詳細よりも正確性と実装可能性を優先します。
• 用語をプロジェクトドメインと一貫性を保ちます。
• aestheticsなどの曖昧なラベルよりもUX consistency/visual design constraintsを優先します。
• monolithic stylesheetよりもsingle consolidated stylesheetを優先します。
• ユーザーが正確なIEEE表現を求める場合は断り、非逐語的サマリーを提供します。

出力品質基準

• SDDセクションは実装ハンドオフに十分に完成しています。
• index.mdは安定したナビゲーションとドキュメント管理を提供します。
• アーキテクチャ概要は明示的で、論理的およびデプロイ/ランタイム描写を含みます。
• ビューポイント選択は明示的で、ビューポイント-ビューマッピングを含みます。
• 設計要素は、コンポーネントフィールド付きで正式に定義されています。
• 用語、コンポーネント名、およびバージョン/参照はファイル全体で内部的に一貫しています。
• ギャップレポートの推奨事項は実行可能で優先順位付けされています。
• 乖離レポートはgit変更をスコープ境界として使用し、明示的に要求されない限り完全なコードベース監査を回避します。
• 乖離レポートは、標準的なドキュメントを自動的に編集することなく、変更された実装証拠をSDD更新の可能性に明確にマッピングします。
• ドキュメントコンテンツに機械固有の仮定またはローカル専用の依存関係はありません。

このスキルをトリガーすべきリクエスト例

• 「このPRDとリポジトリ構造からIEEE 1016にインスパイアされた構造を使用してSDDドキュメントセットを作成してください。」
• 「このマルチファイルSDDをレビューし、標準ギャップと修正をリストアップ