【授業レポート】システム開発入門 第30週目 〜改善の恒常化とドキュメンテーション〜
第30週目は、29週目までに行ってきた改善の「運用への定着」と、成果を継続的に残すための**ドキュメンテーション（手順書・変更履歴・監視設計）**に取り組みました。作って終わりにせず、チームや後任が扱える形にすることがテーマです。
■ 先生の導入：「知識はコードだけじゃ残らない。手順と記録が命です」
田中先生：「改善を一度やるだけで終わらせないために、手順を書き、担当を決め、効果を測る仕組みを作ることが重要です。今日作るのは“未来の自分”や“次に入る人”のための設計図です。」
■ 今日のゴール
- 改善を運用に落とし込むための**チェックリスト（Runbook）**を作る。
- 変更履歴（Changelog）の書き方とテンプレートを整備する。
- 監視・アラートの指標（SLO/KPI）を決め、簡易ダッシュボード案を作る。
- インシデント時の初動フロー（簡易プレイブック）を作成する。
■ 実習①：Runbook（運用手順書）を作る
生徒たちは班ごとに、自分たちが行った改善（例：キャッシュTTL延長・入力サニタイズ・フォールバック調整）を誰でも実行できる手順に落とし込みました。Runbookに含めた主な項目：
- 目的（何を期待する改善か）
- 適用環境（テスト / ステージ / 本番）
- 前提条件（必要な環境変数・権限・依存サービス）
- 実行手順（コマンドやファイル差分の貼り付け）
- 巻き戻し手順（ロールバック方法）
- 動作確認チェックリスト（確認するKPIやログの確認方法）
- 実行者・承認者・実施日時の記録欄
Runbook の短い例（抜粋）
目的：キャッシュTTLを300→900に変更し、ピーク時の応答改善を図る
前提：config/cache_config.pyへの書き込み権限
手順：
1. ステージ環境で config/cache_config.py の TTL = 300 を 900 に変更
2. サービスを再起動： systemctl restart myapp
3. 10分間の負荷テストを実行（スクリプト名：load_test.py）
確認：
- 平均応答時間が前回より改善していること
- エラー率（status != ok）が上昇していないこと
ロールバック：
- TTLを元の300に戻し、サービス再起動
■ 実習②：Changelog（変更履歴）テンプレート作成
変更を簡潔に残すためのテンプレートを作成。記録は後から問題の原因追跡や評価に直結します。
Changelog エントリ例
- 日付：2025-10-01
- 変更者：山田（チームA）
- 変更概要：キャッシュTTLを300→900に延長
- 目的：ピーク時の応答改善（平均応答時間短縮）
- 影響範囲：APIレスポンス（全ユーザー）
- 実施環境：staging→production（順次適用）
- 結果：平均応答時間 -15%（負荷テスト）、問題なし（運用確認）
- 参照：runbooks/cache_ttl_update.md
■ 実習③：監視設計とダッシュボード案
改善を継続的に見るための監視指標（KPI/SLO）を決め、簡易ダッシュボード項目を設計しました。
推奨KPI（例）
- 平均応答時間（avg latency, ms）
- 95パーセンタイル応答時間（p95, ms）
- 成功率（status == ok の割合）
- フォールバック発生率（fallback / total）
- 再生成要求率（ユーザーが再生成を押した割合）
班ごとに「閾値」と「アラート条件」も決定：
- 例：p95 > 2000ms が 5分間継続 → Slack にアラート
- 例：成功率 < 95% → 当番にメール
ダッシュボードは授業では簡易案としてテーブル＋時系列グラフを描く形で共有しました。
■ 実習④：インシデント初動プレイブック（簡易）
万が一問題が起きたときに早く復旧するための「初動フロー」を作成。
初動フロー（サマリ）
- 事象検知（監視アラート受信）
- 影響範囲の確認（どのエンドポイント・ユーザーか）
- 一時対応（トラフィックを切り分ける／フォールバックを有効化）
- 根本原因のログ収集（該当時間帯のログ抽出）
- エスカレーション（担当者に連絡、必要なら先生を介して運用側へ報告）
- 復旧後の振り返り（Root Cause Analysis）とChangelog記載
■ ドキュメント文化の大切さ（ディスカッション）
授業の最後には、ドキュメントの運用ルールについて議論しました。
- ドキュメントは「書くだけ」で終わらせず、更新のフローと責任者を決めること。
- 変更は必ず Changelog に残す（自動化できる箇所は自動化）。
- Runbook は「読む人が再現できること」が最重要。箇条書き＋コマンド例で具体化する。
- 名前付け・ファイル配置（例：docs/runbooks/, docs/changelog.md）の統一。
生徒の気づき：「誰が次に見るかを想像して書くと、丁寧になるね！」
■ 先生のひとこと
「技術だけでなく“伝える仕組み”を作ることが、チームで成果を出す秘訣です。今日作ったRunbookやChangelogは、次の誰かの仕事を格段に楽にします。小さな習慣が大きな信頼に繋がりますよ。」
■ 来週の予告：学期の総まとめと2年生領域のイントロダクション
次週は学期の総まとめ（振り返りシートの提出・ポートフォリオ整理）と、来学期に控える**システム設計（UML・DB設計・アーキテクチャ）**のイントロダクションを行います。2年次の学びに向けて、期待を高めていきます！
第30週目を終え、1年生たちは「作る」だけでなく「運用して伝える」力を身につけました。小さな改善を恒常化する仕組みは、これからの開発活動の大きな武器になります。お疲れさまでした！