Aider AGENTS.md CONVENTIONS.md AIコーディング aider.conf 2026

Aider AGENTS.md vs CONVENTIONS.md：2026年版 コンベンションファイル完全移行ガイド

The Prompt Shelf ·

AiderはCONVENTIONS.mdを長年の標準として採用してきた。コーディング規約、テストコマンド、アーキテクチャ上の制約をこのファイルに書き、--conventions-fileフラグでAiderに渡す形式だ。これは今でも機能する。だが2025年、AIコーディングツールの生態系が急拡大し、AGENTS.mdというクロスツール標準が台頭した。Claude CodeやCursorを併用するチームにとって、「どちらのファイルを使うべきか」という問いは、今や避けられない選択になっている。

本記事では、両フォーマットがAider内部でどう機能するか、ツール間でどう差があるか、そしてCONVENTIONS.mdからAGENTS.mdへ移行する具体的な手順を解説する。

1. AiderのコンベンションファイルとCONVENTIONS.md

Aiderの--conventions-fileフラグは、任意のMarkdownファイルをAiderに渡す仕組みだ。Aiderはそのファイルの内容を全会話のシステムプロンプトの前に付加する。フラグ自体はファイル名を問わない。CONVENTIONS.mdというデフォルト名は、Aiderのドキュメントが推奨し、ユーザーが自然に採用したことで広まった慣習だ。

CONVENTIONS.mdには一般的に以下が書かれる：

  • コードスタイルルール（言語固有のフォーマット規則）
  • テストコマンド（pytest -x --tb=shortなど）
  • アーキテクチャ制約（編集禁止ファイル、避けるべきパターン）
  • コミットメッセージの書式
  • 依存関係ポリシー

Aiderのみを使うプロジェクトではこれで十分だった。問題は、他のAIツールを追加した瞬間に生じる。CONVENTIONS.mdはAiderしか読まない。Claude Codeはこのファイルを無視し、CursorもGitHub Copilotも認識しない。チームが複数のAIツールを使い始めると、コーディング規約がAiderセッションにしか適用されない状態になる。

2025年：AGENTS.mdの標準化。 OpenAI、Anthropic、GitHubなど主要プレイヤーが共通のコンベンションファイル形式として収束したのがAGENTS.mdだ。Linux FoundationのAgentic AI Foundationが仕様を正式化し、2025年中旬までにAider、Claude Code、GitHub Copilot、Cursor、Cline、Roo Codeなど28種類以上のツールが対応を宣言した。

Aiderの対応：2025年のアップデートでAGENTS.mdのネイティブ検出を追加。既存の--conventions-fileフラグをそのままAGENTS.md指定にも使える形とした。

2. AiderがCONVENTIONS.md（AGENTS.md）を読む仕組み

どちらのファイルを使っても、Aider内部の処理は同一だ：

  1. ファイルを全文読み込む
  2. 内容をすべての会話ターンのシステムプロンプト前に付加する
  3. セッション全体を通して有効にする

重要なのは、Aiderはファイルを「セクション単位で解析」しない点だ。ファイル全体をフラットなドキュメントとしてモデルに提示する。一部のツールがAGENTS.mdを構造的に解析して特定セクションだけを抽出するのとは異なる。

この仕様上、AGENTS.mdに他ツール向けのセクション（例：## GitHub Copilot）を追加しても、Aiderセッションでそれが見える。意図しない挙動を引き起こすわけではないが、ルールはできるだけツール横断で通用する形で書くのが望ましい。

# デフォルト：プロジェクトルートのCONVENTIONS.mdを自動検出
aider

# AGENTS.mdを明示的に指定
aider --conventions-file AGENTS.md

# サブディレクトリのファイルを指定
aider --conventions-file docs/AGENTS.md

2025年以降、AiderはプロジェクトルートのAGENTS.mdも自動検出するが、.aider.conf.yamlでの設定が最も確実でバージョンに依存しない方法だ。

3. AGENTS.md vs CONVENTIONS.md 比較表

