technical-design-doc-creator

Name: technical-design-doc-creator
Author: tech-leads-club

github.com/tech-leads-club開発7.1k611 回インストール3 日前に更新

リポジトリ

technical-design-doc-creator について

technical-design-doc-creatorは、アーキテクチャ、実装計画、リスクを記述する技術設計書を作成するスキルです。情報収集を案内し、プロジェクト規模に応じて章立てを調整し、依頼と同じ言語でTDDを生成します。

主な機能

01プロジェクトの背景と要件の収集
02規模に応じたTDDの章立て
03アーキテクチャと実装計画の作成指針
04リスクとテストの文書化指針
05依頼の言語に合わせたMarkdown生成

活用シーン

01新機能や連携の設計を文書化
02大規模な技術変更の前にチームを調整
03システム移行や置き換えを計画

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/tech-leads-club/agent-skills --skill technical-design-doc-creator

インストール後、Claude Code で/technical-design-doc-creatorを入力して読み込まれたか確認します。

同梱ファイルREADME.md

詳細

技術設計書作成ツール

業界のベストプラクティスに沿って、ソフトウェアアーキテクチャの決定、実装計画、リスク評価を明確に伝える技術設計書（TDD）の作成に精通しています。

このスキルを使用するタイミング

次のような場合にこのスキルを使用してください。

ユーザーが「TDDを作成して」「設計書を書いて」「技術設計を文書化して」と依頼した場合
ユーザーが「criar um TDD」「escrever um design doc」「documentar design técnico」と依頼した場合
新しい機能や統合プロジェクトを始める場合
チーム内の合意形成が必要なシステムを設計する場合
既存システムの移行や置き換えを計画する場合
ステークホルダーの承認を得るためのドキュメントが必要だとユーザーが述べた場合
重要な技術的変更を実装する前

言語への適応

重要：TDD は、常にユーザーの依頼と同じ言語で作成してください。ユーザーの入力から言語を自動的に判定し、すべての内容（見出し、本文、説明）をその言語で作成します。

翻訳ガイドライン：

セクション見出し、本文、説明をすべてユーザーの言語に合わせて翻訳します
適切な場合は技術用語を英語のままにします（例：「API」「webhook」「JSON」「rollback」「feature flag」）
コード例とスキーマは言語に依存しない形式にします（JSON、図、コード）
会社名や製品名は原文のままにします
対象言語として自然で専門的な表現を使います
ドキュメント全体で用語を統一します

一般的なセクション見出しの翻訳：

英語	ポルトガル語	スペイン語
Context	Contexto	Contexto
Problem Statement	Definição do Problema	Definición del Problema
Scope	Escopo	Alcance
Technical Solution	Solução Técnica	Solución Técnica
Risks	Riscos	Riesgos
Implementation Plan	Plano de Implementação	Plan de Implementación
Security Considerations	Considerações de Segurança	Consideraciones de Seguridad
Testing Strategy	Estratégia de Testes	Estrategia de Pruebas
Monitoring & Observability	Monitoramento e Observabilidade	Monitoreo y Observabilidad
Rollback Plan	Plano de Rollback	Plan de Reversión

業界標準の参照資料

このスキルは、次の確立されたパターンに準拠しています。

Google Design Docs：コンテキスト、目標、対象外事項、設計、代替案、セキュリティ、テスト
Amazon PR-FAQ：Working Backwards — 顧客の課題から始める
RFC パターン：概要、動機、説明、代替案、欠点
ADR（アーキテクチャ決定記録）：コンテキスト、決定、結果
SRE Book：モニタリング、ロールバック、SLO、オブザーバビリティ
PCI DSS：決済システムのセキュリティ要件
OWASP：セキュリティのベストプラクティス

高レベル設計と実装の詳細

重要な原則：TDD で文書化するのはアーキテクチャ上の決定と契約であり、実装コードではありません。

✅ 含める内容（概要レベル）

カテゴリー	含める内容	例
API コントラクト	リクエスト／レスポンスのスキーマ	JSON ボディの構造を持つ `POST /subscriptions`
データスキーマ	テーブル構造、フィールドの型	id、email、stripeId フィールドを持つ `BillingCustomer` テーブル
アーキテクチャ	コンポーネント、データフロー	「フロントエンド → API → サービス → Stripe → データベース」
判断事項	採用する技術とその理由	「Stripe を使う理由：グローバル対応、PCI 準拠、優れたドキュメント」
図	シーケンス、アーキテクチャ、フロー	相互作用を示す Mermaid／PlantUML の図
構造	ログ形式、イベントスキーマ	構造化ログ用の JSON 構造
戦略	アプローチ。コマンドではありません	「フィーチャーフラグでロールバックする」（curl コマンドではありません）

❌ 避ける内容（実装コード）

カテゴリー	避けるもの	理由
CLI コマンド	`nx db:generate`、`kubectl rollout undo`	具体的すぎて、ツールの変更に伴い変わる可能性があります
コードスニペット	TypeScript／JavaScript の実装	コードに含めるものであり、ドキュメントに含めるものではありません
フレームワーク固有の記述	`@Injectable()`、`extends Repository`	フレームワークは変更される可能性があり、重要なのは判断事項です
ファイルパス	`scripts/backfill-feature.ts`	実装の詳細であり、アーキテクチャ上の判断ではありません
ツール固有の構文	NestJS のデコレーター、TypeORM のエンティティ	実装ではなく、パターンを記述します

例：概要レベルと実装の比較

❌ 不適切（実装の詳細に寄りすぎています）

**Rollback Steps**:

```bash
curl -X PATCH https://api.launchdarkly.com/flags/FEATURE_X \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"enabled": false}'

nx db:rollback billing
```


#### ✅ GOOD (High-Level Decision)

```markdown
**Rollback Steps**:
1. Disable feature flag via feature flag service dashboard
2. Revert database schema using down migration
3. Verify system returns to previous state
4. Monitor error rates to confirm rollback success

❌ 不適切（実装コード）

**Service Implementation**:

```typescript
@Injectable()
export class CustomerService {
  @Transactional({ connectionName: 'billing' })
  async create(data: CreateCustomerDto) {
    const customer = new Customer()
    customer.email = data.email
    return this.repository.save(customer)
  }
}
```


#### ✅ GOOD (High-Level Structure)

```markdown
**Service Layer**:
- `CustomerService`: Manages customer lifecycle
  - `create()`: Creates customer, validates email uniqueness
  - `getById()`: Retrieves customer by ID
  - `updatePaymentMethod()`: Updates default payment method
