9 月の半ばに、Claude Code と Kiro の両方で使うルールファイルを作り直しました。それまで使っていた memory-bank 方式では、書いたはずの指示がセッションの途中から反映されなくなっていたからです。作り直してから 2 週間ほど経ち、タスクも 30 個以上閉じましたが、同じ症状はまだ出ていません。この記事では何を捨てて何を残したかを、その後に足した行の履歴と一緒に書きます。
指示が反映されなくなるまで
作り直す前は、GitHub の awesome-copilot にある Memory Bank の 7 ファイル構成を使っていました。Cline の Memory Bank と同じ構成で、projectbrief、productContext、systemPatterns、techContext、activeContext、progress に、tasks ディレクトリが付きます。同じ構成を今も別のプロジェクトで使っていて、そちらは 7 ファイルで 3,000 行くらいあります。セッションを始めるたびにエージェントはこれを全部読みます。その上に、Karpathy の LLM Wiki の形で LLM が育てる wiki が十数ページありました。
構成としては悪くないと今でも思っています。困ったのは、tasks が増えるにつれて指示が届かなくなったことでした。CLAUDE.md には書いてあるのにやらない。やらないので CLAUDE.md にもう 1 行足す。足すと CLAUDE.md が伸びて、別の行が届かなくなる。当時の ADR にはこう書いてあります。
従来 memory-bank（7ファイル全読み + tasks 蓄積）と llm-wiki（多数ページ）を併用していたが、コンテキストが肥大化し、指示した内容が反映されない現象が出ていた。
もう一つ別の問題として、Claude Code 用の CLAUDE.md と Kiro 用の .kiro/steering/ に同じことを書いていました。片方を直してもう片方を忘れるのは、私の場合ほぼ毎回でした。
捨てたものと残したもの
ADR-0003 として決めた内容を、決めた順に書きます。
ルールファイルは AGENTS.md の 1 つだけにしました。上限は 60 行です。Claude Code 側の CLAUDE.md は 1 行目で AGENTS.md を取り込み、あとは Claude Code 固有の注意を書くだけになりました。今は数行です。
@AGENTS.md
## Claude Code 固有
- hooks が編集後に型チェックと lint を自動実行する（Edit/Write だけでなく Bash 経由の編集も）。失敗時だけ結果が返るので、返ってきたら直してから次に進む。
- 手順が要る作業は skills を使う: adr / task / wiki / cdk / content-gen
- 調査で多くのファイルを読む必要がある時はサブエージェント（Explore）に任せ、結論だけ受け取る。
Kiro は IDE v1.0.309 と CLI v2.18.0 以降で AGENTS.md を標準で読むので、.kiro/steering/ は消しました。これで二重管理が無くなりました。
この決定の翌週、Claude Code 2.1.277 で、CLAUDE.md が無いプロジェクトでは AGENTS.md を読むようになりました。ただし CLAUDE.md がある場合はそちらが優先されます。私のプロジェクトには hooks と skills についての Claude 固有の注意があるので、CLAUDE.md を残して 1 行目で取り込む形を続けています。Claude 固有の注意が無いプロジェクトなら、CLAUDE.md 自体を消せます。その次の 2.1.280 からは Bedrock や Vertex AI 経由でも同じ動きです。
セッション開始時に読むファイルは 3 つに絞りました。AGENTS.md、docs/context.md、docs/tasks/_index.md です。context.md には現在地と直近の変更と次にやることだけを書き、索引には進行中のタスクだけを載せます。wiki は索引から必要なページだけ開き、設計書は全体像が要る時だけ、ADR は設計判断が要る時だけ読む。AGENTS.md の見出しは「セッションの始め方（全部読むな）」にしました。
完了したタスクは docs/tasks/archive/ に移して、読ませません。memory-bank の progress にあたる「これまでの経緯」は git log と ADR で足りました。context.md の冒頭には「歴史は書かない」と書いてあります。
memory-bank の activeContext と progress は context.md の 1 ファイルに畳みました。projectbrief や systemPatterns にあった内容は、原典の企画書と wiki と ADR に分けて吸収し、専用ファイルは持ちません。
最後に、ルールの足し方を決めました。AGENTS.md の 2 行目にこう書いてあります。
Claude Code と Kiro が共有する正のファイル。60行以内を維持する。各行は実際の失敗か固い制約に紐づける。
「こうしてほしい」という願望では行を増やさない。何かがうまくいかなかった時にだけ 1 行足す。これが一番大きな変更だったと思っています。
その後 2 週間で足した行
git log で AGENTS.md の履歴を追うと、どの行がいつ何のために入ったかが分かります。初版から 2 週間で、本文の変更は 5 回でした。そのうち 3 つを書きます。
「長くなったら削る」は守られなかった
初版の context.md についての行はこうでした。
- 作業の終わりに docs/context.md を更新する。長くなったら削る。60行以内。
1 週間で守られなくなりました。エージェントは「直近の変更」に足すだけ足して、古い行を消しません。「長くなったら」の判断を任せたのが失敗でした。そこで行を数値と検査に置き換えました。
- 作業の終わりに docs/context.md を更新する。「直近の変更」は 6 件以内、全体 45 行以内（docs:check が検査。足したら古い行を消す）。
同時に、設計書の検査スクリプト docs:check に context.md の検査を足しました。
if (ctxLines > 45) errors.push(`docs/context.md: ${ctxLines} 行（上限 45。60 行の手前で止める）`);
必須見出しがあるか、「直近の変更」が 6 件以内か、「進行中」の内容が tasks の索引と一致しているかも、同じ場所で見ています。context.md を編集すると hooks が docs:check を回すので、上限を超えた編集はその場でエージェントに差し戻されます。人が守るルールから機械が守るルールに変えた、というのがこの日の変更でした。今の context.md は 30 行弱です。
テストの書き方が揃わなかった
その 3 日後、web パッケージで DOM を描画するテストを書こうとして jsdom を入れかけたのと、テスト名が機能 ID と紐づかず設計書のトレーサビリティ表が空になったのが、同じ日に起きました。1 行足しました。
- テスト名は it("F-xx: …")（機能 ID は docs/design/05。docs:gen がテストを機能に紐づける）。web は DOM を描画しない（jsdom 無し）。UI ロジックは packages/web/src/lib/ の純粋関数に出してテストする。
1 行に 3 つ詰まっていますが、同じ日の同じ作業で起きたので 1 行にしました。分けるべきだったかは今も迷っています。
E2E を npm test に混ぜようとした
これはつい最近の話です。Playwright の E2E は dev 環境への接続と AWS 認証が要るので、ルートの npm test に含めると手元で落ちます。エージェントが含めようとしたので、コマンド欄に 1 行足しました。
- E2E（画面の見た目、手元実行のみ）: AWS_PROFILE=... npm run e2e -w @app/e2e（dev への接続と AWS 認証が要る。npm test には含めない）
今の AGENTS.md
38 行です。上限の 60 行まではまだ余裕があります。見出しだけ載せます。
# AGENTS.md
## プロジェクト
## スタック
## セッションの始め方（全部読むな）
## 作業ルール
## コマンド（ルートで実行）
## 触らない場所
「プロジェクト」の節には「採点しない。ただし must は断言する」というプロダクトの芯を 1 行入れています。実装の細部で迷った時にエージェントが立ち戻る先が要ると思ったからです。
まだ分かっていないこと
「指示が反映されない」がこの 2 週間出ていないのは事実ですが、原因が行数だったのか、ファイル数だったのか、archive を読ませなくしたことだったのかは分かっていません。全部同時に変えたからです。
ADR には「モデル更新時に AGENTS.md の各行が今も必要か点検する」と書きました。モデルが賢くなれば要らなくなる行があるはずですが、まだ一度も削っていません。上限があるので、いずれ足したい行が出た時に「どれを消すか」を考えることになります。それがこの仕組みの狙いなので、その時にまた書きます。
ルールファイルを減らせたのは、「archive を編集しない」「Accepted 済みの ADR を書き換えない」のような禁止事項を hooks に移したからです。ただ、その hooks を Edit と Write にだけ張っていたら、sed とヒアドキュメント経由の編集を見ていなかった、という話が次の記事です。