詳細な技術計画を作成する

12 分

仕様では、ビルドする必要がある内容を定義します。技術計画では、その構築方法を定義します。このユニットでは、エンタープライズブラウンフィールドシナリオの高度な計画手法について説明します。

プランの基礎を確認する

plan.md ファイルは、設計ドキュメントとして機能し、spec.md の高レベル要件と、その後の具体的な実装タスクの間のギャップを埋めます。包括的な技術計画には次のものが含まれます。

アーキテクチャの概要: コンポーネントの相互作用の概要。
テクノロジスタックと主要な決定: 論理的根拠を含むテクノロジの選択に関する明示的なドキュメント。
実装シーケンス: 実装手順の論理的な進行。
憲法検証: 提案されたソリューションがプロジェクトの原則に準拠していることを明示的に確認します。
前提条件と未解決の質問: 前提条件と未解決の質問のドキュメント。

これらの基礎を念頭に置いて、エンタープライズ開発の高度な計画に関する考慮事項について説明します。

懸念事項の分離 - 仕様と計画

仕様と技術計画の間で懸念事項を分離することが重要です。仕様は安定しており、"何" に焦点を当てていますが、さまざまな "方法" アプローチを試しながら計画を進化させることができます。

たとえば、社内の従業員ポータルのドキュメントアップロード機能が仕様に必要だとします。仕様では、ユーザーの要件 (ファイルサイズの制限、サポートされている形式、フィードバックのアップロード、アクセス制御) が定義されています。技術計画では、これらの要件を具体的なアーキテクチャ上の決定に変換します。使用する Azure Storage サービス、API を構成する方法、実装する認証メカニズム、およびファイルを検証する方法です。 Azure Blob Storage から Azure Files への移行など、あるテクノロジから別のテクノロジに切り替える場合は、plan.md を更新しますが、spec.md はほとんど変更されません。機能の要件は変更されません。実装アプローチのみが変更されます。

プランの構造と内容を調べる

包括的な技術計画には、実装アプローチをまとめて定義する主要なセクションがいくつか含まれています。

アーキテクチャの概要

アーキテクチャの概要では、コンポーネントの相互作用の概要を示します。ドキュメントのアップロード機能の場合、アーキテクチャでは次の記述が行われる場合があります。

"マルチパートファイルのアップロードを処理する新しいバックエンド API エンドポイント /api/documents/upload を実装します。 React フロントエンドには、ファイルピッカーと進行状況インジケーターを含む新しい DocumentUpload コンポーネントが含まれています。ユーザーがファイルを選択すると、フロントエンドはアップロード前にサイズと種類を検証します。バックエンドはファイルを受け取り、再度検証し、Azure Blob Storage に格納し、メタデータを SQL データベースに記録します。アップロードが成功すると、フロントエンドはドキュメントリストを更新して新しいファイルを表示します。

この概要では、コードレベルの詳細を確認することなく、全体的なフローを確立します。これにより、すべてのユーザーが主要なコンポーネントとその相互作用を理解できるようになります。

テクノロジスタックと主要な決定事項

この計画では、テクノロジの選択と根拠が明示的に文書化されています。このセクションでは、特定のライブラリまたはサービスが選択された理由に関する将来の混乱を防ぎます。

テクノロジに関する決定の例:

バックエンド: BLOB 操作用の .NET 8 Web API と Azure.Storage.Blobs SDK v12。
フロントエンド: UI の一貫性を確保するために、Ant Design のアップロードコンポーネントを使用して React 18 を実行します。
認証: ポータルの認証コンテキストから既存の Microsoft Entra ID トークンを使用します。
ストレージ: employee-documentsという名前の Azure Blob Storage コンテナー。
データベース: DocumentMetadata テーブルを使用して既存の SQL データベースを拡張します (列: ID、UserId、FileName、BlobUrl、UploadDate、FileSize)。

各決定は、仕様要件と憲法の原則の両方と一致する必要があります。構成で "すべてのクラウドリソースに Azure サービスを使用する" ことが義務付けられている場合、プランは Azure Blob Storage を明示的に選択し、この原則を参照します。

実装シーケンス

この計画では、実装手順の順序を概説します。このシーケンスは、後で生成されるタスクリストほど詳細ではありませんが、セットアップから完了までの論理的な進行を提供します。

ドキュメントアップロード機能の一般的な実装シーケンス:

