2026年のAIコーディング・ワークフロー・ベストプラクティス — CLAUDE.md・AGENTS.md・.cursorrules・Skills・サブエージェント・MCP徹底解説

「エージェントは、あなたが作った環境にそっくり染まる。良い環境を作ることが、そのまま良いエージェントを作ることだ。」

プロローグ — コードよりもコンテキストが先

2026年5月、シニア開発者の一日は、2022年とはずいぶん違って見えます。朝、席についてまず開くのはIDEではなくエージェント・セッションです。PRの半数以上に、人が手で打った行よりエージェントが書いた行のほうが多く含まれています。そしてPR品質を最も左右する変数は、エージェントのモデル・バージョンではなく、あなたが用意したコンテキストです。

この記事は一つのシンプルな命題から始まります。

エージェントは、コードと並んでいるマークダウンと設定ファイル群を、コンパイラのように読む。それらのファイルこそがあなたのエージェントだ。

ここ2年で起きたのはツールの爆発でした。Claude CodeのCLAUDE.md、Cursorの.cursorrulesと.cursor/rules、GitHub Copilotの.github/copilot-instructions.md、そしてOpenAI Codexが推す横断標準AGENTS.md — 名前は違えど本質は同じです。「このリポジトリで作業するときはこう振る舞え」という共有の指示書です。

その上にツール別の高度な機能が積まれています。Claude CodeのSkills(.claude/skills/)、サブエージェント(.claude/agents/)、hooks(.claude/hooks/)、MCPサーバ設定(.mcp.json)、Cursorのエージェント定義(agents.json)とパーミッション機構。一つひとつは小さく見えても、束ねると個人生産性で10倍の差を生みます。

問題は、これを一カ所で解説したガイドが少ないことです。ツール別の公式ドキュメントはあっても、それらが一つのリポジトリでどう共存するかを扱った記事は多くありません。この記事はその穴を埋める試みです。

この記事で扱う内容:

章	主題
第1章	コンテキスト・ファイル群 — 何をどこに置くか
第2章	CLAUDE.mdを上手に書く — 長さ・構造・階層
第3章	AGENTS.md — 横断標準の登場
第4章	Cursorルール — .cursorrulesと.cursor/rules
第5章	GitHub Copilot、README.dev、CONTRIBUTINGの役割
第6章	Claude Code Skills — 再利用可能なワークフロー
第7章	サブエージェントとhooks — 自動化の二軸
第8章	MCPサーバ設定 — エージェントの道具箱
第9章	パーミッションとサンドボックス — 安全な自律性
第10章	エージェント・フレンドリーなコードベースとは
第11章	アンチパターン — こうすると壊れる
エピローグ	チェックリスト + 次回予告

第1章 · コンテキスト・ファイル群

2026年現在、よく整ったリポジトリには通常、次のようなファイル群があります。名前はツール別に分かれますが、役割は明確に分担されています。

1.1 ファイル地図

ファイル	読むのは誰か	用途
`CLAUDE.md`	Claude Code(セッション開始時に自動)	このリポジトリでClaudeが従うルール
`AGENTS.md`	OpenAI Codex、そして増えるツール群	横断共通の指示
`.cursorrules`(旧)/ `.cursor/rules/*.mdc`(新)	Cursor IDE	Cursorモードのルール
`.github/copilot-instructions.md`	GitHub Copilot Chat	Copilotのシステムプロンプト補助
`README.md`	人(エージェントもコンテキストとして使う)	プロジェクトの入口
`CONTRIBUTING.md`	人 + エージェント	開発/PR/レビューのルール
`README.dev.md`	シニア/オンコール/エージェント	内部開発ガイド
`.mcp.json`	Claude Code	このリポジトリが使うMCPサーバ
`.claude/agents/*.md`	Claude Code	サブエージェント定義
`.claude/skills/*/SKILL.md`	Claude Code	再利用可能な手順束
`.claude/hooks/*.toml`	Claude Code	セッション・ライフサイクル・フック
`agents.json`	Cursor	Cursorエージェント定義

