自治体向け詳細設計書の書き方・作り方

行政AIヤマトにおいては「DX・情報」の「自治体システム書類作成」のボタンで、この仕様の通り、AI出力できます。

はじめに　要約と結論

自治体向け詳細設計書は、基本設計で合意した業務・機能・非機能を、開発者、設定担当、試験担当、運用担当が同じ解釈で実装できる粒度へ変換する文書です。画面やAPIの項目だけでなく、入力制御、権限、データ更新、例外処理、ログ、監視、性能、バックアップ、外部連携、運用手順との境界を具体化します。

結論は、すべての詳細設計項目に一意なIDを付け、要件、基本設計、ソースまたは設定、試験、運用手順へ追跡できるようにすることです。よい自治体向け詳細設計書は、担当者の暗黙知を減らし、異常系と境界値を先に示し、個人情報や権限をデータ項目単位で守り、変更時の影響範囲を短時間で特定できます。

想定読者

想定読者は、自治体の業務主管課、情報政策部門、情報セキュリティ担当、設計審査者、受託事業者のアプリケーション・基盤・ネットワーク・データベース・運用担当、開発者、試験担当、移行担当、保守担当です。業務担当者は業務規則と表示内容を、技術担当者は処理・データ・例外を、運用担当者は監視・復旧・証跡を確認します。

1　自治体向け詳細設計書の章立て

1. 文書情報、承認、改訂履歴
2. 目的、対象範囲、対象外、前提条件
3. 適用する要件、基本設計、標準、用語
4. システム・コンポーネント構成
5. 画面詳細設計
6. 帳票・通知詳細設計
7. API・外部インターフェース詳細設計
8. バッチ・ジョブ・スケジュール詳細設計
9. データベース・ファイル詳細設計
10. 認証・認可・セキュリティ詳細設計
11. ログ・監視・監査証跡詳細設計
12. 性能・可用性・バックアップ詳細設計
13. エラー・例外・再処理・縮退設計
14. パラメータ、環境差分、構築・リリース
15. トレーサビリティ、未決事項、レビュー記録

一冊が大きすぎる場合は、画面、API、DB、バッチなどへ分冊します。ただし、文書番号、共通ID体系、用語、更新ルール、関連表の正本を統一します。

2　書き方・作り方の手順

2.1　入力文書を確定する

要件定義書、基本設計書、業務フロー、データ一覧、システム構成図、セキュリティ要件、移行・運用条件、契約仕様を列挙し、適用版を固定します。最新版という表現だけでなく、文書番号と版を記載します。矛盾や未決事項は推測で埋めず、課題IDを起票します。

2.2　設計単位とIDを決める

画面はSCR、APIはAPI、バッチはBAT、テーブルはTBL、帳票はRPT、メッセージはMSGなど、種別が分かるIDにします。要件REQ-xxx、基本設計BD-xxx、詳細設計DD-xxx、試験TC-xxxの対応を追跡表にします。

2.4　処理を入力・判定・更新・出力に分解する

各機能について、入力元、事前条件、処理手順、判定条件、更新対象、出力、事後条件、例外、ログを記述します。文章だけでなく、決定表、状態遷移、項目定義、疑似コードを使い分けます。ただし実装言語のコードを大量に貼り付けず、設計意図と契約を示します。

2.5　横断設計を適用する

認証、認可、監査ログ、エラー、時刻、文字コード、暗号化、秘密情報、共通部品、アクセシビリティ、命名、コーディング規約を横断設計として定めます。個別設計が横断設計から外れる場合は、例外理由と承認を残します。

2.6　試験可能性を確認する

各判定、状態、エラー、権限に試験観点を対応させます。「適切に処理する」「必要に応じて表示」のような検証不能表現を排除します。入力値、期待結果、ログ、データ更新、外部送信を観測できる設計にします。

3　画面詳細設計の書き方

画面ごとに、画面ID、名称、目的、利用者、表示条件、遷移元・先、ワイヤーフレーム、項目一覧、操作一覧、入力検証、権限制御、メッセージ、アクセシビリティ、ログ、タイムアウトを記載します。

画面項目定義テンプレート

自治体向け画面では、読み上げ、キーボード操作、焦点順序、ラベル関連付け、色だけに頼らない表示、エラー位置、拡大時の操作性を確認します。対応すべきアクセシビリティ基準や対象範囲は、案件の調達仕様と基準日時点の公式規格・指針を確認します。

確認画面ではマスキングと完全表示の使い分け、戻る操作時の値保持、二重送信防止、セッション切れ、添付ファイルの検証を設計します。職員画面では検索条件の権限、CSV出力、印刷、職権操作、操作理由の入力、監査ログを重視します。

4　帳票・通知詳細設計

