ドキュメンテーション パターン

アーキテクチャ決定記録(ADR)

目的

ADRは、重要なアーキテクチャの決定とその背景、根拠、および影響を記録します。「このように設計したのはなぜか？」という問いに答えるものです。

ロケーションと命名

• パス: docs/decisions/NNNN-short-title.md
• 番号付け: シーケンシャル、4桁ゼロパディング(0001, 0002, ...)
• タイトル: 決定を説明する短い名詞句
• 例:
  • docs/decisions/0001-use-langgraph-for-agent-orchestration.md
  • docs/decisions/0002-adopt-dual-model-strategy.md
  • docs/decisions/0003-github-discussions-for-deliberation.md

ステータスライフサイクル

Proposed → Accepted → [Deprecated | Superseded by NNNN]

• Proposed: 検討中、未決定
• Accepted: 決定済み、アクティブ状態
• Deprecated: 関連性なし(技術削除、機能削除)
• Superseded: より新しい決定に置き換わった(新しいADRへのリンク)

不変性ルール

承認されたADRは編集しません。決定が変更される場合:

1. 更新された決定で新しいADRを作成
2. 旧ADRのステータスを「Superseded by NNNN」に設定
3. 新しいADRのコンテキストセクションで旧ADRを参照

ADR作成のタイミング

状況	ADR作成?
新しいライブラリ/フレームワークの採用	はい
アーキテクチャパターンの変更	はい
審議の結果(/deliberate-summarize)	はい — Discussion をリンク
バグ修正	いいえ
マイナーリファクタリング	いいえ
新機能(標準パターン)	いいえ
新機能(新しいアプローチ)	はい
既存ADRの変更	はい — 置き換え

MADRテンプレート

# NNNN. 簡潔な決定タイトル

## ステータス

Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-short-title.md)

## コンテキストと問題ステートメント

この決定を促す問題は何か?

## 決定ドライバー

- [ドライバー 1]
- [ドライバー 2]

## 検討したオプション

1. オプション A
2. オプション B
3. オプション C

## 決定結果

選択: **オプション B**、理由は [正当性]。

### 影響

- 利点: [ポジティブ]
- 欠点: [ネガティブ]
- 中立: [トレードオフ]

## リンク

- Discussion: [#N](url) — 審議から派生
- PR: [#N](url) — 実装PR
- 関連: [NNNN](path) — 関連ADR

API ドキュメンテーション標準

Google スタイルドキュメンテーション文字列

すべてのパブリック関数、メソッド、クラスにはドキュメンテーション文字列が必須です:

def function_name(param1: Type, param2: Type = default) -> ReturnType:
    """1行の要約(命令法)。

    必要に応じて拡張説明を記載。非自明な動作、アルゴリズム、
    または副作用を説明します。

    Args:
        param1: param1の説明。
        param2: param2の説明。デフォルトはX。

    Returns:
        戻り値の説明。

    Raises:
        SpecificError: この特定の条件が発生した場合。

    Example:
        >>> result = function_name("input", param2=42)
        >>> assert result.status == "ok"
    """

ドキュメンテーション階層

1. モジュールドキュメンテーション文字列: このモジュールが何をするかを説明する1文
2. クラスドキュメンテーション文字列: 目的、主要属性、使用例
3. メソッドドキュメンテーション文字列: 何をするか、引数、戻り値、例外
4. インラインコメント: WHYのみ、WHATは不可

型ヒントがドキュメンテーション

型ヒントはドキュメンテーションです。以下を推奨:

def process(items: list[Document], config: ProcessConfig) -> list[Chunk]:

ドキュメンテーション文字列を読まないと理解できない曖昧な型より。

テクニカルライティング音声

原則

1. 正確性: 正確な用語を使用。「いくつかのアイテムを返す」ではなく「リストを返す」
2. 簡潔性: 無駄を削除。「この関数はXを処理します」ではなく「この関数はXの処理を担当します」
3. 能動態: 「エージェントがディスカッションを読む」ではなく「ディスカッションはエージェントによって読まれる」
4. 現在時制: 「このモジュールが処理する」ではなく「このモジュールは処理します」
5. 指示には命令法: 「コマンドを実行する」ではなく「コマンドを実行すべき」

対象者の認識

対象者	スタイル
API ユーザー	形式的、完全、例を優先
チーム開発者	簡潔、プロジェクトコンテキストを想定
将来の自分自身	WHYを説明、ディスカッション/イシューへのリンク
新しい貢献者	明示的な前提条件、ステップバイステップ

コードコメント標準

コメント対象

• 複雑なアルゴリズム: アプローチと選択理由を説明
• 非自明な制約: ビジネスルール、パフォーマンストレードオフ、API制限
• ワークアラウンド: ワークアラウンドを必要とするイシュー/バグへのリンク
• 決定根拠: パターンが非自明な場合、ADRまたはディスカッションへのリンク

コメント非対象

• 自明なコード: counter += 1の上に# カウンターをインクリメント
• コードが何をするか: コード自体がそれを示している
• コメントアウトされたコード: バージョン管理を使用
• コンテキストなしのTODO: # TODO: これを修正ではなく、イシューをリンク

リンクパターン

# LangChain イシュー #12345 のワークアラウンド
# 参照: https://github.com/langchain-ai/langchain/issues/12345
# ADR: docs/decisions/0005-custom-retry-logic.md

チェンジログとリリースノート

Conventional Commits → チェンジログ

Conventional形式に従うコミットはsemantic-releaseによって自動処理されます:

プレフィックス	チェンジログセクション	バージョン更新
feat:	機能	マイナー
fix:	バグ修正	パッチ
docs:	(通常は除外)	なし
refactor:	(通常は除外)	なし
BREAKING CHANGE:	破壊的変更	メジャー

優れたコミットメッセージの作成

feat: add multi-agent deliberation with heterogeneous models

Support architectural deliberation using Claude Opus 4.6, Gemini 3 Pro,
and GPT-5.2 in parallel rounds. Each agent independently investigates
the codebase and posts analysis to a GitHub Discussion.

Closes #42

• サブジェクト: 命令法、小文字、ピリオドなし、72文字以下
• 本文: WHYを説明、WHATは不可。差分が何が変わったかを示す
• フッター: イシュー、破壊的変更を参照