- All write operations use transactions to ensure data consistency
- Services call external Stripe API and cache results locally

ガイドライン：「これは変わるか？」と考える

TDD に詳細を追加する前に、次の点を確認してください。

「フレームワークを変更しても、この詳細は当てはまりますか？」
- はい → 含めます（アーキテクチャ上の判断です）
- いいえ → 除外します（実装の詳細です）
「要件を満たしたまま、別の方法で実装できますか？」
- はい → 実装ではなく、要件に焦点を当てます
- いいえ → 具体的すぎる可能性があります

目標：TDD は実装が変わっても有効であり続ける必要があります。NestJS から Express に、または TypeORM から Prisma に移行しても、TDD が引き続き有効であることが望まれます。

ドキュメントの構成

必須セクション（必須）

以下のセクションは必須です。ユーザーから情報が提供されない場合は、AskQuestion ツールを使って必ず質問してください。

ヘッダーとメタデータ
コンテキスト
問題の説明と動機
スコープ（対象範囲／対象外）
技術的ソリューション
リスク
実装計画

重要なセクション（不足している場合は確認）

特に次の場合は、以下のセクションを強く推奨します。

決済連携（セキュリティは必須）
本番システム（モニタリングとロールバックは必須）
外部連携（依存関係、セキュリティ）

セキュリティに関する考慮事項（決済／認証／個人情報を扱う場合は必須）
テスト戦略
モニタリングと可観測性
ロールバック計画

推奨セクション（ユーザーに提案）

ユーザーに「これらのセクションを今追加しますか、それとも後で追加しますか？」と尋ねてください。

成功指標
用語集とドメイン用語
検討した代替案
依存関係
パフォーマンス要件
移行計画（該当する場合）
未解決の質問
ロードマップ／タイムライン
承認と最終承認

プロジェクト規模への適応

次のヒューリスティックを使って、プロジェクトの複雑さを判断します。

小規模プロジェクト（1 週間未満）

使用するセクション：1、2、3、4、5、6、7、9

省略する項目：代替案、移行計画、承認

中規模プロジェクト（1～4 週間）

使用するセクション：1～11、15、18

追加を提案する項目：成功指標、用語集、代替案、パフォーマンス

大規模プロジェクト（1 か月超）

すべてのセクションを使用（1～20）

重要：すべての必須セクションと重要セクションを詳細に記述する必要があります。

対話型ワークフロー

ステップ 1：初期情報の収集

AskQuestion ツールを使用して、基本情報を収集します。

{
  "title": "TDD Project Information",
  "questions": [
    {
      "id": "project_name",
      "prompt": "What is the name of the feature/integration/project?",
      "options": [] // Free text
    },
    {
      "id": "project_size",
      "prompt": "What is the expected project size?",
      "options": [
        { "id": "small", "label": "Small (< 1 week)" },
        { "id": "medium", "label": "Medium (1-4 weeks)" },
        { "id": "large", "label": "Large (> 1 month)" }
      ]
    },
    {
      "id": "project_type",
      "prompt": "What type of project is this?",
      "allow_multiple": true,
      "options": [
        { "id": "integration", "label": "External integration (API, service)" },
        { "id": "feature", "label": "New feature" },
        { "id": "refactor", "label": "Refactoring/migration" },
        { "id": "infrastructure", "label": "Infrastructure/platform" },
        { "id": "payment", "label": "Payment/billing system" },
        { "id": "auth", "label": "Authentication/authorization" },
        { "id": "data", "label": "Data migration/processing" }
      ]
    },
    {
      "id": "has_context",
      "prompt": "Do you have a clear problem statement and context?",
      "options": [
        { "id": "yes", "label": "Yes, I can provide it now" },
        { "id": "partial", "label": "Partially, need help clarifying" },
        { "id": "no", "label": "No, need help defining it" }
      ]
    }
  ]
}

ステップ 2：必須情報の確認

回答に基づき、次の情報をユーザーが提供できるか確認します。

不足している場合に確認する必須項目：

テックリード／オーナー
チームメンバー
問題の説明（内容／理由／影響）
対象範囲
対象範囲外
大まかなソリューションの方針
少なくとも 3 つのリスク
実装タスクの内訳

AskQuestion または自然な会話を使い、ユーザーの言語で尋ねます。

英語の例：

I need the following information to create the TDD:

1. **Problem Statement**:
   - What problem are we solving?
   - Why is this important now?
   - What happens if we don't solve it?

2. **Scope**:
   - What WILL be delivered in this project?
   - What will NOT be included (out of scope)?

3. **Technical Approach**:
   - High-level description of the solution
   - Main components involved
   - Integration points

Can you provide this information?

ポルトガル語の例：

Preciso das seguintes informações para criar o TDD:

1. **Definição do Problema**:
   - Que problema estamos resolvendo?
   - Por que isso é importante agora?
   - O que acontece se não resolvermos?

2. **Escopo**:
   - O que SERÁ entregue neste projeto?
   - O que NÃO será incluído (fora do escopo)?

3. **Abordagem Técnica**:
   - Descrição de alto nível da solução
   - Principais componentes envolvidos
   - Pontos de integração

Você pode fornecer essas informações?

ステップ 3：重要なセクションの確認

project_type に基づき、重要なセクションが必須かどうかを判断します。

プロジェクトタイプ	必須の重要セクション
`payment`、`auth`	セキュリティに関する考慮事項（必須）
すべての本番環境向けプロジェクト	モニタリングとオブザーバビリティ（必須）
すべての本番環境向けプロジェクト	ロールバック計画（必須）
`integration`	依存関係、セキュリティ
すべて	テスト戦略（強く推奨）

重要なセクションが不足している場合は、ユーザーの言語で尋ねます。

英語：

This is a [payment/auth/production] system. These sections are CRITICAL:

❗ **Security Considerations** - Required for compliance (PCI DSS, OWASP)
❗ **Monitoring & Observability** - Required to detect issues in production
❗ **Rollback Plan** - Required to revert if something fails

Can you provide:
1. Security requirements (auth, encryption, PII handling)?
2. What metrics will you monitor?
3. How will you rollback if something goes wrong?

ポルトガル語：

Este é um sistema de [pagamento/autenticação/produção]. Estas seções são CRÍTICAS:

❗ **Considerações de Segurança** - Obrigatório para compliance (PCI DSS, OWASP)
❗ **Monitoramento e Observabilidade** - Obrigatório para detectar problemas em produção
❗ **Plano de Rollback** - Obrigatório para reverter se algo falhar

Você pode fornecer:
1. Requisitos de segurança (autenticação, encriptação, tratamento de PII)?
2. Quais métricas você vai monitorar?
3. Como você fará rollback se algo der errado?

ステップ 4：推奨セクションの提案

必須セクションを網羅した後、任意のセクションをユーザーの言語で提案します。

英語：

I can also add these sections to make the TDD more complete:

📊 **Success Metrics** - How will you measure success?
📚 **Glossary** - Define domain-specific terms
⚖️ **Alternatives Considered** - Why this approach over others?
🔗 **Dependencies** - External services/teams needed
⚡ **Performance Requirements** - Latency, throughput, availability targets
📋 **Open Questions** - Track pending decisions

Would you like me to add any of these now? (You can add them later)

ポルトガル語：

Também posso adicionar estas seções para tornar o TDD mais completo:

📊 **Métricas de Sucesso** - Como você vai medir o sucesso?
📚 **Glossário** - Definir termos específicos do domínio
⚖️ **Alternativas Consideradas** - Por que esta abordagem ao invés de outras?
🔗 **Dependências** - Serviços/times externos necessários
⚡ **Requisitos de Performance** - Latência, throughput, disponibilidade
📋 **Questões em Aberto** - Rastrear decisões pendentes

Gostaria que eu adicionasse alguma dessas agora? (Você pode adicionar depois)

ステップ 5：ドキュメントの生成

以下のテンプレートに従い、Markdown 形式で TDD を生成します。

ステップ 6：Confluence 連携の提案

ユーザーが Confluence Assistant スキルを利用できる場合は、ユーザーの言語で尋ねます。

英語：

Would you like me to publish this TDD to Confluence?
- I can create a new page in your space
- Or update an existing page

ポルトガル語：

Gostaria que eu publicasse este TDD no Confluence?
- Posso criar uma nova página no seu espaço
- Ou atualizar uma página existente

セクションのテンプレート

1. ヘッダーとメタデータ（必須）

# TDD - [Project/Feature Name]

| Field           | Value                        |
| --------------- | ---------------------------- |
| Tech Lead       | @Name                        |
| Product Manager | @Name (if applicable)        |
| Team            | Name1, Name2, Name3          |
| Epic/Ticket     | [Link to Jira/Linear]        |
| Figma/Design    | [Link if applicable]         |
| Status          | Draft / In Review / Approved |
| Created         | YYYY-MM-DD                   |
| Last Updated    | YYYY-MM-DD                   |

ユーザーから情報が提供されない場合：テックリード、チームメンバー、エピックへのリンクを尋ねます。

2. コンテキスト（必須）

## Context

[2-4 paragraph description of the project]

**Background**:
What is the current state? What system/feature does this relate to?

**Domain**:
What business domain is this part of? (e.g., billing, authentication, content delivery)

**Stakeholders**:
Who cares about this project? (users, business, compliance, etc.)

不明確な場合：「現在の状況と、関連するビジネス領域について説明していただけますか？」と尋ねます。

3. 問題の説明と動機（必須）

## Problem Statement & Motivation

### Problems We're Solving

- **Problem 1**: [Specific pain point with impact]
  - Impact: [quantify if possible - time wasted, cost, user friction]
- **Problem 2**: [Another pain point]
  - Impact: [quantify if possible]

### Why Now?

- [Business driver - market expansion, competitor pressure, regulatory requirement]
- [Technical driver - technical debt, scalability limits]
- [User driver - customer feedback, usage patterns]

### Impact of NOT Solving

- **Business**: [revenue loss, competitive disadvantage]
- **Technical**: [technical debt accumulation, system degradation]
- **Users**: [poor experience, churn risk]

ユーザーが「X と連携するため」と答えた場合：「この連携によって具体的にどのような問題を解決しますか？今それが重要なのはなぜですか？実施しなかった場合、何が起こりますか？」と尋ねます。

4. 対象範囲（必須）

## Scope

### ✅ In Scope (V1 - MVP)

Explicit list of what WILL be delivered:

- Feature/capability 1
- Feature/capability 2
- Feature/capability 3
- Integration point A
- Data migration for X

### ❌ Out of Scope (V1)

Explicit list of what will NOT be included in this phase:

- Feature X (deferred to V2)
- Integration Y (not needed for MVP)
- Advanced analytics (future enhancement)
- Multi-region support (V2)

### 🔮 Future Considerations (V2+)

What might come later:

- Feature A (user demand dependent)
- Feature B (after V1 validation)

ユーザーが定義していない場合：「V1 で必須の項目は何ですか？後続バージョンに回せるものは何ですか？」と尋ねます。

5. 技術的ソリューション（必須）

## Technical Solution

### Architecture Overview

[High-level description of the solution]

**Key Components**:

- Component A: [responsibility]
- Component B: [responsibility]
- Component C: [responsibility]

**Architecture Diagram**:

[Include Mermaid diagram, PlantUML, or link to diagram]

```mermaid
graph LR
    A[Frontend] -->|HTTP| B[API Gateway]
    B -->|GraphQL| C[Backend Service]
    C -->|REST| D[External API]
    C -->|Write| E[(Database)]
```

データフロー

ステップ 1：ユーザーの操作 → フロントエンド
ステップ 2：フロントエンド → API Gateway（POST /resource）
ステップ 3：API Gateway → サービスレイヤー
ステップ 4：サービス → 外部 API（該当する場合）
ステップ 5：サービス → データベース（永続化）
ステップ 6：レスポンス → フロントエンド

