setup-engineer

/setup-engineer — Golden-State 調整ツール

このコマンドは「ドキュメントを生成」するものではありません。エージェント型のローカル開発に向けて、リポジトリを固定された独自の理想状態へ調整し、その後の適用状態の維持を、リポジトリ内にある doctor コマンドに引き継ぎます。リポジトリの開発ツールに対する terraform apply のようなものだと考えてください。現在の状態を読み取り、目標の状態との差分を取り、検証済みのフェーズを通じてその差を埋めます。

あなたは、この理想状態を守るガーディアンです。実行するたびに、リポジトリが同じ構成になっている必要があります。予測可能で、並列インスタンスに安全で、自己修復できる状態です。

「理想状態」の意味

以下の8項目がすべて満たされているリポジトリが、理想状態です。完全な不変条件チェックリスト（doctor が適用する内容）は references/golden-state.md にあります。差分を取る前に読んでください。

1. リポジトリごとの開発用 CLI — リポジトリ本来の言語で実装された 深いモジュール（JS リポジトリなら JS、Python リポジトリなら Python）です。動詞のインターフェースはシンプルにし、複雑なオーケストレーションは内部に隠します。ローカル開発のライフサイクル全体を担います。仕様：references/cli-and-just.md。
2. 薄い just インターフェース — すべてのリポジトリと言語で動詞を統一し、ロジックは一切持たず、各行から CLI を呼び出します。これにより、身についた操作感とエンジニアスキルをそのまま使えます。テンプレート：templates/justfile。
3. 生成された環境／ポートの契約 — ENV_INDEX を1つ、DEV_HOST を1つ用意し、スロットテーブルを唯一の信頼できる情報源とします。BASE + INDEX*100 + slot を適用し、Docker 内の DNS とホスト側オフセットとの境界ルールを守ります。仕様：references/env-and-ports.md。
4. 4ファイル構成のエンジニアスキル — SKILL.md ／ ARCHITECTURE.md ／ TESTING.md ／ GOTCHAS.md。コマンドは外に、理由は中に記します。仕様：references/engineer-skill.md。
5. 薄い CI — ワークフローでは同じ just／CLI インターフェースを呼び出し、ロジックをほぼ持たせません。これにより再利用性を高め、CI ベンダーへのロックインを避けます。
6. doctor が接続され、正常に動作する — リポジトリ内で不変条件を適用するツール（CLI の動詞）がパスし、CI でも実行されます。
7. トラッカーとの紐付け — エンジニアスキルの隣に TRACKER.md を置き、このリポジトリの課題トラッカー、そのコマンド、ラベルの意味を記載します。これにより、トラッカーに書き込むすべてのスキルで認識を統一できます。任意です。紐付ける価値のあるトラッカーがないリポジトリは、これがなくても理想状態を保てます。仕様：references/tracker.md。
8. 依存関係との紐付け — エンジニアスキルの隣に DEPENDENCIES.md を置き、更新幅から想定されるよりリスクの高いパッケージ、どの依存関係をどの動詞で検証するか、無人の更新処理をどこまで許可するかを記載します。トラッカーと同様に任意です。依存関係ボットがないリポジトリは、これがなくても理想状態を保てます。仕様：references/dependencies.md。

setup-engineer は、1〜8の存在と構成を調整します。構成が整った後は、doctor が実行時に不変条件を適用します。この役割分担を明確にしてください。setup-engineer は、構成を作成・移行するメタ調整ツールです。doctor は、ずれを検出するリポジトリ内のガードです。setup-engineer は最後のゲートとして doctor を実行します。

調整ループ

以下の手順を順番に実行してください。差分確認を省略せず、既存のリポジトリを一気に作り変えないでください。

1. 検出

既存のものを調べて一覧化します。思い込みで進めず、実際に確認してください。

# Identity
basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