AGENTS.mdCONVENTIONS.md
標準化団体Linux Foundation / Agentic AI FoundationAider独自
対応ツール数28種類以上Aiderのみ
ファイル場所プロジェクトルート（慣習）プロジェクトルート（または--conventions-fileのパス）
Aiderネイティブサポートあり（2025年〜）あり（当初から）
GitHub Copilot対応ありなし
Cursor対応ありなし
Claude Code対応ありなし
Cline/Roo Code対応ありなし
クロスツール互換性完全Aiderのみ
内容フォーマットMarkdown（スキーマ非強制）Markdown（スキーマ非強制）
移行コストファイル改名＋Aider設定変更のみ—

コンテンツの書き方に違いはない。どちらもスキーマのない平文Markdownだ。差異はツール認識だけ：AGENTS.mdはエコシステム全体で読まれ、CONVENTIONS.mdはAiderしか読まない。

4. どちらを使うべきか：判断基準

CONVENTIONS.mdのままでよいケース：

  • Aider専用のプロジェクト
  • 他のAIコーディングツールを使う予定がない
  • 既存のCONVENTIONS.mdが機能していて移行コストを払いたくない

Aiderしか使わない環境では、ファイル名を変えても機能面での得は何もない。

AGENTS.mdへ即移行すべきケース：

  • AiderとClaude Code、Cursor、Copilotなど他ツールを併用している
  • 将来的に複数ツールを使う可能性がある
  • 新規プロジェクトを立ち上げる

マルチツール環境でCONVENTIONS.mdを使い続けると、コーディング規約がAiderセッションにしか効かない。Claude CodeがPRのコードを書いても、Cursorが補完を出しても、あなたのルールは適用されない。ツールをまたいだコードの品質にばらつきが生まれ続ける。

AGENTS.mdとCONVENTIONS.mdが両方ある場合： CONVENTIONS.mdを削除する。2つのファイルを並存させると「どちらが正」か曖昧になり、一方だけ更新されて内容が乖離するリスクがある。AGENTS.mdに統合してAiderの設定を変更し、クリーンな状態にすること。

5. 移行手順：CONVENTIONS.md → AGENTS.md

ほとんどのプロジェクトで15分以内に完了する作業だ。

ステップ1：ファイルを改名またはコピー

# 方法A：そのまま改名
mv CONVENTIONS.md AGENTS.md

# 方法B：内容を確認しながら移行したい場合
cp CONVENTIONS.md AGENTS.md

ステップ2：AGENTS.mdの標準セクションを確認・追加

エコシステムが収束しつつある標準的なセクション名があるため、最低限以下を含めることを推奨する：

# AGENTS.md

## Commands

```bash
# テスト
pytest -x --tb=short

# リント
ruff check .
ruff format .

Code Style

  • 全パブリック関数に型ヒントを付ける
  • フォーマッターはruff（行長100）
  • Googleスタイルのdocstring（パブリッククラス・関数に必須）

Architecture

  • src/core/ — ドメインロジック、外部依存なし
  • src/adapters/ — I/O・外部サービス・DB
  • src/api/ — HTTPレイヤーのみ、coreに委譲
  • src/generated/ 内のファイルは編集禁止（自動生成）

セクション名はAider動作に影響しないが、Claude Codeなど特定セクションをパースするツールとの互換性が上がる。

### ステップ3：.aider.conf.yamlを設定

プロジェクトルートに`.aider.conf.yaml`を作成または更新する：

```yaml
# .aider.conf.yaml
conventions-file: AGENTS.md
auto-commits: false
model: claude-sonnet-4-5

これで毎回--conventions-fileフラグを指定する必要がなくなる。チーム全員が同じAider設定を使えるようにバージョン管理に含めること。

ステップ4：CONVENTIONS.mdを削除（コピーした場合）

rm CONVENTIONS.md

ステップ5：他ツールで動作確認

  • Claude Code：プロジェクトルートでclaudeを起動。AGENTS.mdは自動読み込み。追加設定不要
  • Cursor：プロジェクトをCursorで開くとセッション開始時にAGENTS.mdを読む
  • GitHub Copilot：VS CodeのCopilot拡張がワークスペースルートのAGENTS.mdを読む
  • Cline / Roo Code：どちらもプロジェクトルートのAGENTS.mdを自動認識