API とエンドポイント

エンドポイント	メソッド	説明	リクエスト	レスポンス
`/api/v1/resource`	POST	リソースを作成	`CreateDto`	`ResourceDto`
`/api/v1/resource/:id`	GET	ID で取得	-	`ResourceDto`
`/api/v1/resource/:id`	DELETE	リソースを削除	-	`204 No Content`

リクエスト／レスポンスの例：

// POST /api/v1/resource
{
  "name": "Example",
  "type": "standard"
}

// Response 201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Example",
  "type": "standard",
  "status": "active",
  "createdAt": "2026-02-04T10:00:00Z"
}

データベースの変更

新しいテーブル：

{ModuleName}{EntityName} - ［説明］
- 主なフィールド：id、userId、name、status
- タイムスタンプ：createdAt、updatedAt
- インデックス：userId、status（クエリのパフォーマンス向上のため）

スキーマの変更（既存のものを変更する場合）：

ExistingTable にカラム newField を追加
- 型：[varchar/integer/jsonb/etc.]
- 制約：[nullable/unique/foreign key]

マイグレーション戦略：

スキーマの変更からマイグレーションを生成する
まずステージング環境でマイグレーションをテストする
トラフィックの少ない時間帯に実行する
ロールバック用のマイグレーションを用意する

データのバックフィル（必要な場合）：

対象レコード：件数の見積もり
処理時間：データ移行にかかる時間の見積もり
検証：バックフィル後にデータの整合性を確認する方法


**If user provides vague description**: Ask "What are the main components? How does data flow through the system? What APIs will be created/modified?"

---

### 6. Risks (MANDATORY)

