プロジェクト立ち上げフロー (Project Setup Flow)

新規プロジェクトを AI と協働で立ち上げる際の手順を定義する． 各フェーズを順番に進め，成果物を確定させてから次のフェーズに移ること．

フェーズ一覧 (Phase Overview)

※ 立ち上げフローで作成するのは 02_ENV / 03_PLAN / 04_SPEC カテゴリの成果物と，規約整備フェーズの .claude/rules/*.md のみ．05_TECH（技術設計）・06_TEST（テスト）は実装フェーズで必要になった時点で作成し，立ち上げ時に空フォルダを作らない．

開発モードとファイル構成 (Development Modes & File Layout)

プロジェクトは個人開発（solo）とチーム開発（team）の 2 モードで運用できる．モードは /setup の冒頭で選択し，.claude/project-mode に記録される（後からの切り替えは /set-mode <solo|team>）．

• .claude/rules/ はすべて共通層だが，進捗記録ルール（progress-log）だけは team モードで運用上上書きされる（進捗は CLAUDE.md／docs/PROGRESS.md ではなく GitHub Issues と git 履歴で追う．GUIDE_03）．
• team 層ファイルの配置・削除は /set-mode が一括で行い，/sync-template は .claude/project-mode を見て team 層の同期可否を判定する．team 層ファイルの正確なリストは /set-mode・/sync-template の定義に持たせており，増減時は両者を一致させること．
• テンプレート由来のファイルをプロジェクトの都合で意図的に変更した場合は，.claude/template-overrides.md（テンプレート改変台帳）に方針（keep / merge / ask）と理由を記録する（.claude/rules/template-customization.md）．/sync-template は台帳を読み，登録ファイルをテンプレート版で上書きせず方針に従って処理する．未登録でも前回同期版から改変されたファイルは上書き前に確認される．

立ち上げ中の Git 運用 (Git During Setup)

立ち上げ作業は専用ブランチ chore/project-setup の上で行う（ブランチの作成は /setup が行う）．/setup は各フェーズの成果物を最初から保存先のファイルとして書き出し，チャットには書き出したファイルの一覧と要確認点（判断してほしい点・Claude が決めた点）だけを示す．人間はエディタでファイルを読んで修正点をチャットで伝え，/setup はファイルを直接直す（差分は git diff で追える）．

• コミットは人間が /commit で行う（フェーズごとに 1 コミットを推奨）．/setup はコミット・push・PR 作成・マージを行わず，コミットメッセージ例の提示（.claude/skills/setup/reference.md「フェーズごとのコミット」）とコミット済みの確認だけを行う
• /setup は次のフェーズに進む前に作業ツリーがクリーン（コミット済み）であることを確認し，未コミットのまま進むかは人間に確認する
• 狙いは，書き出された最終形を人間がエディタで確認してからコミットできるようにし，フェーズ単位でレビュー・巻き戻しでき，中断・再開しても「どこまで終わったか」が git 履歴から辿れるようにすること
• 全フェーズ完了後，main への取り込みはユーザーが /commit push（PR 作成まで）または /commit merge（マージまで）で行う

方針決定 (Direction)

プロジェクトの全体像を明確にする．

• 人間が決めること: プロジェクトの目的，対象ユーザー，スコープ（やること・やらないこと）
• AI に依頼できること: 要件の整理・構造化，類似プロジェクトの調査，要件定義書のドラフト作成
• 成果物: PLAN_01_要件定義書.md

技術選定 (Tech Stack)

要件に基づいて技術スタックを決定する．

• 人間が決めること: 最終的な技術選定の判断，チームのスキルセットとの適合性
• AI に依頼できること: 要件に適した技術の候補提案，各候補のメリット・デメリット比較
• 成果物: ENV_01_技術スタック.md

環境構築 (Environment Setup)

開発環境を構築し，手順をドキュメント化する．初回のみの管理者作業と，メンバーが繰り返し行う構築手順を分けて整備する．

• 前提条件: 以下のツールは全プロジェクト共通で導入する．
  • git — バージョン管理（運用ルールは .claude/rules/git-conventions.md で定義）
  • gh — GitHub CLI（PR 作成・マージ等に使用）
  • Python 3.7 以上と bash — .claude/settings.json のフック（リポジトリ外アクセス制限・通知）の実行に使用．フックは bash .claude/hooks/run_python.sh 経由で起動し，python3 → python → py の順に実際に起動できるものを使う（いずれか 1 つで起動できればよい．Windows では Git for Windows 付属の bash を使う）．※ Python が見つからないとアクセス制限フックが Read・Write・Edit・Glob・Grep・Bash をすべてブロックする（通知フックは何もせず素通りする）
• 基本方針: 環境の再現性を重視し，手順書だけに頼らず構築を自動化・コード化できる方法を優先する（例: Docker，Dev Containers，Windows Sandbox，IaC ツール等）．
• 人間が決めること: 開発マシンの選定，クラウドサービスのアカウント作成，環境構築方法の選択
• 実際の構築まで行う: 手順書を書いて終わりにせず，/setup がその手順に従って実際に環境を構築し，実行して分かった誤り・前提の抜けを手順書に反映してから人間のレビューを受ける（未検証の手順書は誤りを含みやすく，最初に詰まるのがその場のユーザーになるため）．区分は次の 3 つ（詳細は .claude/skills/setup/reference.md「環境構築の実行」）
  • リポジトリ内で完結する操作（プロジェクト初期化・依存インストール・設定ファイル生成・ビルドや起動の疎通確認・gh でのリポジトリ設定）はそのまま実行する
  • ツール導入（SDK・ランタイム・CLI のインストール，docker build，dev container の起動）は実行するコマンド・バージョン・入る場所を提示して都度承認を得てから実行する
  • 外部サービスのコンソール操作・アカウント作成・対話ログイン（gh auth login 等）・クレデンシャルの発行はユーザーが行う
• AI に依頼できること: 環境構築手順書の作成，設定ファイルの生成，.gitignore の作成，Dockerfile や devcontainer.json 等の構築用ファイルの作成，GitHub リポジトリのセキュリティ設定・.github/dependabot.yml の生成（後述），検証プロファイル（.claude/verify-profile.md．任意．後述）の記入
• GitHub リポジトリのセキュリティ設定: GitHub の Settings → Code security にある Dependabot alerts（既知脆弱性の検出．"Vulnerabilities" として表示される）と Dependabot security updates はリポジトリごとに既定で OFF のため，リポジトリを作成したら必ず有効化する．モードに関わらず /setup が gh api で有効化・検証する（コマンド・検証・トラブル対応は .claude/skills/setup/reference.md「GitHub リポジトリのセキュリティ設定」）．/setup 時点でリポジトリが無い場合は，ENV_03_管理者用環境構築手順.md に転記した同じコマンドをリポジトリ作成後に実行する．
• 依存バージョン更新（Dependabot version updates）: 上記とは別に，依存パッケージを定期的に最新化する PR を作らせるため，/setup が技術スタックに合わせて .github/dependabot.yml を必ず生成する（週 1 回・マイナー／パッチをまとめる・[update] プレフィックス．エコシステム対応表と雛形は .claude/skills/setup/reference.md「依存バージョン更新の設定」）．Dependabot が作る PR と alert の処理は /deps-update で行う（ゲートを満たす PR を自動マージし，メジャー更新等は分析付きで報告．GUIDE_02「コミットルール」の例外）．
• Claude Code の権限設定（.claude/settings.json）: テンプレート同梱の permissions.allow（Bash(gh pr merge:*)）は，auto mode で ops-runner に /commit merge・/deps-update のマージを実行させるために必要なので削除しない（変更はセッション再起動後に反映）．マージが分類器に止められた場合の切り分けと対処は .claude/skills/commit/reference.md「gh コマンドが実行される前にブロックされた場合」を参照．
• スマホへのプッシュ通知（任意）: テンプレート同梱の .claude/settings.json は，作業完了（Stop）・許可待ち（Notification）・質問（PreToolUse の AskUserQuestion）で .claude/hooks/notify.py を呼び，ntfy 経由でスマホに通知する（ホスト OS・dev container のどちらでも動く）．送信先トピックが未設定なら何もしないため，受け取りたい人だけ以下を行う．
  • スマホに ntfy アプリを入れ，推測されにくいトピック名（例: claude- ＋ランダムな英数字）を購読する．トピック名を知っていれば誰でも購読・送信できるため，パスワードと同様に扱いリポジトリには書かない
  • iPhone でアプリを開くと届いているのにプッシュ通知が出ない場合は，トピックを削除してアプリを再起動し，購読し直す（ntfy の既知の問題．購読し直すと通知の登録がやり直される）
  • { "env": { "NTFY_TOPIC": "<トピック名>" } } を以下のいずれかに書く（既存の設定がある場合は env にキーを追加する．反映されない場合はセッションを再起動する）
    • dev container を使わない場合: ユーザー設定 ~/.claude/settings.json に書く．デバイスごとに 1 回でよく，全プロジェクトで共通のトピックに通知される（フックの無いプロジェクトでは何も起きない）．プロジェクトフォルダがクラウド同期（OneDrive 等）されていてもトピック名が同期されない
    • dev container を使う場合: プロジェクトの .claude/settings.local.json（gitignore 済み）に書く．ホストの ~/.claude は通常コンテナから見えないが，ワークスペースはコンテナに共有されるため，プロジェクトごとに 1 回でよい
    • 両方に書いた場合はプロジェクトの .claude/settings.local.json が優先される
  • 外部サービスを経由するため，通知には「Claude Code (リポジトリ名)」（origin リモートが無ければフォルダ名）と定型文だけを送り，コードや会話の内容は送らない
  • 完了通知はターン終了のたびには送らない．サブエージェント（/implement の coder 等）やワークフローに依頼して待っているだけのターン終了では黙り，依頼した作業が終わって本当に手が空いたときだけ「処理が完了しました」を送る（フックが Stop の入力 background_tasks を見て判定する）．一方，バックグラウンドのシェル（開発サーバー等）は動かし続けるのが普通で，対象にすると通知が永久に止まるため判定から除いている
  • 許可待ち・質問の通知は，サブエージェント起因なら本文に「（エージェント: coder）」のようにエージェント名が付く
• 成果物:
  • ENV_02_環境構築手順.md — メンバーの参加時や環境の再構築時に使う手順
  • ENV_03_管理者用環境構築手順.md — プロジェクト作成時に一度だけ行う初期設定（リポジトリ作成，GitHub リポジトリのセキュリティ設定，外部サービスの設定等）
  • ENV_04_開発コマンド.md（任意）— アプリの起動・テスト・lint・ビルド等，日常の開発で使うコマンド一覧．人間とエージェント（tester・coder，/auto-refactor・/auto-audit）がコマンドを推測せずに済むようにするための唯一の参照先とする
    • 立ち上げ時点で確定しているコマンドが無ければ作成を後回しにしてよい．実装中にコマンドが確定・変更された時点で作成・追記する（/implement の Phase 4 で自動的に見直される）
    • コマンドが増えてきたら，タスクランナー（npm scripts・Makefile 等）への集約を優先し，本ファイルは薄い一覧に保つ（「手順書より自動化・コード化」の基本方針と同じ）
  • .claude/verify-profile.md（任意）— 検証プロファイル．Claude（verifier エージェント）がアプリを操作して動作確認できるようにするための，プロジェクト固有の情報（検証手段・検証対象の環境・実行コマンドと出力先・前提条件・認証／ロール・テストデータの規約・既知のノイズ・禁止操作・シナリオのテンプレート）をまとめたファイル
    • 用意すると /verify と /implement の Phase 1b が動き，人間の動作確認の前段としてエッジケース等を Claude が先に潰す（人間の確認は無くならない．GUIDE_02）．用意しなければ Phase 1b はスキップされ，従来どおり人間が動作確認する
    • 雛形 .claude/skills/verify/profile-template.md を .claude/verify-profile.md にコピーして記入する．シナリオを実行するランナー（起動・実行・集計・後始末）はプロジェクト側に用意する（要件は雛形の「実行基盤の要件」，Web アプリ向けの実装例は同「参考実装」のリンク先）
    • 検証対象の環境は既定でローカルのみ．staging 等の検証用環境を使わせるかは人間が判断し，使わせる場合だけ「いじっても影響が無い」と判断した根拠（本番と DB が分離されている・実ユーザーがいない・外部通知や課金が無効 等）とともに許可リストへ書く．書かれていない環境に Claude は接続しない．本番はどんな場合も対象外
    • 技術スタックと開発コマンドが固まってから作る．立ち上げ時に作らず，必要になった時点で用意してもよい
    • プロジェクト所有のファイルであり /sync-template で上書き・削除されない．検証結果の出力先は .gitignore に追加する

仕様設計 (Specification)

アプリケーションの設計を行う．

• 人間が決めること: ユーザー体験の方針，ビジネスロジックの最終判断
• AI に依頼できること: アーキテクチャ設計のドラフト，データモデル定義，画面遷移図の整理
• 成果物: SPEC_01_*.md（プロジェクトの規模に応じて複数ファイルに分割）

規約整備 (Coding Standards)

技術スタックに応じたプロジェクト固有の規約を作成する． 汎用の規約（Git 運用・ドキュメント書式・ファイル命名・進捗記録・テンプレート改変記録）はテンプレートの .claude/rules/ に含まれているため，ここでは技術スタック固有の規約を追加する．

• 基本方針: 言語・フレームワークの公式ガイドラインや広く採用されている標準規約に則る（例: Effective Dart，PEP 8，Google Style Guide 等）．プロジェクト固有のルールは標準と異なる部分のみ定義する．
• 置き場所: 「コードを書くときは常に X せよ」という指示型の規約は，docs ではなく path-scoped rule（.claude/rules/*.md の frontmatter に paths: を付けたもの）として作成する．該当ファイルの編集時に自動ロードされるため，規約の読ませ忘れが起きない．アーキテクチャの背景説明や設計判断の記録など「読み物・参照資料」は従来どおり docs（04_SPEC／05_TECH）に置く．
• 人間が決めること: 標準規約でカバーされない判断（アーキテクチャパターンの選択等）
• AI に依頼できること: 標準規約を踏まえた規約のドラフト作成，参照元ガイドラインの調査
• 作成すべき rule（paths はプロジェクトの実際のディレクトリ構成に合わせて設定する）:
  • .claude/rules/coding-style.md — 命名規則，フォーマット，import 順序，型の使い方，コメントの書き方，コード内ドキュメントの規則（例: paths: ["src/**", "lib/**"]）
  • .claude/rules/project-structure.md — プロジェクトのディレクトリ構成とファイル配置ルール（paths はソースディレクトリ全般）
  • .claude/rules/testing.md — テストの種類，粒度，実行タイミング，カバレッジ基準，モック方針，テストファイルの配置規則（例: paths: ["test/**", "**/*.test.*"]）
  • .claude/rules/error-handling.md — エラーの分類，処理方法，ログ出力の方針（paths はソースディレクトリ全般）
  • ※ リファクタリング方針は言語に依存しないため，.claude/agents/refactorer.md の判断基準を共通ルールとして使用する
  • ※ 機能実装完了フローは GUIDE_02 と /implement で定義済みのため，別途作成しない
  • ※ 規約以外の運用フロー文書を docs/01_GUIDE/ に追加する場合は，team 層の GUIDE_03 との衝突を避けるため GUIDE_04 以降の番号を使う

