tsumiki完全ガイド｜Claude Code で仕様駆動×TDD開発を実現するフレームワークの設計思想・全コマンド・gstack比較

# プロジェクトルートで実行
git clone https://github.com/classmethod/tsumiki.git /tmp/tsumiki

# .claude/commands/ ディレクトリにコマンドファイルをコピー
mkdir -p .claude/commands
cp /tmp/tsumiki/.claude/commands/*.md .claude/commands/

# rulesync のセットアップ（Node.js 18+ 必要）
npx -y rulesync init
npx -y rulesync config --init

# Claude Code 向けにインポート（.claude/commands/ に配置）
npx -y rulesync import --targets claudecode --features commands,subagents

# Gemini CLI 向けにも生成する場合（.gemini/commands/ に配置）
npx -y rulesync generate --targets geminicli --features commands

# Cursor 向けにも生成する場合（.cursor/rules/ に配置）
npx -y rulesync generate --targets cursor --features commands

.claude/
  commands/
    init-tech-stack.md      # 技術スタック選定
    kairo-requirements.md   # 要件定義
    kairo-design.md         # 設計書作成
    kairo-tasks.md          # タスク分割
    kairo-implement.md      # TDD実装
    kairo-task-verify.md    # タスク確認
    kairo-loop.md           # 長時間実装ループ
    tdd-requirements.md     # TDD用要件定義
    tdd-testcases.md        # テストケース生成
    tdd-red.md              # Red フェーズ
    tdd-green.md            # Green フェーズ
    tdd-refactor.md         # Refactor フェーズ
    tdd-verify-complete.md  # TDD完了検証
    direct-setup.md         # テスト不要タスク設定
    direct-verify.md        # 直接実装確認
    rev-tasks.md            # タスク構造抽出
    rev-design.md           # 設計書逆生成
    rev-specs.md            # テスト仕様書逆生成
    rev-requirements.md     # 要件定義書逆生成
    dcs-feature-rubber-duck.md  # アイデア整理

# Technology Stack

## Frontend
- Framework: React 18
- State Management: Zustand
- Styling: Tailwind CSS
- Package Manager: pnpm

## Backend
- Runtime: Node.js 20
- Framework: Hono
- Database: PostgreSQL 16
- ORM: Drizzle ORM

## Infrastructure
- Deployment: AWS ECS（Fargate）
- CDN: CloudFront
- CI/CD: GitHub Actions
- IaC: Terraform

## Testing
- Unit: Vitest
- E2E: Playwright
- Coverage Target: 80%+

# PRD: 商品レビューシステム

## 概要
ECサイトのユーザーが購入した商品にレビューを投稿できる機能。

## ターゲットユーザー
- 購入済みの商品を評価したい顧客
- 購入前に商品の評判を知りたい顧客

## 解決したい課題
現在、購入後のフィードバックを受け取る手段がなく、商品の改善に繋がる情報が得られていない。

## 主要機能（MVP）
- 1〜5の星評価とコメントのテキスト投稿
- 1ユーザー×1商品に1件のみ
- 投稿後24時間以内は編集・削除可能

## 除外（v1では実装しない）
- 画像添付
- いいね機能
- 返信スレッド

## 成功指標
- レビュー投稿率：購入ユーザーの20%以上
- API 応答時間：95パーセンタイルで500ms以下

# Requirements

## Functional Requirements

### Authentication
- ユーザーは有効なメールアドレスとパスワードで登録できる
- システムはパスワードを bcrypt でハッシュ化して保存しなければならない
- ユーザーはログイン時に JWT を受け取り、以降のリクエストに使用できる
- JWT の有効期限は24時間とし、リフレッシュトークンで更新できる

### Review Feature
- 認証済みユーザーは商品に対して1〜5の評価とコメントを投稿できる
- 1人のユーザーは1商品に対して1件のレビューのみ投稿できる
- レビューは投稿から24時間以内であれば編集・削除できる

## Non-Functional Requirements
- API レスポンスタイム: 95パーセンタイルで500ms以下
- 同時接続: 1,000ユーザーの同時リクエストを処理できること
- 可用性: 月次 SLA 99.9%（ダウンタイム43分/月以内）

# Design Specification

## Architecture Overview

```mermaid
graph TD
    Client[Browser/Mobile Client]
    CDN[CloudFront CDN]
    API[Hono API Server]
    DB[(PostgreSQL)]
    Cache[Redis Cache]

    Client --> CDN
    CDN --> API
    API --> DB
    API --> Cache
```

## API Design

### POST /api/reviews
- **認証**: JWT Bearer トークン必須
- **Request Body**: `{ productId: string, rating: 1-5, comment: string }`
- **Response**: `{ id: string, createdAt: string }`
- **エラー**: 401（未認証）、409（重複投稿）、422（バリデーション失敗）

## Database Schema

```sql
CREATE TABLE reviews (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id     UUID NOT NULL REFERENCES users(id),
  product_id  UUID NOT NULL REFERENCES products(id),
  rating      SMALLINT NOT NULL CHECK (rating BETWEEN 1 AND 5),
  comment     TEXT,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  UNIQUE (user_id, product_id)
);
```

# Implementation Tasks

## Critical Path: 認証 → 商品 → レビュー

## Phase 1: インフラ・環境構築（並列実行可）
- [ ] TASK-001: PostgreSQL スキーマ作成（migrations/001_initial.sql）
- [ ] TASK-002: Hono プロジェクト初期化（src/index.ts）
- [ ] TASK-003: Drizzle ORM 設定（drizzle.config.ts）

## Phase 2: 認証機能（TASK-001, TASK-002 完了後）
- [ ] TASK-004: ユーザーモデル実装（src/models/user.ts）
- [ ] TASK-005: 登録エンドポイント（POST /api/auth/register）
- [ ] TASK-006: ログインエンドポイント（POST /api/auth/login）
- [ ] TASK-007: JWT ミドルウェア（src/middleware/auth.ts）

## Phase 3: レビュー機能（TASK-004〜007 完了後）
- [ ] TASK-008: レビューモデル実装（src/models/review.ts）
- [ ] TASK-009: レビュー投稿エンドポイント（POST /api/reviews）
- [ ] TASK-010: レビュー一覧エンドポイント（GET /api/reviews/:productId）

# 現在のタスク進捗を確認する
/tsumiki:kairo-task-verify

# 長時間実装（中断リカバリー機能付き）
/tsumiki:kairo-loop

import { describe, it, expect } from "vitest";
import { submitReview } from "../src/services/review";

describe("submitReview", () => {
  it("評価が1〜5の範囲内なら投稿できる", async () => {
    const result = await submitReview({
      userId: "user-1",
      productId: "product-1",
      rating: 5,
      comment: "良い商品でした",
    });
    expect(result.id).toBeDefined();
    expect(result.rating).toBe(5);
  });

  it("評価が0の場合はバリデーションエラー", async () => {
    await expect(submitReview({
      userId: "user-1",
      productId: "product-1",
      rating: 0,    // 無効な値
      comment: "",
    })).rejects.toThrow("Rating must be between 1 and 5");
  });

  it("同一ユーザーが同一商品に2件目を投稿しようとするとエラー", async () => {
    await expect(submitReview({
      userId: "user-1",
      productId: "product-1",  // 1件目と同じ
      rating: 3,
      comment: "やっぱり普通でした",
    })).rejects.toThrow("Review already exists");
  });
});
// → この時点で submitReview が実装されていないため全テストが失敗（Red）

import { db } from "../db";
import { reviews } from "../db/schema";
import { eq, and } from "drizzle-orm";

// Green フェーズ: テストが通る最小実装。エラーハンドリングは後回し。
export async function submitReview(input: {
  userId: string;
  productId: string;
  rating: number;
  comment: string;
}) {
  if (input.rating < 1 || input.rating > 5) {
    throw new Error("Rating must be between 1 and 5");
  }
  const existing = await db.select().from(reviews).where(
    and(eq(reviews.userId, input.userId), eq(reviews.productId, input.productId))
  );
  if (existing.length > 0) {
    throw new Error("Review already exists");
  }
  const [result] = await db.insert(reviews).values({
    userId: input.userId,
    productId: input.productId,
    rating: input.rating,
    comment: input.comment,
  }).returning();
  return result;
}
// → テスト全件 Green。次は Refactor で品質を上げる。

# Terraform の初期化（テストが書けない設定作業）
/tsumiki:direct-setup TASK-001

# 設定が意図通りになっているか確認
/tsumiki:direct-verify TASK-001

# まず設計を把握する
/tsumiki:rev-design

# 要件定義書を逆生成
/tsumiki:rev-requirements

# 既存テストがない場合、仕様書をもとに TDD フローに入る
/tsumiki:tdd-testcases
/tsumiki:tdd-red
...

project-root/
  docs/
    tech-stack.md           # init-tech-stack が生成
    spec/
      requirements.md       # kairo-requirements が生成（EARS記法）
      prd.md               # dcs:feature-rubber-duck が生成（任意）
    design/
      design.md            # kairo-design が生成
      dataflow-diagram.md  # kairo-design が生成（Mermaid）
    tasks.md               # kairo-tasks が生成（チェックリスト形式）
  src/
    （実装コード）           # kairo-implement / tdd-green が生成
  tests/
    （テストファイル）        # tdd-testcases / tdd-red が生成