Claude Codeを活用して作詞支援ツールを開発・リリースしたので技術構成を振り返ってみた

はじめに

先日、個人開発のサービスとして作詞支援ツールのWEBアプリを開発・リリースしたので技術構成と開発フローを解説します。

この記事では以下をカバーします。

• プロダクト設計思想とアーキテクチャ
• サーバーレス構成（Lambda + DynamoDB + S3/CloudFront）の詳細
• サービスの運用設計（監視・レート制限・コスト管理）
• Claude Codeを活用した開発フロー

Claude Codeの活用方法と、個人開発でのサーバーレスアーキテクチャに興味がある方の参考になれば幸いです。

開発したツールについて

歌詞の母音構造・韻パターン・音数のバランスをリアルタイムで可視化し、候補を提案する作詞支援ツールです。
AIが歌詞を書くツールではなく、作詞家が自分の歌詞の構造を把握し、推敲するための可視化ツールという立ち位置になっています。

開発の動機

趣味で音楽制作をしていて、作詞中に「韻や類義語が自動で出てきたら便利なのに」と感じたのがきっかけです。既存ツールを調べても、日本語の韻構造を可視化してくれるものが見つかりませんでした。

開発期間は5日間です。骨組みを3日で構築し、残り2日で修正してリリースしました。技術的にはインフラをメインにやっており、フロントエンド・バックエンドの実装はClaude Codeに大きく頼っています。

コア機能

母音解析がブラウザ内で完結する点がポイントです。AIはあくまで補助であり、コア機能はオフラインでも動作します。

また、韻候補と類義語はログインなしで利用できる設計にしています。作詞支援ツールとしての価値をまず体感してもらい、楽曲の保存やAI推敲を使いたくなった段階でログインを促す導線です。

アーキテクチャ

┌─ フロントエンド ──────────────────────────┐
│  Next.js 16 (App Router) + TypeScript    │
│  kuroshiro.js（漢字→ひらがな変換）          │
│  韻検索辞書（ローカルJSON → IndexedDB）     │
│  Tailwind CSS（ダークテーマ基調）           │
└──────────────────────────────────────────┘
         │ Static Export
         ▼
┌─ ホスティング ───────────────────────────┐
│  S3 + CloudFront                         │
│  Route 53                                │
└──────────────────────────────────────────┘
         │ API Gateway (HTTP API)
         ▼
┌─ バックエンド ────────────────────────────┐
│  Lambda (Python 3.12) × 14関数           │
│  ├─ suggest   — AI提案　　　　　　         │
│  ├─ diagnose  — AI歌詞診断　　　　　       │
│  ├─ rhyme     — 韻候補API　　　　　　      │
│  ├─ synonym   — 類義語検索　　　　　　  　  │
│  ├─ define    — 単語定義　　　　　　　   　 │
│  ├─ songs     — 楽曲CRUD × 4関数          │
│  ├─ billing   — 決済 × 4関数              │
│  └─ daily-report — Slack日次レポート      │
│                                          │
│  DynamoDB (2テーブル, On-Demand)          │
│  Cognito (Google OAuth 2.0)              │
└──────────────────────────────────────────┘
         │
         ▼
┌─ 外部サービス ───────────────────────────┐
│  Anthropic API　　　　　　　　　　　　    │
│  Stripe（サブスクリプション決済）         │
│  Slack Webhook（運用通知）               │
└─────────────────────────────────────────┘

設計方針

ブラウザ完結設計を採用しています。母音解析・音数カウント・韻検索はすべてブラウザ内で処理するため、ユーザーが歌詞を入力・編集する際にAPIコールは発生しません。この設計はコスト削減とゼロ遅延の解析体験を両立させています。

サーバーにリクエストが飛ぶのは、韻候補・類義語・AI機能などの作詞の補助機能でユーザーが明示的にアクションを起こした場合です。

母音解析エンジン

コア機能である母音解析は、kuroshiro.js + IPAdic辞書（MeCabベース）を使い、「入力テキスト → 漢字からひらがな変換 → 音数分割 → 母音抽出」の処理をすべてブラウザ内で完結させています。日本語の拗音・長音・促音・撥音といった音数ルールを正しく処理する必要がありますが、ここでは割愛します。

