この記事は

初学者の個人的な学習記録が主な目的です。

同じ立場の人、これからエンジニアを目指している人に届けばと思って書いています。

⚠️ 楽しく書きたいので、所々言葉を崩しています、ご了承ください。

この記事の作業中に見つけた「skillのdescription常駐問題」は、前回の記事で深掘りしているので、ここでは軽く触れるだけにします。

目次

要約でち
きっかけ
「何を削っていいか」問題にぶつかった
実食（実践）
CLAUDE.md 100行→31行、agents 10体→5体にした
削っただけで終わらせず、3本の検証をした
claude doctorという答え合わせツールの存在を知った
ついでに、環境の別の腐敗も見つかった
「同時2体まで」って、本当に効いてるの？
今回の調査で知れたこと
参考

要約でち

Anthropicが「Claude Codeのシステムプロンプトを80%以上削除して性能低下なし」という新しいプラクティスを出したのを見て、自分の ~/.claude（CLAUDE.md 100行・agents description合計17,258B・skills 164個）を全面的に見直した
ただ削ると事故る。Anthropicの記事自体には例外基準が書かれていなかったので、permissions.denyという別レイヤーの仕組みと比べながら、自分で「縛ったままにする範囲」を決めてから作業した
Wave単位で1コミットというルールでgit管理下に置き、いつでも git revert で戻れる状態を作りながら進めた
CLAUDE.mdは100行→31行、agentsのdescriptionは17,258B→1,017B（94%削減）
削った後、実際にスキルやルールが発火するか3本の検証をした
手作業が終わったあと、claude doctorという診断コマンドで答え合わせをした。ここで見積もり（5.4k削減のつもり）と実測（2.2k）が2.5倍ズレていることが分かった
「サブエージェント同時2体まで」という自分のルールが、実は決定論的な制約になっていないことにも気づいた
ついでに、廃止されたAWS向けMCPサーバーの放置や、Homebrewのcodexが壊れたsymlinkのままcommand not foundになっていた事故も見つかって直した

きっかけ

その日、人類は思い出した。
奴らに支配されていた恐怖を。
鳥かごの中に囚われていた屈辱を。
Anthropicがこの記事を出した速報を。

We removed over 80% of Claude Code's system prompt for models like Claude Opus 5 and Claude Fable 5 with no measurable loss on our coding evaluations.

（訳：Claude Opus 5やClaude Fable 5向けに、Claude Codeのシステムプロンプトを80%以上削除したが、コーディング評価に測定可能な性能低下はなかった）

はい、ということで！
自分の ~/.claude を見てみた！のコーナーです。

CLAUDE.md：100行
agentsのdescription合計：17,258バイト
skills：164個

こちとら、一生懸命「やめろめろめろ、イタチめろ」って増やしていったのに対して、Anthropic様は「システムプロンプトを80%削れ」と言ってきました。

これはもう、UNOでいうところのリバース（違う）
これはもう、大富豪で言うところの革命ですよ（こっちは多分あってる）

📝 ここまでのポイント

Anthropicが「システムプロンプトを80%以上削除して性能低下なし」という記事を公開
自分の環境（CLAUDE.md 100行・agents description 17,258B・skills 164個）は真逆に肥大化していた

「何を削っていいか」問題にぶつかった

じゃあ削ろう、となったところで、すぐ壁にぶつかった。

何でもかんでも削っていいわけじゃない。

たとえば私の rules/aws.md には「NAT Gatewayは原則使わない」「ルートアカウントは使わない」みたいなルールが書いてある。

『削ったらお金が飛ぶかセキュリティ事故が起きるやつちゃうか？』

電流走る

・「モデルの判断力を信じて指示を減らす」という新しいプラクティスと
・「初学者だから安全側のガードレールは要る」という自分の事情が、真正面からぶつかったのだ。

初学者は困ったら公式に泣きつこう

