こんにちは、とまだです。
AIエージェントを使い始めたけど、「動くコードは作ってくれるけど、品質が心配...」と感じたことはありませんか？
私も最初はそうでした。
Claude CodeやCursor、Codexを使っていると、確かに素早くコードを生成してくれます。
ですが、そのコードが本当に「良いコード」なのか不安になりますよね。
Zenn でこちらの記事が注目を集めているように、多くの方がコードの品質を気にしているようです。
そこで、AI駆動開発でより良いコードを書くための「共通ルールファイル」をご紹介します！
ここでいう「ルールファイル」とは、AIにもっと品質の高いコードを書いてもらうための指示を書いたファイルです。
Claude Code などでは「メモリファイル」とも呼ばれていますが、パッと見でわかりやすいよう「ルールファイル」と呼ぶことにします。
そして、これらはプロジェクトごとに作るのではなく、共通で使えるようにすることで、効率的にコードを書くことができます。
今回は、AIにもっと品質の高いコードを書いてもらうための「共通ルールファイル」を紹介します。
初心者の方でもわかりやすいよう、丁寧に解説しています！
（追記：より詳しい解説はYoutubeで公開しています）
忙しい人のために要約
- AIに「良いコード」の基準を教える設定ファイルを作る
- 一度設定すれば、すべてのプロジェクトで自動的に適用される
- コード品質をAIが常に意識してくれる
- Claude Code、Codex、Cursor での設定方法を紹介
- 他の AI エージェントでも同じように設定できるはず
この記事を読むと得られるメリット
- AI駆動開発でより良いコードを書くための「共通ルールファイル」を作る方法を学べる
- 設定方法を紹介するので、すぐに実践できる
- セキュリティや保守性で悩むことなくコードを書ける
- 初心者でも長く使えるコードを書ける
それでは、早速本題に入ります！
なぜAIエージェントに「ルール」が必要なのか
プログラミングの「良いコード」は奥が深い
プログラミングを始めたばかりの頃、私は「動けばOK」だと思っていました。
しかし実際の開発現場では、コードが動くのは最低限のことなのです。
料理で例えてみましょう。
家で自分用に作る料理なら「食べられれば良い」かもしれません。
ですが、レストランで提供する料理となると話は別です。
味はもちろん、見た目、栄養バランス、食材の安全性、原価、調理時間まで考える必要があります。
プログラミングも同じです。
趣味のコードなら「動けばOK」でも、仕事で使うコードは違います。
読みやすさ、修正のしやすさ、エラーへの対処、処理速度など、様々な品質が求められるのです。
AIは「何を重視すべきか」が分からない
実は、AIエージェントは「良いコード」を書く能力を持っています。
ただし、私たちが何も指示しなければ、AIは「とりあえず動くコード」を優先して書いてしまいます。
なぜでしょうか？
それは、AIには「このプロジェクトで何を重視すべきか」が分からないからです。
たとえば、以下のような状況を考えてみてください。
- プロトタイプを作る場合 → スピード重視で良い
- お客様に納品する場合 → 品質とセキュリティが最重要
- 大規模サービスの場合 → 性能と拡張性が大切
AIにはこういった文脈が分かりません。
だからこそ、私たちが「ルール」として教えてあげる必要があるのです。
共通ルールファイルとは
優秀な先輩エンジニアのアドバイスを自動化
共通ルールファイルは、AIに対する「開発の指針」を書いたドキュメントです。
イメージとしては、優秀な先輩エンジニアが常に隣にいて、以下のようなアドバイスをしてくれる感じです。
「このエラー処理、ちゃんと書いた？」
「セキュリティは大丈夫？」
「後から読む人のことも考えてる？」
このようなアドバイスを、AIが自動的に考慮してくれるようになります。
一度設定すれば、ずっと使える
共通ルールファイルの素晴らしい点は、一度設定すれば新しいプロジェクトを始めるたびに設定し直す必要がないことです。
プロジェクトごとに特別なルールがある場合は追加できますが、基本的な品質ルールは共通で使い回せます。
設定方法（5分で完了！）
設定方法はとても簡単です。
使っているAIエージェントによって方法が異なるので、それぞれ説明します。
後述するルールをコピペして貼り付けるだけです。
Claude Codeの場合
Claude Codeは、ターミナルから使うAIエージェントです。
設定は以下の手順で行います。
1. 設定用のフォルダとファイルを作る
ターミナル（コマンドプロンプトやPowerShell）を開いて、以下のコマンドを順番に実行します。
# フォルダを作成
mkdir -p ~/.claude
# ファイルを作成
touch ~/.claude/CLAUDE.md
Windowsの場合は、PowerShellで以下のコマンドを実行してください。
# フォルダを作成
New-Item -Path "$HOME\.claude" -ItemType Directory -Force
# ファイルを作成
New-Item -Path "$HOME\.claude\CLAUDE.md" -ItemType File -Force
2. ファイルを開いて、ルールを貼り付ける
作成したファイルを開く必要があります。
VS Codeを使っている場合は、以下のコマンドで開けます。
code ~/.claude/CLAUDE.md
VS Codeで code コマンドが使えない場合は、以下の手順で有効にしてください。
- VS Codeを開く
-
Command+Shift+P（Macの場合）またはCtrl+Shift+P（Windowsの場合）を押す - 「Shell Command: Install 'code' command in PATH」を選択
もしくは、直接ファイルを探して開くこともできます。
ただし、.claude のようにドット（.）で始まるフォルダは通常見えないので、隠しファイルを表示する設定が必要になります。
（ここでは割愛しますが「隠しフォルダ 表示」というキーワードで検索すれば、設定方法が出てきます）
Codexの場合
Codexも同様の手順です。
# フォルダを作成
mkdir -p ~/.codex
# ファイルを作成
touch ~/.codex/AGENTS.md
# VS Codeで開く
code ~/.codex/AGENTS.md
Cursorの場合
CursorはVS Codeベースのエディタなので、GUI（画面操作）で設定できます。
- Cursorを開く
- 設定画面を開く（歯車アイコンをクリック）
- 「Rules & Memories」を選択
- 「User Rules」の「Add Rule」ボタンをクリック
- ルールを貼り付けて保存
これで設定完了です！
実際に使えるルールファイル（コピペOK）
では、実際に私が作成したルールファイルをご紹介します。
そのままコピペして使うだけで、コードの品質をAIが常に意識してくれるようになります！
（Git コミットメッセージは日本語とルールでは指定しておりますが、日本語でもOKです。）
# AI駆動開発 共通ガイドライン
## 開発の基本理念
- 動くコードを書くだけでなく、品質・保守性・安全性を常に意識する
- プロジェクトの段階（プロトタイプ、MVP、本番環境）に応じて適切なバランスを取る
- 問題を見つけたら放置せず、必ず対処または明示的に記録する
- ボーイスカウトルール：コードを見つけた時よりも良い状態で残す
## エラーハンドリングの原則
- 関連が薄く見えるエラーでも必ず解決する
- エラーの抑制（@ts-ignore、try-catch で握りつぶす等）ではなく、根本原因を修正
- 早期にエラーを検出し、明確なエラーメッセージを提供
- エラーケースも必ずテストでカバーする
- 外部APIやネットワーク通信は必ず失敗する可能性を考慮
## コード品質の基準
- DRY原則：重複を避け、単一の信頼できる情報源を維持
- 意味のある変数名・関数名で意図を明確に伝える
- プロジェクト全体で一貫したコーディングスタイルを維持
- 小さな問題も放置せず、発見次第修正（Broken Windows理論）
- コメントは「なぜ」を説明し、「何を」はコードで表現
## テスト規律
- テストをスキップせず、問題があれば修正する
- 実装詳細ではなく振る舞いをテスト
- テスト間の依存を避け、任意の順序で実行可能に
- テストは高速で、常に同じ結果を返すように
- カバレッジは指標であり、質の高いテストを重視
## 保守性とリファクタリング
- 機能追加と同時に既存コードの改善を検討
- 大規模な変更は小さなステップに分割
- 使用されていないコードは積極的に削除
- 依存関係は定期的に更新（セキュリティと互換性のため）
- 技術的負債は明示的にコメントやドキュメントに記録
## セキュリティの考え方
- APIキー、パスワード等は環境変数で管理（ハードコード禁止）
- すべての外部入力を検証
- 必要最小限の権限で動作（最小権限の原則）
- 不要な依存関係を避ける
- セキュリティ監査ツールを定期的に実行
## パフォーマンスの意識
- 推測ではなく計測に基づいて最適化
- 初期段階から拡張性を考慮
- 必要になるまでリソースの読み込みを遅延
- キャッシュの有効期限と無効化戦略を明確に
- N+1問題やオーバーフェッチを避ける
## 信頼性の確保
- タイムアウト処理を適切に設定
- リトライ機構の実装（指数バックオフを考慮）
- サーキットブレーカーパターンの活用
- 一時的な障害に対する耐性を持たせる
- 適切なログとメトリクスで可観測性を確保
## プロジェクトコンテキストの理解
- ビジネス要件と技術要件のバランスを取る
- 現在のフェーズで本当に必要な品質レベルを判断
- 時間制約がある場合でも、最低限の品質基準を維持
- チーム全体の技術レベルに合わせた実装選択
## トレードオフの認識
- すべてを完璧にすることは不可能（銀の弾丸は存在しない）
- 制約の中で最適なバランスを見つける
- プロトタイプなら簡潔さを、本番なら堅牢性を優先
- 妥協点とその理由を明確にドキュメント化
## Git運用の基本
- コンベンショナルコミット形式を使用（feat:, fix:, docs:, test:, refactor:, chore:）
- コミットは原子的で、単一の変更に焦点を当てる
- 明確で説明的なコミットメッセージを英語で記述
- main/masterブランチへの直接コミットは避ける
## コードレビューの姿勢
- レビューコメントは建設的な改善提案として受け取る
- 個人ではなくコードに焦点を当てる
- 変更の理由と影響を明確に説明
- フィードバックを学習機会として歓迎
## デバッグのベストプラクティス
- 問題を確実に再現できる手順を確立
- 二分探索で問題の範囲を絞り込む
- 最近の変更から調査を開始
- デバッガー、プロファイラー等の適切なツールを活用
- 調査結果と解決策を記録し、知識を共有
## 依存関係の管理
- 本当に必要な依存関係のみを追加
- package-lock.json等のロックファイルを必ずコミット
- 新しい依存関係追加前にライセンス、サイズ、メンテナンス状況を確認
- セキュリティパッチとバグ修正のため定期的に更新
## ドキュメントの基準
- READMEにプロジェクトの概要、セットアップ、使用方法を明確に記載
- ドキュメントをコードと同期して更新
- 実例を示すことを優先
- 重要な設計判断はADR (Architecture Decision Records)で記録
## 継続的な改善
- 学んだことを次のプロジェクトに活かす
- 定期的に振り返りを行い、プロセスを改善
- 新しいツールや手法を適切に評価して取り入れる
- チームや将来の開発者のために知識を文書化
8つの品質チェックポイント（初心者向け解説）
ルールファイルに含まれる品質の観点を、初心者にも分かりやすく解説します。
1. エラーハンドリング（エラーへの対処）
プログラムでエラーが起きたとき、どう対処するかということです。
自動販売機で例えると分かりやすいでしょう。
お金が詰まったとき、良い自動販売機なら「お金が詰まりました。係員を呼んでください」と表示します。
悪い自動販売機は、そのまま固まってしまいます。
プログラムも同じです。
何か問題が起きたとき、適切にユーザーに知らせて、安全に処理を続けるか止める必要があります。
AIにルールを設定することで、ネットワークエラーやファイル読み込みエラーなど、様々なエラーに対処するコードを自動的に書いてくれるようになります。
2. セキュリティ（安全性の確保）
家の鍵をかけ忘れたら誰でも入れてしまうように、プログラムにもセキュリティ対策が必要です。
具体的には以下のような対策です。
- パスワードを画面に表示しない
- 個人情報を暗号化する
- 悪意のある入力をブロックする
- APIキー（サービスを使うための鍵）を隠す
AIが自動的にこれらを考慮したコードを書いてくれるようになります。
3. 保守性（修正・改善のしやすさ）
コードは一度書いて終わりではありません。
後から機能を追加したり、バグを修正したりする必要があります。
部屋の整理整頓と同じです。
きちんと整理されていれば、必要なものがすぐ見つかります。
散らかっていると、探すのに時間がかかります。
整理されたコードの特徴の例をあげてみましょう。
- 変数名が分かりやすい（
aではなくuserNameなど） - 機能ごとにファイルが分かれている
- コメントで意図が説明されている
- 重複したコードがない
4. テスタビリティ（テストのしやすさ）
新しい家電を買ったとき、まず動作確認しますよね。
プログラムも同じで、きちんと動作確認（テスト）できる作りにすることが大切です。
テストしやすいコードは、以下のような特徴があります。
- 機能が小さく分割されている
- 外部サービスに依存しすぎていない
- 入力と出力が明確
- 予測可能な動作をする
5. パフォーマンス（処理速度）
プログラムの処理速度のことです。
レジで会計するとき、1商品ずつ別々に会計するより、まとめて会計した方が早いですよね。
プログラムも同じで、効率的な処理方法を選ぶことが重要です。
- 不要な処理を避ける
- データベースアクセスを最小限にする
- 重い処理は必要なときだけ実行
- キャッシュ（一時保存）を活用
6. 信頼性（安定した動作）
電車が遅延したとき、良い鉄道会社は振替輸送の案内をします。
プログラムも、問題が起きたときの代替手段が必要です。
信頼性を高める方法：
- エラーが起きたら自動的にリトライ（再試行）
- サービスが停止したら別のサービスを使う
- データのバックアップを取る
- 異常を検知したらアラートを出す
7. 可観測性（状況把握のしやすさ）
体温計で熱を測るように、プログラムも「今どんな状態か」を把握できることが大切です。
具体的には、以下のような対策があります。
- ログ（記録）を残す
- エラーの詳細情報を記録
- 処理時間を計測
- ユーザーの行動を追跡（プライバシーに配慮して）
問題が起きたとき、これらの情報があれば原因を特定しやすくなります。
8. スケーラビリティ（拡張性）
小さなお店が人気になって、お客さんが増えたらどうするでしょうか？
席を増やしたり、店舗を拡大したりしますよね。
プログラムも同じで、利用者が増えたときに対応できる作りが重要です。
- データベース設計を工夫する
- サーバーを増やせる構成にする
- 処理を並列化できるようにする
- 不要な機能は後から追加できる設計にする
よくある質問
Q: プログラミング初心者でも使えますか？
はい、むしろ初心者の方にこそおすすめです！
共通ルールファイルがあれば、AIが「なぜこの実装が良いのか」を説明しながらコードを書いてくれます。
実践しながら、良いコードの書き方を自然に学べます。
最初は生成されたコードの意味が分からなくても大丈夫です。
AIに「このコードのエラー処理の部分を説明して」と聞けば、丁寧に教えてくれます。
Q: すべてのプロジェクトに同じルールで大丈夫？
基本的なルールは共通で使えます。
ただ、プロジェクトごとに CLAUDE.md や AGENTS.md を作成して、カスタマイズすることもできます。
たとえば React のプロジェクトならコンポーネント配置のルールや、
TypeScript での型定義のコーディングルールなどを追加すると良いでしょう。
Q: ルールが多すぎてAIが混乱しませんか？
あまりに多いとAIが混乱する可能性がありますが、今回ご紹介したルール程度であれば問題ありません。
また、ルールファイルには「プロジェクトの段階に応じて適切なバランスを取る」という指示も含まれているため、AIが状況に応じて判断してくれます。
ただし、今後追記していって長くなった際には、Claude や ChatGPT などにプロンプトとルールファイルを渡して「内容を圧縮」すると良いでしょう。
こちらはプロンプトの例です。私がよく使用しているプロンプトです。
# 背景
これは、AIに対するルールファイルです。
AIがコーディングを行う際に、このルールファイルを常に参照しています。
...（ここにルールファイルの内容）
# 現状の問題点
かなり長いルールファイルになってしまっています。
このままだと全体のコンテキストが長大になり、性能が低下してしまう可能性があります。
# 命令
元の内容を保持しつつも、内容を圧縮・整理してください。
Q: 設定したルールを確認する方法は？
AIに「現在設定されているルールを教えて」と聞けば、適用されているルールを確認できます。
また、コードを生成してもらうときに「なぜこの実装にしたの？」と聞けば、どのルールを考慮したか説明してくれます。
それ自体が勉強にもなりますので、ぜひ試してみてください！
まとめ
AI駆動開発において、AIエージェントは私たちの強力なパートナーです。
ですが、パートナーも「どんな仕事を期待しているか」を知る必要があります。
共通ルールファイルは、その期待を明確に伝える手段です。
一度設定すれば、AIが常に品質を意識したコードを書いてくれるようになります。
「動くコード」から「良いコード」へ。
より自信を持って開発を進められるようになります。
設定はたった5分で完了します。
ぜひ今すぐ試してみてください！
より良いコードを書けるようになると、開発が楽しくなりますし、将来の自分や他の開発者にも喜ばれます。
質問や相談があれば、お気軽にコメントやX（Twitter）でお声がけください！
また、AI駆動開発をはじめた方のために質問や相談、仲間との交流ができる Discord も「今日」作りました。
（眺めているだけでも勉強になる仕組みにしているので、気軽に参加してください）
一緒にAI駆動開発を楽しんでいきましょう！