brief-ku

Name: brief-ku
Author: adytm404

github.com/adytm404開発253 回インストール8 週間前に更新

リポジトリ

brief-ku について

brief-ku は、アプリのアイデアを製品・技術仕様と実装計画にまとめるスキルです。段階的に重要な要件を確認し、エージェントのモードや権限に応じて進め方を調整し、必要に応じて実装へ進みます。

主な機能

01段階的な要件の確認
02アーキテクチャと技術の提案
03PRD と技術仕様の作成
04実装計画の作成
05エージェントのモードと権限への対応

活用シーン

01曖昧なアプリ案を開発要件に整理
02アーキテクチャ選定前の要件確認
03AI エージェントによる計画やアプリ構築

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/adytm404/skills --skill brief-ku

インストール後、Claude Code で/brief-kuを入力して読み込まれたか確認します。

同梱ファイルREADME.md

詳細

App Architect & PRD Builder Skill

目的

このスキルは、短く曖昧な、または技術的な知識を前提としないアプリケーション開発の依頼を、完全で実装可能な製品仕様書にまとめます。

ユーザー入力の例：

出勤管理アプリを作ってください。

重要な要件がまだ明確でない場合、このスキルはすぐに完全な PRD を生成してはいけません。まず、シンプルで技術的な知識を前提としない言葉でユーザーのニーズを把握し、適切な場合は妥当なデフォルトを提案します。そのうえで、不足している情報が製品、アーキテクチャ、セキュリティ、データベース、認証、デプロイ、実装に実質的な影響を与える場合に限り、追加の質問をします。

最終的な成果物は、コーディングエージェントやソフトウェア開発者にそのまま渡せるだけの詳細さを備えている必要があります。

基本動作

このスキルは、次の 5 つの段階で動作します。

アプリケーションのアイデアを把握する
重要な要件を明確にする
アーキテクチャと技術を提案する
完全な製品仕様と技術仕様を作成する
実装可能な開発計画を準備する

技術用語で技術に詳しくないユーザーを圧倒してはいけません。

まず技術的な判断をわかりやすい言葉で伝え、その後、回答を技術要件に置き換えて内部的に扱います。

実行モードの検出

実質的な作業を始める前に、現在の AI エージェントが Plan モードまたは Build モードのどちらで動作しているかを確認します。

これは OpenCode、Codex、Claude Code、Cursor、その他の互換エージェントに適用されます。モード名、メタデータ、権限はホストによって異なるため、普遍的な API を想定せず、使用中のホストが提供する標準的なシグナルを使います。

ホスト名とは別に、利用可能な機能を確認します。現在のエージェントが以下を実行できるか判断します。

構造化された質問をする
ファイルを読み取る
ファイルを編集する
コマンドを実行する
ブラウザーや外部ドキュメントにアクセスする
データベースやデプロイプラットフォームにアクセスする
読み取り専用の制限なしで操作する

実際に利用可能な機能だけを使用します。ホスト名が確認できても、特定のツールや権限が利用できるとは限りません。

次の優先順位で検出します。

現在のモードを示す明示的なシステム指示または開発者指示。
ホストが公開しているネイティブのモードメタデータ。
ファイル編集、シェル実行、実装ツールが許可されているか、またはセッションが読み取り専用かなどのツール権限。
計画のみを求める、またはアプリケーションの構築を求めるといった、ユーザーからの明示的な依頼。

信頼できるシグナルがない場合、モードを検出したと主張してはいけません。

Plan モード

エージェントが Plan モードの場合：

要件を確認し、重要な曖昧さを解消します。
ユーザーが求める PRD、技術仕様、実装計画を作成します。
読み取りアクセスが可能で、かつ関連性がある場合は、既存のプロジェクトファイルを確認します。
アプリケーションのファイルを編集したり、破壊的なコマンドを実行したり、実装を開始したりしてはいけません。
読み取り専用の制限を回避したり、ホストを Build モードに強制的に切り替えたりしてはいけません。
計画が完了したら、ユーザーが計画のみを求めている場合を除き、ホストのネイティブな対話型質問／選択肢ツールを使って、Build モードに切り替えて実装を続けるかユーザーに尋ねます。
ホストにネイティブのモード切り替えコントロールがある場合は、それを使うようユーザーに案内するか、使用を依頼します。チャットでの回答によってホストの実際の権限が変わったかのように装ってはいけません。

ビルドモード

エージェントがビルドモードの場合：

安全に実装できるよう、要件の把握と計画を十分に行います。
計画が完了したら、追加の確認を求めず、ただちに実装します。
コードの変更、必要に応じたマイグレーション、検証、関連するテストを行い、簡潔な完了報告を続けて提示します。
実装計画は作業の指針として使い、コーディング前に作業を止める理由として使ってはいけません。
重大な曖昧さ、外部の承認、シークレット、取り消せない操作、または利用できない依存関係によって安全に進められない場合にのみ、ユーザーに確認します。

PRD、仕様書、レビュー、または計画のみを作成するというユーザーの明示的な依頼は、自動実装より優先されます。ビルドの許可は実装を認めるものですが、ユーザーが指定した作業範囲を超えるものではありません。

不明モード

信頼できるモードの手がかりがなく、ユーザーの意図から望ましい成果が明確でない場合は、アクティブなエージェントの対話型質問ツールで、次の概念的な選択肢を提示します。

Question: What should happen after the specification is ready?
Options:
- Plan and build (Recommended) — generate the plan, then implement it.
- Plan only — stop after the PRD and implementation plan.

対話型質問ツールがない場合は、簡潔なテキストで同じ質問をします。システム指示でセッションがプランモードまたは読み取り専用と明示されている場合、シェルや編集ツールが使えることだけを根拠にビルドモードだと推測してはいけません。

指示の優先順位

指示が競合する場合は、次の順序で適用します。

システム指示およびホスト固有の制約
ユーザーが明示した作業範囲と制約
既存プロジェクトの慣例とアーキテクチャ
確認済みの要件
文書化された前提
このスキルのデフォルト

このスキルとはデフォルトが異なるという理由だけで、既存プロジェクトの技術スタックや慣例を置き換えてはいけません。

最優先ルール

ユーザーの依頼に不足がある場合、重要なビジネス要件や技術要件を暗黙に作り出してはいけません。

不足している情報によって次のいずれかが大きく変わる場合は、まずユーザーに確認してください。

アプリケーションの範囲
UI のみか、完全に機能するアプリケーションか
プラットフォーム
認証
ユーザーの役割
データベース
中核となるビジネスロジック
バックエンド
API
サードパーティとの連携
ファイルストレージ
セキュリティモデル
デプロイ先
デバイスのネイティブ機能
決済または金融フロー
機密性の高いユーザーデータ

実装上の細部については、妥当なデフォルトを選び、前提を文書化してください。

デフォルトの前提

ユーザーに希望が示されておらず、選択の不足がビジネス上の重大事項ではない場合に限り、次のデフォルトを使用してください。

デフォルトのアプリケーションプラットフォーム：Web ベースのアプリケーション
デフォルトの提供形態：完全に機能するアプリケーション
デフォルトの UI：レスポンシブ
デフォルトのアーキテクチャ：フルスタック
デフォルトのデータベース：PostgreSQL
デフォルトの認証：メールアドレスとパスワード
デフォルトの認可：複数のユーザー種別がある場合は、ロールベースアクセス制御
デフォルトの API 形式：REST API
デフォルトのデプロイ前提：最新のクラウド／VPS 環境へのデプロイ
デフォルトのセキュリティ基準：本番環境に適した一般的な Web セキュリティ対策
デフォルトのタイムゾーン処理：タイムスタンプを一貫した形式で保存し、アプリケーションの業務タイムゾーンを明示的に定義
デフォルトの技術スタック：アプリケーションの要件に最適なものを選択

ユーザーのデプロイ環境やアプリケーション要件から別の選択が適切と考えられる場合、デフォルトを機械的に適用してはいけません。

例：

共有ホスティングまたは cPanel を明示的に対象とする場合は、Laravel + MySQL がより適切なデフォルトとなることがあります。
最新の SaaS ダッシュボードが必要な場合は、Next.js + PostgreSQL がより適していることがあります。
マネージドバックエンドサービスを使った迅速な MVP が必要な場合は、Next.js + Supabase が適切なことがあります。
ネイティブモバイルアプリケーションが必要な場合は、適切なネイティブまたはクロスプラットフォームのモバイル技術スタックを推奨してください。

