specs-tickets

仕様チケット

仕様駆動のライフサイクルに沿ってチケットを作成・実行するか、既存のチケットで作業を再開します。

スキルの依存関係

このスキルは、連携して動作するように設計された一連のスキルの一部です。

• spec-driven — 中核となるルールと高レベルのドキュメントマップ
• specs-setup — 新規プロジェクトの specs/ を初期化
• specs-tickets（このスキル）— ライフサイクルに沿ってチケットを作成・実行
• specs-review — 仕様の健全性、一貫性、乖離を監査
• specs-finish-ticket — 完了前に実装済みチケットをレビュー

これらのスキルがプロジェクトにない場合は、先にインストールするようユーザーに案内してください。

npx skills add b12consulting/skills --skill <missing_skill>

中核となるルールを確認するため、常に最初に spec-driven スキルを読み込んでください。ライフサイクルと Findings の詳細なガイダンスについては、methodology reference を読み込んでください。ドキュメントを作成する際は、templates を読み込んでください。

前提条件

1. specs/ フォルダーに Vision.md、PRD.md、Architecture/README.md が存在することを確認します。存在しない場合は、先に specs-setup スキルを実行するようユーザーに促してください。
2. プロジェクトのコンテキストを把握するため、specs/README.md、続いて specs/Vision.md、specs/PRD.md、specs/Architecture/README.md を読みます。
3. チケットに関連する specs/Architecture/data-model.md などのアーキテクチャ補足ドキュメントを読みます。

---

エントリーポイント：新規チケットか既存チケットか？

ユーザーが新規チケットを作成したいのか、既存チケットを続行したいのかを判断します。

• ユーザーが新しい作業について説明している場合は、以下の「新規チケット」に進みます。
• ユーザーが既存のチケットに言及している場合は、以下の「チケットの再開」に進みます。
• 不明な場合は、ユーザーに確認します。

---

新規チケット

フェーズ 0：チケットの作成

1. 実施する作業についてユーザーに説明を求めます。
2. 次のチケット番号を決めます。specs/tickets/ を調べ、既存の番号のうち最も大きい番号に 1 を加えます。チケットがない場合は 001 から始めます。
3. 説明から、小文字とハイフン区切りの語で短いスラッグを作成します。
4. チケットフォルダーと Spec.md を作成します。

specs/tickets/<NNN>-<slug>/Spec.md

以下のフロントマターを使用します。

---
id: "<NNN>"
title: "<Descriptive title>"
status: research
owner: ""
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

続けて、チケットの概要を 1 段落で記述し、仕様の初期スキャフォールドを作成します。

その後、フェーズ 1：調査に進みます。

---

チケットの再開

1. チケットの特定

どのチケットを続行するかユーザーに尋ねるか、会話の文脈から特定します。

• 003 などのチケット番号
• チケットのタイトルを調べて特定する、「認証チケット」などの説明

あいまいな場合は、specs/README.md に記載されている進行中のチケットを一覧表示し、どれを選ぶかユーザーに尋ねます。

2. チケットの状態を確認

チケットの Spec.md を読み、フロントマターのステータスを確認します。次に、チケットフォルダー内にあるすべてのドキュメントを読み、全体のコンテキストを把握します。

現在の状態をユーザーに要約します。チケットがどのフェーズにあるか、完了していること、次に行うことを伝えます。

3. 乖離の確認

チケットのドキュメントを、以下の現在の状態と比較します。

• specs/Vision.md と specs/PRD.md — このチケットの作成後、要件や成功に関する期待に変更はあったか？
• specs/Architecture/README.md — アーキテクチャに変更はあったか？
• コードベース — 前回チケットに取り組んでから、関連するコードに変更はあったか？

乖離が見つかった場合：

• 具体的な不整合をユーザーに報告します
• 続行する前にチケットを更新する必要があるか相談します
• 仕様が変更されている場合、チケットの Spec.md または Plan.md の更新が必要になることがあります
• コードが変更されている場合、完了済みのチェック項目を再検証する必要があることがあります

