【エージェントルール】 中長期開発におけるルール設計

はじめに

• 中長期的なプロジェクトにおいてAIを用いた開発を行うには単純なプロンプト以外にルールの設計が必要です。
• 現状、自分の知る限りでは、ルール設計はまだ十分に確立されておらず、効果がどれほどあるかも定かではありません。
• ただ、実務に活用できればさらに効率的に開発できると思うので、ルール設計の調査と検証を行ってみました。

検証においては個人で行っただけなので、簡単な検証のみとなり、再現性においては保証できません。
参考程度にしていただければと思います。

ルールとは？

• ルールとは、プロジェクト特有の情報をAIエージェントに自動で読み込ませるためのカスタムコンテキストファイルです。これにより、チャットプロンプトで毎回同じ指示を繰り返す必要がなくなります。
• GitHub CopilotならCopilot Instructions、CursorならProject Rulesがそれにあたります。
• メリット：
  • プロジェクト固有の知識を共有： デザインパターンやフレームワーク、コーディングルールをAIが理解できるようになります。
  • 生産性の向上： 毎回同じ指示をする手間が省け、質の高いコード生成が期待できます。

ルール設計の必要性と判断基準

• 中長期的な開発が見込まれるプロジェクトに最適です。
• 短期開発では、ナレッジが育つ前にプロジェクトが終了する可能性があるため、導入効果が薄い場合があります。

中長期開発におけるルール設計のカギ

• 中長期開発において必要なルールを大まかに以下にまとめました。

1. 仕様駆動である
2. 実装計画書を作らせる
3. 実装範囲を明確にする
4. ルールファイルを自動更新させる

1.仕様駆動である

• コード生成における不確定要素を減らすことが重要です。
• 不確定要素が残ることで、不確定な部分をAIがよしなに実装してしまうことがあります。
• これが潜在的な実装であるほどレビュー時に気づきにくいです。
• 仕様に存在しない実装が行われないためにも仕様駆動は大切です。

2.実装計画書を作らせる

• 実装に入る前に実装計画書を作成し、事前に実装方針をユーザーとすり合わせします。
• これにより、実装の手戻りコストを減らすことができます。
• また実装計画書を残しておくことで、そのまま仕様書として活用できます。

3.実装範囲を明確にする

• 実装範囲を明確にすることが特に重要です。
• 実装範囲が不明確だとどこまで実装すればいいのかをAIの判断に委ねることになります。

4.ルールファイルを自動更新させる

• 実際に運用して分かったことですが、ルールファイルの手動での更新はかなり時間がかかります。
• 書いたからといってその通りに作業してくれない場合もあります。
• そのため、基本的にルールファイルの運用はAIにやらせるようにします。
• ユーザーからのフィードバックや実装中の新しい知見を見つけたらルールファイルに記録するように指示しておきます。

ルールファイルを使った実装フロー

ルールファイルの構成

以下の構成で、ルールを分類・管理しました。

.
├── .github
│   ├── tasks (実装計画書)
│   │   └── [YYYYMMDD]-[タスクid]-[タスク名]-[タスクの種類].prompt.md
│   ├── instructions (コード生成指示 (個別の指示書))
│   │   ├── general.instructions.md          # コーディング指示 (全体)
│   │   ├── security.instructions.md         # セキュリティ指示
│   │   ├── test.instructions.md             # テスト指示
│   │   ├── ts.instructions.md               # TypeScript指示
│   │   └── vue.instructions.md              # Vue指示
│   └── copilot-instructions.md              # エージェントの役割と作業フローを定義
├── docs
│   ├── projectbrief.md               # プロジェクトの概要
│   ├── productContext.md             # プロダクトのコンテキスト
│   ├── etc...

ルールの説明

copilot-instructions.md

• 開発全体のルールを定義します。
• エージェントがどのようにタスクを進めるのかをこのファイルに定義します。
• ここにはコーディングについてのルールは書きません。

実際のルールはこちら（長いです）

general.instructions.md

