auto-repo-setup

自動リポジトリセットアップ

ユーザーの普段の作業方法を変えずに、リポジトリを使える状態にします。 セットアップは、特定の役職の人向けの特別なインターフェースではなく、 証拠に基づいてリポジトリに対応する作業として扱います。

入口での振り分け

変更を加える前に、依頼を分類します。「セットアップ」という語が含まれている というだけで、複数のモードを組み合わせてはいけません。

ユーザーが望む結果	モード	最初のアクション
「動かない」、依存関係が不足している、新しいマシン	環境の修復	プロジェクトの指示を読み、実際のスタックを特定する
「作業前に同期して」、「最新の状態を取得して」	セッションのルーチン	プロジェクトの指示に従うか、ユーザーの自然言語による依頼を実行する
フックの出力が繰り返される、または予期しない	フックの診断	設定を編集する前に、登録数と発火したセッション数を数える
チームメイトに再現可能な引き継ぎが必要	リポジトリの引き継ぎ	既存のオンボーディングを監査し、不足している運用上の契約だけを補う
コミット、プッシュ、競合、漏えいしたシークレットや履歴	Git の安全対策	変更する前に references/git_safety.md を読む
最初のプロンプトより前に動作させる必要がある	起動時の自動化	references/startup_automation.md を読み、フックのゲートを通過する

運用の原則

1. 役割から能力を推測しないでください。 ユーザーが示した習熟度に合わせます。 協力者がエージェントに「先にリモートを同期して」と伝えることはできます。 ユーザーが求めていない限り、ランチャー、ショートカット、ウィザードを 勝手に作らないでください。
2. 望む結果を満たす最小限の仕組みを使います。 次の順に優先してください。 エージェントへの直接の指示 → プロジェクトの指示 → 明示的なコマンド → ライフサイクルフック。フックは、単なる文よりも専門的な手段ではありません。
3. 作成する前に権威ある情報を確認します。 現在のユーザー依頼を読み、 次にプロジェクトの指示、オンボーディングや運用手順書、マニフェスト、 ロックファイル、実際のコマンド出力を確認します。リポジトリが宣言していない ONBOARDING.md、Python、uv、ffmpeg、.env を必須にしてはいけません。
4. ユーザーの作業を保護します。 セットアップを成功したように見せるために、 ローカルの変更を自動で stash、マージ、リベース、強制適用、破棄、上書きしては いけません。このタスクで分離された変更の、すでに許可された反映には、 許可された共有チェックアウトへの反映 に基づき、リポジトリで定められたスコープ付きワークフローを使用できます。 ただし、無関係なローカルコミットや共有中の未コミット作業を統合する権限は 与えられません。
5. 反証可能な成功状態を定義します。 「依存関係をインストールした」だけでは 不十分です。プロジェクト本来のスモークテストまたは起動コマンドを実行し、 目に見える結果を確認してください。
6. 原因が判明するまでは、診断を読み取り専用にします。 インストール、 設定の編集、フックの登録、コミット、外部への書き込みには、ユーザーの依頼が 示す権限が必要です。破壊的な操作や公開を伴う操作には、明示的な承認が必要です。

ワークフロー A — 環境の修復

A1. プロジェクトの構成を確認する

存在するファイルのみを、次の順に読みます。

1. AGENTS.md と AGENTS.override.md
2. CLAUDE.md とスコープが適用されるプロジェクトルール
3. ONBOARDING.md またはリポジトリで指定されたセットアップ／運用手順書
4. README.md
5. マニフェスト、ロックファイル、タスクランナー、CI、コンテナー設定
6. 依頼がエージェントの動作に関係する場合に限り、既存の Claude/Codex 設定

オンボーディングガイドがない場合は、権威あるマニフェストと実際に使用されている コマンドからセットアップ手順を推測します。長期的に使える引き継ぎが依頼に 含まれていない限り、ドキュメントを作成するかどうかを確認するために作業を 止めないでください。

A2. 読み取り専用で機能を棚卸しする

Python 3.10 以降の実行環境がすでに利用可能な場合は、リポジトリのルートに対して、同梱の scripts/check_env.py を実行します。このスクリプトは、宣言されているエコシステムを検出し、関連するツールチェーンのみを確認します。依存関係のインストールや、シークレットの値の読み取りは行いません。Python 自体が不足している前提条件である場合は、監査を実行するためだけに Python をインストールするのではなく、代わりに同じ読み取り専用のマニフェストの棚卸しを直接行ってください。

uv run python scripts/check_env.py --repo <repo-root>
uv run python scripts/check_env.py --repo <repo-root> --json

