escrever-prd

PRD の作成

機能の PRD を作成・編集します。PRD はプロダクトの思考単位です。つまり、意思決定をまとめて説明できる振る舞いとビジネスルールの集合です。人間向けのドキュメントであり、プロダクトの意図を示す信頼できる情報源です。振る舞いとビジネスルールの観点から機能を完全に記述し、AI は必要に応じてその「理由」を参照し、sdd-especificar で PRD から導出された SPEC に基づいて実装します。実装に必要な技術的コンテキストは、実装時に読み込まれる TRD から得られます。参照フィールドを使うと、必要に応じて PRD 同士や外部リソースを関連付けられます。

このスキルでは、PRD の新規作成と、未完了の既存 PRD の編集の両方を行います。status: concluido の PRD は不変であり、このスキルで編集してはいけません。

ワークフローにおける PRD の役割

PRD には 2 つの役割があります。

1. 機能仕様 — 機能の実装に使用する、振る舞いとビジネスルールを記述した自己完結型のドキュメント
2. 状態管理 — status フィールドと depends_on グラフを通じて、機能のライフサイクルに関する信頼できる情報源となること

そこから導かれる原則は次のとおりです。

• concluido における不変性 — ステータスが concluido に達すると、PRD は凍結され、履歴記録となります。その後に振る舞いを変更する場合は、完了済みの PRD を編集するのではなく、新しい PRD を作成します
• depends_on による段階的な情報開示 — PRD 間の依存関係は明示的に宣言します。エージェントは、実装のコンテキストで必要になった場合にのみ、依存先の PRD を読み込みます
• 責務の分離 — PRD は振る舞いとビジネスルールを扱い、TRD と ADR は技術的な制約、スタック、アーキテクチャ上の意思決定を扱います。PRD は技術的な成果物を参照しますが、それを指揮、規模設定、追跡するものではありません。PRD の形式は実行方法ではなく、プロダクトによって決まります
• 安定した ID — US と Milestone には ID（US01、Milestone 1 など）が割り当てられます。後続の成果物（計画、タスク）がこれらの ID を参照するため、割り当て後に変更してはいけません

入力

ユーザーは、構築したいものについての説明を提供します。次の内容を含めることができます。

• 問題または機会の説明
• 解決策のアイデア
• 技術的なコンテキスト
• 既知の制約

$ARGUMENTS — 指定されている場合は、機能の初期説明として使用します。

実行フロー

1. モードの特定

最初に、リクエストが新規作成か編集かを特定します。

• 新規作成 — ユーザーが新しい機能を説明している、または既存の PRD を参照していない
• 編集 — ユーザーが特定の PRD を（番号、名前、またはファイルで）参照している、または既存の内容の調整・改善を求めている

編集モードの場合：

1. ./docs/prds/ にある、参照された PRD を読み込みます
2. status を確認します。concluido の場合は処理を中断し、完了済みの PRD は不変であり、振る舞いを変更する場合は新しい PRD を作成する必要があることをユーザーに伝えます
3. rascunho、pronto、または em-progresso の PRD は、割り当て済みの prd_number、US ID、Milestone ID を保持したまま編集を進めます

2. スコープとブロッキングギャップの分析

生成する前に、次の2点をすばやく確認します。

2a. 複数の機能の検出

単位の基準は分離ではなく、自立性です。PRDが1つの機能を扱うのは、各部分がそれぞれ単独で説明でき、ユーザーにとって観測可能な価値を提供する場合です。入力に、この基準を個別に満たす部分がある場合、それらは別々の機能です。相互に依存していても同様です。依存関係は一般的なものであり、depends_onに記載します（連鎖する機能も、それぞれ独立した機能です）。分割を妨げる要因ではありません。

**健全性の目安：**その機能に多くのプロダクトマイルストーン（実際には約6つ超）が必要な場合、おそらく複数の機能が含まれているため、分割を見直してください。マイルストーンが少ないからといって、必ずしも何かをする必要はありません。小さな機能に正当なマイルストーンが1つまたは2つある場合もあります。

複数の機能を検出した場合、生成前に具体的な分割案を提案します。

Detectei 3 features no input. Sugiro criar:
  PRD-A: [nome da feature A]
  PRD-B: [nome da feature B]
  PRD-C: [nome da feature C]