必須の初回確認

ユーザーの最初の依頼で次の質問に答えられない場合は、早い段階でこの 2 つの選択を尋ねてください。

1. アプリケーションの範囲

専門用語を使わずに尋ねます。

アプリは画面やプロトタイプのみを作成しますか？それとも、ログイン、データの保存、バックグラウンド処理なども含めて、実際に使える状態にしますか？

簡単な選択肢を提示します。

画面のみ — プロトタイプ、デモ、UI デザインに適しています。
完全に動作するアプリ — 必要に応じてデータベースやバックエンドを含め、機能が実際に動作します。
まだ決まっていない — アプリのアイデアに基づいて、最適な選択肢を提案します。

デフォルト：完全に動作するアプリ。

説明を添えずに「フロントエンド」または「フルスタック」という用語だけを使わないでください。

2. アプリケーションのプラットフォーム

次のように尋ねます。

アプリはウェブサイトとモバイルアプリのどちらとして作成しますか？

選択肢を提示します。

ウェブベース — ブラウザーから開き、ノートパソコンやスマートフォンに合わせて表示を調整できます。
モバイルアプリ — Android／iOS にインストールするアプリです。
まだ決まっていない — 最適なプラットフォームを提案します。

デフォルト：ウェブベース。

ユーザーがモバイルアプリを希望する場合は、次のどれを求めているか確認します。

Android のみ
iOS のみ
Android と iOS
ネイティブモバイルアプリ
クロスプラットフォームのモバイルアプリ

ユーザーがネイティブモバイルアプリを明示的に希望する場合は、その要件を尊重し、適切なネイティブスタックを提案します。

要件確認の原則

必須の対話型質問ツール

スキルがユーザーからの回答を必要とする場合は、質問を通常のチャットテキストとして書くのではなく、現在の AI エージェントが提供する対話型質問／選択ツールを使用する必要があります。

アクティブなエージェントまたはランタイムが提供するツールを使用します。たとえば、次のとおりです。

OpenCode：question
Codex：request_user_input または、そのランタイムで利用可能な同等の対話型入力ツール
Claude Code：AskUserQuestion
Cursor：利用可能な対話型質問、選択、またはユーザー入力ツール
その他のエージェント：ホストが提供する同等の構造化質問ツールまたは選択ツール

ツール名やスキーマはエージェントによって異なります。利用可能なツールを検出し、そのツール固有の形式に従ってください。他のエージェントのツール呼び出し形式を模倣しないでください。

構造化された質問では、次の点に従います。

ツールが対応している場合は、短く明確な見出しまたはラベルを付けます。
質問は、簡潔でわかりやすい言葉で書きます。
簡潔な選択肢のラベルと短い説明を提示します。
ツールがラベルや説明で対応している場合は、推奨する選択肢を先頭に置き、推奨であることを示します。
ツールが対応している場合は、自由記述や任意の回答を選べるようにします。
必要な機能や対応プラットフォームなど、複数の回答が有効な場合に限り、複数選択を有効にします。
UI のみか完全に動作するアプリかなど、相互に両立しない判断には単一選択を使います。
現在のラウンドの開始時点ですでにわかっている情報だけで回答できる質問に限り、まとめて提示します。
回答に依存する追加質問を、その回答を求める質問と同じツール呼び出しに含めないでください。
ツールで提示した質問を、文章でも繰り返さないでください。

アクティブなランタイムに対話型質問ツールが本当に用意されていない場合は、明確な選択肢を付けた簡潔な番号付きリストを代わりに提示します。この代替手段が許されるのは、必要なツールが利用できない場合に限ります。単なる利便性を理由に使ってはいけません。

回答が不要な場合、要件がすでに明確な場合、または細かな点に文書化されたデフォルトを安全に適用できる場合は、対話型質問ツールを使わないでください。

段階的な質問

一度に20個の質問をしないでください。

次のアーキテクチャ上の判断に進むために必要な、最小限の有用な質問だけを行います。

最初の依頼が曖昧な場合は、長大なフォームを一度に提示するのではなく、状況に応じて複数回に分けて確認します。

ラウンド 1 — 基盤

通常は、方向性を定める独立した質問を 2～3 件だけ尋ねます。

アプリケーションの範囲：UI／プロトタイプ、または完全に機能するアプリケーション
プラットフォーム：Web、モバイル、デスクトップ、API のみ、またはその他の適切な選択肢
推測できない場合の提供レベル：プロトタイプ、MVP、本番環境対応、またはエンタープライズ

これらの回答に左右される場合は、関連性が明らかになるまで、バックエンド、認証、ロール、ストレージ、連携、デプロイに関する詳細な質問はしないでください。

計画のチェックポイント

ラウンド 1 の回答を受け取った後：

要件の状態を更新します。
選択された方向性を、簡潔な 1～3 文で要約します。
その回答によって重要になったプロダクトまたはアーキテクチャ上の決定事項を特定します。
それらの依存関係に基づいて、次の質問を用意します。

このチェックポイントは、作業上の短い解釈であり、最終版の PRD ではありません。まだ完全な仕様書を作成しないでください。

例：

初期の方向性：業務利用を想定した、完全に機能する Web アプリケーションです。そのため、ユーザーアカウント、データの保存、アクセスルールが必要になる可能性があります。次に、ユーザーと主要なワークフローを明確にする必要があります。

ラウンド 2 — プロダクトの形

ラウンド 1 の回答に基づいて、適応的な質問を 2～5 件ほど尋ねます。一般的なトピック：

対象ユーザーとロール
主要なワークフローと P0 機能
アカウントとログインの動作
保存が必要なデータ
アプリケーション固有のビジネスルール

UI／プロトタイプが選択された場合、ラウンド 2 ではページ、インタラクション、モックデータ、ビジュアルの方向性、レスポンシブ対応の対象に重点を置きます。プロトタイプでバックエンドを表現する必要がない限り、バックエンドに関する質問はしないでください。

完全に機能するアプリケーションが選択された場合、アーキテクチャを確定する前に、通常は対象ユーザー、コアワークフロー、認証、ロール、永続化するデータを明確にします。

ラウンド 3 以降 — 条件に応じた詳細

回答を受け取るたびに要件の状態を更新し、重要な曖昧さが残っている場合に限って、次の短いラウンドを尋ねます。条件に応じて扱うトピックには、次のようなものがあります。

決済
GPS、カメラ、生体認証、またはデバイスへのネイティブアクセス
サードパーティ連携
ファイルストレージ
マルチテナンシー
機密データのライフサイクル
デプロイの制約
規模またはコンプライアンス要件

追加のラウンドに入る前に、何が分かったのか、なぜ次の決定事項が重要なのかを説明する、短い計画のチェックポイントを示します。

ラウンド数を固定しないでください。曖昧な依頼で、ラウンド 1 の回答から完全に機能するアプリケーションが選ばれた場合、通常は 2 ラウンドを最低限とします。ユーザーの最初の依頼に必要な詳細がすでに含まれている場合は、不要なラウンドを省略してください。

ユーザーの回答から、別の重要な曖昧さが明らかになった場合に限り、追加の質問をしてください。

複数の質問を扱えるツールだからという理由だけで、想定されるすべての質問をラウンド 1 で尋ねないでください。

初回の確認質問テンプレート

必要な場合は、現在のエージェントが利用できる対話型の質問／選択肢ツールを通じて、次のような基礎的な質問だけを送信します。

このアプリケーションは、見た目だけにしますか、それとも完全に機能するものにしますか？
Web サイトとモバイルアプリのどちらにしますか？まだ分からない場合は、デフォルトを Web サイトとします。
目標はプロトタイプ、MVP、本番環境対応のどれですか？期待される結果に大きく影響し、推測できない場合に限って尋ねます。

アプリケーションに合わせて質問を調整してください。関係のない質問はしないでください。

ユーザー、主要な操作、ログイン、ロール、永続化するデータ、技術に関する質問は、ユーザーがすでに基礎的な決定事項を示している場合を除き、ラウンド 2 以降で尋ねてください。

技術用語を使わない

次のように聞いてください。

アプリを再び開いたときにも利用できるように、ユーザーのデータや活動を保存する必要がありますか？

次のように聞くのではなく、

データベースを使いますか？

次のように聞いてください。

ユーザーごとに個別のアカウントが必要ですか？

次のように聞くのではなく、

認証は必要ですか？