重要なのは、この処理がブラウザ完結であることです。これにより、ユーザーが歌詞を入力するたびにAPIコールが発生することを防ぎ、後述するコスト設計の土台になっています。

Claude Codeを使った開発フロー

ここからは本ツールの開発で実際にClaude Codeをどう活用したかを解説します。

Claude Codeとは

みなさんご存じかと思いますが、Anthropicが提供するCLIベースのAIコーディングツールです。ターミナル上でClaudeと対話しながら、コードの読み書き・コマンド実行・Git操作をシームレスに行えます。VS CodeやCursorのようなエディタ統合型ツールとは異なり、ターミナルの中で完結するのが特徴です。

CLAUDE.md ― プロジェクトの「取扱説明書」

Claude Codeを使う上で最も重要なのが、プロジェクトルートに置くCLAUDE.mdです。会話開始時にClaude Codeが自動的に読み込むマークダウンファイルで、プロジェクトのコンテキストを共有します。

本ツールでは、コードを書き始める前にまずCLAUDE.mdを作りました。プロダクトの方向性・ターゲットユーザー・技術選定・データモデルなどをClaude Codeと壁打ちしながら徹底的に詰め、296行のドキュメントに落とし込んでいます。この初期投資が、以降の開発で「意図と違うコードが出てくる」問題をほぼ消してくれました。

記載内容は以下の通りです。

CLAUDE.mdに哲学や制約を書いておくことで、Claude Codeが文脈を理解した状態で作業を始められます。「フル歌詞自動生成機能は哲学に反するため作らない」と明記しておけば、その方向の提案は出てきません。

メモリ機能 ― 会話をまたぐフィードバックの蓄積

Claude Codeにはファイルベースのメモリ機能があります。一度伝えたフィードバックを永続化し、次回以降の会話でも反映されます。

本ツールでは以下のようなメモリを蓄積しています。

- pushする前に必ずユーザーの許可を取る（本番稼働中のため）
- デプロイはCI/CD経由のみ。手動sam deploy禁止
- Route 53で独自ドメイン取得済み

一度「勝手にpushしないで」と伝えれば、以降の会話では必ず確認が入ります。プロジェクト固有のルールを覚えさせられるのは、チームメンバーにオンボーディングするのに近い感覚です。

実際の開発サイクル

本ツールの開発での典型的なサイクルは以下の通りです。

1. 機能要件をClaude Codeに伝える
   → CLAUDE.mdの文脈があるので、最小限の説明で意図が伝わる

2. Claude Codeが既存コードを読み、実装方針を提案
   → 必要に応じて方針を修正指示

3. コード生成・ファイル編集
   → 複数ファイルにまたがる変更も一度に対応

4. 動作確認は自分の目で行う
   → UI/UXの判断は人間がする

5. 「pushして」でgit commit + push
   → GitHub Actions（CI/CD）が自動デプロイ

ステップ4が最も重要です。Claude Codeはコードを書けますが、「このUIでユーザーが使いやすいか」「この挙動に違和感がないか」は人間が判断する必要があります。

Claude Codeが特に活きた場面

横断的なリネーム

「分析」機能を「提案」にリネームする作業では、フロントエンド（Reactコンポーネント）、バックエンド（Lambdaハンドラー）、Slack通知メッセージ、エラーメッセージまで、プロジェクト全体を横断して一括修正できました。手動で行うと見落としが発生しやすい作業です。

SAMテンプレートの構築

724行のSAMテンプレートでLambda + API Gateway + DynamoDB + Cognito + S3 + CloudFrontを管理しています。SAMテンプレートの記法を逐一覚えるのは現実的ではありませんが、CLAUDE.mdにアーキテクチャが書いてあるため、「新しいLambda関数を追加して」と指示すれば既存構成に合わせた設定でtemplate.yamlに追加してくれます。

バグの原因特定

「Proプランなのに相談回数が0/3と表示される」というバグに対して、Claude Codeがコードを追い、管理者用レスポンスにchatUsage/chatLimitフィールドが欠けていたことを特定しました。

