documenting-contracts

コントラクトの文書化

前提条件: technical-writing スキル (厳格なルール、真実に関するルール、スタイル)。

概要

コントラクト文書は、コードを見ることができず、これからそれに依存しようとしている他人によって読まれます。中心原則: ワイヤーを網羅的に文書化し、各詳細をそれぞれのレベルに置く。呼び出し元の言語はワイヤー形式とドメイン用語であり、実装の型では決してない。 コントラクトの表面はリファレンス種別であるため、リファレンスの中核ルールが適用されます: すべてのエンドポイント、すべてのフィールド、すべてのエラーです。

いつ呼び出すか、呼び出さないか

機械が呼び出す、あるいは解析するものを文書化するときに呼び出します: REST および RPC エンドポイント、メッセージキューとトピック、Webhook、CLI コマンド、ファイル形式。レガシーキャンペーン (documenting-legacy-codebases) の api-reference.md は、このスキルの成果物です。内部コードインターフェース (コード自体が文書化します) や、設定リファレンス (リファレンスの中核ルールに基づき config-reference.md に属します) には呼び出さないでください。コントラクトが適切に設計されているかの判断は範囲外です: このスキルは、存在するコントラクトを文書化します。

単一の置き場所 vs 生成される仕様

OpenAPI または AsyncAPI の仕様が存在する場合、あるいはコードがそれを生成する場合、その仕様がフィールド表を所有します。Markdown は、仕様が言えないこと (セマンティクス、副作用、順序、省略 vs null) のみを文書化し、仕様にリンクします。生成された表の隣にフィールド表を手作業で保守してはなりません。2 つ目の置き場所は乖離します。以下のカタログは、機械可読な仕様が存在しない場合のためのものです。仕様を書くことは、この文書の役割ではありません。

4 つの詳細レベル

各レベルには独自の置き場所があり、書き手は誤ったレベルで見つけた詳細を、それを所有するレベルへ移します:

レベル	呼び出し元の問い	置き場所
索引	ここに何が存在するか	エンドポイント、メッセージ、コマンドの表
セマンティクス	それを呼び出すと何が起きるか	エンドポイントごと、メッセージごと、コマンドごとの散文: 副作用、発行されるイベント、冪等性、再配信、終了時の挙動、癖
形状	ワイヤー上を何が通過するか	DTO カタログ: DTO ごとに 1 つのフィールド表
例	それがどのように見えるか	DTO ごとに最大 1 つの例示的な例

レベルをまたぐ繰り返しが、追い求めるべき欠陥です: エンドポイントのセクションが自身の DTO のフィールドを再掲すること、例が表に欠けているフィールドを紛れ込ませること。

DTO カタログ

DTO は一度だけ定義し、どこからでも参照します:

• 言語の型ではなく、ワイヤーの型。 string (date, ISO 8601)、number (64-bit integer)、string (decimal): この列はワイヤー上を何が通過するかを示し、読者が実装の型を代理として必要としない程度に完全です。消費者のネイティブな数値型の範囲や精度を超える 64 ビット整数はワイヤー情報です。それを生成した型名はそうではありません。
• DTO ごとに 1 つの Source 行、所有するクラスまたはスキーマファイルを明示します。リファレンス種別は、設定リファレンスがバインディングの証拠を持つように、この証拠のアンカーを認めます。
• Required は三状態: yes、no、または条件を明記した if <condition>。
• 省略 vs null は、それが重要なところでは必ず明記し、replace 形式の書き込みで使われる DTO では常に明記します。そこでは、省略されたフィールドは結果に存在しません。代わりにサーバーが省略時に値を仮定する場合は、その値を Default 列に記載します。
• Enum は独自の表を持ち、値と意味を記載します。ネストされたオブジェクトは自身のカタログ項目にリンクし、インラインの 2 つ目のコピーは決して作りません。
• 制約はドメイン用語で: 「過去の日付」、「1..100 文字」、「既存の予算ポリシーを参照する必要がある」など、コードが強制する検証から読み取ります。

テンプレート

# API reference: <service>

## Conventions
[Once, never per endpoint: base path, auth, content type, the error
envelope, global (de)serialization behavior, idempotency defaults.]

## Endpoints
| Method | Path | Purpose | Request | Response | Errors |
|---|---|---|---|---|---|
| POST | `/thing` | Create a thing | [ThingRequest](#thingrequest) | 200 [Thing](#thing) | 422, 404 |

### POST /thing
[Semantics only: side effects, events published, idempotency, quirks.
No field lists; the index and catalog are not repeated.]

## Messages
| Direction | Destination | Payload | Reply | On error |
|---|---|---|---|---|
| in | `thing.create` | [ThingRequest](#thingrequest) | `thing.created` | `thing.create.error` |

### thing.create
[Semantics only: redelivery, ordering, events published, quirks;
what differs from the sibling transport is called out here.]

## Commands
| Command | Purpose | Arguments | Output |
|---|---|---|---|

### <command>
[Semantics only: side effects, idempotency, exit behavior, quirks.]

## DTOs
### ThingRequest
Source: `api/ThingRequest`

| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|

[Omitted versus null, where it matters. At most one illustrative example.]

### Thing
[Response shapes are catalog entries like any other.]

## Errors
| Status | When | Body |
|---|---|---|

ルール

• クラスではなくシリアライザーに対して検証します。 ワイヤー上で実際に何が送受信されるかは、設定されたシリアライザーが出力・受け入れする内容そのものです。グローバルなトリマー、null を省略するマッパー、独自の日付フォーマットは、どの DTO にも触れることなくコントラクトを変えてしまいます。フィールドの行を1つ書く前に、シリアライゼーションの設定を読んでください。
• 非対称性はセマンティクスです。 あるトランスポートではイベントを発行し、もう一方では何も発行しないミューテーションや、兄弟のエンドポイントが実行するステップを飛ばすエンドポイントは、セマンティクスのレベルで文書化します。
• 例はあくまで例示であり、規範ではありません。 DTO ごとに最大1つ、その旨を明記し、テーブルにないフィールドを含めません。テーブルがコントラクトです。
• エラーは一度だけカタログ化します。エンベロープとステータステーブルとして記載し、各エンドポイントはどのエントリが適用されるかだけを列挙します。コマンドの失敗も同じ方法で、終了コード別にカタログ化します。
• 網羅性は検証可能です。 エンドポイント数と DTO 数は、ほかのものと同じく分母です（中核となる真実のルール）。レガシーキャンペーンでは、それらを背後にあるコマンドと日付とともにカバレッジ台帳に記録します。