📃

″仕様駆動開発″というプロンプトを外付けするSpec Kit

に公開
Kiro
zennfes2025ai
仕様駆動開発
Spec Kit
tech

はじめに

何番煎じかもう分からないけどSpec Kitを触る。

https://azukiazusa.dev/blog/spec-driven-development-with-spec-kit/

https://zenn.dev/beagle/articles/7976e6ac40c762

Spec Kit

Spec Kitは、GitHubが2025年9月に発表した、仕様駆動開発（Spec-Driven Development）を支援するオープンソースのツールキットです。2025/9/9時点ではClaude Code/Gemini CLI/GitHub Copilotに対応している。

https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/

そんなんAWSも出してなかったっけ? と気づいた方は正しくて、Kiroというプロダクトのコア機能がSpecという機能でSpec-Driven Developmentはおそらくそれが初出ですね、はい。

https://kiro.dev/blog/kiro-and-the-future-of-software-development/

ちなみにKiroの大まかなSpecでのフローはこの通り。ウォーターフォールの再発明、または「螺旋」的な技術の揺り戻し。

パクリかどうかみたいな話をする気はなくて、逆にもっと混乱させる話もすると、Clineでも/deep-planningとfocus chainという機能で似た動きができます、はい。

https://qiita.com/watany/items/8b08958427c9e48a20fb

仕様駆動開発(Spec Driven Development)

Specとは仕様の意味で、乱暴に言うと仕様書ドリブンでCoding Agentを動かすぞ！なのが「仕様駆動開発」です。漢字が6文字も連続してると名前がカッコよくなって勘違いしがちだが、開発サイクルを完全にAIに代替してヒューマンフリーにするものではないです。

Amazon曰く、仕様駆動開発は元ネタとしてAI-DLC(Ai Driven Development Life Cycle)という考え方を踏まえているとのこと。

https://aws.amazon.com/jp/blogs/news/ai-driven-development-life-cycle/

https://aws.amazon.com/jp/what-is/sdlc/

AI-DLCという名前からしてSDLCの置き換えかな? と誤解を誘発するかもなのだが、そもそもAI-DLCを超訳すると「Coding Agentに全てを賭けろ」「ドライバー席を譲れ」くらいの話しか書いておらず(諸説あります)、要は原義のVibe Coding、コードなんか見ないで指示してプロダクトを作るのは危ないやろ！ 従来のソフトウェア開発のプロセスを普通に入れようや！くらいの提言であり、どのように具体に落とすかは詳細に触れられていません。

とりあえず、以下のあたりはコンセンサスが取れていて、各種製品でも実装されている機能も多いです。

  • Coding Agentはタスクリストに沿って進めろと指示すると、勝手な完了状態でサボらずに進む。
  • タスクリストをチラチラ見るとコンテキストの健忘症が緩和される。
  • Coding Agentにはいきなり実装させず、コードベースを含むコンテキストを踏まえて事前に実行計画をプランするフェーズを挟むとよい。

それをプロセス化して、要求(ユーザプロンプト) → 要件(仕様書/requirements.md) → 設計(設計書/design.md) → 実装(todoリスト/todo.md)の順でドキュメントを固めた上でタスクベースでCoding Agentを動かそうとするのがVibe Codingへのカウンターとしての仕様駆動開発、またはSpecと呼ばれる機能です。やっぱり大仰な名前な気がする。

ツール概要

雑談が長くなったので本題に戻します。Spec Kitは名前の通りSpec(仕様)を作るためのkitです。リポジトリを見るといくつかのシェルスクリプトなどが転がっており、CLIやMCP化されてもなく素朴な実装がある。

https://github.com/github/spec-kit

大まかにいうと、以下2つがSpecの職掌らしいです。

  1. uvx(Pythonのnpxみたいなやつです)でコマンド(specity init)を実行してscafoldの作成

  2. Spec kitが1で用意したスクリプトを叩いてプロンプトを注入する

動かしてみよう

リポジトリを読むと、2025/9/9時点では、以下が前提条件です。

  • Linux/macOS (or WSL2 on Windows)
  • AI coding agent: Claude Code, GitHub Copilot, or Gemini CLI
  • uv for package management
  • Python 3.11+
  • Git

今回はこんな環境(Ubuntu)で動かしていきます。

claude -v
1.0.109 (Claude Code)
uv --version
uv 0.8.15

1. Init

specity initコマンドをuvxで実行しよう。既に作業ディレクトリ内にいるときは--hereでいいらしい。