帳票には、帳票ID、用途、出力契機、対象者、元データ、レイアウト、ページ制御、再発行、保管、アクセス権を記載し、長い氏名・住所、外字、複数ページ、PDF表示等を確認します。通知には、チャネル、宛先、テンプレート、差込項目、契機、抑止、再送、失敗時対応、URL期限を設計し、メール本文へ機微情報を直接記載しません。

5　API・外部インターフェース詳細設計

APIごとに、API ID、提供者・利用者、エンドポイント、メソッド、認証・認可、要求・応答スキーマ、必須、型、桁、コード、エラー、タイムアウト、再試行、レート制限、冪等性、バージョン、ログを記載します。

API ID: API-021 申請登録
事前条件: 利用者認証済み、下書き状態
要求: requestId、applicant、applicationItems、attachments
処理: 権限確認→スキーマ検証→業務検証→重複確認→登録→監査記録
成功: 201、applicationId、acceptedAt
競合: 409、同じrequestIdの既登録結果を返却
業務エラー: 422、項目ID付きエラー配列
障害: 500、内部情報を含まない受付番号付きメッセージ
ログ: requestId、主体ID、結果、処理時間。本文・添付内容は原則記録しない

ファイル連携では、ファイル名、文字コード、改行、区切り、ヘッダー、項目順、桁、圧縮、暗号化、署名、授受場所、受渡時刻、完了ファイル、重複、再送、保管、削除を定義します。相手先障害時の滞留上限と手動再処理も必要です。

6　バッチ・ジョブ詳細設計

バッチには、バッチID、目的、起動方式、予定時刻、営業日・休日、依存ジョブ、入力、処理単位、コミット単位、並列数、出力、終了コード、再実行、途中再開、排他、監視、想定件数、制限時間を記載します。

日次、月次、年度切替は、自治体の閉庁日や繁忙期、外部連携先の運用時間と整合させます。失敗時に最初から再実行するのか、チェックポイントから再開するのか、重複更新が起きないかを設計します。手動実行権限と操作ログ、誤実行防止も定義します。

7　データベース・ファイル詳細設計

テーブル定義には、論理・物理名、目的、主キー、外部キー、列、型、桁、NULL、初期値、コード体系、制約、索引、更新主体、履歴、保持・削除、個人情報区分を記載します。

データ項目テンプレート

論理削除と物理削除、履歴、訂正、監査証跡を区別します。個人情報は収集目的に必要な最小限とし、暗号化、マスキング、検索、バックアップ、削除まで一貫して設計します。データ保存期間は技術者だけで決めず、文書管理、業務、法務・個人情報担当が、適用される規程・法令等の最新版を確認して決定します。

8　認証・認可・セキュリティ詳細設計

認証方式、セッション、タイムアウト、再認証、多要素認証、パスワードを扱う場合の方針、アカウントロック、退職・異動時処理を定義します。認可は画面表示だけでなく、API、データ行、操作、ファイル出力、管理機能でサーバー側に適用します。

権限マトリクス例です。

入力検証、出力エスケープ、CSRF等のWeb対策、アップロード検証、外向き通信制限、秘密情報管理、依存部品、脆弱性対応を設計します。具体的な方式・版・設定値は、利用技術の公式文書、自治体の情報セキュリティポリシー、基準日時点の政府等の最新ガイドラインを確認します。

9　ログ・監視・監査証跡設計

ログ種別を、アプリケーション、アクセス、監査、セキュリティ、ジョブ、外部連携、基盤に分けます。各ログについて、出力イベント、必須項目、時刻、主体、相関ID、結果、保存先、保存期間、閲覧権限、マスキング、改変防止、監視条件を記載します。

監査ログは、誰が、いつ、何を、どの対象へ行い、結果がどうだったかを追跡できるようにします。一方、パスワード、認証トークン、秘密鍵、申請本文、添付内容などを安易に記録してはいけません。障害調査用ログと監査証跡は目的、閲覧者、保持期間が異なるため分けます。

監視は、死活、性能、容量、エラー率、連携滞留、証明書期限、バックアップ、セキュリティイベントを対象にし、閾値、継続時間、通知先、抑止、一次対応、エスカレーションを定義します。

10　性能・可用性・バックアップ設計

性能は、対象処理、同時利用、データ量、応答時間、時間帯、測定点を数値化し、ピークと外部API待ち、バッチ完了時刻も考慮します。可用性は、冗長化対象、切替条件、検知、同期、復帰を記載します。バックアップは、対象、頻度、保存先、世代、暗号化、隔離、復元試験を定義し、要求された復旧時間・復旧時点と対応付けます。

11　エラー・例外・状態遷移設計

