RsDT (Requirements, Specs, Design & Tasks) Instructions

Instructions for AI coding assistants using RsDT for specification-driven development.

IMPORTANT: All files generated by this skill (requirement-spec.md, design.md, tasks.md, ADRs, Design Docs) MUST be written in Japanese unless explicitly requested otherwise by the user.

TL;DR Quick Checklist

Review existing work: Related codebase, existing features under RsDT/
Decide <feature_name>: kebab-case, verb-led (add-, fix-, update-, refactor-)
Deepen understanding: Codebase investigation, websearch, context7 MCP server, user questions
Generate 3 files: requirement-spec.md, design.md, tasks.md (all in Japanese)
Review drafts: Call rsdt-spec-reviewer sub-agent to verify compliance
Implementation: Follow tasks.md order and check off upon completion

Workflow Overview

Stage 1: Draft - Requirements and Design Specification

Trigger Examples:

"I want to add 〇〇 feature"
"Fix this bug"
"Create a refactoring plan"

Process:

Context Gathering
- Read and understand related codebase
- Check existing features under RsDT/ for duplicates or conflicts
- If using external tools/libraries, check latest documentation via context7 MCP server
- Use websearch for latest information as needed
Requirements Clarification
- Assume user input may be memo-level quality
- Identify unclear or ambiguous points
- Read related code before asking questions to enable discussion
- Use AskUserQuestion tool to clarify requirements
Feature Name Decision
- kebab-case, verb-led naming
- Examples: add-user-authentication, fix-login-bug, refactor-api-client
- Create directory: RsDT/<feature_name>/
Generate 3 Files (in Japanese)
- requirement-spec.md: Requirements and specifications
- design.md: Design (as needed)
- tasks.md: Task breakdown
Review Drafts (MANDATORY)
- Call rsdt-spec-reviewer sub-agent using Task tool
- Verify compliance with Design Philosophy and Important Reminders
- Address any feedback before proceeding to Stage 2

Stage 2: Implementation - Build

Follow tasks while tracking with TodoWrite tool:

Read requirement-spec.md - Understand what to build
Read design.md - Understand how to build
Read tasks.md - Check implementation steps
Implement tasks sequentially - Follow tasks.md order
Confirm completion - Verify all tasks in tasks.md are finished
Update checklist - Mark all tasks as - [x] after completion

Stage 3: Archive - Post-Completion Cleanup

After implementation completion, organize as follows:

Delete tasks.md
- Completed task list is no longer needed
Create ADRs (if needed)
- Only if project manages ADRs (Architecture Decision Records)
- Create individual ADRs for each architecture decision made
- Check project's ADR policy and match existing format and file structure
- Review existing ADRs to confirm naming conventions and location
Create Design Doc (if needed)
- Only if content is worth keeping as specification documentation
- Summarize requirements and design from requirement-spec.md and design.md
- Place in appropriate project location (e.g., docs/design/, docs/specs/)
Delete Working Files
- Delete requirement-spec.md
- Delete design.md
- Finally delete entire RsDT/<feature_name>/ directory

Directory Structure

RsDT/
└── <feature_name>/          # Work in progress (delete after completion)
    ├── requirement-spec.md  # Requirements and specs (Japanese)
    ├── design.md           # Design (optional, Japanese)
    └── tasks.md            # Task breakdown (Japanese)

Note: Directories under RsDT are temporary working directories. After implementation completion, create ADRs or Design Docs as needed, then delete the working directory.

File Format Guide

requirement-spec.md

IMPORTANT: Write this file in Japanese.

Include the following sections:

# <Feature Name>

## 背景・目的

[Why this feature is needed, what problem it solves]

## スコープ

### 実装すること
- [List of changes]
- [Mark BREAKING CHANGE with **BREAKING** if applicable]

