design-doc

Topics in the source

• Design Document Skill
• ADR との違い
• 手順
• ファイル形式
• 壁打ちの進め方ガイドライン
• 命名規則

設計の壁打ちや検討過程を docs/design/ にドキュメントとして残す。 ADR（決定記録）の前段階として、アイデアの探索・比較・整理を行うためのドキュメント。 | | Design Doc | ADR | |---|---|---| | 目的 | 設計の探索・壁打ち・検討過程の記録 | 最終的な設計判断の記録 | | ステータス | ドラフト → 検討中 → ADR化（昇格時に元ファイルは削除） | 提案 → 決定済み/却下 | | 内容 | 問題の深掘り・選択肢の比較・トレードオフ分析 | 決定事項・理由・却下した案 | | 配置先 | docs/design/ 直下 | docs/adr/（日本語で書く） | 1. ユーザーと対話しながら設計の論点を明確にする 何を解決したいのか（問題・課題） どういう制約があるか どんな選択肢を考えているか 2. 過去決定の確認（必須） — docs/design/ および docs/adr/ の既存ドキュメントを確認し、重複・関連・衝突がないか調べる。この確認を設計着手前に必ず行う（測定上、記録の存在そのものより、この「取り出す手続き」の方が数倍効く — hane ADR-63） 今回のテーマに関わる語彙で docs/adr/ のファイル名と本文を grep し、過去に同様のテーマが検討・決定されていないかを遡って探査する とりわけ 却下された決定（ステータス: 却下 の ADR、または採用 ADR の「## 却下した案」節） を狙って探す。今回の案が過去に却下された案と同じなら、その却下理由を設計に反映する（同じ轍を踏まない／覆すなら根拠を新 ADR に残す） 衝突する過去決定が見つかったら、ドキュメントの「背景・課題」または「制約・前提」に明記し、関連 ADR を相互リンクする 3. テスト観点ライブラリ（TPL）を確認する（ホスト repo が docs/test-perspectives/ を採用している場合のみ。ディレクトリが無ければ本ステップをスキップする）。2 段階で観点を取り込む: 1. 既存 TPL の一覧: 今回の設計にマッチする TPL を引き、ドキュメントの ## Related TPLs 節に列挙する（docs/test-perspectives/ へのリンク付き） tpl CLI の呼び方: tpl CLI（@kompiro/tpl-tools）を次の順で探し、最初に見つかった呼び方を使う: ホスト repo が script で tpl を包んでいればその script ／ @kompiro/tpl-tools が devDependency にあれば pnpm exec tpl / npx tpl ／ PATH 上の tpl。どれも repo のルートで実行する。script

This is an excerpt. Refer to the complete source and its current requirements.