1.2 階層化の原則

このすべてが一つのリポジトリにある必要はありません。ただしどれをどこに置くかを決めるとき、次の三軸を意識すると衝突が減ります。

ツール汎用性軸 — 一ツール専用なら当該ツールのファイルに、複数ツールに共通ならAGENTS.mdまたはREADME.mdに。
スコープ軸 — リポジトリ全体ならルートに、特定フォルダだけならそのフォルダに別のCLAUDE.mdやAGENTS.mdを置きます。Claude Codeは作業中ファイルの親ディレクトリを遡って見つけたすべてのCLAUDE.mdを結合します。
揮発性軸 — よく変わるもの(進行中の移行メモ、会議決定事項)は別ファイルか短い節に。ほとんど変わらないルール(コードスタイル、セキュリティ原則)は本文に。

一行要約: 共通ルールはAGENTS.mdに、ツール別の詳細は各自のファイルに、フォルダ別の詳細はそのフォルダに。

第2章 · CLAUDE.mdを上手に書く

Claude Codeはセッション開始時に作業ディレクトリのCLAUDE.mdを自動で読み、システムプロンプトに結合します。さらに作業中ファイルの親ディレクトリを遡ってCLAUDE.mdを探し、ユーザのホームの~/.claude/CLAUDE.md(グローバル)とマージします。これがよく書けていれば、同じモデルでも結果品質が目に見えて上がります。

2.1 良いCLAUDE.mdの形

# Project: Acme Web

## Stack
- Next.js 15 (App Router), TypeScript strict, Tailwind v4
- Drizzle ORM + Postgres 16
- Vitest + Playwright

## Conventions
- All server actions live in `app/_actions/` and import zod schemas from `lib/schemas/`.
- Database access goes through `lib/db/repositories/`. Do NOT import drizzle directly in components.
- Error type: throw `AppError` (see `lib/errors.ts`); the global handler converts to JSON.

## Verification (do this before reporting "done")
- `pnpm typecheck`
- `pnpm test --run`
- `pnpm lint`

## Permissions
- You may run: pnpm scripts, git read commands, gh CLI for issues/PRs.
- You may NOT run: git push, gh pr merge, anything that mutates production.

ポイントは、短く行動志向であること。「このリポジトリでは違う振る舞いをすべき部分」だけを書きます。

2.2 長さ — 200行で打ち切る

CLAUDE.mdが1000行になると二つの問題が同時に起こります。第一に、毎ターンその分のトークン費が発生します。第二に、モデルがそのすべてのルールを均一には守れません。長くなるほど中盤が薄まります。

経験則: 200行を超えたら分割。二つのパターンがあります。

フォルダ別CLAUDE.md — バックエンドのルールはapps/api/CLAUDE.md、フロントはapps/web/CLAUDE.mdに。Claude Codeが自動でマージします。
別ドキュメント — 長くてあまり参照しないポリシー(セキュリティ運用、データ保持)は別マークダウンに置き、CLAUDE.mdには「必要ならdocs/security.mdを読め」とだけ書きます。

2.3 何を書き、何を外すか

書くもの:

このリポジトリ固有の非標準コンベンション(普遍ルールは書かない — 「TypeScriptはstrict」はほぼどのリポジトリでも同じなので、書かなくて済む)
よくハマる落とし穴(「このリポジトリではdayjsではなくdate-fnsだけを使う」)
検証手順 — どのコマンドを通せば「完了」か
禁止事項 — force push禁止、マイグレーション自動適用禁止など

外すもの:

モデルの既定動作に既に含まれる一般論(「綺麗なコードを書け」はノイズ)
すぐ変わる一時メモ(それはチケットかPR説明に)
機密情報(このファイルは通常コミットされるので、トークンや鍵を絶対に書かない)

2.4 フォルダ別CLAUDE.mdの例

apps/api/CLAUDE.mdを別に置けば、バックエンド作業時にだけそのルールが合流します。

# apps/api

## Boundaries
- Controllers in `routes/` — only HTTP concerns.
- Business logic in `services/`.
- DB access in `repositories/` (Drizzle).

