infrastructure-documenter

インフラストラクチャドキュメント作成スキル

概要

このスキルは、明確で保守しやすいインフラストラクチャドキュメントの作成を支援します。アーキテクチャ図、ランブック、システムドキュメント、運用手順、ドキュメント・アズ・コードの実践を扱います。

ドキュメント作成の理念

原則

1. 常に最新のドキュメント：実際の状況と同期させます
2. 読者を意識する：読者ごとに適切なドキュメントを用意します
3. 実行可能：どのドキュメントも、読者が何らかの作業を行えるようにします
4. バージョン管理：ドキュメントの変更をコードとともに追跡します

ドキュメントの種類

種類	対象者	目的
アーキテクチャ	エンジニア	システム設計を理解する
ランブック	運用／SRE	インシデントに対応する
API ドキュメント	開発者	システムと連携する
オンボーディング	新入社員	業務に慣れる
意思決定記録	将来の自分	決定の理由を理解する

アーキテクチャドキュメント

システムアーキテクチャの概要

# System Architecture

## Overview

[Project Name] is a [type] application that [purpose].

## High-Level Architecture

┌─────────────────────────────────────────────────────────────┐ │ ユーザー │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Vercel Edge │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Next.js App │ │ Edge Functions │ │ │ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Supabase │ │ Redis │ │ Stripe │ │ - PostgreSQL │ │ - Session │ │ - Payments │ │ - Auth │ │ - Cache │ │ - Webhooks │ │ - Realtime │ │ │ │ │ │ - Storage │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘

## Components

### Frontend (Next.js App)
- **Location**: Vercel Edge Network
- **Framework**: Next.js 14 (App Router)
- **Styling**: Tailwind CSS + shadcn/ui
- **State**: Zustand + React Query

### Backend Services
| Service | Provider | Purpose |
|---------|----------|---------|
| Database | Supabase | PostgreSQL with RLS |
| Auth | Supabase Auth | User authentication |
| Storage | Supabase Storage | File uploads |
| Cache | Upstash Redis | Session & API cache |
| Payments | Stripe | Subscriptions |
| Email | Resend | Transactional emails |

### Data Flow

1. User request → Vercel Edge
2. SSR/API Route processes request
3. Database queries via Supabase client
4. Response cached at edge (when applicable)
5. Response returned to user

## Security

### Authentication Flow
1. User signs in via Supabase Auth
2. JWT token issued and stored in cookie
3. Server validates token on each request
4. RLS policies enforce data access

### Data Protection
- All data encrypted at rest (AES-256)
- TLS 1.3 for data in transit
- Secrets stored in Vercel environment
- PII fields encrypted in database

Mermaid 図

## Request Flow

```mermaid
sequenceDiagram
    participant U as User
    participant V as Vercel
    participant N as Next.js
    participant S as Supabase
    participant R as Redis

    U->>V: HTTPS Request
    V->>N: Route to App

    alt Cached Response
        N->>R: Check Cache
        R-->>N: Cache Hit
        N-->>U: Return Cached
    else Cache Miss
        N->>S: Query Database
        S-->>N: Data
        N->>R: Store in Cache
        N-->>U: Return Response
    end

データベーススキーマ

erDiagram
    users ||--o{ projects : owns
    users {
        uuid id PK
        text email
        text name
        timestamp created_at
    }
    projects ||--o{ tasks : contains
    projects {
        uuid id PK
        uuid user_id FK
        text name
        text status
    }
    tasks {
        uuid id PK
        uuid project_id FK
        text title
        boolean completed
    }

## Runbooks

### Runbook Template

```markdown
# Runbook: [Service Name] - [Issue Type]

## Overview
Brief description of the issue and when this runbook applies.

## Severity
- **P1 (Critical)**: Complete outage
- **P2 (High)**: Degraded service
- **P3 (Medium)**: Minor impact
- **P4 (Low)**: No user impact

## Detection
How this issue is typically detected:
- [ ] Alert from [monitoring system]
- [ ] User report
- [ ] Automated check failure

## Impact Assessment
- **Users affected**: All / Segment / None
- **Data at risk**: Yes / No
- **Revenue impact**: High / Medium / Low / None

## Prerequisites
- [ ] Access to [system/dashboard]
- [ ] Credentials for [service]
- [ ] Contact info for [team/person]