パフォーマンス改善

コード進行管理機能の追加後、エディタの描画が重くなりました。Aメロを1文字編集しただけで、Bメロもサビも含む全セクションが再描画される状態です。Claude Codeに「重いので直して」と伝えたところ、「変更のないセクションは再描画をスキップする」最適化に加え、その最適化が正しく効くための前提条件（親から渡す関数の作り方）まで含めて修正してくれました。こうした「対症療法ではなく根本原因まで遡る」修正は、Claude Codeが得意な場面です。

Claude Code利用時の注意点

• UIの感覚的な調整は人間の仕事：余白や色味の微調整は、画面を見ながら自分で判断する必要がある
• 動作確認は省略しない：特にエッジケースや既存機能との整合性は必ず確認する
• CLAUDE.mdの品質が出力の品質に直結する：最初に時間をかけて書く価値がある
• メモリでガードレールを設ける：本番稼働中のサービスでは「勝手にpushしない」「手動デプロイ禁止」などの制約を記憶させる

CI/CDパイプライン

GitHub Actionsで以下のフローを構築しています。

PR時（ci.yml）

on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - run: npm ci
      - run: npx tsc --noEmit   # TypeScript型チェック
      - run: npm run lint        # ESLint

mainマージ時（deploy.yml）

deploy-backend → deploy-frontendの2ジョブ構成で、needsで依存関係を定義しています。

[deploy-backend]
1. Lambda共通モジュール（shared/）を各関数ディレクトリにコピー
2. SAM build → SAM deploy（Lambda + API Gateway + DynamoDB等）
3. CloudFormation Outputs（API URL、S3バケット名等）を取得

[deploy-frontend]  ← deploy-backendの完了後に実行
4. Next.js build（Static Export）
   ※ API Routesは本番では使わないため、ビルド前に一時リネーム
5. S3 sync → CloudFront invalidation

バックエンドのデプロイで確定したAPI URLやS3バケット名をフロントエンドのビルド時に環境変数として渡す必要があるため、この順序は必須です。

並列デプロイを防ぐconcurrency設定（cancel-in-progress: false）を入れているため、連続pushしてもデプロイがキューイングされ安全に処理されます。

サーバーレス運用設計

個人開発で見落としがちなのが運用です。これまでの経験から「一人でも安全に回せる仕組み」を最初から組みました。

Slack通知の2系統

日次レポート（EventBridge → Lambda → Slack）

毎日23:55 (JST) にDynamoDBを集計してSlackに通知します。

（例）
📊 日次レポート（YYYY-MM-DD）
━━━━━━━━━━━━━━━━━
👤 登録ユーザー: N人（Pro: N人）
📝 楽曲数: N
━━━━━━━━━━━━━━━━━
🔥 今日のアクティブ: N人
💬 AI相談: N人（合計N回）
🔍 AI提案: N人（合計N回）
🚫 上限到達: N人

上限到達者数はフリーミアムの価格設計を見直す判断材料として活用しています。

リアルタイムエラーアラート（Lambda → Slack）

全Lambda関数の共通モジュールにnotify_error()を用意し、エラー発生時に即座にSlack通知を送ります。

def notify_error(function_name: str, error_msg: str, context: str = ""):
    """エラーをSlackに通知"""
    if not SLACK_ALERT_URL:
        return
    text = (
        f"🚨 *Lambda エラー*\n"
        f"関数: `{function_name}`\n"
        f"エラー: {error_msg}\n"
    )
    if context:
        text += f"詳細: {context}\n"
    payload = json.dumps({"text": text}).encode("utf-8")
    req = urllib.request.Request(
        SLACK_ALERT_URL,
        data=payload,
        headers={"Content-Type": "application/json"},
    )
    urllib.request.urlopen(req)

個人開発ではCloudWatchを毎日確認することが難しいため、異常発生時にはSlackにプッシュする仕組みが有効です。

レート制限の多層防御

サービスに反響があると予想外のトラフィックが来ます。コスト爆発を防ぐため、3層のレート制限を設けています。