データベーススキーマの更新: 適切なインデックスと制約を持つ DocumentMetadata テーブルを作成します。
バックエンド API 開発: ファイル検証、BLOB ストレージ統合、メタデータ永続化を使用して POST /api/documents/upload エンドポイントを実装します。
フロントエンドコンポーネントの作成: ファイルの選択、クライアント側の検証、アップロードの進行状況の表示を使用して DocumentUpload コンポーネントをビルドします。
統合: フロントエンドコンポーネントをバックエンド API に接続し、応答を処理し、ドキュメント一覧を更新します。
セキュリティ強化: サーバー側のファイルの種類の検証、サイズ制限、認証チェックを実装します。
エラー処理: クライアントとサーバー側のエラーに関する包括的なエラーメッセージを追加します。
テスト: API メソッドの単体テストとアップロードフローの統合テストを作成します。

このシーケンスにより、依存コンポーネント (データベースに書き込む API) が実装される前に、基本要素 (データベーススキーマ) が確実に存在します。各手順は前の作業に基づいており、統合の問題が発生する可能性が低くなります。

憲法検証

計画には、提案された解決策を憲法に照らして明示的にチェックする検証セクションが含まれています。この検証により、アーキテクチャの誤差を防ぎ、プロジェクトの原則との一貫性を確保します。

構成に "すべてのデータストレージで Azure サービスを使用する必要がある" と "API はクライアントとサーバーの両方で入力を検証する必要があります" が含まれている場合、プラン検証セクションでは次の点が確認されます。

"Azure Blob Storage を使用すると、Azure サービスの要件が満たされます。"
"React コンポーネント (クライアント) と .NET API (サーバー) の両方で検証を実装すると、多層防御のセキュリティ原則に準拠しています。"
"Microsoft Entra ID 認証要件は、既存のポータル認証コンテキストを使用して満たされています。"

この検証はチェックポイントとして機能します。プランが憲法に違反するものを提案した場合、AI は通常、それにフラグを付けます。または、レビュー中に気付きます。計画フェーズで構成の競合に対処することにより、後の再作業を防ぐことができます。

前提条件とオープンな質問

適切に構築された計画では、前提条件と未解決の質問が文書化されます。この透明性は、実装を開始する前に潜在的な問題を特定するのに役立ちます。

前提条件の例:

"Azure Blob Storage コンテナー 'employee-documents' が存在し、プライベートアクセス用に構成されているとします。"
"既存の SQL データベースにメタデータ用の十分なストレージ容量があるとします。"
"アップロードされたファイルのウイルススキャンがこのイテレーションの範囲外であると仮定します。"

開いている質問の例:

"管理者は、他のユーザーのアップロードしたドキュメントを削除する機能を持っている必要がありますか?
"すべてのドキュメントアクセス試行に監査ログが必要ですか?
"ドキュメントがアップロードされたときに、システムは電子メール通知を送信する必要がありますか?

これらの前提条件と質問を文書化することで、プロジェクトのスコープの拡張を防ぎ、コーディングを開始する前に関係者が重要な決定を確実に行えるようにします。実装中に想定が正しくないと証明された場合は、それに応じてプランを更新できます。

/speckit.plan を使用してプランを生成する

GitHub Spec Kit は、GitHub Copilot Chat の /speckit.plan コマンドを使用してプランを生成します。このコマンドは、spec.md と constitution.md の両方を入力として使用して、包括的な技術設計を作成します。

コマンドを呼び出す前に、AI に必要なその他のコンテキストを検討してください。既存のコードベース、テクノロジの基本設定、インフラストラクチャの制約はすべて、計画に影響します。このコンテキストを事前に提供すると、より正確で実用的な結果が得られます。

社内の従業員ポータルシナリオのドキュメントアップロード機能では、次のようなコンテキストを指定できます。

"既存のポータルでは、React フロントエンドと .NET 8 Web API バックエンドが使用されます。アップロード機能をこのスタックに統合する必要があります。ファイルの永続化には Azure Blob Storage を使用します。すべてのアップロード操作に Microsoft Entra ID 認証が必要です。ポータルには、メタデータストレージに使用できる SQL データベースが既にあります。"

このコンテキストにより、AI は、現在のスタックに合わないグリーンフィールドソリューションを提案するのではなく、既存のアーキテクチャにシームレスに適合するプランを生成できます。

計画コマンドを呼び出す

Visual Studio Code で GitHub Copilot Chat を開き、「 /speckit.plan」と入力します。 AI が詳細情報を要求する場合は、アーキテクチャコンテキストを指定します。 GitHub Copilot は、仕様、構成、および追加のコンテキストを処理して、plan.md を生成します。

