Project Standards

# Project Standards — 共通ルール v2.0

## なぜルールが必要か

このルールの目的は **AI Agent の効率を最大化** すること。

CLAUDE.md が整備されたプロジェクトでは、AI Agent が正確にコンテキストを把握し、
適切なコード変更・テスト・デプロイを行える。逆に、構造が不明確なプロジェクトでは
Agent がコンテキスト理解に時間を費やし、品質も低下する。

共通ルールを定義することで:
- **AI Agent が即座にプロジェクトを理解できる**（CLAUDE.md, agents/, settings.json）
- **プロジェクト間の移動コストが下がる**（同じ構造 → 同じ思考パターン）
- **事業設計が明文化され、判断基準が一貫する**（CONCEPT, LEAN-CANVAS, BRAND-IDENTITY）
- **vitals スコアが客観的なフィードバック機構として機能する**

### ゴールドスタンダード: ai-navigator

ai-navigator (AI Solo Builder) を Tier 3 のリファレンス実装として位置づける。
CLAUDE.md, docs/, .claude/, specs/ の構成が最も整っており、他の Premium プロジェクトはこれを目標水準とする。

---

## Tier 分類

| Tier | 名称 | 対象 | vitals aiAgent 目標 |
|------|------|------|-------------------|
| **3** | Premium | ユーザーがいるアクティブプロダクト | >= 70 |
| **2** | Standard | アクティブ開発中のツール/サービス | >= 50 |
| **1** | Minimal | 静的サイト/ポリシー/低頻度更新 | >= 30 |

Tier 割り当ては `standards/project-tiers.json` で管理する。

---

## Tier 1 — Minimal（全リポジトリ共通）

全プロジェクトが満たすべき最低限の基準。3ファイル。

### 1. README.md

**目的:** 初めてリポジトリを見た人が5分以内に概要を理解しセットアップできる。

**必須セクション:**
- プロジェクト名 + 1行説明
- セットアップ手順（git clone 〜 起動まで）
- 主要コマンド一覧

### 2. CLAUDE.md

**目的:** AI Agent がプロジェクトの全体像を把握し、適切に作業できる。

**Tier 1 必須セクション:**
```markdown
## Mission    — プロジェクトの目的（1-2文）
## File Structure — 主要ディレクトリとファイルの説明
## Dev Commands   — 開発・ビルド・テスト等のコマンド一覧
```

### 3. .gitignore

**目的:** 不要ファイル（node_modules, .env, build等）がリポジトリに入らない。

---

## Tier 2 — Standard（Tier 1 + 5項目）

アクティブ開発のプロジェクトに必要な AI Agent 体制と品質基盤。

### 4. CLAUDE.md 拡張セクション

Tier 1 の3セクションに加え、以下を追加:

```markdown
## Architecture       — 技術スタック一覧、システム構成の概要
## Design Principles  — 設計原則（3-5項目）
## Constraints        — 技術的制約・ビジネス制約
## Environment Variables — 環境変数の一覧と用途
```

### 5. .claude/settings.json

**目的:** AI Agent の権限とモデル割当を明示的に管理する。

```json
{
  "permissions": {
    "allow": ["Bash(npm test)", "Bash(npm run lint)"],
    "deny": []
  }
}
```

### 6. .claude/agents/（最低1つ）

**目的:** プロジェクト固有の専門エージェントを定義する。

各エージェントファイルは以下のフロントマターを持つ:
```yaml
---
name: developer
model: sonnet
description: General-purpose development agent
tools: [Read, Write, Edit, Bash, Glob, Grep]
---
```

### 7. CONTRIBUTING.md

**目的:** コントリビューション手順を統一する。

**必須セクション:**
- ブランチ命名規約（feat/, fix/, chore/, docs/）
- コミットメッセージ規約（Conventional Commits）
- PR 手順
- AI Agent との協働方法

### 8. .env.example（環境変数がある場合）

**目的:** 必要な環境変数を列挙し、新規参加者がすぐに設定できる。

キーのみリストし、シークレット値は絶対に含めない。コメントで用途を説明する。

### 9. CI/CD（build + lint）

**目的:** コードの品質を自動でガードする。

`.github/workflows/` に最低限 build と lint のジョブを設定する。

---

## Tier 3 — Premium（Tier 2 + 以下）

ユーザーがいるプロダクトの完全な運用基盤。事業設計・AI Agent 運用・品質管理を網羅する。

### ゴールドスタンダード参照

> ai-navigator (AI Solo Builder) を基準実装として参照する。
> 各項目の「参考」欄に ai-navigator の該当ファイルを記載。

---

### A. 事業設計（Business Design）

#### 10. docs/CONCEPT.md — コンセプトシート

**参考:** `ai-navigator/docs/CONCEPT.md`

プロダクトの存在意義を定義する最上位文書。全ての判断はここに立ち返る。

**必須セクション:**

