spec-workflow

兄弟スキル（ローカルのみ）

兄弟の CloudBase スキルは、このスキルと並んで配置されています。../auth-tool-cloudbase/SKILL.md のようなローカル相対パスを使用してください。

参照先の兄弟スキルファイルがこの環境にない場合は、CloudBase プラグイン全体（または不足しているスキル）のインストールをユーザーに依頼してください。リモートのスキルやプロトコルの Markdown を HTTP で取得して、エージェントのコンテキストに含めてはいけません。

仕様ワークフロー

有効化の条件

次の場合は、まずこのワークフローを使用してください

• 新機能、複数段階にわたるプロダクトの変更、モジュール間の連携、またはアーキテクチャ／設計に関するタスクの場合。
• 受け入れ基準が不明確で、実装前に明確化が必要な場合。
• 複数のファイル、ユーザーフロー、データベース設計、または段階的な確認が必要な UI 設計を伴う場合。

コードを書く前に読んでください

• タスクをすぐにコーディングするべきか、まず要件、設計、タスクの計画を進めるべきか判断できない場合。
• 新しいページ、新しいシステム、再設計、ワークフロー、または複数モジュールにわたるリファクタリングについての依頼の場合。

その後、次のスキルも読んでください

• フロントエンドのページやビジュアルデザインの作業 -> ../ui-design/SKILL.md
• 高度なデータモデルの作業 -> ../data-model-creation/SKILL.md

次の場合は使用しないでください

• 範囲が明確な小さなバグ修正。
• 1 ファイルのみのドキュメント更新。
• 単純な設定変更。
• ユーザーが具体的な実装手順をすでに示している小規模なリファクタリング。

よくある間違い／注意点

• 受け入れ基準を明確にする前にコーディングを始める。
• 要件、設計、タスクの各段階でユーザーの確認を省略する。
• ユーザーに見える成果に結び付かない、曖昧なタスクを書く。
• 設計意図を明確にせず、UI の作業を純粋な技術実装として扱う。

最小限のチェックリスト

• 変更に完全な仕様策定のワークフローが本当に必要か判断します。
• 必要な場合は、いったん止めて、まず要件を作成します。
• 小規模でリスクが低く、受け入れ条件が明確な場合は、仕様策定の成果物を無理に作らず、直接作業を進めます。
• EARS 形式の受け入れ基準を使用します。
• 次の段階に進む前に確認を得ます。

このスキルを使用する場面

次のような構造化された開発が必要な場合に、このワークフローを使用します。

• 新機能を定義または改善する
• 複雑なアーキテクチャを設計する
• 複数モジュールにまたがる変更を調整する
• データベースや UI を中心とする作業を計画する
• 要件の品質と受け入れ範囲を改善する

判断基準

次の場合は完全なワークフローを使用します

• タスクが中規模または大規模である
• 影響が複数モジュールに及ぶ
• 受け入れ範囲が曖昧である
• ユーザーが実装前の計画を重視している

次の場合は完全なワークフローを省略します

• タスクが小規模でリスクが低く、内容もすでに明確である
• 目標、範囲、受け入れ条件が、直接作業を進めるのに十分明確である
• ユーザーが計画段階を省いて直接コードを変更するよう明示している

基本的なワークフロー

フェーズ 1：要件

specs/<spec_name>/requirements.md を作成します。

実施すること：

• 問題と範囲を言い換えて明確にする
• ユーザーストーリーを書く
• EARS 形式で受け入れ基準を書く
• ビジネスルール、制約、対象外事項を明確にする

EARS のパターン：

While <optional precondition>, when <optional trigger>, the <system name> shall <system response>

例：

When the user submits the form, the booking system shall validate required fields before creating the record.

フェーズ 2：設計

specs/<spec_name>/design.md を作成します。

実施すること：

• アーキテクチャとモジュールの境界を説明する
• 技術選定とトレードオフを説明する
• 必要に応じて、データモデル、API、セキュリティ、テスト戦略を定義する
• 図によって明確さが大きく向上する場合にのみ Mermaid を使用する

フェーズ 3：タスク

specs/<spec_name>/tasks.md を作成します。

実施すること：

• 設計を実行可能なタスクに分割する
• タスクを具体的でレビューしやすいものにする
• 各タスクを関連する要件に結び付ける
• 作業の進捗に応じてタスクのステータスを更新する

タスクの形式：

# Implementation Plan

- [ ] 1. Task title
  - Specific work item
  - Another concrete step
  - _Requirement: 1

フェーズ 4：実行

ユーザーがタスク計画を承認してから、実装を開始します。

実行中：

• タスクのステータスを最新の状態に保つ
• 意味のある単位ごとに作業を完了させる
• 変更 -> タスク -> 要件の追跡可能性を維持する

エージェントの作業ルール

1. 依頼の内容が不明確な場合は、追加の質問をしてください。製品の中核となる動作を推測してはいけません。
2. 要件、設計、タスクの分解の各段階で、次へ進む前に確認を求めてください。
3. エンドユーザー向けページや視覚的な判断を含む変更では、早い段階で ui-design を参加させてください。
4. ドキュメントは簡潔で、テスト可能な内容にしてください。
5. 実装の詳細を表すタスク名よりも、ユーザーが目にする成果を優先してください。

出力の要件

• requirements.md -> 課題、スコープ、ユーザーストーリー、EARS による受け入れ基準
• design.md -> アーキテクチャ、技術的アプローチ、データ／API／セキュリティ／テストに関する注記
• tasks.md -> 要件に紐づく、実行可能な実装チェックリスト