AI Agentのアウトプットに『Next.jsの考え方』を反映するプラクティス
AI Agentの進化は目覚ましく、日々実装の品質も向上しています。しかし、開発者自身に明確な実装イメージがある場合、それをAI Agentに出力させることは難しく、さまざまな工夫を必要とします。Agentに与えるコンテキストやプロンプトを最適化したり、詳細なルールを整備することで精度を高めることができますが、これらには大変な労力を伴います。
筆者がNext.jsアプリケーションを扱う場合、実装イメージは著書『Next.jsの考え方』の内容に沿って生成されるため、「この本をAI Agentに読ませることで、アウトプットの精度を高めることができるのではないか」と考え、様々な検証を行いました。
本稿では検証を通して筆者が得た、AI Agentのアウトプットに『Next.jsの考え方』を反映するプラクティスについて紹介します。
要約
以下の条件を満たすことで、AI Agentのアウトプットに『Next.jsの考え方』の設計やプラクティスを反映できる可能性が向上します。
- 適切に設計された静的解析と単体テスト
- 『Next.jsの考え方』に沿って実装されたリファレンス実装
- AI Agentが『Next.jsの考え方』を都度参照するようなルール設定
前提
AI Agent
筆者が検証に用いたツールとモデルは以下の通りです。
- AI Agent: Claude Code, Cursor
- AI Model: Claude 4 Sonnet
『Next.jsの考え方』
Next.jsの根底にある考え方に沿った設計やプラクティスについて、筆者なりに解説したものです。
GitHub上で原著を参照できます。
解説
検証に用いたリポジトリは以下です。
筆者が検証した結果、以下の工夫をすることでAI Agentのアウトプットに『Next.jsの考え方』の設計やプラクティスを反映できる可能性が向上しました。
適切に設計された静的解析と単体テスト
『Next.jsの考え方』を活かすかどうかに関わらず、AI Agentを使用する場合、静的解析と単体テストは非常に重要です。AI Agentの実装が想定通りに振る舞っているかどうか、また既存の振る舞いに影響していないか、既存の実装とルールの整合性が取れているかなどの観点をAI Agent自身が確認できることは、AI Agentの実装精度を高める上で非常に重要です。特に、Claude 4 Sonnetは静的解析や単体テストのフィードバックをもとに改善のサイクルを回すことに長けており、Claude 4 Sonnetと静的解析や単体テストの組み合わせは非常に効果的です。
筆者が行った検証では以下のツールを使用し、AI Agentに都度アウトプットした実装のチェックを実施させました。
- Biome
- TypeScript
- Vitest
画面やStorybookの状態を確認するためにMCPサーバーを用意するのも効果的です。
余談: StorybookのAOM取得用MCPサーバー
筆者は特にStorybookのAOM（Accessibility Object Model）を取得するMCPサーバーを用意することを好みます。これにより、AI AgentはStorybookのコンポーネントの状態を正確に把握し、実装の精度を向上させることができます。
具体的には、http://localhost:6006/iframe.html?globals=&args=&id=${id}&viewMode=storyのようなURLを作成し、PlaywrightからChrome Devtools Protocol（CDP）を使用してAOMを取得するMCPサーバーのメソッドを実装します。
なお、スクリーンショットを取得することもできますが、AI Agentは画像から文字情報を読み取ることが苦手なので、筆者はAOM取得を好んで採用します。
『Next.jsの考え方』に沿って実装されたリファレンス実装
昨今のAI Agentは、リポジトリ内の既存実装を強く学習する傾向にあります。CLAUDE.mdや.cursor/rules/*などのルールドキュメント内に実装例を記載することも効果的ですが、筆者の体感ではリポジトリ内の実装の方が強く学習されるように感じます。
ルールと既存実装で乖離しているとAIが混乱し精度が低下する可能性もあります。ルールと整合性が取れた実装をリポジトリ内に用意しておくことは非常に重要です。
AI Agentが『Next.jsの考え方』を都度参照するようなルール設定
AI Agentに『Next.jsの考え方』を読ませるためには、マークダウンファイルが最適だと考えられます。『Next.jsの考え方』はZennで無料公開しており、原著はパブリックリポジトリで管理されています。
git cloneするなりGitHubからダウンロードするなり方法は様々ですが、これらのマークダウンファイルをコピーしてNext.jsのアプリケーションのリポジトリ内に配置します。これにより、AI Agentは任意のタイミングで『Next.jsの考え方』を参照できるようになります。
ルールはClaude Codeで/initで生成したものをベースに、『Next.jsの考え方』の格納場所や読むべきタイミングなどを設定します。以下は、筆者が実際に使用したルールの一例です。各々のプロジェクトに合わせて調整してください。
評価
筆者が検証した結果、上記の条件下でAI Agentのアウトプットに『Next.jsの考え方』の内容が反映され、筆者が求める品質に対して精度が向上することが確認できました。
特に『Next.jsの考え方』の必要な箇所を都度読ませることで、AI Agentの実装理解度がより高いものになると感じました。『Next.jsの考え方』を読ませなかった場合、AI Agentのアウトプットは表面的な理解に基づくレベルに留まるため、一定以上のフィードバックや自身での修正作業が伴います。一方、『Next.jsの考え方』を読み込ませるとしっかり読者レベルの理解度に基づいた実装が行えるようになったと感じました。これにより、より多くの作業をAI Agentに委任できるようになると筆者は感じています。
特に、筆者が難しいだろうと予想していたDataLoaderを使った設計や、筆者なりのVitestやStorybookの観点の出し方がとても高い精度で行えることを確認できたので、筆者としては自分自身の思想が強く反映されたAI Agentのように感じました。
注意点
検証の過程で、AI Agentの精度に影響する要素がいくつかあることがわかりました。
『Next.jsの考え方』の要点のみをルール設定すると精度が低下する
CLAUDE.mdに『Next.jsの考え方』の要点を記載することで、都度AI Agentが読みに行くことで発生するコンテキストやトークンの消費量を抑えつつ同様の精度を実現できると考え検証しましたが、結果としては精度が低下したように感じました。
これは人が理解するのと同等の情報量を必要としている可能性や、AI Agentに対して同じ指示でも情報量が多い方が精度が高い可能性など、原因は様々考えられますが詳細は不明です。
『Next.jsの考え方』に沿わない実装のノイズ
AI Agentはリポジトリ内にある実装を読み取り学習するため、『Next.jsの考え方』にある内容とは異なる設計思想の実装が含まれているとノイズになり、AI Agentが混乱したり期待したアウトプットが得られない可能性があります。
リポジトリ内に参考にして欲しくない実装が含まれる場合には、参考にすべき実装ファイルを明示的にコンテキストに含めるなど、工夫が必要になると思われます。
感想
「自分自身の価値観を言語化してコンテキストに設定できれば、アウトプットの精度を高められるのではないか」というアイディアは以前から筆者の中にありましたが、価値観を言語化すること自体大変な労力が伴う上にモデルの進化も早いため、なかなかアイディアを検証できずにいました。しかし、『Next.jsの考え方』が筆者の価値観そのものを表現したものだと気づき、今回の検証に至りました。
本稿の主題はNext.jsアプリケーションの開発でAI Agentを活用するための方法論ですが、他にも様々な示唆に富んでいると感じています。人に読んでもらうために書いた文章がAIにとっても強く有効に働くこと、情報の圧縮はマイナスに働きうること、日頃アウトプットして自身の価値観やプラクティスを言語化しておくことがAI時代においても重要であることなど、筆者自身様々な発見を得ることができました。
今後のAIの進化を想像することは一種の面白味も感じますが、一方でエンジニアとして今目の前でやるべきことはおそらく今までとそう変わらず、日々インプットとアウトプットを続けることなのだと思います。
Discussion
結局既存コードにかなり引っ張られるんで、mdコネコネするよりも最善のコードを常に書き、規律から違反したコードは即修正、常に最高の状態でリファクタリングしまくる方が有意義かなと思いました
『Next.jsの考え方』を英語に翻訳して、ローカルにおいた方が良いのでしょうか？
やはり英語の方がLLMには有利であると実感しており
試したことないのでぜひやってみてください！