Linc'well, inc.Publicationへの投稿
📝

AIエージェント向けのルールファイルにはなにを書くべきか

sugaya
に公開
AI
idea

はじめに

AIでの補助やVibe Codingはもう開発のスタンダードになってきました。AIのモデルは日々進化し、ツールも様々なものが登場しています。しかしながらAIエージェントの環境が進化していく中でも、より効率的な開発をするためにはAIが参照するルールファイルが非常に重要です。今回はどのようなルールを作成すべきかを考えます。

なぜAIエージェントにルールを教える必要があるのか

AIエージェントは強力ですが、そのまま使うだけでは汎用的な提案を重視します。プロジェクト固有のアーキテクチャ、命名規則、コーディングスタイルを理解していないため、生成されたコードがプロジェクトの方針と合わないことがよくあります。

ルールがない場合の問題点

1. コードの一貫性が失われる

  • AIが生成するコードが既存のコーディング規約に従わない
  • 命名規則がバラバラになる
  • 同じ機能を異なる方法で実装してしまう

2. レビュー負荷が増大する

  • プロジェクトの方針に合わないコードを毎回修正する必要がある
  • 「このパターンはプロジェクトでは使わない」という指摘を繰り返す

3. 技術的負債が蓄積する

  • プロジェクトのアーキテクチャを理解していないため、不適切な場所に実装が追加される
  • 既存の共通処理を知らず、重複実装が生まれる

これはルールが明示されていないプロジェクトに新しいメンバーがジョインした状況と考えられるでしょう。新しいメンバーはコード作成における質の基準やスタイル、技術的負債について理解できないままコードを作成してしまいます。その結果、レビュアーの負荷を上げ、潜在的な不具合を生み、さらなる負債やルールの破綻を招いてしまいます。

ルールを定義することで得られるメリット

1. 開発速度の向上

  • AIがプロジェクトの文脈を理解し、プロジェクトに合ったコードを生成する
  • 既存のパターンに従った実装が提案されるため、レビューや修正の手間が減る

2. コード品質の向上

  • プロジェクトの設計思想に沿った実装が生成される
  • 命名規則やコーディング規約が自動的に守られる

3. オンボーディングの効率化

  • 新メンバーがAIエージェントを通じてプロジェクトのルールを学習できる
  • プロジェクト固有の知識がドキュメント化される

ルールを定義して守っていくことで、AIだけでなく人間の開発者や新メンバーに対しても恩恵があります。もしもルール自体を言語化できていない場合は、以下の基準を参考にしてルールを作成してみてください。

ルール作成のベストプラクティス

ここからは、AIエージェントに効果的にプロジェクトを理解してもらうためのルールファイル作成のベストプラクティスをご紹介します。

抽象と具体の両面からのルール化

ルールファイルには、抽象的な説明と具体例の両方を記載すべきです。
抽象的な説明とは、プロジェクトの概要や目的、アーキテクチャの解説、開発の環境などで、コードからは読み取れない知識も含まれます。特にアーキテクチャは設計の背景や思想も記載しておくことで、どうしてこの設計となったかが読み取れるようになります。
また、抽象的な説明だけでなく、具体的な例も挙げることで実際にコードに落とし込むとどうなるか、どのように書いていくのが正解なのかをより正確に把握できるようになります。
抽象的な説明により思想や背景、目的などを理解させ、その考えのもとに具体的な例を挙げることで一貫した学習が行われ、より正確なAIコーディングが可能になります。

抽象的な説明の例

抽象的な説明の例として、作成すべきルールを以下に列挙します。

全体概要

  • プロジェクトの概要
    • なんのためのプロジェクトなのか、何を提供するのか
  • 開発の大原則
    • 開発言語、開発環境、メインフレームワーク

プロジェクトアーキテクチャ

  • アーキテクチャ概要
    • MVVM、レイヤードアーキテクチャ、クリーンアーキテクチャなど何のアーキテクチャを採用しているか
    • 一般的なアーキテクチャからの変更点はどこか
    • どうしてこのアーキテクチャを採用したか
  • レイヤーの役割
    • UI、モデルなどの各レイヤーの責務を言語化する
    • 該当レイヤーでの禁止すべき実装や依存関係を明示する
  • データ・処理のフローの解説
    • エントリーポイントや処理の起点を明記し、一連の処理を行う際の関連するクラスについて解説する
  • ディレクトリ構造やファイルの置き方
    • 各ディレクトリの役割を言語化する
  • UIパーツごとの役割、デザインシステム
    • 共通するUIパーツやコンポーネントの役割を解説する
  • テストの観点やテストルール
    • テストコードの作成基準やテストで保証すべきこと
  • 動作環境
    • 本番環境、開発環境といった各環境の説明
    • 環境ごとの役割やどの環境で開発するか
  • パフォーマンス
    • 開発にあたって注意すべき指標を明らかにする
  • 使用ライブラリの説明
  • 用語の定義、用語集