次のように聞いてください。

たとえば管理者と従業員など、異なる種類のユーザーがいますか？

次のように聞くのではなく、

RBAC は必要ですか？

次のように聞いてください。

アプリは一般的なホスティングサービス／cPanel、VPS に設置しますか、それともまだ決まっていませんか？

次のように聞くのではなく、

デプロイ先はどこですか？

技術用語は、その意味を説明した後で使用できます。

「わかりません」への対応

ユーザーが技術的な質問を理解できないために、先へ進めなくなることがあってはなりません。

技術的な選択肢については、次のような回答を認めてください。

どれでもよい
お任せします
わかりません
おすすめしてください
選んでください

ユーザーがわからない場合は、最適な選択肢を選び、その理由を簡潔に説明してください。

例：

このようなアプリには PostgreSQL をおすすめします。データ同士が関連しており、一貫した構造が必要だからです。

ユーザーが理解していない技術の選択を、何度も求めないでください。

要件の状態モデル

重要な要件を、内部で次のように分類してください。

KNOWN
ASSUMED
UNKNOWN
NOT_REQUIRED

「勤怠管理アプリを作って」と依頼された場合の例：

Application Type: Attendance System — KNOWN
Application Scope: Full Functional — ASSUMED
Platform: Web — ASSUMED
Target Users: UNKNOWN
Authentication: ASSUMED_REQUIRED
Database: ASSUMED_REQUIRED
User Roles: UNKNOWN
Backend: ASSUMED_REQUIRED
Attendance Method: UNKNOWN
Location Validation: UNKNOWN
Deployment: UNKNOWN
Technology Stack: UNKNOWN

このモデルを使って、何を確認する必要があるかを判断してください。

ユーザーの理解に役立つ場合を除き、この内部状態を表示しないでください。

要件の充足度

次の概念的な尺度を使用してください。

0-30% — 要件が曖昧すぎるため、確認が必須です。
30-60% — 主要なプロダクト上およびアーキテクチャ上の決定事項を確認してください。
60-80% — 残っている重要な質問だけをいくつか尋ねてください。
80-100% — 仕様を作成し、細かな前提事項を記載してください。

形式的に 100% に到達することだけを目的に質問しないでください。

プロダクトの要件発見

次の事項を特定してください。

アプリケーションの概要

わかっている場合は、アプリケーション名
アプリケーションの種類
ビジネス上の目的
解決する課題
対象ユーザー

プラットフォーム

Web
モバイル
ネイティブモバイル
クロスプラットフォーム
デスクトップ
API のみ
マルチプラットフォーム

スコープ

UI／プロトタイプのみ
完全な機能を備えたもの
MVP
本番運用可能なシステム

プロジェクトの状況

依頼が次のどちらに当たるかを判断してください。

新規開発 — 既存のコードベースがない、新しいアプリケーション
既存プロジェクト — 既存のコードベース内で行う機能追加、再設計、移行、または修正

既存プロジェクトの場合、アーキテクチャや実装を提案する前に、利用可能なプロジェクトの情報を確認してください。

ディレクトリ構成とパッケージマニフェスト
フレームワーク、言語、ランタイムのバージョン
既存のデータベーススキーマとマイグレーション
認証と認可のパターン
API の規約
コーディング規約とエージェントへの指示
テストフレームワークとコマンド
デプロイと環境の設定

既存のパターンが要件と両立しない、安全でない、壊れている、またはユーザーが明示的に移行を依頼している場合を除き、それらのパターンを維持してください。変更を提案する場合は、その理由と影響を説明してください。

新規開発の場合は、確認済みの要件と明記した前提事項に基づいて、適切な範囲で最もシンプルなアーキテクチャを選んでください。

提供レベル

想定される提供レベルを分類してください。

プロトタイプ — UI と操作にはモックデータを使用できます。本番環境向けバックエンドを含むとは限りません。
MVP — 中核となるワークフローを完了できる、実用上最小限のプロダクトです。
本番運用可能 — 運用上のセキュリティ、テスト、デプロイ、監視、復旧の要件を含みます。
エンタープライズ — コンプライアンス、監査可能性、高可用性、正式な運用体制など、組織規模の管理機能が必要になる場合があります。

すべての完全な機能を備えたアプリの依頼を、エンタープライズソフトウェアとして扱わないでください。提供レベルによってスコープが大きく変わり、推測もできない場合は、対話型の質問ツールを使って尋ねてください。それ以外の場合は、妥当なレベルを選び、その判断を記載してください。

スコープの境界

最終版のPRDでは、必ず次の項目を区別します。

In Scope
Out of Scope / Non-Goals
Future Considerations

将来のアイデアや任意の推奨事項を、現在の実装スコープに暗黙のうちに含めないでください。Build モードでは、スコープ内であることが確認された作業のみを実装します。

規模と制約

規模やコストについては、アーキテクチャに影響する場合にのみ質問してください。関連する指標には次のものがあります。

想定ユーザー数と同時利用数
単一組織での運用か、マルチテナントでの運用か
データとファイルの容量
オフライン要件
ホスティング予算
地域的または規制上の制約

一般的な小規模アプリケーションについては、推測に基づくキャパシティプランニングを無理に行わせるのではなく、妥当で文書化された前提を使用してください。

ユーザーの種類

次の点を確認します。

誰がアプリケーションを使用するか
複数の役割があるか
各役割の権限

例：

管理者
従業員
教師
学生
顧客
ベンダー
オペレーター
所有者

機能の洗い出し

次の項目を特定します。

主要なワークフロー
コア機能
補助機能
管理機能
レポート要件
検索／フィルター要件
通知
ファイルのアップロード
エクスポート／インポート
外部連携
位置情報／GPS
カメラ
QR コード
決済
承認ワークフロー
監査証跡

明確な要件がない限り、コストや複雑さの大きい機能を自動的に追加しないでください。

任意の機能は、別途提案してもかまいません。

UI のみのモード

ユーザーが画面のみを選択した場合、データベース、バックエンド、認証サーバーのロジック、API の実装を無理に行わせないでください。

仕様では、次の項目に重点を置きます。

ページ
ナビゲーション
コンポーネント
レイアウト
レスポンシブ動作
モックデータ
インタラクションの状態
読み込み状態
空の状態
エラー状態
フォームの動作
UI のバリデーション
デザインの方向性

バックエンドに依存するインタラクションは、モックであることを明確に示してください。

例：

Login form:
- UI only
- Authentication is simulated
- No real credential validation

フル機能モード

ユーザーがフル機能を選択した場合、アプリケーションに次のものが必要かどうかを確認します。

データベース
バックエンド
認証
認可
API
ファイルストレージ
バックグラウンド処理
外部連携
デプロイ
ロギング
モニタリング
セキュリティ制御

データ駆動型のアプリケーションのほとんどでは、アプリケーションの性質から見て不要と判断できる場合を除き、バックエンドとデータベースが必要であると想定してください。

技術選定エンジン

すべてに同じ技術スタックを使用するのではなく、アプリケーションのニーズに基づいて技術スタックを推奨してください。

推奨する理由は、簡潔で分かりやすい言葉で説明してください。

推奨するデフォルトの技術スタック

モダンな Web アプリケーション／SaaS／ダッシュボード

推奨する出発点：

Frontend: Next.js
Language: TypeScript
Backend: Next.js server/API or dedicated Node.js service when needed
Database: PostgreSQL
ORM: Prisma or equivalent
Authentication: Auth.js or equivalent secure authentication solution
Validation: Zod or equivalent schema validation
Styling: Tailwind CSS

ユーザーに希望がなく、別の技術スタックを示唆するデプロイ上の制約もない場合に使用してください。

共有ホスティング／cPanel

推奨：

Backend: Laravel
Language: PHP
Frontend: Blade or suitable JavaScript frontend
Database: MySQL/MariaDB
Authentication: Laravel authentication

cPanel への容易なデプロイが重要な場合は、こちらを優先してください。

クイック MVP／マネージドバックエンド

推奨候補：

Frontend: Next.js
Language: TypeScript
Backend/Data Platform: Supabase
Database: PostgreSQL
Authentication: Supabase Auth
Storage: Supabase Storage when files are required

迅速な開発とインフラの複雑さの軽減が優先事項である場合に使用してください。

ネイティブ Android

推奨候補：

Language: Kotlin
UI: Jetpack Compose
Backend: API-based backend
Database: PostgreSQL/MySQL on server
Local Storage: Room when offline storage is needed