• プロジェクトの実装の概要を定義します。
• 採用技術やプロジェクト固有の仕様ライブラリについて書きます。
• 工夫ポイント：
  • ライブラリには公式ドキュメントでリンクさせておくところがポイントです。
  • これにより、ライブラリの仕様の確認時にAIが正しく情報を取得できるようになります。

ts.instructions.md

• TypeScript固有のルールを定義します。
• 最近のAIモデルは賢いですが、たまに古い書き方をしたり、any型を使ったり、定数管理を怠ったりします。
• これらの問題が起きないように細かくルールを定義する必要があります。

vue.instructions.md

• Vue固有のルールを定義します。
• Reactを使っている場合は、tsx専用のルールファイルを作成するとよいでしょう。
• VueをAIに書かせるとテンプレート内でpropsを定義するなどたまにおかしなコード生成をします。
• NG例とOK例を含めるとより精度高くコード生成してくれます。

security.instructions.md

• セキュリティについてのルールを定義します。
• Vibe Codingにおいてはセキュリティ面での問題が多く見受けられるようになったため、独自のルールが重要です。
• RAILGUARDフレームワークに沿って簡潔に書きました。

tasks/*

• tasksディレクトリ配下には実装計画書ファイルを書きます。
• 実装計画書については以下で詳しく説明しています。

docs/*

• docsディレクトリ配下には具体的なプロジェクト仕様を書きます。
• ファイル単位としては、APIフェッチやエラーハンドリングなど大きな括りで書くとよいと思います。
  • 例えば：api.mdやerror-handling.md
• また、ファイルを分割することでコンテキストを削減＆ファイル名で参照しやすくなります。
• 実際の案件では、docsをBEとFEチームで共通で使えるようにリポジトリとして管理し、開発リポジトリごとにgit submodule で取り込むような開発手法をとっています。
• また、エンジニア以外のメンバーにはObsidian等のドキュメンテーションツールで閲覧or編集してもらうことも可能です。

実装計画書とは

• 実装する前に実装の内容を詳細に記述するためのファイルです。
• これはKiroのSpecモードを参考にしました。
• ユーザーが簡単なプロンプトを投げると、AIがタスク開始前にファイルを参照しながら具体的な実装内容を記述していきます。
• 実装計画書はユーザーのプロンプトをAIにリライトさせることでプロンプト強化としての役割を担います。
• 以下は実装計画書のテンプレートです。
• 実際にAIが以下の項目を埋めていきます。

# 実装計画書テンプレート

## 説明

## 要件

## 詳細実装計画

## 参考にする既存ファイル

## ファイル構成

## 技術的考慮事項

良いルールの書き方

• 以下の3点を意識してルールを定義すると良いです。

1. 具体性・明確性：誰が読んでも理解できる内容にすること
2. 簡潔性：箇条書きベースで書くこと
   • 書き方を箇条書きに限定することで要点を絞って簡潔に記述できる
   • また、AIがルールを修正する時もAIが説明しすぎる問題を減らす
3. 参照先明記：ライブラリ名を書く時にはドキュメントのリンクを貼ること
   • リンクを使ってドキュメントを自動的に参照できます

ルール設計に迷ったら

• ネットで調べてみると、様々な言語やフレームワークのルールファイルが公開されています。
• 今回のルール設計も以下のリポジトリのルールをいくつか参考にしています。

awesome-cursorrules
https://github.com/PatrickJS/awesome-cursorrules/tree/main?tab=readme-ov-file

Cursor Directory Rules
https://cursor.directory/rules

使ってみた結果

• ルールを導入した環境と導入していない環境で、いくつかの新規実装を行い比較検証してみました。
• 主に次の観点で検証を行いました：
  1. 既存のコードや設計パターンへの準拠
     • 車輪の再発明を行わないか
     • 設計パターンが一貫しているか
  2. 仕様の理解度と遵守
     • 実装が仕様に沿っているか
     • 特に指示していない実装が行われていないか
• 検証の前提条件：
  • GitHub Copilot Agentを使用
  • 特定のプロジェクト用にチューニングされたルールファイルを使用
  • Claude Sonnet 4モデルを使用

1. 既存のコードや設計パターンへの準拠

• 結果：
  • ルールなし：⭐️⭐️（まあまあできた、ただし改善が必要）
  • ルールあり：⭐️⭐️⭐️（十分にできた）
• ルール設計なし：
  • Copilotのエージェント機能が優秀なので、そもそもルールを使わなくてもコンポーネントはある程度見つけられていました。
  • ただし、新規実装の場合は、コーディングルールが無視されていたり、既存のコンポーネントを参照しろと言わないと実装してしまうことがありました。
• ルール設計あり：
  • 新規実装では、他の実装とほぼ変わらないような実装をすることができました。
  • また正しいコンポーネントの使い方ができていました。

2. 仕様の理解度と遵守

• 結果：

  • ルールなし：⭐️（指示外の余計な実装が含まれた）
  • ルールあり：⭐️⭐️⭐️（簡単なプロンプトで仕様に沿った実装ができた）

• ルールなし：

  • プロンプトに仕様の説明を入れることである程度コード生成はできました。
  • しかし、仕様に存在しない箇所までAIがよしなに実装してしまうことがありました。
  • この「仕様外の実装」はユーザーが気づかずに紛れ込んだ場合、プロジェクトにおいてとても悪質です。

• ルールあり：

  • ルールで実装計画書を作成する指示を行っているので、ユーザーの簡単なプロンプトからまず実装計画書を作成し、ユーザーと実装方針をすり合わせます。
  • 基本的に実装計画書に問題がなければその通りに実装してくれるようになりました。
  • ルールで実装範囲を明確に定義することで、「仕様外の実装」をすることもなくなりました。

今後の課題について

• ドキュメンテーションの重要性: ルール設計だけでなく、コード自体の品質（ドキュメンテーションや可読性など）もAIの精度に大きく影響します。
• 過剰な補完: AIが良かれと思って指示外のコードを追加することがあります。ルールで実装範囲を明確に定義することが重要です。
• エディタの制限：今回の記事はvscodeで使えるGitHub Copilot用のルール形式で作成しました。実際の開発ではvscodeだけでなくcursorなど開発者間で異なるエディタを使う場合もあると思います。今後の課題として異なるエディタ間で使えるルール設計が重要となります。
  • OpenAIが異なるエディタ間で共通のルールファイルを定義できる「AGENTS.md」を公開していますが、こちらに統一できるかも調査していく必要があります。

まとめ

• 今回ルールを運用してみて、中長期的な開発では、プロジェクト固有の知識をAIに共有するためのルール設計が必要だと感じました。
• 検証結果では、既存コードへの準拠や不要な実装の抑制においてルールファイルを使用した方が効果があることがわかりました。
• しかし、ルールの質を高めるだけでなく、コード自体のコンテキストを改善していく努力も、AIとの協業においては必要であることもわかりました。
• 今後もルール設計の開発を進めていきます。

活用できるツールや手法を紹介

Repomixでプロジェクトルールを自動生成させよう

• 既存プロジェクトへルールを導入することはそこまで難しいことではありません。
• すでにコードがある程度書かれている場合、repomixとGeminiを使ってルールを自動生成させることができます。

https://repomix.com/ja/guide/

Reconcilation Loopで正確なコード生成をさせよう

• Reconcilation Loopとはゴールの状態を設定して、そこに近づけるために繰り返し調整する仕組みのことです。
• 具体的には、tsc, ESLint, prettierなど静的解析ツールを導入し、実装完了前にこれらのツールを使用して最終チェックを行わせます。
• TypeScriptの型を使い型エラーが起きないようなコードを書くことも重要です。

https://zenn.dev/bitkey_dev/articles/098257fda90c67

RAILGUARDフレームワークでセキュアなコード生成をさせよう

• 近年の流行を見せているVibe Codingですが、セキュリティ面で問題のあるコードを生成することが分かってきました。
• そこでセキュリティのルールであるRAILGUARDフレームワークを適用した方がよいと判断しました。
• security.instructions.md は以下を参考にしました。