uvx --from git+https://github.com/github/spec-kit.git specify init --here

2. 仕様策定(Specify)

Claude Codeを実行すると、このようなカスタムコマンドが使えるようになっている。

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ > /                                                                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
  /plan                   Plan how to implement the specified feature. (project)
  /specify                Start a new feature by creating a specification and feature branch. (project)
  /tasks                  Break down the plan into executable tasks. (project)
  /add-dir                Add a new working directory

まずは/specifyコマンドから要求を書き込んでいく。Spec-kitの要求分析力を試すため、できるだけひどい指示で依頼する。

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ > /specify webから使える飲み会の割り勘用ツールを作って欲しい。100人くらいでも使えるように。役職ごとに傾斜をかけられるように。   │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

ちょっと待っているとファイルができあがるので読んでみよう。

spec.md
specs/001-web-100/spec.md 
# Feature Specification: Web-Based Bill Splitting Tool for Drinking Parties

**Feature Branch**: `001-web-100`  
**Created**: September 9, 2025  
**Status**: Draft  
**Input**: User description: "webから使える飲み会の割り勘用ツールを作って欲しい。100人くらいでも使えるように。役職ごとに傾斜をかけられるように。"

## Execution Flow (main)
---
1. Parse user description from Input
   → If empty: ERROR "No feature description provided"
2. Extract key concepts from description
   → Identify: actors, actions, data, constraints
3. For each unclear aspect:
   → Mark with [NEEDS CLARIFICATION: specific question]
4. Fill User Scenarios & Testing section
   → If no clear user flow: ERROR "Cannot determine user scenarios"
5. Generate Functional Requirements
   → Each requirement must be testable
   → Mark ambiguous requirements
6. Identify Key Entities (if data involved)
7. Run Review Checklist
   → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
   → If implementation details found: ERROR "Remove tech details"
8. Return: SUCCESS (spec ready for planning)

---

## ⚡ Quick Guidelines
- ✅ Focus on WHAT users need and WHY
- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
- 👥 Written for business stakeholders, not developers

### Section Requirements
- **Mandatory sections**: Must be completed for every feature
- **Optional sections**: Include only when relevant to the feature
- When a section doesn't apply, remove it entirely (don't leave as "N/A")

### For AI Generation
When creating this spec from a user prompt:
1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
4. **Common underspecified areas**:
   - User types and permissions
   - Data retention/deletion policies  
   - Performance targets and scale
   - Error handling behaviors
   - Integration requirements
   - Security/compliance needs

---

## User Scenarios & Testing *(mandatory)*

### Primary User Story
A party organizer creates a new bill-splitting session for a drinking party. They input the total bill amount, add participants' names and positions, and set position-based multipliers (e.g., managers pay 1.5x, entry-level pay 0.8x). The system calculates each person's share automatically, and participants can view their portion through a shared link.

### Acceptance Scenarios
1. **Given** a party organizer has a total bill of ¥50,000 and 20 participants with various positions, **When** they create a new session and assign position multipliers, **Then** the system calculates individual amounts and provides a shareable link
2. **Given** a participant receives a session link, **When** they access it, **Then** they can see their name, position, calculated amount, and total session summary
3. **Given** an organizer needs to modify participant details, **When** they update names or positions, **Then** amounts are recalculated automatically
4. **Given** a session with 100 participants, **When** the organizer inputs all data, **Then** the system responds within acceptable time limits and displays all calculations correctly

### Edge Cases
- What happens when the calculated amounts don't sum exactly to the total due to rounding?
- How does the system handle identical names?
- What occurs if someone tries to access an expired or invalid session?
- How are zero or negative amounts handled for extreme multiplier combinations?

## Requirements *(mandatory)*

### Functional Requirements
- **FR-001**: System MUST allow organizers to create new bill-splitting sessions without user accounts
- **FR-002**: System MUST support up to 100 participants per session
- **FR-003**: System MUST accept total bill amount input with currency formatting
- **FR-004**: System MUST allow adding participant names and position titles
- **FR-005**: System MUST support position-based payment multipliers (e.g., 0.5x to 2.0x)
- **FR-006**: System MUST calculate individual payment amounts automatically based on equal base split and position multipliers
- **FR-007**: System MUST handle rounding discrepancies by adjusting the organizer's amount
- **FR-008**: System MUST generate shareable links for each session
- **FR-009**: System MUST display session summary showing all participants, amounts, and total verification
- **FR-010**: System MUST be accessible via web browsers on desktop and mobile devices
- **FR-011**: System MUST allow organizers to edit participant details and recalculate amounts
- **FR-012**: System MUST prevent unauthorized modification of sessions [NEEDS CLARIFICATION: authentication method for organizer verification not specified]
- **FR-013**: System MUST retain session data for [NEEDS CLARIFICATION: data retention period not specified]
- **FR-014**: System MUST support [NEEDS CLARIFICATION: currency types - Japanese Yen only or multiple currencies?]
- **FR-015**: System MUST handle concurrent access when multiple people view the same session