```markdown
## Risks

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| External API downtime | High | Medium | Implement circuit breaker, cache responses, fallback to degraded mode |
| Data migration failure | High | Low | Test on staging copy, run dry-run first, have rollback script ready |
| Performance degradation | Medium | Medium | Load test before deployment, implement caching, monitor latency |
| Security vulnerability | High | Low | Security review, penetration testing, follow OWASP guidelines |
| Scope creep | Medium | High | Strict scope definition, change request process, regular stakeholder alignment |

**Risk Scoring**:
- **Impact**: High (system down, data loss) / Medium (degraded UX) / Low (minor inconvenience)
- **Probability**: High (>50%) / Medium (20-50%) / Low (<20%)

ユーザーが 3 件未満のリスクしか提示しない場合：「どのような問題が起こり得ますか？外部依存関係、データの整合性、パフォーマンス、セキュリティ、スコープの変更を検討してください。」と尋ねます。

7. 実装計画（必須）

## Implementation Plan

| Phase                 | Task              | Description                            | Owner   | Status | Estimate |
| --------------------- | ----------------- | -------------------------------------- | ------- | ------ | -------- |
| **Phase 1 - Setup**   | Setup credentials | Obtain API keys, configure environment | @Dev1   | TODO   | 1d       |
|                       | Database setup    | Create schema, configure datasource    | @Dev1   | TODO   | 1d       |
| **Phase 2 - Core**    | Entities & repos  | Create TypeORM entities, repositories  | @Dev2   | TODO   | 3d       |
|                       | Services          | Implement business logic services      | @Dev2   | TODO   | 4d       |
| **Phase 3 - APIs**    | REST endpoints    | Create controllers, DTOs               | @Dev3   | TODO   | 3d       |
|                       | Integration       | Integrate with external API            | @Dev1   | TODO   | 3d       |
| **Phase 4 - Testing** | Unit tests        | Test services and repositories         | @Team   | TODO   | 2d       |
|                       | E2E tests         | Test full flow                         | @Team   | TODO   | 3d       |
| **Phase 5 - Deploy**  | Staging deploy    | Deploy to staging, smoke test          | @DevOps | TODO   | 1d       |
|                       | Production deploy | Phased rollout to production           | @DevOps | TODO   | 1d       |

**Total Estimate**: ~20 days (4 weeks)

**Dependencies**:

- Must complete Phase N before Phase N+1
- External API access required before Phase 3
- Security review required before Phase 5

ユーザーの計画が曖昧な場合：「これを具体的なタスクを含むフェーズに分けられますか？各パートは誰が担当しますか？予定期間はどれくらいですか？」と尋ねます。

8. セキュリティに関する考慮事項（決済／認証／PII を扱う場合は重要）

## Security Considerations

### Authentication & Authorization

- **Authentication**: How users prove identity
  - Example: JWT tokens, OAuth 2.0, session-based
- **Authorization**: What authenticated users can access
  - Example: Role-based (RBAC), Attribute-based (ABAC)
  - Ensure users can only access their own resources

### Data Protection

**Encryption**:

- **At Rest**: Database encryption enabled (AES-256)
- **In Transit**: TLS 1.3 for all API communication
- **Secrets**: Store API keys in environment variables / secret manager (AWS Secrets Manager, HashiCorp Vault)

**PII Handling**:

- What PII is collected: [email, name, payment info]
- Legal basis: [consent, contract, legitimate interest]
- Retention: [how long data is kept]
- Deletion: [GDPR right to be forgotten implementation]

### Compliance Requirements

| Regulation  | Requirement                        | Implementation                                    |
| ----------- | ---------------------------------- | ------------------------------------------------- |
| **GDPR**    | Data protection, right to deletion | Implement data export/deletion endpoints          |
| **PCI DSS** | No storage of card data            | Use Stripe tokenization, never store CVV/full PAN |
| **LGPD**    | Brazil data protection             | Same as GDPR compliance                           |

### Security Best Practices

- ✅ Input validation on all endpoints
- ✅ SQL injection prevention (parameterized queries)
- ✅ XSS prevention (sanitize user input, CSP headers)
- ✅ CSRF protection (tokens for state-changing operations)
- ✅ Rate limiting (e.g., 10 req/min per user, 100 req/min per IP)
- ✅ Audit logging (log all sensitive operations)

### Secrets Management

**API Keys**:

- Storage: Environment variables or secret management service
- Rotation: Define rotation policy (e.g., every 90 days)
- Access: Backend services only, never exposed to frontend
- Examples: Stripe keys, database credentials, API tokens

**Webhook Signatures**:

- Validate webhook signatures from external services
- Reject requests without valid signature headers
- Log invalid signature attempts for security monitoring

情報が不足しており、プロジェクトが決済／認証を扱う場合：「これは［決済／認証］システムです。セキュリティの詳細が必要です。認証はどのように処理しますか？どのような暗号化を使用しますか？どのような PII を収集しますか？コンプライアンス要件（GDPR、PCI DSS）はありますか？」と尋ねます。

9. テスト戦略（重要）

## Testing Strategy

| Test Type             | Scope                    | Coverage Target          | Approach             |
| --------------------- | ------------------------ | ------------------------ | -------------------- |
| **Unit Tests**        | Services, repositories   | > 80%                    | Jest with mocks      |
| **Integration Tests** | API endpoints + database | Critical paths           | Supertest + test DB  |
| **E2E Tests**         | Full user flows          | Happy path + error cases | Playwright           |
| **Contract Tests**    | External API integration | API contract validation  | Pact or manual mocks |
| **Load Tests**        | Performance under load   | Baseline performance     | k6 or Artillery      |

### Test Scenarios

**Unit Tests**:

- ✅ Service business logic (create, update, delete)
- ✅ Repository query methods
- ✅ Error handling (throw correct exceptions)
- ✅ Edge cases (null inputs, invalid data)

**Integration Tests**:

- ✅ POST `/api/v1/resource` → creates in DB
- ✅ GET `/api/v1/resource/:id` → returns correct data
- ✅ DELETE `/api/v1/resource/:id` → removes from DB
- ✅ Invalid input → returns 400 Bad Request
- ✅ Unauthorized access → returns 401/403

**E2E Tests**:

- ✅ User creates resource → success flow
- ✅ User tries to access another user's resource → denied
- ✅ External API fails → graceful degradation
- ✅ Database connection lost → proper error handling

**Load Tests**:

- Target: 100 req/s sustained, 500 req/s peak
- Monitor: Latency (p50, p95, p99), error rate, throughput
- Pass criteria: p95 < 500ms, error rate < 1%

### Test Data Management

- Use factories for test data (e.g., `@faker-js/faker`)
- Seed test database with realistic data
- Clean up test data after each test
- Use separate test database (never use production)

情報が不足している場合：「どのようにテストしますか？どの種類のテスト（単体、統合、E2E）が必要ですか？重要なテストシナリオは何ですか？」と尋ねます。

10. モニタリングと可観測性（本番環境では重要）

## Monitoring & Observability

### Metrics to Track

| Metric                    | Type       | Alert Threshold   | Dashboard          |
| ------------------------- | ---------- | ----------------- | ------------------ |
| `api.latency`             | Latency    | p95 > 1s for 5min | DataDog / Grafana  |
| `api.error_rate`          | Error rate | > 1% for 5min     | DataDog / Grafana  |
| `external_api.latency`    | Latency    | p95 > 2s for 5min | DataDog            |
| `external_api.errors`     | Counter    | > 5 in 1min       | PagerDuty          |
| `database.query_time`     | Duration   | p95 > 100ms       | DataDog            |
| `webhook.processing_time` | Duration   | > 5s              | Internal Dashboard |

### Structured Logging

**Log Format** (JSON):

```json
{
  "level": "info",
  "timestamp": "2026-02-04T10:00:00Z",
  "message": "Resource created",
  "context": {
    "userId": "user-123",
    "resourceId": "res-456",
    "action": "create",
    "duration_ms": 45
  }
}
```

ログに記録する内容：

✅ すべての API リクエスト（メソッド、パス、ステータス、所要時間）
✅ 外部 API 呼び出し（エンドポイント、ステータス、所要時間）
✅ データベースクエリ（100ms を超える低速クエリ）
✅ エラーと例外（スタックトレース、コンテキスト）
✅ ビジネスイベント（リソースの作成、決済の処理）

ログに記録しない内容：

❌ パスワード、API キー、シークレット
❌ クレジットカード番号全桁
❌ 機密性の高い PII（マスキングまたはハッシュ化する）

アラート

アラート	重大度	チャネル	オンコール時の対応
エラー率 > 5%	P1（重大）	PagerDuty	直ちに調査し、必要に応じてロールバックする
外部 API の停止	P1（重大）	PagerDuty	フォールバックモードを有効にし、関係者に通知する
レイテンシ > 2s（p95）	P2（高）	Slack #engineering	パフォーマンスの低下を調査する
Webhook の失敗 > 20	P2（高）	Slack #engineering	Webhook エンドポイントと Stripe の状態を確認する
データベースの接続プールが枯渇	P1（重大）	PagerDuty	接続数を増やすか、リークを調査する

ダッシュボード

運用ダッシュボード：

リクエスト率（エンドポイントごと）
エラー率（全体およびエンドポイントごと）
レイテンシ（p50、p95、p99）
外部 API の健全性
データベースのパフォーマンス

ビジネスダッシュボード：

作成されたリソース（1 日あたりの件数）
アクティブユーザー
コンバージョン指標（該当する場合）


**If missing for production system**: Ask "How will you monitor this in production? What metrics matter? What alerts do you need?"

---

### 11. Rollback Plan (CRITICAL for production)

```markdown
## Rollback Plan

### Deployment Strategy

- **Feature Flag**: `FEATURE_X_ENABLED` (LaunchDarkly / custom)
- **Phased Rollout**:
  - Phase 1: 5% of traffic (1 day)
  - Phase 2: 25% of traffic (1 day)
  - Phase 3: 50% of traffic (1 day)
  - Phase 4: 100% of traffic

- **Canary Deployment**: Deploy to 1 instance first, monitor for 1h before full rollout

### Rollback Triggers

| Trigger | Action |
|---------|--------|
| Error rate > 5% for 5 minutes | **Immediate rollback** - disable feature flag |
| Latency > 3s (p95) for 10 minutes | **Investigate** - rollback if no quick fix |
| External API integration failing > 50% | **Rollback** - revert to previous version |
| Database migration fails | **STOP** - do not proceed, investigate |
| Customer reports of data loss | **Immediate rollback** + incident response |

### Rollback Steps