ネイティブ iOS

推奨候補：

Language: Swift
UI: SwiftUI
Backend: API-based backend
Database: PostgreSQL/MySQL on server
Local Storage: SwiftData/Core Data when needed

クロスプラットフォームモバイル

推奨候補：

Flutter + Dart

または

React Native + TypeScript

ユーザーのエコシステムと要件に基づいて選択してください。

ユーザーがネイティブ開発を明示的に求めている場合、クロスプラットフォームソリューションを「ネイティブ」と呼ばないでください。

データベースの選定

次の場合を除き、ユーザーにデータベースを選ばせないでください。

ユーザーがすでに各選択肢を理解している
インフラ上の制約がある
組織が特定のデータベースを必須としている
選択が連携またはデプロイに大きく影響する

それ以外の場合は、データベースを推奨してください。

一般的な推奨：

PostgreSQL — モダンな構造化アプリケーション、SaaS、リレーショナルな業務データ
MySQL/MariaDB — 共有ホスティング／cPanel、一般的な PHP エコシステム
SQLite — ローカルのプロトタイプやシンプルなシングルユーザーアプリケーション
マネージド PostgreSQL — MVP の迅速なデプロイ

アプリケーションに JSON 形式のデータが含まれているという理由だけで、デフォルトで NoSQL を使用しないでください。

バックエンドの要否

バックエンド機能が必要かどうかを判断します。

一般的なバックエンドの要件には、次のものがあります。

ユーザーアカウント
永続データ
権限
ビジネスルール
ファイルストレージ
決済
レポート
外部 API 連携
管理者向け操作

ユーザーが UI だけを求めている場合は、これらのシステムを実装せずにモックを使用します。

認証要件

アプリケーションに次のいずれかが含まれる場合は、必ず認証を検討します。

ユーザー固有のデータ
非公開データ
管理者向け機能
制限付き機能
保存された個人記録
ユーザーに紐づくデータの変更

一般的な Web アプリケーションでのデフォルトの認証方式：

メールアドレス＋パスワード
安全なパスワードハッシュ化
ログイン
ログアウト
セッション管理
パスワードを忘れた場合の手続き
パスワードのリセット
アカウント状態の検証

登録機能は、適切な場合にのみ含めます。

アプリケーションによっては、一般公開の登録ではなく、管理者がアカウントを作成する方式が適しています。

認可

複数のユーザー種別がある場合は、ロールベースのアクセス制御（RBAC）を定義します。

例：

Admin:
- Manage users
- View all records
- Manage configuration
- View reports

Employee:
- View own profile
- Create own attendance
- View own attendance history

認可はバックエンドで適用する必要があります。

フロントエンドでボタンを非表示にするだけでは、十分なアクセス制御になりません。

セキュリティの基本要件

機能を備えたすべてのアプリケーションには、セキュリティ要件のセクションを含める必要があります。

アーキテクチャに応じて、該当する対策を適用します。

認証セキュリティ

平文のパスワードを保存しない
Argon2、bcrypt、scrypt、または適切で安全なパスワードハッシュ化の実装を使用する
セッションまたはトークンを安全に管理する
セッションを期限切れにする
安全なログアウト
パスワードリセットトークンに有効期限を設ける
実用上可能な範囲で、ユーザーの特定を防ぐ

認可

サーバー側で権限を検証する
ロールベースまたはリソースベースの認可
管理者向けエンドポイントを保護する
レコードの所有権を検証する

入力検証

サーバー側での検証
スキーマ検証
長さの上限
型の検証
想定外の入力を拒否する
必要に応じてサニタイズする

データベースセキュリティ

ORM またはプリペアドステートメント
SQL インジェクション対策
データベース認証情報に最小権限の原則を適用する
データベース認証情報を環境変数に保存する

Web セキュリティ

次の項目を検討します。

HTTPS
セキュア Cookie
HttpOnly Cookie
SameSite Cookie ポリシー
該当する場合は CSRF 対策
XSS 対策
必要に応じた Content Security Policy
セキュリティヘッダー
CORS 設定
レート制限

API セキュリティ

認証ミドルウェア
認可ミドルウェア
入力検証
レート制限
一貫したエラー処理
本番環境で内部のスタックトレースを公開しない
機密情報の漏えいを避ける

シークレット管理

シークレットをハードコードしてはいけません。

環境変数または安全なシークレットマネージャーを使用してシークレットを保存します。

例：

DATABASE_URL
AUTH_SECRET
JWT_SECRET
SMTP_PASSWORD
THIRD_PARTY_API_KEY

例に実際の認証情報を含めてはいけません。

機能ごとのセキュリティ拡張

ファイルアップロード

該当する場合は、次の項目を含めます。

ファイル形式の検証
ファイルサイズの上限
安全なファイル名の生成
該当する場合は実行可能ファイルのアップロードを防止する
非公開ファイルには非公開ストレージを使用する
ファイルへのアクセスを認可する
リスクの高いユースケースでは、マルウェアスキャンを検討する

決済または金融データ

次の項目を検討します。

監査証跡
冪等性
厳格な認可
トランザクションの整合性
適切な場合は変更不可の金融履歴
準拠したプロバイダーとアーキテクチャを使用する場合を除き、機密性の高い決済カードデータを保存しない

管理者パネル

次の項目を含めます。

強固な認可
機密性の高い操作の監査ログ
管理者の操作履歴
権限昇格への対策

位置情報

次の項目を含めます。

ユーザー権限の処理
位置情報の検証
適切な精度
プライバシーへの配慮
機能に必要な範囲を超えて位置情報を収集しない

カメラ／生体認証

最終決定の前に、プライバシー、同意、保存、デバイスの権限に関する要件を明確にします。

ビジネスロジックのルール

ユーザーの発言を、明確なシステムルールに変換してください。

ユーザーの発言の例：

Karyawan cuma boleh absen sekali.

次のように変換します。

- A user may create only one check-in record per attendance date.
- Duplicate check-in requests must be rejected.
- The server, not the client, determines authoritative attendance timestamps.

例：

Admin sama pegawai beda.

次のように変換します。

Roles:
- ADMIN
- EMPLOYEE

ADMIN can manage employees and view all attendance records.
EMPLOYEE can only access their own attendance records.

API 設計

API を使用する完全な機能を備えたアプリケーションでは、API セクションを完全な形で作成してください。

以下を含めます。

HTTP メソッド
ルート
目的
認証要件
権限要件
リクエストパラメーター
リクエスト本文
レスポンス形式
重要なバリデーション
想定されるエラー

API の例

POST /api/attendance/check-in

目的：

本日のチェックイン記録を作成します。

認証：

必須です。

認可：

従業員アカウント。

リクエストの例：

{
  "latitude": -7.9666,
  "longitude": 112.6326
}

レスポンスの例：

{
  "success": true,
  "data": {
    "id": "att_123",
    "checkInAt": "2026-09-06T08:01:00+07:00",
    "status": "present"
  }
}

発生し得るエラー：

401 UNAUTHENTICATED
403 FORBIDDEN
409 ALREADY_CHECKED_IN
422 INVALID_LOCATION
429 RATE_LIMITED

API の命名ルール

別のスタイルが明らかに適している場合を除き、予測しやすい REST の規約を優先してください。

例：

POST   /api/auth/login
POST   /api/auth/logout
GET    /api/auth/me

GET    /api/users
POST   /api/users
GET    /api/users/:id
PATCH  /api/users/:id
DELETE /api/users/:id

CRUD に自然に対応しないアクションには、明示的なアクションエンドポイントを使用できます。

POST /api/attendance/check-in
POST /api/attendance/check-out
POST /api/leave-requests/:id/approve

API レスポンスの規約

一貫した形式を使用してください。

成功：

{
  "success": true,
  "data": {}
}

エラー：

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

機密性の高い実装の詳細を公開しないでください。

データベース仕様

完全な機能を備えたデータ駆動型アプリケーションでは、以下を作成してください。

テーブル／エンティティ
重要なフィールド
必要に応じたデータ型
主キー
外部キー
一意制約
インデックスの推奨事項
リレーションシップ
該当する場合は論理削除の要件
作成／更新のタイムスタンプ
ビジネス上の制約

例：

users
-----
id
name
email
password_hash
role
status
created_at
updated_at

attendance
----------
id
user_id
attendance_date
check_in_at
check_out_at
check_in_latitude
check_in_longitude
status
created_at
updated_at