### Key Entities *(include if feature involves data)*
- **Bill Session**: Represents a single bill-splitting event, contains total amount, creation date, and participant list
- **Participant**: Individual attendee with name, position title, payment multiplier, and calculated amount
- **Position**: Job role or hierarchy level with associated default multiplier value
- **Payment Calculation**: Mathematical result showing base amount, multiplier effect, and final payment due

---

## Review & Acceptance Checklist
*GATE: Automated checks run during main() execution*

### Content Quality
- [ ] No implementation details (languages, frameworks, APIs)
- [ ] Focused on user value and business needs
- [ ] Written for non-technical stakeholders
- [ ] All mandatory sections completed

### Requirement Completeness
- [ ] No [NEEDS CLARIFICATION] markers remain
- [ ] Requirements are testable and unambiguous  
- [ ] Success criteria are measurable
- [ ] Scope is clearly bounded
- [ ] Dependencies and assumptions identified

---

## Execution Status
*Updated by main() during processing*

- [x] User description parsed
- [x] Key concepts extracted
- [x] Ambiguities marked
- [x] User scenarios defined
- [x] Requirements generated
- [x] Entities identified
- [ ] Review checklist passed

---

3. 実装計画(Plan)

仕様はこれでOKという前提で、続けてみよう。/planコマンドから対応してほしい技術スタックで書き込んでいく。

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ > /plan 以下の技術スタックを参考にベストな実装計画を作成してください。                                                                │
│                                                                                                                                       │
│   - React + Vite                                                                                                                      │
│   - TypeScript                                                                                                                        │
│   - Tailwind CSS                                                                                                                      │
│   - Vitest                                                                                                                            │
│   - Biome                                                                                                                             │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

このフェーズでは割と色々ドキュメントが作られる(plan.mdから引用)。ちなみにcontracts/を確認するとopenapi.yamlが転がっていた。

specs/001-web-100/
├── plan.md              # This file (/plan command output)
├── research.md          # Phase 0 output (/plan command) [PENDING]
├── data-model.md        # Phase 1 output (/plan command) [PENDING]
├── quickstart.md        # Phase 1 output (/plan command) [PENDING]
├── contracts/           # Phase 1 output (/plan command) [PENDING]
└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)

全部貼るのはしんどい量なので、とりあえずplan.mdの様子を気になる人は見て欲しい。

plan.md
specs/001-web-100/plan.md
# Implementation Plan: Web-Based Bill Splitting Tool for Drinking Parties