4. ブロッカーの解消

チケットのステータスが open-questions の場合：

• Decisions.md にある未解決の質問をユーザーに提示します
• 各質問について判断を求めます
• Decisions.md の Resolved セクションに決定事項を記録します
• すべての質問に回答したら、チケットのステータスを更新します

チケットの Plan.md に未解決のブロッカーや順序上の制約が記録されている場合：

• それらのブロッカーと現在の状況を報告します
• 待機するか、回避策を使うか、スコープを見直すかを相談します

5. ライフサイクルを再開する

現在のステータスに基づいて、適切なフェーズから再開します。

現在のステータス	次のアクション
research	Research.md の調査結果を確認します。フェーズ 2：仕様策定に進みます。
specifying	Spec.md が検証済みかどうかを確認します。検証済みの場合は、フェーズ 3：計画に進みます。未検証の場合は、検証のために提示します。
open-questions	質問を解決してから、前のフェーズに戻ります。
planned	チェックリストを含む Plan.md を確認し、承認されたら実装に進みます。
in-progress	Plan.md の実行チェックリストに沿って作業を続けます。
done	チケットが完了したことをユーザーに伝えます。再開するか、フォローアップを作成するかを尋ねます。
archived	チケットがアーカイブされたことをユーザーに伝えます。代わりに新しいチケットを作成するかを尋ねます。

6. 調査結果を更新する

作業を再開した際に、長期的に有効な前提、摩擦、回避策、フォローアップ候補、または残存リスクが明らかになった場合は、Findings.md を作成または更新します。時系列の記録ではなく、厳選された長期的に有効な内容を保ちます。

---

チケットのライフサイクル

ライフサイクルは次のとおりです。調査 → 仕様策定 → 計画 → 実装 → 完了レビュー → 完了。

仕様、計画、完了確認の各チェックポイントでは、ユーザーによる検証が必要です。

人間またはエージェントを問わず、誰でも任意のフェーズを実行できます。 ライフサイクルで定めるのは順序であり、担当者ではありません。

---

フェーズ 1：調査

目標：問題領域を理解し、適切な仕様を作成するために必要な情報を収集します。

1. チケットに関連するコードベース、既存のドキュメント、外部リソースを調査します。
2. 技術的な制約、既存のパターン、考えられるアプローチを特定します。
3. チケットがドメインエンティティまたは境界ペイロードに影響する可能性がある場合は、次の項目を特定します。
   • 関連する標準的なドメイン概念
   • 関連する標準的な境界コントラクト
   • そのコントラクトの所有者、生成元、利用者
   • シリアライズ形式または永続化形式が、標準的なメモリー内の形状と異なるかどうか
4. Research.md に調査結果を記録します。
   • 目的：明らかにしようとしていること
   • 調査結果：トピックごとに整理
   • 検討した選択肢と、それぞれの長所・短所
   • 推奨案
   • 参考資料
5. Spec.md のチケットステータスを research に更新します。

単純なチケットでは、Research.md は任意です。 ユーザーの説明から進め方が明確な場合は、フェーズ 2 に直接進みます。1 行で済むバグ修正に調査は不要ですが、複数のアプローチが考えられる新機能では、多くの場合、調査が必要です。

---

フェーズ 2：仕様策定

目標：完了の定義を明確にします。

1. 調査結果またはユーザーの説明に基づいて、Spec.md を作成します：

   • ユーザーストーリー：誰が何を求めているのか、またその理由を記述します。各ストーリーに優先度（P1、P2、P3、...）を割り当てます。各ストーリーは独立してテスト可能であり、1 行の検証メモを含める必要があります。
   • 受け入れ基準：作業の完了を証明する、具体的でテスト可能な条件
   • スコープの境界：対象範囲と、明示的に対象外とする範囲

