technical-spec

技術仕様および設計ドキュメント

効果的な技術設計ドキュメント、RFC、Architecture Decision Record、技術評価フレームワークを作成するための専門的なガイダンスです。

基本理念

• コーディングの前に書く — 設計ドキュメントは、コストのかかる手戻りを防ぎ、チームの足並みをそろえます
• 常に更新されるドキュメント — システムの進化に合わせてドキュメントを最新の状態に保ちます
• 網羅性より明確さ — シンプルで直接的な表現により、認知負荷を軽減します
• 図をコードとして扱う — バージョン管理でき、保守可能なアーキテクチャ図を作成します
• 説明より意思決定 — 何をしたかだけでなく、なぜそうしたかを記録します

---

必ず守るべきルール

これらのルールは必須です。違反した場合、このスキルは正しく機能していません。

代替案を必須とする

すべての設計ドキュメントには、少なくとも2つの代替ソリューションを含める必要があります。

❌ FORBIDDEN:
## Solution
We will use PostgreSQL for the database.
(No alternatives considered)

✅ REQUIRED:
## Proposed Solution
PostgreSQL for primary database.

## Alternatives Considered

### Option A: PostgreSQL (Recommended)
**Pros**: ACID compliance, JSON support, mature ecosystem
**Cons**: Vertical scaling limits
**Decision**: Chosen for reliability and team expertise

### Option B: MongoDB
**Pros**: Horizontal scaling, flexible schema
**Cons**: Eventual consistency, less familiar to team
**Decision**: Rejected due to consistency requirements

### Option C: DynamoDB
**Pros**: Serverless, auto-scaling
**Cons**: Vendor lock-in, complex query patterns
**Decision**: Rejected due to query flexibility needs

図を必須とする

システム設計にはアーキテクチャ図を含める必要があります。テキストだけの説明は不可です。

❌ FORBIDDEN:
"The user sends a request to the API, which talks to the database
and returns a response."

✅ REQUIRED:
Include at least one of:
- C4 Context/Container diagram
- Sequence diagram for key flows
- Data flow diagram

Example (Mermaid):
```mermaid
sequenceDiagram
    Client->>API: POST /orders
    API->>Auth: Validate token
    Auth-->>API: User context
    API->>DB: Create order
    DB-->>API: Order ID
    API-->>Client: 201 Created

### Success Metrics Defined

**Every design must include measurable success criteria.**

```markdown
❌ FORBIDDEN:
## Goals
- Make the system faster
- Improve reliability
- Better user experience

✅ REQUIRED:
## Success Metrics

| Metric | Current | Target | Measurement |
|--------|---------|--------|-------------|
| API Latency (P95) | 500ms | <200ms | Prometheus histogram |
| Availability | 99.5% | 99.9% | Uptime monitoring |
| Error Rate | 2% | <0.1% | Error tracking |
| Throughput | 1K req/s | 10K req/s | Load testing |

リスクと緩和策

すべての設計で、リスクとその緩和策を特定する必要があります。

❌ FORBIDDEN:
(No risk section, assuming everything will work)

✅ REQUIRED:
## Risks & Mitigations

| Risk | Severity | Likelihood | Mitigation |
|------|----------|------------|------------|
| Database migration fails | High | Medium | Backup + rollback plan, test in staging |
| Third-party API unavailable | Medium | Low | Circuit breaker, fallback cache |
| Team lacks expertise | Medium | Medium | Pair programming, external review |
| Scope creep | High | High | Fixed scope document, change control |

---

このスキルを使う場面

シナリオ	ドキュメントの種類	複雑度
新機能の設計	技術設計ドキュメント	中～高
システムアーキテクチャ	C4 モデル図	中
重要な技術的決定	Architecture Decision Record（ADR）	低～中
チーム横断の提案	RFC（Request for Comments）	中～高
技術評価	技術選定マトリクス	中
API コントラクト	OpenAPI/AsyncAPI 仕様	低～中

---

ドキュメントの種類の概要

技術設計ドキュメント（TDD）

目的：機能またはシステムを実装するための設計図 対象者：エンジニア、技術リード 作成時期：重要な機能を実装する前 セクション：課題、ソリューション、代替案、リスク、タイムライン

RFC（Request for Comments）

目的：議論とフィードバックのための提案 対象者：部門横断チーム 作成時期：技術的な方向性について合意が必要なとき セクション：課題の説明、提案、トレードオフ、未解決の質問