## Tests
- Unit tests next to the file (`*.test.ts`).
- Integration tests in `tests/integration/` — they spin up testcontainers Postgres.

第3章 · AGENTS.md — 横断標準

2025年後半からOpenAI Codexが推し始めたAGENTS.mdは、「リポジトリに置いた一つのマークダウンを、あらゆるコーディング・エージェントが読めるようにしよう」という運動です。2026年現在、Codex、Cursorの一部モード、複数のOSSエージェントがこのファイルを認識します。記述形式は自由なマークダウンです。

3.1 典型的なAGENTS.md

# AGENTS.md

This file gives AI coding agents the context they need to work in this repository.

## What this repo is
A pnpm monorepo with `apps/web` (Next.js), `apps/api` (Fastify), and `packages/*` shared libs.

## Setup
- Node 20.18+, pnpm 9.
- `pnpm install` from root.
- `pnpm dev` runs all apps in parallel.

## Test
- `pnpm test` — unit tests across the workspace.
- `pnpm test:e2e` — Playwright; requires Docker for testcontainers.

## Coding rules
- TypeScript only. No JS files in `src/`.
- Public APIs go in `packages/*/src/index.ts` re-exports.
- New endpoints need a zod request schema and 1+ test.

## Don't
- Don't commit secrets. `.env.local` is gitignored on purpose.
- Don't change `pnpm-lock.yaml` without running `pnpm install`.

3.2 CLAUDE.mdとの関係

二つのツールが同じファイルを読まないとき、同じ内容を二度書くのは避けたいでしょう。よくあるパターンが二つあります。

AGENTS.md一元化 — 共通ルールはすべてAGENTS.mdに、CLAUDE.mdは一行だけ。

# CLAUDE.md
Read AGENTS.md first. Anything below is Claude-specific addenda.

## Claude-only
- When running shell commands, prefer pnpm over npm here.

CLAUDE.md一元化 — Claudeしか使わないならAGENTS.mdを置かないかシンボリック・リンクします。ただし他エージェントが入ってきたときの動作は保証しません。

判断基準: チームが一ツールだけなら単一ファイル、二つ以上ならAGENTS.mdを真実のソースに置き、ツール別ファイルは薄く保つ。

3.3 実例を覗いてみる

公開された良い実例があります。Vercel自身のOSSリポジトリ(vercel/next.js, vercel/ai)は比較的短く直截なAGENTS.mdを置き、ビルド/テスト・コマンドと「PR前チェックリスト」を中心に書きます。AnthropicのSDKリポジトリ(anthropics/anthropic-sdk-pythonなど)はCLAUDE.mdを採用しており、移行期には冒頭に「今シーズンの変更点」を一時的に置きます。これらのパターンはそのまま流用できます。

第4章 · Cursorルール

Cursorは二つのルール・ファイル系統を持っています。旧来方式と新方式で、2026年時点ではどちらも動作します。

4.1 旧方式 — `.cursorrules`

リポジトリ・ルートに平文マークダウンで一ファイルだけ置きます。

# Cursor Rules

- Use TypeScript strict mode and avoid `any`.
- Prefer named exports.
- React components: function components with explicit prop types.
- All API handlers must validate input with zod.

## When generating tests
- Use Vitest.
- Place test files adjacent to source as `*.test.ts`.

長所はシンプルさ、短所は分岐できないこと。すべてのファイル作業に同じルールが入ります。

4.2 新方式 — `.cursor/rules/*.mdc`

.cursor/rules/の下に複数の*.mdcファイルを置き、各ファイルがヘッダで適用条件を宣言します。

---
description: "Backend API rules — Fastify routes"
globs:
  - "apps/api/src/routes/**/*.ts"
alwaysApply: false
---

# Backend API rules

- Every route declares its zod schema via `schema:` option.
- Use `app.log` not `console.log`.
- Error handling: throw `AppError` (see lib/errors.ts).

