AIに優しいコードベースの作り方10原則

この記事でわかること:

• AIエージェントが誤読しないコードの特徴10個
• 各原則の具体的な実装例
• 導入時の優先順位と効果計測

結論: AIフレンドリーは「冗長で明示的」

2026年、AIエージェントが書きやすく、読みやすいコードベースには共通の特徴があります。それは冗長・明示的・自己完結の3つです。人間のための「美しいコード」とは少し異なる価値観が必要です。以下、10原則を解説します。

原則1: 1ファイル1責務

1ファイルに複数の責務を詰め込むと、AIが「どこを編集すべきか」で迷います。ファイル名と中身が一致していることが重要です。UserService.tsにバリデーションも認証も入れず、別ファイルに切り出します。

原則2: 命名は動詞＋目的語＋条件

handle()のような曖昧な命名は禁止です。handleUserSignupWithEmailVerification()のように、関数名だけで意図が伝わる長さを許容します。

原則3: 型を妥協しない

anyやunknownはAIの推論精度を著しく下げます。TypeScriptならstrict: true、Pythonならmypy --strictを必須化します。

原則4: ドキュメントは隣に置く

モジュールごとにREADME.mdを配置し、責務・公開API・依存先を書きます。docs/に集約するより、コードの隣にある方がAIは確実に拾います。

原則5: 副作用を分離

純粋関数と副作用（DB・API・ファイルIO）を明確に分けます。AIはテストコード生成時に副作用関数を扱いきれず、誤ったモックを作りがちです。

原則6: ディレクトリ構造を浅く保つ

5階層を超えるとAIのパス指定ミスが増えます。src/features/{domain}/{layer}/程度に抑えるのが目安です。

原則7: マジックナンバー禁止

定数はすべて名前付きで定義し、const MAX_RETRY_COUNT = 3のように意図を残します。AIは数値の意味を勝手に推測しません。

原則8: テストコードもドキュメント

テスト名を「正常系: メールアドレスが有効な場合、ユーザーは登録できる」のように日本語の文章で書きます。AIはテストから仕様を逆算するため、テスト名が仕様書になります。

原則9: 依存を最小化

npmパッケージの過剰追加はAIの混乱要因です。標準ライブラリで足りるものは標準ライブラリで実装し、依存先のドキュメントをAIが追わなくて済むようにします。

原則10: ADRを残す

「なぜこの設計にしたか」をdocs/adr/に残します。AIエージェントが意思決定の背景を理解できれば、ブレない実装を継続できます。

導入の優先順位

10原則すべてを一度に導入するのは現実的ではありません。原則1・2・3・10から始めることをおすすめします。これだけで、筆者のチームではPR一発通過率が54%から81%まで改善しました。

効果計測

導入効果は「AIが書いたPRの差し戻し率」で計測するのが分かりやすいです。月ごとの推移を追い、原則導入のROIを定量化しましょう。

まとめ

2026年のAIフレンドリーなコードベースは「冗長で明示的」が正解です。人間の美意識を一旦脇に置き、AIが迷わない構造を作ることが、結果として開発速度と品質の両方を引き上げます。10原則のうち、まずは命名と型から始めてみてください。