はじめに
こんにちは。dely株式会社のフロントエンドエンジニアの橘井と申します。
AIツールの進化が著しい昨今、「AIを使えば開発効率が劇的に改善する」という考えのもと、Devin、Cursor、Claude Codeと様々なツールを試してきました。しかし、実際にレガシープロジェクトでAIツールを活用しようとしても障壁が山ほどあります。
これらの問題を分析していく中で、Agentic Code以前の土台整備が必要であることに気付きました。そのため、まずは焦らずに土台作りをすることから始めることにしました。本記事では、レガシープロジェクトでAIの恩恵を最大限受けるために、Claude Codeを活用している事例をご紹介します。
※ 本記事は「【AI特集】3社が語るClaude Code活用 開発組織の取り組みと課題とは？」の登壇内容を拡張したものです。
プロジェクトの背景と直面した課題
クラシルWebプロジェクトの現状
クラシルは「80億人に1日3回の幸せを届ける」をミッションに掲げるレシピ動画プラットフォームです。
私が担当するWebフロントエンドは、2016年に生まれ、現在は紆余曲折あり Rails 依存の Vue2 のレガシープロジェクトとして動作しています。現在は React へのリアーキテクチャを実施している状態です。
フロントエンドのコードベースの規模をおおまかに示すと次のようになります。
- TypeScript：約120,000行
- Vue：約30,000行
- SCSS：約70,000行
この巨大でレガシーなコードベースを、少数精鋭のチームで開発・運用しています。少人数だからこそ密なコミュニケーションが取れる一方で、新規参入者がコードを理解するまでにかなりの時間がかかるという課題も抱えています。
レガシーコードがAI活用を阻む3つの壁
社内でAIが本格導入されたタイミングで、実際にコード生成を試してみました。当初は上手くいけば大幅に生産性が向上すると考えていましたが、現実は甘くありませんでした。レガシープロジェクトには、AIの恩恵を受ける前に解決すべき根本的な問題が3つ存在していたのです。
1. ドキュメント不足による認知コストの高さ
プロジェクトの歴史が10年目に突入する中で、機能実装はされ続けてきましたが、ドキュメントの整備は十分に進められていませんでした。DRY原則が守られていない箇所も多く、似たようなコードが散在している状況です。AIにコードを読ませても、コンテキストが不足しているため、的確な提案や実装ができません。既存の実装コードを見て仕様を推測するしかない状況では、人間もAIも暗黙知となっている仕様を正しく理解することが困難でした。
2. フロントエンドテストの完全欠如
バックエンドの Rails にはテストが存在しますが、フロントエンドにはテストが全く存在しませんでした。テストがないということは、AIが生成したコードの品質を機械的に検証する手段がないということでもあります。また、テストコードはAIに対して期待される振る舞いや仕様を明確に伝える優れたコンテキストとしても機能するため、その点でも大きな障壁となっています。
3. QA負荷の増大とデグレリスク
QAは開発エンジニアとチケット起票者が主に担当していますが、スピーディーにリリースをしたい状況で手動確認に多くの時間を要しています（iOS Safariでのスタイル崩れやエッジケースの対応不足など）。AIが実装したコードも人間がレビューをする必要がありますが、ドキュメントやガードレールが整備されていない状況では、さらに確認項目が増えてしまいます。
これらの問題を抱えたまま安易にAIツールを導入すると、レガシーコードの上にさらに品質の低いコードが積み重なり、手がつけられない状況になりかねません。そのため、まず土台を整えることから始める必要がありました。
AIツール選定の流れ
幸いなことに、弊社では積極的にAIツールを活用できる環境が整っています。私は2025年3月から約3ヶ月間、様々なAIツールを試してきました。
Devin（3月〜5月）
最初に試したのは Devin でした。主に Devin Search でコード調査に活用し、自身でコーディングする際の補助として使用していました。PR作成も試してみましたが、実際にマージを行ったPRは1つだけでした。前述の通りコンテキスト等が不足している状況では、コーディング品質が期待に届かないなどが要因です。「自律的なAIソフトウェアエンジニア」を謳うツールでしたが、レガシープロジェクトの複雑さには対応が難しい状況でした。
Cursor（5月〜6月下旬）
次に試したのは Cursor です。ここで Agentic Code の勘所を掴むことができました。Cursor は使いやすく、多くの開発者に支持されているツールですが、私たちの巨大なコードベースでは、細かくルール整備を行った状態でも、ごくわずかにファイル読み込みと回答速度が期待値を下回りました。（この後に Claude Code の定額プランが登場することが個人的な Cursor 離れの大きな原因にはなっていますが、 Cline 以降のエディターで直接コードを触らせに行くというメンタルモデルを形成できたという点では役立った時期であるとは感じています。）
Claude Code（6月下旬〜現在）
そして現在使用しているのがClaude Codeです。選定の決め手となったのは以下の点でした。
- ToDo機能：自律的にタスクを分解し、順序立てて処理してくれる
- コーディング品質の高さ：生成されるコードの質は（当時）他のツールと比較しても高く感じられ、既存コードのスタイルに合わせやすい
- レスポンス速度：大規模コードベースでも実用的な速度で動作
- Slash commands や Sub Agents：よく使う操作を効率化できたり、コンテキストの消費を賢く削減できる
しかし、それなりに使いやすいツールを利用できるようになっただけでは、レガシープロジェクトの根本の問題は解決しません。次に目指していくステップは、AIが効果的に働ける環境を整えることでした。
Agentic Code までの道のり
理想と現実のギャップ
私たちの開発フローはビジネスメンバーが Notion にチケットを作成し、エンジニアがアサインされて開発、レビューを経てリリースを行うという一般的なものです。このフローにAIを取り入れる理想としては、このチケット自体を Claude Code が読み取り、自動的に実装してくれることにあります。
しかし、現実はそう甘くはありません。これらの作業をAIに行わせようとすると下記のような問題が生じます。
- チケットの表記揺れ（同じページを指すのに複数の呼び方が存在するなど）
- コンテキスト不足によるAIの誤解釈（「ここはこう実装して欲しい」というビジネスロジックへ細かく対応ができない）
- テスト不在によるAIの暴走リスク
これらの障壁を一つずつ、段階的に解決していく必要がありました。
第1フェーズ：ドキュメント整備
JSDoc充実化の取り組み
最初に着手したのは JSDoc の記述徹底です。JSDoc は本来、JavaScript のコードにおける意図や使用方法を説明するための重要なドキュメントですが、私たちのプロジェクトでは人によって書く/書かないの基準が曖昧でした。
まずはコンテキストを増やすために JSDoc を記述することにしましたが、単に「良い感じに JSDoc を追記して」と Claude Code に指示しても、表記揺れが発生します。そこで、以下のプロセスを確立しました。
-
頻出定義の洗い出し
プロジェクト全体でグローバルに使用される定数などを洗い出します。 -
チーム内での擦り合わせ
洗い出した内容をもとに、 Notion で定義の標準化について擦り合わせを行います。 -
段階的なコメント追加
確定した定義をもとに、 Claude Code で段階的に JSDoc を追記します。まずは洗い出した定数自体への追記から始め、次にページコンポーネントへと展開します。各メソッド、変数、関数に対して一つずつコメントを追加していきました。
ユビキタス言語作成の試行錯誤
次に取り組んだのが、DDDの文脈でいうユビキタス言語（用語集）の作成です。開発チーム、ビジネスチーム、そしてAIの3者が同じ認識を持てるようにすることが目的です。
形式の選定では試行錯誤がありました。最初はJSONやYAMLも検討しましたが、最終的にマークダウンのテーブル形式に落ち着きました。理由は以下の通りです。
- 非エンジニアにとって読みやすい
- Notion に配置することを想定
- AIツールを変更しても移植が容易
特にAIのために工夫したのが、「表記統一ルール」と「エイリアス」カラムの追加でした。
※ 以下はこの流れで作成したユビキタス言語の例です
| 用語 (Term) | 意味・定義 (Definition) | エイリアス・同義語 (Alias) | 使用例 (Example) | 表記統一ルール (Standardization Rules) |
| :--- | :--- | :--- | :--- | :--- |
| クラシル | 日本最大級のレシピ動画プラットフォームサービス。レシピ動画、たべれぽ（ユーザー投稿）、プレミアム会員機能などを提供する総合的な料理アプリ・Webサービス。 | Kurashiru | クラシルの月間アクティブユーザー数を集計する。 | 「kurashiru」「KURASHIRU」は「クラシル」に統一。 |
| レシピ詳細ページ | 個別のレシピ動画コンテンツを表示するページ。動画再生、材料・手順表示、たべれぽ閲覧、関連レシピ表示、お気に入り登録などの機能を持つ。URL形式は `/recipes/:id` | レシピ詳細, レシピ詳細画面, 動画詳細ページ | レシピ詳細ページに広告を追加する。 | 「レシピページ」「動画ページ」「コンテンツ詳細」は「レシピ詳細ページ」に統一。「レシピの詳細」等の助詞を含む表現も修正対象。 |
この「表記統一ルール」が、後の自動添削機能で重要な役割を果たすことになります。
このユビキタス言語は JSDoc の内容をもとに、 Claude Code に重要な頻出単語を洗い出させた後、人間が細かくチューニングを行うことで作成をしました。
Zapier 自動添削機能
コード上のドキュメントとユビキタス言語が整ったところで、Notion チケットの自動添削機能を実装しました。Zapier を使用し、以下のワークフローを構築しています。
- Slack で「添削して
https://notion.so/〜」とメッセージ送信 - Notion ページのURL確認とデータ取得
- 事前に作成しておいたプロンプトでAIモデル（GPT-4）が添削を実施
- Slack に添削結果を返信
- 人間が承認後、自動でチケット内容を更新
以下が使用しているプロンプトの一部抜粋の例です。
### Phase 3: 文全体の整合性確認
修正後の文が日本語として自然かを確認
## 3. 出力フォーマット
### 3.1 検出サマリー（必須）
===== 表記統一チェック結果 =====
検査文数: X文
違反検出数: Y件
【違反内訳】
- 省略形の使用: Z件
- 「リスト」単独使用: A件
- 「動画」単独使用: B件
- エイリアスの使用: C件
- 「食べれぽ」: D件
### 3.2 修正提案フォーマット
【違反 #1】
セクション: 背景・目的
原文: 「リストのたべれぽ枠の削除を行う」
検出された問題:
① 「リスト」（位置: 文頭）
→ 修正: 「リスト詳細ページ」
→ 根拠: 用語集#3 - ページ全体を指す文脈での省略形使用
修正文: 「リスト詳細ページのたべれぽ枠の削除を行う」
「ここを守れ」という記載を Phase 1,2 で済ませておき、出力フォーマットや修正提案の方法なども定義するようなプロンプトを用意しています。
ここまでの土台整備を行うことで、「なんとなく」AIに指示を出してコードを出力させていた頃と比較しても、より精度の高い出力を得られるようになりました。
現時点での成果と見えてきた課題
しかし、この取り組みにはまだまだ課題が存在します。
ユビキタス言語の肥大化問題
網羅しようとするコンテキストが増えるにつれ、用語集へ記載する必要のある情報量も増え続けます。このまま際限なく増やし続けると、AIのコンテキストウィンドウを圧迫し、出力精度が低下する懸念があります。現在は、頻繁に開発するコア機能（2, 3ページ）に限定することで対処していますが、根本的な解決策の検討が必要です。
自動化が辛すぎる問題
Zapier の設定は複雑で、デバッグも困難。そして何より、チケット作成頻度は週に数回程度。自動化のコストに見合わないことが分かりました。
現在は、より現実的なアプローチを模索している段階です。現状は無理に自動化をせずとも手元で Claude Code を使って添削するくらいで十分だと考えています。初めからは自動化にこだわらず、本当に必要になったタイミングで再検討するのが筋の良いアプローチだと感じています。
今後の展望：第2フェーズへ
テスト整備によるガードレール作り
現在進行中の React 移行が完了次第、第2フェーズとしてテスト整備に着手する予定です。
- 単体テスト：Jest or Vitest を使用し、まずはビジネスロジックから
- E2Eテスト：Playwrightを検討中、クリティカルパスから段階的に
テストがあることで、リファクタリングや機能追加もより安心して行うことができるようになります。自動テストが存在しないプロジェクトへテストを導入することは非常に困難な取り組みではありますが、AIを利活用できる恩恵を生かし、この難易度の高い課題へチャレンジしたいと思います。
まとめ
8年半のレガシープロジェクトでAIツールを活用するための土台作りは、非常に泥臭いものですが、これらの当たり前で基本的な要素をコツコツと整備していくことが、これからの時代に重要になってくると痛感しています。
最後に、この記事が同じような課題を抱える方々の参考になれば幸いです。
Discussion