File Structure - AI Dev Organization

Repository Root

組織リポジトリのルート構成。全プロジェクト・ガバナンス・ナレッジを一元管理する。

Organization/ ├── CLAUDE.md -- マスターブループリント（PO指示書） ├── tracker.yaml -- パターン追跡（組織横断） ├── sessions.yaml -- セッション管理 ├── prompts/ -- ロールプロンプト │ ├── common.md │ ├── orchestrator.md │ ├── compliance-officer.md │ ├── researcher.md │ ├── architect.md │ ├── developer.md │ ├── reviewer.md │ ├── designer.md │ ├── sre.md │ ├── secretary.md │ ├── auditor.md │ ├── session-manager.md │ └── guard.md ├── governance/ -- ルール・ゲート定義 │ ├── rules.yaml │ ├── gates.md │ ├── escalation-matrix.md │ └── audit-log-format.md ├── knowledge/organization/ -- 組織ナレッジ（Tier 2） │ ├── process.md │ ├── architecture.md │ ├── development.md │ ├── review.md │ ├── operations.md │ └── pendulum-history.md ├── Report/ -- レポート・改善 │ ├── __memo__.md │ ├── token-usage.yaml │ ├── Daily/YYYY-MM-DD.md │ ├── Improvement/YYYY-MM-DD_{topic}.md │ └── Projects/{project}/YYYY-MM-DD.md ├── Projects/ -- プロジェクト群 │ └── {project_name}/... ├── Docs/ -- このドキュメントサイト │ └── ... └── .claude/ -- Hook・セッション管理 ├── hooks/ │ ├── guard.sh │ ├── pre-agent-compliance.sh │ ├── post-agent-checklist.sh │ ├── validate-rules.sh │ └── open-pr.sh └── sessions/ └── .heartbeat-{PPID}

Project Template

全プロジェクトは統一テンプレートに従う。新規・既存問わず、docs/ ディレクトリは必須。

Projects/{project_name}/ ├── docs/ │ ├── .knowledge/ -- Tier 1 ナレッジ │ │ ├── architect.md │ │ ├── developer.md │ │ ├── reviewer.md │ │ ├── designer.md │ │ └── sre.md │ ├── audit-log.md │ ├── tasks.yaml │ ├── resources.yaml │ ├── phase-state.yaml │ ├── 00_existing_analysis.md │ ├── 01_requirements.md │ ├── 01.5_research.md │ ├── 02a_rfc.md │ ├── 02b_design.md │ ├── 03_ui_design.md │ ├── 03.5_test_plan.md │ ├── 04_implementation.md │ ├── 05_review.md │ └── 06_deploy.md └── src/ -- ソースコード

ドキュメントファイル詳細

File	Phase	Author	Purpose
`audit-log.md`	All	Orchestrator	監査証跡。全フェーズ遷移・CO判定・エラーを記録
`tasks.yaml`	All	PO / Orchestrator	タスク管理。ステータス追跡
`resources.yaml`	Phase 4	Orchestrator	共有リソースボード（並列作業時のロック管理）
`phase-state.yaml`	All	Orchestrator	フェーズ進捗状態。グループ分割の引き継ぎに使用
`00_existing_analysis.md`	Phase 0	Orchestrator	既存コード分析。既存プロジェクト参画時も必須
`01_requirements.md`	Phase 1	PO	要件定義書
`01.5_research.md`	Phase 1.5	Researcher	技術リサーチ結果・比較分析
`02a_rfc.md`	Phase 2a	Architect	RFC -- スコープ・方向性・代替案
`02b_design.md`	Phase 2b	Architect	詳細設計（RFC承認後）
`03_ui_design.md`	Phase 3	Designer	UI/UX設計
`03.5_test_plan.md`	Phase 3.5	Reviewer	テスト計画・テスト戦略
`04_implementation.md`	Phase 4	Developer	実装記録・変更ファイル一覧
`05_review.md`	Phase 5	Reviewer	コードレビュー結果
`06_deploy.md`	Phase 6	SRE	デプロイ手順・インフラ設定

Branch Strategy (GitHub Flow)

🛑

PRマージ禁止 -- Guard が物理ブロック

この組織はPRをマージしない。gh pr merge はGuard hookが物理的にブロックする。PRは作成まで。マージはユーザーが手動で行う。

基本ルール

mainブランチへの直接コミット禁止 -- 全作業は専用ブランチで実行
作業開始前にブランチ必須 -- Phase 0で必ずmain最新から分岐。例外なし
1タスク = 1ブランチ -- 複数タスクを同一ブランチで混在させない
main最新から分岐 -- 古いmainから分岐しない
Squash merge -- PRはsquash mergeを使用

ブランチ命名規則

Prefix	Use Case	Example
`feature/`	新機能追加	`feature/card-lp/contentful-integration`
`fix/`	バグ修正	`fix/card-purchase-system/dynamic-params-404`
`refactor/`	リファクタリング	`refactor/card-lp/component-extraction`
`docs/`	ドキュメント変更	`docs/organization/unified-index`

Task Management (tasks.yaml)

プロジェクト単位のタスク管理。ステータスフローに従って進捗を追跡する。

yaml
tasks:
  - id: "card-lp_001"
    title: "Contentful統合"
    status: "in_progress"
    branch: "feature/card-lp/contentful-integration"
    subtasks:
      - title: "Contentful Client設定"
        status: "done"
      - title: "型定義作成"
        status: "in_progress"
      - title: "データ取得Hook実装"
        status: "todo"

Status Flow

🔄

ステータス遷移

backlog → todo → in_progress → in_review → done

Phase State (phase-state.yaml)

フェーズ進捗状態を管理し、Orchestratorのグループ分割起動間で状態を引き継ぐ。

yaml
flow_type: "full_pipeline"    # full_pipeline | small_task
status: "in_progress"         # pending | in_progress | completed | failed
current_phase: "phase_2a"
retry_count: 0
last_error: null

rfc_checkpoint:
  status: "pending"            # pending | approved | revision_requested
  approved_at: null

knowledge_updated:
  - "architect"
  - "developer"

phases:
  - id: "phase_0"
    name: "Preparation"
    status: "completed"
    group: 1
    completed_at: "2026-04-01T10:05:00"
  - id: "phase_1"
    name: "Requirements"
    status: "completed"
    group: 1
    completed_at: "2026-04-01T10:15:00"
  - id: "phase_1.5"
    name: "Research"
    status: "completed"
    group: 1.5
    completed_at: "2026-04-01T10:25:00"
  - id: "phase_2a"
    name: "RFC"
    status: "in_progress"
    group: 2
  - id: "phase_2b"
    name: "Detailed Design"
    status: "pending"
    group: 2

フィールド説明

Field	Type	Description
`flow_type`	string	パイプライン種別。`full_pipeline` or `small_task`
`status`	string	全体ステータス。`pending` / `in_progress` / `completed` / `failed`
`current_phase`	string	現在実行中のフェーズID
`phases[]`	array	各フェーズの詳細（id, name, status, group, completed_at）
`retry_count`	integer	リトライ回数。3回以上でユーザーにエスカレーション
`last_error`	string\|null	最後に発生したエラー内容
`knowledge_updated`	array	ナレッジ更新済みロール一覧（空配列 = 候補なし）
`rfc_checkpoint`	object	RFCチェックポイントの承認状態（full_pipeline時）