書いた指示が黙って無視される副業AI運用、Claude Code 2.1.277のAGENTS.md仕様に合言葉検証を挟む工程設計

AIで副業の仕組みを作れる人ほど、なぜか収益が伸びない時期がある。自分もSIerで10年以上コード書いてきて、副業でAIエージェントを運用しているけれど、手応えが出ない時期は長かった。原因を一つに絞れないのは分かってるけど、後から振り返って一番痛かったのは『設定ファイルは自分の意図どおりに読まれている』と信じ込んでいたことだった。

2026年9月18日にリリースされたClaude Code 2.1.277で、AGENTS.mdという別の設定ファイルが読まれるようになった。ただしこの仕様、Qiitaで実測レポートを出しているsuwa_nobu氏（株式会社JQIT）が合言葉検証で明らかにしたとおり、罠が3つほど積んである。1回目のセッションでは読まれない、CLAUDE.local.mdを1つ置くだけで黙って無効化される、AGENTS.local.mdは読まれない。公式changelogとドキュメントに書いてはあるけど、読み飛ばすと確実にハマる。

この記事は「AGENTS.mdの使い方解説」ではない。副業でAIエージェントを回している立場から、こういう仕様変更が入った時にどう振る舞うかで収益が変わる、という話をしたい。仕組みを作れる人ほど、設定ファイルの読み込み仕様みたいな地味な穴で時間と信頼を溶かす。

仕組みを作れても稼げない人が見落としている『設定ファイルは本当に読まれているか』
1. AGENTS.mdが1回目のセッションで無視される仕様
2. CLAUDE.local.mdが黙って優先順位を書き換える仕様
AIツールを増やすたびに増える『見えない前提』のコスト
検証してから信じる姿勢が、副業運用の収益を守る
まとめ
参考
【PR】おすすめの書籍
1. あわせて読みたい

仕組みを作れても稼げない人が見落としている『設定ファイルは本当に読まれているか』

自分の観測範囲だけど、AI副業で「作れるのに稼げない」層はだいたい同じ勘違いをしている。書いた設定はAIが必ず読んでいる、と暗黙に信じているところ。実際にはツールの設定ファイル読み込みは、バージョンや設定の組み合わせで挙動が変わる。読まれていない前提で書いた指示は、当然結果に反映されない。反映されない指示を根拠に「精度が足りない」「モデルが弱い」と結論を出して、次の対策を空振りさせる。

2026年9月に入ったClaude Code 2.1.277の変更は、この層に直撃する種類のものだった。CLAUDE.mdが無いプロジェクトでAGENTS.mdが読まれる、という一見シンプルな追加機能だけど、実測すると挙動が細かく分岐する。suwa_nobu氏の記事では、各ファイルに一意な合言葉（例：The AGENTS passphrase is AGENTS-ORANGE-7731.）を仕込んで「指示にある合言葉を全部挙げろ」とClaude Codeに聞き、返ってきた合言葉で読み込みの有無を判定していた。ファイル読み込み系のツール（Read、Grep、Bash等）は全部--disallowedToolsで禁止、MCPも空設定にする徹底ぶり。ここまで環境を隔離しないと、ツールが勝手にファイルを開いて「読まれた」ように見えてしまう。

自分もこの検証方法は使ったことがある。エージェントの動作確認で「本当にこの指示を見ているのか」を確かめる時、指示ファイルに一意なマーカーを入れて出力に出るか確認する。地味だけど、これをやらないと『動いているように見えて動いていない』状態を見逃す。副業で自動化を組んでいる人ほど、この確認を挟まずに次のタスクに進みがちで、後で「なんで反映されてないんだ」と数時間溶かす。

AGENTS.mdが1回目のセッションで無視される仕様

公式ドキュメントに書いてある注意書きだけど、盲点になる。Claude Codeを2.1.277以降にアップグレードして、AGENTS.mdだけ置いたプロジェクトで初回セッションを立ち上げると、AGENTS.mdは読まれない。2回目以降のセッションから読まれ始める。公式にはClaude reads AGENTS.md from your next session onと明記されている。

suwa_nobu氏は新しい設定ディレクトリを用意して、続けて4回セッションを投げる検証をしていた。セッション1は読まれず、セッション2・3・4は読まれた、という結果。これを知らずに「アップグレードしたから試そう」と1回投げて「効いてないじゃん」と判断すると、間違った結論を持ち帰る。