そこで我々はアマゾンの奥地へAnthropicの記事に答えを探しに戻った。「安全系の指示は例外的に残していい」みたいなことが書いてあれば、それを基準にできるやないの！！

ふぅ〜！！！！

はい、書いてなかった。

記事は「指示を削れ、モデルの判断力を信じろ」としか明言していない。
安全や不可逆操作についての例外は、どこにも出てこない。
じゃあ何を根拠に「rules/aws.mdは残す」と判断すればいいのか。

Claude Codeには、そもそも指示文とは別の層で不可逆操作を止める仕組みがある。

permissions.denyという設定で、Bash(git push --force *)のような危険なコマンドを、指示文で「やめて」と書かなくてもツール側でブロックできる。しかもdenyはallowより常に強く、後から誰かが緩めることもできない。

つまり rules/aws.md の「NAT Gatewayは原則使わない」のような指示は、deny設定で機械的に止められる領域とは別物。

deny は「特定のコマンドを実行させない」ことしかできない。「NAT Gatewayを使うと月4,000円かかると気づいて設計を見直す」みたいな、判断を伴う注意はdenyでは代替できない。指示文で縛るしかない領域と、設定で縛れる領域が、そもそも別レイヤーだった。

わかりやすく比喩コーナー

パパとママは人を殴ったらダメって僕に言ったことないけど、六法全書に書いてあるから人は殴らないもん。
あと、パパとママは、女の子を泣かせたらダメなんだって言ってたから、優しくするんだ。

って六法全書を持った、法律を尊守する、女の子に優しいくろーど君を誕生させられるってこと

これで基準がはっきりした。

自分で立てた基準

行き着いたのが「安全・お金・不可逆操作に関わるような指示のうち、denyのような設定側の仕組みで代替できないものだけは縛ったままにする」というルール。

削る対象：LLMの自己検証指示、繰り返しの例示、冗長な説明
残す対象：お金が発生する操作への注意、判断を伴う不可逆操作の防止、秘密情報へのアクセス制限

この基準を最優先にして、そこからはみ出さない範囲で削っていくことにした。
実際、rules/aws.md はこの基準のおかげで最終的に一文字も変えなかった。中身のほぼ全部が請求トラップ・IAM最小権限・シークレット管理で、まるごと「残す対象」だったから。

📝 ここまでのポイント

公式記事に「安全系は例外」という基準は書かれていなかった
permissions.deny（設定で縛れる領域）と指示文（判断を伴う注意）は別レイヤーと気づき、そこから基準を立てた
rules/aws.md は基準のおかげで一文字も変えずに済んだ

実食（実践）

設定ファイルを一気に書き換えるのは怖い臆病者なので、Wave取り決めて、コミットしつつ全速前進DA！

一応手法を書き記しておきマッチョ

① ~/.claude をgit管理下に置く。 ただし全部コミットするわけじゃない。allowlist方式の.gitignoreにして、projects/（会話履歴）とagent-memory/（機微情報）は最初から除外した。

② Wave（作業の区切り）1つにつきコミット1つ。 何かおかしくなったら git revert <該当Waveのsha> で、その回の変更だけを個別に戻せる状態にした。

ここはClaudeCodeくんに託した

cd ~/.claude
git log --oneline
# b2b9597 Wave 0: 最適化前のベースラインを記録
# 76db75d Wave 2: CLAUDE.md から機能を移す受け皿 Skill を作成
# b73c350 Wave 3: CLAUDE.md を100行から31行へ再設計
# ...

Wave 0はベースラインを記録するだけの回。 ここで「今の状態」を測っておかないと、後で「削減できた」と言っても、それが本当に自分の作業の成果なのか、比較のしようがなくなる。

~~この後、我々は大きな過ちを犯してしまったことに気付く...~~

📝 ここまでのポイント

~/.claudeをgit管理下に。projects/とagent-memory/は機微情報のため除外
Wave 1つ＝コミット1つ。壊れたらgit revertで個別に戻せる状態にした
Wave 0はベースラインを記録するだけの回（この判断が後で効いてくる）