Começamos pelo PRD-A?

分割案の確認または調整を待ちます。保留中のPRDの一覧を内部に記録します。

2b. ブロッキングギャップ

ドラフトが使いものにならなくなるような、合理的に推測できない情報が欠けていないか確認します。実際のブロッキングギャップの例としては、機能のドメインや、機能が組み込まれるシステムを特定できないことが挙げられます。

ブロッキングギャップがある場合は、面談形式にせず、選択肢が可能な場合は選択肢を添えて、回答が限定される質問を1つだけ行います。それ以外のギャップはすべて推測し、ドラフト内に明記します。

ブロッキングギャップがない場合は、すぐに生成します。

3. 前提を明記したドラフトの生成

追加情報を待たずに、すぐに完全なPRDを生成します。提供されていない情報は推測し、本文中に明記します。

前提の形式：

- Token expirado → redirecionar para login *(premissa — confirme ou corrija)*

推測した内容には、rules、edge cases、受け入れ基準、対象外の範囲、milestonesのいずれであっても、*(premissa — confirme ou corrija)*を使用します。ユーザーが見直すのは具体的な文章であり、抽象的な質問に答える必要はありません。

生成手順：

1. references/template-prd.mdのテンプレートを読む
2. すべてのセクションを埋めて完全なPRDを生成する
3. 提供されていないrulesとedge casesを推測し、それぞれに前提であることを明記する
4. 部分的な見直しのため、ドラフトをユーザーに提示する 生成ルール：

• 明確で簡潔な表現を使い、不要な専門用語は避けてください
• すべてのセクションを埋めてください。推測した内容は前提として明記し、ユーザーが明示的に未決定とした項目に限り「未定」を使用してください
• PRDは動作とビジネスルールについて自己完結させます。技術的なコンテキストについては自己完結させません。スタック、アーキテクチャ、規約は実装時に読み込まれるTRDに記載します。「コンテキスト」セクションには、関連する場合に参照先のみを記載し、スタックを重複して記載しないでください
• 各機能は、連番のID（US01、US02...）を付けたユーザーストーリー（US）にしてください
• 各USには、「[ペルソナ]として、[アクション]したい。[メリット]のために」の形式のユーザーストーリー、ビジネスルールと期待される動作を記載するRules、異常な状況と期待される動作を記載するEdge casesを含めてください
• 各USには、少なくとも1つのRuleと1つのEdge caseが必要です。提示されていない場合は、最も可能性の高い内容を推測し、前提として明記してください
• Edge casesは「[異常な状況] → [期待される動作]」の形式にしてください
• 受け入れ基準（§5a）には、機能に固有の機能要件と非機能要件を含めてください。応答時間、可用性、容量はビジネス上の理由がある場合に記載し、しきい値とその理由を記録してください。プロジェクト全体のNFR（全般的なp95、稼働時間、暗号化）はPRDではなくTRDに記載してください。成功指標（ベースライン→目標値）は§5bに記載します
• 「正しく動作すること」や「高いパフォーマンス」といった曖昧な基準は認められません。客観的に検証できるように書き直してください。十分なデータがない場合は前提として明記してください
• マイルストーンはプロダクト上の節目です。ユーザーに価値を届ける、一貫性のある機能群であり、実行工程の一部ではなく、成果として発表できるものです。各マイルストーンには、対象となるUS（IDで指定）、節目とする理由（自己評価として、理由付けが無理に感じられる場合は、タスクを偽装しているか、2つの節目を押し込んでいる可能性があります）、受け入れチェックリスト（マイルストーン内のUSに該当する§5aの基準を抽出したもので、実装後に承認者がチェックできます）を定義してください。マイルストーンの最低数はありません。上限の目安である約6件は、2aの妥当性を判断するための指標です。マイルストーン内で技術タスクや実行順序を詳述しないでください。分解（スライス、タスク、順序）は sdd-especificarが担当します
• ルール分岐が文章だけでは明確にならない場合に限り、「ビジネスフロー」セクション（§4、判断ポイントをルールとして示すジャーニー／プロセス図）を含めてください。技術トポロジー（コンポーネント／サービス、データモデル）はPRDには含めず、TRD、ADR、またはローカルな判断で元に戻すことが難しい場合はスライスのPLANに記載します
• 「スコープ外」セクションは必須です。提示されていない場合は、明らかに除外される項目を推測し、前提として明記してください
• 「決定事項の記録」には、重要なプロダクト上の決定とビジネス上の前提を記録します。アーキテクチャや技術上の決定は含めず、ADRに記載します
• 入力に長期的に有効なアーキテクチャ上の決定（データベースの選択、認証戦略、アーキテクチャパターン、基盤となるライブラリ）が含まれている場合、プロダクト上の決定として取り込まないでください。ADRであることを明示し、escrever-trdのDecisionモードを使って（docs/adrs/に）記録するよう提案してください。PRDでは§8から参照できます
• 「参考資料」セクションには、コンテキストで言及されたドキュメント、issue、関連PRD、API、デザイン、外部リソースへのリンクを記載してください
• frontmatterのreferencesフィールドには、「参考資料」セクションと同じリンクをリスト形式で記載してください
• USのID（US01、US02...）とマイルストーンのID（Milestone 1、2...）は変更しないでください。一度割り当てたIDは、後続の成果物（計画、タスク）がこれらのIDを参照するため、変更できません
• 作成モードで保存する際の初期statusは、常にrascunhoです。編集モードでは、PRDの現在のstatusを維持してください。pronto、em-progresso、concluido間の遷移は、今後の計画・実行スキルで行います