コーディングスタイル、コーディングルール

  • コーディング規約
    • プロジェクト独自のルールがあれば記載する
  • 命名規則
    • 言語標準の規則や、特に守らせたい規則を明記する
  • コメントの書き方
    • 不要なコメントや書くべきでないコメントの定義
  • 変数や関数の記載順
  • UIの構築
    • パラメータの指定順や指定方法
    • 共通のUIパーツを使用するよう促す
    • 特定の書き方を禁止する

具体的な説明の例

具体的なルールや説明も必要です。実際のコードから例を挙げ、AIがコード例をなぞって生成できるようにします。以下にどのような説明を記載すべきか列挙しました。

コードの記述例

  • 真似すべき画面の設計例
  • エラーハンドリングの方法
  • 通信やデータ取得の方法
  • テストの記述例

以下は実際に記載している具体例です。後述のテクニックのように良い例とともに悪い例も記載することで明確な方針を定めます。

## Repositoryメソッドでのエラー時はnullを返すのではなく、適切な例外を生成すること
// 良い例: 例外を生成する
Future<User> fetchUser(String id) async {
  final response = await apiClient.get('/users/$id');
  if (response.statusCode == 404) {
    throw const UserNotFoundException(message: 'ユーザーが見つかりません');
  }
  return User.fromJson(response.data);
}
  
// 悪い例: nullを返す
Future<User?> fetchUser(String id) async {
  final response = await apiClient.get('/users/$id');
  if (response.statusCode == 404) return null; // 避けるべき
  return User.fromJson(response.data);
}

開発方法やツールの操作手順

  • 環境構築の手順
    • サービスの起動方法
  • 使用するコマンドの一覧
  • Gitの使い方やコマンド
    • コミットの粒度や説明に関するルール
  • PRやブランチの作成ルール
    • コードレビューの観点やレビューの仕方
  • デバッグの方法や効率的なデバッグ方法
    • 開発時のよくあるエラーの解決方法
  • 外部サービスについての説明
    • トラッキングツールの解説
      • 機能の説明
      • 計測イベントの追加手順

その他ルール作成のテクニック

ルールの作成において普段使用しているテクニックを紹介します。

  • どのAIエージェントを利用していても同じルールが自動で守られるように環境を整備する
    • rulesyncなどを用いてAIエージェント間のルールを統一する
  • 「良い例」だけでなく、「悪い例」も提示する
    • 明確に禁止する際は「禁止」の項目を設ける
  • ルールファイルは役割ごとに細かく分ける
  • ルールを適用する範囲やファイルの拡張子を指定する
  • マークダウンによる構造化した記述を行う
  • AIに草案のルールを作成させる
    • ルールファイル自体をAIが管理・保守できるようにする

上記の中でもrulesyncによるAIエージェント間のルール統一と「悪い例」の提示が効果的に感じています。
最初は共通ルールとして別フォルダを用意し、ルールファイルなどからパスを指定し参照させるような仕組みを採用していましたが、この方法では正確にルールが適用されないことも多かったです。その後、rulesyncにより各AIエージェントのルールファイルとして自動で作成することができるようになり、ルールの適用がより正確に行われるようになりました。結果、AIエージェントが生成するコードを修正せずともそのまま採用できるようになりました。
また、プロジェクト内の実装の一部に古く負債化した書き方が残ってしまっており、AIエージェントがそちらを参照してしまうことがありました。これをルールファイルで「悪い例」として明記することでAIエージェントがその方法を採用せずに「良い例」のみに沿ってコードを生成しやすくなりました。
これらのようにルールファイルを適切に管理・運用していくことでAIエージェントにより生成したコードがプロダクトでも十分に使えるようになります。

まとめ

今回はAIエージェント向けのルールファイル作成について紹介しました。ルールファイルは一人で作成するのではなく開発者みんなで育てていくものです。ルールファイル作成はAIエージェント利用者全員のためになるので効率的です。
また、AIエージェント向けとはしているものの、実際には開発者自身も参考にするドキュメントであり、開発時には存在していてほしいドキュメントも多いです。もしもプロジェクト内でルールがない場合、まずはチーム内でルールを議論し、定義し、言語化してみてください。その結果AIだけでなく、開発者たちにとっても開発が進めやすい環境が自然と作られていくでしょう。

Linc'well, inc.
Linc'well, inc.Publication

医療スタートアップ Linc'well のエンジニアの記事を集めています。

Discussion