6. AiderとのAGENTS.md：効果の高いセクション

すべてのAGENTS.mdコンテンツがAiderに等しく影響するわけではない。

Aiderへの影響が大きいセクション：

  • コードスタイルルール — 言語、フォーマット、インポート順序など。具体的に書くほど効果が高い
  • テストコマンド — edit-testループでAiderが使用する。使いたいフラグも含めて正確に書く
  • 禁止パターン — 「/generated/内のファイルを編集しない」「eval()は使わない」などのルールは確実に守られる
  • アーキテクチャ制約 — どのモジュールが何を担当するかの定義。新規コードの配置先をAiderが判断するために使う

Aiderへの影響が低いセクション（追加しても問題なし）：

  • コミットメッセージ形式 — --auto-commitsフラグの方が直接的に影響する
  • ツール固有セクション — ## GitHub CopilotセクションはAiderに見えるが動作には影響しない
  • プロジェクト概要 — 人間向けの背景説明。コンテキストとして有用だが、Aiderの編集判断には影響しない

7. AiderチームのためのAGENTS.mdテンプレート（完全版）

# AGENTS.md

<!-- 対応ツール: Aider, Claude Code, Cursor, GitHub Copilot, Cline, Roo Code -->

## Commands

<!-- Aider: edit-testループで使用。Claude Code: 検証時に実行 -->

```bash
# セットアップ
pip install -e ".[dev]"

# テスト
pytest -x --tb=short                             # テスト実行（初回失敗で停止）
pytest --cov=src --cov-report=term-missing       # カバレッジ付き

# リント・フォーマット
ruff check .     # リント
ruff format .    # フォーマット
mypy src/        # 型チェック

# ビルド
python -m build

Code Style

  • Python 3.11以上を使用 — match/case、型ヒント必須
  • フォーマッター: ruff（行長100）
  • 型アノテーション: 全パブリックメソッドと関数に必須
  • Docstring: Googleスタイル、パブリッククラス・関数に必須
  • インポート順: stdlib → サードパーティ → ローカル（空行区切り）
  • ライブラリコードにprint()を使わない — loggingを使う

Architecture

  • src/core/ — ドメインロジック、外部依存なし
  • src/adapters/ — I/O、外部サービス、DB
  • src/api/ — HTTPレイヤーのみ、coreに委譲
  • tests/はsrc/の構造を鏡映しにする
  • src/api/からsrc/core/へのインポート禁止（依存の方向は一方向）

Constraints

  • src/generated/内のファイルを編集しない（スキーマから自動生成）
  • eval()、exec()、動的インポートを使わない
  • 全DBクエリはリポジトリレイヤー経由 — APIハンドラーに生SQLを書かない
  • 新規依存関係はpyproject.tomlに追加する（場当たり的インストール禁止）

Testing

  • 全パブリック関数に最低1つのユニットテストを書く
  • pytestフィクスチャを使う（setUp/tearDown禁止）
  • 外部サービスはアダプター境界でモックする
  • 複数入力に対してテスト関数を繰り返すよりparametrizeを使う
  • テストファイル名: test_<モジュール名>.py

Git

  • コミットメッセージ形式: type(scope): description（Conventional Commits）
  • タイプ: feat, fix, docs, refactor, test, chore
  • コミットはアトミックに — 1コミット1論理変更

## 8. .aider.conf.yamlの設定

`.aider.conf.yaml`はプロジェクトルートに置き、バージョン管理に含める。チームメンバー全員が同じAider設定を使えるようになる。

```yaml
# .aider.conf.yaml

# コンベンションファイル — AGENTS.mdを指定
conventions-file: AGENTS.md

# モデル設定
model: claude-sonnet-4-5

# 動作設定
auto-commits: false        # 手動コミット（AIの変更をレビューしてからコミット）
dirty-commits: false       # 未コミット変更がある状態でコミットしない
suggest-shell-commands: true