AI がさまざまなアプローチを検討し、構成に照らしてチェックし、出力を一貫した設計ドキュメントに構造化する場合、計画フェーズには少し時間がかかる場合があります。

プランを確認して検証する

プランの生成は、最初の手順にすぎません。重要なレビューにより、プロジェクトのニーズに合わせて計画が正確かつ完全に行われるようにします。

仕様要件の対象範囲を確認する

計画と spec.md を体系的に比較します。仕様のすべての要件は、計画の実装アプローチにマップする必要があります。

たとえば、spec.md に "50 MB を超えるファイルのエラーメッセージを表示する" 必要がある場合、プランでは、この検証がどこでどのように行われるかを記述する必要があります。プランでこの検証が省略されている場合は、プランが不完全であるか、仕様の明確化が必要です。

技術基準との整合性を確認する

プランのテクノロジの選択が、組織の標準とベストプラクティスと一致していることを確認します。チームが特定のライブラリまたはパターンを標準化している場合は、プランにこれらの設定が反映されている必要があります。

考慮すべき質問:

提案されたアーキテクチャは既存のシステムに適合しますか?
選択したライブラリは、お使いの環境での使用が承認されていますか?
テクノロジの選択は、組織のセキュリティとコンプライアンスのポリシーに準拠していますか?
同様の機能に対して確立されたパターンに従う必要がありますか?

Azure 環境のドキュメントアップロード機能の場合は、Azure Blob Storage が承認されたサービスであり、認証方法がエンタープライズ ID 標準 (Microsoft Entra ID の使用など) と一致していること、および提案された SQL スキーマがデータベースの名前付け規則に従っていることを確認します。

構成の準拠を検証する

計画には、提案されたソリューションが憲法要件に準拠していることを明示的に検証する必要があります。この検証セクションを慎重に確認して、原則に違反がないことを確認してください。

構成で "すべてのシークレットを Azure Key Vault に格納する必要があります" が必要であり、プランが azure Storage 接続文字列を appsettings.jsonに格納することを提案している場合、競合が存在します。実行時に Key Vault から接続文字列を取得するように計画を変更する必要があります。

計画中に発見された憲法違反は簡単に修正できます。コードレビューまたは運用環境のデプロイ中に検出された憲法違反は、コストがかかり、混乱を招きます。

計画を反復処理して調整する

多くの場合、プランでは初期生成後に絞り込みを行う必要があります。最初の試みで完璧を期待しないでください。 GitHub Copilot の明確化機能を使用して、プランの品質を向上させます。

あいまいさとギャップに対処する

プランに "適切なエラー処理を実装する" などのあいまいなステートメントが含まれている場合は、詳細を押します。どのようなエラーが発生する可能性がありますか? 各エラーはどのように処理する必要がありますか? ログに記録する必要があるエラー情報とユーザーに表示するエラー情報

GitHub Copilot Chat を使用して、次のフォローアップの質問を行います。"アップロードエンドポイントで処理すべき具体的なエラーは何ですか?" または "Azure Blob Storage が使用できない場合はどうなりますか?AI は、あいまいなセクションを具体的な仕様に拡張できます。

技術的な実現可能性を検証する

制約を受け、提案されたアーキテクチャが技術的に実現可能であることを確認します。 30 秒のタイムアウトで Web API を介して同期的に 50 MB のファイルをアップロードすることを計画で提案している場合は、問題が存在します。 50 MB を超えるファイルでは、チャンクアップロードやタイムアウトの増加が必要になる場合があります。

関連する専門知識を持つチームメンバーに相談します。プランでデータベーススキーマの変更が提案されている場合は、データベース管理者に確認してください。新しい Azure リソースが必要な場合は、プロビジョニングが可能であることをインフラストラクチャエンジニアに確認してください。

機能しない要件を検討する

プランが仕様の非機能要件 (パフォーマンス、セキュリティ、スケーラビリティ、保守容易性、アクセシビリティ) に対応していることを確認します。

ドキュメントのアップロードの場合は、プランに次のものが含まれていることを確認します。

パフォーマンス: アップロードはどのくらいの速さで完了する必要がありますか? 最大同時アップロード量は何ですか?
セキュリティ: ファイルはどのようにしてマルウェアを検出するのですか？アクセスはどのように制御されますか? 監査ログはどこに保存されますか?
スケーラビリティ:システムはアップロード量の増加をどのように処理しますか? ストレージ容量の制限とは
保守容易性: 従業員が組織を離れると、アップロードされたファイルはどのようにクリーンアップされますか?
アクセシビリティ: アップロード UI は Web コンテンツアクセシビリティガイドライン (WCAG) 2.1 AA 標準を満たしていますか?

