Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Task Detail Document Creation Guide

本ガイドは、各ソフトウェアコンポーネント配下の backlog/tasks/ ディレクトリにフラットに作成する実装タスク詳細ファイル（<SPEC-I-ID>.md）の記述内容とMarkdownテンプレートを定義するものです。

Rules & Section Guidelines

1. ディレクトリ配置・ID命名・作成ルール

  • 1:1:1 の原則: Incremental Specification と実装計画、タスク詳細ファイルは必ず 1:1:1 の関係 となります。タスク詳細ファイルは incremental specification に対して必ず 1 つ作成されます。
  • 配置ディレクトリ: <component>/backlog/tasks/ 配下にフラットに配置・管理します（ディレクトリによる階層化は行いません）。
  • ファイル名 / ID: 対応する増分仕様 ID と同一の <SPEC-I-ID>.md（例: SPEC-I-001.md）とします。
  • 作成起点: すべてのタスク詳細は Incremental Spec（SPEC-I）に紐づく実装計画（Plan）から作成されます（ISSUE から直接作成することは禁止）。
  • タスク詳細の種別:
    • Incremental 型: 計画分割のない通常タスク詳細。単一の作業・受入条件・検証手順で完結します。
    • Track 型: 計画分割がある場合。タスク詳細ファイルの中に Track 階層（## Track 1: ..., ## Track 2: ... 等）を設けて管理 します。
  • ケース別運用ルール:
    • 新規機能・契約変更: 新規増分仕様に基づきタスク詳細を新規作成します。
    • 契約不変の軽微修正（1ファイル10行以下）: 契約不変の仕様修正・不具合修正・脆弱性修正・リファクタリング・パフォーマンス改善で、1ファイル10行以下の場合は実装計画を作成せず直接作業し、完了後に本ファイルの「## 実装メモ」に作業内容・修正理由を追記・記録します。
    • 契約不変の通常修正（複数ファイルまたは11行以上）: 本ファイルを WIP ステータス に戻し、作業内容を反映して実装します。このとき実装計画など上位のステータスは変更しません。

2. フロントマターとステータス管理

  • 標準項目（name, description, timestamp, ai）に加え、status, reason, review キーを記述。
  • ステータス値（status）、理由種別（reason）、レビューメタデータ（review）、ライフサイクル遷移、および台帳同期ルールについては、document-status-guide.md を参照してください。

3. 必須セクション構成

  1. 概要: タスク全体の概要。
  2. 目的: タスクの目的・達成ゴール。
  3. 実装内容: 作業項目全体に対する実装方針・内容概要。
  4. 作業: 個別の作業項目を WI-<no>（例: WI-1, WI-2）形式で定義。
  5. Acceptance Criteria: 受入条件を AC-<no>（例: AC-1, AC-2）形式で定義し、チェックリスト項目（- [ ]）として記述。
  6. Verification: 各 AC-<no> に対応する具体的な検証内容・手順・方法を記述。
  7. 実装メモ: 作業時のメモや、1ファイル10行以下の軽微な修正内容・履歴を記録（任意・追記用）。

Template

以下はタスク詳細ファイル（Incremental型: SPEC-I-001.md）を作成する際の標準Markdownテンプレートです。

---
name: SPEC-I-001.md
description: <タスクの1行概要>
timestamp: YYYY-MM-DD
ai: ai-coauthored
status: DRAFT # DRAFT | REVIEW:DRAFT | TODO | WIP | REVIEW:WIP | DONE | CLOSE
reason: feature # feature | defect | security | spec-change | investigation | performance | refactor | ops
review:
  result: "" # ACCEPTED | REJECTED
  timestamp: "" # YYYY-MM-DD
  reason: "" # REJECTED時の1行理由サマリー
---

# Task: SPEC-I-001

## 概要

<タスク全体の概要を記述します。>

## 目的

<タスクを実施する目的や達成すべきゴールを記述します。>

## 実装内容

<すべての作業項目に対する全体的な実装方針・概要を記述します。>

## 作業

### WI-1: トークン生成ヘルパーモジュールの作成

-   JWTトークンをエンコード・デコードするユーティリティ関数を実装する。

### WI-2: バリデーション処理の実装

-   リクエストヘッダーのBearerトークンを検証する処理を追加する。

## Acceptance Criteria

### AC-1: トークン生成と検証の正常動作 (WI-1, WI-2 に対応)

- [ ] 有効期限内のJWTトークンが正しく生成・検証されること。

### AC-2: 不正トークンのエラーハンドリング (WI-2 に対応)

- [ ] 期限切れまたは改ざんされたトークンで 401 Unauthorized が返却されること。

## Verification

### AC-1 の検証

-   単体テスト（`test_token_generate`）を実行し成功すること。
-   有効なトークンでのリクエスト検証が成功すること。

### AC-2 の検証

-   期限切れトークンによる検証テスト（`test_token_expired`）を実行し 401 が返ることを確認すること。

## 実装メモ

<!-- 1ファイル10行以下の軽微な修正内容や作業メモを必要に応じて記録 -->

Track型タスク詳細の構成例 (Track 階層を設ける場合)

Track型の場合、タスク詳細ファイル内に Track 階層を設けて作業・受入条件・検証をまとめます。

# Task: SPEC-I-001 (Track型)

## 概要・目的・実装内容
<全体概要を記述>

## Track 1: トークン生成基盤の実装

### 作業 (Track 1)
- WI-1: トークン生成ヘルパーモジュールの作成

### Acceptance Criteria (Track 1)
- [ ] AC-1: トークン生成の正常動作

### Verification (Track 1)
- AC-1 の検証: 単体テスト実行

## Track 2: 認証ミドルウェア連携

### 作業 (Track 2)
- WI-2: リクエストヘッダー検証処理の実装

### Acceptance Criteria (Track 2)
- [ ] AC-2: 不正トークンのエラーハンドリング

### Verification (Track 2)
- AC-2 の検証: 結合テスト実行