メインコンテンツへスキップ
エンジニアリングMar 28, 2026

私たちがClaude CodeでNuxt 4 + Rustモノレポをどう維持しているか

OS
Open Soft Team

Engineering Team

私たちのスタックとClaude Codeが適している理由

Open Softでは、メインプロダクトはモノレポとして構築されたウェブサイトです：TypeScriptのNuxt 4フロントエンドとPostgreSQLバックのRust/AxumバックエンドAPI。コードベースは2つの言語、2つのビルドシステム、共有データコントラクト、データベースマイグレーション、10言語のi18nファイル、デプロイメントインフラストラクチャにまたがっています。変更は頻繁にスタックの両側に同時に影響します。

私たちは2025年半ばにClaude Codeを採用し、最も使用する開発ツールになりました。コードを書いてくれるからではなく、他のツールではできない方法でコードベース全体について推論してくれるからです。Claude Codeに「articlesにpublished_atフィールドを追加して」と言うと、Rustマイグレーションを読み、ハンドラのSQLクエリを更新し、フロントエンドのTypeScript型を修正し、Nuxtページコンポーネントを調整し、10個のロケールファイルすべてを更新し、検証のためにビルドを実行します。このクロススタックの認識が、モノレポ開発で欠かせないものにしています。

CLAUDE.md：エージェントにあなたの規約を教える

効果的なClaude Code使用の基盤はCLAUDE.mdファイルです。これはClaude Codeが各セッションの開始時に読むプロジェクトレベルの指示ファイルです。AIエージェント向けのオンボーディングドキュメントと考えてください。

私たちのCLAUDE.mdには以下が含まれます：

  • コミット規約： すべてのコミットはTASK-XXX:で始まり、命令形を使用
  • アーキテクチャ概要： モノレポ構造、どのディレクトリに何が含まれるか
  • コードスタイルルール： TypeScript strictモード、any禁止、Composition APIのみ、<script setup>構文
  • i18nルール： 10言語すべてを同期、キーをアルファベット順に並べ替え、英語プレーンテキストキー
  • セキュリティルール： コミットに秘密情報なし、パラメータ化SQL、明示的CORSオリジン
  • 開発コマンド： npm run dev、cargo run、make fixturesなど

Claude Codeはこれらの規約に一貫して従います。コミットメッセージを生成する時はTASK-XXX:プレフィックスを使います。翻訳キーを追加する時は、アルファベット順で10個のロケールファイルすべてに追加します。SQLを書く時はパラメータ化クエリを使います。これにより、コードレビューのフィードバックの一カテゴリ全体 — 規約違反 — が排除されます。

# CLAUDE.md抜粋例
## i18nルール
10言語すべてを同期に保つ必要があります。翻訳キーを追加する時：
1. キーフォーマット：キーとして英語プレーンテキストを使用
2. アルファベット順：すべてのロケールファイルでキーをA-Z順にソート
3. すべてのロケールが必要：en、ru、id、zh、ja、ko、fr、de、es、ar

バックエンド（/server/CLAUDE.md）とフィクスチャ（/server/fixtures/CLAUDE.md）にはディレクトリごとのCLAUDE.mdファイルも維持しており、Claude Codeがそれらのディレクトリで作業する時にアクティブになるコンテキスト固有の指示を提供します。

マルチファイルリファクタリング：キラーユースケース

最も時間を節約するワークフローはクロススタックリファクタリングです。プロジェクトからの実例を紹介します。

タスク： articlesシステムにSEOフィールド（meta_title、meta_description、focus_keyword、robots_meta）を追加する。

Claude Codeなしでは、この変更に必要なこと：

  1. 4カラムを追加するSQLマイグレーションの作成
  2. Rust Articleモデル構造体の更新
  3. Rust CreateArticleとUpdateArticle DTOの更新
  4. articlesハンドラの全SQLクエリの更新（SELECT、INSERT、UPDATE）
  5. フロントエンドのTypeScript Article型の更新
  6. 管理エディタフォームの新フィールド追加
  7. ブログ記事ページのmetaタグレンダリング更新
  8. サイトマップ生成ロジックの更新
  9. 全フィクスチャファイルの新フィールド更新
  10. マイグレーション実行、リビルド、テスト