**Branch**: `001-web-100` | **Date**: September 9, 2025 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/workspaces/my-vibe-coding-example/specs/001-web-100/spec.md`

## Execution Flow (/plan command scope)
---
1. Load feature spec from Input path ✓
   → If not found: ERROR "No feature spec at {path}"
2. Fill Technical Context (scan for NEEDS CLARIFICATION) ✓
   → Detect Project Type from context (web=frontend+backend, mobile=app+api)
   → Set Structure Decision based on project type
3. Evaluate Constitution Check section below ✓
   → If violations exist: Document in Complexity Tracking
   → If no justification possible: ERROR "Simplify approach first"
   → Update Progress Tracking: Initial Constitution Check
4. Execute Phase 0 → research.md ✓
   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
5. Execute Phase 1 → contracts, data-model.md, quickstart.md, CLAUDE.md ✓
6. Re-evaluate Constitution Check section ✓
   → If new violations: Refactor design, return to Phase 1
   → Update Progress Tracking: Post-Design Constitution Check
7. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md) ✓
8. STOP - Ready for /tasks command ✓
---

**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
- Phase 2: /tasks command creates tasks.md
- Phase 3-4: Implementation execution (manual or via tools)

## Summary
A web-based bill splitting application for drinking parties that supports up to 100 participants with position-based payment multipliers. Users can create sessions, add participants with job roles, set multipliers, and share calculated results via web links. Technical approach uses modern web stack with React + Vite frontend and appropriate backend for scalability.

## Technical Context
**Language/Version**: TypeScript with React 18, Node.js 18+  
**Primary Dependencies**: React + Vite, Tailwind CSS, Vitest for testing, Biome for linting/formatting  
**Storage**: Initially local storage/session storage, with potential for backend database (PostgreSQL) for persistence  
**Testing**: Vitest for unit/integration tests, React Testing Library for component tests  
**Target Platform**: Modern web browsers (Chrome 90+, Firefox 88+, Safari 14+), responsive mobile-first design  
**Project Type**: web - requires frontend + backend architecture  
**Performance Goals**: <200ms response time for calculations, <3s initial load, support 100 concurrent users per session  
**Constraints**: No user authentication required, sessions accessible via shareable links, mobile-responsive design  
**Scale/Scope**: Up to 100 participants per session, 1000+ concurrent sessions, currency formatting for Japanese Yen

## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

**Simplicity**:
- Projects: 2 (frontend: React app, backend: Node.js API)
- Using framework directly? Yes - React, Express, no unnecessary wrappers
- Single data model? Yes - Session with embedded Participants
- Avoiding patterns? Yes - direct API calls, no Repository pattern for simple CRUD

**Architecture**:
- EVERY feature as library? Yes - bill-splitting logic as standalone library
- Libraries listed: 
  - `@bill-splitter/core` - calculation engine with position multipliers
  - `@bill-splitter/web` - React components and UI logic
- CLI per library: 
  - `bill-splitter calculate --total 50000 --participants participants.json`
  - `bill-splitter-web --help --version --format`
- Library docs: llms.txt format planned for both libraries

**Testing (NON-NEGOTIABLE)**:
- RED-GREEN-Refactor cycle enforced? Yes - tests written first, must fail before implementation
- Git commits show tests before implementation? Will be enforced in workflow
- Order: Contract→Integration→E2E→Unit strictly followed
- Real dependencies used? Yes - actual HTTP server for integration tests
- Integration tests for: API contracts, React component integration, calculation library
- FORBIDDEN: Implementation before test, skipping RED phase

**Observability**:
- Structured logging included? Yes - JSON logs with request IDs
- Frontend logs → backend? Yes - error tracking with context
- Error context sufficient? Yes - user actions, session state, calculation inputs

**Versioning**:
- Version number assigned? v1.0.0 (MAJOR.MINOR.BUILD)
- BUILD increments on every change? Yes - automated via CI
- Breaking changes handled? API versioning, backward compatibility tests

## Project Structure

### Documentation (this feature)
---
specs/001-web-100/
├── plan.md              # This file (/plan command output)
├── research.md          # Phase 0 output (/plan command) [PENDING]
├── data-model.md        # Phase 1 output (/plan command) [PENDING]
├── quickstart.md        # Phase 1 output (/plan command) [PENDING]
├── contracts/           # Phase 1 output (/plan command) [PENDING]
└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
---

### Source Code (repository root)
---
# Option 2: Web application (frontend + backend detected)
backend/
├── src/
│   ├── models/          # Session, Participant entities
│   ├── services/        # Calculation service, session service  
│   ├── api/             # REST endpoints
│   └── lib/             # Core bill-splitting library
└── tests/
    ├── contract/        # API contract tests
    ├── integration/     # Full workflow tests
    └── unit/            # Service/library unit tests

frontend/
├── src/
│   ├── components/      # React components
│   ├── pages/           # Session creation, view pages
│   ├── services/        # API client, calculation helpers
│   └── lib/             # Frontend utilities
└── tests/
    ├── components/      # Component unit tests
    ├── integration/     # User workflow tests
    └── e2e/             # End-to-end Playwright tests
---

**Structure Decision**: Option 2 (Web application) - Feature requires frontend UI and backend API for session persistence and sharing

## Phase 0: Outline & Research

Executing research for NEEDS CLARIFICATION items from spec:

1. **Authentication method for organizer verification** - Research session-based access control
2. **Data retention period** - Research appropriate retention policies for temporary sessions  
3. **Currency support** - Research internationalization vs Japanese Yen only
4. **Technology stack validation** - Research React + Vite + TypeScript best practices
5. **Scalability approach** - Research backend architecture for 100 concurrent users

**Output**: research.md with all NEEDS CLARIFICATION resolved

## Phase 1: Design & Contracts
*Prerequisites: research.md complete*

1. **Extract entities from feature spec** → `data-model.md`:
   - Session entity with total amount, participant list, creation metadata
   - Participant entity with name, position, multiplier, calculated amount
   - Position entity with default multipliers
   - Calculation result entity for audit trail

2. **Generate API contracts** from functional requirements:
   - POST /api/sessions - Create new bill splitting session
   - GET /api/sessions/:id - Retrieve session details
   - PUT /api/sessions/:id - Update session participants/amounts
   - GET /api/sessions/:id/share - Get shareable view data
   - Output OpenAPI schema to `/contracts/`

3. **Generate contract tests** from contracts:
   - Session creation/retrieval/update test suites
   - Calculation accuracy tests
   - Concurrent access tests
   - Tests must fail (no implementation yet)

4. **Extract test scenarios** from user stories:
   - Organizer creates session with 20 participants
   - Participants access shared link
   - Real-time calculation updates
   - 100-participant stress test

5. **Update CLAUDE.md incrementally**:
   - Add React + Vite + TypeScript context
   - Add bill-splitting domain knowledge
   - Add testing approach with Vitest
   - Keep under 150 lines

**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, CLAUDE.md

## Phase 2: Task Planning Approach
*This section describes what the /tasks command will do - DO NOT execute during /plan*

**Task Generation Strategy**:
- Load `/templates/tasks-template.md` as base
- Generate tasks from Phase 1 design docs
- Each API contract → contract test task [P]
- Each React component → component test + implementation task [P]
- Each calculation scenario → unit test task [P]
- Integration tasks for user workflows
- E2E tasks for complete user journeys

**Ordering Strategy**:
- TDD order: Tests before implementation
- Dependency order: Core library → Backend API → Frontend components
- Mark [P] for parallel execution (independent components)

**Estimated Output**: 25-30 numbered, ordered tasks in tasks.md

**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan

## Phase 3+: Future Implementation
*These phases are beyond the scope of the /plan command*

**Phase 3**: Task execution (/tasks command creates tasks.md)  
**Phase 4**: Implementation (execute tasks.md following constitutional principles)  
**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)

## Complexity Tracking
*No constitutional violations identified - simple 2-project structure with direct framework usage*

## Progress Tracking
*This checklist is updated during execution flow*

**Phase Status**:
- [x] Phase 0: Research complete (/plan command)
- [x] Phase 1: Design complete (/plan command)  
- [x] Phase 2: Task planning complete (/plan command - describe approach only)
- [ ] Phase 3: Tasks generated (/tasks command)
- [ ] Phase 4: Implementation complete
- [ ] Phase 5: Validation passed

**Gate Status**:
- [x] Initial Constitution Check: PASS
- [x] Post-Design Constitution Check: PASS
- [x] All NEEDS CLARIFICATION resolved
- [x] Complexity deviations documented (none required)

---
*Based on Constitution v2.1.1 - See `/memory/constitution.md`*

4. タスク作成(Tasks)

この調子で/tasksを叩くとtask.mdファイルとしてTodoリストが作成される。

task.md
specs/001-web-100/task.md
# Tasks: Web-Based Bill Splitting Tool for Drinking Parties

**Input**: Design documents from `/workspaces/my-vibe-coding-example/specs/001-web-100/`
**Prerequisites**: plan.md (required), research.md, data-model.md, contracts/openapi.yaml

## Execution Flow (main)
---
1. Load plan.md from feature directory ✓
   → Tech stack: React 18 + Vite, TypeScript, Node.js 18+, PostgreSQL
   → Structure: Web application (frontend + backend)
2. Load design documents ✓:
   → data-model.md: Session, Participant, Position Template, Calculation Result entities
   → contracts/openapi.yaml: 5 API endpoints with full OpenAPI spec
   → research.md: Session-based auth, 30-day retention, Japanese Yen only
3. Generate tasks by category ✓:
   → Setup: Project structure, dependencies, database
   → Tests: Contract tests, integration tests per quickstart scenarios  
   → Core: Models, services, API endpoints, React components
   → Integration: Database connections, middleware, frontend-backend integration
   → Polish: Unit tests, performance validation, final testing
4. Apply task rules ✓:
   → Different files = mark [P] for parallel execution
   → Tests before implementation (TDD enforced)
   → Backend and frontend can run in parallel where appropriate
5. Number tasks sequentially (T001-T035) ✓
6. Validation complete ✓: All contracts tested, entities modeled, TDD order enforced
---

## Format: `[ID] [P?] Description`
- **[P]**: Can run in parallel (different files, no dependencies)
- File paths use web app structure: `backend/src/`, `frontend/src/`

## Phase 3.1: Setup
- [ ] T001 Create backend and frontend project structure per implementation plan
- [ ] T002 Initialize Node.js backend with Express, TypeScript, PostgreSQL dependencies
- [ ] T003 Initialize React frontend with Vite, TypeScript, Tailwind CSS, Vitest dependencies  
- [ ] T004 [P] Configure Biome linting and formatting for backend in backend/.biome.json
- [ ] T005 [P] Configure Biome linting and formatting for frontend in frontend/.biome.json
- [ ] T006 Setup PostgreSQL database schema and connection configuration in backend/src/db/
- [ ] T007 Seed position templates data in backend/src/db/seeds/position_templates.sql

## Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3
**CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation**

### Contract Tests (API Endpoints)
- [ ] T008 [P] Contract test POST /api/v1/sessions in backend/tests/contract/test_sessions_post.ts
- [ ] T009 [P] Contract test GET /api/v1/sessions/:id in backend/tests/contract/test_sessions_get.ts
- [ ] T010 [P] Contract test GET /api/v1/sessions/:id/edit/:token in backend/tests/contract/test_sessions_edit_get.ts
- [ ] T011 [P] Contract test PUT /api/v1/sessions/:id/edit/:token in backend/tests/contract/test_sessions_edit_put.ts
- [ ] T012 [P] Contract test POST /api/v1/sessions/:id/finalize/:token in backend/tests/contract/test_sessions_finalize.ts
- [ ] T013 [P] Contract test GET /api/v1/positions/templates in backend/tests/contract/test_positions_templates.ts

### Integration Tests (User Workflows from quickstart.md)
- [ ] T014 [P] Integration test: Create session with 5 participants (新年会 scenario) in backend/tests/integration/test_create_session_workflow.ts
- [ ] T015 [P] Integration test: Share session URL access and validation in backend/tests/integration/test_share_session_workflow.ts
- [ ] T016 [P] Integration test: Edit session and recalculate amounts in backend/tests/integration/test_edit_session_workflow.ts
- [ ] T017 [P] Integration test: Position template usage and auto-fill in backend/tests/integration/test_position_templates_workflow.ts
- [ ] T018 [P] Integration test: Session finalization and access control in backend/tests/integration/test_session_finalization_workflow.ts

### Frontend Component Tests
- [ ] T019 [P] Component test: Session creation form in frontend/tests/components/test_session_creation_form.tsx
- [ ] T020 [P] Component test: Participant list and calculations display in frontend/tests/components/test_participant_display.tsx
- [ ] T021 [P] Component test: Session sharing interface in frontend/tests/components/test_session_sharing.tsx

## Phase 3.3: Core Implementation (ONLY after tests are failing)

### Backend Models and Core Logic  
- [ ] T022 [P] Session model with validation in backend/src/models/Session.ts
- [ ] T023 [P] Participant model with validation in backend/src/models/Participant.ts
- [ ] T024 [P] Position Template model in backend/src/models/PositionTemplate.ts
- [ ] T025 [P] Calculation Result model in backend/src/models/CalculationResult.ts
- [ ] T026 [P] Core bill-splitting calculation service in backend/src/lib/calculator.ts
- [ ] T027 [P] Session management service in backend/src/services/SessionService.ts
- [ ] T028 [P] Position template service in backend/src/services/PositionTemplateService.ts

### Backend API Endpoints
- [ ] T029 POST /api/v1/sessions endpoint in backend/src/api/sessions.ts
- [ ] T030 GET /api/v1/sessions/:id endpoint in backend/src/api/sessions.ts
- [ ] T031 GET /api/v1/sessions/:id/edit/:token endpoint in backend/src/api/sessions.ts
- [ ] T032 PUT /api/v1/sessions/:id/edit/:token endpoint in backend/src/api/sessions.ts
- [ ] T033 POST /api/v1/sessions/:id/finalize/:token endpoint in backend/src/api/sessions.ts
- [ ] T034 GET /api/v1/positions/templates endpoint in backend/src/api/positions.ts

### Frontend Components (Can run parallel with backend endpoints)
- [ ] T035 [P] Session creation page component in frontend/src/pages/CreateSession.tsx
- [ ] T036 [P] Session view page component in frontend/src/pages/ViewSession.tsx  
- [ ] T037 [P] Session edit page component in frontend/src/pages/EditSession.tsx
- [ ] T038 [P] Participant form component in frontend/src/components/ParticipantForm.tsx
- [ ] T039 [P] Calculation display component in frontend/src/components/CalculationDisplay.tsx
- [ ] T040 [P] Position selector component in frontend/src/components/PositionSelector.tsx
- [ ] T041 [P] API client service in frontend/src/services/apiClient.ts

## Phase 3.4: Integration
- [ ] T042 Connect SessionService to PostgreSQL database in backend/src/services/SessionService.ts
- [ ] T043 Session token validation middleware in backend/src/middleware/authMiddleware.ts
- [ ] T044 Request logging and error handling middleware in backend/src/middleware/loggingMiddleware.ts
- [ ] T045 Frontend routing setup with React Router in frontend/src/App.tsx
- [ ] T046 Frontend-backend API integration and error handling in frontend/src/services/apiClient.ts
- [ ] T047 CORS and security headers configuration in backend/src/app.ts

## Phase 3.5: Polish
- [ ] T048 [P] Unit tests for calculator logic in backend/tests/unit/test_calculator.ts
- [ ] T049 [P] Unit tests for session validation in backend/tests/unit/test_session_validation.ts
- [ ] T050 [P] Unit tests for API client in frontend/tests/unit/test_api_client.ts
- [ ] T051 Performance test: 100 participants calculation (<200ms) in backend/tests/performance/test_large_sessions.ts
- [ ] T052 Performance test: Frontend load time (<3s) in frontend/tests/performance/test_app_performance.ts
- [ ] T053 E2E test: Complete user journey from quickstart.md in frontend/tests/e2e/test_complete_workflow.ts
- [ ] T054 [P] Update backend API documentation in backend/docs/api.md
- [ ] T055 [P] Update frontend component documentation in frontend/docs/components.md
- [ ] T056 Mobile responsiveness verification and fixes in frontend/src/styles/responsive.css
- [ ] T057 Japanese text and currency formatting verification across all components
- [ ] T058 Execute complete quickstart.md scenarios manually and validate all success criteria

## Dependencies
- **Setup before everything**: T001-T007 must complete before tests
- **Tests before implementation**: T008-T021 must complete and FAIL before T022-T041
- **Models before services**: T022-T025 before T027-T028
- **Services before endpoints**: T027-T028 before T029-T034
- **Backend endpoints before frontend integration**: T029-T034 before T046
- **Core implementation before integration**: T022-T041 before T042-T047
- **Integration before polish**: T042-T047 before T048-T058

## Parallel Execution Examples

### Setup Phase

```bash
# T004 and T005 can run together (different config files):
Task: "Configure Biome linting for backend in backend/.biome.json"
Task: "Configure Biome linting for frontend in frontend/.biome.json"