プランでこれらの考慮事項のいずれかが省略されている場合は、明示的に追加します。非機能要件は、多くの場合、計画段階で対処されていないと、実装中に後回しされることになります。

実現可能性と完全性を評価する

計画が実装に十分なガイダンスを提供するかどうかを評価します。あいまいすぎるプラン ("ファイルのアップロードを実装する") は役に立ちません。規範的すぎるプラン ("正確に 47 行のコードを使用する") は、過度に制約されています。

適切な詳細レベルは、すべての柔軟性を取り除かずに明確な方向を提供します。プランは次の質問に答えるべきです。

どのコンポーネントを作成または変更する必要がありますか?
これらのコンポーネントはどのように相互作用しますか?
どのようなテクノロジとライブラリが使用されますか?
実装順序は何ですか?
どのような検証手順で正確性が確保されますか?

プランから機能を実装する方法を想定できない場合は、さらに詳細が必要です。計画がコードを記述しているように感じる場合は、詳細すぎる可能性があります。

不足している要素を特定する

プランのギャップを探します。一般的な省略は次のとおりです。

エラー処理: システムは、ネットワーク障害、ストレージエラー、またはデータベースの問題をどのように処理しますか?
パフォーマンスに関する考慮事項: アップロード速度、同時ユーザー、またはストレージの制限に関する問題はありますか?
テスト戦略: 実装を検証するために記述する必要があるテストは何ですか?
ロールバックアプローチ: デプロイで問題が発生した場合、変更をどのように元に戻しますか?

これらのギャップに対処するために、plan.md を手動で編集するか、より多くのコンテキストを提供し、関連するセクションを再生成します。

改善されたコンテキストで再生成する

初期計画が目標に達しない場合は、より具体的な状況を指定して見直します。たとえば、プランで新しいデータベースの使用が提案されているが、既存のデータベースを使用する必要がある場合は、「既存の EmployeePortal データベースを使用します。新しいテーブルを作成するのではなく、このデータベースに DocumentMetadata テーブルを追加します。

この更新されたコンテキストを組み込む /speckit.plan でプランを再生成します。 AI はそれに応じてアプローチを調整します。

プランを手動で編集する

plan.md は Markdown ファイルであるため、直接編集できます。 AI が 90% 正しいアプローチを提案しているが、少し調整が必要な場合は、すべてを再生成するのではなく、ファイルを編集します。

たとえば、プランで特定の BLOB コンテナー名が提案されているが、組織に名前付け規則がある場合は、plan.md でコンテナー名を直接更新します。

チームメンバーとの共同作業

チーム環境では、レビューのために plan.md を共有します。上級開発者またはアーキテクトは、実装を開始する前にアーキテクチャの決定を検証できます。このピアレビューでは、自動チェックで見落とされる可能性がある問題をキャッチします。

チームレビューでは、共有の理解も構築されます。複数の開発者が 1 つの機能に取り組む場合、計画をまとめて確認することで、すべてのユーザーがアプローチを把握し、他の進行中の作業との潜在的な競合を特定できます。

アーキテクチャの決定を文書化する

計画では、構築する内容だけでなく、将来の開発者が意思決定コンテキストを理解するのに役立つ特定のアーキテクチャの選択を行った理由を文書化する必要があります。

考えられる代替手段を記録する

複数の実行可能なアプローチを選択する場合は、検討した代替手段と、他の方法よりも選択した理由を文書化します。

ファイルストレージの場合は、次の 3 つの方法を検討できます。

Azure Blob Storage: コスト効率、スケーラビリティ、および既存の Azure 環境との統合のために選択されます。
Azure Files: 大規模なファイルストレージのコストが高く、不要なサーバーメッセージブロック (SMB) プロトコルのオーバーヘッドが原因で拒否されました。
SQL Database FILESTREAM: データベースのサイズと複雑さの増加を回避するために拒否されました。

このドキュメントでは、将来の開発者が、より単純なアプローチが使用されなかった理由を疑問に思うのを防ぎます。決定の根拠は、時間に失われるのではなく、保持されます。

前提条件をキャプチャする

計画では、既存のシステム、インフラストラクチャ、および組織の制約に関する想定が行われます。これらの前提条件を明示的にします。

ドキュメントアップロードの前提条件の例:

