escrever-trd

TRD の作成

docs/trd.md に TRD（技術要件ドキュメント）を作成し、維持します。TRD はプロジェクト全体の技術ドキュメントであり、唯一のドキュメントとして維持され、SDD ワークフローのスキルから参照されます。全体に関わる安定した内容、つまり技術スタック、アーキテクチャ、非機能要件、外部依存関係、標準、決定事項を扱います。特定の機能の要件は PRD に、個別の決定の詳細は ADR に記載します。

このスキルはプロジェクトを自動的に分析し、外部検索で内容を補足します。未解決の点についてのみユーザーに質問し、摩擦を最小限に抑え、質問せずに推定できる内容を最大限にします。

入力

ユーザーは次の方法でこのスキルを呼び出せます。

• 引数なし：docs/trd.md の有無からスキルがモードを自動検出します
• 「更新」「編集」「TRD が変わった」「技術スタックが変わった」：編集モードを確認します
• 「作成」「新しい TRD」：作成モードを確認します

モード

作成と編集の検出は docs/trd.md の有無によって自動で行われるため、ユーザーが指定する必要はありません。Decision モードは明示的な意図（決定事項の記録／ADR の作成）によって起動し、自動検出よりも優先されます。

• 作成 — docs/trd.md が存在しない場合：プロジェクトを分析し、外部検索で内容を補足し、未解決の点についてのみ簡単なインタビューを行い、references/template-trd.md に基づいて 6 つのセクションからなる TRD を作成します。
• 編集 — docs/trd.md が存在する場合：プロジェクトを再分析し、現在の TRD と比較して、相違点だけに絞ってインタビューを行い、正しい内容を維持しながら更新します。
• Decision — 技術的な決定を docs/adrs/NNN-slug.md に ADR として記録し（aceito の後は変更不可）、TRD の「グローバルな決定」セクションを更新します。明示的な依頼（「…の決定を記録して」「ADR を作成して」）で起動し、TRD の有無には依存しません。

実行フロー

作成モード

docs/trd.md が存在しない場合に実行します。摩擦を最小限に抑えながら完全な TRD を作成することが目的です。内容の大部分は自動分析と情報の補足によって作成し、インタビューでは実際に未解決の点だけを扱います。

ステップ 0 — コードのないプロジェクト（ソースドキュメントを使用）

プロジェクトにまだコードがない場合（通常はシステムのブレインストーミング（brainstorm-for-systems）の直後）は、分析するファイルがありません。情報源はソースドキュメント（ブレインストーミングの内容をまとめたもの、またはユーザーが指定した別のドキュメント）です。そこから技術スタック、アーキテクチャ、非機能要件、外部依存関係を抽出し、ステップ 1 をスキップして、引用されている依存関係について外部情報で補足（ステップ 2）し、未解決の点についてのみインタビューします。ドキュメントで「検証済み」とされている項目には、情報源と確認日を記載します。

ステップ 1 — プロジェクトの自動分析

質問をする前に、次のファイルとパターンを調べてください。ここで推測できることが多いほど、インタビューは短くなります。インタビューが短いことは、このスキルがうまく機能している証拠です。

スタック：

• package.json / lockfiles → 言語、ランタイム、主要な依存関係、フレームワーク、テストツール
• tsconfig.json → TypeScript の設定、モジュールシステム、ターゲット
• pyproject.toml / requirements.txt / setup.py → Python スタック
• go.mod → Go スタック
• Cargo.toml → Rust スタック
• Makefile、justfile → ビルドおよびテストコマンド

パターン：

• .eslintrc*、.prettierrc*、ruff.toml、clippy.toml → リントとフォーマット
• jest.config.*、vitest.config.*、pytest.ini → テストフレームワークと設定
• package.json 内のテストスクリプト → テストコマンド

アーキテクチャ：

• フォルダー構成（2 階層）→ アーキテクチャパターンと構成
• 代表的なソースファイル 1～2 件 → 命名規則とエラー処理

外部依存関係（部分的な推測）：

