agentic-docs

エージェント向けドキュメント

説明対象のコードと一緒に存在するドキュメントを書きます。平易な言葉を使い、専門用語は避けます。「何を」ではなく「なぜ」を説明します。

基本方針

コードと一緒に置くのが最善です。 別ファイルに置いたドキュメントは、コードと内容がずれていきます。コードのそばにあるコメントは、コードと一緒に更新されるため、正確さを保てます。

次の3つの読者を想定して書きます。

1. 半年後の自分
2. なじみのないコードを読むチームメイト
3. 一度に1つのファイルを見る AI アシスタント（Claude、Copilot）

「なぜ」を問うテスト： コメントを書く前に、次のように考えてください。「このコードが存在する理由、またはこのように動作する理由を説明しているか？」コードが「何を」するかを言い換えるだけなら、コメントは不要です。

ドキュメントのレベル

ファイルヘッダー

すべてのファイルの冒頭に、その目的とシステム全体での役割を簡潔に説明します。

// UserAuthContext.tsx
//
// Manages authentication state across the app. Wraps the root component
// to provide login status, user info, and auth methods to any child.
//
// Why a context instead of Redux: Auth state is read-heavy and rarely
// changes mid-session. Context avoids the ceremony of actions/reducers
// for something this simple.

// NetworkRetryPolicy.swift
//
// Handles automatic retry logic for failed network requests.
// Uses exponential backoff with jitter to avoid thundering herd
// when the server comes back online after an outage.
//
// Used by: APIClient, BackgroundSyncManager
// See also: NetworkError.swift for error classification

含める内容：

• このファイル／モジュールが担う役割
• 存在する理由（名前から明らかでない場合）
• コードベースの他の部分との関係
• 重要だが自明ではない設計上の判断

関数とメソッドのドキュメント

実装ではなく、契約を記述します。

/**
 * Calculates shipping cost based on weight and destination.
 *
 * Uses tiered pricing: under 1lb ships flat rate, 1-5lb uses
 * regional rates, over 5lb triggers freight calculation.
 *
 * Returns $0 for destinations we don't ship to rather than
 * throwing. Caller should check `canShipTo()` first if they
 * need to distinguish "free shipping" from "can't ship."
 */
function calculateShipping(weightLbs: number, zipCode: string): number

def sync_user_preferences(user_id: str, prefs: dict) -> SyncResult:
    """
    Pushes local preference changes to the server and pulls remote changes.

    Conflict resolution: server wins for security settings, local wins
    for UI preferences. See PREFERENCES.md for the full conflict matrix.

    Called automatically on app foreground. Can also be triggered manually
    from Settings > Sync Now.
    """

含める内容：

• 関数が達成すること（方法ではなく）
• 自明ではないパラメーターの制約やエッジケース
• 戻り値の意味（特に、解釈が曖昧な場合）
• 副作用（ネットワーク呼び出し、ファイルへの書き込み、状態の変更）

省略してよいもの： 単純なゲッター、明白な一行の処理、名前から役割が分かるプライベートヘルパー。

インラインコメント

必要最小限にします。必要な場合は、理由を説明します。

// Debounce search by 300ms to avoid hammering the API on every keystroke.
// 300ms feels responsive while cutting API calls by ~80% in user testing.
const debouncedSearch = useMemo(
  () => debounce(executeSearch, 300),
  [executeSearch]
);

// Force unwrap is safe here: viewDidLoad guarantees the storyboard
// connected this outlet. If it's nil, we want to crash immediately
// rather than fail silently later.
let tableView = tableView!

# Process oldest items first. Newer items are more likely to be
# modified again, so processing them last reduces wasted work.
queue.sort(key=lambda x: x.created_at)

アーキテクチャに関するコメント

重要な設計判断を反映したコードには、トレードオフを説明します。

// ARCHITECTURE NOTE: Event Sourcing for Cart
//
// Cart state is rebuilt from events (add, remove, update quantity)
// rather than stored directly. This lets us:
// - Show complete cart history to users
// - Replay events for debugging
// - Retroactively apply promotions to past actions
//
// Tradeoff: Reading current cart state requires replaying all events.
// We cache the computed state in Redis with 5min TTL to keep reads fast.
// Cache invalidation happens in CartEventHandler.

// WHY COORDINATOR PATTERN
//
// Navigation logic lives here instead of in view controllers because:
// 1. VCs don't need to know about each other (loose coupling)
// 2. Deep linking becomes straightforward; just call coordinator methods
// 3. Navigation is testable without instantiating UI
//
// The tradeoff is more files and indirection. Worth it for apps with
// 10+ screens; overkill for simple apps.

TODO コメント

実行可能で、追跡可能な内容にします。

// TODO(pete): Extract to shared util once mobile team needs this too.
// Blocked on: Mobile API parity (see MOBILE-123)

// HACK: Workaround for Safari flexbox bug. Remove after dropping Safari 14.
// Bug report: https://bugs.webkit.org/show_bug.cgi?id=XXXXX

// FIXME: Race condition when user rapidly toggles. Need to cancel
// in-flight requests. Reproduced in issue #892.

言語ごとのパターン

詳しい例については、references/language-examples.md を参照してください。

• TypeScript/JavaScript（JSDoc、TSDoc のパターン）
• Swift（ドキュメントコメント、MARK プラグマ）
• Python（docstring、型ヒントのドキュメント）
• React/Next.js（コンポーネントのドキュメントパターン）

書き方

平易な言葉を使います。 背景を知らない優秀な同僚に説明するように書きます。

能動態を使います。 「この関数は検証します」と書き、「検証が実行されます」とは書きません。

具体的に書きます。 「1秒の間隔を空けて3回再試行します」と書き、「再試行に対応します」とは書きません。

自明なことは省きます。 コードが user.isAdmin なら、「ユーザーが管理者かどうかを確認する」とコメントする必要はありません。

期限があるものには日付を付けます。 回避策、特定のバージョンに依存するコード、一時的な解決策には、いつ削除できるかを記します。

値を重複させず、定数を参照します。 定数によって動作が制御される場合は、コメントに値を繰り返し書かず、定数名を参照します。

// Bad: duplicates the value, will drift when constant changes
/// Returns true if stale (not updated in last 5 minutes)
pub fn is_stale(&self) -> bool { ... }

// Good: references the constant
/// Returns true if stale (not updated within [`STALE_THRESHOLD_SECS`])
pub fn is_stale(&self) -> bool { ... }

単位の換算を添えるのは問題ありません（1048576 // 1MB）。重複ではなく、分かりやすさにつながるためです。