4
4

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

AIコーディングで本格的なプロダクト開発をするために知っておきたいこと

4
Posted at

はじめに

最近、Claude Code、OpenAI Codex、Gemini CLI などのコーディングエージェントが急速に進化しています。

以前であれば、人間が一つひとつコードを書いていた作業も、現在では AI に指示を出すだけで実装できるようになりました。

簡単な Web アプリケーションや小さなツールであれば、AI を活用することで驚くほど短時間で開発できます。

しかし、実際のプロダクト開発では、単にコードが動けばよいというわけではありません。

  • 保守性を維持できるか
  • コード全体に一貫性があるか
  • テストが十分に実装されているか
  • 将来的な機能追加に対応できるか
  • AI が意図しない実装をしていないか

こうした問題を考える必要があります。

特に、AI にほぼすべてのコードを書かせる「フル AI コーディング」では、従来の開発とは異なる課題が発生します。

この記事では、AI コーディングを実際のプロダクト開発に活用する際に重要だと考えるポイントを整理します。

1. AI が生成するコードには一貫性がない

最初に理解しておきたいのは、LLM(大規模言語モデル)は非決定的な振る舞いをするということです。

同じプロンプトを与えたとしても、毎回まったく同じコードが生成されるとは限りません。

例えば、あるファイルでは次のような実装をすることがあります。

const getUserName = () => {
  return "Ichiro";
};

一方、別のファイルでは次のように実装するかもしれません。

function getUserName() {
  return "Ichiro";
}

どちらも動作しますが、同じプロジェクト内で異なる書き方が混在すると、コード全体の一貫性が失われます。

さらに、問題は単なる文法の違いだけではありません。

  • ファイルの命名規則が統一されない
  • コメントの書き方が異なる
  • 設計原則の理解にばらつきがある
  • 不必要な抽象化が追加される
  • 特定のファイルだけ特殊な実装になる

こうした問題は、プロジェクトの規模が大きくなるほど管理しづらくなります。

対策:コード規約をツールで強制する

プロンプトだけでコードの一貫性を維持するのは難しいため、ESLint などの静的解析ツールを活用します。

例えば、以下のようなルールを設定できます。

  • 命名規則を統一する
  • 未使用変数を禁止する
  • import の依存関係を制限する
  • 不適切な構文を禁止する
  • 特定の設計ルールを強制する

AI の判断に任せるのではなく、ツールによって守らせることが重要です。

2. プロンプトを増やせば品質が上がるとは限らない

AI の出力品質を改善しようとすると、プロンプトに大量のルールを追加したくなります。

例えば、

  • 必ずクリーンアーキテクチャを採用する
  • SOLID 原則を厳守する
  • エラーハンドリングを徹底する
  • 過剰設計を禁止する
  • 必ずテストを書く

といった指示です。

もちろん、適切な指示は有効です。

しかし、指示を増やしすぎると、別の問題が発生することがあります。

例えば、「エラーを適切に処理すること」と「必ず fail fast すること」という指示が、特定の状況では矛盾する可能性があります。

また、「過剰設計を禁止する」という指示によって、本来必要な設計まで省略されることもあります。

つまり、プロンプトを増やすだけでは問題を解決できません。

重要なのは、指示の量ではなく、指示同士の整合性です。

対策:ルールを増やす前に環境を整える

プロンプトですべてを解決しようとするのではなく、次のような方法を組み合わせることが重要です。

  1. ESLint などでコード規約を強制する
  2. ディレクトリ構造で責務を分離する
  3. テストによって動作を検証する
  4. MCP などを利用して正確な情報を提供する
  5. 人間が設計と実装をレビューする

AI にすべての判断を任せるのではなく、間違いが起こりにくい開発環境を構築しましょう。

3. AI の報告をそのまま信用してはいけない

コーディングエージェントを使用していると、次のような報告を受けることがあります。

  • 「すべてのテストが成功しました」
  • 「カバレッジは100%です」
  • 「問題なく修正できました」
  • 「すべてのエラーを解消しました」

しかし、実際に確認すると、テストが失敗していたり、修正が不完全だったりすることがあります。

AI はコマンドの実行結果を正しく解釈できない場合があります。

特に、利用経験や学習データが少ない言語、ライブラリ、テストランナーでは、予想外の誤解が発生する可能性があります。

対策:実際の実行結果を確認する

AI の報告だけで判断するのではなく、実際のコマンド出力を確認することが大切です。

