system-design

システム設計

スタートアップ向けに、モジュール式の包括的な技術アーキテクチャ文書を生成します。

サブエージェントアーキテクチャ

このスキルでは、事前のコンテンツ抽出を伴う並列リサーチエージェントを使用します。パターン：D（リサーチ＋統合）＋E（段階的パイプライン）。

エージェント

エージェント	役割	並列化
prd-reader	PRDと補足ドキュメントを読み込み、構造化された抽出結果を返します	逐次（1回のみ）
tech-researcher	1回のリサーチラウンドを担当します（5つ並列で起動）	並列（5インスタンス）
tad-writer	すべての入力から完全な tad.md を生成します	逐次（すべてのリサーチ完了後）

リサーチラウンド（5つ並列）

• ラウンド 1：テクノロジースタックの検証（React、Node.js、PostgreSQL、Elasticsearch）
• ラウンド 2：インフラストラクチャの検証（Vercel、AWS、CDN、コスト見積もり）
• ラウンド 3：セキュリティレビュー（認証、暗号化、コンプライアンス、API セキュリティ）
• ラウンド 4：リスク評価（ボトルネック、ベンダーロックイン、チームの不足）
• ラウンド 5：総合レビュー（PRD との整合性、チームの能力、すぐに実行できる改善策）

並列化戦略

• PRD コンテンツ：prd-reader が一度だけ抽出し、メインコンテキストには含めません
• リサーチの独立性：各ラウンドでは、概念的に異なる観点（技術、インフラ、セキュリティなど）を調査します
• 推論の分離：各分野の推論を並列ラウンドで分離し、集団思考を防ぎます
• 注：リサーチラウンドは概念的な推論であり、データ取得ではありません。並列ラウンドで根本的に異なる情報が得られるわけではありませんが、分離することで品質が向上します

結果：5つのラウンドがすべて同時に完了し、tad-writer が出力を統合して一貫した TAD を作成します。

環境チェック

実行前に、以下を確認します。

1. プロジェクトディレクトリに prd.md が存在すること
2. 利用可能な場合、補足ドキュメント（idea.md、validate.md）があること
3. リサーチに WebSearch と WebFetch ツールを利用できること
4. tad.md の作成に必要なプロジェクトルートへの書き込み権限があること
5. 最終コミットに必要な Git アクセス権があること

編集前のリポジトリ同期（必須）

既存のリポジトリ内でファイルを作成、更新、削除する前に、現在のブランチをリモートと同期します。

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

作業ツリーに未コミットの変更がある場合は、先にスタッシュし、同期してから復元します。

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

origin がない場合、pull を実行できない場合、または rebase／スタッシュの競合が発生した場合は、作業を中止してユーザーに確認してください。

入力

$ARGUMENTS に含まれるプロジェクトフォルダーのパス：

• prd.md - プロダクト要件（必須）
• idea.md、validate.md - 追加コンテキスト（任意）

ワークフロー

フェーズ 1：セットアップと検証

1. prd.md が存在することを確認します
2. 補足ドキュメントがあれば読み込みます
3. 技術に関する推奨事項について、references/tech-stack.md を読み込みます
4. 既存の tad.md があればバックアップします

フェーズ 2：コンテキストの抽出

PRD から以下を抽出します。

• プロダクト名とビジョン
• 主要な機能と要件
• ユーザーフロー
• 非機能要件
• サードパーティとの統合
• 分析要件

フェーズ 3：アーキテクチャの明確化

明確でない場合は、ユーザーに確認します。

決定事項	選択肢
デプロイ	Vercel／Netlify（推奨）、AWS、GCP、セルフホスト
データベース	PostgreSQL、MongoDB、Supabase／Firebase、複数
認証	ソーシャル（OAuth）、メール／パスワード、マジックリンク、エンタープライズ SSO
予算	無料枠、<$50/mo、<$200/mo、柔軟に設定

フェーズ 4：リサーチと検証

5つのリサーチラウンドを実施します。

1. テクノロジースタック：業界標準に照らして選択肢を検証します
2. インフラストラクチャ：コストとスケーラビリティの観点からホスティングを比較します
3. セキュリティ：選択したスタックに対する OWASP ガイドラインを確認します
4. リスク評価：ボトルネックとベンダーロックインを特定します
5. 総合レビュー：PRD との整合性とスタートアップでの実現可能性を確認します

フェーズ 5：TAD の生成

次のセクションを含む tad.md を作成します。