CLAUDE.md 100行→31行、agents 10体→5体にした

ここからが本番。

CLAUDE.md（Wave 2〜3）

100行・6,889バイトから、31行・2,474バイトに削った。禁止形（「〜してはいけない」という指示）は16件から4件に減らして、残した4件は全部「安全系」（機密情報の取り扱い・破壊的操作の確認など）にした。

削った代表例が「Skills一覧」のセクション。CLAUDE.mdに全skillの説明を書いていたんだけど、これはまさにAnthropic様が私を名指しで批判していた件ですね。

A common myth is that you want to make these a central repository for every known practice that you might run into, because Claude would not find it otherwise.

（訳：よくある誤解は、CLAUDE.mdやSKILL.mdを「知っているすべての慣習の中央リポジトリ」にしようとすることだ。そうしないとClaudeが見つけられない、と思い込んでいるからだが）

削った内容の受け皿として、skillspectorとjapanese-writingという2つのskillを先に作ってから本体を削るという順番にした。

逃げ先を先に用意する（大事）

agents（Wave 5）

10体から5体に統合。使われていない4体と、重複していた1体を削除して、残った5体のdescriptionを**17,248バイトから1,017バイト（94%削減）**にした。

Persistent Agent Memoryを消した話

さらに、各agentファイルの末尾に自動でついてくる定型文（＝ボイラープレートのこと）約150行も全部消した。

具体的に何の話かというと、agentの定義ファイル（例：~/.claude/agents/code-reviewer.md）の末尾に、こういう文章が自動で貼られていた。

## MEMORY.md

Your MEMORY.md is currently empty. As you complete tasks, write down
key learnings, patterns, and insights so you can be more effective in
future conversations.

（訳：あなたのMEMORY.mdは今のところ空です。タスクを完了するたびに、重要な学び・パターン・気づきを書き留めておくと、次回以降の会話でもっと役に立てます）

これは**agents/code-reviewer.mdという設定ファイルの中に書かれた説明文**。「まだ何も記録されていないよ」という案内文。

一方、実際にcode-reviewerが記録を書き込む場所は別のファイルにある。~/.claude/agent-memory/code-reviewer/MEMORY.mdという、agentごとに専用の記憶ファイル。開いてみたらちゃんと書いてあった。

# Memory Index

- [user_profile.md](user_profile.md) — Toriumi: ほにゃらら
- [project_adhd_patterns.md](project_adhd_patterns.md) — ほにゃらら
...

思いっきり中身が入っていた。 つまりはこういうこと。

ファイル	役割	実際の状態
`agents/code-reviewer.md`（説明文）	「MEMORY.mdは空だよ」と案内する定型文	agent作成時にコピペされたまま、更新されていない
`agent-memory/code-reviewer/MEMORY.md`（実データ）	実際にagentが記録を積み重ねる先	ちゃんと使われていて、中身が入っている

説明文の中の「空です」という一文と、本物のファイルの実態が食い違っていた。
「空です」はagentを作った瞬間だけ正しくて、その後どれだけ記録が増えても、説明文のほうは書き換わらずに固まっていたらしい。

定型文をコピペして使い回した結果なのか、私の脳では焼き切れそうになったため、これ以上深掘りはしていないので、書いてある内容と実態がズレていた、という話なんだなと軽く理解しておくことにした。

その後はfrontmatterにmemory: userと1行書くだけでこの機構自体は動くことを、別のagentで検証してから展開した。

📝 ここまでのポイント

CLAUDE.md：100行→31行、禁止形16件→4件（全部安全系）
agents：10体→5体、description 17,248B→1,017B（94%削減）
各agentの説明文に「MEMORY.mdは空です」と固定で書かれていたが、実データファイルには中身がしっかり入っていた（説明文だけが更新されず古くなっていた）