例えば、以下のようなコマンドを実行します。

pnpm lint
pnpm typecheck
pnpm test
pnpm build

それぞれの結果を確認し、成功していることを検証します。

さらに、問題が発生した場合は、誤った推論を繰り返している可能性も考慮する必要があります。

そのような場合は、同じセッションで無理に修正を続けるよりも、正確な情報を整理して新しいセッションで作業を始めた方がよいこともあります。

4. AI コーディングではレイヤー構造が重要

プロジェクトの規模が大きくなると、コードの依存関係を適切に管理する必要があります。

AI に自由に実装させていると、さまざまな場所から直接データベースにアクセスしたり、特定のライブラリに依存したりすることがあります。

こうした実装が増えると、変更や修正が難しくなります。

そのため、AI コーディングではレイヤー構造を明確にすることが重要です。

例えば、次のような構成が考えられます。

src/
├── domain/
│   ├── entities/
│   └── services/
│
├── application/
│   ├── usecases/
│   └── interfaces/
│
├── infrastructure/
│   ├── database/
│   └── external-api/
│
├── presentation/
│   ├── controllers/
│   └── components/
│
└── shared/

それぞれのレイヤーに役割を持たせ、依存関係を明確にします。

特に重要なのは、データベースや外部 API などの外部依存を明確な境界で分離することです。

こうすることで、AI が実装を変更する際にも、変更の影響範囲を限定しやすくなります。

また、ESLint の eslint-plugin-boundaries などを利用すれば、レイヤー間の依存関係を静的にチェックできます。

5. テストでは結合テストを重視する

AI はユニットテストを生成することができます。

しかし、ユニットテストが成功しているからといって、アプリケーション全体が正常に動作するとは限りません。

例えば、次のような問題が考えられます。

  • API とデータベースの連携が正しくない
  • データの保存形式が一致していない
  • 認証処理と API の連携に問題がある
  • 複数のモジュールを組み合わせた際にエラーが発生する

こうした問題を発見するためには、結合テストが重要です。

テストの考え方

個人的には、AI コーディングでは結合テストを特に重視するべきだと考えています。

例えば、バックエンド API であれば、実際のデータベースへの読み書きを含めたテストを実施します。

describe("ユーザー登録API", () => {
  it("ユーザー情報を登録できる", async () => {
    // 前提条件:
    // データベースに対象メールアドレスが存在しないこと

    // APIを実行
    const response = await registerUser({
      email: "ichiro@example.com",
      name: "Ichiro",
    });

    // 結果を検証
    expect(response.email).toBe("ichiro@example.com");
  });
});

テストコードは、単に動作するだけではなく、第三者が読んでも何を検証しているのか理解できる状態にすることが重要です。

また、テストの前提条件や検証内容をコメントとして明確に記述しておくと、AI による変更時にも意図が伝わりやすくなります。

6. コメントとドキュメントを軽視しない

AI が生成するコードでは、コメントが不足することがあります。

また、コメントがあっても、実際には意味のない説明になっているケースもあります。

例えば、次のようなコメントです。

// ユーザーを取得する
const user = await getUser(userId);

コードを見れば明らかなことを説明しているだけです。

重要なのは、なぜその処理が必要なのか、どのような注意点があるのかを記述することです。

TypeScript であれば、TSDoc を利用できます。

/**
 * 指定されたIDのユーザー情報を取得します。
 *
 * データベースに対象ユーザーが存在しない場合は、
 * NotFound エラーを返します。
 *
 * @param userId - 取得対象のユーザーID
 * @returns ユーザー情報
 */

特に、複雑な処理や外部サービスとの連携部分では、コメントを丁寧に記述することが大切です。

コードを読む人だけでなく、将来的にコードを変更する AI にとっても、適切なコメントは重要なコンテキストになります。

7. 実装前に AI に見積もりをさせる

いきなり実装を始めるのではなく、最初に AI に作業内容を整理させる方法も有効です。

例えば、次のような指示を与えます。

実装を開始する前に、必要な作業を整理してください。

以下の項目を必ず含めてください。

1. 変更対象のファイル
2. 各ファイルの変更内容
3. 関連するデータベースのテーブルとカラム
4. 関連するAPI
5. 外部サービスとの連携
6. 必要なテスト
7. 想定されるリスク
8. 不明点や仕様上の矛盾

推測だけで仕様を決めないでください。
不明点がある場合は、実装を開始する前に質問してください。

また、実装前にリファクタリングが必要かどうかも検討してください。