• package.json / lockfiles → 外部連携を示す、よく知られたサードパーティ SDK（例：stripe、@sendgrid/mail、 firebase-admin）。すべてのライブラリを列挙するのではなく、契約、レート制限、またはアーキテクチャに関連する動作を 規定するものだけを記載してください
• .env.example / .env.sample → 外部 API の URL またはキーを参照する変数 （例：STRIPE_SECRET_KEY、REDIS_URL、AUTH0_DOMAIN）から、見えにくい依存関係が明らかになります
• docker-compose.yml / docker-compose.yaml → 宣言されているサービス（例：Redis、Postgres、 RabbitMQ）から、開発時にプロジェクトが依存するものがわかります
• terraform/、infra/、k8s/ → クラウド依存関係を明らかにするインフラストラクチャリソース

非機能要件（限定的な推測）：

• インフラストラクチャ設定ファイルから制約がわかる場合があります（例：docker-compose のメモリ制限、 プロキシ／ゲートウェイ設定のタイムアウト）
• 一般に、NFR はファイルに記載されていることが少ないため、インタビューで優先的に確認する項目です

分析後、確信を持って推測できたことと、不確かなままのことを内部で整理してください。不確かな点は ステップ 2 と 3 で確認します。

ステップ 2 — 外部検索による情報の補完

ステップ 1 で特定した外部依存関係ごとに、ユーザーに質問する前に、関連する公開制約を積極的に検索してください。ドキュメントにすでに記載されている内容を尋ねるのは、余計な手間を生むだけです。

検索方法：

ドキュメントへのアクセスや関連情報の検索に使える MCP またはツールを利用してください。たとえば、WebSearch、言語／フレームワークのドキュメント用 MCP、特定サービスの MCP（例：ライブラリ用の context7）、またはセッション内で利用可能なその他のツールです。判断基準は、そのツールがサービスに関する信頼できる技術情報を返せるかどうかです。

• 公開ドキュメントがあり、安定しているサービスを優先してください。例：レート制限、SLA、デフォルトの動作、タイムアウト、接続制限、クォータ
• プロジェクトの内部システムについては検索せず、情報はユーザーへのヒアリングのみで確認してください
• 同じサービスに複数のツールを利用できる場合は、より専門性の高いツールを優先してください（例：サービス専用 MCP ＞ 汎用 WebSearch）

記録方法：

• 出典とともに、結果を内部的に記録してください（例：[WebSearch]、[context7]、[MCP stripe]）
• 検索結果は事前入力の提案として扱い、確認済みの事実とはみなさないでください。ユーザーがプレビューで確認してから記録します
• 信頼できる結果が得られない場合、またはドキュメントが曖昧な場合は、情報の不足として分類し、通常どおりヒアリングに含めてください

検索する制約の例：

検出されたサービス	検索する内容
Stripe / @stripe/stripe-js	エンドポイントごとのレート制限、冪等性の動作
Redis / ioredis	デフォルトの最大接続数、最大 TTL、メモリ不足時の動作
SendGrid / @sendgrid/mail	送信レート制限、バウンスの制限
Auth0 / auth0	認証のレート制限、デフォルトのトークン有効期限
AWS S3 / @aws-sdk/client-s3	オブジェクトサイズ制限、リクエストのレート制限
Firebase / firebase-admin	Firestore の読み取り／書き込み制限、クォータ

ステップ 3 — 不足情報を確認する簡易ヒアリング

推測でも外部検索でも確認できなかった内容だけを質問してください。質問数の上限は 5 件以下（PRD の目標値。許容できる最大数は 8 件）です。なぜこの上限があるのでしょうか。質問がそれ以上必要なら、問題はユーザーではなく分析と情報補完にあります。ヒアリングは補完手段であり、主要な手段ではありません。

ステップ 2 ですでに情報を補完した依存関係については、質問をしません。確認用の提案としてプレビューに表示するだけです。外部検索で信頼できる結果が得られなかった依存関係についてのみ質問してください。

やり取りを減らすため、関連する質問は 1 回のメッセージに最大 2 件までまとめてください。優先順位は次のとおりです。

1. スタックの不足情報（言語またはランタイムが明確でない場合）
2. アーキテクチャパターン（ディレクトリ構成から判別できない場合）
3. テストコマンド（スクリプトや設定に見つからない場合）
4. 規約（リンティング／フォーマット設定がない場合）
5. 主な非機能要件（インフラ関連ファイルに手がかりがない場合）：想定パフォーマンス、SLA、セキュリティ上の制約を、1 つのまとめた質問で尋ねてください。NFR は推測できないことが多く、計画への影響も大きいためです
6. 明らかでない外部依存関係（.env.example やロックファイルから判明せず、外部検索でも確認できなかった場合）：プロジェクトが利用しているサードパーティ API または内部サービスと、遵守すべきレート制限や契約があるかを尋ねてください
7. ADR の場所（docs/adrs/ が存在せず、別のパスを使っている可能性がある場合）