**1. Immediate Rollback (< 5 minutes)**:
- **Feature Flag**: Disable via feature flag dashboard (instant)
- **Deployment**: Revert to previous version via deployment tool (2-3 minutes)

**2. Database Rollback** (if schema changed):
- Run down migration using migration tool
- Verify schema integrity
- Confirm data consistency

**3. Communication**:

- Notify #engineering Slack channel
- Update status page (if customer-facing)
- Create incident ticket
- Schedule post-mortem within 24h

### Post-Rollback

- **Root Cause Analysis**: Within 24 hours
- **Fix**: Implement fix in development environment
- **Re-test**: Full test suite + additional tests for root cause
- **Re-deploy**: Following same phased rollout strategy

### Database Rollback Considerations

- **Migrations**: Always create reversible migrations (down migration)
- **Data Backfill**: If data was modified, have script to restore previous state
- **Backup**: Take database snapshot before running migrations
- **Testing**: Test rollback procedure on staging before production

本番環境向けの情報が不足している場合：「デプロイに問題が起きた場合、どうなりますか？どのようにロールバックしますか？ロールバックの判断基準は何ですか？」と尋ねます。

12. 成功指標（推奨）

## Success Metrics

| Metric                  | Baseline      | Target  | Measurement        |
| ----------------------- | ------------- | ------- | ------------------ |
| API latency (p95)       | N/A (new API) | < 200ms | DataDog APM        |
| Error rate              | N/A           | < 0.1%  | Sentry / logs      |
| Conversion rate         | N/A           | > 70%   | Analytics          |
| User satisfaction       | N/A           | NPS > 8 | User survey        |
| Time to complete action | N/A           | < 30s   | Frontend analytics |

**Business Metrics**:

- Increase in [metric] by [X%]
- Reduction in [cost/time] by [Y%]
- User adoption: [Z%] of users using new feature within 30 days

**Technical Metrics**:

- Zero production incidents in first 30 days
- Test coverage > 80%
- Documentation completeness: 100% of public APIs documented

13. 用語集とドメイン用語（推奨）

## Glossary

| Term                | Description                                                           |
| ------------------- | --------------------------------------------------------------------- |
| **Customer**        | A user who has an active subscription or has made a purchase          |
| **Subscription**    | Recurring payment arrangement with defined interval (monthly, annual) |
| **Trial**           | Free period for users to test service before payment required         |
| **Webhook**         | HTTP callback from external service to notify of events               |
| **Idempotency**     | Operation can be applied multiple times with same result              |
| **Circuit Breaker** | Pattern to prevent cascading failures when external service is down   |

**Acronyms**:

- **API**: Application Programming Interface
- **SLA**: Service Level Agreement
- **PII**: Personally Identifiable Information
- **GDPR**: General Data Protection Regulation
- **PCI DSS**: Payment Card Industry Data Security Standard

14. 検討した代替案（推奨）

## Alternatives Considered

| Option                | Pros                                                     | Cons                                                                        | Why Not Chosen                                    |
| --------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------- |
| **Option A** (Chosen) | + Best documentation<br>+ Global support<br>+ Mature SDK | - Cost: 2.9% + $0.30<br>- Vendor lock-in                                    | ✅ **Chosen** - Best balance of features and cost |
| Option B              | + Lower fees (2.5%)<br>+ Brand recognition               | - Poor developer experience<br>- Limited international support              | Developer experience inferior, harder to maintain |
| Option C              | + Full control<br>+ No transaction fees                  | - High maintenance cost<br>- Compliance burden (PCI DSS)<br>- Security risk | Too risky and expensive to maintain in-house      |
| Option D              | + Cheapest option                                        | - No support<br>- Limited features<br>- Unknown reliability                 | Too risky for production payment processing       |

**Decision Criteria**:

1. Developer experience and documentation quality (weight: 40%)
2. Total cost of ownership (weight: 30%)
3. International support and compliance (weight: 20%)
4. Reliability and uptime (weight: 10%)

**Why Option A Won**:

- Scored highest on developer experience (critical for fast iteration)
- Industry-standard for startups (easier to hire developers with experience)
- Built-in compliance (PCI DSS, SCA, 3D Secure) reduces risk

15. 依存関係（推奨）

## Dependencies

| Dependency            | Type           | Owner       | Status           | Risk                |
| --------------------- | -------------- | ----------- | ---------------- | ------------------- |
| Stripe API            | External       | Stripe Inc. | Production-ready | Low (99.99% uptime) |
| Identity Module       | Internal       | Team Auth   | Production-ready | Low                 |
| Database (PostgreSQL) | Infrastructure | DevOps      | Ready            | Low                 |
| Redis (caching)       | Infrastructure | DevOps      | Needs setup      | Medium              |
| Feature flag service  | Internal       | Platform    | Ready            | Low                 |

**Approval Requirements**:

- [ ] Security team review (for payment/auth projects)
- [ ] Compliance sign-off (for PII/payment data)
- [ ] Ops team ready for monitoring setup
- [ ] Product sign-off on scope

**Blockers**:

- Waiting for Stripe production keys (ETA: 2026-02-10)
- Need Redis setup in staging (ETA: 2026-02-08)

16. パフォーマンス要件（推奨）

## Performance Requirements

| Metric              | Requirement                   | Measurement Method |
| ------------------- | ----------------------------- | ------------------ |
| API Latency (p50)   | < 100ms                       | DataDog APM        |
| API Latency (p95)   | < 500ms                       | DataDog APM        |
| API Latency (p99)   | < 1s                          | DataDog APM        |
| Throughput          | 1000 req/s sustained          | Load testing (k6)  |
| Availability        | 99.9% (< 8.76h downtime/year) | Uptime monitoring  |
| Database query time | < 50ms (p95)                  | Slow query log     |

**Load Testing Plan**:

- Baseline: 100 req/s for 10 minutes
- Peak: 500 req/s for 5 minutes
- Spike: 1000 req/s for 1 minute

**Scalability**:

- Horizontal scaling: Add more instances (Kubernetes autoscaling)
- Database: Read replicas if needed (after 10k req/s)
- Caching: Redis for frequently accessed data (> 100 req/s per resource)