条件は通常二系統に分かれます。globsにマッチするファイルを開いているときだけ、もしくはユーザが明示的にスラッシュ・コマンドで呼び出したときだけ。このモジュール式は.cursorrulesより整っているので、新規リポジトリでは最初から.cursor/rules/を推奨します。

4.3 Cursorエージェント — `agents.json`

Cursorの「エージェント・モード」は独自のエージェント定義を持てます。ルートのagents.jsonにどのツールを許可するか、どのモードで動かすかなどを書きます。詳細はCursorのバージョンごとに変わるので公式ドキュメントを基準に。本記事では「こういうファイルがある」と認識すれば十分です。

第5章 · GitHub Copilot、README.dev、CONTRIBUTING

5.1 `.github/copilot-instructions.md`

GitHub Copilot Chatは、このファイルがあると自動で自分のシステムプロンプトに合流させます。使い方はCLAUDE.mdに似ていますが、より短く書くのが良いでしょう。Copilotのモデルは通常、より狭いコンテキスト窓で動作するからです。

# Copilot Instructions

- This repo uses pnpm, Next.js 15, Drizzle, Vitest.
- Always type API responses (no `any`).
- For React components, prefer server components unless interactivity is required.
- New endpoints must validate input with zod.

5.2 README.dev.md

README.mdが外向きの顔だとすれば、README.dev.md(またはdocs/dev.md)は内部開発者とエージェント向けの顔です。入れる内容は通常:

ローカル初回立ち上げ手順(依存、env、DBシード)
よく使うコマンド一覧(pnpm dev, pnpm db:reset, pnpm e2e:headed)
ディレクトリ構造の一枚絵
「初見が詰まりやすいポイント」集

このファイルはエージェントにも新人にも効きます。だから費用対効果の最も高いドキュメントの一つです。

5.3 CONTRIBUTING.md

OSSなら外部貢献者向けですが、社内リポジトリでも「PRをどう開き、どうレビューするか」のルールを書いておくとエージェントがそれに従います。AGENTS.mdと重複するなら片方に集約し、もう片方はリンクだけにする方が整います。

第6章 · Claude Code Skills — 再利用可能なワークフロー

SkillはClaude Codeの強力な機能です。何度も繰り返す作業手順をマークダウンで束ねたもので、名前で呼び出せます。置き場所は.claude/skills/<name>/SKILL.md(リポジトリ・ローカル)または~/.claude/skills/(グローバル)。

6.1 SKILL.mdの形

---
name: release-blog-post
description: Write, validate, and commit a trilingual blog post under data/blog/
when_to_use: User says "write a blog post" with a topic.
---

# Release Blog Post

1. Confirm filename slug: `data/blog/<category>/<YYYY-MM-DD>-<slug>.mdx`
2. Draft Korean version first.
3. Translate to en.mdx and ja.mdx, preserving structure.
4. Validate:
   ```bash
   npx tsx val.ts data/blog/.../<slug>.mdx data/blog/.../<slug>.en.mdx data/blog/.../<slug>.ja.mdx
   ```
5. Fix any reported issues, re-run until clean.
6. Stage and commit with message: `post: <topic> (ko/en/ja)`.

6.2 良いSkillの書き方

トリガー(when_to_use)を明確に — モデルがいつこのSkillを呼ぶかを決めます。
手順は番号付きの短いステップに。1ステップ = 1文 = 1アクション。
検証ステップを最後に。失敗したら上に戻って直すと明示。
Skill同士は呼び合わない — 依存ができるとデバッグが難しくなります。

6.3 Skill vs CLAUDE.md vs サブエージェント

資産	いつ呼ばれるか	何が入るか
CLAUDE.md	セッション開始時に常時	「このリポジトリではこう振る舞え」静的ルール
Skill	モデルがトリガー条件を見て呼ぶ	繰り返しの手順、チェックリスト
サブエージェント	メイン・エージェントが委譲	分離したコンテキストが要る大作業

この三つを混同しないことで、きれいな設計が出ます。

第7章 · サブエージェントとhooks

7.1 サブエージェント(`.claude/agents/`)