| セクション | 内容 | 例（ai-navigator） |
|-----------|------|-------------------|
| ビジョン | 1文で表現される到達目標 | 「毎日まずこのサイトを見よう、というもの」 |
| ターゲット | プライマリ/セカンダリ顧客の属性・特徴・ニーズ | AIソロビルダー / AI活用に興味のある技術者 |
| 差別化 | 競合比較表（機能軸×プロダクト軸マトリクス） | vs HN / Ben's Bites / TLDR / 日本語AIメディア |
| 独自の価値 | 数字で説明できる差別化要素 | グローバル日本語化、定量データ必須、NVA |
| コンテンツ/機能体系 | 提供する価値の分類・種別定義 | Digest / News / Product / Case Study / Knowledge |
| 進化パス | Phase 1→2→3 のロードマップ | キュレーション → ビルドログ → コミュニティ |
| UIベンチマーク | デザインの参考先と参考ポイント | TLDR.tech / The Verge / Techmeme |
| KPI | 定量的成功指標と計測方法 | 記事数100+ / PV 1,000/月 / 検索100/月 |
| 技術スタック | フレームワーク・ホスティング・コスト | Next.js + Vercel / 月額 ¥0 |

#### 11. docs/LEAN-CANVAS.md — リーンキャンバス

**参考:** `ai-navigator/docs/LEAN-CANVAS.md`

Ash Maurya のリーンキャンバスフォーマットに基づく事業設計の全体像。

**9セクション全て必須:**

| # | セクション | 必須内容 |
|---|-----------|---------|
| 1 | 課題（Problem） | ユーザーが抱える3つの具体的課題 + 既存代替手段の列挙 |
| 2 | 顧客セグメント | メインターゲットの属性・特徴（年齢層、職種、行動特性） |
| 3 | 独自の価値提案（UVP） | 1文で表現。「何を」「誰に」「なぜ独自か」 |
| 4 | ソリューション | 課題に対する具体的な解決策（3-4項目） |
| 5 | チャネル | Phase別のユーザー獲得経路（SEO, SNS, Newsletter等） |
| 6 | 収益の流れ | Phase別の収益化戦略（無料→アフィリエイト→有料等） |
| 7 | コスト構造 | 月額コスト一覧表（ホスティング、ドメイン、API等） |
| 8 | 主要指標 | Phase別の定量KPI + 計測方法 |
| 9 | 圧倒的な優位性 | 模倣困難な競争優位（2-4項目） |

#### 12. docs/BRAND-IDENTITY.md — ブランドアイデンティティ

**参考:** `ai-navigator/docs/BRAND-IDENTITY.md`

プロダクトのブランドを包括的に定義する文書。

**必須セクション:**

| セクション | 内容 |
|-----------|------|
| ブランドコンセプト | 名前の意味、タグライン、サブコピー候補 |
| パーソナリティ | ブランドを人格として表現。5つの柱（例: Fast, Data-Driven, Actionable, Passionate, Honest） |
| ビジュアルアイデンティティ | カラーパレット（用途/色/コード/意味の表）、タイポグラフィ、デザイン原則 |
| 編集方針 | 文体ルール（です/ます調 or だ/である調）、NGルール |
| ブランドの約束 | ユーザーへの5つのコミットメント |

#### 13. 競合分析・ベンチマーク

CONCEPT.md 内、または独立した docs/BENCHMARKS.md として。

**必須内容:**
- 競合比較表（最低3つの既存プロダクト/サービスとの比較）
- 各軸の説明（言語、ターゲット、形式、独自機能等）
- UIベンチマーク（デザインの参考先、何を参考にするか）

---

### B. AIエージェント体制（AI Agent）

#### 14. .claude/agents/（2つ以上の専門エージェント）

**参考:** ai-navigator は 4 エージェント体制

```
news-scout     (sonnet) — ニュース収集・スクリーニング
article-writer (sonnet) — 記事作成
quality-checker (haiku) — 品質チェック
publisher       (haiku) — デプロイ・公開
```

**要件:**
- プロジェクトのドメインに特化したエージェントを2つ以上定義
- 各エージェントに適切なモデルを割当（品質重視 = sonnet、定型 = haiku）
- エージェント間の責任境界を明確にし、1つに全タスクを集中させない
- フロントマターに name / model / description / tools を宣言

#### 15. .claude/skills/（3つ以上のスキル）

**参考:** ai-navigator は 7 スキル

```
article-template    — カテゴリ別テンプレート
brand-voice         — ブランドトーン・文体ルール
editorial-standards — 編集基準チェックリスト
news-curation       — キュレーション手順
nva-process         — ニュースバリュー評価手順
research-sources    — 巡回先クイックリファレンス
site-config         — 技術仕様・デプロイ手順
```

**要件:**
- CLAUDE.md に全知識を詰め込まず、ドメイン知識をスキルファイルに分離
- settings.json でエージェント × スキルのマッピングを定義
- 各スキルは「いつ使うか」が明確であること

#### 16. .claude/hooks/ — 自動化フック

**要件:**
- PreToolUse / PostToolUse / UserPromptSubmit のいずれかを設定
- 例: セッション開始時のプロジェクト状態確認、コミット前の lint/test 実行

