開発者向け README

開発者向け README はマーケティング文書ではなく、「引き継ぎ書」です。 この文書一つを見るだけで、新規開発者がローカルサーバーを立ち上げ、コードの流れを頭の中で描けるようになるべきです。

コア原則

「README = 地図、詳細は docs/ へリンク」

情報を一つのファイルにすべて詰め込まず、README が全体像を提供し、詳細はリンクで辿れるようにします。

README 品質チェックリスト

README を読むだけで新しい開発者が以下の質問に答えられれば合格です。

• [ ] このシステムの目標/非目標は？
• [ ] データはどこに保存され、主要な識別子は？
• [ ] 主要なフロー 2～3 個はどのように動作するのか？
• [ ] エントリーポイントファイル 3 個はどこにあるのか？
• [ ] 頻繁に発生するバグの観測地点は？
• [ ] CI は何をどのような順序で強制するのか？
• [ ] デプロイ/ロールバックはどのように行うのか？
• [ ] ローカル実行の 3 ステップは？

必須セクション構造

0) 新規エンジニア向け高速パス (30分コース)

## 0) New Engineer Fast Path
- ✅ 1) システムの概要 → '1) System at a glance'
- ✅ 2) ローカル実行 → '4) Local Dev'
- ✅ 3) 主要なフロー 2つ → '2) Core Flows'
- ✅ 4) デバッグポイント → '8) Debugging'
- ✅ 5) 初めての作業ガイド → '10) Working Agreement'

1) システムの概要

## 1) System at a glance

### What / Why
- **目標**:
- **非目標** (行わないこと):
- **ユーザー/顧客**:
- **成功指標**:

### Architecture
(Mermaid ダイアグラムまたは画像)

### Design Principles (3～5個)
- SSOT 優先
- 安全なデフォルト
- 段階的ロード
- 決定記録 (ADR)

2) 主要なフロー (主要な動作 2～3個)

## 2) Core Flows

### Flow A: <例: Preview Render>
- **入力**:
- **処理ステップ**:
- **出力**:
- **主要なコード位置**:
- **頻繁に問題が発生する箇所**:

### Flow B: <例: Video Export>
(同じフォーマット)

3) リポジトリマップ (フォルダー構造)

## 3) Repo Map

\`\`\`
/app          # Next.js App Router
/src          # ソースコード
  /components # 共通 UI コンポーネント
  /features   # 機能別モジュール
  /lib        # ユーティリティ
/scripts      # ビルド/デプロイスクリプト
/docs         # 詳細ドキュメント
\`\`\`

- **エントリーポイント**: `app/page.tsx`
- **状態/ドメインの核**: `src/features/`
- **パイプライン**: `src/lib/pipeline/`

4) ローカル開発

## 4) Local Dev

### Prerequisites
- Node.js: v20+
- Package manager: pnpm
- OS の問題: (あれば明記)

### Setup
\`\`\`bash
# 1. 依存関係のインストール
pnpm install

# 2. 環境変数
cp .env.example .env.local
# 必要な値を入力

# 3. 実行
pnpm dev
\`\`\`

### Common Commands
| コマンド | 説明 |
|--------|------|
| `pnpm dev` | 開発サーバー |
| `pnpm test` | テスト |
| `pnpm build` | ビルド |
| `pnpm lint` | リント |

5) 設定とシークレット

## 5) Configuration & Secrets

| 変数名 | 用途 | 例 | 必須 | 露出禁止 |
|--------|------|------|------|----------|
| `DATABASE_URL` | DB 接続 | `postgresql://...` | ✅ | ✅ |
| `NEXT_PUBLIC_API_URL` | API アドレス | `https://api.example.com` | ✅ | ❌ |

### シークレット管理
- **ローカル**: `.env.local` (gitignore)
- **CI**: GitHub Secrets
- **プロダクション**: Vercel/AWS Secrets Manager

6) データモデル / ストレージ