エラーを入力、業務、認証・権限、外部連携、システム、運用へ分類し、利用者表示、内部コード、HTTP等の結果、ログ、監視、再試行、問い合わせ番号を対応付けます。内部構造や機微情報を利用者へ表示しません。

状態遷移表は、現在状態、イベント、条件、次状態、更新者、通知、監査ログを記載します。

並行更新では、先に更新された内容を後の保存が黙って上書きしない設計にします。タイムアウト後の結果不明、通知送信成功後のDB失敗など、分散処理の部分成功も扱います。

12　自治体特有の重要事項

制度改正と施行日

制度・条例・様式の改定には公布、施行、経過措置、受付日、決定日など複数の日付があります。単一の「適用日」で済ませず、判定基準日を業務担当と合意し、将来日設定や過去分再計算を設計します。

標準化と既存業務

国の標準仕様、自治体の共通基盤、文字・コード体系、連携仕様が適用される場合は、対象版と差分を管理します。「標準準拠」を宣言するだけでなく、該当設計IDと試験証跡を示します。最新の適用範囲・移行方針は公式情報と当該自治体の方針を確認します。

窓口・代理・職権処理

本人のオンライン操作だけでなく、窓口支援、代理人、法定代理、職員による補正、郵送取込、DV等への配慮を含む閲覧制限など、業務上必要な例外を確認します。具体的な対象と取扱いは担当課の正式判断に基づきます。

13　禁止事項

1. 要件・基本設計と対応しない機能を独断で追加すること。
2. 未決事項を推測で確定値として記載すること。
3. 「適切に」「必要に応じて」「通常どおり」だけで処理を説明すること。
4. 正常系だけを書き、権限エラー、外部停止、重複、再処理を省くこと。
5. 画面でボタンを隠すだけで認可したとみなすこと。
6. パスワード、秘密鍵、トークン、実データを設計書へ記載すること。
7. ログへ機微情報を無制限に出力する設計にすること。
8. 本番データを無断で開発・試験へ複製すること。
9. DB項目、API項目、画面項目で型・桁・コードを不一致にすること。
10. 設計変更後に試験、パラメータ、運用手順を更新しないこと。
11. 法令、条例、標準、ガイドラインの版を確認せず準拠を断定すること。

14　詳細設計の具体的な記入例

業務判定を決定表で書く例

文章だけで複数条件を説明すると、実装者と試験者の解釈が分かれます。例えば申請の編集可否は、利用者、申請状態、受付期間、代理権限を条件として決定表にします。

各規則IDを単体試験へ対応させます。条件が重複する場合の優先順位、どの日時を基準に受付期間を判定するか、操作中に期限を越えた場合の扱いも記載します。

排他制御の記入例

職員二人が同じ申請を開いた場合、後から保存した内容で先の更新を無言で上書きしないよう、更新版番号を使用します。保存要求に画面表示時の版番号を含め、DB上の現行版と一致した場合だけ更新します。不一致なら、再読込みを促し、入力内容を失わない方法を示します。職権修正では、修正前後、理由、実施者、承認者、日時を監査履歴へ残します。

外部連携失敗の記入例

外部通知APIへの要求がタイムアウトした場合、相手側で処理済みか未処理か判別できないことがあります。要求ごとに一意な冪等キーを付け、同じキーの再送が二重通知を生まない契約を定めます。結果不明は「失敗」と同一視せず、照会APIまたは配信結果ファイルで確定します。再試行回数を超えたデータは保留キューへ移し、運用画面で個別再処理できるようにします。再処理者、理由、結果は監査ログへ残します。

個人情報を含むCSV出力の記入例

CSV出力には、利用できる役割、対象範囲、最大件数、項目、文字コード、ファイル名、出力理由、承認要否を定義します。出力要求と完了・ダウンロードをログに記録し、短い有効期限後にサーバー上の一時ファイルを削除します。表計算ソフトで数式として解釈される文字列への対策も検討します。全件出力を標準にせず、業務目的に必要な項目と期間へ絞ります。

日付・年度境界の記入例

「当日」「年度」をサーバーの現在時刻だけで判断しません。基準タイムゾーン、業務日付、締切時刻、休日、うるう日、年度末、遡及処理を定義します。予約処理では、登録日、適用日、施行日を分けます。制度改正が将来施行される場合は、ルールの有効開始・終了をデータで管理し、リリース日と施行日を混同しない設計にします。

レビュー指摘の例

「入力チェックあり」とだけ記載された設計には、必須、型、桁、文字、範囲、相関、DB・外部照合のどれを、クライアントとサーバーのどこで行うかを確認します。「管理者のみ」には、管理者ロールの付与者、承認、定期棚卸し、緊急権限、操作ログを確認します。「エラー時はロールバック」には、複数サービスや外部送信を含む処理で何が戻り、何が戻らないかを確認します。