Contract Tests Phase

# T008-T013 can all run in parallel (different test files):
Task: "Contract test POST /api/v1/sessions in backend/tests/contract/test_sessions_post.ts"
Task: "Contract test GET /api/v1/sessions/:id in backend/tests/contract/test_sessions_get.ts" 
Task: "Contract test GET /api/v1/sessions/:id/edit/:token in backend/tests/contract/test_sessions_edit_get.ts"
Task: "Contract test PUT /api/v1/sessions/:id/edit/:token in backend/tests/contract/test_sessions_edit_put.ts"
Task: "Contract test POST /api/v1/sessions/:id/finalize/:token in backend/tests/contract/test_sessions_finalize.ts"
Task: "Contract test GET /api/v1/positions/templates in backend/tests/contract/test_positions_templates.ts"

Integration Tests Phase

# T014-T018 can run in parallel (independent test scenarios):
Task: "Integration test: Create session workflow in backend/tests/integration/test_create_session_workflow.ts"
Task: "Integration test: Share session workflow in backend/tests/integration/test_share_session_workflow.ts"
Task: "Integration test: Edit session workflow in backend/tests/integration/test_edit_session_workflow.ts"

Core Implementation Phase

# T022-T028 can run in parallel (different model/service files):
Task: "Session model with validation in backend/src/models/Session.ts"
Task: "Participant model with validation in backend/src/models/Participant.ts"
Task: "Position Template model in backend/src/models/PositionTemplate.ts"
Task: "Core bill-splitting calculation service in backend/src/lib/calculator.ts"

