CLAUDE.md・AGENTS.md・SKILL.mdでAIエージェント開発を効率化するベストプラクティス

なぜ設定ファイルが必要なのか

AI エージェントに毎回「このリポジトリはこういう構成で、こういうルールで書いて」と説明するのは非効率です。

設定ファイルを用意しておくと、次の恩恵があります。

• 一貫性 — どのセッションでも同じルールで動く
• 自律性 — 確認なしで作業を完遂できる
• 再現性 — 別の AI（Gemini・Copilot）でも同じ前提で動かせる
• 引き継ぎ — チームメンバーや未来の自分にも伝わる

この3つのファイルはそれぞれ役割が異なります。

ファイル	対象	役割
CLAUDE.md	Claude Code 専用	プロジェクト固有のルール・制約
AGENTS.md	全 AI エージェント共通	AI が参照する汎用ガイド
SKILL.md	Claude Code のスキル定義	再利用可能なタスクフロー

---

CLAUDE.md — Claude Code 専用の指示書

何を書くか

CLAUDE.md は Claude Code がプロジェクトを開いたとき自動的に読み込まれる設定ファイルです。

書くべき内容はこの4つです。

1. リポジトリ構造 — どこに何があるか
2. フォーマットルール — コードスタイル、命名規則
3. ワークフロー — よく使うコマンド、デプロイ手順
4. 禁止事項 — やってはいけないこと

実際の例

以下はフロントエンドプロジェクトの CLAUDE.md の例です。自分のプロジェクトに合わせて書き換えてください。

# my-project — Claude 操作ガイド

## リポジトリ構造

