writing-agent-context-docs

name	writing-agent-context-docs
description	AIエージェントがコードベースを理解・探索するためのドキュメント（CLAUDE.md、アーキテクチャドキュメント等）の作成・更新時に適用する。 Use when this capability is needed.
metadata	{"author":844196}

エージェント向けコンテキストドキュメントの作成ガイド

原則1: 書くべきものと書くべきでないものを区別する

ドキュメントの目的は「コードを読まなくても全体像と探索の起点を把握できる」こと。

書くべき内容

• アーキテクチャの全体像（レイヤー構成、責務、依存方向）
• 処理フロー（リクエストライフサイクル、主要な非同期境界）
• アーキテクチャレベルの構成要素と各要素の役割（1行説明）
• 設計判断の意図（Why、トレードオフ）

書くべきでない内容

• 型シグネチャ、フィールド一覧、定数値の列挙
• コードレベルの構成要素の網羅的列挙（エラー型・DTO一覧等）
• 関数の振る舞いや引数の説明（→ コードコメント / テストへ）

判断基準

「コードを変更したとき、このドキュメントも更新しなければ嘘になるか？」

• Yes → コードコメント・テストに書く
• No / 嘘になっても探索に有用な"上位の真実" → ドキュメントに書く

例外: 探索の起点になる最小の具体値

以下は最小限に限り記載してよい（目安: 各カテゴリ3個以内）。

• 最初に実行すべき開発・検証コマンド
• エントリーポイントとなるファイル
• ログやトレースを確認する最短経路

原則2: 常時ロードされるコンテキストを最小に保つ

CLAUDE.md は会話の度に常時ロードされる。トークンコストに直結するため、本当に毎回必要な情報のみを記載する。

• 上位階層に詳細を書かない — 下位ドキュメントまたはコード自体に委譲する
• 情報は一箇所に記述し、重複させない

原則3: 配置先を内容の性質とロードタイミングで決める

コンテキストの配置先は3層に分けて管理する。

CLAUDE.md — 常時ロード
  性質: オリエンテーション（概要・探索の起点）
  例: プロジェクト概要、技術スタック、開発コマンド、ディレクトリ構成、下位ドキュメントへのリンク

.claude/rules/<topic>.md — 条件付き自動ロード or 常時ロード
  性質: 規範（「〜せよ / 〜するな」）
  例: テスト規約 (paths: *.test.ts)、命名規約 (paths: *.ts)、コミットメッセージ規約 (paths なし = 常時)

docs/<topic>.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 — claim your Tome and manage your conversions.