Frontend Components Phase

# T035-T041 can run in parallel (different component files):
Task: "Session creation page component in frontend/src/pages/CreateSession.tsx"
Task: "Session view page component in frontend/src/pages/ViewSession.tsx"
Task: "Participant form component in frontend/src/components/ParticipantForm.tsx"
Task: "API client service in frontend/src/services/apiClient.ts"

Notes

  • [P] tasks target different files with no shared dependencies
  • All contract and integration tests MUST fail initially (TDD requirement)
  • Japanese text handling (UTF-8) must be verified in T057
  • Performance benchmarks from quickstart.md enforced in T051-T052
  • Complete quickstart.md execution validates entire implementation in T058
  • Database schema changes should include proper migrations
  • Security: Edit tokens must be cryptographically secure (32+ chars)
  • Cultural context: Position templates reflect Japanese corporate hierarchy

Task Generation Rules Applied

  1. From OpenAPI Contract (5 endpoints):

    • POST /sessions → T008 contract test + T029 implementation
    • GET /sessions/:id → T009 contract test + T030 implementation
    • GET /sessions/:id/edit/:token → T010 contract test + T031 implementation
    • PUT /sessions/:id/edit/:token → T011 contract test + T032 implementation
    • POST /sessions/:id/finalize/:token → T012 contract test + T033 implementation
    • GET /positions/templates → T013 contract test + T034 implementation

  2. From Data Model (4 entities):

    • Session → T022 model + T027 service
    • Participant → T023 model
    • PositionTemplate → T024 model + T028 service
    • CalculationResult → T025 model

  3. From Quickstart Scenarios (5 user stories):

    • Create session workflow → T014 integration test
    • Share session workflow → T015 integration test
    • Edit session workflow → T016 integration test
    • Position template usage → T017 integration test
    • Session finalization → T018 integration test

  4. From Project Structure (Web app):

    • Backend setup → T001, T002, T004, T006
    • Frontend setup → T001, T003, T005
    • Integration → T042-T047 (middleware, routing, CORS)