優先順位 5 と 6 の両方が未確認の場合は、メッセージ 1 回にまとめてもかまいません。ただし、メッセージのやり取りは 5 回以下にしてください。

ステップ 4 — ADR のスキャン（US03）

docs/adrs/ をスキャンして、既存の ADR を探します。見つかった各ファイルから、次の情報を抽出します。

• タイトル：H1 またはファイル名から取得します
• 日付：フロントマターまたはファイル名の接頭辞から取得します
• ステータス：フロントマターの status フィールド、または本文中のキーワード（aceito / obsoleto）から取得します
• リンク：docs/trd.md からの相対パスです

ステータスが obsoleto の ADR は、視覚的なマークアップ ~~タイトル~~ を付けて一覧表示します。削除してはいけません。 ADR の内容をインラインで記載しないでください。内容が長い場合があり、TRD とは別に変更されるためです。

docs/adrs/ が存在しない場合は、セクションに *(決定事項はまだ記録されていません)* を使用します。ユーザーから別のパスが指定された場合は、そのパスをスキャンします。

ステップ 5 — プレビューと書き込み

references/template-trd.md を正式な構成として使用し、6 つのセクションを生成します。書き込む前に、各セクションのプレビューをユーザーに提示し、確認を求めます。ステップ 2 で得られた提案には出典を付記し、推論された情報、検索された情報、手動で提供された情報のどれなのかが分かるようにします。

docs/ が存在しない場合は、書き込み前にディレクトリを作成します。ユーザーがキャンセルした場合、ファイルを書き込みません。キャンセルによる副作用はありません。

編集モード

docs/trd.md がすでに存在する場合に実行されます。モードは自動的に検出されるため、ユーザーが指定する必要はありません。目的は、すでに正しい内容を損なわずに TRD を同期させることです。変更があった箇所だけを重点的に確認し、変更されていない内容の再確認をユーザーに求めないようにします。

ステップ 1 — 現在の TRD の読み込み

docs/trd.md をすべて読み込みます。ファイルは存在するものの空、または破損している（認識可能なセクションがない）場合は、作成モードとして扱い、ユーザーに知らせます。

ステップ 2 — 再分析と情報の補足

作成モード（ステップ 1）と同じ基準で、自動分析を繰り返します。その結果が「推論された現在の状態」となり、既存の TRD と比較されます。

この再分析で新たに検出された外部依存関係（プロジェクトには存在するが、現在の TRD には記載されていないもの）については、ユーザーに提示する前に、作成モードのステップ 2 と同様に外部検索で情報を補足します。TRD にすでに記載されている依存関係は、再検索する必要はありません。

ステップ 3 — 差異の検出

TRD と推論された状態を比較し、6 つのセクション（スタック、アーキテクチャ、非機能要件、外部依存関係、規約、全体的な決定事項）のすべてについて、差異を次のように分類します。

• （a）プロジェクトの変更が TRD に反映されていない — 例：フレームワークの変更、新たな外部依存関係の追加、docker-compose へのサービス追加、.env.example への環境変数の追加
• （b）TRD に記載されているが、プロジェクトでは確認できなくなった項目 — 例：依存関係の削除、規約の廃止、外部サービスの提供終了
• （c）曖昧な領域 — 何らかの違いが確認されたものの、実際の変更なのか解釈の違いなのか判断できない場合
• （d）TRD にないセクション — 例：非機能要件や外部依存関係のセクションが追加される前に作成された TRD。その場合、対象を絞ったヒアリングを通じてセクションを補完するかどうかを提案します

差異が見つからない場合は、TRD が同期済みであることを伝え、編集せずに終了します。

ステップ 4 — 対象を絞ったヒアリング

差異を提示し、それぞれについて、更新する、維持する、無視するのいずれかを選べるようにします。TRD ですでに正しい情報は再度収集しません。目的は変更点の確認であり、ヒアリングを最初からすべてやり直すことではありません。これにより、ユーザーがすでに承認した内容を維持します。

ADR の扱い： TRD 内の ADR への参照は、デフォルトで保持します。明示的な確認なしに削除してはいけません。参照先の ADR がリポジトリ内で見つからない場合は、*(ファイルが見つかりません)* と記載し、参照を削除するかユーザーに確認します。ステータスが obsoleto の ADR は、~~タイトル~~ を付けたまま一覧に残します。