17. 移行計画（該当する場合は推奨）

## Migration Plan

### Migration Strategy

**Type**: [Blue-Green / Rolling / Big Bang / Phased]

**Phases**:

| Phase             | Description                            | Users Affected | Duration | Rollback            |
| ----------------- | -------------------------------------- | -------------- | -------- | ------------------- |
| 1. Preparation    | Set up new system, run in parallel     | 0%             | 1 week   | N/A                 |
| 2. Shadow Mode    | New system processes but doesn't serve | 0%             | 1 week   | Instant             |
| 3. Pilot          | 5% of users on new system              | 5%             | 1 week   | < 5min              |
| 4. Ramp Up        | 50% of users on new system             | 50%            | 1 week   | < 5min              |
| 5. Full Migration | 100% of users on new system            | 100%           | 1 day    | < 5min              |
| 6. Decommission   | Turn off old system                    | 0%             | 1 week   | Restore from backup |

### Data Migration

**Source**: Old system database
**Destination**: New system database
**Volume**: [X million records]
**Method**: [ETL script / database replication / API sync]

**Steps**:

1. Export data from old system (script: `scripts/export-old-data.ts`)
2. Transform data to new schema (script: `scripts/transform-data.ts`)
3. Validate data integrity (checksums, row counts)
4. Load into new system (script: `scripts/load-new-data.ts`)
5. Verify: Run parallel reads, compare results

**Timeline**:

- Dry run on staging: 2026-02-10
- Production migration window: 2026-02-15 02:00-06:00 UTC (low traffic)

### Backward Compatibility

- Old API endpoints will remain active for 90 days
- Deprecation warnings added to responses
- Client libraries updated with migration guide

18. 未解決の質問（推奨）

## Open Questions

| #   | Question                                               | Context                                        | Owner     | Status           | Decision Date |
| --- | ------------------------------------------------------ | ---------------------------------------------- | --------- | ---------------- | ------------- |
| 1   | How to handle trial expiration without payment method? | User loses access immediately or grace period? | @Product  | 🟡 In Discussion | TBD           |
| 2   | Allow multiple trials for same email?                  | Prevent abuse vs. legitimate use cases         | @TechLead | 🔴 Open          | TBD           |
| 3   | SLA for webhook processing?                            | Stripe retries for 72h, what's our target?     | @Backend  | 🔴 Open          | TBD           |
| 4   | Support for promo codes in V1?                         | Marketing requested, is it in scope?           | @Product  | ✅ Resolved: V2  | 2026-02-01    |
| 5   | Fallback if Identity Module fails?                     | Can we create subscription without user data?  | @TechLead | 🔴 Open          | TBD           |

**Status Legend**:

- 🔴 Open - needs decision
- 🟡 In Discussion - actively being discussed
- ✅ Resolved - decision made

19. ロードマップ／タイムライン（推奨）

## Roadmap / Timeline

| Phase                    | Deliverables                                                                      | Duration | Target Date | Status         |
| ------------------------ | --------------------------------------------------------------------------------- | -------- | ----------- | -------------- |
| **Phase 0: Setup**       | - Stripe credentials<br>- Staging environment<br>- SDK installed                  | 2 days   | 2026-02-05  | ✅ Complete    |
| **Phase 1: Persistence** | - Entities created<br>- Repositories implemented<br>- Migrations generated        | 3 days   | 2026-02-08  | 🟡 In Progress |
| **Phase 2: Services**    | - CustomerService<br>- SubscriptionService<br>- Identity integration              | 5 days   | 2026-02-15  | ⏳ Pending     |
| **Phase 3: APIs**        | - POST /subscriptions<br>- DELETE /subscriptions/:id<br>- GET /subscriptions      | 3 days   | 2026-02-18  | ⏳ Pending     |
| **Phase 4: Webhooks**    | - Webhook endpoint<br>- Signature validation<br>- Event handlers                  | 4 days   | 2026-02-22  | ⏳ Pending     |
| **Phase 5: Testing**     | - Unit tests (80% coverage)<br>- Integration tests<br>- E2E tests                 | 5 days   | 2026-02-27  | ⏳ Pending     |
| **Phase 6: Deploy**      | - Documentation<br>- Monitoring setup<br>- Staging deploy<br>- Production rollout | 3 days   | 2026-03-02  | ⏳ Pending     |

**Total Duration**: ~25 days (5 weeks)

**Milestones**:

- 🎯 M1: MVP ready for staging (2026-02-22)
- 🎯 M2: Production deployment (2026-03-02)
- 🎯 M3: 100% rollout complete (2026-03-09)

**Critical Path**:
Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6

20. 承認と承認記録（推奨）

## Approval & Sign-off

| Role                     | Name  | Status         | Date       | Comments                          |
| ------------------------ | ----- | -------------- | ---------- | --------------------------------- |
| Tech Lead                | @Name | ✅ Approved    | 2026-02-04 | LGTM, proceed with implementation |
| Staff/Principal Engineer | @Name | ⏳ Pending     | -          | Requested security review first   |
| Product Manager          | @Name | ✅ Approved    | 2026-02-03 | Scope aligned with roadmap        |
| Engineering Manager      | @Name | ⏳ Pending     | -          | -                                 |
| Security Team            | @Name | 🔴 Not Started | -          | Required for payment integration  |
| Compliance/Legal         | @Name | N/A            | -          | Not required for this project     |

**Approval Criteria**:

- ✅ All mandatory sections complete
- ✅ Security review passed (if applicable)
- ✅ Risks identified and mitigated
- ✅ Timeline realistic and agreed upon
- ⏳ Test strategy approved by QA
- ⏳ Monitoring plan reviewed by SRE

**Next Steps After Approval**:

1. Create Epic in Jira (link in metadata)
2. Break down into User Stories
3. Begin Phase 1 implementation
4. Schedule kickoff meeting with team

検証ルール

必須セクションのチェックリスト

TDD を仕上げる前に、以下を確認してください。

