update-agentsmd Skill

目的

コンテキストゼロの別AIが読むだけで作業を継続できる AGENTS.md を作成・更新します。

AGENTS.md には、コードや設計ドキュメントから復元できない暗黙知（非自明な Why・落とし穴・型やコメントで表現しきれない制約）を中心に置きます。アーキテクチャ・仕様・要件といった静的な設計情報は設計ドキュメントに書きます。対象プロジェクトに requirements.md / specification.md / architecture.md / design.md があれば（無ければ作成を検討すべきなら）内容はそちらに書き、AGENTS.md 側は Key References から1行のポインタで参照するだけに留めます。

情報は次の表で振り分けます。期限切れになるもの（TODO・未解決の問い・進行中の状態）は AGENTS.md に書きません。

Issue はこのスキルの成果物ではありません。Issue を立てられない状況（repo 未作成・オフライン）では、立てられるようになるまで会話の中で保留し、その旨をユーザーに伝えます。ファイルには逃がしません。

暗黙知の保存先を Claude の自動メモリ機能に委ねない。 理由は2つ。(1) 自動メモリは Claude 専用で、Codex・Gemini CLI など他のハーネスに切り替えると情報が失われる。AGENTS.md はハーネスを問わず読まれる前提のファイル。(2) 自動保存はユーザーの意図しない情報が蓄積されやすく、想定外の挙動に傾く傾向がある。暗黙知は本スキルの手順に従い、人間のレビューを経て AGENTS.md に書く。

グローバル指示と矛盾する場合は、グローバル指示を優先します。

判断基準

1行ごとに「この行を消したらエージェントが間違えるか」で判断します。No なら消します。

長さを抑える理由はコストです。ファイルの長さや指示の位置は指示の守られ方に影響しない一方（arXiv:2605.10039）、毎回読み込まれるぶん推論コストが増えます（context file で平均20%以上。arXiv:2602.11988）。目安は Anthropic 公式の200行未満です。Codex は合計32 KiB で読み込みを打ち切ります（いずれも2026年11月時点の公式ドキュメント）。

書かない

• README・コード・設定ファイル・git log を見れば分かること（採用ライブラリ名、ディレクトリの中身、過去の修正履歴）
• リポジトリやプロダクトの概要・紹介文。効果が確認されていない（arXiv:2602.11988）
• アーキテクチャ・仕様・要件など静的な設計情報（書くのは設計ドキュメントで、AGENTS.md は参照のみ）
• 一般論（「テストを書きましょう」「型を付けましょう」）や、言語・フレームワークの標準どおりの慣習
• グローバル指示や他のスキルに既にある指示の再掲
• 複数ステップの手順（how-to）。スキルに切り出す
• テスト結果など、実行すれば分かる状態
• 必ず止めたい操作の禁止そのもの。指示ファイルは強制力のある設定ではなく文脈として扱われるので、hooks / permissions で止める。AGENTS.md には「なぜ止めているか」だけを書く

書く

• 非自明な Why（なぜこの設計／制約を選んだか）
• 型やコメントで表現しきれていない制約
• 言語やフレームワークの標準と違う独自の慣習。context file が最も役立つのはここ（arXiv:2602.11988）
• プロダクトの非交渉事項。AIが提案してはいけないこと
• 踏みやすい落とし穴。説明を長文にせず、再現するテストや事故ったコミットのパスを指す
• 実行コマンド（対応するテストスキルがあればそれを使う旨）
• 運用上の注意。「この操作は遅い・高い、代わりにこれを使う」の形で書く。行動の変化が実測できたのはこの種類だけ（arXiv:2607.27250）
• 配布・運用上の外部制約（対象地域、年齢制限、外部サービスの規約など）
• 既存の設計ドキュメントへの参照。古い場合は「コードを正とする」と明記する

並べ方

• 重要なルールほど先頭に置く
• 事故の記録（日付・経緯の一覧）は置かない。過去の判断は今も有効とは限らず、残すと古い判断に従わせてしまう。導いた再発防止策だけを、関係する節に現在形の規則として書く
• 環境やツールのバージョンに依存する事実には、確認したバージョンを添える（例: 「Codex 0.145.0 で計測」）。古くなったと判断できるようにするため

手順

確認なしに AGENTS.md を上書きしない。 小さな修正でも、書き込む前に手順5の分類表と差分を示して承認を待ちます。LLM が書いた context file は効果がないという結果があり（arXiv:2602.11988）、人間のレビューが品質の担保になるためです。

暗黙知はコードベースではなく会話履歴の中にあります。**ユーザーに直接質問しない。**聞いても、何が暗黙知にあたるかを本人が自覚していないことが多く、うまく答えが返ってこないため、代わりに手順3でこのセッションの会話履歴を遡って拾います。コードを読んで埋められる部分だけで完走しないこと。

1. 既存の AGENTS.md を読む。無ければ最小構成で新規作成する（Commands と落とし穴だけ。最初から埋め尽くさない）。CLAUDE.md は作らない（Claude Code は AGENTS.md を直接読む。CLAUDE.md があると AGENTS.md が読まれなくなる）
2. 設計ドキュメント（requirements.md / specification.md / architecture.md / design.md）の有無を確認する。あれば静的な設計情報はそちらに任せ、AGENTS.md 側は Key References から1行参照するだけに留める
3. 会話履歴を遡り、次のシグナルを拾う。
   • ユーザーの訂正・却下（採用しなかった案とその却下理由）
   • 複数案から選んだ理由・トレードオフの判断
   • 調査やデバッグで判明した非自明な事実（落とし穴・事故の元になりうるもの）
   • ユーザーが明示した制約・非交渉事項
4. **拾えた内容だけを反映する。**会話に出てこない情報は推測で埋めない。埋まらない箇所は無理に埋めず空欄のままにする。仕様レベルの未決も着手中のものも Issue に回す
5. 差分更新のみ（全文書き換えしない）。Why 系は事実が変わらない限り残す。書き込む前に、行ごとの分類表（keep / remove / move-to-skill と理由）と差分をユーザーに示し、承認を待つ
6. 育てるのは失敗したときだけ。実際に事故ったら、そこから導いた規則を関係する節に足す。経緯は commit メッセージに書く
7. 更新後、剪定パスを1回かける。今は成り立たない規則、存在しないファイル・コマンドへの参照も消す（Claude Code なら /doctor prompt-audit で洗い出せる）

参考資料

• セクション構成に迷ったら テンプレート