# CLAUDE.md が長くなりすぎたら：AGENTS.md・Skills・CI の境界を見直す

> Canonical: https://vxi.me/ja/posts/claude-md-agents-md-skills-ci/
> Locale: ja-jp
> Published: 2026-10-06
> Updated: 2026-10-06
> Markdown: https://vxi.me/ja/posts/claude-md-agents-md-skills-ci.md

Codex や Claude Code のような Coding Agent を長く使っていると、AGENTS.md や CLAUDE.md はかなり自然に長くなっていきます。最初から設計を間違えたというより、実運用で失敗するたびにルールが一つずつ増えるからです。

関係ないファイルまで変更したら「スコープ外は触らない」を追加する。テストを実行せず完了と言ったら「実際の検証結果を出す」を追加する。migration の失敗後に証拠を消してしまったら、cleanup を制限するルールを追加する。一つひとつは妥当でも、半年後には root instruction が開発規約、障害メモ、作業手順、注意事項を全部抱えた社内ハンドブックのようになってきます。

私が気になったのは行数そのものではなく、ほぼすべてが always-on になっていることでした。README を少し直すだけでも frontend の境界、release 手順、protocol の制約、database migration の注意事項まで一緒に付いてくる。さらに同じルールが root、Skill、docs、CI にそれぞれ現れ始めると、「書いてあるか」より「誰が本当の owner なのか」の方が難しい問題になります。