設計完了判定会議の進め方

会議前に、未決事項、重大指摘、要件未対応、例外設計なし、試験不能表現を自動または目視で抽出します。会議では文書を最初から読み上げず、業務リスクの高い状態遷移、個人情報、権限、外部連携、復旧を重点確認します。条件付き承認の場合は、条件、責任者、期限、再確認者を記録し、条件解消前に実装・リリースしてよい範囲を明確にします。

15　実務チェックリスト

トレーサビリティ

• [ ] 各設計に一意IDがある
• [ ] 要件、基本設計、実装、設定、試験との対応がある
• [ ] 適用文書の文書番号と版が確定している
• [ ] 未決事項は課題管理され、推測で埋めていない

機能・データ

• [ ] 正常、境界、異常、権限、並行更新を設計した
• [ ] 項目の型、桁、必須、コード、保存先が一致する
• [ ] 状態遷移と禁止遷移が明確である
• [ ] 外部連携の再送、重複排除、結果不明を扱う
• [ ] 保持、訂正、削除、監査履歴を定義した

セキュリティ・運用

• [ ] API・サーバー側で認可する
• [ ] 個人情報、秘密情報、ログの扱いが明確である
• [ ] 監視閾値、通知、一次対応、再処理がある
• [ ] バックアップと復元試験が設計されている
• [ ] 管理・保守操作に承認と監査証跡がある

レビュー・納品

• [ ] 業務、開発、基盤、セキュリティ、試験、運用がレビューした
• [ ] 指摘と対応、再確認、承認の履歴がある
• [ ] 図表、疑似コード、一覧で矛盾がない
• [ ] 編集可能形式と関連する定義ファイルを納品できる
• [ ] 実装完了時の設計書が実環境と一致している

16　FAQ　自治体向け詳細設計書の作り方

Q1　基本設計書と詳細設計書の違いは何ですか

基本設計は利用者・業務・システム外部から見た仕様と全体方針を主に示し、詳細設計は内部処理、データ、例外、設定を実装可能な粒度へ落とします。境界は契約と開発方式に合わせて定義します。

Q2　アジャイル開発でも詳細設計書は必要ですか

必要な設計情報は開発方式にかかわらず必要です。一冊の固定文書にせず、API定義、スキーマ、決定記録、受入条件などを反復的に更新できます。ただし正本、版、承認、納品方法を合意します。

Q3　ソースコードがあれば詳細設計書は不要ですか

不要にはなりません。コードだけでは業務根拠、権限、例外方針、運用意図、外部契約、変更理由を読み取れないためです。自動生成資料を活用しても、設計意図と追跡情報を残します。

Q4　画面キャプチャだけで画面設計になりますか

なりません。項目定義、入力制約、権限、エラー、遷移、保存先、アクセシビリティが必要です。キャプチャは見た目の補足として使います。

Q5　エラーメッセージはどこまで設計しますか

利用者が次に取る行動を理解できる文面、表示位置、項目との関連、問い合わせ番号を設計します。内部情報は隠し、内部コード、ログ、監視、運用手順と対応付けます。

Q6　詳細設計レビューへ自治体職員は参加すべきですか

全実装詳細の確認は不要でも、業務規則、表示、帳票、権限、状態遷移、保存、監査、例外運用は確認が必要です。技術部分は専門担当が結果を説明します。

Q7　設計値は詳細設計書とパラメータシートのどちらに書きますか

設計書には値の意味、決定根拠、制約を、パラメータシートには環境ごとの実値と適用証跡を記載します。設計IDとパラメータIDで相互参照します。

Q8　個人情報項目はどう管理しますか

データ項目単位で目的、取得元、利用者、保存先、連携先、保持、削除、マスキングを追跡します。具体的な適法性や保存期間は、案件に適用される最新の法令・条例・規程を担当部門と確認します。

Q9　変更時にどこまで再レビューしますか

変更対象だけでなく、関連要件、呼出元・先、データ、権限、性能、試験、運用、移行への影響を確認します。影響分析の範囲と承認者を変更管理票に残します。

Q10　完成判定は何ですか

未決事項が解消または正式管理され、レビュー指摘が閉じ、実装・設定・試験と一致し、自治体と受託者の定めた承認を得た状態です。単に章が埋まったことを完成としません。

まとめ

自治体向け詳細設計書の書き方で重要なのは、実装を細かく説明する量ではなく、業務ルール、データ、権限、例外、運用を一貫したIDで結び、検証できることです。自治体向け詳細設計書を要件・基本設計・パラメータ・試験・運用へつなげ、曖昧語と暗黙知を排除すれば、安全で保守可能な自治体システムの基盤になります。