リアーキテクチャでClaude Codeを8ヶ月使い込んで分かった「任せること」と「握ること」の境界線
この記事は5名のフロントエンドチームのリーダーとして、既存アプリのリアーキプロジェクトの開発業務でClaude Codeを約8ヶ月間運用した記録です。
2つのアプリのリアーキテクチャを通じて見えてきた、AIに任せてよい仕事と、人間が握るべき判断の境界線について書いていきます。
背景
- チーム規模: 5名のフロントエンドチーム
- AIエージェントへの投資額: $200 / 月（Claude Max 20xプラン） × 5名 = $1,000 / 月
- 対象: Vue2 → Reactのリアーキテクチャプロジェクト（2アプリ、合計PR数215本）
技術選定やアーキテクチャの設計判断については別の記事で書く予定ですので、ここではAIエージェントの活用に焦点を絞ります。プロジェクト自体の予算確保の話も別の記事に譲ります。
導入スパンは先行者2名（私とシニアエンジニア1名）が同時期に使い始めてから約1週間でメンバー全員のマシンにインストール、CLAUDE.mdの初回コミットから約1ヶ月で全員がほぼ全てのコミットでClaude Codeを利用する状態になりました。
MCPの導入などの環境整備はメンバーへの普及をしながら並列で進めました。
開発ワークフローへの影響
「まず書かせて判断する」への移行
AI導入によって最も開発速度の向上を感じるのは、アプローチが複数あり意思決定が難しい場面で「とりあえず書かせてみる」という選択肢を取れるようになったことです。導入以前はコードに落とす前に複数の選択肢を頭の中やドキュメントで検討するのに時間を使っていましたが、実装を見てから判断するスタイルに変わりました。肌感覚ですが、以前では1日かかっていた開発タスクが2時間程度に短縮されるようなことは珍しくないと思います。
ただし、この手法を全体設計にまで適用してしまった際には、深刻なコード品質の低下を招いてしまいました。
詳しくは「設計における主導権」で後述します。
コードレビュー観点の変化
レビューの観点も変わりました。AI導入前は実装の正しさや詳細レベルの設計の確認が中心でしたが、導入後は設計意図の確認や、トレードオフの検討が人間主導で行われたかの確認にシフトしました。
副次的な効果として、全員が同じAIエージェントで開発することでコードのスタイルが均一化されました。メンバーごとの書き方のクセが減り、コード理解にかかる認知負荷が下がりました。
PRサイズ
チームに導入する前はコードの生産量が上がることでPRサイズも大きくなると予想していましたが、予想に反して概ね400行以下の適正サイズを維持しました。
| 1つ目のアプリ | 2つ目のアプリ | |
|---|---|---|
| 400行以下の割合 | 86% | 77% |
| Claude Code使用PRの変更行数（中央値） | 177行 | 212行 |
| 非使用PRの変更行数（中央値） | 54行 | 63行 |
| co-authorタグ付与率 | 25% | 29% |
Claude Code使用PRの変更行数が大きいのは、新機能実装やリファクタリングなど比較的大きな変更に集中して活用されたことを示唆しています。co-authorタグ（Claude Codeにコミットまで実行させた場合に付与されるタグ）の付与率は低いですが、これはClaude Codeで生成したコードを人間がコミットする運用が大半だったため、実際の利用率を大きく下回る下限値です。体感では、チームにClaude Codeが定着した後はほぼ全てのコミットに何らかの形でClaude Codeを利用しており、実態としては9割以上だったと推定しています。
理解負債の蓄積
起きたことは改善ばかりではなくAIエージェントに実装を任せることで、「動くが、なぜそう書かれたか開発者自身が理解していないコード」、いわゆる理解負債が蓄積する現象が起きました。技術的負債とは異なり、コード自体の品質には問題がないこともあります。しかし書いた本人が仕組みを把握していないことで、変更時の判断コストやインシデント時の対応コストが上がります。
これが顕在化したのは、2つ目のアプリのリファクタリング時でした。特定のコンポーネントやカスタムフックがどういう意図で切り出され、どういう責務を持つか、メンバーの誰も把握できていないことがありました。薄々懸念はありましたが、明確に問題として認識されたのはこのタイミングです。
この理解負債への対処として機能したのが、毎日のPR同期レビュー会、チーム内で「マージの儀」と呼んでいる仕組みでした。PR作成者が画面共有しながらメンバーにコードの意図を説明し、直接フィードバックを受けるレビュー会で、リアーキプロジェクト開始当初から運用していました。AI導入以前から存在していた仕組みですが、AI導入後にその効果を強く発揮するようになりました。詳細は次のセクションで書きます。
チームへのClaude Code導入で直面した課題と対処
チームにClaude Codeを導入する過程で、2つの課題に対処し、1つの課題が未解決のまま残っています。
スキルレベル別のAIリテラシー格差
Claude Codeの導入時にはスキルレベルごとに異なる実用上の課題がありました。
ざっくりとまとめると、
シニアでは「自分が納得できる品質のコードが出力されず、修正が必要だから結局自分で書いたほうが早い」
ジュニアでは「使い方がわからない」「出力されたコードの正しさが判断できない」
というものでした。
自分はチームリーダーの立場だったこともあり、かなり好意的に捉えていたため先行して積極的に使い始めました。シニアメンバーもほぼ同時期に使い始めており、チーム内での導入への温度差は小さかったです。
スキルレベル別に異なる施策を打ちました。
ジュニアの「使い方がわからない」に対しては、まずユースケースと効果をデモしたりドキュメントを書いたりして最低限の使い方を周知しました。そしてMCP導入やカスタムサブエージェントの作成などを行い、基本的には意識せずとも出力品質が向上する仕組みを作りました。
シニアの「品質が低い」に対しては、サブエージェントによる探索で推測を排除し根拠を持った提案を実現できることを示しました。ただし正直に言えば、シニアに対してはチームとして積極的に介入したというよりも、ツールの性能向上と本人の慣れが解消の主因でした。
MCP導入やカスタムコマンド作成といった基盤整備のコストはかかったものの、得られたリターンが大きかったです。
総括すると、効果的に使えるように環境を整えて提供し、使って慣れてもらうことで解決しました。
コード品質の担保
2つ目の課題は「AIが生成したコードの品質をどう担保するか」のルールがなかったことです。ここで「マージの儀」が品質担保の核として機能しました。
マージの儀は以下のように運用しています。
- 日次で16時から開催
- PR作成者が画面共有しながらメンバーに変更内容を説明し、レビュワーから直接フィードバックを受ける
- 所要時間はPRの数と内容により30分から1時間程度
- プロジェクト初期は可能な限り全員が参加し、プロジェクト後半ではレビュワー2名以上で実施
PRの内容によってレビューが欠かせないエンジニアが時間を取れない場合、一般的なレビューのようにGitHub上で非同期にコメントし、当日のマージの儀でコメント内容を議論するようにしました。
日次で時間を取られるので負荷が高い施策ですが、これを続けられたのは以下の3点が大きいと考えています。
- レビュワーとレビュイー双方が品質担保に効果を感じていた
- 既存のレビュー作業を同期的に行う形態であり、レビュー工数の純増ではなかった
- 日次でチームがコミュニケーションを取る良い機会になっていた
マージの儀を廃止してもレビュー工数自体は発生するので、非同期レビューの代替として位置づけています。
AI導入後、この仕組みが品質担保に強く効くようになりました。意図を説明できない変更はリジェクトするルールが自然に生まれ、理解負債の蓄積を防止する機能を果たしました。
プロジェクトが一時的に止まっている現在も、フロントエンドのコード品質をプロジェクト横断で担保する仕組みとして同じ密度で運用を続けています。
AIエージェント活用時のレビュー判断基準
AIが生成するコードには過剰に高度・複雑な実装が含まれることがあり、これをチームで「AI臭いコード」と呼んでいました。ただし一律にリジェクトするのではなく、判断基準を設けました。
-
許容する例：ループ内の
findによる線形探索を、事前に構築したMapオブジェクトを利用した探索に置き換え、検索コストを最適化する → パフォーマンスに実質的な意味がある - リジェクトする例：Compound Componentsパターンの不要な適用 → 利用箇所が1箇所で、メンバーから「分かりづらい」「過剰」と意見が出て削除しました
判断基準は「その高度さに実質的な意味があるかどうか」でした。
未解決の課題：セキュリティリスクへの対応
3つ目は現在進行形の課題です。
Claude CodeをはじめとしたAIエージェントの利用にはセキュリティリスクへの懸念がありますが、完全に対応できているとは言えない状態です。
当初チームでは主な懸念が2つありました。悪意のあるMCPサーバーの利用によるコードやデータの流出リスクと、.envファイルなどの読み込みによるAPIキー等の秘匿情報の意図しない流出です。
現状実施している対策は、.envファイル等へのAIエージェントのアクセス制限と、信頼性が不確かな提供元のMCPサーバーの導入禁止です。しかし発生しうるセキュリティリスクは多岐にわたり、網羅的な把握がまだできていません。ガイドラインの整備と対策はこれからも行なっていきます。
設計における主導権
2つのアプリのリアーキテクチャで、AIに任せる範囲が異なった結果、コード品質に大きな差が出ました。
前提として、この2つのアプリではFeature-basedアーキテクチャを採用し、機能単位でディレクトリを分割する設計方針でした。Feature間の依存関係はESLintルール（import/no-restricted-paths）で機械的に強制していました。ただしこのルールは境界違反のインポートを防ぐだけであり、featureの切り出し自体が不自然であれば設計上の問題は防げません。
成功例: 1つ目のアプリ
全体設計（featureの切り出しと共通処理の決定）は完全にモブで人間が主導しました。詳細設計まで完全には詰めることはせず、feature/store/コンポーネントのまとまりレベルで設計を固めました。
チーム全体へのAI導入は途中からで詳細設計と実装にAIを活用しましたが、コード品質が顕著に低下することなく実装を完了できました。
失敗例: 2つ目のアプリ
1つ目のアプリで設計フェーズが重かったことはチームの共通認識でした。2つ目のアプリで「とりあえずAIにディレクトリ構成を出させよう」という意見がチーム内で自然発生的に出ました。アプリの規模が小さかったこともあり、設計フェーズを短縮してClaude Codeに提案させたディレクトリ構成を元に開発を進めました。これはあくまで叩き台のつもりでしたが、十分に検討しないまま採用してしまったことは事実です。
こうして振り返ると明らかに軽率な判断ですが、当時はClaude Codeの導入直後で過剰にAIエージェントに対する信頼が高まってしまっていたり、プロジェクトの期日への焦りであったりなど複合的な要因でこのような判断をしてしまったのだと考えています。リーダーとして、1つ目のアプリと同じように設計フェーズに時間を確保すべきでした。1つ目の成功体験と「設計が重かった」という意見に引きずられ、初期の設計コストを削る判断を止められなかったことは自分の責任だと痛感しています。
結果として、具体的に2つの問題が起きました。
1つは、特定のfeatureが肥大化してしまったことです。小さいアプリとはいえ基本機能全てに責任を持つようなfeatureができてしまっていました。リファクタリング時にfeature内にサブfeatureを作成して対処しましたが、正直に言うとこれはより良い解決策があったように思います。
もう1つは、認証状態が共通部分に残っていて共通処理を肥大化させていたことで、これをfeatureとして分離させる作業が困難で最も影響が深刻でした。
リカバリには段階的なリファクタリングで対応しました。経営レイヤーに対しては「最低限のコード品質に達していないのでリファクタリングが必要」と事実ベースで報告し、予定期間より1ヶ月超過して完了しました。ある程度改善はしましたが、当初からfeatureをより自然に切り出せていれば、より疎結合でロジックや状態を綺麗に分離できたのではないかという感覚が残っています。
教訓
当たり前のことのようですが、アプリのアーキテクチャレベルの設計は人間が主導すべきです。モデルの進化によりこの境界線は変わりえますが、少なくとも2025〜2026年時点のモデル性能では画面数が5画面程度のごく小さいアプリでも設計が破綻する可能性があります。
AIの実装は恐ろしく早いので、叩き台のつもりで作り始めてもリファクタが困難になる程にコード量が増え、仮設計が既成事実化する恐れがあります。
詳細設計・実装はAIに任せても全体設計の品質が十分に高ければある程度品質を維持できます。だからこそ全体設計の決定は人間のリソースを十分に投じて、考え抜いて意思決定を行う必要があります。
また、全体設計以外にも、AIが苦手な領域はあります。コンテキストに収まりきらないほど巨大な既存コード全体の仕様把握は精度が下がる傾向が強いです。ビジネスロジックの判断なども、コンテキストを適切に渡すのはかなり難しいため苦手な領域だと考えています。「AIに任せてよい仕事」の境界線は、全体設計 vs 詳細実装という軸に加えて、コンテキストの大きさとドメイン知識の必要性という軸でも引く必要があります。
前述の「まず書かせて判断する」スタイルは、詳細実装レベルでは有効に機能しました。しかし全体設計にまでこのアプローチを適用した結果、失敗しました。この二面性を理解することが、AI活用の成熟度を測る一つの指標になると考えています。
責任の所在
「AIが書いたコードの責任は誰にあるのか」について、チームで明示的に議論の場を設けたことはありません。当然にエンジニアにあるからです。「Claudeが書いたのでわかりません」とは言わない、という感覚は最初からメンバー全員にありました。
ただし、マージの儀で毎日PRの意図を説明し合う中で、「実装者が意図を把握していない変更は通さない」というルールが形成されました。ここで振り返ると、マージの儀は結果的に3つの機能を同時に果たしていました。理解負債の防止、AI生成コードの品質担保、そしてこのセクションで述べた責任の暗黙的な形成です。この3つは別々の課題として認識していましたが、1つの仕組みが同時に解決していました。
PRレビューでは「戦略的にトレードオフができているか」を確認するようになりました。抽象化 vs 具体（どの粒度で共通化するか）、コンポーネントを分割する/しないといった判断が、AIに委ねられず人間が行ったかどうかを確認する観点です。
これからチームに導入する人へ
導入プロセス
導入は2つのフェーズが並列で進みました。
環境整備フェーズ: MCP導入、ドキュメント整備、スキルやエージェントの作成
普及フェーズ: 先行者2名がほぼ同時期に使い始め、約1週間で全員のマシンにインストールされ、CLAUDE.mdの初回コミットから約1ヶ月で全員・全コミットに使う程度まで浸透
このように環境整備と普及が並行してできたのは、以下のような条件があったからだと思います。
- チームサイズが小さかったこと
- リアーキという新規開発寄りのプロジェクトだったこと
- 先行者が基盤整備を事前に済ませていたこと
チームサイズが大きい場合は段階的な導入の方が適切でしょう。
チーム運用で効いた知見
まず重要なことですが、プロンプトの書き方の標準化はしませんでした。 AIエージェント自体が発展途上であり、標準化をするには時期尚早だと考えたためです。代わりにCLAUDE.md整備やカスタムコマンドで環境側から品質を底上げするようにしました。
また、AIエージェントを利用するにあたって得られたナレッジの共有はメンバー間の雑談などで日常的に行うようにしました。
チームとして「何を共通化し、何を個人に委ねるか」の線引きを振り返ると次の通りです。
- 共通化したもの：CLAUDE.md、MCP構成、カスタムコマンド
- 個人に委ねたもの：プロンプトの書き方、セッションの切り方の粒度
ご参考までに特に効いたClaudeCodeのナレッジを3つ挙げます。
1. メモリーを利用したセッションの細かな分割 プロジェクトルートにgitignoreした.tmpディレクトリを作成し、ここにmarkdownファイルを作成させることでメモリー（セッションをまたげる一時記憶）として使います。調査結果やプランニング結果を記載することでセッションを細かく分割できるようになります。セッション間の引き継ぎ時など、度々.tmp内のファイルを人間もチェックして、タスクの認識のズレがないかを必ず確認します。
2. 環境側の品質底上げ CLAUDE.mdにESLintルールの定義やプロジェクト固有の規約を記載し、Skillsやカスタムサブエージェントで出力品質を自動的に向上させ、MCP導入でコードベースの理解精度を向上させました。これはプロンプト標準化の代替として機能しました。
例えば、既存コードの調査時に推測を含めず必ず根拠を持って回答するcode-investigatorというカスタムエージェントを作成し、コンテキストが不足している場合はその旨をユーザーに伝える仕組みにしました。公式のExplorer agentが存在する現在でも、信頼性の高い既存コード調査エージェントとして活用しています。
3. サブエージェントによるコンテキスト効率化 調査などセッション内で独立して実行できるタスクは徹底的にサブエージェントを活用しています。そうすることでセッションのコンテキストを圧縮でき、かなり精度が向上します。
CLAUDE.mdに書いても見落とされがちなので度々プロンプトでも指示する運用をしているのですが、この点は改善の余地があると思っています。
その他の補足
CLAUDE.mdの運用
- 常に必要な最小限のルールを記載します。肥大化すると指示が無視される原因になります。
MCP構成
- 全リポジトリで共通導入したMCPサーバーは以下のものです
- Serena
- Context7
- Notion
- GitHub
- Playwright
- sequential-thinking
自動検証
- Hooks、テスト、Linterによる自動検証で機械的に防げるものは自動化しています
Auto Memoryについて
- 2026年2月時点では、公式のAuto Memory機能より、プロジェクトルートに.tmpディレクトリを置きメモリーの内容を人間が把握・管理する方針の方が制御しやすいと判断しました
- Claude Codeは改善が続いているため、この判断は今後変わる可能性があります
効果測定の反省
1つ目のアプリの完成時に、マイルストーン達成報告の中でAI導入結果を報告しました。しかし、厳密にAIエージェント導入による効果測定はしきれていませんでした。
リアーキプロジェクト以前も対象にPRサイクルタイムの前後比較を試みましたが、交絡要因が多すぎて因果推論は困難でした。
主な交絡要因は、プロジェクトの性質の違い、チーム習熟度の変化、タスクの性質の変化、開発者の変動です。
計測基盤を導入前に整えていなかったことが根本的な原因であり、これ自体が学びでした。
厳密な計測はできませんでしたが、メンバー全員がClaude Codeなしの開発には戻りたくないと感じており、これはチームとしての一致した実感です。$1,000/月の投資に対して定量的な根拠で継続を正当化したわけではなく、「全員が手放せないという実感」をもって利用を継続しています。
AIエージェントを活用した開発は今後当たり前になるという認識がCTOにもあったことも大きいです。
ただ、定量的な測定ができていればよかったという反省はかなり強くあります。
もしこれからAIエージェントの導入を行うのであれば、以下のようなことは役に立つかと思います。
- 導入前のベースラインのPRサイクルの時間を計測しておく
- Claude Code関与率（co-authorタグ等）を初期から記録する
- 定性アンケート（月次のチーム満足度・生産性実感）を併用する
- 交絡要因を記録し、AI導入の効果とその他の要因を切り分ける設計にする
- 機能リリースのリードタイムや手戻り頻度も計測対象に含める
2026年2月時点の記録として
ツール固有の知見は変わりえますが、以下は普遍的だと考えています。
- 全体設計の主導権は人間が握る
- 運用の仕組み（私たちの場合はマージの儀）で品質と責任を日常的に確認し続ける
- AIには詳細実装を任せても、構造の決定と説明責任は手放さない
今の私の目線ではAIに任せてよい仕事と、人間が握るべき仕事の境界線が少し見えてきました。
この試行錯誤の記録が、誰かのお役に立てば幸いです。
この記事では省きましたが、そもそもこのプロジェクト自体をどう始めたか、組織の技術投資をどう動かしたかは、次の記事で書きます。
また、Vue2→Reactの技術選定で悩んだポイント（Feature-basedの設計判断やテスト戦略等）も別の記事でまとめる予定です。
Discussion