### 実装しないこと
- [Explicitly list what's out of scope]

## 要件・仕様

### [Requirement Category] - ADDED/MODIFIED/REMOVED

#### 要件: [Requirement Name]

[Requirement description]

##### Scenario: [Scenario Name]
- **GIVEN** [Preconditions]
- **WHEN** [Actions/Events]
- **THEN** [Expected Results]

Or

##### Scenario: [Scenario Name]
- **Arrange** [Setup preconditions]
- **Act** [Execute actions]
- **Assert** [Verify results]

## 制約条件

- [Technical constraints]
- [Performance requirements]
- [Security requirements]
- [Other constraints]

Key Points:

Each requirement must have at least one scenario
Scenarios must use Given-When-Then or Arrange-Act-Assert format
Explicitly mark whether requirement is ADDED, MODIFIED, or REMOVED

design.md

IMPORTANT: Write this file in Japanese.

Include as needed (not all sections are mandatory):

# <Feature Name> 設計

## 設計選択肢の検討

**Note: 複数の選択肢が存在する設計判断がある場合のみ記述。単純な要件で選択肢がほぼない場合は省略可。**

### [設計判断項目名]

| 選択肢 | 概要 | メリット | デメリット |
|--------|------|----------|------------|
| A: [選択肢A名] | [簡潔な説明] | [利点] | [欠点] |
| B: [選択肢B名] | [簡潔な説明] | [利点] | [欠点] |
| C: [選択肢C名] | [簡潔な説明] | [利点] | [欠点] |

**採用**: [選択肢X]
**理由**: [なぜこの選択肢を選んだか1-2文で簡潔に]

## Refactoring Analysis (REQUIRED)

### Existing Code Modification/Deletion Review

| Target | File:Line | Current State | Proposal | Reason |
|--------|-----------|---------------|----------|--------|
| [Function/Class name] | `file.ts:42` | [Current impl] | Delete/Modify/Merge | [Reason] |

### Deletion Targets
- [ ] `function_name` in `file.ts:XX` - [Reason for deletion]

### Modification Targets (including breaking changes)
- [ ] `function_name` in `file.ts:XX` - [Change details and reason]

### Consolidation Targets
- [ ] `func_a` + `func_b` → `new_func` - [Reason for consolidation]

### Justification for New Additions

**Only fill this section if new code is truly necessary**

| New Item | Reason Required | Why Existing Code Cannot Be Used |
|----------|-----------------|----------------------------------|
| [Function/Class name] | [Reason] | [Why existing code is insufficient] |

### Code Volume Estimate

- Lines to delete: XX
- Lines to modify: XX
- Lines to add: XX
- **Net change: ±XX lines** (Goal: minimize net increase)

## 全体構成

[System architecture diagram/explanation]

## コンポーネント設計

### [Component Name]
- 責務: [Component's responsibilities]
- インターフェース: [Public API]
- 依存関係: [Relationships with other components]

## データベース設計

### テーブル: [Table Name]
- カラム定義
- インデックス
- 制約

## API設計

### [Endpoint Name]
- メソッド: GET/POST/PUT/DELETE
- パス: /api/...
- リクエスト: [Parameters]
- レスポンス: [Return values]

## UI設計

[Screen transitions, component composition, etc.]

## 外部連携設計

[External API, library usage]

## セキュリティ設計

[Authentication, authorization, data protection, etc.]

## テスト設計

### テスト方針
- **テスト対象**: [public API / export関数 / クラスの公開メソッド]
- **モック対象**: [外部API名]（理由: 課金/不安定）
- **実DB使用**: [はい/いいえ]
- **テストインフラ**: [testcontainers / docker-compose / in-memory DB / N/A]
- **高コストテスト**: [あり/なし] → 環境変数制御

### [Test Type: Integration / E2E / Unit]

#### Test: [Test Name]
- **対応シナリオ**: requirement-spec.mdの[シナリオ名]
- **テスト対象**: [public関数/メソッド名]
- **Given/Arrange**: [Preconditions]
- **When/Act**: [Execution]
- **Then/Assert**: [Verification]
- **モック**: [なし / 外部API名]

Key Points:

Tests must correspond to scenarios in requirement-spec.md
Use the same Given-When-Then or Arrange-Act-Assert format for tests

tasks.md

IMPORTANT: Write this file in Japanese.

IMPORTANT: Tasks MUST be structured for TDD (Test-Driven Development). Each task should include writing the test first, then the implementation.

# <Feature Name> タスク

## Phase 1: [Phase Name]

### Task 1.1: [タスク名]
- **対応シナリオ**: requirement-spec.mdの[シナリオ名]
- [ ] テスト作成: [テスト内容の説明]
- [ ] テスト実行 → Red確認
- [ ] 実装: [実装内容の説明]
- [ ] テスト実行 → Green確認
- [ ] リファクタリング（必要な場合）
- [ ] Playwright MCP serverで動作確認（フロントエンド実装の場合）

### Task 1.2: [タスク名]
- **対応シナリオ**: requirement-spec.mdの[シナリオ名]
- [ ] テスト作成: [テスト内容の説明]
- [ ] テスト実行 → Red確認
- [ ] 実装: [実装内容の説明]
- [ ] テスト実行 → Green確認
- [ ] リファクタリング（必要な場合）
- [ ] Playwright MCP serverで動作確認（フロントエンド実装の場合）

## Phase 2: [フェーズ名]

### Task 2.1: [タスク名]
- **対応シナリオ**: requirement-spec.mdの[シナリオ名]
- [ ] テスト作成: [テスト内容の説明]
- [ ] テスト実行 → Red確認
- [ ] 実装: [実装内容の説明]
- [ ] テスト実行 → Green確認
- [ ] リファクタリング（必要な場合）
- [ ] Playwright MCP serverで動作確認（フロントエンド実装の場合）

## Phase 3: 統合テスト & ドキュメント

### Task 3.1: 統合テスト
- [ ] 統合テスト作成・実行
- [ ] 全テストがGreenであることを確認
- [ ] Playwright MCP serverでE2E動作確認（フロントエンド実装の場合）

### Task 3.2: ドキュメント更新
- [ ] [必要なドキュメントを更新]

Key Points:

Break down into phases for gradual implementation
Each task MUST follow TDD cycle: Test → Red → Implement → Green → Refactor
Link each task to its corresponding scenario in requirement-spec.md
For frontend implementations: Use Playwright MCP server to verify UI behavior after each task
Time estimates are not required
Track with TodoWrite tool during implementation

Draft Creation Workflow

Step 1: Initial Assessment

# Check existing RsDT
ls -la RsDT/

# Search related code with Grep
# (Example: searching for authentication-related implementation)

Step 2: Context Gathering

Understand Codebase
- Read related files with Read tool
- Search related code with Grep
- Understand existing implementation patterns
Gather External Information
- Get latest documentation via context7 MCP server
- Get latest information via websearch
- Understand libraries/frameworks to be used
Clarify Requirements
- List unclear points
- Ask questions with AskUserQuestion
- Clarify requirements based on answers

Step 3: Feature Name Selection

# kebab-case, verb-led naming
FEATURE=add-user-authentication

# Create directory
mkdir -p RsDT/$FEATURE

Step 4: File Generation

# Generate 3 files (content will be in Japanese)
touch RsDT/$FEATURE/requirement-spec.md
touch RsDT/$FEATURE/design.md
touch RsDT/$FEATURE/tasks.md

Step 5: Draft Review (MANDATORY)

After creating the 3 draft files, you MUST call the rsdt-spec-reviewer sub-agent to review them.

Use the Task tool with subagent_type='rsdt-spec-reviewer' to verify that the created files comply with:

Design Philosophy (Destructive Simplicity)
Important Reminders
File format requirements
TDD workflow requirements

The reviewer will check the draft files against the current SKILL.md guidelines and provide feedback. Address any issues before proceeding to implementation.

Archive Guidelines

ADR Creation

IMPORTANT: ADRs should follow the project's existing language. Check existing ADRs to determine if they are in Japanese or English.

Determine if ADR is Needed
- Check if project has ADR directory (e.g., docs/adr/, adr/)
- Check if architecture-level decisions were made
- Examples: Library selection, design pattern choice, data structure decisions
Review Existing ADRs
- Read existing ADR files to understand format
- Check naming conventions (e.g., 0001-use-markdown.md, ADR-001-database-choice.md)
- Understand template structure being used
Create ADRs
- Extract relevant architecture decisions from design.md
- Create individual ADRs matching project format
- Create one ADR file per decision

Design Doc Creation

IMPORTANT: Design Docs should be written in Japanese unless the project has existing design docs in English.

Determine if Design Doc is Needed
- Is the design content worth referencing in the future?
- Is it a complex feature that other developers need to understand?
- Does the project have a location for design docs? (e.g., docs/design/, docs/specs/)
Create Design Doc
- Extract important parts from requirement-spec.md and design.md
- Summarize concisely:
  - Background and purpose
  - Key design decisions
  - Component composition
  - Important constraints
- Place in appropriate project location
When Not Needed
- For small bug fixes or simple feature additions, Design Doc is not needed
- If implementation itself is clear enough as documentation, don't create

Implementation Guidelines

Stage 2 Implementation Notes

TDD (Test-Driven Development) Approach
- MUST follow TDD cycle for each task: Red → Green → Refactor
- Red: Write a failing test first based on requirement-spec.md scenarios
- Green: Write minimal code to make the test pass
- Refactor: Clean up code while keeping tests green
- Never write implementation code without a failing test first
Utilize TodoWrite Tool
- Register tasks.md content in TodoWrite at implementation start
- Update each task from in_progress → completed
- Keep only one task in in_progress state at a time
Sequential Implementation
- Follow tasks.md order
- Confirm completion per phase
- Map tests to requirement scenarios
Completion Confirmation
- All tasks completed
- All tests passing
- Update all checkboxes in tasks.md to [x]

TDD Workflow Per Task

For each task in tasks.md:
1. Identify the scenario from requirement-spec.md
2. Write test case (Red - test should fail)
3. Run test to confirm it fails
4. Write minimal implementation (Green - test should pass)
5. Run test to confirm it passes
6. Refactor if needed (keep tests green)
7. Mark task as completed

Behavior-Driven Test Principles

Test Targets

Test: Public/exported interfaces (public methods, exported functions)
Do NOT test: Private functions, internal implementation details

Test Granularity

Test end-to-end behavior flows
Example: For APIs, test request → response flow

Mocking Policy

| Target | Policy | Reason | |--------|--------|--------| | Self-managed resources (DB, etc.) | Do NOT mock | Verify actual behavior | | External APIs (paid services, AI APIs, etc.) | Mock them | Cost and stability |

Expensive Tests

Control execution with RUN_EXPENSIVE_TESTS=1 environment variable
Skip in regular CI runs, explicitly run when needed

Test Infrastructure Check (MANDATORY)

Before writing tests that require real DB connections, MUST verify test infrastructure exists:

Check for existing infrastructure - Look for these indicators:

| Language/Framework | What to Look For | |-------------------|------------------| | Java/Kotlin | testcontainers in pom.xml/build.gradle | | Node.js/TypeScript | testcontainers in package.json, docker-compose.test.yml | | Python | testcontainers in requirements.txt/pyproject.toml | | Go | testcontainers-go in go.mod | | Any | docker-compose.yml, docker-compose.test.yml, .devcontainer/ |
If infrastructure is missing, discuss with user:
- "実DBテストのインフラがないようです。テスト作成前にセットアップしますか？"
- Propose setup options:
  - testcontainers: Recommended for most cases (programmatic container management)
  - docker-compose: Good for complex multi-service setups
  - In-memory DB: SQLite for simple cases (limited compatibility)
Only proceed with test design after infrastructure is confirmed

Design Philosophy

Destructive Simplicity

CRITICAL: Prioritize "modify/delete" over "add" during design

When designing, consider in this order:

Can this be achieved by deleting/consolidating existing code?
- Remove duplicate code
- Remove unused features
- Merge multiple functions into one
Can this be achieved by making breaking changes to existing functions?
- Change signatures (prefer simplicity over backward compatibility)
- Reassign responsibilities
- Simplify interfaces
Only add new code as a last resort
- New functions/classes are the last option
- When adding, simultaneously consider reducing existing code

Code Volume Principles

Avoid net increase: Even when adding features, minimize total code increase through refactoring
Reduce cognitive load: More functions/files = more cognitive load. Prefer consolidation
Breaking changes are good: Directly modify rather than creating wrappers/adapters for backward compatibility

Mandatory Design Checklist

Before writing design.md, MUST verify:

[ ] Have you read ALL related existing code?
[ ] Is there code that can be deleted?
[ ] Are there functions that can be consolidated?
[ ] Can this be achieved by modifying existing functions?
[ ] Is new code addition truly necessary?

Best Practices

Simplicity First

Default to <100 lines of net new code (追加と削除の差分で計算)
Single-file implementation unless clearly justified
Be cautious about adding frameworks
Choose boring, proven patterns
Prefer modifying existing functions over creating new ones
Delete code aggressively - dead code has negative value

When to Add Complexity

Only add complexity when:

Performance data shows current solution is too slow
Concrete scale requirements (>1000 users, >100MB data)
Multiple proven use cases requiring abstraction
Simpler alternatives have been explicitly ruled out

Clear References

Reference code locations in file.ts:42 format
Reference related features as RsDT/<feature_name>/

Feature Naming

kebab-case, verb-noun format: add-user-auth, fix-payment-bug
Single purpose per feature
10-minute understandability rule
Split if description needs "AND"

Common Patterns

For Bug Fixes

requirement-spec.md (in Japanese):

# requirement-spec.md

## 背景・目的
[Bug description and impact scope]

## スコープ
### 実装すること
- バグの修正
- 関連テストの追加

### 実装しないこと
- 機能追加
- リファクタリング

## 要件・仕様
### バグ修正 - MODIFIED

#### 要件: [Existing Feature Name]
[Correct behavior after fix]

##### Scenario: バグ発生条件
- **GIVEN** [Conditions where bug occurs]
- **WHEN** [Actions]
- **THEN** [Expected behavior after fix]

For New Features

requirement-spec.md (in Japanese):

# requirement-spec.md

## 背景・目的
[Need for new feature]

## スコープ
### 実装すること
- 新機能A
- 新機能Aのテスト

### 実装しないこと
- 既存機能の変更
- 関連しない機能

## 要件・仕様
### 新機能 - ADDED

#### 要件: [New Feature Name]
[Feature description]

##### Scenario: 基本的な使用
- **GIVEN** [Preconditions]
- **WHEN** [Actions]
- **THEN** [Expected results]

##### Scenario: エラーケース
- **GIVEN** [Error conditions]
- **WHEN** [Actions]
- **THEN** [Error handling]

Troubleshooting

Common Issues

"Unclear what to implement"

Re-check requirement-spec.md
Ask user about unclear points
Re-read related code

"Design is too complex"

Return to Simplicity First principle
Verify if complexity is truly needed
Consider gradual implementation

"Tasks are not progressing"

Review tasks.md phase breakdown
Break down into smaller tasks
Identify blockers and consult user

Quick Reference

Stage Indicators

RsDT/<feature_name>/ - Work in progress (delete after completion)
ADR - Architecture decision records (create as needed)
Design Doc - Specifications to keep (create as needed)

File Purposes

requirement-spec.md - What to build (requirements and specs, in Japanese)
design.md - How to build (design, in Japanese)
tasks.md - In what order to build (task breakdown, in Japanese)

Workflow Summary

Draft (Requirements) → Implementation (Build) → Archive (Create ADR/Design Doc, delete working directory)

Key Commands

# Check existing
ls -la RsDT/

# Create new
mkdir -p RsDT/<feature_name>

# Check implementation status
# Review checkboxes in tasks.md

# During Archive
# 1. Delete tasks.md
rm RsDT/<feature_name>/tasks.md

# 2. Create ADR/Design Doc (as needed)
# Check existing ADRs
ls -la docs/adr/  # or adr/

# 3. Delete working directory
rm -rf RsDT/<feature_name>/

Important Reminders

User input is memo-level: Must deepen understanding before generating 3 files
Understand code before asking: Get to a state where you can discuss before asking questions
Check latest info for external tools: Utilize context7 and websearch
Tests correspond to requirements: Always map scenarios to tests
Track with TodoWrite: Always use TodoWrite tool for progress management during implementation
Prioritize simplicity: Avoid excessive abstraction and complexity
RsDT is temporary directory: Create necessary documents after implementation completion and delete
ADR/Design Doc are selective: Only create when needed, follow existing format
Files in Japanese: All generated files (requirement-spec.md, design.md, tasks.md) must be in Japanese
Destructive Simplicity First: Always consider deleting/modifying existing code before adding new code. New functions are the LAST resort.
Minimize net code increase: Track lines added vs deleted. Aim for zero or negative net change when possible.
Breaking changes are acceptable: Prefer clean code over backward compatibility. Don't create wrappers just to avoid breaking changes.
TDD is mandatory: Always write tests first (Red), then implementation (Green), then refactor. Never write implementation without a failing test.
Document design alternatives: When multiple valid approaches exist, briefly document the options and why the chosen one was selected.
Draft review is mandatory: After creating draft files (requirement-spec.md, design.md, tasks.md), MUST call rsdt-spec-reviewer sub-agent to verify compliance with Design Philosophy and guidelines before proceeding to implementation.
Behavior-driven test targets: Only test public/exported interfaces. Do NOT test private functions or internal implementations.
Smart mocking policy: Do NOT mock self-managed resources (DB, etc.) - use real connections. Only mock external APIs (paid services, AI APIs).
Test infrastructure first: Before writing tests requiring real DB, verify test infrastructure exists (testcontainers, docker-compose, etc.). If missing, discuss with user and set up first.
Expensive test control: Tests with significant cost (external API calls, long-running operations) must be controlled with RUN_EXPENSIVE_TESTS=1 environment variable.

Remember: Requirements are truth. Design guides implementation. Tasks track progress. RsDT is temporary. Files are in Japanese. Deletion before Addition. Test First. Review Before Implementation. Real DB over Mocks.