サブエージェントは、「この作業は別のコンテキストで別のツールセットで処理しろ」と委譲するときに使います。たとえばコード・レビュー、セキュリティ・スキャン、大規模検索など。定義はマークダウンです。

---
name: security-review
description: Reviews code for security issues — secrets, injection, auth bypass.
tools: [Read, Grep, Bash]
---

You are a security reviewer.

Process:
1. Search for hardcoded secrets (regex on common patterns).
2. Look for SQL/command injection in user-input paths.
3. Check authn/authz boundaries.

Output: a markdown report with severity tags (P0/P1/P2).

サブエージェントの最大価値はコンテキスト分離です。メイン・セッションに10万トークンの検索結果が雪崩込まない。

7.2 hooks(`.claude/hooks/`)

hookはセッション・イベントに自動で介入する小さなスクリプトです。よくあるパターン:

pre_tool_use — 危険コマンド(例: rm -rf, git push --force)に対するアラート
post_tool_use — ファイル編集直後にフォーマッタを自動実行
session_start — セッション開始時に環境情報を出力してモデルにコンテキストを与える
notification — 外部システム(Slack、通知)にステータスをプッシュ

フック定義の例:

[[hooks]]
event = "post_tool_use"
matcher.tool = "Edit"
matcher.path = "*.ts"
command = "pnpm prettier --write"

hookはユーザ環境を触るので、「このリポジトリでのみ」動くよう設計するのが安全です。

第8章 · MCPサーバ設定 — エージェントの道具箱

MCP(Model Context Protocol)はモデルにツールを接続する標準プロトコルです。Claude Codeは.mcp.jsonを見て、そのリポジトリでどのMCPサーバを起動するかを決めます。

8.1 `.mcp.json`例

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgres://app:app@localhost:5432/app"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

このファイルがあれば、モデルにpostgres MCPのクエリ・ツール、github MCPのイシュー/PRツールが露出します。つまりモデルは直接SQLを書いて実行したり、GitHubのイシューを開閉できます。

8.2 どのMCPを置くか

原則は「チームが頻繁にする外部呼び出しをツール化」です。候補:

データベース(Postgres、MySQL) — デバッグ時のアドホック・クエリに無限に有用
GitHub/GitLab — イシュー、PR、コメント
観測ツール(Sentry、Datadog、Grafana) — エラー・コンテキストを自動で取り込む
社内APIの薄いMCP — 社内wiki、デザイン・システム、RBAC参照

つけすぎるとコンテキストが重くなるので、1セッションあたり5個以内を推奨。あまり使わないものはオン/オフを切り替えるのが良いでしょう。

8.3 シークレットの扱い

.mcp.jsonは通常コミットされますが、env値は絶対に中に書きません。${env:VAR}構文を使うか、シークレット項目だけ.mcp.local.json(gitignore済み)に置きます。Claude Codeは両者を自動でマージします。

第9章 · パーミッションとサンドボックス

自律的なエージェントの最大リスクは「想定外の振る舞い」です。2026年のツールはこれを防ぐために二つの機構を提供します。

9.1 Claude Codeのパーミッション・モード

Claude Codeは次のようなモードをサポートします(名前はバージョンで多少違いますが意味は近い)。

default — 危険コマンドごとにユーザに確認を求める。
acceptEdits — ファイル編集は自動承認、外部コマンド(シェル、ネットワーク)は確認。
plan — 読み取り専用。計画だけ立て、変更はしない。
bypassPermissions — すべての確認をスキップ。隔離環境でのみ推奨。

リポジトリ単位でパーミッション・モードを固定したいなら、.claude/settings.jsonにこう書けます。

{
  "permissions": {
    "allow": [
      "Bash(pnpm test*)",
      "Bash(pnpm typecheck)",
      "Bash(git status)",
      "Bash(git diff*)"
    ],
    "deny": [
      "Bash(git push*)",
      "Bash(gh pr merge*)"
    ]
  }
}

核となる発想: 読み取り、ビルド、テストは自動許可。外部に変更を及ぼす行動は常に明示承認。このルールひとつで事故が大幅に減ります。

