こんにちは、とまだです。
SuperClaudeのコマンドはたくさんあるけれど、どの順番で使えばいいか迷っていませんか？
実はSuperClaudeには「Common Workflows」という推奨パターンがあります。
この流れに沿って進めると、要件定義から実装計画の策定、さらにコード品質の向上までスムーズに開発が進むようになります。
今回は天気予報アプリを題材に、SuperClaudeの4つのワークフローを実践してみました！
忙しい人のために要約
- SuperClaudeの推奨ワークフローで効率的に開発できる
- brainstorm → design → workflow の3つで設計が完成
- 各コマンドの実行結果が具体的で実用的
- コード品質の分析と改善が数値で可視化される
- ドキュメント生成機能で開発資産を残せる
ちなみに、こちらの動画版の方が解説は手厚いのでおすすめです。
今回使うワークフローの全体像
SuperClaudeのドキュメントには「Common Workflows」として4つの推奨パターンが紹介されています。
それぞれ、よくある開発シーンに対応しているのです。
- New Project Setup - プロジェクト立ち上げ
- Feature Development - 機能開発
- Code Quality Improvement - 品質改善
- Bug Investigation - 問題調査
これらを組み合わせることで、開発の全工程をカバーできます。
プロジェクトのセットアップ
まずはNext.jsでプロジェクトを作成します。
npx create-next-app@latest weather-app
cd weather-app
npm run dev
別ターミナルでClaude Codeを起動。
claude
初期化コマンドで現在の状態をメモリファイルに記録します。
/init
これで準備完了です。
プロジェクトの現状をCLAUDE.mdファイルに保存しておくことで、以降の会話で文脈を保持できるようになります。
SuperClaude をインストール
まだ SuperClaude をインストールしていない場合は、別の記事を参考にインストールをしておきます。
なお、SuperClaude のカスタムコマンドは日々追加されているようですので。適宜バージョンアップしておくと良いでしょう。
再度、インストールすると確実にコマンドを最新化できます。
uv venv
source .venv/bin/activate
uv pip install SuperClaude
python3 -m SuperClaude install
ワークフロー1：プロジェクトの立ち上げ
新規プロジェクトで最初に使うワークフローです。
要件定義 → 設計 → 計画という流れで進めていきます。
brainstormで要件定義
まずは作りたいものを明確にします。
/sc:brainstorm "天気予報アプリを作りたいです。OpenWeatherMap APIを使って現在の天気と5日間の天気予報を表示したい"
するとSuperClaudeが対話的に要件を詰めてくれます。
🤔 要件の詳細確認
基本機能について
- 場所の指定方法はどうしましょうか？
- 都市名で検索？
- 現在地を自動取得？
- お気に入りの場所を保存？
- 複数都市の切り替え機能？
表示したい天気情報
- 現在の天気で表示したい項目：
- 気温、体感温度、天気アイコン？
- 湿度、風速、気圧？
- 降水確率、視界？
- 5日間予報の表示形式：
- 1日ごとの最高/最低気温？
- 3時間ごとの詳細予報？
- 週間トレンドグラフ？
デザイン・UX
- ビジュアルスタイル：
- シンプルでクリーンなデザイン？
- 天気に応じた背景画像/アニメーション？
- カード型レイアウト？
- ダーク/ライトモード対応？
技術的な要望
- データ更新：
- ページ読み込み時のみ？
- 定期的な自動更新？
- プルダウンでリフレッシュ？
📝 現時点での要件整理
プロジェクト: 天気予報Webアプリ
技術スタック:
- Next.js 15.5.0 (App Router)
- TypeScript
- Tailwind CSS v4
- OpenWeatherMap API
確定機能:
- 現在の天気表示
- 5日間の天気予報
検討事項:
- 場所の指定方法
- 表示する詳細情報
- UI/UXデザイン
- レスポンシブ対応の優先度
どの部分から詳しく決めていきましょうか？特に重視したい機能はありますか？
ここで注目すべきは、曖昧な部分を明確にしてくれる点です。
ただ「天気予報アプリを作りたい」と伝えただけでは、実装の詳細が決まらず後で手戻りが発生します。
でもbrainstormコマンドなら、考慮すべき点を網羅的に提示してくれるのです。
例えば場所の指定方法ひとつとっても、都市名検索なのか現在地取得なのか。
この選択によって実装の複雑さが大きく変わります。
シンプルに作りたいので、以下のように返答しました。
場所については都市名で検索できるようにしつつ、デフォルトは東京にしておいてください。
他の要件については任せますが、まずはできるだけシンプルで最低限な機能にとどめてほしいです。
最終的にこのような要件定義書が作成されました。
⏺ 了解しました！シンプルで最低限の機能に絞った天気予報アプリを作りましょう。
📋 最終仕様書
コア機能（MVP）
場所の指定:
- 都市名検索（テキスト入力）
- デフォルト: 東京
- 検索履歴: なし（シンプルさ優先）
現在の天気:
- 都市名
- 現在の気温
- 天気の説明（晴れ、曇りなど）
- 天気アイコン
- 最高/最低気温
5日間予報:
- 日付
- 天気アイコン
- 最高/最低気温
- シンプルなリスト表示
UI/UX:
- クリーンでミニマルなデザイン
- モバイル対応（レスポンシブ）
- ライトモードのみ
- 日本語表示
技術実装
API設定:
- OpenWeatherMap API (無料プラン)
- 言語パラメータ: ja（日本語）
- 単位: metric（摂氏）
コンポーネント構成:
- SearchBar: 都市名入力
- CurrentWeather: 現在の天気カード
- ForecastList: 5日間予報リスト
- WeatherCard: 予報の各日表示
エラー処理:
- 都市が見つからない場合
- API制限/エラー
- ローディング状態
実装の優先順位
1. Phase 1: 基本機能
- 東京の天気をハードコード表示
- UIレイアウト構築
2. Phase 2: API統合
- OpenWeatherMap API接続
- データ取得と表示
3. Phase 3: 検索機能
- 都市名検索実装
- エラーハンドリング
これでよろしいでしょうか？実装を開始してもよいですか？
要件が明確になったところで、ドキュメント化しておきます。
> 決まった要件定義について、docsディレクトリ内にドキュメントとしてまとめてください
ドキュメント化しておくことで、後から振り返ったり、AIとの会話が長くなっても文脈を失わないようにできます。
また、APIキーを事前にOpenWeatherMapから取得しておいたので、その旨を伝えてあげましょう。
env.localにOPEN_WEATHER_API_KEYという名前でAPIキーを設定してあります。
その前提で進めるよう、要件定義書に追記してください。
designでシステム設計
要件が固まったら、技術的な設計に入ります。
/sc:design "要件定義をもとにシステム設計"
すると、以下のような設計が自動生成されました。
⏺ システム設計書を docs/system-design.md として作成しました。
設計のポイント
🏗️ アーキテクチャ
- 3層構造: クライアント → API Routes → 外部API
- セキュリティ重視: APIキーをサーバーサイドで管理
🔐 セキュリティ設計
- APIキーは環境変数 OPEN_WEATHER_API_KEY で管理
- Next.js API Routesを使用してキーを保護
- 入力検証とレート制限を実装
📦 コンポーネント設計
- SearchBar: 都市名検索
- CurrentWeather: 現在の天気表示
- ForecastList: 5日間予報リスト
- WeatherCard: 個別の予報カード
🔄 データフロー
1. ユーザー入力 → SearchBar
2. API Route経由でOpenWeatherMapに接続
3. レスポンスを整形してUIに反映
⚡ パフォーマンス最適化
- 5分間のAPIレスポンスキャッシング
- 検索入力に500msのデバウンス
- エラーハンドリングと再試行機能
設計書には、型定義、エラーハンドリング、テスト戦略も含まれています。これをベースに実装を進められます。
アーキテクチャ、セキュリティ、コンポーネント、データフロー、パフォーマンスなど、実践的な観点でまとめられています。
特に注目したいのはセキュリティ設計の部分です。
APIキーをクライアント側に露出させないために、Next.js API Routesを経由する設計になっています。
こういった実装上の落とし穴を事前に回避できるのは、設計段階でしっかり考えているからです。
ゼロから適切な設計を作らせる指示をするのも大変ですが、SuperClaudeならこのレベルのシステム設計をコマンド一発で作成できます。
workflowで実装計画作成
設計ができたら、具体的な実装計画を立てます。
/sc:workflow "実装計画"
テスト駆動開発で進めたいとフィードバックしたところ、以下の計画が作成されました。
📋 実装計画の概要
Phase 1: UI基盤構築 (Day 1)
- 型定義とプロジェクト構造
- モックデータでUIコンポーネント作成
- レスポンシブデザイン実装
Phase 2: API実装 (Day 2)
- Next.js API Routes構築
- OpenWeatherMap連携
- キャッシング実装
Phase 3: 統合と検索機能 (Day 2-3)
- フロントエンドとAPI統合
- リアルタイム検索機能
- UX改善（ローディング、エラー表示）
Phase 4: 最適化 (Day 3)
- エラーハンドリング強化
- パフォーマンス最適化
- セキュリティとアクセシビリティ
Phase 5: テスト (Day 3-4)
- ユニット/統合テスト
- ドキュメント整備
- デプロイ準備
計画書も自動的にドキュメント化されました。
この段階的な実装計画があることで、どこから手をつけるべきか迷うことがなくなります。
特にPhaseごとに明確な成果物が定義されているので、進捗も把握しやすくなります。
ワークフロー2：機能開発
計画ができたら、実際の開発に入ります。
implementで段階的に実装
まずはテスト基盤の設定から始めます。
/sc:implement "テスト基盤の設定"
実行結果はこちらです。
⏺ ✅ テスト基盤のセットアップ完了
テスト駆動開発（TDD）のための基盤を構築しました。
📦 インストール済みパッケージ
- Jest: テストフレームワーク
- @testing-library/react: Reactコンポーネントテスト
- @testing-library/jest-dom: DOM要素のカスタムマッチャー
- @testing-library/user-event: ユーザーインタラクションシミュレーション
- jest-environment-jsdom: ブラウザ環境のシミュレーション
📁 作成したファイル構造
weather-app/
├── jest.config.js # Jest設定ファイル
├── jest.setup.js # テスト環境のセットアップ
├── __tests__/ # テストファイル用ディレクトリ
│ ├── components/ # コンポーネントテスト
│ ├── lib/ # ライブラリテスト
│ ├── api/ # APIテスト
│ └── types/ # 型定義テスト
└── src/
├── components/ # コンポーネント実装
├── lib/ # ユーティリティ
└── types/ # 型定義
🧪 利用可能なテストコマンド
npm test # テスト実行
npm run test:watch # 変更監視モードでテスト
npm run test:coverage # カバレッジレポート生成
✨ セットアップ内容
- Next.js対応のJest設定
- TypeScriptサポート
- パスエイリアス（@/）のサポート
- 環境変数のモック（OPEN_WEATHER_API_KEY）
- fetchのグローバルモック
テスト環境の動作確認も完了し、TDD開発の準備が整いました。
テスト基盤のセットアップが完了しました。
ここで重要なのは、単にライブラリをインストールするだけでなく、ファイル構造まで整理してくれている点です。
後からテストを書きやすい構造になっているので、開発効率が上がります。
続けてPhase 1から順に実装を進めます。
/sc:implement "Phase 1"
実装計画に従って、自動的にコードが生成されていきます。
もし、一気に進めたい場合は以下のようなプロンプトでOKです。
すでにシステム設計や計画は綿密に立てられていますので、こちらでも大丈夫かと思います。
/sc:implement "実装計画に沿って完了まで進めてください"
計画があるからこそ、こういった大雑把な指示でも適切に実装が進むのです。
エラーが発生した時の対処法
実装が完了してブラウザで確認すると、エラーが出ていました。
「東京という都市が見つかりませんでした」というメッセージです。
throw new Error(error.error || '天気予報の取得に失敗しました')
これを解消するため、カスタムコマンドを使ってみましょう
troubleshootで問題診断
問題を解決するためのカスタムコマンドがありますので、そちらを使います。
エラー内容を引数的に渡してあげればOKです。
/sc:troubleshoot "## Error Type
Console Error
## Error Message
Forecast data not found for 東京
at fetchForecast (src/lib/weather.ts:19:11)
at async Home.useCallback[loadWeatherData] (src/app/page.tsx:23:43)
## Code Frame
17 | if (!response.ok) {
18 | const error = await response.json()
> 19 | throw new Error(error.error || '天気予報の取得に失敗しました')
| ^
20 | }
21 |
22 | return response.json()
Next.js version: 15.5.0 (Turbopack)
"
SuperClaudeが問題を分析してくれます。
問題の診断結果と解決策
原因：OpenWeatherMap APIは日本語の都市名を認識できません
解決：英語の都市名のみを受け付けます
以下の修正を実施：
- 日本語都市名を英語に変換するヘルパー関数を追加
- よく使われる日本の都市名のマッピングを作成
この診断結果が重要なのは、単にエラーを修正するだけでなく、根本原因を特定している点です。
日本語の都市名が使えないという仕様上の制約を見つけ、それに対する解決策まで提示してくれています。
これは単純にエラーメッセージをClaude Codeに渡すよりも、構造的な問題解決になっています。
修正後、無事に天気情報が表示されるようになりました。
機能追加と見積もり
ここまで、天気アイコンは画像として取得していました。
この天気アイコンを絵文字に変更する作業の見積もりを取ってみます。
estimateで工数見積もり
/sc:estimate "天気アイコンを画像ではなく絵文字を使うようにしたい"
プロジェクトマネージャーのような詳細な見積もりが出力されました。
📊 見積もり結果
推定作業時間: 2-3時間（人間の実装時間）
複雑度: 低〜中程度
影響箇所: 2コンポーネント
実装計画:
1. 天気コードと絵文字のマッピング作成
2. CurrentWeatherコンポーネントの修正
3. ForecastListコンポーネントの修正
4. テストの更新
メリット:
✅ 外部画像依存の排除
✅ パフォーマンス向上（ネットワークリクエスト削減）
✅ オフライン対応可能
デメリット:
⚠️ OS・ブラウザによる絵文字表示の差異
⚠️ 細かい天気の表現が難しい
リスクと対策:
- リスク：絵文字が表示されない環境
- 対策：フォールバックテキストの用意
- 影響度：低
実装の判断に必要な情報が網羅されています。
特にメリット・デメリットが明確になっているので、実装すべきかどうかの判断材料になります。
個人開発でも、こういった見積もりを取ることで手戻りを減らせます。
taskで実装
見積もりを元に、実装を進めます。
implementコマンドでも良いのですが、せっかくなのでestimateとセットで使われるtaskコマンドを使ってみます。
/sc:task "天気を画像から絵文字に置き換える実装"
今回だとタスクが細分化され、いくつかの段階に分かれて実装が進みます。
画像を絵文字に置き換える程度の実装であればtaskコマンドの恩恵は小さいのですが、規模が大きく、複雑な実装であればtaskは効力を発揮しそうです。
taskコマンドの利点は、実装を論理的な単位で分割してくれることです。
これにより、途中で問題が発生しても、どこまで完了していて何が残っているかが明確になります。
特に詰まることなく、置き換えが完了しました。
ワークフロー3：ドキュメント生成
開発が一段落したら、ドキュメントを整備します。
--typeオプションで指定すると、ドキュメントの種類を選べます。
APIドキュメント生成
/sc:document --type api
API仕様書が自動生成されました。
こちらは一部抜粋した例です。
## Endpoints
### 1. Get Current Weather
**Endpoint:** `GET /api/weather/[city]`
**Description:** Returns current weather information for the specified city.
**Parameters:**
| Parameter | Type | Location | Required | Description |
|-----------|------|----------|----------|-------------|
| city | string | URL path | Yes | City name (English or romanized) |
**Response Schema:**
```typescript
{
city: string // City name
temperature: number // Current temperature (°C)
description: string // Weather description in Japanese
icon: string // Weather icon code (e.g., "01d", "09n")
tempMax: number // Maximum temperature (°C)
tempMin: number // Minimum temperature (°C)
humidity?: number // Humidity percentage (optional)
windSpeed?: number // Wind speed in m/s (optional)
}
```
**Example Request:**
```bash
curl http://localhost:3000/api/weather/Tokyo
```
**Example Response:**
```json
{
"city": "Tokyo",
"temperature": 25.4,
"description": "晴れ",
"icon": "01d",
"tempMax": 28.2,
"tempMin": 22.1,
"humidity": 65,
"windSpeed": 3.5
}
```
**Error Responses:**
| Status Code | Description | Response Body |
|-------------|-------------|---------------|
| 404 | City not found | `{ "error": "Weather data not found for [city]" }` |
| 500 | Server error | `{ "error": "Failed to fetch weather data" }` |
| 500 | No API key | `{ "error": "API key is not configured" }` |
**Cache Behavior:**
- Results cached for 5 minutes per city
- Cache key: lowercase city name
- Cache cleared on server restart
このAPIドキュメントが優れているのは、実装から自動生成されているため、常に最新の状態を保てることです。
手動でドキュメントを書くと、実装と乖離しがちですが、SuperClaudeなら実装と同期したドキュメントが作成できます。
チーム開発でAPIを共有する際にも役立ちます。
ユーザーガイド生成
/sc:document --type user-guide
エンドユーザー向けのガイドも生成されます。
# 天気予報アプリ ユーザーガイド
## 🌤️ はじめに
このアプリは、世界中の都市の天気情報を簡単に確認できるWebアプリケーションです。現在の天気と5日間の天気予報を、見やすい絵文字とともに表示します。
## 📱 主な機能
### 現在の天気表示
- 🌡️ リアルタイムの気温
- 🌤️ 天気の状態（絵文字で表示）
- 📊 最高・最低気温
- 💧 湿度
- 💨 風速
### 5日間天気予報
- 📅 日付と曜日
- 🌡️ 各日の最高・最低気温
- 🌤️ 天気予報（絵文字で表示）
## 🚀 使い方
### 1. アプリケーションへのアクセス
ブラウザで以下のURLにアクセスしてください：
...以下略
個人開発でも、こういったユーザーガイドがあると、SNSで宣伝する時や、利用者からの質問対応が楽になります。
ワークフロー4：品質改善
最後に、コード品質を改善していきます。
analyzeで品質分析
/sc:analyze --focus quality
詳細な分析レポートが生成されます。
スコアも出るので、定期的にレポートを生成して品質改善に役立てそうです。
⏺ 📊 コード品質分析完了
Weather Appプロジェクトの品質分析を完了しました。
📈 総合評価: 85/100点 ⭐⭐⭐⭐
分析結果をdocs/QUALITY_REPORT.mdに保存しました。
主な評価ポイント:
優れている点 ✅
- Next.js 15.5 App Routerによるモダンなアーキテクチャ
- TypeScript厳格モードによる型安全性
- 適切なコンポーネント設計と責務分離
- 完全な日本語ローカライゼーション
改善が必要な点 ⚠️
- ErrorBoundaryコンポーネントが未使用
- テストカバレッジ測定の設定不備
- ネットワークエラーの詳細分類が不足
- アクセシビリティ対応の強化余地
詳細な改善提案とロードマップはレポートファイルをご確認ください。
100点満点中85点というスコアが出ました。
これにより、コード品質を客観的に把握できます。
特に改善点が明確になっているので、どこから手をつければ良いかが分かります。
improveで品質改善
分析結果を元に、改善を実行します。
/sc:improve --type quality "出力は日本語でお願いします"
自動的に改善が実施されました。
⏺ 🎉 コード品質改善完了
Weather Appのコード品質を大幅に改善しました。
📈 実施した改善内容
1. エラーハンドリングの強化 ✨
- カスタムエラータイプ5種類を実装
- APIエラーの詳細な分類とメッセージの日本語化
- デバッグしやすいエラーコード体系
2. アクセシビリティの大幅改善 ♿
- SearchBarコンポーネントのWCAG準拠
- スクリーンリーダー完全対応
- キーボードナビゲーション強化
3. ローディング体験の向上 ⚡
- スケルトンスクリーンの実装
- 視覚的に快適なローディングアニメーション
4. テストインフラの改善 📊
- カバレッジ測定設定の追加
- 品質閾値の設定（80%目標）
📊 品質スコアの向上
85点 → 92点 に改善
📁 生成ファイル
- src/lib/errors.ts - カスタムエラークラス
- src/components/WeatherSkeleton.tsx - スケルトンスクリーン
- docs/QUALITY_IMPROVEMENTS.md - 改善レポート
✅ 動作確認
- リントエラー: なし
- 型エラー: なし
- ビルド: 正常
詳細な改善内容は docs/QUALITY_IMPROVEMENTS.md をご確認ください。
7点もスコアが向上しました。
重要なのは、単に数値が上がっただけでなく、具体的にどのような改善が行われたかが明確な点です。
エラーハンドリング、アクセシビリティ、ローディング体験など、ユーザー体験に直結する改善が含まれています。
テストカバレッジ分析
/sc:test --coverage
テストの実行とカバレッジ分析が行われます。
⏺ 📊 テストカバレッジ分析完了
現在のカバレッジ状況
総合カバレッジ: 34.95% （目標: 80%）
| メトリクス | 現在値 | 目標値 | 差分 |
|------------|--------|-----|-----------|
| Statements | 34.95% | 80% | -45.05% ❌ |
| Branches | 29.52% | 70% | -40.48% ❌ |
| Functions | 33.33% | 80% | -46.67% ❌ |
| Lines | 35.64% | 80% | -44.36% ❌ |
テスト実行結果
- ✅ 成功: 36テスト / 5スイート
- ❌ 失敗: 3テスト / 3スイート
- 合計: 39テスト / 8スイート
📁 生成されたレポート
docs/TEST_COVERAGE_REPORT.md に詳細なカバレッジ分析レポートを作成しました。
🔍 主な問題点
1. メインページ（page.tsx）: 0% - 完全に未テスト
2. エラー処理: ErrorBoundary.tsx (0%), errors.ts (25.71%)
3. API通信層: weather.ts (0%)
✅ 良好な部分
- UIコンポーネント: CurrentWeather, ForecastList, WeatherCard は100%カバレッジ
- APIルート: 70-100%の高カバレッジ
🎯 推奨される次のステップ
1. 緊急対応（1-2日）
- page.tsxの統合テスト追加
- weather.tsのユニットテスト
- errors.tsのテスト追加
2. 標準達成（3-5日）
- カバレッジ閾値を段階的に上げる
- ErrorBoundaryのテスト実装
- 全体カバレッジ80%を目指す
詳細な改善計画はレポートファイルをご確認ください。
カバレッジが約35%と低い結果になりました。
でも、これで良いのです。
現実的な開発では、最初から100%のカバレッジを目指すのではなく、段階的に改善していくものです。
重要なのは、どこが未テストなのか、どこから手をつけるべきかが明確になっていることです。
SuperClaudeを使って感じたこと
今回の開発を通じて、SuperClaudeの威力を実感しました。
特に印象的だったのは以下の点です。
1. 段階的な思考プロセス
brainstorm → design → workflowという流れが自然です。
人間のエンジニアが考える流れと同じなのですね。
要件を明確にして、設計して、計画を立てる。
この当たり前のプロセスを、AIがサポートしてくれます。
普段なんとなく頭の中で考えていることを、きちんと言語化してくれるので、思考の抜け漏れがなくなります。
2. 数値による可視化
コード品質が85点から92点に改善された。
カバレッジが34.95%で目標まであと45%。
このような具体的な数値があると、次のアクションが明確になります。
「なんとなく品質を上げたい」ではなく、「92点を95点にするために、エラーハンドリングを強化する」という具体的な目標設定ができるのです。
3. 専門的な観点での分析
セキュリティ、パフォーマンス、アクセシビリティ。
それぞれの観点で専門的な分析をしてくれます。
一人で開発していると見落としがちな部分も、きちんとチェックしてくれるのです。
特にアクセシビリティは忘れがちな観点ですが、SuperClaudeなら自動的に考慮してくれます。
まとめ
SuperClaudeの推奨ワークフローを使って天気予報アプリを作ってみました。
各コマンドが連携して動くことで、開発の全工程がスムーズに進みます。
特にanalyzeとimproveの組み合わせは強力でした。
要件定義から品質改善まで、一貫した流れで開発できるので、手戻りが少なく効率的です。
もしSuperClaudeを使っている方は、ぜひこのワークフローを試してみてください。
開発効率が劇的に向上することを実感できるはずです。
今回紹介したコマンドはSuperClaudeの一部に過ぎません。
他にも便利なコマンドがたくさんあります。
詳しく知りたい方は、前回の記事もぜひご覧ください。
SuperClaudeとは？Claude Codeのコード品質を30%改善できた神ツールの完全ガイド！
また、動画でも詳しく解説していますので、よければチェックしてみてください。
X（Twitter）でも開発の様子を発信しています。