2. 明確化の確認。 仕様を確定する前に、次のカテゴリにわたって曖昧さがないか確認します：

   • 機能の範囲と動作
   • ドメインとデータモデル
   • インタラクションと UX フロー
   • 非機能的な品質属性
   • 統合と外部依存関係
   • エッジケースと障害時の処理
   • 制約とトレードオフ
   • 用語の一貫性

   各カテゴリに不足や曖昧な点がある場合、確認が実装に重大な影響を与えるか判断します。影響がある場合は、ユーザーに質問します。最も重要な質問に絞ってください。計画段階で後回しにするのが適切な点は、内部に記録して先に進みます。

3. 仕様策定を妨げる未解決の質問がある場合は、Decisions.md を作成します：

   • コンテキストとともに各質問を「未解決」セクションに記載します
   • それぞれの選択肢とトレードオフを示します
   • それぞれに推奨する回答を記載します
   • 先に進む前に、すべての未解決の質問についてユーザーに判断を求めます
   • 解決した質問は、決定内容、日付、根拠とともに「解決済み」セクションに移動します

4. 仕様を自己検証します。 ユーザーに提示する前に、次の点を確認します：

   • 実装の詳細が仕様に紛れ込んでいない
   • すべての要件がテスト可能で曖昧でない
   • 受け入れ基準が測定可能である
   • スコープの境界が明確である
   • [NEEDS CLARIFICATION] のマークが付いた項目が 3 件を超えていない
   • すべてのユーザーストーリーに優先度と独立したテスト方法の説明がある
   • フィールドレベルのスキーマ詳細が仕様に含まれるのは、ユーザーから見える契約またはプロダクトレベルの契約の一部である場合に限る。安定した技術的な契約の定義は、アーキテクチャ文書または計画書に記載する

   いずれかの確認に失敗した場合は、提示する前に仕様を修正します。

5. Spec.md のチケットステータスを specifying に更新します。質問がある場合は open-questions に更新します。

6. Spec.md をユーザーに提示し、検証してもらいます。

チェックポイント：ユーザーが仕様を検証するまで、フェーズ 3 に進んではいけません。

---

フェーズ 3：計画

目標：実装戦略と実行可能なチェックリストを定義します。

1. 確定した仕様に基づいて、Plan.md を作成します：

   • アプローチ：実装戦略の概要
   • 主要な設計上の決定：重要な選択とその根拠
   • 依存関係と実施順序：実行に実質的な影響を及ぼすブロッカーまたは順序上の制約のみ
   • データモデルとコントラクトへの影響：該当する場合、正規エンティティ、境界コントラクト、シリアライズの違い、互換性または切り替えポリシー
   • 実装チェックリスト：ファイル単位の具体的な実行チェックリスト
   • リスクと軽減策：起こり得る問題とその対処方法
   • 検証：計画が仕様を満たしていることを証明するチェック

2. アーキテクチャドキュメントとの整合性を確認します。 計画でアーキテクチャの変更が必要な場合：

   • その旨をユーザーに明示します
   • specs/decisions/ に ADR を提案します
   • ユーザーの承認後にのみ、specs/Architecture/README.md と影響を受けるサブドキュメントを更新します

3. 網羅性チェック。 計画を提示する前に、Spec.md と Plan.md の整合性を確認します：

   • すべての要件が少なくとも 1 つのチェックリスト項目に対応している
   • すべてのチェックリスト項目が要件または設計上の決定に紐づいている
   • 用語が両ファイルで一貫している

   データモデリングまたは境界コントラクトに影響するチケットでは、以下も確認します：

   • 変更された正規エンティティまたはコントラクトが、関連するアーキテクチャドキュメントに反映されている
   • すべてのコントラクト変更について、提供側と利用側の整合性を確認する明示的な検証チェックリスト項目がある
   • 必要な場合、互換性対応または移行作業が Plan.md に記載されている

   不足が見つかった場合は、先に進む前に Plan.md または Spec.md を更新します。この確認は簡易的なものです。チェックリスト項目が 5 個以下の非常に小規模なチケットでは省略してください。

