プロジェクト立ち上げフロー (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・NotebookEdit・Glob・Grep・Bash・PowerShell）をすべてブロックする（通知フックは何もせず素通りする）
• 基本方針: 環境の再現性を重視し，手順書だけに頼らず構築を自動化・コード化できる方法を優先する（例: 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/hooks/restrict_repo_access.py）: 目的は「リポジトリ外のファイルの削除と既存ファイルの上書き（取り返しのつかない操作）だけを確実に止める」こと．テンプレート同梱の .claude/settings.json が PreToolUse で呼ぶ．

  • 位置づけ: 新規ファイルの作成・ダウンロード・ディレクトリ作成・追記は止めない（環境構築でのダウンロード・mkdir・~/.bashrc への追記等を自動で進められるようにするため）．それ以外のグレーな操作の判断は権限モード（auto mode の分類器・コマンドごとの承認等）に任せ，フックは最後の砦として削除・上書きだけを止める

  • 削除（常に拒否）: Bash の rm・rmdir・unlink・shred・truncate・find -delete／-exec rm・mv の移動元・rsync --delete の書き込み先，PowerShell の Remove-Item とそのエイリアス・Clear-Content・Move-Item／Rename-Item の移動元・[IO.File]::Delete 等，cmd /c del 等．python -c・node -e・ヒアドキュメント等のインライン実行は，削除系の呼び出し（rmtree・os.remove・unlink・fs.rm 等）があり，かつコード中にリポジトリ外のパスがある場合に拒否する．Edit・NotebookEdit（既存ファイルの書き換え）も拒否する

  • 上書き（書き込み先が既に存在する場合だけ拒否．無ければ新規作成として許可）: >・>|・&>，cp・mv・install・rsync・scp・ln -f・Copy-Item・Move-Item の書き込み先（既存ディレクトリへのコピー・移動は <ディレクトリ>/<コピー元の名前> で判定），sed -i・perl -i，tee（-a 無し）・Set-Content・Out-File／Tee-Object／Export-Csv（-Append 無し）・New-Item -Force，dd of=，curl -o・wget -O・Invoke-WebRequest -OutFile 等の保存先，Expand-Archive -Force・Compress-Archive -Force，Write ツール，インライン実行の open(..., 'w')・writeFile 等

  • 許可: 新規作成・ダウンロード・mkdir／New-Item -ItemType Directory・touch・追記（>>・tee -a・Add-Content・Out-File -Append）．chmod・chown・Set-Acl も中身が失われないため許可する

  • cd・pushd・Set-Location を追跡し，~ と $HOME を展開してから判定する．基準はリポジトリのルート（CLAUDE_PROJECT_DIR）で，システム一時ディレクトリ（/tmp・%TEMP%．スクラッチパッドを含む）と /dev/null・$null 等は削除・上書きも許可する

  • 読み取り: Read・Glob・Grep，Bash・PowerShell の読み取りはリポジトリ外も許可する．読んだファイルの内容は Claude の API に送信されるため，リポジトリ外を読ませることの是非はプロジェクトごとに判断する．読ませたくない場所（~/.ssh・~/.aws・他案件のフォルダ等）は禁止リスト .claude/repo-access.json に書く（任意．無ければ禁止リストは空）．禁止リストに該当するパスは読み取り・書き込みとも拒否する．Glob・Grep・再帰的に読むコマンド（grep -r・find・Get-ChildItem 等）は，リポジトリ外の検索起点の配下に禁止パスがある場合も拒否する

    {
      "deny_read": ["~/.ssh", "~/.aws", "C:/Users/me/source/other-project", "secrets"]
    }
    

    • パスは絶対パス・~ 始まり・リポジトリルート相対で書く．ファイルが壊れている（JSON として読めない等）場合は禁止リストを空として扱い，警告を出す
    • プロジェクト所有のファイルであり，テンプレートには含まれないため /sync-template で上書きされない．人によって守りたい場所が違う場合は各自の場所も含めて書くか，各自が後述の permissions.deny を .claude/settings.local.json に書く

  • 限界: コマンド文字列の静的解析のため原理的に完全には防げない．変数展開（$DIR 等．~・$HOME・$env:USERPROFILE・一時ディレクトリ系以外は解決しない），スクリプトファイル経由の操作，xargs 等パイプで渡したパス，エイリアス・関数，エンコードされたコマンド，未対応コマンドによる削除・上書き，インライン実行中の未対応の書き方（変数に入れたパス・Perl の open 等）は検出できない．既存かどうかはフック実行時点で判定するため，同じコマンド内で先に作ったファイルを上書きする場合等は許可される．逆に，インライン実行で削除系の呼び出しとリポジトリ外のパス（文字列やコメント中のものも含む）が同時に現れると，削除対象でなくても拒否されることがある．cmd /c の引数のうち /opt のように / の後に要素が 1 つだけのパスは，スイッチ（/mir 等）と区別できないため判定の対象外になる．また Glob・Grep を省略した検索起点（リポジトリ内）では，リポジトリ内の禁止パスを含む検索までは止めない

  • 拒否されたときの運用: リポジトリ外の削除・上書きの最終判断は人間が持つ．フックに拒否されても，Claude は別の書き方（変数経由・スクリプトファイル経由・python -c 等）で迂回しない．必要な操作であれば，Claude は実行するコマンドをそのまま提示して依頼するので，ユーザーが内容を確認し，プロンプトで ! <コマンド> として自分で実行する．フックが検出できない書き方であっても，リポジトリ外のファイルの削除・上書き（既存ファイルの移動を含む）は同じ扱いとする（CLAUDE.md「手動確認が必要な作業」）．禁止リストによる読み取りの拒否は「読ませたくない場所」の指定なので，Claude は迂回して読まず，! での実行依頼もしない

  • ! で実行したコマンドにはこのフックはかからない（実機で確認済み）．Claude が提示したコマンドは，削除・上書きの対象が意図どおりかを確認してから実行する

  • 確実性が必要な場合は以下を併用する

    • OS のフォルダ権限（Claude Code を実行するユーザーに守りたいフォルダの書き込み権限を与えない．dev container ならリポジトリだけをマウントする）
    • settings.json の permissions.deny（例: "Read(~/.ssh/**)"・"Edit(~/.ssh/**)"．Claude Code 本体が Read・Edit 系ツールを確実に止める）
    • Bash・PowerShell の実行前に確認を挟む権限モード（auto mode や --dangerously-skip-permissions を使わず，コマンドごとに承認する）
    • バックアップ（Git 管理外の大事なデータは定期的に退避する）
• スマホへのプッシュ通知（任意）: テンプレート同梱の .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 からはリンクで参照する．