削っただけで終わらせず、3本の検証をした

description を94%削って、一番怖かったのは**「agentsやskillsが正しく起動するか」**だった。名前と説明が減った分、Claude自身がそれを見て「これを使うべきだ」と判断できなくなるかもしれない。

セッションを再起動したあと、3つのトリガーを実際に投げて確認した。

トリガー	期待する挙動	結果
「AWS Lambdaのコールドスタート対策を調べて」	`tech-researcher` agentが起動	✅ 起動。要点と出典まで返した
「支払督促が届いた」	`japan-debt-welfare-law` skillが起動し、2週間の異議申立て期限に言及	✅ 起動。民事訴訟法386条の期限に明示的に言及
`amplify/`配下のファイルを開いて「NAT Gatewayを入れたい」	`rules/aws.md`が発火し料金目安を出す	✅ 発火。月額目安を提示

3本とも、effort（＝Claudeの思考の深さを調整する設定）をmediumのまま通った。一番警戒していた「description圧縮で起動しなくなる」リスクは、実際には起きなかった。

📝 ここまでのポイント

削って終わりにせず、実際にトリガーを投げて起動確認まで行った
3本とも medium effort のまま通過。description 94%削減でも実害なし

`claude doctor`という答え合わせツールの存在を知った

手作業がひと通り終わったあと、claude doctor（/doctor）というコマンドの存在を知った。

これは、全プロジェクトのセッション履歴を横断的に見て「使われていないskill・plugin・MCPサーバー」を洗い出してくれる診断ツール。

先に手を入れず、まずdoctorを走らせてから比較するべきだったのでは？？？

理由はWave 0でベースラインを取ったのと同じ。
先に変更してしまうと、doctorの結果が「元々そうだった」のか「自分の変更の効果」なのか、切り分けられなくなる。

とりあえず途中だったけど、コミットしてなかったので実行してみた結果、全プロジェクト・直近50セッション・生涯438起動を横断したdoctorが、こんなことを教えてくれた。

ある拡張機能（プラグイン）が生涯使用回数0で、約80個のskillを一覧に常駐させていた
生涯使用回数0のskillが14個あった

これらを無効化したところ、実測は以下の通り。

Skills · /skills
Before: 9.9k tokens・164 skills
After : 7.7k tokens・74 skills

ただ、ここで見積もりを外した。実行前は5.4k減るつもりだったのに、実測は2.2kだった。2.5倍のズレ。 このズレの計算過程は前回記事で詳しくやったので、ここでは結論だけ。

実際に消した90件の多くは一行だけの短いdescription（20〜50トークン程度）で、残した74件のほうがむしろ丁寧に書かれた長めのdescriptionだったからですね。

📝 ここまでのポイント

手を入れる前ではなく後にdoctorを走らせてしまった（本当は先に走らせて答え合わせに使うべきだった）
実測：Skills 9.9k→7.7k、164件→74件
見積もり5.4k削減 vs 実測2.2k削減。件数ベースの見積もりは2.5倍外れた（詳細は前回記事）

ついでに、環境の別の腐敗も見つかった

doctorを走らせている過程で、本題と関係ない放置物も2つ見つかった。

① 廃止されたAWS向けMCPサーバー。 aws-diagram-mcp-serverというダイアグラム生成用のMCPサーバー（＝外部ツールと接続する仕組みのこと）を設定していたが、接続が失敗していた。調べたら、AWS側がこのMCPサーバー自体を廃止して、aws-architecture-diagramというskillに置き換えていた。上位互換があったので、設定からは削除した。

② Homebrewのcodexが壊れたsymlinkのまま放置されていた。 codexコマンドを打つとcommand not foundになる。原因を追うと、symlinkの先である/opt/homebrew/Caskroom/codex/0.130.0/のディレクトリが空になっていた。brew reinstall codexで0.145.0が入り直して直った。さらに、別のnode バージョン管理下に**孤立した旧インストール（134MB）**も見つけて回収した。