この棚卸しは証拠として扱い、プロジェクトのセットアップ仕様として扱わないでください。カスタムの運用手順書や CI ワークフローでは、汎用的な棚卸しでは推定できないツールが必要な場合があります。

想定される結果：

• exit 0：マニフェストから推定されたすべてのツールチェーンが利用可能です。
• exit 1：推定された前提条件のうち、1 つ以上が不足しています。
• exit 2：リポジトリまたはそのメタデータを安全に調査できませんでした。

A3. 根本原因を修正する

要件を満たせなかった場合は、次の手順を実行します。

1. 正確なコマンド、終了コード、標準出力、標準エラーを記録します。
2. プロジェクトガイド、マニフェスト、ロックファイル、設定、ランタイムログなど、宣言元をたどって失敗の原因を特定します。
3. 起動設定と読み取り専用の調査結果に基づいて、対象コマンドが実際に使用するランタイムを特定します。必要に応じて、インタープリターとパッケージ環境、コンテナーイメージ、サービスの起動方法を確認します。隔離された検証環境は、そのコマンドの実行環境とは別に保ちます。実行環境がすでに要件を満たしている場合は、その状態を維持し、再インストールせずに A4 に進みます。
4. 実行環境を変更する前に、影響を受ける進行中の作業と既存の権限を確認します。セットアップの許可は、他の作業を中断する許可を意味しません。変更によって作業に支障が出る場合は、調整するか完了を待ちます。プロセスを強制終了または再起動するのではなく、未解決のアクティベーション手順を正確に報告します。
5. プロジェクトの既存の更新手段を通じて、プロジェクトに適合する最小限の修正を行い、対象外の有効な依存関係と設定を維持します。
6. 次に進む前に、失敗したチェックを再実行します。

最初の手段として、再起動、すべての再インストール、またはパッケージマネージャーの切り替えを行わないでください。.env や認証情報の内容を表示しないでください。値を出力せずに、有無と動作を確認します。

A4. 製品の動作経路を検証する

プロジェクトで文書化されているスモークテスト、ビルド、または起動コマンドを実行します。いずれも存在しない場合は、CI またはタスクランナーの設定からコマンドを導き出し、導出したことを明記します。終了コードが 0 であることだけでなく、観測可能な結果を検証します。

依存関係を修正した場合は、特定した実行環境で新しいプロセスを起動し、インストール済みのバージョンを読み取ってから、製品チェックを実行します。ロックファイルの変更や隔離環境へのインストール成功だけでは、実行環境が更新されたことの証明にはなりません。すでに実行中のプロセスや別のマシンは、個別に検証していない限り、報告の対象外とします。対象範囲を広げるためだけに、それらを再起動しないでください。ホストされた依存関係のアラートについては、解決済みと報告する前に個別に確認します。

以下を報告します。

• 問題の内容と、その証拠
• 変更した内容
• 正確な検証手順と結果
• ユーザーに残された作業、または権限上の阻害要因

ワークフロー B — Git の定期同期

「作業開始前に同期する」場合は、リポジトリを使用するエージェント間で共有する短いプロジェクト指示を優先してください。定期的な手順は次のとおりです。

1. ブランチ、上流ブランチ、作業ツリーの状態を確認します。
2. タスクにすでに承認済みの成果物の受け渡しが含まれ、リポジトリで、共有 HEAD、インデックス、WIP のうち無関係なものを維持できる、使用可能なスコープ付きツールが宣言されている場合は、承認済みの共有チェックアウトでの受け渡しを使用します。作業ツリーが汚れている、または履歴が分岐しているというだけで、受け渡しを保留する必要はありません。
3. それ以外の場合、作業ツリーがクリーンであれば、git pull --ff-only を実行します。
4. ローカル変更がある場合は、自動で stash したり pull したりせず、状態を説明します。
5. ローカルとリモートの履歴が分岐している場合は、自動でマージ、リベース、強制更新を行わず、状態を説明します。
6. ネットワークに障害が発生した場合はその旨を伝え、ユーザーのタスクをローカル版で安全に進められる場合に限り、ローカルで続行します。

共同作業者は、単に次のように伝えることもできます。

作業を始める前に、最新のリモート版と同期してください。

これは通常のエージェント指示であり、機能が劣る代替策ではありません。

この定期処理を自動化するためだけに SessionStart を登録しないでください。静的な動作は AGENTS.md/CLAUDE.md に記述します。シェルプロセスに隠すのではなく、エージェントが状況を確認し、例外的な Git の状態に対処できます。

ワークフロー C — リポジトリの引き継ぎ

ユーザーが継続的に利用できる引き継ぎ資料を希望しており、既存のプロジェクトマップにその資料がない場合に限り、オンボーディング資料を作成または改訂します。