Architecture Decision Record（ADR）

目的：単一のアーキテクチャ上の決定を記録する 対象者：現在および将来のエンジニア 作成時期：アーキテクチャ上重要な選択を行うとき セクション：コンテキスト、決定、結果、ステータス

C4 モデル図

目的：複数のズームレベルでシステムアーキテクチャを可視化する 対象者：技術系および非技術系のステークホルダー 作成時期：システム構造を伝えるとき レベル：コンテキスト、コンテナー、コンポーネント、コード

---

必須のドキュメントセクション

1. フロントマター

# Title: User Authentication System

**Author**: Jane Doe
**Status**: Proposed | In Review | Approved | Implemented
**Created**: 2025-12-18
**Last Updated**: 2025-12-18
**Reviewers**: @tech-lead, @security-team

2. 課題の説明（「なぜ」）

## Problem

**Current State**: Users authenticate via legacy session cookies, no MFA support.
**Impact**: 23% of security incidents related to compromised credentials.
**Constraint**: Must support 10K concurrent users, <200ms login latency.
**Goal**: Implement secure, scalable authentication with MFA and OAuth support.

3. 提案するソリューション（「何を」）

## Solution

Implement JWT-based authentication with:
- Access tokens (15min TTL) + Refresh tokens (7 day TTL)
- TOTP-based MFA (Google Authenticator compatible)
- OAuth 2.0 providers (Google, GitHub)
- Redis for token blacklist and session management

### High-Level Design

[Include C4 Container diagram here]

### Data Flow

1. User submits credentials → Auth Service validates
2. Auth Service generates JWT pair, stores refresh token in Redis
3. Client includes access token in Authorization header
4. API Gateway validates token, extracts user context
5. On expiry, client exchanges refresh token for new access token

4. 検討した代替案

## Alternatives

### Option A: Session-based authentication
**Pros**: Simpler implementation, server-side revocation
**Cons**: Doesn't scale horizontally, higher latency
**Decision**: Rejected - doesn't meet scalability requirements

### Option B: Auth0 (3rd party)
**Pros**: Battle-tested, feature-complete
**Cons**: $500/month cost, vendor lock-in
**Decision**: Deferred - revisit if team velocity insufficient

5. リスク評価

## Risks & Mitigations

| Risk | Severity | Likelihood | Mitigation |
|------|----------|------------|------------|
| JWT secret leak | Critical | Low | Rotate secrets quarterly, use HSM |
| Token theft (XSS) | High | Medium | HttpOnly cookies, CSP headers |
| Redis downtime | High | Low | Fallback to stateless validation |
| Clock skew issues | Medium | Medium | Use `nbf` claim, allow 5min tolerance |

6. 実装計画

## Work Breakdown

### Phase 1: Core Authentication (Week 1-2)
- [ ] JWT generation/validation service
- [ ] Password hashing (bcrypt)
- [ ] User repository interface
- [ ] Unit tests + integration tests

### Phase 2: MFA (Week 3)
- [ ] TOTP secret generation
- [ ] QR code generation
- [ ] Verification endpoint
- [ ] Backup codes

### Phase 3: OAuth (Week 4)
- [ ] Google OAuth integration
- [ ] GitHub OAuth integration
- [ ] Account linking flow

### Success Metrics
- 100% test coverage for auth logic
- <100ms token validation latency
- Zero security vulnerabilities in audit

7. 未解決の質問

## Open Questions

1. **Token storage**: Should refresh tokens be in httpOnly cookie or localStorage?
   - **Recommendation**: Cookie (XSS protection), need CSRF mitigation

2. **MFA enforcement**: Opt-in or mandatory for all users?
   - **Requires**: Product team decision

3. **Session limits**: Should we limit concurrent sessions per user?
   - **Impact**: Redis storage requirements, UX complexity

---

ベストプラクティス

明確さと言葉遣い

✅ DO:
- Use simple, direct language
- Define acronyms on first use
- Include diagrams for complex flows
- Use tables for comparisons
- Provide concrete examples

❌ DON'T:
- Use jargon without explanation
- Write walls of text
- Assume prior knowledge
- Skip the "why" behind decisions
- Create docs that become stale

図

Mermaid（シンプルなフロー）

