Kiro でテスト駆動開発（TDD）：こうあるべき体験

待ってください！ あなたは今コードを書こうとしています。TDD に従い、まずテストを書いてください。

必要なアクション:
1. これがテストファイル（*test*.py、*.spec.* など）の場合 — 続行する
2. これが例外（設定ファイル、ドキュメント、.kiro/）の場合 — 続行する
3. 対応するテストファイルが存在し、かつ実行した結果すべてのテストが失敗（RED フェーズ）していることが確認できている場合 — 続行する
4. それ以外の場合 — 中断し、まずテストファイルを書く:
   a. test_<filename>.py（または同等のもの）を作成する
   b. （単なる import ではなく）実際のアサーションで失敗するテストを書く
   c. テストを実行し、すべてがアサーションエラーで失敗することを確認する
   d. その後、戻ってこの実装を書く

TDD サイクル:
- RED: まず失敗するテストを書く（新しいテストはすべてアサーションで失敗しなければならない）
- GREEN: テストをパスさせる最小限のコードを書く
- REFACTOR: テストが green のままになるようにしつつコードを整理する

RED フェーズの要件:
- すべてのテストは AssertionError またはテスト失敗で失敗しなければならない
- RED フェーズでいずれかのテストがパスする場合、そのテストは弱い／中身がない
- RED フェーズでテストがパスするのは、空のループ、アサーションの欠落、テスト内のロジックエラーを意味する

正しい RED フェーズ: すべてのテストが AssertionError で失敗している
不正な RED フェーズ: 一部のテストがパスする、ImportError、ModuleNotFoundError、構文エラー

例外（テストなしで続行してよいもの）:
- テストファイル: *test*.py、*.spec.*、*.test.*、test_*.py、*_test.go
- 設定: package.json、tsconfig.json、.eslintrc、webpack.config.js、vite.config.ts、jest.config.js、pytest.ini、setup.py、pyproject.toml、requirements.txt、Dockerfile、docker-compose.yml、.env、.gitignore
- .kiro/ ディレクトリ内のファイル
- 型定義: .d.ts ファイル、Protocol クラス
- ドキュメント: .md、.txt、.rst、LICENSE、README、CHANGELOG
- データファイル: .json、.yaml、.yml、.xml、.csv、.sql、.html、.css、.scss（ロジックを含まないもの）
- ビルド成果物: dist/、build/、__pycache__/、*.pyc、node_modules/

先にテストを必要とするもの:
- 関数／クラスを含む Python ファイル（テストパターンに一致しない .py）
- ロジックを含む JavaScript／TypeScript（テストパターンに一致しない .js、.ts、.jsx、.tsx）
- 実行可能なロジックを含むすべてのソースコード（Go、Java、C#、Ruby など）

重要な確認: テストを実行し、すべてのテストが失敗したことを確認しましたか？ スタブ実装でいずれかのテストがパスした場合は、まずテストを修正してください。すべてのテストが失敗する適切な RED フェーズが得られたときにのみ続行してください。

# 要件ドキュメント

## はじめに

タスク管理システム用の REST API です。この API は、永続化のための
リレーショナルデータベースまたは組み込みデータベース（PostgreSQL や
SQLite など）を備えた Python の Web フレームワーク（Flask や
FastAPI など）を使って構築します。アプリケーションは Docker コンテナ
としてパッケージ化されるため、コンテナをサポートする任意の
プラットフォームにデプロイできます。この API はオープン（認証・認可
なし）です。タスクに対する完全な CRUD 操作をサポートし、クライアントが
タスクを作成・読み取り・更新・削除できるようにします。フロントエンドは
ありません。これは API のみのサービスです。

## 用語集

- **API_Server**: HTTP リクエストを受け取り、適切なリクエスト
  ハンドラーへルーティングする Python の Web フレームワーク
  アプリケーション（Flask や FastAPI など）
- **Task_Service**: タスク関連のビジネスロジックの処理を担う、
  コンテナ内で動作するアプリケーションロジック
- **Task**: 一意の識別子、タイトル、説明、ステータス、
  タイムスタンプといったプロパティを持つ作業単位
- **Task_Store**: タスクが格納・取得されるリレーショナル
  データベースまたは組み込みデータベース（PostgreSQL や SQLite など）
- **Client**: API に HTTP リクエストを送信する外部システム
  またはユーザー
- **Dockerfile**: アプリケーションとその依存関係をポータブルな
  Docker イメージにパッケージ化する、コンテナのビルド定義
- **Container**: API_Server と Task_Service をホストする、
  Docker イメージの実行中インスタンス
- **Standard_Error_Format**: すべての API エラーレスポンスで
  使われる一貫した JSON エラーレスポンス構造。
  `{"error": "<説明的なメッセージ>"}` の形式

## 要件

### 要件 1: タスクの作成

**ユーザーストーリー:** クライアントとして、API を通じて
新しいタスクを作成したい。作業項目を追跡できるようにするためである。

#### 受け入れ基準