ステップ 5 — プレビューと書き込み

承認された変更の概要（変更されたセクションと保持されたセクション）を書き込む前に表示します。TRD は、承認されたすべての変更を反映したうえで、最後にのみ上書きします。

ユーザーがどの時点でキャンセルしても、書き込みは行いません。元のファイルはそのまま保持されます。キャンセルによる副作用はありません。以前の TRD を失うより、後でインタビューをやり直すほうがよいためです。

Decision モード

ユーザーが技術的な決定の記録を依頼した場合（「…の決定を記録して」「ADR を作成して」「X を Y に変更することに決めた」）に実行します。TRD の有無には関係なく、ADR は独立して docs/adrs/ に保存されます。references/template-adr.md から ADR を作成します。

ADR に該当する場合（該当しない場合）

ADR として記録するのは、広範囲に影響し、元に戻すコストが高い永続的な決定のみです。たとえば、データベースの選択、認証戦略、アーキテクチャパターン、基盤となるライブラリ、API の規約などです。特定の機能に限定された決定は ADR ではありません。元に戻すのが難しい場合（新しい依存関係、データモデル、スライス間のインターフェース）は、sdd-especificar が生成するスライスの PLAN に記録します。元に戻せる場合（再利用するユーティリティ、エンドポイントの接続方法など）は、記録する必要もありません。依頼が局所的な決定に関するものなら、ADR を作成する代わりに、その旨を伝えて適切な手順を提案します。

ステップ 1 — 番号付け

docs/adrs/ の一覧を取得します（存在しない場合はディレクトリを作成します）。次の ADR には、既存の最大番号に 1 を加えた番号を付け、3 桁の NNN 形式にします。既存の ADR がない場合は 001 から開始します。

ステップ 2 — ドラフト優先で生成

ユーザーの説明をもとに、長いインタビューは行わず ADR 全体を生成します。不足している「コンテキスト」「検討した代替案」「結果」は推測で補い、それぞれの推測に *(前提 — 確認または修正してください)* と記します。ユーザーがすでに決定している場合、初期 status は aceito とします。決定がまだ未確定の場合は proposto とします。

ステップ 3 — 置き換え

決定が以前のものに取って代わる場合は、古い ADR を特定します。

1. 新しい ADR の supersedes: "NNN" を記入します。
2. 古い ADR の superseded_by: "NNN" を記入し、status を obsoleto に変更します。これは aceito の ADR に許可される唯一の変更です。古い ADR のその他の部分は編集しません。

ステップ 4 — 書き込みと TRD への参照

1. docs/adrs/NNN-slug.md に書き込みます。
2. docs/trd.md が存在する場合は、「グローバルな決定」テーブルに新しい行（#、タイトル、日付、ステータス、リンク）を追加します。obsoleto の ADR は ~~タイトル~~ として表示し、削除しません。
3. docs/trd.md が存在しない場合は、次回の TRD 作成時に ADR が自動的にインデックスされることを伝えます（作成モードの ADR スキャンがこれを担当します）。
4. コミットを提案します：docs(adr): adiciona ADR-NNN <slug>。

不変性

aceito の ADR は、別の ADR に置き換えられた際の status の変更を除き、不変です。決定を見直す場合、ADR を編集するのではなく、古い ADR を指す supersedes を付けた新しい ADR を作成します。これは、PRD の concluido に対する不変性と同じ方針です。

参照テンプレート

• references/template-trd.md — 6 つの必須セクションを含む、生成される TRD の標準構成です。TRD のセクションを生成または編集する際は、必ず参照してください。
• references/template-adr.md — Decision モードで生成する ADR の標準構成です。ADR を作成する際は、必ず参照してください。

対象外

このスキルでは、次のことは行いません。

• PRD を作成する（escrever-prd の役割）
• SPEC、PLAN、TASKS を生成する（sdd-especificar の役割）
• Decision モード以外で ADR を作成する。作成モードと編集モードでは、docs/adrs/ にすでに存在する ADR のみを参照します。ADR の作成は Decision モードに限られます
• ビジネス上の決定を行う。不足している情報はユーザーに確認します
• ユーザーが書き込み前のプレビューをキャンセルした場合に、docs/trd.md を編集する