環境って、自分で意図的に触った部分だけじゃなく、外部のツールが向こう側の都合で変化することでも静かに腐っていく。今回はたまたま監査のタイミングで巻き込みで見つかったけど、これ専用の点検をどこかに置いたほうがいい気がしている。

なお、このdoctor監査で見つけた「セキュリティスキャナーが権限設定までは見ていない」という話（.claude/settings.jsonのacceptEdits問題）は、前回の記事で詳しく書いたので、ここでは省略する。

📝 ここまでのポイント

AWS側が廃止したMCPサーバーを放置していた（上位互換のskillに置き換え済みと判明し削除）
Homebrewのcodexが壊れたsymlinkでcommand not foundになっていた（再インストールで復旧、孤立した旧版134MBも回収）
環境は自分が触らない部分でも、外部都合で静かに腐る

「同時2体まで」って、本当に効いてるの？

記事を書きながら、自分がWave 3で書かせたこのルールを見返した。

サブエージェントは、過程が結果より長いタスク（Web 調査・広範なコード探索）にだけ使う。1つの依頼につき同時2体まで。判断や設計は委譲しない

改めて見て、疑問が湧いた。この「2体まで」、何が保証してるの？

＿人人人人人人人人人人人人人人人人人人人＿
＞ 理由がどこにも記録されていなかった。 ＜
￣Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^￣

Wave 0のベースラインには「調査・デバッグはサブエージェントに委譲」というゆるい一文しかなくて、Wave 3で今の形に書き換えた時の判断根拠が抜けていた。

じゃあ、この制約は実際どう働いているのか整理してみた。

rules/aws.mdのBash(git push --force *)のようなdenyルールは、システム側がツール呼び出しをブロックする機械的な仕組み。
一方「同時2体まで」は、そういうdenyのルールでは表現できない。permissionの仕組みは「このツールをこの引数で呼ぶな」しか書けなくて、「Agentツールを3回目呼んだら止める」という回数の制限には対応していない。

つまりこの「2体まで」は、rules/aws.mdと同じ指示文の層にある。
Claudeくんがそれを読んで、自分の判断で守っているだけ。技術的に止める仕掛けはどこにもない。

そう思ってAnthropicの別のドキュメント（Claude Opus 5向けのプロンプティングガイド）を読み直したら、これやろって文章発見。

Delegate to a subagent only for large tasks... or set a deterministic upper limit on how many agents can be spawned.

（訳：サブエージェントへの委任は本当に独立した大きなタスクにだけ限定するか、起動できるエージェント数に決定論的な上限を設定してください）

「決定論的な上限」。ここで言う「決定論的」は、「毎回同じ出力になる」という意味じゃない。 「その制約を、Claudeの判断を経由せずに、コード側が強制できるか」という意味。

言い換えるとこう。

決定論的な上限：denyルールみたいに、Claude Codeというツール自体が「3回目のAgent呼び出しはブロックする」と機械的に判定する。Claudeが何を考えていようと関係ない。Claudeの意思を通り越して止まる
プロンプトの指示：CLAUDE.mdに「2体まで」と書いてあるのを、Claudeが読んで「じゃあ2体で止めよう」と自分で判断する。Claudeの意思を経由して初めて守られる

後者は、Claudeの判断というワンクッションを挟む。ということは、その判断が状況次第でブレる可能性を常に持っている。effortを上げれば積極性が増す、他の指示と競合すれば優先順位が入れ替わる、そもそも読み落とすことすらありえる。「守られるかどうかが、Claude次第になっている」状態は、Anthropicが言う「決定論的」の対極にある。

つまりClaudeくんの意思が介入しているか、していないか。

『てか、数決めるのどうなん？後出しで決めた方が融通きくんじゃね？』

わかるよぉカ○ジ君。

ちとここで、考えてみた