1. WHEN クライアントが title と description の両方を含む有効な
   リクエストボディとともに `/tasks` へ POST リクエストを送信する、
   THE Task_Service SHALL Task_Store に新しい Task を作成し、
   一意の識別子を持つ作成済みの Task を HTTP ステータス 201 とともに返す
2. WHEN クライアントが必須フィールド（title または description）が
   欠落したリクエストボディとともに `/tasks` へ POST リクエストを
   送信する、THE Task_Service SHALL Standard_Error_Format の
   エラーメッセージとともに HTTP 400 レスポンスを返す
3. THE Task_Service SHALL 新しく作成された各 Task に、一意の識別子、
   `createdAt` タイムスタンプ、`updatedAt` タイムスタンプを割り当てる
4. THE Task_Service SHALL 新しい Task の初期ステータスを
   "pending" に設定する

### 要件 2: 単一タスクの取得

**ユーザーストーリー:** クライアントとして、識別子を指定して
特定のタスクを取得したい。その詳細を閲覧できるようにするためである。

#### 受け入れ基準

1. WHEN クライアントが有効なタスク識別子とともに
   `/tasks/{taskId}` へ GET リクエストを送信する、
   THE Task_Service SHALL 一致する Task を HTTP ステータス 200
   とともに返す
2. WHEN クライアントが Task_Store に存在しないタスク識別子とともに
   `/tasks/{taskId}` へ GET リクエストを送信する、
   THE Task_Service SHALL Standard_Error_Format の
   エラーメッセージとともに HTTP 404 レスポンスを返す

### 要件 3: 全タスクの一覧取得

**ユーザーストーリー:** クライアントとして、すべてのタスクを
一覧表示したい。追跡中の全作業項目の概要を確認できるように
するためである。

#### 受け入れ基準

1. WHEN クライアントが `/tasks` へ GET リクエストを送信する、
   THE Task_Service SHALL Task_Store のすべての Task のリストを
   HTTP ステータス 200 とともに返す
2. WHEN Task_Store に Task が 1 つも存在しない、
   THE Task_Service SHALL 空のリストを HTTP ステータス 200 とともに返す

### 要件 4: タスクの更新

**ユーザーストーリー:** クライアントとして、全体を置き換える形で
既存のタスクを更新したい。タイトル、説明、ステータスを変更できるように
するためである。

#### 受け入れ基準

1. WHEN クライアントが有効なタスク識別子と、すべての必須フィールド
   （title、description、status）を含むリクエストボディとともに
   `/tasks/{taskId}` へ PUT リクエストを送信する、
   THE Task_Service SHALL Task_Store 内の一致する Task を完全に
   置き換え、更新後の Task を HTTP ステータス 200 とともに返す
2. WHEN クライアントが Task_Store に存在しないタスク識別子とともに
   `/tasks/{taskId}` へ PUT リクエストを送信する、
   THE Task_Service SHALL Standard_Error_Format の
   エラーメッセージとともに HTTP 404 レスポンスを返す
3. WHEN クライアントが必須フィールド（title、description、status）
   のいずれかが欠落したリクエストボディとともに `/tasks/{taskId}` へ
   PUT リクエストを送信する、THE Task_Service SHALL
   Standard_Error_Format のエラーメッセージとともに HTTP 400
   レスポンスを返す
4. THE Task_Service SHALL Task が変更されるたびに `updatedAt`
   タイムスタンプを更新する

### 要件 5: タスクの削除

**ユーザーストーリー:** クライアントとして、タスクを削除したい。
不要になった作業項目を完全に除去できるようにするためである。

#### 受け入れ基準

1. WHEN クライアントが有効なタスク識別子とともに
   `/tasks/{taskId}` へ DELETE リクエストを送信する、
   THE Task_Service SHALL Task_Store から Task を完全に削除し、
   HTTP ステータス 204 を返す
2. WHEN クライアントが Task_Store に存在しないタスク識別子とともに
   `/tasks/{taskId}` へ DELETE リクエストを送信する、
   THE Task_Service SHALL Standard_Error_Format の
   エラーメッセージとともに HTTP 404 レスポンスを返す

### 要件 6: リクエストの検証

**ユーザーストーリー:** クライアントとして、不正なリクエストに
対して明確なエラーレスポンスがほしい。API 呼び出しの問題を
修正できるようにするためである。

#### 受け入れ基準

1. WHEN クライアントが無効な JSON ボディを含むリクエストを送信する、
   THE API_Server SHALL Standard_Error_Format の
   エラーメッセージとともに HTTP 400 レスポンスを返す
2. WHEN クライアントが未定義のルートへリクエストを送信する、
   THE API_Server SHALL HTTP 404 レスポンスを返す
3. WHEN クライアントが定義済みのルートに対してサポートされていない
   HTTP メソッドを使ってリクエストを送信する、THE API_Server SHALL
   HTTP 405 レスポンスを返す

### 要件 7: 入力長の検証