作業が大きい場合は、適切な単位に分割してください。

このように事前に作業内容を整理することで、変更範囲や実装の規模を把握できます。

また、必要以上に大きな変更が発生することを防ぎやすくなります。

ただし、AI が作成した設計書や見積もりも必ず正しいとは限りません。

人間が内容を確認し、必要に応じて修正することが重要です。

8. AI による実装には人間のレビューが必要

AI コーディングが普及すると、人間がコードを書く時間は減っていくかもしれません。

しかし、コードをレビューする必要がなくなるわけではありません。

むしろ、AI が大量のコードを生成できるようになることで、レビューの重要性はさらに高まります。

特に、以下のような観点を確認する必要があります。

  • 要件どおりに実装されているか
  • 不必要な機能が追加されていないか
  • エラーハンドリングは適切か
  • データの整合性は保たれているか
  • セキュリティ上の問題はないか
  • テストで重要なケースを検証できているか
  • 既存の設計や命名規則と一致しているか

AI の説明をそのまま受け入れるのではなく、疑問点があれば積極的に質問することが重要です。

例えば、

「なぜこの設計にしたのですか?」

「この処理を別の方法で実装できない理由は何ですか?」

「このエラーケースはどのように処理されますか?」

といった質問を繰り返すことで、実装の問題点を発見しやすくなります。

AI にコードを書かせることと、そのコードの品質に責任を持つことは別の問題です。

9. フル AI コーディングでおすすめしたい技術スタック

AI コーディングとの相性を考慮すると、広く利用されていて、ドキュメントや学習データが豊富な技術を選ぶことが重要です。

例えば、TypeScript を中心とした開発環境が選択肢になります。

技術 用途
TypeScript プログラミング言語
Node.js LTS 実行環境
pnpm パッケージ管理
ESLint 静的解析
Vitest テスト
Husky Git Hooks
React フロントエンド

もちろん、すべてのプロジェクトで同じ技術スタックを採用する必要はありません。

既存システムとの互換性やチームの経験も考慮する必要があります。

ただし、AI が十分に扱える技術を選ぶことは、開発効率と品質の両方に影響します。

10. AI デトックスも忘れてはいけない

最後に、技術面以外で重要だと感じることがあります。

それは、AI から意識的に離れる時間を作ることです。

AI コーディングでは、プロンプトの調整、コードレビュー、エラーの調査、技術情報の収集など、常に AI と向き合うことになります。

特に、AI の誤った実装を何度も修正していると、想像以上に精神的な負担が蓄積します。

そのため、定期的に AI から離れる時間を作ることが大切です。

例えば、

  • 毎日少しでも AI を使わない時間を作る
  • 週に一度は AI に関する作業から離れる
  • 散歩や運動をする
  • 自然の中で過ごす
  • AI 以外の趣味に時間を使う

といった習慣が考えられます。

AI を使い続けることだけが生産性を高める方法ではありません。

集中力を維持するためにも、意識的に休むことが大切です。

まとめ

AI コーディングは、ソフトウェア開発の可能性を大きく広げています。

しかし、AI にコードを書かせるだけで、高品質なプロダクトが完成するわけではありません。

今回紹介した内容をまとめると、重要なポイントは次のとおりです。

  1. AI が生成するコードには一貫性がないため、静的解析ツールを活用する
  2. プロンプトを増やすだけでなく、開発環境を整備する
  3. AI の報告を鵜呑みにせず、実際の実行結果を確認する
  4. レイヤー構造を明確にして、依存関係を管理する
  5. ユニットテストだけでなく、結合テストを重視する
  6. コメントやドキュメントを丁寧に記述する
  7. 実装前に作業内容と変更範囲を整理する
  8. 人間によるコードレビューを継続する
  9. AI が扱いやすい技術スタックを選択する
  10. 定期的に AI から離れる時間を作る

これから AI コーディングはさらに進化していくと思います。

しかし、少なくとも現在の段階では、AI にすべてを任せるのではなく、人間が適切な環境を整え、設計を確認し、品質を管理することが重要です。

AI にコードを書かせる時代だからこそ、エンジニアにはコードを書く能力だけでなく、コードの品質を判断する能力が求められるのではないでしょうか。

皆さんは、AI コーディングを実際のプロダクト開発に取り入れる際、どのような工夫をしていますか?

おすすめの開発環境やレビュー方法などがあれば、ぜひコメントで教えてください。

4
4
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
4
4

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?