リレーションシップ：

users 1 ---- N attendance

重要な制約についても説明してください。

例：

UNIQUE(user_id, attendance_date)

日次の出勤記録の重複を防ぐためです。

データのライフサイクルと運用

ユーザー、ビジネス、金融、医療、教育、人事、行政、その他の機密データを永続化するアプリケーションでは、関連するライフサイクルのルールを定義してください。

データの所有権
保持期間
アカウント削除時の動作
論理削除と物理削除の使い分け
エクスポート要件
バックアップの頻度と保持期間
復元の想定と復旧テスト
監査履歴
アーカイブまたは匿名化
ユーザーが特定した法的要件または規制要件

保持期間やコンプライアンスに関する主張を勝手に決めないでください。選択がビジネス上重要であれば確認し、それ以外の場合は未決定事項または文書化された前提として記載してください。

本番環境向けシステムでは、該当する場合、以下の運用要件を含めてください。

モニタリングとヘルスチェック
エラー通知
バックアップと復元の手順
マイグレーションとロールバックの戦略
インシデント対応に必要な監査ログ
根拠がある場合、または提示されている場合に限った復旧目標

フロントエンドのページとルート

フロントエンドのルート仕様を作成してください。

例：

/login
/dashboard
/attendance
/attendance/history
/profile

/admin
/admin/users
/admin/attendance
/admin/reports
/admin/settings

重要な各ルートについて、以下を含めます。

アクセスレベル
目的
主要なコンポーネント
主な操作
読み込み状態
空の状態
エラー状態

ルート一覧とアクセシビリティの検証

すべての Web アプリケーションまたは API について、対象範囲内のルートを漏れなく一覧にしてください。「アクセス可能」とは、関連する各アクターに対して各ルートが定義された結果を返すことを意味します。すべてのルートが全員に 200 を返す必要があるという意味ではありません。

実際のプロジェクトが利用できる場合は、以下からルートを特定してください。

ファイルベースのページおよび API ルート
ルーター設定
ネストされたレイアウトおよびルートグループ
動的ルートおよびキャッチオールルート
リダイレクトおよびコールバック
認証およびロール制限のあるルート
ナビゲーションリンク、メニュー、ボタン、プログラムによる画面遷移
ページに必要なサーバーアクション、ローダー、または API 依存関係

グリーンフィールドプロジェクトでは、実装前に確認済みの要件から一覧を導き出してください。既存のプロジェクトでは、文書化されたルートをソースコードと照合し、不一致を報告してください。

ルート契約

対象となるすべてのルートについて、次のフィールドを定義します。

フィールド	説明
ルート ID	`ROUTE-WEB-001` や `ROUTE-API-001` のような安定した ID
パス	静的パスまたは動的パターン
種別	ページ、API、リダイレクト、コールバック、Webhook、または内部アクション
アクセス	公開、認証済み、ロール固有、またはサービス認証
想定される結果	レンダリングされたページ、レスポンスステータス、リダイレクト、またはドメイン上の結果
テストデータ	必要なフィクスチャ、アカウント、パラメーター、またはリクエストボディ
ナビゲーション元	メニュー、リンク、ボタン、フロー、または意図的に直接アクセスのみ
検証	スモーク、認可、レンダリング、ナビゲーション、依存関係、または E2E テスト ID

例：

Route ID: ROUTE-WEB-003
Path: /admin/users
Type: Page
Access: ADMIN
Expected Results:
- ADMIN: 200 and users page renders
- EMPLOYEE: 403 or documented safe redirect
- Guest: redirect to /login
Navigation Source: admin sidebar
Verification: TEST-ROUTE-003, TEST-AUTHZ-004, TEST-NAV-002

必須の検証レイヤー

該当するすべてのレイヤーを適用します。

登録 — ルートが存在し、意図しない 404 が発生しないこと。
HTTP 結果 — ステータスまたはリダイレクトがルート契約と一致し、予期しない 500 が返されないこと。
認証 — 該当する場合、ゲスト、認証済み、セッション期限切れ、アカウント無効時の動作が正しいこと。
認可 — 関連する各ロールに、許可されたページ／結果、または想定される拒否が返されること。
レンダリング — ページが捕捉されない例外、ハイドレーションの失敗、空白画面なしにレンダリングされること。
ナビゲーション — ユーザー向けルートに、意図されたメニュー、リンク、ボタン、またはワークフローからアクセスできること。
依存関係 — ローダー、サーバーアクション、API、必要なデータがルートを壊さないこと。
動的パラメーター — 有効、無効、レコードなし、未認可のレコードの各ケースが正しく動作すること。
エラーバウンダリー — 想定される 403、404、バリデーションエラー、予期しないエラーの各状態が正しくレンダリングされること。
レスポンシブ環境でのアクセス — サポート対象のデスクトップおよびモバイルのレイアウトで、主要なナビゲーションが引き続き利用できること。

結果ラベルは一貫して使用します。

PASS — expected page, response, denial, or redirect observed
FAIL — route missing, wrong access result, unexpected 500, render crash, or broken navigation
NOT_RUN — verification could not run; include the concrete blocker
NOT_APPLICABLE — layer does not apply; include the reason when not obvious

ルートアクセスマトリックス

詳細かつ実装可能な出力を得るには、対象となるすべてのルートと関連するアクターを網羅するマトリックスを生成します。

ルート	ゲスト	認証済みユーザー	管理者	想定される結果	テスト ID	ステータス
`/login`	レンダリング	ダッシュボードにリダイレクト	ダッシュボードにリダイレクト	認証ループなし	`TEST-ROUTE-001`	計画済み
`/dashboard`	ログインにリダイレクト	自分のダッシュボードをレンダリング	ダッシュボードをレンダリング	保護されたルート	`TEST-ROUTE-002`	計画済み
`/admin/users`	ログインにリダイレクト	403	ユーザーをレンダリング	管理者専用	`TEST-ROUTE-003`	計画済み

アクター列は、実際のロールに合わせて調整します。API では、想定される HTTP ステータスとレスポンス契約を使用します。

ルートの例外

次のようなルートには、特別なセットアップや除外が必要な場合があります。

開発専用ルートまたはフレームワーク内部のルート
署名付き Webhook
プロバイダーの状態情報を必要とする OAuth コールバック
サードパーティパッケージのルート
削除予定の非推奨ルート

すべての例外、必要なフィクスチャ、代替の検証方法を文書化します。ルートを黙ってスキップしてはいけません。

ユーザーフロー

重要なエンドツーエンドのフローを説明します。

例：

Employee Login
↓
Dashboard
↓
Check In
↓
Validate location
↓
Validate duplicate attendance
↓
Save attendance
↓
Display confirmation

重要な場合は、代替フローやエラーフローも含めます。

機能の優先順位付け

機能を次のように分類します。

P0 — 必須
P1 — 重要
P2 — 任意

例：

優先度	機能
P0	ログイン
P0	出勤
P0	退勤
P0	勤怠履歴
P1	休暇申請
P1	レポート
P2	QR コードによる勤怠管理
P2	顔認識

任意のアイデアを自動的に必須の対象範囲へ昇格させないでください。

受け入れ基準

重要な P0 機能には、測定可能な受け入れ基準を設ける必要があります。

例：

Feature: Employee Check-in

Acceptance Criteria:
- User must be authenticated.
- User may check in only once per business day.
- Authoritative time must come from the server.
- Invalid location must be rejected when office radius validation is enabled.
- Successful check-in must be stored permanently.
- Duplicate check-in must return a clear error.

次のような曖昧な基準は避けてください。

機能が正しく動作すること。

要件のトレーサビリティ

詳細仕様または実装可能な仕様では、P0 要件に安定した ID を割り当てます。各要件を、その実装箇所および検証箇所に結び付けます。

例：

Requirement: REQ-ATT-001
Feature: Employee check-in
Priority: P0
Pages: /attendance
API: POST /api/attendance/check-in
Data: attendance
Business Rules: one check-in per employee per business day
Verification: TEST-ATT-API-001, TEST-ATT-E2E-001

引き継ぎの品質が向上する場合に、トレーサビリティを使用します。簡潔なプロトタイプに不要な ID を課さないでください。

検証マトリクス

すべての P0 機能について、完了をどのように証明するかを示してください。曖昧な説明より、観測可能な確認方法を優先してください。

例：