副業運用の視点で見ると、これは『初回だけ結果が違うツール』を組み込むリスクの話でもある。自動化パイプラインに新しいツールや設定を差し込む時、1発目の挙動だけで検証を終わらせると、2発目以降の実運用でズレる。自分は記事生成のパイプラインでモデル振り分けを変えた時、テストで1本だけ走らせて「動いた」と判断して本番に流し、翌日に3本連続で品質スコアが下がっているのを見て慌てて戻したことがある。1発目と2発目以降で挙動が変わるパターンは、AIツール全般で起き得ると思っていい。

Claude CodeのAGENTS.md初回セッション問題も、性質としては同じカテゴリ。「アップグレード直後の1回で判定しない」という単純なルールだけど、これを見落とすと数日は原因追求で溶ける。

CLAUDE.local.mdが黙って優先順位を書き換える仕様

こっちの方が怖い。個人のメモをCLAUDE.local.mdに書いてリポジトリにコミットしない運用は珍しくない。チームの共通指示はAGENTS.md、個人の一時メモはCLAUDE.local.md、みたいに使い分ける発想。

このCLAUDE.local.mdを1つ置いた瞬間、Claude CodeはAGENTS.mdを読まなくなる。suwa_nobu氏の検証結果でも明確に出ていて、AGENTS.md+CLAUDE.local.mdの組み合わせだと、返ってくる合言葉はCLAUDE.local分とユーザー階層（~/.claude/CLAUDE.md）分だけ。AGENTSは無し。公式ドキュメントにもCLAUDE.local.md counts, adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you.と注意書きが載っている。claude -pのログには警告もエラーも一切出ない、と検証記事にある。

チーム開発を想像すると分かりやすい。リーダーがAGENTS.mdにコーディング規約を書き、メンバーが各自のCLAUDE.local.mdに個人のショートカットメモを置く。この状態でメンバーがClaude Codeを回すと、チームの規約は読まれず個人メモだけが効く。誰も気づかないままレビューでズレた成果物が上がってくる。

両方読ませたい場合は~/.claude/settings.jsonに以下のような設定を入れる必要がある。

"pluginConfigs": {
  "agents-md@builtin": {
    "options": {
      "instructionFiles": "claude-md-and-agents-md"
    }
  }
}

公式によると、この設定はプロジェクトやローカルの設定に書いても無視されるので、ユーザー階層のsettings.jsonに書く必要がある、と検証記事にある。

副業で受託寄りの案件を取る時、この手の「デフォルトで沈黙する仕様」を知っているかどうかは、そのまま単価に効いてくる。動かない原因を1時間で特定できる人と、3日かけて『AIモデルの精度問題』と誤診する人では、次の依頼が来るかどうかが変わる。稼げないフェーズを抜けるには、こういう地味な仕様知識の在庫を積む方が、新しいAIサービスを触る時間より収益に直結する場面が多い。

AIツールを増やすたびに増える『見えない前提』のコスト

AGENTS.mdの話は、単体で見ると「Claude Codeの仕様の話」だけど、副業運用の視点だと『AIツールを増やすたびに、見えない前提が積み上がっていく』という構造の一例に見える。

1つのAIツールが持っている暗黙の前提は、だいたい次の4種類に分かれる。

①読み込みルールどのファイルを、どの順序で、どの条件で読むか

②優先順位ルール複数の指示が衝突した時、どれが勝つか

③発火タイミングインストール直後・アップグレード直後・初回セッション等で挙動が違う場合

④無音の失敗期待した動作が起きなかった時、ログや警告が出るか出ないか

AGENTS.mdの件でいえば、①でファイル判定の複雑さ、②でCLAUDE.local.mdの優先順、③で初回セッション無効、④で警告なしのサイレント無効化、と4種類すべてに罠がある。1ツールでこの数の前提が積んであると、複数ツールを組み合わせた時に組み合わせ爆発する。

自分の副業運用でも、Claude CodeにCodex CLIを足して、記事レビューを分担させる構成を組んでいるけど、両方のCLIが持つ暗黙の前提を全部揃えるのに結構な時間を使う。片方が読む設定ファイルの場所と、もう片方が読む場所が違う、モデル指定の書き方が違う、認証の永続化の仕組みが違う、というのを1個ずつ潰していく。この作業は華やかさゼロだけど、これを飛ばすと本番で無音の失敗が積み上がる。