**ユーザーストーリー:** クライアントとして、API に妥当な入力長を
強制してほしい。過度に大きな入力が拒否されるようにするためである。

#### 受け入れ基準

1. WHEN クライアントが 100 文字を超える `title` フィールドを含む
   リクエストを送信する、THE Task_Service SHALL title が長すぎる
   ことを示す Standard_Error_Format のエラーメッセージとともに
   HTTP 400 レスポンスを返す
2. WHEN クライアントが 1000 文字を超える `description` フィールドを
   含むリクエストを送信する、THE Task_Service SHALL description が
   長すぎることを示す Standard_Error_Format のエラーメッセージと
   ともに HTTP 400 レスポンスを返す
3. THE Task_Service SHALL 作成（POST）操作と更新（PUT）操作の
   両方で入力フィールドの長さを検証する

### 要件 8: タスクのデータモデル

**ユーザーストーリー:** クライアントとして、一貫したタスクの
データ構造がほしい。API レスポンスを確実にパースできるように
するためである。

#### 受け入れ基準

1. THE Task_Service SHALL 各 Task を次のフィールドを持つ JSON
   オブジェクトとして表現する: `id`（string）、`title`（string）、
   `description`（string）、`status`（string）、
   `createdAt`（ISO 8601 タイムスタンプ）、
   `updatedAt`（ISO 8601 タイムスタンプ）
2. THE Task_Service SHALL Task の status フィールドとして次の値を
   受け入れる: "pending"、"in-progress"、"completed"
3. IF クライアントが受け入れ可能な集合に含まれない status 値を
   指定する、THEN THE Task_Service SHALL Standard_Error_Format の
   エラーメッセージとともに HTTP 400 レスポンスを返す

### 要件 9: JSON シリアライズのラウンドトリップ

**ユーザーストーリー:** クライアントとして、シリアライズと
デシリアライズを通じて API がタスクデータを忠実に保持してほしい。
データが失われたり破損したりしないようにするためである。

#### 受け入れ基準

1. FOR ALL 有効な Task オブジェクトについて、Task を JSON へ
   シリアライズし、その JSON を再び Task へデシリアライズすると、
   同等の Task オブジェクトが得られる SHALL（ラウンドトリップ特性）
2. THE Task_Service SHALL すべてのリクエストボディとレスポンス
   ボディの唯一のデータ交換形式として JSON を使用する
3. THE Task_Service SHALL すべてのレスポンスに
   `Content-Type: application/json` ヘッダーを含める

### 要件 10: 標準エラーレスポンス形式

**ユーザーストーリー:** クライアントとして、すべてのエラー
レスポンスが一貫した JSON 構造に従ってほしい。エラーを確実に
パースして処理できるようにするためである。

#### 受け入れ基準

1. THE Task_Service SHALL すべてのエラーレスポンスを
   Standard_Error_Format で返す: `{"error": "<説明的なメッセージ>"}`
2. THE Task_Service SHALL すべてのエラーレスポンスに
   `Content-Type: application/json` ヘッダーを含める
3. THE Task_Service SHALL 各エラーレスポンスの `error` フィールドに
   人間が読めるエラーの説明を提供する

### 要件 11: コンテナの構成

**ユーザーストーリー:** 開発者として、妥当なデフォルト値を備えた
Docker コンテナとしてアプリケーションをパッケージ化したい。
システムがポータブルで、任意のプラットフォームに簡単にデプロイ
できるようにするためである。

#### 受け入れ基準

1. THE Dockerfile SHALL API_Server と Task_Service を、必要なすべての
   依存関係とともに単一の Docker イメージにパッケージ化する
2. THE Dockerfile SHALL イメージサイズを最小化するため軽量な
   Python ベースイメージを使用する
3. THE Container SHALL API_Server が HTTP リクエストを受け付けるための
   設定可能なポート（デフォルトは 8000）を公開する
4. THE Container SHALL データベース接続設定とサーバーポートについて、
   環境変数による構成をサポートする
5. THE Dockerfile SHALL API_Server が稼働しているときに HTTP
   ステータス 200 を返すヘルスチェックエンドポイントを `/health` に含める

### 要件 12: データベースの移植性

**ユーザーストーリー:** 開発者として、アプリケーションに標準的な
リレーショナルデータベースを使ってほしい。デプロイ環境に合った
データベースバックエンドを選べるようにするためである。

#### 受け入れ基準

1. THE Task_Service SHALL SQL ベースのデータベースアクセスを使用し、
   Task_Store を SQLite、PostgreSQL、その他の SQL 互換データベースで
   支えられるようにする
2. THE Task_Service SHALL 外部データベース接続が構成されていない場合、
   Task_Store としてデフォルトで SQLite を使用する
3. WHEN 環境変数を通じて外部データベース接続文字列が提供される、
   THE Task_Service SHALL Task_Store として指定されたデータベースに
   接続する
4. THE Task_Service SHALL 起動時にテーブルが存在しない場合、必要な
   データベーステーブルを自動的に作成する