## Resolution Steps

### Step 1: Verify the Issue
```bash
# Check service status
curl -I https://api.example.com/health

# Check logs
vercel logs --follow

ステップ 2：根本原因を特定する

よくある原因：

• データベース接続プールの枯渇
• メモリ上限への到達
• 外部サービスの停止
• デプロイの不具合

ステップ 3：修正を適用する

データベースの問題の場合：

# Check connection count
SELECT count(*) FROM pg_stat_activity;

# Kill idle connections
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle' AND query_start < now() - interval '1 hour';

デプロイの不具合の場合：

# Rollback to previous deployment
vercel rollback

ステップ 4：修正を検証する

# Check service health
curl https://api.example.com/health

# Monitor error rates for 15 minutes

エスカレーション

30 分以内に解決できない場合：

1. オンコールエンジニアに連絡します：[contact]
2. #incidents で関係者に通知します
3. ステータスページを更新します

インシデント後

• インシデントレポートを作成します
• 事後検証を予定します（P1／P2 のみ）
• 必要に応じてこのランブックを更新します

関連リンク

• ダッシュボード
• ログ
• メトリクス

### Database Runbooks

```markdown
# Runbook: Database Performance Issues

## Symptoms
- Slow API responses (>1s)
- Timeout errors in logs
- High database CPU in dashboard

## Quick Checks

### 1. Check Active Connections
```sql
SELECT
  state,
  count(*),
  max(now() - query_start) as max_duration
FROM pg_stat_activity
GROUP BY state;

2. 長時間実行されているクエリを確認する

SELECT
  pid,
  now() - query_start AS duration,
  query
FROM pg_stat_activity
WHERE state = 'active'
  AND now() - query_start > interval '30 seconds'
ORDER BY duration DESC;

3. テーブルサイズを確認する

SELECT
  schemaname,
  tablename,
  pg_size_pretty(pg_total_relation_size(schemaname || '.' || tablename)) as size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname || '.' || tablename) DESC
LIMIT 10;

4. 不足しているインデックスを確認する

SELECT
  relname,
  seq_scan,
  idx_scan,
  seq_scan - idx_scan AS difference
FROM pg_stat_user_tables
WHERE seq_scan > idx_scan
ORDER BY difference DESC;

解決

問題のあるクエリを終了する

SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE pid = [PID_FROM_ABOVE];

不足しているインデックスを追加する

CREATE INDEX CONCURRENTLY idx_table_column
ON table_name (column_name);

## Decision Records (ADRs)

### ADR Template

```markdown
# ADR-001: Choose Supabase for Database

## Status
Accepted

## Context
We need a database solution for [Project Name] that supports:
- PostgreSQL compatibility
- Real-time subscriptions
- Built-in authentication
- Easy local development
- Generous free tier

## Decision
We will use Supabase as our primary database and auth provider.

## Alternatives Considered

### PlanetScale
**Pros:**
- Excellent scaling
- Branching for schema changes
- MySQL compatible

**Cons:**
- No built-in auth
- No real-time subscriptions
- Additional services needed

### Firebase
**Pros:**
- Real-time built-in
- Mature platform
- Good mobile SDKs

**Cons:**
- NoSQL (not ideal for our use case)
- Vendor lock-in concerns
- Complex security rules

## Consequences

### Positive
- Single provider for DB + Auth + Storage
- Great developer experience
- Row Level Security for data protection
- Local development with supabase CLI

### Negative
- PostgreSQL-specific features tie us to provider
- Supabase still maturing (some rough edges)
- Limited to their managed offering

### Risks
- Supabase scaling limitations at high traffic
- Migration cost if we need to move