開発計画 (Development Plan)

実装の順序とステップを決定する．

• 人間が決めること: 優先度，リリース計画，マイルストーン
• AI に依頼できること: 仕様を元にしたステップ分割の提案，依存関係の整理
• 成果物: PLAN_02_開発ステップ.md

実装開始 (Implementation)

開発計画に沿って AI と協働で実装を進める．

• 各ステップの完了時に Git 規約（.claude/rules/git-conventions.md）に従ってコミット・PR を作成する（ドキュメント書式は .claude/rules/markdown-style.md が自動適用される）．
• 仕様変更が発生した場合は，先にドキュメントを更新してから実装に反映する．

CLAUDE.md の管理 (CLAUDE.md Management)

CLAUDE.md は AI が会話開始時に最初に読むファイルであり，プロジェクトの引継ぎ情報を一元管理する． AI は毎回新しい会話で始まるため，このファイルが唯一の継続的な文脈となる．

記載すべき内容

• プロジェクト概要: プロジェクト名，目的，技術スタックの要約
• 開発進捗: 現在のステップ（最新 1 行のみ）．詳細な進捗履歴は docs/PROGRESS.md に追記する（進捗記録ルール .claude/rules/progress-log.md 参照）
• 必須ルール: AI が実装時に必ず守るべきルール（コーディング規約，コミット前チェック等の要点）
• ドキュメント一覧: docs/ 内のファイルへの参照パス

更新タイミング

• ステップの完了時に開発進捗を更新する（CLAUDE.md は最新 1 行に上書き，docs/PROGRESS.md は末尾に追記）
• ドキュメントの追加・削除・リネーム時に参照パスを更新する
• 必須ルールに変更があった場合に反映する

運用上の注意

• CLAUDE.md は AI が毎回読み込むため，簡潔に保つ．詳細は docs/ のドキュメントに委ね，CLAUDE.md には要点と参照先のみ記載する．
• 進捗記録は二段構成（CLAUDE.md = 最新 1 行 / docs/PROGRESS.md = 追記型フルログ）で管理する．詳細は .claude/rules/progress-log.md を参照．
• プロジェクト固有のルールが増えたら，docs/ に独立ファイルとして切り出し，CLAUDE.md からはリンクで参照する．