4. 依存関係のマッピング

最終レビューのために PRD を提示する前に、次の手順を実行します。

1. ./docs/prds/（またはユーザーが指定したパス）にある既存のファイルを一覧表示します
2. 既存の各 PRD について、現在の機能がその PRD ですでに仕様化されている内容に依存するかどうかを評価します。依存とは、この機能の実装が、別の PRD に記載された動作、エンティティ、インターフェース、またはルールを前提とすることを意味します
3. 特定した prd_number のリストを frontmatter の depends_on フィールドに入力します（例：depends_on: ["001", "003"]）
4. 各依存関係の判断基準を「決定記録」に記録します。これにより、後から推論を再構築する手間を省けます

ルール：

• 依存関係は実際に存在し、具体的である必要があります。「関連する」または「同じドメインの」すべての PRD を列挙しないでください
• 依存関係がない場合は、depends_on: [] のままにします
• 依存する PRD の読み込みは必要に応じて行います（段階的開示）。その内容を現在の PRD に含めないでください

5. 個別の調整

ユーザーが求めた修正をドラフトに適用します。前提の修正、スコープの調整、ルールの精緻化などを行います。承認されるまで繰り返します。

レビューによって機能のスコープが変更された場合は、保存前に depends_on を再評価します。責任範囲が増減した機能では、依存関係も増減する可能性があります。

6. ファイルの保存

新規作成モードでは、新しい PRD を保存します。

1. 次の番号を決定する：./docs/prds/ にあるファイルを一覧表示し、使用済みの最大番号（形式 NNN）を特定します。次の PRD には、連続する次の番号を割り当てます。PRD がない場合は、001 から始めます。
2. ファイル名を付ける：NNN-[nome-em-kebab-case].md（例：003-autenticacao-oauth.md）
3. 標準の保存先：./docs/prds/
4. ユーザーが別のパスを指定した場合は、指定されたパスを使用します
5. ディレクトリが存在しない場合は作成します
6. frontmatter の prd_number フィールドに割り当てた番号を入力します（例：003）

編集モードでは、prd_number、ファイル名、現在の status、割り当て済みの US と Milestone の ID を維持したまま、元のファイルを上書きします。新しい US には、次に利用可能な連番 ID を割り当てます。

7. 複数 PRD の継続

保存後、ステップ 2a で保留中の PRD を含む分割案が提示されていたか確認します。

提示されていた場合：

PRD-A salvo. Continua com PRD-B: [nome da feature B]?

確認後、次の PRD のサイクルを開始します。より正確な推論のために、前の PRD の決定をコンテキストとして活用します（同じスタック、同じシステム、検出済みの同じパターン）。

分割したすべての PRD が保存されるか、ユーザーが中断するまで繰り返します。