EXERCISE 90分

総合演習：プロジェクトドキュメント一式の作成

ストーリー

「いよいよ総合演習だ。これまで学んだことをすべて使ってドキュメントを作成してみよう」

「全部ですか？」

「README、議事録、週報、手順書、障害報告書。実際のプロジェクトで必要な文書を一通り作ってもらうよ」

「頑張ります！」

ミッション概要

これまで学んだドキュメンテーションスキルを総動員して、プロジェクトドキュメント一式を作成します。

Part内容目安時間
Part 1README作成15分
Part 2議事録作成20分
Part 3週報作成15分
Part 4手順書作成20分
Part 5障害報告書作成20分

達成条件

  • Part 1: READMEを作成できた
  • Part 2: 議事録を作成できた
  • Part 3: 週報を作成できた
  • Part 4: 手順書を作成できた
  • Part 5: 障害報告書を作成できた

前提：プロジェクト情報

架空のプロジェクト「ChatBot」を題材にします。

プロジェクト名: ChatBot
概要: 社内問い合わせに自動応答するチャットボット

技術スタック:
- バックエンド: Python 3.11 + FastAPI
- フロントエンド: React 18
- データベース: MongoDB
- AI: OpenAI API

チーム:
- PM: 山田
- バックエンド: 田中、佐藤
- フロントエンド: 鈴木、あなた