4. Spec.md のチケットステータスを planned に更新します。

5. 確認のため、Plan.md をユーザーに提示します。

チェックポイント：ユーザーが計画を承認するまで、実装に進まないでください。

---

フェーズ 4：実装

目標：計画を実行します。

1. Plan.md の実行チェックリストに沿って、順番に作業します：

   • 各項目の完了時にチェックを付けます
   • 項目を進める中で仕様または計画の更新が必要だと判明した場合は、実装を一時停止します
   • 該当するドキュメントを更新し、ユーザーに伝えます。変更が重大な場合は承認を得ます

2. Findings.md を段階的に更新します：

   • セッション終了後も重要な、記録に残すべき発見事項に使用します
   • そのような発見事項が生じたらすぐに作成し、チケットがほぼ完了するまで待たないでください
   • すべての発見事項の末尾に、Addressed here、Follow-up needed、Accepted for now などの明確な対応状況を記載します

3. 実装中の乖離検出：実装により Vision.md、PRD.md、またはアーキテクチャドキュメントとの矛盾が明らかになった場合：

   • 直ちにユーザーに知らせます
   • 仕様を更新する ADR を作成するか、コードを修正するフォローアップチケットを作成します
   • 仕様から黙って逸脱しないでください

4. Spec.md のチケットステータスを in-progress に更新します。

---

フェーズ 5：完了レビューの準備

目標：チケットを完了としてマークする前に、独立したクローズアウトレビューに引き継ぎます。

1. Spec.md のすべての受け入れ条件が満たされているように見えることを確認します。
2. Plan.md と Findings.md を最終確認します：
   • 完了したチェックリスト項目にチェックが付いているか、明確に置き換えられていることを確認します
   • Findings.md に、長期的に重要な前提、障害要因、フォローアップ候補、残存リスク、テストの不足が、明確な対応状況とともに記録されていることを確認します
3. チケットがデータ形状に影響する場合は、変更を明確に分類するために specs/Architecture/data-model.md を更新します：
4. チケットをまだ done にしないでください。
5. ユーザーに新しい会話を開始し、独立したレビューのために specs-finish-ticket スキルを実行するよう依頼します。

通常、完了レビューに合格し、ユーザーがクローズを承認するまで、チケットは in-progress のままです。

---

途中で変更が発生した場合の対応

実装中に要件が変更されることはよくあります。その場合は、次の手順に従ってください。

1. 新しい要件や変更された要件を Spec.md に反映します。
2. アプローチ、順序、チェックリストが実情に合うよう、Plan.md を更新します。
3. 変更によって明らかになった前提、回避策、今後の対応候補、または記録に残す価値のある残存リスクがあれば、Findings.md を更新します。
4. 変更が Vision.md、PRD.md、またはアーキテクチャのドキュメントに影響する場合は、ADR を作成します。
5. 正式なエンティティ、境界の契約、またはシリアライズの方針が変わる場合は、それらの定義が長期的なシステム設計の一部であれば、specs/Architecture/data-model.md および／または該当するアーキテクチャのドキュメントを更新します。
6. 変更が重大な場合は、ユーザーに再確認します。

チケットの正とする情報源は、常にコードではなく仕様です。仕様を最新の状態に保ってください。

規模に応じたガイダンス

• バグ修正や設定変更などの小規模なチケット：チケットを作成し、仕様を定め、チェックリスト付きの簡潔な計画を作成して実装した後、完了レビューに回します。Research は省略します。
• 機能追加やリファクタリングなどの中規模なチケット：すべてのフェーズを使用します。Research は簡潔でもかまいません。
• 新しいシステムの構築や大規模な再設計などの大規模なチケット：すべてのフェーズを使用します。Plan.md のチェックリストが約 15 項目を超える場合は、作業を複数のチケットに分割することを検討してください。