---

### C. 運用・品質管理（Operations）

#### 17. docs/WORKFLOW-ARCHITECTURE.md — ワークフロー設計書

**参考:** `ai-navigator/docs/WORKFLOW-ARCHITECTURE.md`（20,011 bytes, 5フェーズ×2種）

**必須内容:**
- ワークフロー種別ごとのフェーズ定義
- 各フェーズの担当エージェント・入出力・品質ゲート
- 自動化されている部分と手動の部分の明示
- cron / スケジュール設定（該当する場合）

#### 18. docs/CHECKLIST.md — 品質チェックリスト

**参考:** `ai-navigator/docs/CHECKLIST.md`（16,556 bytes）

**必須内容:**
- Pre-commit チェック項目
- Pre-push チェック項目
- 公開前ゲートチェック項目
- 定期品質チェック項目
- 各項目は Yes/No で判定可能な具体的基準

#### 19. specs/ — 仕様駆動開発（SDD）

**参考:** `ai-navigator/specs/`（content-policy, content-model-db）

**要件:**
- プロダクトの重要な仕様を正規文書として格納
- specs/ が Single Source of Truth — 他の docs/ は specs/ を参照する
- 複数ドキュメントでの仕様重複を排除し、情報の不整合を防ぐ

---

### D. 技術基盤（Technical）

#### 20. ARCHITECTURE.md — アーキテクチャ設計書

**必須セクション:**
- 技術スタック一覧と選定理由
- ディレクトリ構造の説明
- データフロー図
- API 設計（ルート一覧）
- デプロイ構成
- 主要な技術的意思決定の記録

#### 21. CI/CD パイプライン（build + lint + test + deploy）

`.github/workflows/` に全ステージをカバーする GitHub Actions を設定。

#### 22. テストフレームワーク + 実行可能なテスト

Unit / Integration / E2E のいずれかで、`npm test` 相当で実行可能であること。

---

## CLAUDE.md 構造の比較

| セクション | Tier 1 | Tier 2 | Tier 3 |
|-----------|--------|--------|--------|
| Mission | ● | ● | ● |
| File Structure | ● | ● | ● |
| Dev Commands | ● | ● | ● |
| Architecture | | ● | ● |
| Design Principles | | ● | ● |
| Constraints | | ● | ● |
| Environment Variables | | ● | ● |
| 事業設計文書テーブル（docs/へのリンク） | | | ● |
| エージェント体制表 | | | ● |
| スキル一覧表 | | | ● |
| ワークフロー概要 | | | ● |
| デザイン仕様（カラー/タイポグラフィ/レイアウト） | | | ● |
| コンテンツ構造 | | | ● |
| 重要なポリシー・制約 | | | ● |
| Testing Strategy | | | ● |
| Deployment | | | ● |

---

## ドキュメント間の関係性と情報の一元管理

Premium プロジェクトはドキュメント数が多くなるため、情報の重複と不整合が最大のリスクとなる。

### 原則: Single Source of Truth

```
specs/           ← 仕様の正規定義（canonical）
  ↑ 参照
docs/            ← 運用文書・設計文書（specs/ を参照、重複記述しない）
  ↑ 参照
CLAUDE.md        ← エージェント行動指針（docs/ へのリンクテーブル、要約のみ記述）
  ↑ 参照
.claude/skills/  ← エージェント用クイックリファレンス（docs/ の要約版）
```

### NGパターン

- ❌ 同じ仕様を CLAUDE.md と docs/ と skills/ に3重記述
- ❌ specs/ に正規定義があるのに、docs/ に古いバージョンが残る
- ❌ CLAUDE.md に全知識を詰め込む（ファイルサイズ肥大 → Agent のコンテキスト浪費）

### OKパターン

- ✅ CLAUDE.md に docs/ テーブルを置き「詳細は docs/CONCEPT.md を参照」
- ✅ skills/ に docs/ の要約版を置き「正規の情報は docs/WORKFLOW-ARCHITECTURE.md」と注記
- ✅ docs/ に specs/ へのリンクを置き「canonical 定義は specs/content-policy/spec.md」と注記

---

## 適用方法

```bash
# Tier 1 プロジェクトに標準を適用（dry-run）
pnpm init:standards ~/dev/app-policies --tier 1 --dry-run

# Tier 2 プロジェクトに適用
pnpm init:standards ~/dev/ai-web-inspector --tier 2

# Tier 3 プロジェクトに適用
pnpm init:standards ~/dev/history-quiz-app --tier 3
```

スクリプトは既存ファイルを上書きしない（非破壊的）。

---

## 計測とフィードバック

```
ルール適用 → CLAUDE.md/agents/settings/docs 整備
          → vitals aiAgent スコア向上
          → Standards Compliance 向上（ダッシュボードで可視化）
```

---

## 参照

- 定義ファイル: `standards/project-tiers.json`
- テンプレート: `templates/standards/`
- 適用スクリプト: `scripts/init-project-standards.js`
- ゴールドスタンダード: `~/dev/ai-navigator`