Zenn
😺

各AIツールが読み込むルールファイルを共通管理する

に公開
AI
GitHub Copilot
Cline
projectrules
Claude Code
tech

Project Rules

AIに、どのように動作して欲しいのか、覚えて欲しいことを伝える設定ファイルのこと。
今後登場するLLMの性能によっては変わる可能性はあるが、設定ファイルには無駄なことを書かずに情報を絞りコンテキストをシンプルに保つのが良いと思う。

この記事では、様々なAIコーディングアシスト、AIエージェントツールを併用しつつ評価するために、リポジトリ内で一意なルールを使い回す仕組みについて考えてみた。

サービス毎のフォーマット(2025/4)

一部ではあるがサービス毎のルール設定について調べた。構造化されたディレクトリをそのまま読み取ったり、単一ファイルに集約する必要があったりとフォーマットはバラバラである。

ルールファイルに何を書くか

以下の資料を参考に、一般的知識ではなくプロダクト特有の知識をルールとして記述する。

https://speakerdeck.com/yodakeisuke/dot-mdc-driven-knowledge-management

書かない

  • コードを読めばわかる系
    • 型情報や関数名で表明されている知識
    • 処理を追えばわかること
    • コメントでの目的の補足
  • AIが知っているであろうコミニュティのプラクティス系
    • 原則、ベストプラクティス
    • 有名ライブラリの使い方

書く

  • それは教えなきゃ知らない系
    • プロダクトのドメイン知識
    • 固有のユビキタス言語の意味
    • 社内デザインシステムの使い方
  • 規約系（チーム内の合意）
    • コーディングルールやテスト規約
    • gitコミットやPR本文のテンプレート
    • 採用しているアーキテクチャに則るような書き方の指針

どのように管理するか

シンプルなサンプル実装:
https://github.com/to4iki/ai-project-rules

チーム開発 & モノレポやマルチモジュール構成を想定し、Clineの公式ドキュメントで紹介されているRules Bank パターン を参考にする。

  • AIエージェントが自動で読み取らない非アクティブなルールを格納する rules-bank/ ディレクトリ内にリポジトリ構造と同じになるようルールを分割して配置する
    • rules-bank/ 内にはチーム開発で利用する最低限の共通ルールを格納する
  • AIサービス毎にルールファイルのフォーマットが異なるが中身は大体同じになるので、コンテキストに応じたファイルをスクリプトで作成・結合する
    • rules-bank/ に定義した共通ルールを、各自の .clinerules/ に配置するようなイメージ
  • 各種AIサービスが読み取るルールファイルはgit管理から除外する
    • 前述しているAIサービス毎の設定ファイルは .gitignore に含める
  • 個人環境で好みが異なるようなルールや、カスタマイズしたいルールがある場合には、rules-bank/xxx-local.md のようなファイルを作成し管理する
    • local が含まれるファイルは .gitignore 化する

リポジトリ構造

/
├── module-a
└── module-b

rules-bankの構造

/
└── rules-bank
    ├── module-a
    │   ├── 01-init.md
    │   ├── 02-architecture.md
    ├── module-b
    │   ├── 01-init.md
    ├── 01-init.md
    ├── 02-architecture.md
    ├── 03-coding.md
    ├── 04-git-workflow.md
    ├── 100-local.md

rules-bank/ 直下のファイルはリポジトリ全体で共通する広い範囲の事柄を記述し、配下のコンテキストにはそれぞれのルールを書くこと。例えば rules-bank/02-architecture.md にはリポジトリ全体の構造を書いて、rules-bank/module-a/02-architecture.md にはmodule-a内の設計方針が書いてあるイメージ。

スクリプトで連結して配置する

$ make ai-rules を実行し、各AIサービスに対応するファイルを配置する。

├── .github
│   ├── copilot-instructions.md
├── .clinerules
│   ├── module-a
│   │   ├── 01-init.md
│   │   ├── 02-architecture.md
│   ├── module-b
│   │   ├── 01-init.md
│   ├── 01-init.md
│   ├── 02-architecture.md
│   ├── 03-coding.md
│   ├── 04-git-workflow.md
│   ├── 100-local.md
├── module-a
│   │   └── CLAUDE.md
├── module-b
│   │   └── CLAUDE.md
│   ...
└── CLAUDE.md

clinerules

rules-bank/ 直下の構造を維持したまま .clinerules ディレクトリに配置する。
※ .cursor/rules も同様の方針でいけるはず。

CLAUDE.md

それぞれのディレクトリに該当する CLAUDE.md を配置する。例えば module-a/CLAUDE.md は rules-bank/module-a/*.md を結合した内容になる。

モジュール毎に絞り込んだルールファイルを作成しているので、コンテキストを切り替える場合には該当のディレクトリに移動して claude を実行する。

$ cd module-a & claude

.github/copilot-instructions.md

.clinerules のようにディレクトリでルールファイルを管理することができないので、次のような順でファイルを連結したものを .github/copilot-instructions.md とする。
※ .codex/instructions.md も同様の方針でいけるはず。

rules-bank/01-init.md
rules-bank/module-a/01-init.md
rules-bank/module-b/01-init.md
rules-bank/02-architecture.md
rules-bank/module-a/02-architecture.md
rules-bank/03-coding.md
rules-bank/04-git-workflow.md
rules-bank/100-local.md

.gitignore

# AI
.github/copilot-instructions.md
.clinerules
CLAUDE.md

参考

https://yaakai.to/blog/2025/rule-files-unified-management/

https://zenn.dev/ks0318/articles/b8eb2c9396f9cb

https://github.com/mizchi/ailab

https://github.com/kinopeee/cursorrules

Discussion