9.2 Cursorのエージェント許可リスト

Cursorエージェントも同様に許可/拒否リストを持ちます。よくある推奨は「テスト・lint・typecheckは無制限、パッケージ・インストールは確認、git pushはブロック」です。

9.3 サンドボックス — worktree、コンテナ、dev container

パーミッションとは別に、作業そのものを隔離環境に閉じ込めるパターンが急速に標準化しています。

git worktree — 一つのリポジトリの複数ブランチを同時に別ディレクトリにチェックアウトする機能。エージェントをworktree内だけに閉じ込めれば、メイン作業と衝突しません。
dev container / Docker — 依存とネットワークが制御されたコンテナ内でエージェントが動きます。Claude Code公式のDockerイメージがあり、これを使えばホストOSと分離されます。
クラウド・サンドボックス — OpenAI Codexなど一部モードはクラウドVMで動作します。ホストは絶対に触られません。

自律性を増やしたいほどサンドボックスを強く。二つのダイヤルは同じ軸ではなく、直交しています。

第10章 · エージェント・フレンドリーなコードベースとは

設定ファイルがどれだけ良くても、コード自体が応じなければ限界があります。「エージェントが働きやすいコード」というものが別に存在します。

10.1 五つの特性

強い型 — TypeScript strict、Python typingフル稼働、Rust。モデルがシグネチャだけ見て意図を察せる必要があります。
明確な境界 — モジュール間のimportグラフがシンプルで、各モジュールの責務が一文で説明できる。
速いテスト — 単体テストが10秒以内に終わるなら、エージェントは毎ステップ検証できます。分単位のテストしかないとエージェントは検証をスキップします。
良いエラーメッセージ — Error: invalid inputのようなメッセージはモデルに情報を与えません。Error: 'email' must be a valid RFC 5322 address (got "foo@")のようなエラーがエージェントには手がかりになります。
命名の一貫性 — 似たものが似た名前であってこそ、モデルの一般化がうまく働きます。userService.findByIdとOrderRepository.getが混在するとモデルが混乱します。

10.2 「テストをエージェントの検証者に」

最も強力なパターンは「エージェントが自分の変更を検証する方法を事前に決めておく」ことです。CLAUDE.md/AGENTS.mdの「Verification」節がその役割を果たします。モデルがコードを変え、テストを実行し、失敗したら直すループを自分の中で閉じます。このループが閉じているほど、人の介入は減ります。

10.3 小さな単位 = 小さなPR = 良いエージェント出力

エージェントは、一度に多くを変えなくてよいときに最もよく動きます。だからコードベース自体が「小さなPRが自然に生まれる」ように設計されている必要があります。モジュールが大きすぎると、エージェントの一作業が自動で巨大化します。これはただの良いエンジニアリング原則ですが、エージェント時代には報酬が二倍です。

第11章 · アンチパターン — こうすると壊れる

11.1 長すぎるコンテキスト・ファイル

最もよくある失敗です。CLAUDE.mdが2000行になると、毎ターンその分のトークンを焼きながらモデルは中盤のルールを忘れます。200行で打ち切る自己抑制が要ります。

11.2 互いに矛盾する指示

CLAUDE.mdには「pnpmを使え」、AGENTS.mdには「npmを使え」という状態。モデルはランダムに一方を選びます。真実のソースを定め、他のファイルはそちらを参照するだけにすべきです。

11.3 空のplaceholder、古いコマンド

"This file is a stub — fill in your project details"がそのまま残ったCLAUDE.mdを見たことがあるはずです。モデルはそれを真面目に受け取ります。半年前のコマンドがそのまま書いてあれば、それを実行して失敗します。コンテキスト・ファイルもCIでlintできるのが理想です(空のplaceholder検出)。

11.4 シークレット漏洩

MCP設定にAPIキーを直接書く、hookスクリプトにトークンを埋め込んでコミット、といった事故。絶対に起きてはなりません。env変数、OSキーチェーン、シークレット・マネージャを経由して注入します。