# Stack / package manager
ls package.json pyproject.toml go.mod Cargo.toml 2>/dev/null
# Compose + existing env tooling
ls docker-compose*.yml compose*.yml .env .env.example 2>/dev/null
ls scripts/ 2>/dev/null
# Existing command surface
ls justfile Justfile Makefile 2>/dev/null
# Existing engineer skill — check wherever this repo keeps skills
ls -d */skills/*-engineer/ .*/skills/*-engineer/ 2>/dev/null | grep -v '^\.\./'
# Tracker — a binding beside the engineer skill, and evidence of what to bind to
ls */skills/*-engineer/TRACKER.md .*/skills/*-engineer/TRACKER.md 2>/dev/null
git remote -v; command -v gh glab jira 2>/dev/null
# Dependency binding — the same, plus evidence of a bot to bind to
ls */skills/*-engineer/DEPENDENCIES.md .*/skills/*-engineer/DEPENDENCIES.md 2>/dev/null
ls renovate.json renovate.json5 .renovaterc* .github/renovate.json* \
   .github/dependabot.yml 2>/dev/null
# CI
ls .github/workflows/ .gitlab-ci.yml 2>/dev/null

見つかったものはすべて読みます。既存の有機的なスクリプト（setup-env.mjs、dev-data.mjs、reset-data.sh など）は、削除する不要物ではありません。CLI に移行するロジックです。何かを提案する前に、それらを読み、リポジトリで実際に行われているライフサイクルを把握してください。

2. 分類する

リポジトリを、次のいずれか1つに厳密に分類します。分類によって、変更の踏み込み具合を決めます。

• グリーンフィールド — CLI、just、環境ツール、エンジニアスキルがありません。→ 言語ごとのテンプレートを使って、ゴールデン状態全体をスキャフォールドします。リスクは低く、壊れるものもほとんどありません。
• 部分的 — 既存のスクリプトや、単一の大きなエンジニアスキル（最も一般的な開始状態）があります。→ 移行はフェーズごとに進め、各フェーズの後に検証します。最もリスクが高いため、一括で変更してはいけません。
• ゴールデン — すでに準拠しています。→ just doctor を実行し、問題がないことを報告して終了します。すでに正しいリポジトリに不要な変更を加えてはいけません。

3. 差分を確認する

ゴールデン状態のチェックリストに照らした、具体的な乖離レポートを作成します。8つの要素それぞれについて、「存在」「一部存在」「欠落」のいずれかと、具体的な不足点を示します。例：

CLI            partial   logic lives in 4 loose scripts/*.mjs, no single entrypoint, no `doctor`
just           missing   no justfile
env contract   partial   setup-env.mjs exists but 2 services hardcode host ports in compose
engineer skill partial   1 monolith SKILL.md (33KB) + 3 helper scripts inside the skill dir
CI             partial   workflow reimplements test orchestration inline instead of calling CLI
doctor         missing
tracker        missing   github remote + authenticated gh, but no TRACKER.md
dependencies   missing   renovate.json present, no DEPENDENCIES.md

4. 計画する

差分を、順序立てた段階的な修正計画にまとめます。部分的なリポジトリで、各ステップの後もリポジトリが動作する状態を保つ順序は次のとおりです。

1. CLI の骨組みをスキャフォールドする（動詞のインターフェースと doctor。最初は既存のスクリプトに処理を委譲）とともに、その上に薄い justfile を用意します。
2. 既存のロジックを1つずつ CLI に移行する（環境 → ライフサイクル → データ → テスト）。各コマンドが動作するようになってから、対応する単独スクリプトを削除します。
3. 環境／ポートの契約を仕様に適合させる（スロットテーブルを正とし、ハードコードされたポートをなくし、境界 URL を導出する）ことで、doctor が成功する状態にします。
4. エンジニアスキルを4ファイルの最小構成に再編する。コマンドを外に移し、スクリプトを CLI に移し、理由／アーキテクチャ／注意点だけを残します。
5. CI を簡素化し、just／CLI を呼び出すようにします。
6. トラッカーを紐づける — 先行フェーズに依存せず、解決にユーザーが答えられる質問が必要になる可能性があるため、後半で行います。
7. DEPENDENCIES.md を作成する — トラッカーと合わせて、参照する just の動詞が実在してから行います。記載するすべてのコマンドが実在する動詞に解決される必要があるためです。

計画を提示し、適用する前に承認を得ます。これは、各フェーズの最後に検証するというリポジトリ所有者の継続的なルールに沿っています。

5. 適用する — フェーズごとに進め、一括で変更しない

各フェーズの後に、次を実行します。

just doctor      # invariants hold
just test        # nothing broke   (use the repo's real test verb if `just` isn't wired yet)

フェーズで問題が発生した場合は、次のフェーズに進む前に停止して修正します。重い検証（テストスイート全体の実行、アプリの動作確認など）には Task ツールで検証用サブエージェントを起動し、推測だけでフェーズの完了を宣言しないようにします。代替となる動詞が成功するまで、既存のスクリプトを削除してはいけません。

6. 検証して報告する

最後に、doctor が問題なく完了した状態にし、references/report-format.md に沿って報告します。変更内容、各フェーズで検証した内容、フォローアップとして残る乖離を記載してください。

必ず導入する2つの行動規範

これらはエンジニアスキルの SKILL.md に追加し、後からリポジトリで作業するすべてのエージェントが常に従うようにします。これらは「ガーディアン／継続的改善」の核心です。全文とその理由は、references/engineer-skill.md を参照してください。

• ライフサイクルの衛生管理 — 環境を起動したら、作業が終わったときに停止します。 just down は手軽に使える習慣です（データを保持し、RAM を解放するため、より多くのインスタンスを並行して実行できます）。複数のエージェントインスタンスが同時に動作する場合に特に重要です。古い環境が RAM を消費し続けることが、障害の原因になります。
• 自己改善（実行可能な仕組みへのエンコードを優先） — エージェントが問題に苦労して対処した場合、その修正は、それを保持できる最も永続的な層に反映します。新しい just／CLI 動詞 > 新しい doctor チェック > GOTCHAS.md のメモ、の順に優先します。文章での説明は最後の手段であり、標準の対応ではありません。これにはインフラ変更の規範も含まれます。サービス（データストア、キュー、キャッシュ、IdP）を追加または変更する場合は、同じ変更で、そのポートスロット、ヘルスチェック、nuke のボリューム対象範囲、再生成された .env も追加します。この4つすべてがそろうまで、doctor は失敗する必要があります。

リファレンスマップ

参照先	タイミング
references/golden-state.md	差分を確認する前 — 不変条件の完全なチェックリスト
references/cli-and-just.md	CLI、justfile、doctor のスキャフォールディング／移行時
references/env-and-ports.md	env／ポートの仕様、devbox、HTTPS に取り組むとき
references/engineer-skill.md	エンジニアスキルと2つの法則を再構成するとき
references/tracker.md	リポジトリの課題トラッカーを TRACKER.md に紐付けるとき
references/dependencies.md	リポジトリの依存関係ポリシーを DEPENDENCIES.md に紐付けるとき
templates/justfile	そのまま配置できる、正規の薄い動詞サーフェス
references/report-format.md	最終的なゴールデンステートレポート