tech-spec

技術仕様

技術仕様とは、型付きのコールスタックアーキテクチャの引き継ぎ資料です。コード形式の契約と実行フローを記述します。正確さが重要な箇所では、文章より TypeScript 風の擬似コードを優先してください。

このスキルは設計のみを対象とします。実装しないでください。ユーザーがファイルを求めた場合にのみファイルを保存し、それ以外の場合は仕様をインラインで返してください。

分岐の選択

1. 会話、ドキュメント、またはコードベースに変更を記述するのに十分な背景情報がすでに含まれている場合は、パス A：コンテキストを仕様に変換を使用します。
2. ユーザーが新しい仕様を求めているものの、問題、制約、設計方針、影響を受けるコード、または受け入れ基準に関する情報が不足している場合は、パス B：まず質問するを使用します。

コードベースを調査すれば答えられる質問の場合は、質問する代わりにコードベースを調査してください。

完了基準：実際に利用できるコンテキストに基づいて分岐を選択し、不足しているアーキテクチャ上の決定を創作しないこと。

パス A：コンテキストを仕様に変換

1. 標準とローカルコンテキストを確認する

既存のコードとドキュメントを調べ、ローカルの用語、モジュール構成、ドメイン概念、エラー、アダプター、可観測性、ランタイムのパターン、テストのスタイルを確認します。

完了基準：仕様でプロジェクト固有の用語を使い、既存の先例を確認する前にパターン、ライブラリ、アダプター、スキーマのスタイル、またはテスト戦略を持ち込まないこと。

2. 設計上の問題を抽出する

以下を把握します。

• 現状；
• 問題；
• ユーザー／呼び出し元；
• 目標；
• 対象外；
• 制約；
• 不変条件；
• 影響を受けるシステム；
• 想定されるエントリーポイント；
• 運用／ランタイムに関する懸念；
• リスク；
• 未解決の質問。

不明点は、もっともらしい設計で埋めるのではなく、未解決の質問として明記します。

完了基準：要件または制約として記述するすべての内容が、会話、コード、ドキュメント、または明示的な未解決の質問に裏付けられていること。

3. 設計の代替案を検討する

推奨する設計を選ぶ前に、実質的に異なる代替案を提示します。代替案は、名称だけでなく、インターフェースの形、境界の配置、責務の所在、コールスタック、ランタイムトポロジー、またはモジュール境界が異なるものにしてください。

各代替案について、以下を概略として示します。

• ドメイン型と状態モデル；
• 公開／モジュールインターフェースと API；
• 入力／出力型；
• 想定される失敗の型；
• 境界、責務の区切り、アダプター；
• エントリーポイントから副作用までのコールスタック；
• パース／投影の方針；
• 適用可能な場合は、認可、可観測性、キャンセル、冪等性、トランザクションのフロー；
• テスト境界の方針；
• トレードオフ。

代替案を以下の観点で比較します。

• 呼び出し元の負担；
• モジュールの階層の深さと活用度；
• 不変条件と変更の局所性；
• 境界の配置；
• 境界でのパースと投影；
• エラーとキャンセルのモデル；
• 実際の境界を通じたテスト可能性；
• 運用／ランタイムへの適合性；
• 実装の複雑さ。

完了基準：代替案を比較した後に推奨案を選択していること。

4. 推奨する型付き契約を仕様化する

推奨する設計について、新規、変更、または削除される以下の項目をすべて概説します。

• ドメイン値；
• ブランド型／精緻化型；
• 状態マシンのバリアント；
• 入力／出力型；
• リクエスト／レスポンスの形式；
• 関数シグネチャー；
• クラスまたはモジュールのインターフェース；
• 想定される失敗／カスタムエラー型；
• アダプターインターフェース；
• プロトコル DTO；
• 永続化 DTO／投影；
• ランタイム境界のコーデック；
• 公開 API。

境界、アダプター、実装、責務の境界、および各境界を越えるものに名前を付けます。各レイヤーが知ってよいことと、境界を越えて漏らしてはならないものを明記します。

完了基準：新規または変更されるすべての境界について、具体的な型／インターフェース／API の概要を示すか、新しい契約が不要な明確な理由を示していること。

5. コールスタックとデータフローを仕様化する

新規、変更、または削除される各動作について、エントリーポイントから副作用、レスポンスまでのコールスタックを示します。

型／データのフローを含めます。

raw input
  -> boundary DTO / unknown
  -> parser
  -> canonical domain/application input
  -> service/module interface
  -> adapter call
  -> typed result/error
  -> projection
  -> serialized output

既存の動作を変更する場合は、現状と提案後のフローを含めます。該当する場合は、失敗、再試行、キャンセル、トランザクション性、冪等性、可観測性、認可、ランタイムホップの各フローも含めます。

完了基準：影響を受ける各動作について、エンドツーエンドのコールスタックと型／データフローの追跡を示していること。

6. ファイルとモジュールを整理する