Validation Checklist ✓

  • All 6 API endpoints have contract tests (T008-T013)
  • All 4 entities have model tasks (T022-T025)
  • All tests come before implementation (Phase 3.2 before 3.3)
  • Parallel tasks target different files (verified [P] markings)
  • Each task specifies exact file path
  • No [P] task conflicts with same file modifications
  • TDD order enforced: tests must fail before implementation
  • Cultural requirements addressed: Japanese text, Yen formatting, corporate hierarchy
  • Performance requirements: <200ms calculations, <3s load time
  • Complete user journey validated via quickstart.md execution

以降のTask実行はただ実装するだけなので割愛する。

感想

Vibe Coderでも何も考えずに一定以上の根拠をもって実装できるのはやはり良い。LLM任せにしたくないエンジニア的にも、ドキュメントベースでいくらでもLLMと議論したり勝手に直せばいいので便利。

仕様駆動開発をいろんなクライアントで実現できる世界観になるのはいいと思う。思うのだが、Spec Kitはぶっちゃけて言うと、KiroやClineのそれより使いづらい印象がある。私がAWSやClineチームが好きなのでバイアスはかかっている前提で言語化しておくと、

  • /specify, /plan, /tasksを1ステップごとに入力する体験がしんどい。
    • 特に/tasksは/planのインプットを元にリストを作るだけなのでフェーズを分割する意味が感じられない
  • Planのドキュメント量が想定より大きく戸惑う
    • 検証コストが他のSpecより大きい印象がある。
    • 率直にいうと過剰な分量で、これをレビューするのは重たい
  • /planという命名がClineやClaude CodeなどのPlanモードと衝突して混乱する