IP単位のレート制限は、Lambda実行環境のインメモリで管理しています。

_ip_requests: dict[str, list[float]] = defaultdict(list)
_IP_WINDOW = 60    # 秒
_IP_MAX_REQUESTS = 20

def check_ip_rate_limit(event: dict) -> str | None:
    ip = get_client_ip(event)
    now = time.time()
    # 期限切れエントリを除去
    _ip_requests[ip] = [t for t in _ip_requests[ip] if now - t < _IP_WINDOW]
    if len(_ip_requests[ip]) >= _IP_MAX_REQUESTS:
        return "リクエストが多すぎます。しばらく待ってから再度お試しください。"
    _ip_requests[ip].append(now)
    return None

ユーザー単位の制限はDynamoDBの条件付き更新（ConditionExpression）でアトミックにカウントしており、同時リクエストでも上限を超えることはありません。

コスト設計 ― AWS月額$1で運用可能

本ツールのAWS利用料金は、ユーザー100人超・トラフィックピークありの状態で月額$4程度でした。ただしこの半分以上はCloudWatchカスタムダッシュボードの固定費でした。監視はSlack通知に移行済みでダッシュボードは不要なため削除したので、月額$1程度になる見込みです。個人開発では気づかないうちにダッシュボードが課金要因になるので注意が必要ですね。

実質的な固定費はRoute 53のホストゾーン代（月$0.50）程度で、サービスの維持コストはほぼかかっていません。

ブラウザ完結設計とサーバーレスの組み合わせで意図的に実現しています。

なぜAWS料金がほぼゼロなのか

ポイントは「ユーザーの操作がサーバーに届かない」設計です。

本ツールのコア機能（母音解析・音数カウント・韻検索）はすべてブラウザ内で処理します。ユーザーが歌詞を入力・編集しても、LambdaやDynamoDBへのリクエストは発生しません。サーバーにリクエストが飛ぶのは「AI提案を使う」「楽曲を保存する」という明示的なアクション時のみです。

この設計とAWS無料枠の相性が良く、ほとんどのサービスが無料枠内に収まります。

ユーザーがいない時間帯のコストはゼロ。EC2やECSのような常時起動型のリソースが一切ないため、「誰も使っていない時間にお金が溶ける」という個人開発あるあるが起きません。

コスト爆発の防止

サーバーレスは自動スケールする反面、青天井でコストが膨らむリスクがあります。特にAnthropic APIは従量課金です。
前述のレート制限（API Gatewayスロットリング + IP単位 + ユーザー単位の3層）で流量を制御しています。

個人でも再現できるアーキテクチャ

本ツールのアーキテクチャは、特別な技術を使っていません。すべてAWSのマネージドサービスとOSSの組み合わせです。個人開発で同じ構成を再現するためのポイントを整理します。

トラフィック急増にも耐える：Static Export + CloudFront

Next.jsをStatic Export（ビルド時にHTMLを生成し、静的ファイルとして書き出す方式）でビルドし、S3 + CloudFrontで配信しています。SSR（リクエストのたびにサーバーでHTMLを生成）やISR（一定間隔でHTMLを再生成）は使っていません。ユーザーごとに異なるページを返す必要があるサービス（ECサイト、SNSなど）ではSSR/ISRが有効ですが、本ツールはログイン後もクライアント側で描画が完結するため、静的配信で十分でした。CloudFrontがエッジロケーションからキャッシュ済みの静的ファイルを返すだけなので、アクセス量に関係なく安定して配信されます。

トラフィックピーク時にも一切ダウンしませんでした。「サーバーが存在しない」フロントエンドは、個人開発でトラフィック予測ができない場合に最も安全な選択肢です。

実装上のポイントがいくつかあります。

CloudFront Functionによるパスの書き換え

S3は/aboutのようなパスに対して/about/index.htmlを自動的に返してくれません。CloudFront Functionで解決しています。

function handler(event) {
  var request = event.request;
  var uri = request.uri;
  if (uri.endsWith('/')) {
    request.uri += 'index.html';
  } else if (!uri.includes('.')) {
    request.uri += '/index.html';
  }
  return request;
}