以下を列挙します。

• 追加するファイル／モジュール
• 変更するファイル／モジュール
• 削除するファイル／モジュール（あれば）
• テストファイル
• 設定／マイグレーション／ランタイム関連のファイル（あれば）

各ファイルについて、担当する契約、コードパス、境界、アダプター、ドメイン概念、またはテスト責務を明記します。

完了基準：すべての契約とコールスタックの各ステップが、ファイル／モジュール、または未解決の質問に対応していること。

7. RGR TDD テスト計画を作成する

同階層の TDD ワークフローとテスト標準に従います。垂直の Red-Green-Refactor スライスを計画し、動作テストを 1 つ失敗させ、最小限の実装を行い、これを繰り返します。「まずすべてのテストを書き、後からすべてのコードを書く」という水平的な計画にはしないでください。

実装に密結合したモックよりも、公開インターフェースと実際のシームを通じた動作を優先します。

以下を、その重要度に応じてカバーします。

• 正常系
• 失敗系
• パーサーによる拒否と受け入れられる形式
• ドメイン不変条件と状態遷移
• アダプターの契約
• 永続化／ランタイムのセマンティクス
• キャンセル／再試行／冪等性の経路
• 該当する場合は、可観測性と安全な要約
• 重大な影響を伴う動作に対するエンドツーエンドのフロー

完了基準：すべての公開動作、不変条件、重要な失敗経路、変更された境界、変更されたシームに、Red テストスライス、またはテストしない明示的な理由があること。

8. 仕様書を作成する

ユーザーがファイルパスを指定していない場合は、仕様書をインラインで返します。ファイルの指定がある場合は、そこに保存します。

実装は行わず、デフォルトでは実装を促す質問もしないでください。

完了基準：出力が以下の概要に従い、別のエンジニアが実装に着手できること。

パス B：まず質問する

1. 仕様書全体をまだ書かないでください。
   • 実装可能な技術仕様書を作るには、コンテキストが不足していると伝えます。
   • 完了基準：エージェントが要件、API、ファイル、コールスタックを作り上げていないこと。
2. 質問を重ねるインタビューを始めます。
   • 一度に 1 つ質問し、各質問に推奨回答を添えます。
   • コードベースを調べれば回答できる質問は、質問せずにコードベースを調査します。
   • 完了基準：パス A に必要な、問題、ユーザー／呼び出し元、制約、影響を受けるシステム、望ましい動作、境界、想定 API、不変条件、リスク、受け入れテストを網羅するだけのコンテキストが得られていること。
3. 仕様書にまとめます。
   • 質問を重ねて十分なコンテキストが得られたら、パス A を実行します。
   • 完了基準：最終成果物がインタビューのメモではなく、型定義付きのコールスタックを含むアーキテクチャ引き継ぎ資料であること。

必須の仕様書概要

要件やコールスタックの契約を損なわずに簡潔にできるほどタスクが小さい場合を除き、以下の形式を使います。

# <Title>

## Summary

## Context / Current State

## Goals

## Non-Goals

## Invariants

## Design Constraints

## Alternatives Considered

### Option 1: <name>

### Option 2: <name>

### Option 3: <name>

## Recommendation

## Proposed Design

## Domain Model and Types

## Types, Interfaces, and APIs

## Seams, Boundaries, Adapters, and Implementations

## Call Stacks and Data Flow

### Current / Old Flow

### Proposed / New Flow

### Failure Flow

### Retry / Cancellation / Idempotency Flow

### Observability Flow

## Files to Add / Change / Delete

## RGR TDD Test Plan

## Risks and Open Questions

本当に該当しないセクションは省略できます。ただし、定義が難しいという理由で、型付き契約、シーム、コールスタック、テストを省略しないでください。

執筆ルール

• コードを先に書きます。TypeScript の疑似コードで、契約、API、データフローを定義します。
• その理由は文章で説明し、変更内容は型とコールスタックで定義します。
• 型、インターフェース、API、入出力、シーム、境界、アダプター、ドメインモジュール、サービスモジュール、外部アダプター、コールスタックに焦点を当てます。
• 文字列、ブール値、nullable な値を詰め込んだオブジェクト、形状が曖昧なオブジェクトより、精密なドメイン値を優先します。
• シームは実際の境界として保ちます。アダプターは、フレームワーク、永続化、ネットワーク、時刻、乱数、テレメトリー、ランタイム、プラットフォームの境界を変換します。
• 抽象化をむやみに推測して作らないでください。不変条件、局所性、活用範囲、テスト、実際の境界のいずれかによって、各シームの必要性が説明できるようにします。
• 信頼できる情報源は 1 つに保ちます。あるセクションから別のセクションを参照する場合を除き、同じルールを複数のセクションに重複して記載しないでください。
• 不明点は未解決の質問として残します。仕様書を完全に見せるために、プロダクト要件、ドメインルール、API、コールスタックを作り上げないでください。