ヘッダー：Tech Lead、Team、Epic リンクが記載されている
コンテキスト：背景とドメインを説明する段落が 2 つ以上ある
問題：具体的な問題が少なくとも 2 つ特定され、それぞれの影響が示されている
スコープ：スコープ内とスコープ外の項目が明確に示されている（それぞれ最低 3 項目）
技術的ソリューション：アーキテクチャ図または説明がある
技術的ソリューション：少なくとも 1 つの API エンドポイントが定義されている
リスク：影響度／発生確率／緩和策を含むリスクが少なくとも 3 つある
実装計画：見積もりを含むフェーズに分けられている

重要セクションのチェックリスト（プロジェクトの種類別）

決済／認証プロジェクトの場合：

セキュリティ：認証方式が定義されている
セキュリティ：暗号化（保存時、転送時）が明記されている
セキュリティ：PII の取り扱い方針が記載されている
セキュリティ：コンプライアンス要件が特定されている

本番システムの場合：

モニタリング：しきい値を含む指標が少なくとも 3 つ定義されている
モニタリング：アラートが設定されている
ロールバック：ロールバックのトリガーが定義されている
ロールバック：ロールバックの手順が記載されている

すべてのプロジェクト：

テスト：少なくとも 2 種類のテスト（ユニット、インテグレーション、E2E）が定義されている
テスト：重要なテストシナリオが列挙されている

出力形式

TDD を作成する場合

Markdown ドキュメントを生成する
上記のチェックリストに照らして検証する
不足している重要セクションを明示する
ユーザーに概要を提示する：

✅ TDD Created: "[Project Name]"

**Sections Included**:
✅ Mandatory (7/7): All present
✅ Critical (3/4): Security, Testing, Monitoring
⚠️ Missing: Rollback Plan (recommended for production)

**Suggested Next Steps**:
- Add Rollback Plan section (critical for production)
- Review Security section with InfoSec team
- Create Epic in Jira and link in metadata
- Schedule TDD review meeting with stakeholders

Would you like me to:
1. Add the missing Rollback Plan section?
2. Publish this TDD to Confluence?
3. Create a Jira Epic for this project?

Confluence との連携

ユーザーが Confluence への公開を希望する場合：

I'll publish this TDD to Confluence.

Which space should I use?
- Personal space (~557058...)
- Team space (provide space key)

Should I:
- Create a new page
- Update existing page (provide page ID or URL)

その後、Confluence Assistant スキルを使って公開します。

よくあるアンチパターンと回避方法

❌ 曖昧な問題の記述

悪い例：


We need to integrate with Stripe.

良い例：


### Problems We're Solving

- **Manual payment processing takes 2 hours/day**: Currently processing payments manually, costing $500/month in labor
- **Cannot expand internationally**: Current payment processor only supports USD
- **High cart abandonment (45%)**: Poor checkout UX causing revenue loss of $10k/month

❌ スコープが未定義

悪い例：


Build payment integration with all features.

良い例：


### ✅ In Scope (V1)

- Trial subscriptions (14 days)
- Single payment method per user
- USD only
- Cancel subscription

### ❌ Out of Scope (V1)

- Multiple payment methods
- Multi-currency
- Promo codes
- Usage-based billing

❌ 決済システムのセキュリティが欠落

悪い例：


No security section for payment integration.

良い例：


### Security Considerations (MANDATORY)

**PCI DSS Compliance**:

- Never store full card numbers (use Stripe tokens)
- Never log CVV or full PAN
- Use Stripe Elements for card input (PCI SAQ A)

**Secrets Management**:

- Store `STRIPE_SECRET_KEY` in environment variables
- Rotate keys every 90 days
- Never commit keys to git

❌ ロールバック計画がない

悪い例：


We'll deploy and hope it works.

良い例：


### Rollback Plan

**Triggers**:

- Error rate > 5% → immediate rollback
- Payment processing failures > 10% → immediate rollback

**Steps**:

1. Disable feature flag `STRIPE_INTEGRATION_ENABLED`
2. Verify old payment processor is active
3. Notify #engineering and #product
4. Schedule post-mortem within 24h

重要な注意事項

ユーザーの言語を尊重する - ユーザーの依頼と同じ言語を自動的に検出し、その言語で TDD を作成します
実装ではなくアーキテクチャに重点を置く - コードではなく、決定事項と契約を記録します
概要レベルの例のみを使用する - API コントラクト、データスキーマ、図を示します（CLI コマンドやコードスニペットは示しません）
必須セクションを必ず検証する - ユーザーが省略できないようにします
決済／認証の場合 - セキュリティセクションは必須です
本番環境の場合 - モニタリングとロールバックは必須です
不明点は質問する - 不足している情報を推測せず、ユーザーの言語で質問します
十分かつ現実的に対応する - 小規模なプロジェクトに 20 のセクションすべては必要ありません
ドキュメントを更新する - TDD はプロジェクトの進行に合わせて発展させます
業界標準を使用する - Google、Amazon、RFC のパターンを参照します
コンプライアンスを考慮する - 該当する場合は GDPR、PCI DSS、HIPAA を考慮します
長期的な有効性を考慮する - 実装フレームワークが変わっても、TDD が有効であり続けるようにします

このスキルを起動するプロンプトの例

英語

「Stripe 連携の TDD を作成してください」
「新しい認証システムの技術設計書が必要です」
「API 再設計の設計ドキュメントを書いてください」
「決済連携のアーキテクチャを文書化するのを手伝ってください」
「マイクロサービスへの移行に関する技術仕様を作成してください」

ポルトガル語

「Stripe 連携の TDD を作成してください」
「新しい認証システムの技術設計書が必要です」
「API 再設計の設計ドキュメントを書いてください」
「決済連携のアーキテクチャを文書化するのを手伝ってください」
「マイクロサービスへの移行に関する技術仕様を作成してください」

スペイン語

「Stripe 連携の TDD を作成してください」
「新しい認証システムの技術設計書が必要です」
「API 再設計の設計ドキュメントを書いてください」
「決済連携のアーキテクチャを文書化するのを手伝ってください」
「マイクロサービスへの移行に関する技術仕様を作成してください」

参考資料

Industry Standards

Markdown 対応

ログインしてコメント

基本情報

作者: tech-leads-club
リポジトリ: tech-leads-club/agent-skills
カテゴリ: 開発
インストール数: 611
GitHub スター: 7,109

問題を報告