無音の失敗が一番怖い。エラーが出れば直せる。警告すら出ずに『指示は無視されたが処理は完走した』状態になると、成果物の品質だけが静かに下がる。副業で自動化パイプラインを回している人が『なんとなく最近アウトプットの質が落ちた気がする』と感じる時、原因の候補にこの手のサイレント失敗を必ず入れておく方がいい。

書いた設定が読まれているか、を確かめる手段はツール側が用意していない場合が多い。だから、AGENTS.mdの検証でsuwa_nobu氏がやっていた『合言葉を仕込んで出力に出るか見る』みたいな自作の確認方法を、自分の運用ツールごとに持っておく必要がある。手間だけど、これが『動いているつもり』を『動いていることを確認した』に変える唯一の方法だと思う。

副業で稼げるフェーズに入るには、機能追加より無音の失敗の検出に時間を使う方が効く場面が多い。新機能を1個足すと売上が伸びるわけじゃないけど、無音の失敗を1個潰すと、それまで気付かず垂れ流していた品質低下が止まって、平均が上がる。地味な作業だけど、効くんですよ。この積み上げが。

検証してから信じる姿勢が、副業運用の収益を守る

suwa_nobu氏の検証記事で個人的に一番刺さったのは、まとめの手前に置かれた『言えないこと』のセクションだった。測ったのは2.1.277だけで2.1.276以前とは未比較、claude -pの1往復で対話セッションでの表示は未確認、サブディレクトリのAGENTS.md・@pathインポート・サブエージェントへの伝播は未測定、各条件2〜3回で回数は多くない、測定中に自分のスクリプトのバグで1条件が偽の結果を出したので作り直して測り直した、と正直に書いてある。

この姿勢が、AI時代の副業で信頼を稼ぐ最短ルートだと思う。派手な結論だけ書いて『これで解決』と言い切る記事は無限にあるけど、条件・回数・自分のバグ発覚まで開示している記事は稀。読み手は『この人の言うことは自分で確かめられる範囲で正確だ』と判断できる。副業でリピート案件を取れる人は、この開示の細かさが違う。

自分が副業でハマった時期を振り返ると、検証を飛ばして『こう動くはず』で先に進んだ時が一番損失が大きかった。動くはずの前提が崩れているのに、その前提の上に3つ4つと機能を積んでしまい、後から掘り返して全部組み直す羽目になる。3時間かけた仕組みが5分で壊れた、みたいな話をよく聞くけど、5分で壊れたんじゃなくて、3時間の最初の10分で検証を飛ばしたのが原因だったりする。

AGENTS.mdの件で言えば、検証しないでいきなり本番プロジェクトに投入するのは避けた方がいい。合言葉を1個仕込んだ捨て設定ディレクトリを作って、--disallowedToolsでツールを封じた状態で1回試すだけで、自分の環境がどう振る舞うかが分かる。この10分の投資で、後から『なんで指示が効いてないんだ』と数時間掘るリスクを消せる。

副業で収益を作れる人と、作れない人の分岐点は、この10分をケチるかどうかだと思う。仕組みが組めるのに稼げない人は、たいてい仕組みを組む速度が速すぎて検証が追いつかない。速度を落とせ、じゃなくて、検証を工程に組み込め、が正しい処方箋。合言葉を仕込む・出力を確認する・ログに出ない失敗を仮定して探す、という地味な工程を1つ挟むだけで、成果物の平均品質は目に見えて上がる。

AIツールのバージョンアップは、これからも頻繁に入る。Claude Codeも数日単位でchangelogが更新される時期がある。全部追いかける必要はないけど、自分の運用に使っているツールの破壊的変更・仕様追加は、リリースノートを見て『これは自分の環境に影響しそう』と判断したものだけ、10分の検証を挟む。この習慣を持てるかどうかで、無音の失敗に飲まれるか、変更を武器にできるかが変わる。

まとめ

Claude Code 2.1.277でAGENTS.mdが読まれるようになったが、1回目のセッションでは読まれない・CLAUDE.local.mdを1つ置くと黙って無効化される、という2つの罠がある
AIツールを増やすたびに読み込みルール・優先順位・発火タイミング・無音の失敗という4種類の暗黙の前提が積み上がる。組み合わせると爆発する
副業で稼げないフェーズを抜けるには、機能追加より無音の失敗を検出する仕組みを工程に組み込む方が効く。合言葉検証のような10分の投資が数時間の損失を防ぐ