references/onboarding_template.md はチェックリストとして使用し、Python／動画のテンプレートをそのまま使わないでください。

• マニフェストと実際のプロジェクトコマンドから前提条件を導き出します。
• 各コマンドの実行後に予想される出力を記載します。
• 初回のみのセットアップと日常的な使用方法を分けます。
• 実際に確認された障害に対する復旧方法を含めます。
• プロジェクト指示を運用上の SSOT とし、値の重複を避けます。

ユーザーにとって重要な対象 OS ごとに、すべてのコマンドを検証してください。

ワークフロー D — 起動時の自動化とフックの診断

フックを追加または変更する前に、references/startup_automation.md を読んでください。

まず、繰り返し出力される原因を診断する

1. プロジェクト、ローカル、ユーザー、管理対象、プラグインの各フック登録を列挙します。
2. 該当する登録の数を数えます。出力が 3 回あったからといって、「登録が 3 つある」と推測しないでください。
3. どのルートセッション、再開、コンパクション、サブエージェントでそれらが実行されたかを特定します。
4. イベントのマッチャーと現在のランタイムペイロードを検証します。
5. 変更案を提示する前に、根本原因を明らかにします。

フックの条件を満たした後にのみインストールする

同梱の初期化ツールは Claude Code 専用で、軽量な起動時コンテキスト通知のみをインストールします。無関係な設定を維持し、起動時マッチャーを追加して、ガイドのパスを検証したうえでアトミックに書き込み、冪等性を保ちます。

まずプレビューします。

uv run python scripts/init_session_start_hook.py \
  --repo <repo-root> \
  --guide ONBOARDING.md \
  --dry-run

プロンプト前の挿入が本当に必要であることをユーザーが確認した後、--dry-run を付けずに同じコマンドを実行します。--remove を使って、管理対象のエントリだけを削除します。

類推によって、この設定を Codex にコピーしないでください。Codex のプロジェクト動作は通常 AGENTS.md に記述します。Codex のフックが本当に必要な場合は、インストール済みバージョンのルート／サブエージェントの動作とペイロードを最初に確認してください。

Git の安全性

コミット、プッシュ、競合解決、または履歴の書き換えを行う前に、references/git_safety.md をお読みください。特に重要なルールは次のとおりです。

• 意図したパスだけをステージする；
• このセッションでユーザーがバイパスを明示的に入力していない限り、フックをバイパスしない；
• プッシュ前に、ホスティングサービスでリポジトリの公開範囲を確認する；
• 公開プッシュ、強制プッシュ、または履歴の書き換えの前に、明示的な承認を得る；
• 競合はプロジェクトの意図に基づいて解決し、「ours」または「theirs」を機械的に選ばない；
• 履歴のクリーンアップが完了したと判断する前に、漏えいした認証情報を失効させる。

一般公開するコンテンツのレビューには、references/pii_guard.md を使用してください。スキャナーで問題が検出されなくても、意味内容のレビューは必要です。

通常の Git コミット前にアーティファクトを自動検証するには、コミット時のチェック手順を使用してください。Agent と手動コミットの両方に適用される Git フック、ステージ済み入力の検証、既存フックの保持について説明しています。タスクの分離を維持しつつ、リポジトリ固有の LFS およびセキュリティ設定を保持する必要がある場合は、分離チェックアウトの準備を使用してください。

読み取り専用の履歴スキャンには、既存のスクリプト scripts/sanitize_history.sh を引き続き使用できます。このスクリプトは履歴を書き換えることはありません。検出結果は候補として扱い、明示的な承認を得ずに書き換えコマンドを実行しないでください。

相互レビューの適用範囲

承認済みの作業によって、セキュリティポリシー、共有ライフサイクルフック、CI/CD、依存関係、または破壊的な Git の動作が実質的に変更される場合は、相互レビューを実施してください。通常のセットアップ確認や、プロジェクトの指示を一行追加するだけの作業でレビュー チームを立ち上げないでください。すべての指摘について、発生確率、コスト、実際の使用状況、直接的な検証に基づいて絞り込んでください。

リソース

• scripts/check_env.py — スタックを考慮した読み取り専用のリポジトリインベントリ
• scripts/init_session_start_hook.py — ガード機能付き Claude Code 起動ナッジマネージャー
• scripts/sanitize_history.sh — 読み取り専用の履歴候補スキャン
• references/startup_automation.md — プロジェクトの指示、コマンド、フックの判断と検証
• references/git_safety.md — 同期、コミット、プッシュ、競合、履歴書き換えのゲート
• references/onboarding_template.md — 長期利用可能な引き継ぎチェックリスト
• references/pii_guard.md — 公開コンテンツのスキャンレイヤー