## 6) Data Model

### 主要なテーブル
| テーブル | 説明 | 主要なフィールド |
|--------|------|----------|
| users | ユーザー | id, email, created_at |
| projects | プロジェクト | id, user_id, name |

### Storage
- S3: `s3://bucket/projects/{project_id}/`
- アップロードルール: ...

### Migration
\`\`\`bash
pnpm db:migrate
\`\`\`

7) CI/CD とリリース

## 7) CI/CD

### Pipeline
1. `validate` - リント、型チェック
2. `test` - ユニット/統合テスト
3. `build` - プロダクションビルド
4. `deploy` - デプロイ

### デプロイトリガー
- `main` → Production
- `develop` → Staging
- PR → Preview

### ロールバック
\`\`\`bash
vercel rollback
\`\`\`

8) デバッグと可観測性

## 8) Debugging

### ログの確認方法
- **ローカル**: コンソール + React DevTools
- **サーバー**: Vercel Logs / CloudWatch

### よく見るダッシュボード
- [Vercel Analytics](リンク)
- [Sentry](リンク)

### トラブルシューティング TOP 5
| 症状 | 原因 | 解決 |
|------|------|------|
| DB 接続失敗 | Docker 未実行 | `docker-compose up -d` |
| ビルド失敗 | 型エラー | `pnpm tsc --noEmit` |

9) セキュリティ

## 9) Security

### 権限モデル
- 認証: NextAuth.js
- 権限: ロールベース (admin, user)

### allowed-tools (スキルシステム)
- スキルごとのツール制限ポリシー

### 脆弱性報告
→ [SECURITY.md](./SECURITY.md)

10) 作業規約

## 10) Working Agreement

### ブランチ戦略
- `main` - プロダクション
- `develop` - 開発統合
- `feature/*` - 機能開発
- `hotfix/*` - 緊急修正

### PR ルール
- 最低 1 名のレビューア承認
- CI 合格必須
- PR テンプレートを使用

### コードスタイル
- ESLint + Prettier
- ファイルあたり 200 行推奨、300 行制限

### ADR (決定記録)
→ `/docs/adr/`

11) ドキュメントインデックス

## 11) Docs Index

- [ARCHITECTURE.md](./docs/ARCHITECTURE.md)
- [RUNBOOK.md](./docs/RUNBOOK.md)
- [ADRs](./docs/adr/)
- [API ドキュメント](./docs/api/)
- [Skills](./docs/skills/)

Mermaid アーキテクチャの例

\`\`\`mermaid
graph LR
    Browser[Browser] --> NextJS[Next.js App]
    NextJS --> API[API Routes]
    API --> DB[(PostgreSQL)]
    API --> S3[(S3 Storage)]
    API --> External[External APIs]

    Worker[Background Worker] --> DB
    Worker --> S3
\`\`\`

アンチパターン

❌ マーケティング文言のみ
   "革新的な AI ベースのソリューション..."
   → 開発者にとって無意味

❌ 実行方法なし
   "インストール後実行してください"
   → コピー＆ペースト可能であるべき

❌ 構造説明なし
   フォルダーのみ羅列
   → 各フォルダーの役割説明が必須

❌ 環境変数説明なし
   .env.example のみ存在
   → 各変数の意味/例が必須

❌ 一つのファイルにすべて
   README が 1000 行以上
   → docs/ に分割しリンク

ワークフロー

1. プロジェクト分析

# フォルダー構造の確認
find . -maxdepth 2 -type d | grep -v node_modules | grep -v .git

# package.json の確認
cat package.json | head -30

# 環境変数の確認
cat .env.example

2. README 草稿の作成

上記の 11 個のセクション構造に合わせて作成します。

3. チェックリストの検証

新規開発者の視点から 8 つの質問に答えられるか確認します。

参考文献

• Diátaxis Documentation Framework
• The Good Docs Project
• GitHub Developer Onboarding