要件	検証
メールアドレスとパスワードによるログイン	有効な認証情報と無効な認証情報を検証する統合テスト
従業員が管理者 API にアクセスできない	認可テストで `403` が返される
1 日に 1 回のチェックイン	データベースの一意制約と重複リクエストに対する API テスト
GPS の半径制限	境界値のユニットテストと、許可範囲外での API テスト

Build モードでは、必要なツールと環境が利用可能な場合、記載されたチェックを実行してください。スキップしたチェックと、その具体的な理由を報告してください。

エッジケース

関連するエッジケースを常に検討してください。

例：

ユーザーが 2 回送信する
インターネット接続が遅く、リクエストが重複する
ユーザーが送信後にページを更新する
フォーム送信中にセッションが期限切れになる
無効化されたアカウントに古いセッションが残っている
ユーザーが他のユーザーのデータにアクセスしようとする
チェックインせずにチェックアウトする
レコードが深夜をまたぐ
タイムゾーンが異なる
必須フィールドが入力されていない
関連レコードが削除されている
サードパーティ API が利用できない
ファイルのアップロードが中断される
API リクエストがタイムアウトする
データベースのトランザクションが一部失敗する

製品に関連するエッジケースのみを含めてください。

エラー処理

該当する場合は、一般的な HTTP エラーを定義してください。

400 — Invalid request
401 — Authentication required
403 — Permission denied
404 — Resource not found
409 — Business rule conflict
422 — Validation failed
429 — Too many requests
500 — Unexpected server error

必要に応じて、ドメイン固有のエラーコードを含めてください。

例：

ALREADY_CHECKED_IN
INVALID_ATTENDANCE_LOCATION
ACCOUNT_DISABLED
LEAVE_ALREADY_APPROVED

非機能要件

関連する要件を評価し、記載してください。

パフォーマンス

次の項目を検討してください。

ページネーション
データベースインデックス
クエリの最適化
妥当な場合のキャッシュ
画像の最適化
遅延読み込み

レスポンシブデザイン

特にユーザーから指定がない限り、ウェブアプリケーションは次の環境で動作する必要があります。

デスクトップ
タブレット
モバイルブラウザー

アクセシビリティ

次の項目を検討してください。

セマンティック HTML
フォームラベル
キーボード操作
フォーカス状態
十分なコントラスト
スクリーンリーダーに対応したコンポーネント

信頼性

次の項目を含めてください。

読み込み状態
空の状態
必要に応じた再試行動作
エラー状態
トランザクション処理
重複リクエストの保護

ログ

次の項目を検討してください。

アプリケーションエラー
認証イベント
機密性の高い管理者操作
連携の失敗

パスワード、トークン、不要な機密データは記録しないでください。

UI 仕様

ユーザーからデザインの指示がない場合は、シンプルで実用的なデフォルトを推奨してください。

例：

Design:
- Modern
- Minimal
- Responsive
- Clear visual hierarchy
- Consistent spacing
- Accessible forms

必要でない限り、独自のブランドカラーを考案しないでください。

ダッシュボードでは、次の項目を決定してください。

ナビゲーションの種類
カード
テーブル
フィルター
検索
フォーム
確認ダイアログ
通知
空の状態
モバイルナビゲーション

テスト要件

機能が完全なアプリケーションには、適切なテスト計画を含めてください。

Build モードでの必須テスト駆動開発

Build モードで実装作業を行う場合、実行可能なテストツールが利用できる、または合理的に設定できるときは、必ず TDD を使用してください。既存のプロジェクトのテスト規約は、推奨ツールより優先されます。

次のサイクルに沿って、垂直スライスで作業します。

Select one observable behavior
Define the public seam
Write one failing test
Run it and confirm RED for the expected reason
Write the minimum implementation
Run it and confirm GREEN
Run the relevant regression tests
Continue with the next behavior
Review and refactor only after behavior is green

必須ルール：

グリーンの前にレッド。失敗する振る舞いテストを書く前に、本番実装を書いてはいけません。
1 サイクルにつき、小さな振る舞いを 1 つ、シームを 1 つにします。
プライベートメソッドや実装の詳細ではなく、公開インターフェースを通じてテストします。
期待値は、仕様、具体的な例、または別の独立した信頼できる情報源に基づく必要があります。
すべてのテストを先に書き、その後にすべての実装を行うことは避けてください。垂直のトレーサーバレットスライスを使います。
正しいテストを、誤った振る舞いを通すためだけに弱めたり書き換えたりしてはいけません。
テストコマンドを実行し、その結果を確認していない場合、RED または GREEN と報告してはいけません。
テストを実行できない場合は、NOT_RUN と記載し、具体的な阻害要因を説明してください。合格したと報告してはいけません。

デフォルトの公開シーム：

ユーザーのナビゲーションとレンダリングに対するブラウザーまたはページ境界
API に対する HTTP 境界
ビジネスルールに対する公開サービスまたは関数境界
制約とトランザクションに対するデータベース統合境界

シームの選択がアーキテクチャやテストコストに大きく影響する場合に限り、ユーザーに選択を依頼してください。それ以外の場合は、振る舞いを証明できる最も狭い公開シームを選択します。

テストツールがない機能的なプロジェクトでは、最初の機能を実装する前に、スタックに適合する最小限のテストハーネスを設定してください。具体的な理由がない限り、既存のテストスタックを置き換えてはいけません。

ルートの TDD シーケンス

ルートは、振る舞いの垂直スライスとして実装します。例：

Slice 1 — Guest opens /login
RED: route test expects the login form to render
GREEN: implement the login page

Slice 2 — Valid user submits login
RED: integration test expects authentication and dashboard redirect
GREEN: implement the minimum authentication flow

Slice 3 — Guest opens /dashboard
RED: route test expects redirect to /login
GREEN: add route protection

Slice 4 — Employee opens /admin/users
RED: authorization test expects 403 or the documented safe redirect
GREEN: enforce the ADMIN permission

各ルートスライスでは、現在失敗しているテストを満たすために必要な振る舞いのみを追加してください。

ユニットテスト

テスト対象：

バリデーション
ユーティリティ
ビジネスルール

API／統合テスト

テスト対象：

認証
認可
CRUD
ビジネスルール
データベースとのやり取り

エンドツーエンドテスト

重要なユーザーフローをテストします。

例：

login
→ check-in
→ check-out
→ view attendance history

否定的なケースも含めます。

例：

Employee requests admin-only endpoint
→ API must return 403

ルートのスモークテストとナビゲーションテスト

対象範囲内のすべてのルートについて、その契約に適したルートレベルの検証を少なくとも 1 つ実施する必要があります。すべてのルートに完全な E2E テストが必要なわけではありません。

次を使用します：

純粋なバリデーションとビジネスルールにはユニットテスト
認証、認可、データベースの動作、ミドルウェア、API、ローダー、サーバーアクションには統合テスト
登録と期待されるステータス／リダイレクトの動作にはルートのスモークテスト
レンダリング、ナビゲーション、レスポンシブメニュー、捕捉されないクライアントエラーにはブラウザーテスト
P0 のユーザージャーニーには E2E テスト

該当する場合、動的ルートには、代表的な有効、無効、レコードなし、権限のないレコードのケースを含める必要があります。

デプロイ要件

デプロイがアーキテクチャに大きく影響する場合、またはユーザーがインフラストラクチャについて言及した場合に限り、デプロイについて質問してください。

環境の例：

共有ホスティング／cPanel
VPS
Docker
クラウドプラットフォーム
マネージドプラットフォーム
App Store／Play Store
内部利用／ローカル利用

対象に基づいてデプロイ要件を生成します。

該当する場合は、次を含めます：

環境変数
ビルドプロセス
データベースのマイグレーション
ストレージ
ドメイン／HTTPS
リバースプロキシ
プロセスマネージャー
Docker
バックアップ戦略

環境変数

実際の認証情報を含めずに、必要な環境変数の一覧を生成します。

例：

APP_URL=
DATABASE_URL=
AUTH_SECRET=
SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASSWORD=
STORAGE_BUCKET=

選択したスタックで実際に必要な変数のみを含めます。

開発フェーズ

実装手順を生成します。

例：

Phase 1 — Project Setup
Phase 2 — Database Schema
Phase 3 — Authentication & Authorization
Phase 4 — Core Backend/API
Phase 5 — Core Frontend
Phase 6 — Admin Features
Phase 7 — Validation & Security
Phase 8 — Testing
Phase 9 — Deployment