SPAのフォールバック設定

CloudFrontのCustomErrorResponsesで403/404を/index.htmlに転送することで、SPAのクライアントサイドルーティングを実現しています。これをSAMテンプレートに書いておけば再現可能です。

フロントエンドとAPIを単一ドメインで配信

CloudFrontで/api/*のパスパターンをAPI Gatewayに振り分けています。フロントエンドとAPIが同じドメインで動くため、CORSの問題が起きにくく、ユーザーから見ても自然です。

example.com/*      → S3 (静的ファイル)
example.com/api/*  → API Gateway → Lambda

なぜSAMを選んだのか

IaCツールはCDK・Terraform・SAMなど選択肢がありますが、本ツールではSAMを選びました。

• CloudFormationネイティブ：SAMはCloudFormationの拡張であり、追加の抽象レイヤーがない。Lambda + API Gatewayの構成ではSAMのAWS::Serverless::Functionがそのまま最短記法になる
• sam build + sam deployで完結：Lambda関数のパッケージング・アップロード・スタック更新が2コマンドで済む。CDKのようにbootstrapや合成ステップが不要
• Claude Codeとの相性：SAMテンプレートはYAMLの宣言的記述であり、AIが既存構成を読み取って追加・修正しやすい。CDKのようにプログラミング言語で書くIaCよりも、テンプレートの変更差分が明確で、意図しない変更が入りにくい
• 学習コストの低さ：CloudFormationのドキュメントがそのまま使えるため、SAM固有の概念は少ない

CDKはTypeScriptで書ける点が魅力ですが、個人開発程度の規模であればSAMの宣言的な記述で十分です。

SAMテンプレート1枚で全インフラ管理

Lambda + API Gateway + DynamoDB + Cognito + S3 + CloudFront + Route 53のすべてを、1つのSAMテンプレート（724行）で管理しています。

個人開発だとマネジメントコンソールで手作業しがちですが、IaCにしておくと以下のメリットがあります。

• 再現性：環境を壊してもsam deploy一発で復元できる
• 差分管理：インフラの変更がGitのコミットログに残る
• CI/CD連携：mainマージ時にGitHub Actionsが自動デプロイ

Cognito + Google OAuthをSAMで完結

認証基盤もSAMテンプレートに含めています。Cognitoの UserPool・UserPoolClient・GoogleIdentityProvider・カスタムドメインまですべてIaCで管理しているため、認証まわりの設定が「コンソールでポチポチした記憶」で消えることがありません。

API GatewayのJWT認証もSAMテンプレート内で設定しています。

Auth:
  DefaultAuthorizer: CognitoAuthorizer
  Authorizers:
    CognitoAuthorizer:
      IdentitySource: $request.header.Authorization
      JwtConfiguration:
        issuer: !Sub "https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}"
        audience:
          - !Ref UserPoolClient

これにより、認証が必要なエンドポイント（楽曲CRUD、AI提案）と不要なエンドポイント（韻候補、類義語）を宣言的に分けられます。認証不要のエンドポイントは各Lambda関数のイベント定義でAuth: Authorizer: NONEを指定するだけです。

セキュリティヘッダーもIaCで

CloudFrontのレスポンスヘッダーポリシーをSAMテンプレートで定義し、HSTS・CSP・X-Frame-Optionsなどのセキュリティヘッダーを一括設定しています。個人開発だとセキュリティヘッダーは後回しにしがちですが、IaCに書いておけば最初から適用されます。

GitHub Actions：OIDCでアクセスキー不要

デプロイにはGitHub ActionsのOIDC（OpenID Connect）連携を使っています。これは「GitHub Actionsの実行であること」をAWSに証明し、IAMロールを直接引き受ける仕組みです。従来のようにアクセスキーとシークレットキーをGitHub Secretsに保存する必要がなく、キーの漏洩リスクや定期ローテーションの手間がなくなります。

permissions:
  id-token: write
  contents: read
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
      aws-region: ap-northeast-1

Lambda共通モジュール：複数の関数でもコード重複しない

Lambda関数が増えると、認証チェック・レート制限・エラー通知・CORS設定といった共通処理がコピペで散らばりがちです。本ツールでは共通モジュールを1箇所にまとめ、デプロイ時に各関数ディレクトリにコピーする方式を取っています。

GitHub Actionsのデプロイ時に共通モジュールを各関数ディレクトリにコピーするだけです。Lambda Layersは外部ライブラリ（anthropic SDK等）に使い、自前の共通コードはコピーで済ませています。Layersは更新のたびにバージョンが増えて管理が煩雑になるため、この使い分けがシンプルでした。

LLMのプロンプトキャッシング

相談機能（AIchat）では最大100ラリーの会話履歴を保持し、一貫したアドバイスを可能にしています。履歴が長くなるとトークン消費が増えますが、Anthropic APIのcache_controlを使い、直前のメッセージまでをキャッシュ対象にすることでコストを抑えています。

# 最後の履歴メッセージにcache_controlを付与
if history:
    history[-1]["content"] = [{
        "type": "text",
        "text": history[-1]["content"],
        "cache_control": {"type": "ephemeral"},
    }]

また、提案と相談ではシステムプロンプトを分けています。提案は構造化された候補を返すプロンプト、相談は会話の流れを重視した対話型プロンプトを使い分けることで、ユーザー体験の質を上げています。

個人開発でLLM APIを組み込む場合、モデルの使い分けとプロンプトキャッシングの組み合わせでAPI利用料が大きく変わります。

リリースから学んだこと

公開後の反応を振り返って感じた要因です。

• ニッチだが熱量の高い領域：作詞に本気の人は一定数いるが、専用ツールがほぼ存在しない
• 「AIが書く」ではないスタンス：AI全自動生成への懐疑が広がる中、「人間が書く」を支援する方向性が共感を得た

リリース後の継続開発

5日間で初期リリースした後も、ユーザーフィードバックを受けて機能を追加しています。リリース後に追加した主な機能は以下の通りです。

• コード進行管理：各行にコード（Am, G/B等）を記入できるように。バージョン履歴にもコード情報を含めて保存・復元
• バージョン履歴：歌詞のスナップショットを保存し、差分表示（diff）で変更箇所を確認。任意のバージョンに復元可能
• 相談（AIchat）の履歴拡張：3ラリー → 100ラリーに拡大。プロンプトキャッシングと専用システムプロンプトで、一貫したアドバイスを実現
• 歌詞テキスト出力：テキスト形式・ひらがな形式（ボカロへの流し込み用）での歌詞エクスポート
• プロジェクト並び替え：ドラッグ&ドロップで楽曲の順序を変更。最後に開いた曲の自動復元

これらの機能追加もすべてClaude Codeとの対話で実装しています。CLAUDE.mdにアーキテクチャが記載されているため、「バージョン履歴にコード進行のデータも含めて」のような一言で、フロントエンド（型定義・UI）とバックエンド（保存・復元ロジック）の両方を一度に修正できました。

まとめ

Claude Codeを使った開発とサーバーレス運用のポイントをまとめます。

Claude Code活用

1. CLAUDE.mdにプロジェクトの全体像を書く：哲学・アーキテクチャ・データモデル・ファイル構成を記載し、AIとの協業の土台にする
2. メモリでガードレールを設ける：「やってはいけないこと」を永続化して本番環境を守る
3. 判断は人間がする：UIの感覚、動作確認、設計判断は省略しない

サーバーレス運用

1. ブラウザ完結設計でコストを根本から抑える：サーバーにリクエストが届かなければ、コストは発生しない
2. SAMテンプレート1枚でインフラをコード管理する：再現性・差分管理・CI/CD連携のすべてが手に入る
3. レート制限を多層で設ける：API Gateway・IP単位・ユーザー単位の3層でコスト爆発を防ぐ
4. Slack通知で運用を自動化する：日次レポートとエラーアラートの2系統で、一人でも回せる

Claude Codeは開発のスピードと品質を大幅に引き上げてくれます。ただし、あくまで道具です。プロダクトの哲学やUXの判断は人間が握り続ける。この姿勢は、本ツールの「AIが書くんじゃない」という設計思想と似ています。