要はKiroやClineのようにワンストップで進めて、都度こちらに聞いて欲しいのだが、現状はこちらがコマンドを順に叩く必要がある。この辺が外差しのプラグインの限界なのかもしれない。あと、1ヶ月でパクれるコンセプトということは、有用であれば各種Agentにより良い形でネイティブ対応されるだろうし、プロンプトエンジニアリングが主体のプロダクトは難しいですね。

Appendix. specity initで作られるファイル

ちなみにscafoldでは、このようにファイルが作られる。.claude/commands配下にカスタムコマンドを配置し、各モード毎にscripts/*.shのツールを叩いて、templatesにドキュメントテンプレートに従って出力しているのだろう。

tree -a
.
├── .claude
│   └── commands
│       ├── plan.md
│       ├── specify.md
│       └── tasks.md
├── memory
│   ├── constitution.md
│   └── constitution_update_checklist.md
├── scripts
│   ├── check-task-prerequisites.sh
│   ├── common.sh
│   ├── create-new-feature.sh
│   ├── get-feature-paths.sh
│   ├── setup-plan.sh
│   └── update-agent-context.sh
└── templates
    ├── agent-file-template.md
    ├── plan-template.md
    ├── spec-template.md
    └── tasks-template.md

6 directories, 15 files

Discussion