Claude Codeを使えば、コマンドを一つ入力するだけ：

articlesにSEOフィールド（meta_title、meta_description、focus_keyword、robots_meta）を追加。
マイグレーションを書き、Rustモデルとハンドラを更新し、フロントエンドの型と
管理エディタを更新し、ブログページにmetaタグを追加し、フィクスチャを更新。

Claude Codeは単一のエージェントループとして実行します：

  • 既存のマイグレーションファイルを読んでスキーマを理解
  • Rustモデルを読んで現在の構造体を理解
  • ハンドラを読んで全SQLクエリを発見
  • フロントエンドの型とコンポーネントを読む
  • 12+ファイルにわたる全変更を実行
  • cargo checkでRustコードのコンパイルを検証
  • npm run buildでフロントエンドのビルドを検証
  • エラーを修正し、両方が通るまでイテレーション

プロセス全体は約5分で、手動では45-60分かかります。さらに重要なのは、人間が見落とすクロスリファレンスバグを検出すること — UPDATEクエリに新カラムを追加し忘れたり、フィクスチャファイルを見落としたりすることです。

マイグレーション作成

データベースマイグレーションは、現在のスキーマ、望む最終状態、その間の安全な変換パスの理解を必要とするため、Claude Codeに特に適しています。

Claude Codeにマイグレーションの作成を依頼すると：

  1. 既存の全マイグレーションファイルを読んで現在のスキーマを理解
  2. Rustモデルを読んでターゲット状態を理解
  3. 適切なALTER TABLE文でマイグレーションSQLを作成
  4. 適切な場所にIF NOT EXISTSガードを追加
  5. 可逆マイグレーションを使用する場合、対応する「ダウン」マイグレーションを作成
  6. 新スキーマを使用するようにRustモデルとハンドラを更新

テスト生成

テストフィクスチャとSQLシードデータの生成にClaude Codeを広く使用しています。フィクスチャファイルには適切なSEOメタデータ付きの現実的な長文コンテンツ（1500+語の記事）が含まれ、手動で書くのは退屈でエラーが起きやすいです。

ワークフロー：

  1. 必要な記事を記述（トピック、角度、技術的深さ）
  2. Claude Codeが完全なMarkdownコンテンツ付きのSQL INSERT文を生成
  3. UUID規約に従う（d0000000-...は記事、a0000000-...はカテゴリ）
  4. 冪等性のためON CONFLICT (slug) DO NOTHINGを追加
  5. article_tagsジャンクションテーブル経由で記事をタグにリンク

Claude Codeによるコードレビュー

マージリクエストを開く前に、Claude Codeをレビュアーとして実行します：

このブランチの全変更をバグ、セキュリティ問題、パフォーマンスの問題、
CLAUDE.md規約との一貫性についてレビューしてください。

Claude Codeは：

  • git diff main...HEADを実行して全変更を確認
  • 各ファイルの潜在的な問題を分析
  • SQLインジェクション（非パラメータ化クエリ）をチェック
  • 10言語すべてでi18nキーの存在を検証
  • Rustプロダクションコードの.unwrap()呼び出しをチェック
  • エラーハンドリングがパターンに従っているか検証
  • ファイルパスと行番号付きの発見を報告

人間のコードレビューで見つかる問題の約30%を検出し、人間のレビュアーがアーキテクチャとビジネスロジックに集中できるようにします。

フック：品質ゲートの自動化

Claude Codeはフック — 特定のアクションの前後に自動実行されるスクリプト — をサポートしています。品質を強制するためにフックを使用しています：

プリコミットフック： Claude Codeがコミットを作成する前にcargo fmt --checkとcargo clippyを実行。どちらかが失敗するとClaude Codeが問題を修正して再試行。

ポストエディットフック： Claude Codeが/i18n/locales/のファイルを修正した後、10個のロケールファイルすべてが同じキーセットを持つかを検証するスクリプトを実行。キーが欠けていればClaude Codeが追加。

MCPサーバー：Claude Codeの能力を拡張