1. システム概要 — 目的、範囲、PRD との整合性
2. アーキテクチャ図 — システムとフローの Mermaid 図
3. 技術スタック — フロントエンド、バックエンド、データベース、インフラストラクチャ、DevOps
4. システムコンポーネント — インターフェースと依存関係を含むモジュール設計
5. データアーキテクチャ — スキーマ、モデル、フロー、ストレージ
6. インフラストラクチャ — ホスティング、環境、スケーリング、CI/CD、モニタリング
7. セキュリティ — 認証、認可、データ保護、API セキュリティ
8. パフォーマンス — 目標、最適化戦略、キャッシュ
9. 開発 — 環境設定、プロジェクト構成、テスト、デプロイ
10. リスク — リスクマトリックスと緩和策
11. 付録 — 調査結果、代替案、コスト、用語集

テンプレートの全構成については、references/tad-template.md を参照してください。

フェーズ 6：README のメンテナンス（ideas リポジトリ）

tad.md の作成後、プロジェクトフォルダーが ideas リポジトリ内にある場合は、リポジトリの README にあるアイデア一覧表を更新します。

• 推奨：リポジトリのルートに cd し、python3 scripts/update_readme_ideas_index.py を実行します（存在する場合）。
• 代替方法：README.md を手動で更新します（該当するアイデアの TAD ステータスが ✅ になっていることを確認してください）。

フェーズ 7：コミットとプッシュ（必須）

• 更新後、ただちにコミットします。
• リモートにただちにプッシュします。
• プッシュが拒否された場合：git fetch origin && git rebase origin/main && git push を実行します。

このスキルが呼び出された後、追加のプッシュ許可を求めないでください。

フェーズ 8：出力

1. プロジェクトフォルダーに tad.md を書き込みます。
2. アーキテクチャ上の決定事項を要約します。
3. モジュール設計のメリットを強調します。
4. フェーズごとのコスト見積もりを一覧にします。
5. 次のステップ（開発環境の設定、タスクの作成）を提案します。

GitHub リンクを使った報告（必須）

完了を報告する際は、次を含めます。

• tad.md への GitHub リンク
• 更新した場合は README.md への GitHub リンク
• コミットハッシュ

リンクの形式（git remote get-url origin から <owner>/<repo> を取得してください）：

• https://github.com/<owner>/<repo>/blob/main/<relative-path>

ステップ完了レポート

各主要ステップの完了後、次の形式でステータスレポートを出力します。

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

チェック項目の名前は、そのステップで実際に検証する内容に合わせてください。合格には √、不合格には × を使用し、簡単な補足には — を使用します。「Criteria」行には、達成した受け入れ基準の数をまとめます。「Result」行には、全体の判定を記載します。

フェーズ別チェック項目

フェーズ 1 — セットアップ

◆ Setup (step 1 of 8 — environment validation)
··································································
  PRD found:                    √ pass
  Context extracted:            √ pass (product + features + NFRs read)
  Architecture questions answered: √ pass (deployment, DB, auth, budget confirmed)
  ____________________________
  Result:             PASS | FAIL | PARTIAL

フェーズ 4 — 調査

◆ Research (step 4 of 8 — validation rounds)
··································································
  5 parallel rounds completed:  √ pass
  Best practices gathered:      √ pass (tech, infra, security, risk, holistic)
  Patterns validated:           √ pass (OWASP, vendor lock-in, startup feasibility)
  ____________________________
  Result:             PASS | FAIL | PARTIAL

フェーズ 5 — 生成

◆ Generation (step 5 of 8 — TAD authoring)
··································································
  11 sections written:          √ pass
  tad.md created:               √ pass
  Diagrams included:            √ pass (mermaid architecture + flow diagrams)
  ____________________________
  Result:             PASS | FAIL | PARTIAL

フェーズ 8 — 出力

◆ Output (step 8 of 8 — delivery)
··································································
  Summary presented:            √ pass (architecture decisions highlighted)
  README updated:               √ pass (TAD status ✅)
  Committed and pushed:         √ pass (commit hash: ...)
  ____________________________
  Result:             PASS | FAIL | PARTIAL

変更モード

既存の TAD を変更する場合：

1. タイムスタンプ付きのバックアップを作成します。
2. 何を変更するかを確認します（スタック、インフラストラクチャ、セキュリティ、データ、スケーリング）。
3. 構成を維持しながら変更を適用します。
4. 改訂履歴を更新します。

ガイドライン

• 実用的：スタートアップが実装できるソリューションにします。
• コスト重視：予算への影響を考慮します。
• モジュール化：関心事の分離を重視します。
• 具体的：具体的な技術を選定します。
• 視覚的：Mermaid 図を含めます。