docs-to-types

Docs to Types

明確化された文章を型付きアーキテクチャに変換するための、事前アーキテクチャ設計スキルです。チームが長期的に維持すべきドメインまたはアーキテクチャ上の事実を把握しているなら、型システムとモジュールグラフにも反映すべきです。

一般的な質問、リファクタリングレビュー、最初の TDD スライスには使用しません。CONTEXT.md、ADR、grill のメモは資料であり、最終的なハーネスではありません。

最優先の指針

ビジネス動作を実装しないでください。 承認済みのコンテキストを、意図するアーキテクチャ全体を型付けして表現する形にまとめます。

• 正規のドメイン型、スキーマ、ブランド型、不変条件
• 無効な状態を排除する判別可能なユニオン／状態モデル
• システム境界から入る値のスマートコンストラクター／パーサー
• プロジェクトの規約に従ったサービス／インターフェースの境界
• 型付きの結果／エラーのファミリーとエラー変換の境界
• 本番／テスト用アダプターの受け口
• プロジェクトの規約に従った構成／レイヤー／モジュールのトポロジー
• 本番環境とテストの呼び出しスタック
• 実用的な範囲での依存方向チェック

ビジネスワークフロー、実際の永続化／ネットワーク処理、プロダクトの動作、後付けのリファクタリング、汎用的な変更／結果のフレームワーク、完成品を装う偽の本番ロジックは作成しないでください。

先に読むもの

1. AGENTS.md とプロジェクトのコーディング規則
2. CONTEXT-MAP.md（存在する場合）
3. 関連する CONTEXT.md ファイル
4. 関連する docs/adr/*
5. 承認済みの grill-with-docs のメモ／仕様
6. 対象領域の既存ソースコード

コンテキストドキュメント／ADR がなく、承認済みの grill-with-docs の出力もない場合は、作業を中止して grill-with-docs を推奨してください。

ワークフロー

1. アーキテクチャ上の事実を抽出する

編集する前に、事実の表を作成します。

| Fact                                        | Source     | Code artifact         | Confidence |
| ------------------------------------------- | ---------- | --------------------- | ---------- |
| Link Catalog is the application-facing seam | CONTEXT.md | `LinkCatalog` service | high       |

ドメイン名、所有権の境界、依存方向、呼び出しスタック、アダプターの選択、ランタイムの制約、型付きエラー、アダプターの内側にとどめる必要があるインフラストラクチャを含めてください。

2. 曖昧さの確認

ドキュメント、コード、またはユーザーの計画が矛盾する場合は、具体的な質問を一つして、回答を待ってください。

文章で記述された事実を、型、境界、アダプター、状態、エラー、依存ルールのいずれかとして明確に表現できない場合は、ドメイン用語がまだ曖昧だと判断してください。

例：CONTEXT.md には「Operator」とありますが、コードでは「User」と「Actor」が使われています。どれを正規の用語としますか？

3. 型付き構造を提案する

ユーザーが直接の実装を求めていない限り、編集する前に以下を列挙します。

• 作成／更新するファイル
• ドメイン型／スキーマ／ブランド型／不変条件／スマートコンストラクター
• 状態モデル／判別可能なユニオン
• サービス／インターフェースの境界
• 型付きの結果／エラーのファミリー
• 本番環境とテストの呼び出しスタック
• アダプターの受け口／スタブ
• アーキテクチャチェック
• 意図的に除外するビジネスロジック

承認を求めてください。

4. 型付き構造のみをコード化する

承認されたら、意図する型付き構造全体をコンパイル可能なアーキテクチャコードとして記述します。

ルール：

• プロジェクトのドメイン名をそのまま使用してください。
• ディープモジュールを優先してください。インターフェースは小さく、複雑さは境界の内側に隠します。
• サービス、インターフェース、DI、構成、レイヤー、ファクトリー、プロバイダー、レジストリーについて、プロジェクトの規約に従ってください。
• 不在、検証、バリアント、状態、想定される失敗は、プロジェクト標準の型付きパターンでモデル化してください。
• HTTP／UI／CLI のトランスポート詳細は境界にとどめてください。
• ストレージ、SQL、キュー、RPC クライアント、SDK、サードパーティ API はアダプターの内側にとどめてください。
• 依存方向を機械的に検査できる場合は、アーキテクチャテスト／lint／インポート規則を追加してください。

許可されるコードの深さと例については、REFERENCE.md を参照してください。

5. 検証して報告する

範囲を絞ったチェックを実行します。型チェック、lint／静的チェック、追加した場合はアーキテクチャテストを行ってください。最終回答には、コード化した事実、変更したファイル、本番環境／テストの呼び出しスタック、アダプターの受け口、実行したチェック、未実装のまま残したビジネスロジックを記載してください。