\`\`\`
src/
  components/   ← React コンポーネント
  pages/        ← Next.js ページ
  lib/          ← ユーティリティ関数
\`\`\`

## コマンド

\`\`\`bash
npm run dev     # 開発サーバー起動
npm run build   # ビルド
npm run test    # テスト実行
\`\`\`

## ルール

- コンポーネントは必ず TypeScript で書く
- CSS は Tailwind のみ使用（styled-components 禁止）
- コミットメッセージは日本語で書く

## やってはいけないこと

- main ブランチへの直接 push
- console.log をコミットに含める
- 頼まれていないファイルを変更する

配置場所

CLAUDE.md はリポジトリルートに置くのが基本ですが、サブディレクトリにも置けるのがポイントです。

my-project/
├── CLAUDE.md          ← プロジェクト全体のルール
├── src/
│   └── CLAUDE.md      ← フロントエンド固有のルール
└── api/
    └── CLAUDE.md      ← バックエンド固有のルール

Claude Code はカレントディレクトリから上位を辿って全 CLAUDE.md を読み込むので、コンテキストを階層的に管理できます。

---

AGENTS.md — AI エージェント汎用ガイド

CLAUDE.md との違い

AGENTS.md は Claude Code だけでなく、Gemini・Copilot・Cursor などあらゆる AI エージェントが参照することを想定したファイルです。

CLAUDE.md は Claude 固有の機能（スキル呼び出し、Bash ツールなど）を前提に書けますが、AGENTS.md は特定の AI に依存しない汎用的な内容にします。

書くべき内容

• プロジェクトの目的・背景
• ディレクトリ構造と各ファイルの役割
• データフォーマット・記法ルール
• 作業フロー（新機能追加、バグ修正など）
• 禁止事項

実際の例

以下はコンテンツリポジトリ向けの AGENTS.md の例です。

# my-project — AI Agent ガイド

このリポジトリは ○○ のコンテンツを管理します。

## ディレクトリ構造

\`\`\`
articles/{slug}/
  index.md     ← 記事本文
  *.png        ← 記事用画像
\`\`\`

## 記事フォーマット

\`\`\`yaml
---
title: 記事タイトル
published: false  # 公開時は true
slug: my-article
topics: ["タグ1", "タグ2"]
---
\`\`\`

## AI への作業指示

- 返答は日本語
- published は必ず false で作成する
- 頼まれていないファイルを変更しない

---

SKILL.md — 再利用可能なタスクフロー

スキルとは

Claude Code のスキルは、複数ステップの作業を1コマンドで実行できるマクロです。

/write-article   テーマを入力するだけで記事＋画像を一括生成
/generate-image  記事に合ったサムネイルを自動生成
/annotate-screenshot  URLを指定して注釈付きスクリーンショットを生成

ファイル構成

スキルは .claude/skills/{name}/SKILL.md に配置します。

.claude/
└── skills/
    ├── write-article/
    │   └── SKILL.md
    ├── generate-image/
    │   └── SKILL.md
    └── annotate-screenshot/
        └── SKILL.md

SKILL.md の書き方

SKILL.md は YAML frontmatter + Markdown 本文で構成します。

---
name: write-article
description: テーマを受け取り記事と画像を生成する。「記事を書いて」で自動トリガー。
allowed-tools:
  - Write
  - Read
  - Edit
  - Bash
  - mcp__claude-in-chrome__navigate
  - mcp__claude-in-chrome__computer
---

## STEP 1 — テーマの解釈
...

## STEP 2 — アウトライン作成
...

重要なポイント：

• description に自動トリガーのキーワードを書く（「記事を書いて」で発火させたいなら明示）
• allowed-tools で使用するツールをホワイトリスト管理する
• ステップは番号付きで順番に書く
• 各ステップで何を判断・実行するか具体的に書く

効果的なスキル設計のコツ

1. ステップを細かく分ける

「記事を書いて画像を生成して保存する」を1ステップにせず、「テーマ解釈 → アウトライン → 本文生成 → 画像生成 → 保存」と分けます。途中でエラーが起きたとき原因を特定しやすくなります。

2. 判断基準を明記する

「適切なファイル名にする」ではなく「英小文字・数字・ハイフンのみ、スペース・日本語・大文字は使わない」のように具体的に書きます。

3. エラー時の挙動を定義する

「ポート 4567 が使用中の場合は PORT=5000 で再試行する」のように、よくある失敗パターンとリカバリー方法を書いておくと AI が自律的に対処できます。

4. 完了報告のフォーマットを統一する

## 完了報告フォーマット

\`\`\`
✅ {タスク名}が完了しました

📄 {生成ファイル}
🖼  {画像ファイル}

次のステップ：
1. ...
\`\`\`

---

3ファイルの連携パターン

パターン1 — コンテンツリポジトリ

ブログ・ドキュメントなど記事を管理するリポジトリの場合：

CLAUDE.md    → 記事フォーマット・禁止事項（Claude 専用）
AGENTS.md    → 同内容を Gemini 等にも共有
SKILL.md ×3  → write-article / generate-image / annotate-screenshot

パターン2 — アプリ開発リポジトリ

CLAUDE.md          → コマンド集・コーディングルール
AGENTS.md          → アーキテクチャ概要・API 仕様
.claude/skills/
  └── add-feature/ → 新機能追加の標準フロー
  └── fix-bug/     → バグ修正の標準フロー
  └── write-test/  → テスト生成フロー

パターン3 — モノレポ

CLAUDE.md               → 全体ルール
packages/
  web/
    CLAUDE.md           → フロントエンド固有ルール
  api/
    CLAUDE.md           → バックエンド固有ルール
.claude/skills/
  └── deploy/           → デプロイフロー

---

実践的なベストプラクティス

1. 「やってはいけないこと」を必ず書く

AI は指示されたことをやろうとするあまり、意図しない変更をすることがあります。

以下はよくある禁止事項の例です。プロジェクトに合わせて追加・変更してください。

## やってはいけないこと（例）

- published: true で記事を作成する（必ず下書きで作る）
- 頼まれていないファイルを編集・削除する
- main ブランチに直接 push する
- 確認なしに外部 API を呼び出す

2. 承認不要な操作を明示する

逆に「これは確認なしでやっていい」を明示すると、AI が都度確認しなくなり作業が速くなります。以下は例として参考にしてください。

## 確認不要な操作（例）

- articles/ 以下のファイル作成・編集
- /tmp/ 以下への一時ファイル書き出し
- git add / commit / push（明示的に依頼された場合）

3. コンテキストを階層化する

グローバル → プロジェクト → サブディレクトリの順でルールを階層化することで、汎用ルールと個別ルールを分離できます。

~/.claude/CLAUDE.md          ← 個人の好み（言語・文体・絵文字設定）
  └── my-project/CLAUDE.md   ← プロジェクトルール
       └── src/CLAUDE.md     ← コンポーネント固有ルール

4. スキルの description でトリガーを制御する

description: >
  「記事を書いて」「記事を作って」「〜について書いて」で自動トリガー。
  テーマを受け取り index.md と cover.png を一括生成する。

曖昧な表現（「作業して」など）はトリガーに含めないようにすると、意図しない発火を防げます。

5. メモリシステムと組み合わせる

Claude Code には会話を跨いで情報を保持できるメモリ機能があります。スキルと組み合わせると「前回の続き」から始められます。

メモリに保存しておくと便利な情報の例：

• ユーザーの好みのスタイル・文体
• よく使うスラッグのパターン
• 過去に失敗したアプローチとその理由

---

まとめ

やること	効果
CLAUDE.md にリポジトリ構造・禁止事項を書く	毎回の説明が不要になる
AGENTS.md に汎用ガイドを書く	Claude 以外の AI でも同じ前提で動く
SKILL.md でタスクフローを定義する	複数ステップの作業を1コマンドで実行できる
「禁止事項」と「確認不要操作」を明示する	AI の自律性と安全性を両立できる
スキルのステップを細かく分ける	エラー時の原因特定が容易になる

AI エージェントは「何をするか」だけでなく「何をしないか」「どのように判断するか」を明示することで、はじめて自律的なパートナーとして機能します。

設定ファイルへの初期投資は1〜2時間ほどですが、その後の開発効率の向上を考えると十分に元が取れます。ぜひ取り組んでみてください。