Model Context Protocol（MCP）サーバーはClaude Codeに外部ツールへのアクセスを提供します。2つのカスタムMCPサーバーを実行しています：

  1. データベースMCPサーバー： Claude Codeが開発PostgreSQLに直接クエリ可能。データ問題のデバッグ時に、SELECTクエリを実行して実際のデータベース状態を検査し、問題を理解し、修正を書く — すべて一つのループで。

  2. デプロイメント状態MCPサーバー： CI/CDパイプラインに接続。Claude Codeが最新のデプロイメントの成否を確認し、ビルドログを読み、失敗を診断 — CIダッシュボードへの切り替え不要。

1Mコンテキストでの大規模コードベースのヒント

Claude Codeの1Mトークンコンテキストウィンドウは、モノレポ作業で最も強力な機能です：

Claude Codeに探索させる。 どのファイルを見せるか事前選択しようとしないでください。何が欲しいかを記述し、Claude Codeにツール（Grep、Glob、Read）を使って関連コードを見つけさせましょう。

安定したコンテキストにCLAUDE.mdを使う。 セッション間で変わらない情報 — アーキテクチャ、規約、コマンド — はCLAUDE.mdに入れ、Claude Codeが再発見にコンテキストを浪費しないようにします。

メガタスクをフェーズに分割。 1Mトークンあっても、「認証システム全体をリファクタリング」のようなタスクはフェージングが有益：まず分析と計画、次にモジュールごとの実装、最後にテスト。

エージェントループを信頼する。 Claude Codeが変更を加え、ビルドを実行し、エラーを見つけ、修正する時 — そのループが機能です。途中で中断しないでください。収束させましょう。

落とし穴と回避策

落とし穴：Claude Codeの過剰設計。 不要な抽象やパターンを追加することがあります。回避策：CLAUDE.mdに「KISS — シンプルに保つ。過剰設計を避ける。」を追加。

落とし穴：長いセッションでの古いコンテキスト。 多くの編集後、Claude Codeの現在のファイル状態の理解がずれることがあります。回避策：各主要タスクで新しいセッションを開始。

落とし穴：非決定的な出力。 同じプロンプトで異なるコードが生成されることがあります。回避策：具体的で詳細なプロンプトを使用。

落とし穴：テストデータの品質。 AI生成のテストデータが内部的に不整合な場合があります。回避策：生成されたフィクスチャを常にレビューし、フルテストスイートを実行。

落とし穴：積極的なファイル変更。 Claude Codeが依頼していないファイルを変更することがあります。回避策：受け入れる前に差分を注意深くレビュー。

FAQ

Claude Codeの日常使用コストは？

4人の開発者チームで、全プロジェクトのClaude Code API使用に月約200-300を費やしています。開発者あたり月20のMaxプランはより予測可能な代替手段です。

Claude Codeはオフラインで使えますか？

いいえ。Claude CodeはAnthropicのAPIとの通信にインターネット接続が必要です。

Claude Codeはビルドを壊しますか？

はい、しかしほとんどの問題は自分で検出します。Claude Codeはエージェントループの一部としてビルドコマンドを実行します。cargo checkが失敗するとエラーを読んで修正します。経験上、約90%のビルドが最初のパスで成功し、99%がClaude Codeの自己修正ループ後に成功します。

秘密情報と環境変数はどう扱っていますか？

Claude Codeは.gitignoreを尊重し、機密ファイルを除外するよう設定できます。リポジトリに秘密情報を保存することはありません。

Claude Codeはソロ開発者に適していますか？

もちろんです。ある意味ではソロ開発者にとってさらに価値があります — コードレビューの第二の目、プロジェクト規約を記憶する知識ベース、退屈なタスクの力の増幅器として機能します。

結論

Claude Codeはアプリケーションを書いてくれる魔法の杖ではありません。クロススタック推論、規約の強制、退屈なマルチファイル変更に優れたフォースマルチプライヤーです。永続的なプロジェクト知識のためのCLAUDE.md、品質強制のためのフック、外部ツールアクセスのためのMCPサーバーの組み合わせが、モノレポ作業で使用した中で最も有能なAI開発ツールにしています。

9ヶ月の日常使用後の重要な洞察：Claude Codeが最も価値を発揮するのは新しいコードの作成ではなく、既存コードの保守 — リファクタリング、マイグレーション、テスト、レビューです。これらは開発者の時間の70%を消費し、コードベース全体を理解するエージェントから最も恩恵を受けるタスクです。

タグ
AIDevOpsNuxtRustTypeScript