ITエンジニアのための日本語技術文書作成法：仕様書・設計書・障害報告書

1. 概要（がいよう）— 概要
2. 目的（もくてき）— 目的
3. 対象範囲（たいしょうはんい）— 対象範囲
4. 機能仕様（きのうしよう）— 機能仕様
5. 非機能要件（ひきのうようけん）— 非機能要件
6. 制約事項（せいやくじこう）— 制約事項
7. 用語定義（ようごていぎ）— 用語定義

■ API仕様書

1. 概要
本書は、ユーザー管理APIの仕様を定義するものである。

（本書はユーザー管理APIの仕様を定義するものです。）

2. エンドポイント一覧

| No. | メソッド | パス | 概要 |
|-----|---------|------|------|
| 1 | GET | /api/v1/users | ユーザー一覧取得 |
| 2 | POST | /api/v1/users | ユーザー新規作成 |
| 3 | PUT | /api/v1/users/{id} | ユーザー情報更新 |
| 4 | DELETE | /api/v1/users/{id} | ユーザー削除 |

3. リクエスト仕様

3.1 ユーザー新規作成（POST /api/v1/users）

リクエストボディ:
| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| name | string | ○ | ユーザー名（最大50文字）|
| email | string | ○ | メールアドレス |
| role | string | × | 権限（デフォルト: "user"）|

4. レスポンス仕様

正常時（200 OK）:
| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | integer | ユーザーID |
| name | string | ユーザー名 |
| created_at | datetime | 作成日時（ISO 8601） |

異常時（400 Bad Request）:
| 項目名 | 型 | 説明 |
|--------|-----|------|
| error_code | string | エラーコード |
| message | string | エラーメッセージ |

～を定義する（ていぎする）— ～を定義する
～を実装する（じっそうする）— ～を実装する
～に準拠する（じゅんきょする）— ～に準拠する
～を考慮する（こうりょする）— ～を考慮する
～とする — ～とする（決定事項）
～ものとする — ～するものとする（規定）
～こと — ～すること（指示・要求）
～は任意とする — ～は任意とする（選択事項）

1. システム構成図（しすてむこうせいず）— システム構成図
2. ネットワーク構成（ねっとわーくこうせい）— ネットワーク構成
3. 画面一覧（がめんいちらん）— 画面一覧
4. 画面遷移図（がめんせんいず）— 画面遷移図
5. テーブル定義（テーブルていぎ）— テーブル定義
6. バッチ処理一覧（バッチしょりいちらん）— バッチ処理一覧
7. 外部インターフェース（がいぶインターフェース）— 外部インターフェース

■ テーブル名: users（ユーザー）

物理名: users
論理名: ユーザーマスタ
スキーマ: public
備考: ユーザー情報を管理するマスタテーブル

| No. | 物理名 | 論理名 | 型 | 桁数 | NOT NULL | PK | デフォルト | 備考 |
|-----|--------|--------|-----|------|----------|-----|----------|------|
| 1 | id | ユーザーID | BIGINT | - | ○ | ○ | AUTO | シーケンス |
| 2 | name | ユーザー名 | VARCHAR | 50 | ○ | | | |
| 3 | email | メールアドレス | VARCHAR | 255 | ○ | | | ユニーク制約 |
| 4 | status | ステータス | SMALLINT | - | ○ | | 1 | 1:有効 2:無効 |
| 5 | created_at | 作成日時 | TIMESTAMP | - | ○ | | CURRENT | |
| 6 | updated_at | 更新日時 | TIMESTAMP | - | ○ | | CURRENT | |
| 7 | deleted_at | 削除日時 | TIMESTAMP | - | | | NULL | 論理削除用 |

インデックス:
| No. | インデックス名 | カラム | ユニーク | 備考 |
|-----|---------------|--------|---------|------|
| 1 | idx_users_email | email | ○ | ログイン検索用 |
| 2 | idx_users_status | status, created_at | × | ステータス検索用 |

■ 障害報告書

報告日: 2026年3月3日
報告者: 金 英珠（きん えいじゅ）
障害番号: INC-2026-0303-001

1. 障害概要（しょうがいがいよう）
発生日時: 2026年3月2日 14:30 JST
復旧日時: 2026年3月2日 15:45 JST
影響範囲: 決済サービス全体（約5,000ユーザーに影響）
障害レベル: A（重大）