スプリント: 2週間
ツール: GitHub, Slack (#chatbot-dev), Jira

Part 1: README作成（15分）

タスク 1-1: README.mdを作成

以下の情報をもとに、ChatBotプロジェクトのREADMEを作成してください。

含めるべき内容:

  • プロジェクト名と概要
  • 機能一覧（質問への自動応答、FAQ管理、応答履歴の確認）
  • 動作要件（Python 3.11+, Node.js 18+, MongoDB 6+）
  • クイックスタート
  • 環境変数（OPENAI_API_KEY, MONGODB_URI, PORT）
<details> <summary>解答例</summary>
markdown
# ChatBot

社内問い合わせに自動応答するチャットボットアプリケーション。
OpenAI APIを活用し、自然な対話で社内の疑問を解決します。

## 機能

- 質問への自動応答（OpenAI API連携）
- FAQ管理（よくある質問の登録・編集）
- 応答履歴の確認（過去の対話ログ）

## 動作要件

- Python 3.11以上
- Node.js 18以上
- MongoDB 6以上

## クイックスタート

### 1. リポジトリをクローン

```bash
git clone https://github.com/example/chatbot.git
cd chatbot

2. バックエンドのセットアップ

bash
cd backend
pip install -r requirements.txt
cp .env.example .env
# .env を編集してAPIキーを設定

3. フロントエンドのセットアップ

bash
cd ../frontend
npm install

4. 起動

bash
# バックエンド（別ターミナル）
cd backend
uvicorn main:app --reload

# フロントエンド
cd frontend
npm run dev

ブラウザで http://localhost:3000 を開く

環境変数

変数名説明必須
OPENAI_API_KEYOpenAI APIキーYes
MONGODB_URIMongoDB接続URIYes
PORTサーバーポートNo（デフォルト: 8000）

ドキュメント

ライセンス

MIT License


</details>

---

## Part 2: 議事録作成（20分）

### シナリオ

以下の会議内容をもとに議事録を作成してください。

会議: ChatBot Sprint 3 プランニング 日時: 2025年4月21日 10:00-11:00 形式: Zoom 参加者: 山田PM、田中、佐藤、鈴木、あなた

議題:

  1. Sprint 2の振り返り
  2. Sprint 3のゴール設定
  3. タスク割り振り

議論内容:

[Sprint 2の振り返り] 田中: 「FAQ管理機能は完了しました。レスポンスタイムが少し遅いですが、最適化は次スプリントで対応します」 佐藤: 「OpenAI API連携は完了。ただし、トークン消費が想定より多いので監視が必要です」 鈴木: 「チャットUIは完成しました」 山田PM: 「全体的に順調ですね。レスポンスタイムとトークン消費は課題として記録しておきましょう」

[Sprint 3のゴール] 山田PM: 「Sprint 3のゴールは『応答履歴機能の実装とパフォーマンス改善』にしましょう」 全員: 了承

[タスク割り振り]

  • CHAT-201 応答履歴API: 田中（5ポイント）
  • CHAT-202 履歴画面UI: 鈴木（3ポイント）
  • CHAT-203 レスポンス最適化: 佐藤（5ポイント）
  • CHAT-204 E2Eテスト: あなた（3ポイント）

次回: 4月28日 10:00


### タスク 2-1: 議事録を作成

<details>
<summary>解答例</summary>

```markdown
# ChatBot Sprint 3 プランニング 議事録

## 基本情報

| 項目 | 内容 |
|------|------|
| 日時 | 2025-04-21 10:00 - 11:00 |
| 形式 | Zoom（リモート） |
| 参加者 | @山田PM, @田中, @佐藤, @鈴木, @私 |
| 記録者 | @私 |
| Slack | #chatbot-dev |

## アジェンダ

1. Sprint 2の振り返り
2. Sprint 3のゴール設定
3. タスク割り振り

## 議論内容

### 1. Sprint 2の振り返り

- @田中: FAQ管理機能は完了。レスポンスタイムが遅い点は次スプリントで最適化予定
- @佐藤: OpenAI API連携完了。トークン消費が想定より多いため監視が必要
- @鈴木: チャットUI完成
- @山田PM: 全体的に順調。レスポンスタイムとトークン消費を課題として記録

### 2. Sprint 3のゴール設定

- @山田PM: 「応答履歴機能の実装とパフォーマンス改善」を提案
- 全員了承

### 3. タスク割り振り

タスクと担当を決定（詳細は下記アクションアイテム参照）

## 決定事項

- [x] Sprint 3のゴール: **応答履歴機能の実装とパフォーマンス改善**
- [x] 各メンバーの担当タスクを決定
- [x] 合計ストーリーポイント: **16ポイント**

## アクションアイテム

| 担当 | 内容 | Jiraチケット | 期限 |
|------|------|-------------|------|
| @田中 | 応答履歴APIの実装 | CHAT-201 | 05/02 |
| @鈴木 | 履歴画面UIの実装 | CHAT-202 | 05/02 |
| @佐藤 | レスポンス最適化 | CHAT-203 | 05/02 |
| @私 | E2Eテストの作成 | CHAT-204 | 05/02 |

## 課題（継続監視）

| 課題 | 担当 | 対応 |
|------|------|------|
| レスポンスタイムの遅延 | @佐藤 | CHAT-203で対応 |
| トークン消費量 | @佐藤 | 監視体制を整備 |

## 次回予定

- 日時: 2025-04-28 10:00
- 議題: Sprint 3 中間レビュー

---
*この議事録は #chatbot-dev に共有済み*
</details>

Part 3: 週報作成（15分）

シナリオ

以下の状況で週報を作成してください。

週: 2025年5月5日週（Sprint 3の2週目）

今週やったこと:
- CHAT-204 E2Eテスト: 完了（3ポイント）
- CHAT-210 ドキュメント整備: 完了（2ポイント）
- CHAT-211 バグ修正（履歴表示の文字化け）: 完了（1ポイント）

来週の予定:
- Sprint 4のタスク着手
- 結合テストの実施

課題:
- E2Eテストの実行時間が長い（10分以上）。並列実行を検討中。

KPT:
- Keep: テストコードの品質が上がってきた
- Problem: テスト実行時間が長くなってきた
- Try: テストの並列実行を導入する

所感:
E2Eテストを書くことで、UI変更時のデグレを早期発見できるようになった。
テスト実行時間の課題はあるが、品質向上への投資として価値があると感じた。

タスク 3-1: 週報を作成

<details> <summary>解答例</summary>
markdown
# 週報: 2025/05/05週

## スプリント情報

- スプリント: Sprint 3（2週目/2週）
- ゴール: 応答履歴機能の実装とパフォーマンス改善

## 今週の成果

### 完了したタスク

| Jiraチケット | タスク名 | ストーリーポイント |
|-------------|---------|------------------|
| CHAT-204 | E2Eテスト作成 | 3 |
| CHAT-210 | ドキュメント整備 | 2 |
| CHAT-211 | バグ修正（履歴表示の文字化け） | 1 |

### 進行中のタスク

なし

## 来週の予定

| 優先度 | タスク | 見積もり |
|--------|--------|---------|
| 高 | Sprint 4のタスク着手 | - |
| 高 | 結合テストの実施 | 1日 |

## 課題・リスク

| 課題 | 影響 | 対応状況 |
|------|------|---------|
| E2Eテストの実行時間が長い（10分以上） | CI/CDパイプラインが遅くなる | 並列実行を検討中 |

## KPT

### Keep（続けたいこと）
- テストコードの品質が上がってきた

### Problem（問題点）
- テスト実行時間が長くなってきた

### Try（次に試したいこと）
- テストの並列実行を導入する

## 所感

E2Eテストを書くことで、UI変更時のデグレを早期発見できるようになった。
テスト実行時間の課題はあるが、品質向上への投資として価値があると感じた。
来週は並列実行の導入にも着手したい。

---
*提出先: #chatbot-dev-weekly*
</details>

Part 4: 手順書作成（20分）

タスク 4-1: ローカル開発環境セットアップ手順書を作成

ChatBotプロジェクトの開発環境セットアップ手順書を作成してください。

含めるべき内容:

  • 概要、前提条件、作業時間の目安
  • バックエンド・フロントエンドのセットアップ手順
  • 各ステップの確認ポイント
  • トラブルシューティング（2つ以上）
<details> <summary>解答例</summary>
markdown
# ChatBot 開発環境セットアップ手順書

## 概要

ChatBotの開発環境をローカルマシンにセットアップするための手順です。

## 前提条件

- Python 3.11以上（確認: `python --version`）
- Node.js 18以上（確認: `node --version`）
- MongoDB 6以上（確認: `mongod --version`）
- Git（確認: `git --version`）
- OpenAI APIキーを取得済み

## 作業時間の目安

約20分

## 手順

### 1. リポジトリをクローンする

```bash
git clone https://github.com/example/chatbot.git
cd chatbot

【確認】chatbotディレクトリが作成されていること

2. バックエンドをセットアップする

bash
cd backend
pip install -r requirements.txt

【確認】エラーなく完了すること

3. バックエンドの環境変数を設定する

bash
cp .env.example .env

.envを編集:

OPENAI_API_KEY=your-api-key-here
MONGODB_URI=mongodb://localhost:27017/chatbot
PORT=8000

【確認】.envファイルが作成され、値が設定されていること

4. MongoDBを起動する

bash
mongod --dbpath /data/db

【確認】「waiting for connections」と表示されること

5. バックエンドを起動する

bash
uvicorn main:app --reload

【確認】以下が表示されること

Uvicorn running on http://127.0.0.1:8000

6. フロントエンドをセットアップする（別ターミナル）

bash
cd frontend
npm install

【確認】エラーなく完了すること

7. フロントエンドを起動する

bash
npm run dev

【確認】以下が表示されること

Local: http://localhost:3000

8. 動作確認する

ブラウザで http://localhost:3000 を開く

【確認】ChatBotの画面が表示され、メッセージを送信できること

完了確認

  • バックエンドが起動している（http://localhost:8000/docs でAPI仕様が見れる）
  • フロントエンドが起動している
  • ブラウザでチャットができる

トラブルシューティング

pip install でエラーが出る

症状: error: externally-managed-environment

対処:

bash
python -m venv venv
source venv/bin/activate  # Windowsは venv\Scripts\activate
pip install -r requirements.txt

MongoDBに接続できない

症状: Connection refused

対処:

  1. MongoDBが起動しているか確認
  2. .envのMONGODB_URIが正しいか確認
  3. ポート27017が他で使われていないか確認

OpenAI APIエラー

症状: Invalid API key

対処:

  1. .envのOPENAI_API_KEYが正しいか確認
  2. APIキーに余分な空白や改行がないか確認

</details>

---

## Part 5: 障害報告書作成（20分）

### シナリオ

以下の障害が発生しました。障害報告書を作成してください。

発生日時: 2025年5月6日 14:30 復旧日時: 2025年5月6日 15:15 影響範囲: 本番環境のChatBot全機能

タイムライン:

  • 14:30 ユーザーから「応答が返ってこない」との報告
  • 14:35 調査開始、エラーログを確認
  • 14:40 OpenAI APIからのレスポンスがタイムアウトしていることを確認
  • 14:50 OpenAIのステータスページを確認、API障害が発生中と判明
  • 15:00 OpenAI側の障害が復旧
  • 15:15 全機能の正常動作を確認、障害クローズ

原因:

  • 直接原因: OpenAI APIの障害
  • 根本原因: 外部API障害時のフォールバック処理がなかった

対応:

  • OpenAI側の復旧を待った（外部障害のため）

再発防止策:

  • API障害時のフォールバック処理を実装する（担当: 佐藤、期限: 5/13）
  • 外部API障害時のユーザー通知機能を追加する（担当: 鈴木、期限: 5/13）
  • 監視アラートを設定する（担当: 田中、期限: 5/9）

### タスク 5-1: 障害報告書を作成

<details>
<summary>解答例</summary>

```markdown
# 障害報告書

## 概要

| 項目 | 内容 |
|------|------|
| 発生日時 | 2025-05-06 14:30 |
| 復旧日時 | 2025-05-06 15:15 |
| 影響時間 | 45分 |
| 影響範囲 | 本番環境のChatBot全機能 |
| 重大度 | 高（サービス全停止） |

## 概要（1-2文で）

外部サービス（OpenAI API）の障害により、ChatBotの応答機能が約45分間停止した。

## タイムライン

| 時刻 | 事象 |
|------|------|
| 14:30 | ユーザーから「応答が返ってこない」との報告を受信 |
| 14:35 | 調査開始、サーバーログを確認 |
| 14:40 | OpenAI APIからのレスポンスがタイムアウトしていることを確認 |
| 14:50 | OpenAIステータスページで障害発生中を確認 |
| 15:00 | OpenAI側の障害が復旧 |
| 15:15 | 全機能の正常動作を確認、障害クローズ |

## 原因

### 直接原因

OpenAI APIの障害により、APIリクエストがタイムアウトした。

### 根本原因

- 外部API障害時のフォールバック処理が実装されていなかった
- ユーザーへの障害通知機能がなかった
- 外部API障害の監視・アラートが設定されていなかった

## 対応内容

1. エラーログとOpenAIステータスページで原因を特定
2. 外部障害のため、OpenAI側の復旧を待機
3. 復旧後、全機能の動作確認を実施

## 影響

- 約45分間、ChatBotの応答機能が使用不可
- 約50件の問い合わせが未応答

## 再発防止策

| 対策 | 担当 | 期限 | Jiraチケット |
|------|------|------|-------------|
| API障害時のフォールバック処理を実装（キャッシュ応答） | @佐藤 | 2025-05-13 | CHAT-301 |
| 外部API障害時のユーザー通知機能を追加 | @鈴木 | 2025-05-13 | CHAT-302 |
| 外部API監視とSlackアラートを設定 | @田中 | 2025-05-09 | CHAT-303 |

## 教訓

- 外部APIへの依存は、障害時のリスクを伴う
- フォールバック処理と監視は事前に準備すべき
- 障害時のユーザーコミュニケーションも重要

---
*報告者: @私*
*報告日: 2025-05-06*
</details>

達成度チェック

以下を確認してください：

  • Part 1: READMEを作成できた
  • Part 2: 議事録を作成できた
  • Part 3: 週報を作成できた
  • Part 4: 手順書を作成できた
  • Part 5: 障害報告書を作成できた

まとめ

この総合演習で作成したドキュメント：

Partドキュメントポイント
Part 1READMEプロジェクトの顔、クイックスタート
Part 2議事録決定事項、アクションアイテム
Part 3週報成果、課題、KPT
Part 4手順書具体的な手順、確認ポイント、トラブルシューティング
Part 5障害報告書タイムライン、原因分析、再発防止策

総合演習の振り返り

Q: 最も難しかったPartは？
A:

Q: 新たに学んだことは？
A:

Q: 実際の業務で活かせそうなことは？
A:

次のステップへ

おめでとうございます！総合演習を完了しました。

次のセクションでは、このミッション全体の理解度を確認する「卒業クイズ」に挑戦します。 合格すると「ドキュメンテーション基礎 修了証明書」が発行されます。

推定所要時間: 90分