# Writing Agent Context Docs > AIエージェントがコードベースを理解・探索するためのドキュメント（CLAUDE.md、アーキテクチャドキュメント等）の作成・更新時に適用する。 Use when this capability is needed. - Skill: `tomevault-io/writing-agent-context-docs` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/writing-agent-context-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/writing-agent-context-docs/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/writing-agent-context-docs --- # エージェント向けコンテキストドキュメントの作成ガイド ## 原則1: 書くべきものと書くべきでないものを区別する ドキュメントの目的は「コードを読まなくても全体像と探索の起点を把握できる」こと。 ### 書くべき内容 - アーキテクチャの全体像（レイヤー構成、責務、依存方向） - 処理フロー（リクエストライフサイクル、主要な非同期境界） - アーキテクチャレベルの構成要素と各要素の役割（1行説明） - 設計判断の意図（Why、トレードオフ） ### 書くべきでない内容 - 型シグネチャ、フィールド一覧、定数値の列挙 - コードレベルの構成要素の網羅的列挙（エラー型・DTO一覧等） - 関数の振る舞いや引数の説明（→ コードコメント / テストへ） ### 判断基準 「コードを変更したとき、このドキュメントも更新しなければ嘘になるか？」 - **Yes** → コードコメント・テストに書く - **No / 嘘になっても探索に有用な"上位の真実"** → ドキュメントに書く ### 例外: 探索の起点になる最小の具体値 以下は最小限に限り記載してよい（目安: 各カテゴリ3個以内）。 - 最初に実行すべき開発・検証コマンド - エントリーポイントとなるファイル - ログやトレースを確認する最短経路 ## 原則2: 常時ロードされるコンテキストを最小に保つ `CLAUDE.md` は会話の度に常時ロードされる。トークンコストに直結するため、本当に毎回必要な情報のみを記載する。 - 上位階層に詳細を書かない — 下位ドキュメントまたはコード自体に委譲する - 情報は一箇所に記述し、重複させない ## 原則3: 配置先を内容の性質とロードタイミングで決める コンテキストの配置先は3層に分けて管理する。 ``` CLAUDE.md — 常時ロード 性質: オリエンテーション（概要・探索の起点） 例: プロジェクト概要、技術スタック、開発コマンド、ディレクトリ構成、下位ドキュメントへのリンク .claude/rules/.md — 条件付き自動ロード or 常時ロード 性質: 規範（「〜せよ / 〜するな」） 例: テスト規約 (paths: *.test.ts)、命名規約 (paths: *.ts)、コミットメッセージ規約 (paths なし = 常時) docs/.md — オンデマンド参照 性質: 知識（「〜はこうなっている」） 例: アーキテクチャ詳細、処理フロー、設計判断の背景、環境変数一覧 ``` ### 配置の判断基準 - **毎回必要か？** → Yes: `CLAUDE.md` / No: 下位へ - **「〜せよ」か「〜である」か？** → 規範: `.claude/rules/` / 知識: `docs/` - **特定のファイルパターンにスコープできるか？** → Yes: `paths:` 付き rules / No: `paths:` なし rules または `CLAUDE.md` **注意:** アーキテクチャ情報は `src/` 全体に適用されるためパスベースの絞り込みの利点が薄い。概要は `CLAUDE.md` に、詳細は `docs/` に置く。 ## 原則4: rules の粒度をロードコストで使い分ける - `paths:` 付き → 必要な分量を書いてよい。命令と理由を明確に - `paths: なし`（常時ロード）→ 命令 + Why を1行で書く。詳細は `docs/` に委譲する - `paths: なし` の rules を増やすのは最後の手段 ## 原則5: 参照構造を明確にする - `CLAUDE.md` は下位ドキュメントへのリンクを持つ - `docs/` は 1ドキュメント = 1テーマ - docs 間の相互参照は可、循環・重複は避ける --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/844196) — claim your Tome and manage your conversions.