✍️
設計書を修正する際に気を付けるべき点
設計書を修正する際に気を付けるべき点
はじめに
設計書はシステムの健全性を保つための重要なドキュメントです。正確な設計書は、開発の手戻りを防ぎ、チームメンバー間の認識齟齬をなくし、将来のメンテナンス性を高める上で不可欠です。
私が今設計書の修正をしているからこそ気を付けるべくこの記事では、設計書を修正する際に特に気を付けるべき点を、修正前・修正中・修正後の3つのフェーズに分けて調べた事をまとめてみました。
1. 修正前の確認事項
影響範囲の特定
一つの修正が、思わぬ箇所に影響を及ぼすことは少なくありません。
- 機能的な影響: 変更する機能が、他のどの機能から利用されているか、またはどの機能を利用しているかを確認します。
- 非機能的な影響: パフォーマンス、セキュリティ、可用性など、非機能要件への影響も考慮します。
- データ構造への影響: データベースのテーブル定義やAPIのレスポンス形式など、データ構造の変更が必要ないか確認します。
関連ドキュメントの確認
設計書は単一のドキュメントで完結しているとは限りません。
- 要件定義書: そもそも今回の修正が、本来の要求仕様から逸脱していないか確認します。
- 基本設計書・詳細設計書: 上位・下位の設計書間で矛盾が生じないように確認します。
- テスト仕様書: 修正に伴い、既存のテストケースの変更や、新たなテストケースの追加が必要になります。
- 運用マニュアル: 運用手順に変更がないか確認します。
関係者との合意形成
設計書の修正は、個人の判断で進めるべきではありません。
- プロジェクトマネージャー: スケジュールやコストへの影響を報告し、承認を得ます。
- 開発チーム: 実装担当者と修正内容の実現性や工数についてすり合わせを行います。
- 品質保証（QA）チーム: テストへの影響を共有し、レビューを依頼します。
- 顧客・ステークホルダー: 必要に応じて、仕様変更として正式な合意形成を行います。
2. 修正作業中のポイント
修正履歴の記録
「いつ、誰が、なぜ、何を修正したのか」を追跡できるようにすることは、非常に重要です。
- バージョン管理: Gitなどのバージョン管理システムで設計書を管理し、コミットメッセージに修正の意図を明確に記述します。
- 変更履歴欄: ドキュメント内に変更履歴のセクションを設け、日付、バージョン、変更内容、担当者を記録します。
明確かつ具体的な記述
設計書は、未来の自分や他のメンバーが読むことを常に意識して書く必要があります。
- 5W1Hを意識する: 「Why（なぜ変更するのか）」を特に重点的に記述します。
- 曖昧な表現を避ける: 「～かもしれない」「適宜対応する」といった曖昧な言葉は避け、具体的な仕様を記述します。
- 図や表の活用: シーケンス図、ER図、状態遷移図などを活用し、文章だけでは伝わりにくいシステムの振る舞いやデータ構造を視覚的に表現します。
3. 修正後のタスク
レビュー
セルフチェックだけでは、思い込みや見落としに気づけないことがあります。
- ピアレビュー: チーム内の他のメンバーにレビューを依頼し、客観的なフィードバックをもらいます。
- 有識者レビュー: 必要に応じて、技術領域の専門家やアーキテクトにレビューを依頼します。
関係者への周知
修正が完了したら、その旨を関係者全員に速やかに共有します。
- 情報共有: チャットツールや定例会議などで、変更点と最新ドキュメントの場所を周知します。これにより、「古い設計書を見て作業してしまった」という事態を防ぎます。
関連ドキュメントの更新
設計書の修正は、それ単体で終わりではありません。
- 整合性の確保: 修正前の確認で洗い出した、影響のある全ての関連ドキュメント（テスト仕様書、マニュアル等）を忘れずに更新し、情報の一貫性を保ちます。
おわりに
設計書は一度作ったら終わりではなく、システムの成長に合わせて継続的にメンテナンスしていく「生き物」だと思っています。子供みたいですね。
今回紹介したポイントを意識して、常に正確で最新の状態を保ち、チーム開発の羅針盤として設計書を最大限に活用して私も頑張っていこうと思います。
Discussion