design-document

name	design-document
description	リポジトリの現在の設計を、読みやすく保守可能な設計ドキュメントとして 作成・更新・整理する。ユーザーが設計書、システム設計、アーキテクチャ概要、 設計ドキュメントの更新、設計資料の分割や整理を求めた場合は、skill名を 明示しなくても必ず使用する。トリガー: 設計書、設計ドキュメント、 システム設計、アーキテクチャ概要、設計資料、design.md。

設計ドキュメント管理

リポジトリの現在の状態を、設計ドキュメント群として整理・更新する。 ADRのような意思決定の履歴ではなく、現在の設計を正確に伝えることを目的とする。

前提

• 変更前にリポジトリ構成、既存ドキュメント、実装、設定を確認する。
• 設計書は実装や合意済みの方針に基づき、推測で補完しない。
• ADRが存在する場合は、過去の判断理由や代替案を設計書に重複記載せず、ADRへリンクする。
• 日本語リポジトリでは、見出し、説明、表の項目名を日本語で統一する。

ワークフロー

1. 現状を把握する。 既存の設計書と実装を読み、記載済みの内容と実際の状態の差分を確認する。
2. 構成を決める。
   • 小規模な内容はdocs/design.mdにまとめる。
   • 内容が増えて読みづらくなった場合だけ、docs/architecture/などのサブディレクトリへ関心事単位で分割する。
   • 分割した場合もdocs/design.mdを入口として、各文書へのリンクと全体像を残す。
   • 分割のためだけにファイルを増やさない。
3. 設計書を更新する。 現在の構成、責務、境界、主要な関係、前提、制約を、読者が実装を読まずに理解できる粒度で記載する。具体的な項目はリポジトリの規模と目的に合わせて決める。
4. 履歴を分離する。 なぜその方式を選んだか、検討した代替案、過去からの変更理由は、既存ADRへリンクする。対応するADRがない場合、細かな判断を無理にADR化せず、必要ならユーザーにADR作成を提案する。
5. 入口を整える。 docs/design.mdから設計ドキュメント群を辿れるようにし、リンク切れ、重複、古い記述、未解決事項の扱いを確認する。
6. 検証する。 設計書が実装と一致し、スナップショットとして現在の状態を表していることを確認する。コード変更を行わない場合は、既存のドキュメント検査があるときだけ実行する。

更新・分割のルール

• 実装の細かな変更ごとに設計書を更新しない。設計の構造、責務、境界、主要な関係が変わった場合に更新する。
• 1つの文書が長くなった場合は、読者や関心事が明確に分かれるときだけ分割する。
• 分割後も、入口、リンク、用語、責務の説明を一貫させる。
• 設計書は現在のスナップショットであり、変更履歴の蓄積場所ではない。
• 未確定の内容は確定事項のように書かず、「未決定」「仮定」「要確認」などと明示する。

出力形式

作業完了時は次を報告する。

1. 作成・更新した設計ドキュメントのパス。
2. 追加、変更、削除した内容の概要。
3. 分割または統合を行った場合の理由。
4. 参照したADR、未解決事項、仮定。

テンプレートはDESIGN_DOCUMENT_TEMPLATE.mdを使用する。

エラー処理

状況	必須の対応
既存設計書と実装が一致しない	実装を正として差分を整理し、根拠が不明な部分は要確認として残す。
設計書を分割するか迷う	まず1ファイルで整理し、読みやすさや責務の分離に明確な効果がある場合だけ分割する。
ADRと設計書の内容が矛盾する	判断履歴を勝手に書き換えず、矛盾を報告してADRの扱いを確認する。
設計情報が不足している	仮定として明記するか、必要な情報を1つずつ確認する。
既存の未コミット変更がある	上書きせず、対象箇所だけを更新し、無関係な変更を保持する。

参照

参照	用途
DESIGN_DOCUMENT_TEMPLATE.md	設計ドキュメント群を新規作成または整理する

実行後の振り返り

複数ステップのワークフロー完了後は、core § 5 実行後の振り返りの手順に従う。