アプリケーションに合わせてフェーズを調整します。

実装タスク

フェーズを、コーディングエージェントが実行できる具体的なタスクに分解します。

Build モードでは、機能タスクを横断的な一括作業ではなく、TDD サイクルとして構成します。

Vertical Slice
Failing Test and RED Command
Minimum Implementation
GREEN and Regression Commands
Route/Requirement Verification Update

すべてのテストを実装前に作成したり、ルートの検証前にすべてのページを実装したりするフェーズは作成しないでください。

例：

Phase 2 — Database

- Create users table
- Create attendance table
- Add role enum
- Add unique attendance-per-day constraint
- Add required indexes
- Create migrations
- Add development seed data

コーディングエージェントがほとんど迷わずに実行できるよう、タスクの詳細を十分に記述してください。

実装準備ゲート

Build モードで実装を始める前に、各項目について、把握済み、意図的に仮定、または不要のいずれかであることを確認してください。

プロジェクトの状況：グリーンフィールドか既存プロジェクトか
納品レベル
対象範囲内の P0 機能
対象範囲外の項目と目標外の事項
ユーザーの役割と権限
重要なビジネスルール
データモデルと整合性制約
API またはインテグレーションの契約
セキュリティ上重要なフロー
測定可能な受け入れ基準
検証方法
対象範囲内のルート一覧（完全版）
各ルートと関連する役割に対して想定されるアクセス結果
動的ルートと保護されたルートのフィクスチャ
文書化されたルートの例外
選定済みの公開テストシーム
特定済みのテストランナーと RED/GREEN コマンド
実装に影響するデプロイ制約
機密データまたは規制対象データのデータライフサイクルルール

項目が欠けていることで実装が危険になったり、誤った製品を作る可能性が高くなったりする場合は、標準の対話型質問ツールを使って、作業を妨げる最小限の質問をしてください。重大な阻害要因が残っていない場合は、ゲートを通過し、確認を追加で求めることなく、そのまま実装に進んでください。

人為的な完全性を要求したり、安全なデフォルトを設定できる通常の実装詳細によって作業を遅らせたりするために、このゲートを使わないでください。

完了の定義

プロジェクト全体に適用される完了の定義を含めてください。

例：

The project is considered complete when:

- All P0 features are implemented.
- Every in-scope page and API route is inventoried.
- Every route returns the expected page, status, denial, or redirect for each relevant actor.
- Internal navigation does not point to missing routes.
- Protected and role-restricted routes enforce access on the server where applicable.
- Dynamic routes cover valid, invalid, missing-record, and unauthorized-record behavior where applicable.
- P0 pages render without uncaught client errors on supported desktop and mobile navigation.
- Route exceptions and `NOT_RUN` checks are documented.
- Each new behavior was implemented through an observed RED/GREEN TDD cycle when test tooling was available.
- Authentication works correctly.
- Authorization is enforced server-side.
- Database migrations are available.
- Required API endpoints are implemented.
- Server-side validation exists.
- Major error states are handled.
- Security requirements are applied.
- Core flows have automated tests.
- Responsive UI works on supported devices.
- Environment variables are documented.
- Deployment instructions are documented.
- The application can be started using the provided README.

最終出力の構成

要件が十分に明確な場合は、次の構成で仕様を作成してください。

# Product Requirement Document

## 1. Project Overview
## 2. Problem Statement
## 3. Product Goals
## 4. Target Users
## 5. Application Scope
## 6. In Scope
## 7. Out of Scope / Non-Goals
## 8. Future Considerations
## 9. Platform
## 10. Delivery Level
## 11. User Roles & Permissions
## 12. Functional Requirements
## 13. Feature Priority
## 14. Requirement Traceability
## 15. User Flows
## 16. Pages & Navigation
## 17. Route Inventory
## 18. Route Access Matrix
## 19. Route Exceptions
## 20. UI Requirements
## 21. Technology Stack
## 22. System Architecture
## 23. Database Design
## 24. Data Lifecycle & Operations
## 25. API Specification
## 26. Authentication
## 27. Authorization
## 28. Security Requirements
## 29. Validation Rules
## 30. Error Handling
## 31. Edge Cases
## 32. Non-Functional Requirements
## 33. Testing Requirements
## 34. TDD Strategy & Test Seams
## 35. TDD Vertical Slices
## 36. Route Verification Matrix
## 37. Verification Matrix
## 38. Test Commands
## 39. Environment Variables
## 40. Deployment Requirements
## 41. Development Phases
## 42. Implementation Tasks
## 43. Acceptance Criteria
## 44. Definition of Done
## 45. Assumptions

該当しないセクションは省略してかまいません。

任意の複数ファイル出力

ユーザーが実装可能な仕様を求めている場合は、内容を概念上、次のように分けることができます。

PRD.md
TECHNICAL_SPEC.md
IMPLEMENTATION_PLAN.md

推奨される担当範囲：

PRD.md

以下を含みます。

製品の概要
課題
目標
ユーザー
役割
機能
優先度
ユーザーフロー
受け入れ基準

TECHNICAL_SPEC.md

以下を含みます。

スタック
アーキテクチャ
データベース
API
認証
認可
セキュリティ
バリデーション
エラー処理
環境変数
デプロイ

IMPLEMENTATION_PLAN.md

以下を含みます。

開発フェーズ
タスクの分解
依存関係
テストの順序
完了の定義

コーディングエージェントに役立つ場合は、コーディング規約と実装ルールを記載した AGENTS.md を提案してもかまいません。

質問終了条件

妥当な実装計画を立てるのに十分な情報が得られたら、質問を終了してください。

安全にデフォルトを使用できる細かな好みについて、質問を続けないでください。

最終的な PRD を作成する前に、次の項目が把握済み、意図的に仮定、または不要のいずれかであることを確認してください。

Application purpose
Project context: greenfield or existing project
Application scope
In-scope and out-of-scope boundaries
Delivery level
Platform
Target users
Core features
Authentication
User roles
Data persistence
Backend requirement
Technology stack
Critical integrations
Security-sensitive features
Deployment constraints
Data lifecycle requirements
Verification approach
Route inventory and expected access outcomes
Test seams and executable test commands

仮定に関するルール

仮定を使用する場合：

妥当なものにしてください。
明示してください。
重要な仮定は、最終出力の Assumptions セクションに記載してください。
後からユーザーが変更できるようにしてください。
製品を大幅に変える可能性のある、ビジネス上重要なルールを決して仮定しないでください。

例：

Assumption:
The application will be web-based because no platform preference was provided.

Assumption:
PostgreSQL will be used because the application contains relational business data and no deployment constraint requires MySQL.

対話例

ユーザー：

出席管理アプリを作ってください。

アシスタント：

アシスタントは、アクティブなエージェントの対話型質問ツールを呼び出します。概念上のペイロード：

Question: Aplikasinya ingin dibuat sampai tahap mana?
Options:
- Full functional (Recommended) — fitur berjalan dengan login, penyimpanan data, dan proses di belakangnya.
- Tampilan saja — prototype atau demo UI tanpa sistem nyata di belakangnya.
- Belum tahu — pilihkan berdasarkan kebutuhan aplikasi.

Question: Aplikasinya ingin digunakan melalui apa?
Options:
- Website (Recommended) — dibuka melalui browser dan responsive di laptop maupun HP.
- Mobile app — di-install di Android atau iOS.
- Belum tahu — pilihkan platform paling sesuai.

最初のツール呼び出しには、ユーザーの役割、ログイン、データ保存、出席方法、GPS のルールを含めないでください。これらの詳細は、スコープとプラットフォームに関する回答に依存するためです。

ユーザー：

すべての機能が必要です。Web だけでお願いします。

アシスタントの計画チェックポイント：

初期方針：すべての機能を備えたWeb出席管理アプリです。データ保存と、異なる権限を持つアカウントが必要になる可能性があります。次に、アーキテクチャを決める前に、ユーザーと出席のフローを明確にする必要があります。

その後、アシスタントは第2ラウンドのために対話型質問ツールを呼び出します：

Question: Siapa yang menggunakan aplikasi ini?
Options:
- Admin dan karyawan (Recommended) — admin mengelola sistem, karyawan melakukan absensi.
- Karyawan saja — tanpa panel administrasi khusus.
- Pengguna lain — jelaskan jenis pengguna yang dibutuhkan.

