1仕組みと動作原理
環境修復は「すべてを再インストール」ではなく「証拠駆動」：所定の順序でAGENTS.md/CLAUDE.md/ONBOARDING/README/manifest/CIを読み込み、読み取り専用のインベントリスクリプトで実際の技術スタックを特定した上で、最小限の修復を実施。
auto-repo-setup/SKILL.md
Use the bundled scripts/check_env.py against the repository root when a Python 3.10+ runner is already available. It detects the declared ecosystem and checks only the relevant toolchain; it does not install dependencies or read secret values.
ここでの処理内容：「リポジトリが動かない」といった曖昧な問題を検証可能なインベントリの差異に集約。check_envはマニフェストで宣言されたツールチェーンがPATHに存在するかのみを確認し、終了コード0/1/2（利用可能/不足/安全に検査不可）の3状態で表現して以降の修復と検証のベースラインとします。
check_env.pyの検出ロジックは、明示的なロックファイルやマニフェスト（uv.lock、package-lock.json、go.modなど）からパッケージマネージャとランタイムを特定し、読み取り専用コマンドを実行して終了コードとstdout/stderrを保持。
auto-repo-setup/scripts/check_env.py
def detect_toolchains(repo: Path) -> list[ToolRequirement]: """Infer package managers and runtimes from explicit manifests/lockfiles."""
run_cmdのdocstringは「Run one read-only command and preserve its three observable outputs.」と記載。すべての検出コマンドは15秒タイムアウト、check=Falseによる確実な中断、3系統の出力キャプチャを徹底し、スクリプト自身によるインストール・同期・変更を一切排除。
「最小限の仕組み」の優先順位付けとhookゲート：日常的な起動同期はAGENTS.md/CLAUDE.mdまたは自然言語指示に委ね、「初回プロンプト前に実行必須」かつホストが検証済みの場合のみSessionStartフックを登録し、必ず事前にdry-runプレビューを実行。
auto-repo-setup/SKILL.md
Prefer, in order: direct Agent instruction → project instruction → explicit command → lifecycle hook. A hook is not a more professional version of a sentence.
Workflow Dでは二重の安全策を適用：「Diagnose repeated output first」（3行の出力から3つの登録があると早合点せず、登録数とトリガーセッションを実測）および「Install only after the hook gate passes」（Preview first → --dry-run → ユーザー確認後に同一コマンドから--dry-runを外して実行）。
init_session_start_hook.pyは管理型かつ冪等なhookインストーラー：[auto-repo-setup]タグ付きのSessionStartエントリ1件のみを追加（matcher startup + echoガイダンス）、guideパスの検証、無関係な設定の保持、アトミック書き込み、--removeに対応。
auto-repo-setup/SKILL.md
The bundled initializer is Claude Code-specific and installs only a lightweight startup context nudge. It preserves unrelated settings, adds matcher startup, validates the guide path, writes atomically, and is idempotent.
スクリプト側にも同様の規律が適用：MANAGED_MARKER = "[auto-repo-setup]"で管理対象エントリを識別。validate_guideは絶対パスや「..」を拒否し、'"'$;&|<>!()%およびバッククォート（FORBIDDEN_GUIDE_CHARS）に対してConfigErrorを送出。ユーザーパスをhookコマンドに埋め込むことによるインジェクションを根本から防止。
Gitワークフローは自動処理ではなく「ルールゲート＋状態説明」：クリーンな状態でのみff-only pullを実行。ローカル変更や履歴の分岐がある場合はstash/merge/rebase/forceの自動実行を禁止し、状態説明を実施。
auto-repo-setup/SKILL.md
If the working tree is clean, run git pull --ff-only.
Operating principlesによる同期制約：「Never auto-stash, merge, rebase, force, discard, or overwrite local changes to make setup look successful.」破壊的・公開操作（public push、force push、履歴書き換え）にはすべて明示的な承認を要求。
履歴内の機密情報クリーンアップは読み取り専用の候補スキャンのみとし、修復作業は人間に委任：sanitize_history.shは「補助的なチェックのみ」と規定され、SKILL.mdはスキャン結果を候補として扱い、未承認での履歴書き換えコマンド実行を厳禁。
auto-repo-setup/scripts/sanitize_history.sh
# 注意：此脚本只辅助检查，最终修复（orphan branch / BFG）需要人工确认后执行。
スクリプトは4段階でスキャン：一般的なシークレットパターン（sk-プレフィックスなど）、個人の絶対パス、プライベートドメイン、現在のワークスペース。問題数と修復提案を出力し、--check-onlyで読み取り専用として終了。
2コア機能
01読み取り専用・スタック認識型のリポジトリ機能インベントリ（check_env.py、終了コード0/1/2で利用可能/不足/検査不可を表現）
02根本原因修復のクローズドループ：失敗コマンドの3出力を記録 → 宣言元を特定 → 最小限の修復 → 再検証 → 実際のsmoke/起動コマンドを実行
03標準的なGit同期（クリーンな場合のみpull --ff-onlyを実行。未コミット変更や分岐は自動処理せず説明のみ）
04管理対象SessionStartフックの登録・診断・削除（冪等性、アトミック書き込み、--dry-runプレビュー、--remove）
05リポジトリ引き継ぎ/オンボーディング監査：onboarding_template.mdをチェックリストとして不足している運用ルールを補完
06Git履歴内の機密情報の読み取り専用スキャン（sanitize_history.sh）および公開コンテンツの確認ガイドライン（pii_guard.md）
07カウンターレビュー境界：セキュリティポリシー、共有hook、CI、依存関係、破壊的なGit操作に影響する場合にのみカウンターレビューを要求。通常のセットアップではチームレビューを招集しない
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | git |
| cli | python3 / uv |
| cli | sh/bash |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: auto-repo-setup/scripts/check_env.py
- 本地工作目录: ファイル読み書きおよび成果物出力: ユーザー確認後にリポジトリ内の .claude/settings.json に書き込み（管理対象 SessionStart フック、init_session_start_hook.py 経由）
監査ノート： 標準ライブラリおよびローカルスクリプト（check_envによる読み取り専用検出、sanitize_historyによる読み取り専用スキャン）を内蔵し、ローカル設定（.claude/settings.json、.gitignore）への書き込みのみで、外部ネットワーク通信および認証情報へのアクセスはゼロです（check_envのdocstringにはシークレット値を一切読み取らない旨を明記）。フック登録はユーザー設定を変更しますが、dry-runプレビュー、冪等アトミック書き込み、--removeを備えており、SKILL.mdにより事前診断とユーザー確認が義務付けられています。注意点：SKILLはエージェントによるGitコミット/プッシュ操作を許可していますが、破壊的操作には明示的承認が必要です。またsanitize_historyのヒューリスティック検出には誤検知・検知漏れの可能性があるため、結果は候補としてのみ扱われます。
5二重目の独立検証
- [ok] check_env.py 只读且不碰 secret — docstring 含『reads secret values』否定句 + 代码仅 git rev-parse/which/shutil.which 探测 + token 扫描零命中。
- [ok] init_session_start_hook.py 行为与 SKILL.md 描述一致（幂等/保留无关设置/原子写） — 脚本 load_settings 校验 JSON 结构并保留 hooks 其余键；update_settings/atomic_write 存在；SKILL.md 原文含『preserves unrelated settings … writes atomically, and is idempotent』同义描述。
- [ok] sanitize_history.sh 永不改写历史 — 脚本头注释『此脚本只辅助检查，最终修复（orphan branch / BFG）需要人工确认后执行』；修复建议仅 echo 输出。
- [ok] Git 门禁（ff-only/不自动 stash/显式批准）有源码依据 — SKILL.md Workflow B 逐条原文存在；Operating principle 4『Never auto-stash, merge, rebase, force, discard, or overwrite local changes…』存在。
- [ok] 无网络外发声明 — scripts/ 三文件 token 扫描仅命中 BFG 文档 URL（输出文案），无任何 fetch/request/curl 调用点。
- [ok] 外部依赖清单（git/python/uv/sh）真实存在 — git：check_env run_cmd 数组含 git；python/uv：SKILL.md 命令与脚本 shebang；sh：sanitize_history.sh shebang。
- [ok] 功能声明 vs 夸大检查 — description 承诺的『Diagnose, repair, and standardize repository setup and safe Git workflows』全部由路由表+脚本+门禁兑现；反例扫描未见越界承诺（无自动破坏性操作、无网络工具）。
- [ok] 元数据（license/stars/commit） — 仓库根 LICENSE 为 MIT (c) 2025 daymade；GitHub API stars=1385、pushed_at=2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678cb5d4fd6acc9c922690df035dbd33d247。
6結論
最適な用途： 対象：新しいマシンでリポジトリが動作しない場合、同僚のオンボーディングで再現可能な引き継ぎが必要な場合、フックによる起動出力の重複を診断したい場合、コミット/プッシュ/競合/履歴クリーンアップに安全なワークフローを求めるClaude CodeまたはCodexユーザー。また、「作業前の同期」などの定常的な起動動作をフックの乱立ではなくAGENTS.md/CLAUDE.mdに集約したいチームに適しています。
不向きな用途： 非対象：AGENTS.md/CLAUDE.mdで完全にカバーされているリポジトリ（プロジェクト指示書に直接従うことを推奨）；確認なしの全自動CI型修復を求める場合（読み取り専用診断、明示的承認、状態説明を重視するため）；Claudeのフック設定をCodexへそのまま流用する用途（スキル側で厳禁。Codex側ではまずstartup_automationを確認してホストの仕様を検証する必要があります）。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload auto-repo-setup.tar.gz
sha256:
Option B · Copy Guide for Agentf95bf84548251fa7…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.