sequenceDiagram
    Client->>API: POST /login
    API->>DB: Validate credentials
    DB-->>API: User data
    API->>Redis: Store session
    API-->>Client: JWT token

C4 を使った PlantUML（アーキテクチャ）

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

System_Boundary(c1, "Auth System") {
    Container(api, "API Gateway", "Node.js", "Routes requests")
    Container(auth, "Auth Service", "Go", "Handles authentication")
    ContainerDb(redis, "Redis", "Cache", "Sessions & tokens")
}

Person(user, "User")
user -> api : Login request
api -> auth : Validate
auth -> redis : Store token
@enduml

構成とテンプレート

組織全体で一貫したテンプレートを使用します。

• 技術設計ドキュメント → templates/design-doc-template.md
• ADR → templates/adr-template.md
• 技術評価 → reference/tech-selection.md

バージョン管理

# Store docs with code
docs/
├── architecture/
│   ├── ADRs/
│   │   ├── 001-database-selection.md
│   │   └── 002-api-authentication.md
│   └── diagrams/
│       └── c4-system-context.puml
├── design/
│   └── auth-system-design.md
└── rfcs/
    └── 2025-01-user-authentication.md

---

トレーサビリティと保守

要件と決定事項を関連付ける

## Requirements Traceability

| Requirement | Design Element | Implementation | Tests |
|-------------|---------------|----------------|-------|
| REQ-001: MFA support | Auth Service TOTP module | `auth/totp.go` | `auth/totp_test.go` |
| REQ-002: OAuth login | OAuth provider adapter | `auth/oauth.go` | `auth/oauth_test.go` |
| REQ-003: <100ms latency | Redis token cache | `middleware/jwt.go` | `benchmark/auth_bench.go` |

ドキュメントのライフサイクル

## Document Status

- **Proposed**: Initial draft, seeking feedback
- **In Review**: Under review by stakeholders
- **Approved**: Accepted, ready for implementation
- **Implemented**: Fully implemented
- **Deprecated**: No longer valid, superseded by ADR-XXX

レビュープロセス

実装前：

1. 作成者が設計ドキュメントを作成する
2. 非同期レビューのためにチームと共有する（2～3日）
3. 30～45分の説明会を設定する
4. フィードバックに対応し、ドキュメントを更新する
5. 技術リードとセキュリティ担当者（必要な場合）の承認を得る

実装後：

• リリースから1か月後にドキュメントをレビューする
• 実際に得られた知見を反映して更新する
• 何がなぜ変わったかを記録する

---

避けるべきアンチパターン

❌ Design as justification
   - Don't write docs after implementation to justify decisions
   - Write BEFORE to think through design

❌ Too much detail
   - Don't document every function and variable
   - Focus on system-level design, not line-by-line code

❌ Spec-first waterfall
   - Don't spend months on perfect design
   - Write enough to start, iterate as you learn

❌ Stale documentation
   - Don't let docs drift from reality
   - Update or delete outdated docs

❌ No alternatives analysis
   - Don't present only one solution
   - Show you considered trade-offs

❌ Missing success criteria
   - Don't forget to define "done"
   - Include measurable success metrics

---

チェックリスト

作成前

• 問題と制約を理解している
• 関係者とレビュー担当者を特定している
• 適切なドキュメントの種類を選択している
• 背景情報（既存のシステム、データ、メトリクス）を収集している

作成中

• 影響を含む明確な問題の説明がある
• 図を使って解決策を提案している
• トレードオフを含め、代替案を検討している
• リスクを評価し、緩和策を示している
• 成功基準を定義している
• タイムラインを含む作業の内訳がある
• 未解決の質問を記録している

公開前

• スペルチェックと文法の確認を行っている
• すべての図が正しく表示される
• リンクが有効である
• 頭字語を定義している
• コード例をテストしている
• レビューを依頼する担当者を特定している

実装後

• 得られた知見を反映してドキュメントを更新している
• ステータスを「実装済み」に変更している
• 重要な決定について、関連する ADR を作成している
• 必要に応じて、ランブック／運用ドキュメントを作成している

---

拡張リファレンス

このスキルを簡潔に保つため、## Quick Reference Card から始まる詳細な資料は reference/extended.md に移動しました。移動された例、コマンド一覧、チェックリスト、プラットフォームの詳細、実装テンプレートが必要なタスクでは、このリファレンスを読み込んでください。