Question: Fitur utama apa yang diperlukan?
Options (multiple selection):
- Check-in dan check-out (Recommended) — catat waktu masuk dan pulang.
- Cuti atau izin — ajukan dan kelola ketidakhadiran.
- Laporan — lihat dan ekspor rekap absensi.
- GPS — gunakan lokasi saat absensi.

Question: Bagaimana akun pengguna dikelola?
Options:
- Login, akun dibuat admin (Recommended) — admin membuat akun karyawan.
- Login, pengguna daftar sendiri — pengguna dapat membuat akun.
- Tanpa login — data tidak dipisahkan berdasarkan akun.

ユーザー：

管理者と従業員です。出勤、退勤、休暇、レポート、GPS が必要です。ログイン機能があり、アカウントは管理者が作成します。

アシスタントは、重要な要件が十分に明確かどうかを分析します。

アシスタントの計画チェックポイント：

主な構成は明確になりました。管理者はアカウントとレポートを管理し、従業員は出席を記録し、休暇を申請します。GPS が選択されたため、最終仕様を作成する前に、位置情報の検証ルールを確認する必要があります。

第3ラウンドで追加質問する場合：

焦点を絞った条件付きの質問を使って、対話型質問ツールを再度呼び出します：

Question: Bagaimana GPS digunakan saat absensi?
Options:
- Batasi radius kantor (Recommended) — absensi hanya diterima di dalam radius yang ditentukan.
- Catat lokasi saja — lokasi disimpan tanpa membatasi absensi.
- Tanpa GPS — hapus pemeriksaan lokasi.

回答を得たら、要件の状態を更新します。重要な曖昧さがなくなったら完全な仕様を作成し、残っている場合は、もう一度だけ簡潔な適応型質問を行います。

技術翻訳の例

ユーザーの発言：

通常のログインでお願いします。

次のように翻訳します：

Authentication:
- Email/password login
- Secure password hashing
- Session management
- Logout
- Forgot password
- Reset password

ユーザーの発言：

管理者と従業員は別です。

次のように翻訳します：

Roles:
ADMIN
EMPLOYEE

Authorization:
ADMIN can manage employees and view organization-wide records.
EMPLOYEE can only access permitted employee features and their own records.

ユーザーの発言：

オフィスで出席を記録する必要があります。

適用方法を推測しないでください。

アクティブなエージェントの対話型質問ツールを通じて質問します：

Question: Bagaimana sistem memastikan pengguna absen di kantor?
Options:
- Periksa radius GPS (Recommended) — absensi hanya diizinkan saat pengguna berada dalam radius kantor.
- Catat GPS saja — lokasi direkam, tetapi tidak memblokir absensi.
- Cara lain — pengguna menjelaskan aturan sendiri.

確認できた場合は、具体的なビジネスルールに翻訳します。

アーキテクチャの決定原則

要件を完全に満たす、最もシンプルなアーキテクチャを優先します。

次のことは行わないでください：

シンプルな CRUD アプリケーションにマイクロサービスを導入する
明確な理由なく Redis を追加する
通常の同期ワークフローに Kafka やキューを追加する
シンプルなデプロイに Kubernetes を追加する
モダンであるという理由だけで GraphQL を追加する
データモデル上の理由なく NoSQL を追加する
モノリシックなフルスタックアプリケーションで十分な場合に、バックエンドサービスを分割する

次の点を重視します：

保守性
セキュリティ
シンプルさ
デプロイとの互換性
開発者の生産性
明確な責務の分離

コーディングエージェントへの引き継ぎ品質

最終仕様を読めば、コーディングエージェントが次のことを理解できるようにします：

何を構築する必要があるか
何を構築してはならないか
誰が何をできるか
どのようなデータが存在するか
データがどのように関連するか
どのページが存在するか
どの API が存在するか
各 API が何を受け取り、何を返すか
どのビジネスルールを適用する必要があるか
認証の仕組み
認可の仕組み
必要なセキュリティ対策
対応する必要があるエッジケース
合格すべきテスト
実装を進める順序
完了の判断基準

次のような曖昧な表現は避けてください：

Create a nice dashboard.
Add secure authentication.
Build CRUD.
Make it responsive.

測定可能な仕様に置き換えてください。

最終的な動作ルール

必ず次のことを行ってください。

ユーザーがインドネシア語で話しかけた場合は、わかりやすいインドネシア語を使います。
明示的に別の言語を求められない限り、ユーザーの言語に合わせます。
本格的な作業を始める前に、アクティブなエージェントのプランモードまたはビルドモードを検出し、それに従います。
エージェントの製品名だけに頼らず、実際のホスト機能を検出します。
正当な理由がない限り、既存のプロジェクト規約を維持します。
ビルドモードが有効で、ユーザーが動作するアプリケーションを求めている場合は、計画から実装へ直接進みます。
プランモードでは計画の作成後に停止し、実装を希望する場合はホストのネイティブなフローを使ってビルドモードへの切り替えを求めます。
重要な要件が不足している場合は、確認を求めます。
ユーザーの回答が必要な質問には、アクティブなエージェントの対話型質問・選択肢ツールを使います。
曖昧な依頼には段階的な複数回の確認を行います。まず基礎事項を確認し、計画のチェックポイントを設け、その後、回答に応じた追加の確認を行います。
OpenCode、Codex、Claude Code、Cursor、または現在のホストに固有のツールスキーマに従い、汎用の形式を仮定しません。
技術的な選択について、専門知識のない人にもわかる言葉で説明します。
初心者に技術的な決定を強いるのではなく、推奨する初期設定を提示します。
ユーザーが明示的に指定しない限り、ウェブベースのアプリケーションを初期設定とします。
ユーザーが UI またはプロトタイプのみを明確に求めている場合を除き、完全に機能するアプリケーションを初期設定とします。
実際のプロジェクトに基づいて技術スタックを推奨します。
プライベート機能またはユーザー固有の機能で必要となる場合は、認証を含めます。
複数のロールがある場合は、認可を含めます。
完全に機能するアプリケーションには、必ずセキュリティ要件を含めます。
構造化された永続データが必要な場合は、データベース設計を含めます。
バックエンド機能がある場合は、API およびバックエンドのルートを含めます。
バリデーションとエラー処理を含めます。
関連するエッジケースを含めます。
コア機能の受け入れ基準を含めます。
テスト要件を含めます。
該当する登録、アクセス、認可、レンダリング、ナビゲーション、依存関係、動的パラメーター、エラー、およびレスポンシブの各レイヤーにわたり、対象範囲内のすべてのルートを洗い出し、検証します。
想定される拒否やリダイレクトは有効なルートの結果として扱い、すべての利用者に 200 が返ることを求めません。
ビルドモードでの実装作業では、テストツールを利用できる場合、または合理的に設定できる場合、観測可能な RED/GREEN の TDD サイクルに従います。
開発フェーズと、実行可能な実装タスクを含めます。
対象範囲、対象外の非目標、および今後の検討事項を定義します。
ビルドモードでのコーディング前に、実装準備ゲートを適用します。
仕様が詳細であるかエージェント向けに準備されている場合は、P0 要件を実装および検証まで追跡します。
P0 機能の検証マトリクスを含めます。
関連するデータのライフサイクルと運用要件を定義します。
重要な前提を文書化します。

次のことは決して行わないでください。

初心者を不要な専門用語で圧倒しません。
プランモード、読み取り専用の制限、承認ゲート、またはホスト固有の権限を回避しません。
ビルドモードで実装を求められており、障害となるものがないのに、計画を提示しただけで停止しません。
すべてのルートを洗い出し、検証結果を記録することなく、すべてのルートにアクセスできると主張しません。
該当するコマンドを正常に実行していないのに、RED、GREEN、またはテスト合格を主張しません。
安全な推奨ができるのに、理解していない技術をユーザーに選ばせません。
重要なビジネスルールを、明示せずに作り上げません。
フロントエンドでボタンを隠すことを認可として扱いません。
パスワードを平文で保存しません。
シークレットをハードコードしません。
内部の機微なエラー情報を公開しません。
実際の製品を理解する前に、巨大な PRD を作成しません。
単純なアプリケーションを過剰に設計しません。
ユーザーが求めていないのに、ネイティブのモバイルアプリケーションを前提としません。
プロトタイプを完全に機能するものだと主張しません。

Markdown 対応

ログインしてコメント

基本情報

作者: adytm404
リポジトリ: adytm404/skills
カテゴリ: 開発
インストール数: 53
GitHub スター: 2

問題を報告