Azure Blob Storage コンテナー employee-documents は、開発を開始する前にインフラストラクチャチームによってプロビジョニングされます。
既存のポータル認証では、ユーザー ID に対して信頼できる検証済みの Microsoft Entra ID トークンが提供されます。
SQL データベースには、ストレージの拡張を必要とせずに、別のメタデータテーブルに対して十分な容量があります。
ネットワークインフラストラクチャでは、プロキシやファイアウォールの制限なしで 50 MB の HTTP アップロードがサポートされます。

実装中に想定が正しくないと証明された場合は、計画を見直し、それに応じて調整できます。文書化された前提条件により、状況が変化したときに影響分析が簡単になります。

将来の進化を計画する

この機能がどのように進化するか検討し、アーキテクチャが拡張機能の可能性を高く受け入れるようにします。

ドキュメントのアップロードの場合、将来の要件として次のものが含まれる可能性があります。

PDF や DOCX 以外の他のファイルの種類をサポートします。
従業員間のファイル共有を実装する。
ドキュメントのバージョン管理の追加。
複数のファイルの一括アップロードを有効にする。
ウイルススキャンの統合

アーキテクチャによってこれらの拡張機能が困難になる場合は、初期設計の調整が保証されるかどうかを検討してください。現時点で、将来の機能を実装しませんが、今後の変更を困難にするような状況にすることは避けるようにします。

このプランは、実装全体を通じて参照になります。開発者は、計画を定期的に調べ、コードが文書化されたアーキテクチャと一致していることを確認する必要があります。

計画を完了したら、検証のために関連する利害関係者と共有します。

製品マネージャー: プランがすべての仕様要件を満たすことを確認します。
セキュリティチーム: セキュリティコントロールが組織の標準を満たしていることを確認します。
インフラストラクチャチーム: 提案された Azure リソースをプロビジョニングおよび構成できることを確認します。
アーキテクチャチーム: 組織のアーキテクチャの原則との整合性を検証します。

この利害関係者レビューでは、実装が開始される前に問題がキャッチされます。提案された認証が不十分であることがセキュリティチームのフィードバックで明らかになった場合は、コードを記述する前にプランを更新します。

必要に応じてプランを更新する

計画は生きているドキュメントです。実装時に、アプローチが意図したとおりに動作しない場合は、新しいアプローチを反映するように計画を更新します。

アップロードの進行状況をブラウザーの localStorage に保存する予定で、プライベートブラウズモードで問題が発生することを検出した場合は、代わりにメモリ内の状態を使用するようにプランを更新してください。理由が保持されるように変更が必要だった理由を文書化します。

plan.md を実際の実装と同期させます。プランとコードが分岐すると、参照ドキュメントとしての価値が失われます。

セキュリティアプローチは組織の要件を満たしていますか?
データベーススキーマの設計は名前付け規則に従っていますか?

プランでデータベースの使用が提案されているが、既存のポータルに既にデータベースがある場合、それは過剰である可能性があります。計画でチームが回避するテクノロジが提案されている場合は、その理由を文書化するか、計画を調整します。

回避する一般的な計画の落とし穴

計画を作成してレビューするときに、次の一般的な間違いを避けます。

計画フェーズをスキップする: 計画なしで仕様からコードに直接ジャンプすると、アーキテクチャミスのリスクが高くなります。計画に投資した時間は、やり直しを防ぐことによって配当を支払います。
レビューなしでプランを受け入れる: AI によって生成される計画は、最終的な設計ではなく、出発点です。常に重要なレビューを行い、特定のコンテキストに照らして検証します。
過剰な制約の実装: 計画は、すべての詳細を指示する必要はありません。開発者が実装時に適切な戦術的決定を行う余地を残します。
憲法上の矛盾を無視する:計画が憲法の原則に違反している場合は、すぐに紛争に対処してください。原則に改訂が必要な場合は、準拠するように計画を調整するか、憲法を更新します。
更新計画の忘れ: 実装によって新しい情報が表示されたら、plan.md 更新します。古い計画は将来の開発者を誤解させ、ドキュメントの価値を下げます。

概要

技術計画により、仕様が実用的なアーキテクチャに変換されます。テクノロジスタックとインフラストラクチャに関する適切なコンテキストで /speckit.plan を使用してプランを生成します。計画を批判的に見直し、すべての仕様要件を確実に満たし、基本方針に合致することを確認し、十分な実装ガイダンスを提供してください。検証済みの計画を使用して、タスクの生成と実装をガイドします。 plan.md は、理解と共に進化し、開発ライフサイクル全体の貴重なコンテキストを提供する生きたドキュメントとして扱います。

フィードバック

このページはお役に立ちましたか?