## References
- [Supabase Documentation](https://supabase.com/docs)
- [Comparison: Supabase vs Firebase](https://...)

API ドキュメント

エンドポイントのドキュメント

# API Reference

## Base URL

本番環境：https://api.example.com/v1 ステージング環境：https://staging-api.example.com/v1

## Authentication

All API requests require authentication via Bearer token.

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/v1/users

エンドポイント

ユーザー

現在のユーザーを取得する

GET /users/me

レスポンス：

{
  "id": "usr_123",
  "email": "[email protected]",
  "name": "John Doe",
  "created_at": "2024-01-01T00:00:00Z"
}

ユーザーを更新する

PATCH /users/me

リクエストボディ：

フィールド	型	必須	説明
name	string	いいえ	表示名
avatar_url	string	いいえ	プロフィール画像の URL

例：

curl -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe"}' \
  https://api.example.com/v1/users/me

エラーレスポンス

ステータス	コード	説明
400	BAD_REQUEST	リクエスト本文が無効です
401	UNAUTHORIZED	トークンがないか、無効です
403	FORBIDDEN	権限が不足しています
404	NOT_FOUND	リソースが見つかりません
429	RATE_LIMITED	リクエストが多すぎます
500	INTERNAL_ERROR	サーバーエラー

エラーレスポンス形式：

{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}

## Environment Documentation

### Environment Matrix

```markdown
# Environments

## Overview

| Environment | URL | Purpose | Deploy |
|-------------|-----|---------|--------|
| Production | https://myapp.com | Live users | Manual (main) |
| Staging | https://staging.myapp.com | Pre-release testing | Auto (main) |
| Preview | https://pr-*.vercel.app | PR review | Auto (PR) |
| Development | http://localhost:3000 | Local dev | Manual |

## Configuration

### Production
```env
NODE_ENV=production
DATABASE_URL=[Supabase Production]
NEXT_PUBLIC_APP_URL=https://myapp.com

ステージング

NODE_ENV=production
DATABASE_URL=[Supabase Staging Branch]
NEXT_PUBLIC_APP_URL=https://staging.myapp.com

開発

NODE_ENV=development
DATABASE_URL=[Local Supabase]
NEXT_PUBLIC_APP_URL=http://localhost:3000

アクセス

本番環境

• Vercel：管理者のみ
• データベース：開発者は読み取り専用、管理者は書き込み可能
• ログ：すべてのエンジニア

ステージング

• Vercel：すべてのエンジニア
• データベース：すべてのエンジニア
• ログ：すべてのエンジニア

シークレットのローテーション

シークレット	ローテーション	最終ローテーション日
データベースのパスワード	90日	2024-01-15
API キー	90日	2024-01-15
JWT シークレット	なし	初期設定

## Documentation-as-Code

### Documentation Structure

docs/ ├── README.md # ドキュメントの目次 ├── architecture/ │ ├── overview.md # システムアーキテクチャ │ ├── data-flow.md # データフロー図 │ └── decisions/ # ADR │ ├── 001-database.md │ └── 002-hosting.md ├── runbooks/ │ ├── README.md # ランブックの目次 │ ├── database.md # データベースの問題 │ ├── deployment.md # デプロイの問題 │ └── outage.md # サービス停止 ├── api/ │ └── reference.md # API ドキュメント └── onboarding/ ├── setup.md # ローカル環境のセットアップ └── contributing.md # 貢献方法

### Auto-Generated Documentation

```yaml
# .github/workflows/docs.yml
name: Generate Docs

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'docs/**'

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate API docs from OpenAPI
        run: |
          npx @redocly/cli build-docs openapi.yaml \
            --output docs/api/index.html

      - name: Generate TypeDoc
        run: npx typedoc --out docs/api/typescript

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

ドキュメントチェックリスト

アーキテクチャドキュメント

• システム概要図
• コンポーネントの説明
• データフローのドキュメント
• セキュリティアーキテクチャ
• 技術選定の決定事項（ADR）

運用ドキュメント

• よくある問題のランブック
• デプロイ手順
• モニタリングとアラート
• インシデント対応計画
• オンコール手順

開発者向けドキュメント

• ローカル環境のセットアップガイド
• API リファレンス
• 貢献ガイドライン
• コード規約
• テストガイド

メンテナンス

• ドキュメントのレビュー予定
• 担当者の割り当て
• 変更プロセスの定義
• バージョン管理戦略

このスキルを使う場面

次の場合にこのスキルを呼び出します：

• アーキテクチャドキュメントを作成するとき
• 運用ランブックを作成するとき
• 決定理由（ADR）をドキュメント化するとき
• ドキュメント構成を設定するとき
• オンボーディング資料を作成するとき
• ドキュメントの自動生成を構築するとき
• インシデント対応手順を計画するとき