11.5 「エージェントが何とかしてくれる」権限

bypassPermissionsをデフォルトにしgit pushまで自動許可。一度の事故でmainブランチが壊れます。デフォルトは常に保守的に、フル自律は隔離されたworktree/コンテナ内でのみ。

11.6 Skillを細かく切りすぎる、または大きく作りすぎる

5行のSkillならシステムプロンプトに移したほうがいいし、200行ならそれはもはやSkillではなく別ドキュメントです。一つのSkillは1画面(50〜80行)が適当。

11.7 コンテキスト・ファイルを人だけが更新する

デプロイ手順やCIコマンドが変わったのにCLAUDE.mdが古いコマンドを持ったままだと、エージェントは無駄足を踏みます。インフラ変更PRに「関連コンテキスト・ファイルの更新」チェックボックスをPRテンプレートに入れておくのが最も安く防ぐ方法です。

エピローグ — 環境への投資は複利で返る

良いエージェント・セットアップの本質はたったひとつです。人とツールが同じ紙を見て働くようにすること。人に良いガイドはエージェントにも良く、エージェントに良い手順は新人にも良い。両者の間に別の標準はほとんどありません。

毎時間をコンテキスト・ファイルに投資するのは負担に感じるかもしれません。しかしこれは一つのPRに使う時間ではありません。今後のすべてのセッションに積み上がる時間です。よく書かれた200行のCLAUDE.mdは1年で数百回読まれます。その200行に追加で1時間使うことは、その1時間を1000倍にした価値で返ってきます。

ベストプラクティス・チェックリスト

AGENTS.md — ツール横断の真実のソースがある
CLAUDE.md — 200行以内、非標準コンベンションと検証手順中心
フォルダ別CLAUDE.md — モノレポならアプリ/パッケージ別に分割
.cursor/rules/ — globで分岐するモジュール式ルール
.github/copilot-instructions.md — Copilot用の短いサマリ
README.dev.md — ローカル・セットアップとよく使うコマンド
.claude/skills/ — 繰り返しのワークフローを束ねたもの(名前トリガー)
.claude/agents/ — コンテキスト分離が必要な委譲作業
.claude/hooks/ — フォーマッタ、アラートなどの自動化
.mcp.json — よく呼ぶ外部システムをツール化(コミット)、シークレットは.mcp.local.json
permissions — 読み取り/ビルド/テストは自動、外部変更行動は確認
サンドボックス — 自律モードはworktreeまたはコンテナ内のみ
CIでコンテキスト・ファイルlint — 空placeholder、古いコマンドを検出
PRテンプレート — 「関連コンテキスト・ファイル更新」チェックボックス
四半期ごとのレビュー — コンテキスト・ファイルもコードのように生きている

避けるべきアンチパターン要約

2000行のCLAUDE.md — モデルは中盤を忘れる。200行で打ち切る
矛盾する指示 — 真実のソースを定める
シークレット直書き — env変数と.mcp.local.jsonを使う
フル自律デフォルト — 常に保守的デフォルト + 明示的opt-in
空placeholder — CIで検出、PRで阻止
インフラ変更時のコンテキスト未更新 — テンプレートのチェックボックスで強制
MCPの付けすぎ — セッションあたり5個以内、不使用は切る
細かく切りすぎたSkill — 5行のものはシステムプロンプトに移す

次回予告

次回は**「AIコード・レビュー・ワークフロー — 人のレビュアーとエージェントのレビュアーを併用する」**です。良いコンテキスト・ファイルが執筆を助けるなら、良いレビュー・プロセスは出力品質を担保します。人のレビュアーが見るべきもの、エージェント・レビュアーが得意なもの、両者をPRテンプレートとCIにどう絡めるか — そしてどうすれば「エージェントが書いたPRを人がレビューするだけ」のシステムになるかをまとめます。

ツールは毎年変わる。標準はゆっくり変わる。環境は一度よく整えれば一年もつ。次の1時間を最も高価なコードに使う代わりに、そのコードを作る環境に使え。