# 出力設定
pretty: true
stream: true

モノレポ構成でAGENTS.mdがプロジェクトルート外にある場合は相対パスで指定する：

conventions-file: ../../AGENTS.md

パスは.aider.conf.yamlが置かれているディレクトリからの相対パスで解決される。

FAQ

AiderはAGENTS.mdを読み込みますか？

はい。Aiderは2025年からAGENTS.mdをネイティブサポートしています。明示的に指定する場合はaider --conventions-file AGENTS.mdを使用するか、.aider.conf.yamlにconventions-file: AGENTS.mdを設定してください。

AiderにおけるAGENTS.mdとCONVENTIONS.mdの違いは？

CONVENTIONS.mdはAider独自のコンベンションファイル形式で、Aiderのみが認識します。AGENTS.mdはClaude Code、GitHub Copilot、Cursorなど28種類以上のAIコーディングツールが対応するクロスツール標準です。Aider内部での動作は同一で、違いは他ツールとの互換性にあります。

AiderでCONVENTIONS.mdの代わりにAGENTS.mdを使うには？

プロジェクトルートの.aider.conf.yamlにconventions-file: AGENTS.mdを追加してください。またはaider --conventions-file AGENTS.mdをコマンドラインで実行する方法もあります。

AGENTS.mdがあればCONVENTIONS.mdは削除すべきですか？

はい。内容をAGENTS.mdに完全移行した後はCONVENTIONS.mdを削除することを推奨します。両ファイルを併存させると「どちらが正」か曖昧になり、一方だけ更新されるなどの混乱が生じます。

AGENTS.mdはCONVENTIONS.mdの後継ですか？

Aiderと他のAIツールを併用するチームにとっては、AGENTS.mdへの移行を推奨します。Aider専用チームであればCONVENTIONS.mdのままで問題ありません。AGENTS.mdの最大のメリットは「1ファイルで全ツールに対応できること」です。

.aider.conf.yamlとは何ですか？

.aider.conf.yamlはAiderのプロジェクト単位の設定ファイルです。--conventions-file、--model、--auto-commitsなどのフラグをデフォルト値として設定でき、毎回コマンドラインで指定する手間を省けます。プロジェクトルートに置いてバージョン管理に含めることを推奨します。

関連記事

AiderのAPIキーを安全に管理する

AiderはClaude・GPT-4など複数プロバイダーに対応しており、それぞれAPIキーが必要になる。1Password CLIならop run -- aiderでキーをランタイム注入でき、.envファイルやシェルプロファイルに平文保存するリスクをゼロにできる。

Share on X

Related Articles

Aider AGENTS.md vs CONVENTIONS.md: Complete 2026 Guide to Convention Files

Should Aider teams use AGENTS.md or CONVENTIONS.md? How both work, how to migrate, and why AGENTS.md wins for multi-tool repos in 2026.

CursorでのAGENTS.md完全セットアップガイド — .cursor/rulesと組み合わせる実践パターン（2026年版）

CursorがどのようにAGENTS.mdを読み込むか、.cursor/rules（.mdc形式）との使い分け、モノレポ構成でのパターン、.cursorrulesからの移行方法を解説する2026年版完全ガイド。

CLAUDE.md vs CONVENTIONS.md vs AGENTS.md: The Definitive 2026 Comparison

A technical deep-dive comparing CLAUDE.md, CONVENTIONS.md, and AGENTS.md — format, supported tools, strengths, weaknesses, migration paths, and real code examples. Decide which AI coding rules format belongs in your repo.

Claude Code × Rust プロジェクト：CLAUDE.mdテンプレートと実践ワークフロー（2026年版）

Rustプロジェクト用のプロダクション対応CLAUDE.mdテンプレートを完全解説。エラーハンドリング規則・Clippy強制・unsafeブロックポリシー・rust-analyzer連携・非同期パターンまでカバー。

Explore the collection

Browse all AI coding rules — CLAUDE.md, .cursorrules, AGENTS.md, and more.

Browse Rules