そこで気になったのが Nession の [issue #1437](https://github.com/BestNathan/nession/issues/1437) です。この repository では root の CLAUDE.md が約 760 行まで増えており、単に文章を短くするのではなく、root guidance、scoped owner、Skills、実行可能な Gate に責務を分ける migration を行っています。実装は [PR #1442](https://github.com/BestNathan/nession/pull/1442) に入っています。

ただ、私はこれを「四層構造が正解」という記事にはしたくありませんでした。知りたかったのは、always-on の面積が実際にどれくらい減ったのか、その境界を CI で守れるのか、そして現在の Codex / Claude Code の instruction loading が昔の記事の前提とまだ同じなのか、という点です。

そこで migration 前後の固定 commit を GitHub API から読み、自分の Content Lab 側で read-only の再計測を行いました。さらに小さな instruction-contract validator を別に実装しました。やってみて一番残ったのは「CLAUDE.md は何行以下にするべきか」という数字ではなく、もっと単純な問いです。

**このルールの owner は誰か。いつ必要になるのか。機械で検証できるのか。**

## 本当に解きたいのは「ファイルが長い」ことではない

760 行が嫌なだけなら、ファイルを分割すれば終わりです。でも CLAUDE.md の 700 行を、結局すべての task で読む別ファイルへ移しただけなら、見た目はきれいになっても本質は変わりません。

私は root instruction を「ほぼすべての task が必要とする最小の共通層」と考えるようになりました。project の最上位目的、安全境界、deeper instruction の見つけ方、全変更に共通する検証原則は root に置いていい。一方、web/ 以下でしか成立しないルールはその directory の近くに置く方が自然です。staging release や code review のような繰り返し作業なら Skill に近い。root budget、Skill 名の重複、compatibility link の破損のように決定的に判断できるものなら、私は prose を増やすより CI で止めたいです。

つまり「AGENTS.md と CLAUDE.md をどう分けるか」ではなく、instruction 全体を ownership graph として見るようになりました。root は一つの owner、scoped instruction は別の owner、Skill は繰り返し workflow をつなぐ役割、docs は常駐させる必要のない背景や説明を持つ場所、そして machine-checkable な制約は code / CI に寄せます。

ここで「全部 Skill にすればいい」とも思いません。Skill も簡単に百科事典になります。今はルールを見ると、まずかなり素朴な質問をします。README だけを直す task でも必要か。特定 directory に入ったときだけ必要ではないか。繰り返し実行する workflow ではないか。モデルに頼らず software が正否を判定できないか。

Nession の migration が面白いのは、知識を消したのではなく置き場所を変えたことです。root は小さくなった一方で scoped owner は増えています。単純な「文書削減」とはかなり違います。

## migration 前後の固定 snapshot を自分でもう一度測った

PR の報告値をそのまま使わないため、Nession の script は実行せず、GitHub API から二つの immutable SHA の tree / blob を読みました。migration 前は 2d57f38ca917a327e5e4bdd7545d1e5dc90bc0bb、後は 7d89c460ea302ea3eeb4380341055b6f2a1da39c です。repository を checkout せず、第三者の hook、package script、workflow も実行していません。

再計測すると、root instruction は 760 行から 116 行へ減り、約 84.74% の縮小でした。文字数は 55,160 から 5,734 へ。8 個の主要 Skill entrypoint は合計 4,079 行から 1,327 行になり、約 67.47% 減っています。

| 指標 | migration 前 | migration 後 | 減少率 |
| --- | ---: | ---: | ---: |
| root instruction 行数 | 760 | 116 | 84.74% |
| root decoded characters | 55,160 | 5,734 | 89.60% |
| 8 Skill entrypoint 行数 | 4,079 | 1,327 | 67.47% |
| 8 Skill entrypoint characters | 161,324 | 42,710 | 73.53% |

ただし、この表は簡単に誤解できます。migration 後に repository の「ルール」が 116 行しか残っていないわけではありませんし、token cost が 84% 減った証拠でもありません。migration 後は root、Web、protocol、agent runtime、design、scripts、GitHub workflows、docs それぞれに canonical AGENTS.md owner が存在しています。

知識は残っています。違うのは、すべてを every task の default context に押し込まなくなったことです。

私はここが progressive loading の一番重要な部分だと思っています。短い CLAUDE.md を競うのではなく、always-on layer を必要最小限にし、task-specific な知識を実際に必要な場所へ近づける。長期運用では、行数そのものより locality の方が効いてきます。

この migration を見ながら、構造自体も小さく検証してみました。Content Lab 側に書いた validator は Nession 固有の path を持たず、抽象的な instruction graph だけを見ます。root budget の超過、editable compatibility copy、broken local link、重複 Skill name、frontmatter の欠落、canonical owner のない scoped compatibility file、存在しない target を向く symlink などを検出します。

それぞれ positive / negative fixture を用意し、8 ケースすべて想定通りの error を出しました。複雑な仕組みではありませんが、私にとってはこれが重要でした。「instruction architecture をきれいに保つ」というルールの一部は、人の注意力ではなく普通の deterministic code で十分守れます。

## Codex と Claude Code は compatibility layer を単純にしにくい

ここまで来ると、次のような directory を標準形として書きたくなります。

~~~text
AGENTS.md
CLAUDE.md -> AGENTS.md
.agents/skills -> .claude/skills
~~~

Nession には似た compatibility surface があります。ただし、私はこれを universal standard とは書きません。

OpenAI の現在の [Codex prompting guide](https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide) では、Codex が上位 location から working directory へ向かって AGENTS.md を読み、より深い instruction が後から context に入る挙動が説明されています。そのため「small root + scoped AGENTS.md」という設計には明確な根拠があります。

一方 Skill path は一つの directory 名へ固定しない方が安全です。現在の OpenAI 資料を見ると、product / migration path によって repo-scoped な置き方が複数登場します。[Skill eval の記事](https://developers.openai.com/blog/eval-skills) と [Claude Agent SDK migration guide](https://developers.openai.com/cookbook/examples/agents_sdk/migrate-from-claude-agent-sdk/readme) を比べるだけでも、安定させるべきなのは directory 名ではなく owner と compatibility mapping だと分かります。

Claude Code 側も変化しています。現在の [memory / instruction docs](https://code.claude.com/docs/en/memory) は AGENTS.md を直接扱えますし、CLAUDE.md は簡潔に保つことを勧め、目安としておよそ 200 行以内を挙げています。path-scoped rule は局所制約に、multi-step workflow は Skills に向いています。[Skills docs](https://code.claude.com/docs/en/skills) も body を必要時に読み込む progressive な形です。

そのため「Claude と互換にするなら必ず CLAUDE.md -> AGENTS.md にする」という書き方も強すぎます。両方のファイルがある場合は version や Project instructions 設定が関係しますし、symlink は macOS / Linux では便利でも Windows では Git checkout や編集の扱いを考える必要があります。

私は今なら、小さな compatibility matrix を持ちます。canonical owner はどれか、adapter はどれか、その client version がどの Skill path を本当に discovery するか、Windows では何に置き換えるか。path は実装詳細で、owner の方が architecture です。

## 今 repository を整理するなら、まず「誰が持つか」を決める

Coding Agent を使い始めたばかりの小さな project なら、最初から十数個の instruction directory は作りません。数十行の AGENTS.md で十分なら、そのままでいいと思います。

本当に refactor したくなるのは、root が内部マニュアルのようになり、同じルールが root / Skill / docs に複製され、directory 固有ルールが別 task へ干渉し、agent の失敗が起きるたびに「prompt に一行追加」するしかなくなったときです。

その段階では、一つずつ owner を決めます。global constraint は root、directory 固有 invariant はその近く、繰り返す作業は Skill、長い背景説明は docs、決定的にチェックできる制約は validator / CI へ。

特に high-risk rule を自然言語だけに残すのは避けたいです。migration 失敗後の証拠を消してはいけない、release 前に特定 gate が必要、ある directory に mock implementation を入れてはいけない。こうしたルールの損失が大きいなら、Prompt は理由を説明し、Skill は手順を案内し、最後の guardrail は executable である方が安心です。

今回の experiment で確認できたのはそこまでです。Nession の root と Skill entrypoint が構造的に大きく縮小したこと、そして instruction graph の代表的な regression を小さな validator で検出できることは確認できました。一方、認証済み Codex / Claude Code client を使った task benchmark は行っていないので、task success が何%上がった、token usage が何%下がった、という話はしていません。

それでも、私の見方はかなり変わりました。AGENTS.md や CLAUDE.md がまた長くなったとき、最初に考えるのは「この 500 行をもっと賢く書く方法」ではなく、「そもそも何行が always-on である必要がないのか」です。

Codex 自体が workflow layer をどう広げているかを見るなら [新しい Codex は何が変わったのか](/ja/posts/what-changed-in-the-new-codex/) がつながります。モデル外の permission、context、memory、guardrail に興味があるなら [Claude Code のソース流出から分かる Harness Engineering](/ja/posts/claude-code-source-leak-harness-engineering/) の方がこの話の次に近いです。