はじめに
「ニュースを鵜呑みにせず、背景・文脈・複数の視点を届けるラジオを作りたい」
そんな思いから、ニュースの自動収集からファクトチェック、クリティカル分析、台本生成、音声合成、動画化まで一気通貫で行う Web アプリケーション AI News Radio を開発しています。
このプロジェクトの特徴は、企画・設計から実装・運用まで、ほぼすべてを Claude Code で行っていることです。
本記事では、以下の3つの観点からこのプロジェクトを紹介します。
- Starter Prompt から始めるプロジェクト立ち上げ — CLAUDE.md を書いて、Phase ごとにアプリを組み立てる
-
Claude Code によるセットアップ体験 —
claude→ 「セットアップして」で環境構築が完了する世界 - OSS コラボ開発 — Issue 起票から実装・レビュー・マージまで Claude Code で完結する開発フロー
AI News Radio の概要
AI News Radio は、7ステップのパイプラインでニュース番組を自動生成するアプリケーションです。
[1.収集] → ✅ → [2.ファクトチェック] → ✅ → [3.分析] → ✅ → [4.台本] → ✅ → [5.音声] → ✅ → [6.動画] → ✅ → [7.素材準備]
各 ✅ はヒューマン承認ゲート。AIが生成した結果を人間が確認・承認してから次のステップに進む設計です。最終ステップでは YouTube 投稿用の動画・音声・メタデータ（タイトル・概要・タグ・タイムスタンプ）を素材として出力します。
技術スタック
| レイヤー | 技術 |
|---|---|
| Backend | Python 3.12 + FastAPI |
| Frontend | React 19 (Vite) + TypeScript + Tailwind CSS |
| Database | PostgreSQL 16 + SQLAlchemy (async) + Alembic |
| Queue | Celery + Redis |
| AI | Anthropic Claude / OpenAI / Google Gemini（切り替え可能） |
| TTS | Google Cloud TTS / VOICEVOX / OpenAI / ElevenLabs |
| Video | FFmpeg + Google Imagen 4 |
| Search | Brave Search API |
| Infra | Docker Compose |
コンテンツ方針
このプロジェクトでは、ニュースを「読み上げるだけ」ではなく、クリティカルシンキングを構造的に組み込んでいます。
- ソースの信頼性評価 — 情報源は誰か？一次情報か？
- 複数視点の提示 — 賛成・反対・中立、立場によって見え方が変わることを明示
- 身近なスケール変換 — 「885億円」→「市民1人あたり約6万円」
- 「わからない」を認める — 不確実なことは不確実と伝える
これらのルールは CLAUDE.md に記載されており、Claude Code が台本を生成する際のプロンプトに構造的に反映されます。
Phase 0: CLAUDE.md と Starter Prompt の設計
すべては CLAUDE.md から始まる
プロジェクトを始めるにあたり、最初に書いたのはコードではなく CLAUDE.md です。CLAUDE.md 自体も、プロジェクトの構想を Claude Code に伝えて生成しました。
CLAUDE.md はプロジェクトのルートに置くファイルで、Claude Code が自動的に読み込みます。ここにプロジェクトの全体像を書いておくと、Claude Code は常にその文脈を理解した上でコードを書いてくれます。
AI News Radio の CLAUDE.md には以下を記載しました:
- プロジェクト概要とコンセプト
- コンテンツ方針（クリティカルシンキングのルール）
- 7ステップパイプラインの設計
- AI プロバイダーの抽象化設計
- ディレクトリ構成
- データモデル（Episode, NewsItem, PipelineStep, ApiUsage）
- 設計原則（独立性、承認ゲート必須、冪等性、ログ重視）
- コーディング規約
ポイントは、実装の詳細ではなく「何を作るか」「なぜそう作るか」を書くことです。 Claude Code は CLAUDE.md を読んで、設計意図を理解した上で実装を進めてくれます。
Starter Prompt で Phase ごとに構築
CLAUDE.md だけでは「全部を一度に作って」と言っても、プロジェクトが大きすぎて破綻します。そこで、Phase ごとの Starter Prompt を用意しました。
## Phase 1: プロジェクト基盤
CLAUDE.md を読んで、プロジェクトの基盤を構築してください。
### やること
1. ディレクトリ構成をCLAUDE.mdに従って作成
2. docker-compose.yml を作成
3. backend/ のセットアップ（FastAPI, SQLAlchemy, Alembic）
4. frontend/ のセットアップ（Vite + React + TypeScript + Tailwind）
5. .env.example を作成
...
全7フェーズの Starter Prompt を用意し、各フェーズの完了後に動作確認してから次へ進めました。
| Phase | 内容 |
|---|---|
| 1 | プロジェクト基盤（Docker, DB, API スケルトン） |
| 2 | パイプラインエンジン + 承認API + AIプロバイダー抽象化 |
| 3 | ダッシュボードUI |
| 4 | ニュース収集ステップ |
| 5 | ファクトチェック + 分析 + 台本生成 |
| 6 | 音声生成 + 動画化 |
| 7 | 素材準備（動画・音声・メタデータ）+ 仕上げ |
各 Phase の Prompt には「やること」だけでなく「制約」も明記しています。例えば:
### 制約
- 承認なしに次ステップに進まないことを必ず保証する
- ステップの実行はすべてCeleryタスクとして非同期実行
- AIプロバイダーは config.py 経由でステップごとに切り替え可能
これにより、Claude Code が勝手に設計を変えてしまうことを防ぎ、一貫したアーキテクチャを保てます。
Starter Prompt 設計のコツ
実際にやってみてわかった、Starter Prompt を書くときのポイントです。
1. 「やること」と「制約」を分ける
「やること」はリスト形式で具体的に。「制約」は設計上の不変条件を書く。Claude Code は制約を守りながら、やることリストを上から順に実装してくれます。
2. 1つの Phase で動作確認できる単位にする
Phase 1 が終わった時点で docker compose up -d して動くこと。Phase 2 が終わった時点でAPIを叩いてパイプラインが動くこと。「次の Phase がないと動かない」状態を作らない。
3. テストを Phase に含める
各 Phase にテストを含めておくと、Claude Code がテストも一緒に書いてくれます。後からテストを追加するより、最初から含めた方が品質が安定します。
4. Phase 間の依存関係を明示する
「Phase 1 で作った ai_provider.py を使って」のように、前の Phase で作ったものを参照する指示を入れると、Claude Code が既存コードを正しく活用してくれます。
Claude Code によるセットアップ体験
「セットアップして」の一言で環境構築
AI News Radio は、環境構築も Claude Code で行えます。
git clone https://github.com/JFK/ai-news-radio.git
cd ai-news-radio
claude
# 「セットアップして」と入力
Claude Code は CLAUDE.md のセットアップ手順（docs/setup.md にリンク）を読み、以下を自動実行します:
- 動作環境チェック — Docker, Python, Git, ポートの空きを確認
- Python venv 作成 — 依存パッケージのインストール
- .env 作成 — AIプロバイダーやAPIキーをユーザーに質問して生成
- Docker 起動 + DB マイグレーション
-
MCP サーバー設定 —
.mcp.jsonを生成し、Claude Code からパイプライン操作可能に
注: 実際の対話の流れは Claude Code のセッションにより異なります。APIキーの聞き方や手順の表示形式は毎回同じとは限りません。
従来の setup.sh との違い
以前は Bash スクリプト（setup.sh）でセットアップしていましたが、Claude Code に置き換えました。
| setup.sh | Claude Code | |
|---|---|---|
| エラー対応 | 決まったメッセージを表示 | 原因を調べて対処法を提案 |
| カスタマイズ | スクリプト修正が必要 | 自然言語で指示 |
| トラブルシューティング | ドキュメントを読む | 「ポート8000が使えない」→ 解決 |
| 前提知識 | Docker, .env の知識が必要 | 不要 |
MCP 連携 — Claude Code からパイプラインを操作
AI News Radio は MCP (Model Context Protocol) サーバーを内蔵しています。セットアップで .mcp.json が設定されると、Claude Code から直接パイプラインを操作できます。
> 熊本市の市庁舎建替えニュースを調べて台本まで作成して
Claude Code:
1. search_news("熊本市 市庁舎 建替え") で記事を検索
2. create_episode_from_articles() でエピソード作成
3. run_step(factcheck) → approve_step(factcheck)
4. run_step(analysis) → approve_step(analysis)
5. run_step(script) → 台本を表示して承認を待つ
WebUI で承認ボタンを押す代わりに、Claude Code に「承認して次へ」と言うだけで進められます。
OSS コラボ開発フロー
Issue → 実装 → PR → レビュー → マージを Claude Code で
AI News Radio の開発は、以下のフローで進めています。
1. Issue の起票
> 台本生成プロンプトを改善して、視聴者を引き込む台本にしたい。イシュー化して。
Claude Code が Issue を作成:
- 現状の課題を整理
- 改善内容を具体的にリスト化
- 対象ファイルを特定
2. ブランチ作成 + 実装
> Issue #53 を実装して
Claude Code が:
-
53-feat/improve-script-promptsブランチを作成 - CLAUDE.md のコンテンツ方針に沿って実装
- Ruff / TypeScript のリント通過を確認
- コミットメッセージは Conventional Commits 形式
3. PR 作成
実装が終わると、Claude Code が PR を作成:
- Summary（変更概要）
- Test plan（テスト項目）
-
Closes #53で Issue を自動クローズ
4. レビュー
> まっさらな気持ちでレビューして
Claude Code が自分の書いたコードを客観的にレビューします。実際にこのプロジェクトで見つかった問題の例:
-
フロントエンドの型定義とバックエンドのフィールド名が不一致 —
viewpointvsstandpoint - サイレンス生成のサンプルレートがハードコード — TTS プロバイダーによって異なる可能性
- SSML 変換失敗時のフォールバックがない — LLM 呼び出しが失敗すると全体が止まる
これらは「まっさらな気持ちで」と指示することで、自分が書いたコードへのバイアスなしに見つけてくれました。
5. マージ
> レビュー問題なし。マージして。
実際の開発セッション例
ある日の開発セッションで行った作業を時系列で紹介します。
1. 台本プロンプト改善 (#53)
- つかみパターンを4種類追加（意外な事実、身近なシーン、核心の問い、対比・ギャップ）
- ストーリーテリング技法の具体的指示を追加
- テンポと緩急の指示を追加
2. WebUI からプロンプト編集可能に (#55)
-
PromptTemplateモデル + Alembic マイグレーション - プロンプトのバージョン管理（更新は新バージョン作成、ロールバック可能）
- Settings ページにプロンプト編集タブを追加
3. 音声生成を記事単位に分割 (#57)
- 全記事一括 → 記事ごとに個別 WAV 生成
- セクション間に無音を挿入
- YouTube 用タイムスタンプを自動生成
4. LLM ベースの SSML 変換
- TTS 直前に LLM でプレーンテキスト → SSML 変換
-
<break>（間）と<emphasis>（強調）で自然な抑揚 - 変換失敗時はプレーンテキストにフォールバック
5. ファクトチェック生データの台本混入修正
-
partially_verifiedやスコア4/5が台本に混入する問題 - 根本対策: ファクトチェック生データを scriptwriter への入力から除外
- 信頼性の低い記事（unverified, disputed）を台本から除外
6. 各種バグ修正
- 分析レンダラーのフィールド名不一致修正
- 全ステップ承認時のエピソードステータス自動更新
- FFmpeg 高速化（720p / ultrafast / CRF 28）
これらすべてが1つの Claude Code セッションで、Issue 起票 → 実装 → レビュー → マージまで完結しました。
Claude Code での OSS コラボレーション
CONTRIBUTING.md にも記載していますが、コントリビューターも Claude Code を使って開発できます。
# Fork & Clone
git clone https://github.com/<your-username>/ai-news-radio.git
cd ai-news-radio
# Claude Code でセットアップ
claude
# 「セットアップして」
# 開発
# 「Issue #42 を実装して」
# バグ報告・機能要望
# 「〇〇のバグを報告して」→ Issue が自動作成される
まとめ
CLAUDE.md を書き、Starter Prompt で Phase ごとにプロジェクトを立ち上げ、日々の開発も Issue → 実装 → レビュー → マージまで Claude Code で完結する。
この開発スタイルのメリットは:
- 設計意図が常に伝わる — CLAUDE.md に書いた方針が、すべてのコード生成に反映される
- セットアップの属人化がない — 「セットアップして」の一言で誰でも環境構築できる
- レビューの客観性 — 「まっさらな気持ちで」と指示するだけで、自分のコードを客観的にレビューしてくれる
- Issue からマージまで一気通貫 — コンテキストの切り替えが少なく、集中できる
AI News Radio は Apache 2.0 ライセンスの OSS です。Claude Code をお持ちの方は、ぜひ clone して「セットアップして」と言ってみてください。
リポジトリ: https://github.com/JFK/ai-news-radio
Starter Prompt: https://github.com/JFK/ai-news-radio/blob/main/docs/starter-prompts.md