2. 事象（じしょう）
決済処理サービスにおいて、クレジットカード決済のリクエストが
タイムアウトエラー（HTTP 504）を返す事象が発生した。

（決済処理サービスにおいて、クレジットカード決済のリクエストが
タイムアウトエラー（HTTP 504）を返す事象が発生しました。）

3. 原因（げんいん）
データベースコネクションプールの枯渇が直接原因であった。
前日のバッチ処理で大量のトランザクションが発生し、
コネクションが正常に解放されなかったことが根本原因と判明した。

（データベースコネクションプールの枯渇が直接原因でした。
前日のバッチ処理で大量のトランザクションが発生し、
コネクションが正常に解放されなかったことが根本原因と判明しました。）

4. 対応内容（たいおうないよう）
(1) 14:35 監視アラートにより障害を検知
(2) 14:40 担当チームにエスカレーション
(3) 14:50 DBコネクションプールの状態を確認、枯渇を確認
(4) 15:00 コネクションプールの再起動を実施
(5) 15:15 サービス復旧を確認
(6) 15:45 全ユーザーへの影響解消を確認、復旧宣言

5. 再発防止策（さいはつぼうしさく）
(1) コネクションプールの最大数を100から200に変更（短期）
(2) コネクションリーク検知の監視強化（短期）
(3) バッチ処理のトランザクション管理の見直し（中期）
(4) 自動フェイルオーバー機構の導入（長期）

6. 横展開（よこてんかい）
他のマイクロサービスにおいても同様のコネクションプール設定を
確認し、必要に応じて見直しを実施する。

（他のマイクロサービスにおいても同様のコネクションプール設定を
確認し、必要に応じて見直しを実施します。）

～が発生した — ～が発生した
～と判明した — ～と判明した
～を確認した — ～を確認した
～を実施した — ～を実施した
～の恐れがある — ～の恐れがある
影響範囲は～に限定される — 影響範囲は～に限定される
根本原因（こんぽんげんいん）— 根本原因（root cause）
暫定対応（ざんていたいおう）— 暫定対応（workaround）
恒久対応（こうきゅうたいおう）— 恒久対応（permanent fix）
横展開（よこてんかい）— 横展開（他にも適用すること）

■ 議事録

会議名: 次期システム基盤 定例会議
日時: 2026年3月3日（火）10:00-11:00
場所: 第3会議室 / Teams
出席者: 田中PM、鈴木リーダー、金（記録）
欠席者: なし

■ 議題と決定事項

1. Kubernetes移行スケジュールについて
  【決定】4月第2週からステージング環境で検証開始
  【TODO】金：検証計画書を3/10までに作成

2. モニタリング基盤の選定
  【議論】Prometheus + Grafana vs Datadog
  - コスト面ではPrometheusが有利
  - 運用負荷はDatadogが低い
  【決定】次回会議までに両方のPoCを実施し比較

3. 次回予定
  日時: 2026年3月10日（火）10:00-11:00
  議題: PoC結果報告、移行計画レビュー

～です・ます調（丁寧語）が基本
（丁寧語のです・ます調が基本です）
「確認しました」「実施します」「報告いたします」

例：
「本件について、以下の通り報告いたします。」
（本件について、以下の通り報告いたします。）

より丁寧な敬語を使用
（より丁寧な敬語を使用します）
「ご確認いただけますでしょうか」
「ご不明な点がございましたら、お申し付けください」
「弊社にて調査を実施いたしました」

例：
「本障害につきまして、多大なるご迷惑をおかけしましたことを
深くお詫び申し上げます。」
（本障害について、大変ご迷惑をおかけしましたことを深くお詫び申し上げます。）

件名: 【報告】○○システム 障害対応完了のご報告

○○部 ○○様

お疲れ様です。
システム開発部の金です。

標記の件について、以下の通りご報告いたします。

■ 対応結果
・対応日時: 2026/3/3 14:00-15:00
・対応内容: DBコネクションプールの設定変更
・結果: 正常に動作していることを確認済み

■ 今後の対応
・詳細な原因分析を今週中に実施予定

ご不明な点がございましたら、お気軽にお問い合わせください。

以上、よろしくお願いいたします。