自分が指定を忘れる：忙しい時、いちいち「2体までで」と言い直さない
Claude自身が判断で超える：「このタスクなら3体使ったほうが早い」と、こちらが何も言っていないのに勝手に広げる

『どっちが、リスキーだろう』

同じOpus 5のガイドが「タスクのスコープを拡大し、要求されていないステップを追加したり、タスクがどうあるべきかについて独自の判断を適用したりすることもある」と、モデル自身の性質として明記している。標準ルールを1回書いただけでは、この性質を止めきれない？

『じゃあどうするのが正解か』

標準ルールを消して、毎回自分で数を指定する運用に切り替える、という手もある。
その場で送るメッセージの指示は、CLAUDE.mdに埋もれた1行より具体的で新しいぶん、優先されやすい。
でも、それだけに寄せるのも危ない。

言い忘れた瞬間、歯止めがゼロになる。

なので今のところの結論は、標準ルールを保険として残したまま、必要な場面だけその場のメッセージで上書きする、二段構え。

「同時2体まで」の実態

CLAUDE.mdの標準ルールはdenyと違い、機械的な強制力を持たない指示文
歯止めが外れる経路は2つ：ユーザーが言い忘れる／Claudeが自分の判断で超える
Anthropic自身が「決定論的な上限」を推奨しているが、プロンプトによる指示はそれを満たさない
対策は「標準ルールを保険として残しつつ、必要な場面はその場の指示で上書きする」二段構え

ちなみに同じ日、superpowersという開発プロセスを丸ごと強制するプラグインを無効化していたことにも気づいた。要件定義→設計承認→TDD→サブエージェントを自動で何時間も走らせるという思想のプラグインで、方向性が今回の「指示を減らして判断は自分で持つ」という設計と正面から矛盾する。無効化した理由もどこにも記録されていなかったけど、今回の軸に照らせば筋は通っていたのかな。

📝 ここまでのポイント

「同時2体まで」はdenyのような機械的強制ではなく、Claudeの判断を経由するプロンプトの指示にすぎなかった
Anthropic自身が「決定論的な上限」を推奨しており、今の実装はその水準に届いていない
対策は標準ルール（保険）＋その場の上書き（柔軟性）の二段構え

まとめ

Opus5くんは『やるな！』って言ったら拗ねてしまうので『OOをしよう！』って小学生の友達を誘う気持ちで行こう！

あと、門限を設けてあげないと、夜遅くまで遊んじゃうから、制限かけたい時は忘れずにね😘

今回の調査で知れたこと

公式記事は「削れ」しか言っていない。例外基準は自分で立てる必要がある。 「安全・お金・不可逆操作」に関わる指示は削らない、というのは記事にない自作の基準。denyという別レイヤーの存在に気づいたことで、根拠を持って線引きできた
Wave単位のコミットは、失敗した時の切り戻しコストを大きく下げる。 全部まとめて1コミットにしないほうがいい
ベースラインは、手を入れる前に測る。 変更後に測ると、その数字が元々そうだったのか自分の変更の結果なのか切り分けられなくなる
description圧縮の効果は、実際にトリガーを投げて検証するまで信用しない。 94%削っても3本とも通ったのは、確認したから言えること
claude doctorは診断ツールなので、変更前に走らせて答え合わせに使うのが正しい順番
件数で削減量を見積もると外れる。 description1件あたりのトークン単価はskillごとに大きく違うので、文字数ベースで見積もるべき
「同時2体まで」のような数の制約は、denyで表現できない。 denyはClaudeの判断を経由せずコード側が強制するが、プロンプトの指示はClaudeが読んで自分で判断して初めて守られる。だから自分が言い忘れる／Claudeが自分の判断で超える、という2つの経路で外れる。標準ルール＋その場の上書き、の二段構えが必要
環境は自分が触らない部分でも腐る。 外部ツールの廃止・更新に巻き込まれて壊れているものが、定期監査で見つかることがある

参考