project-migration

プロジェクトの移行

これは厳格なガイドラインです。 これらのルールに正確に従ってください。

既存のプロジェクトをホストネイティブのツールチェーンに移行します。ゼロから構成を作成する project-setup とは異なり、このスキルは既存のコードを対象とするため、破壊的な変更を避け、対話形式で進める必要があります。

目標の状態は ~/Hermes-Shared/guitarizta/docs/dev-toolchain-architecture.md で定義されています。基準となる参照資料として、このドキュメントを読んでください。このスキルでは、その状態を実現するための作業手順を示します。

---

基本原則

• 確認せずに上書きしないでください。 すでに存在するファイルについては、変更差分を提示してください。
• ブランチで作業してください。 すべての変更は chore/migrate-project-setup で行います。
• 後回しにせず、早めに確認してください。 意図が曖昧な場合は、推測する前に確認してください。
• devcontainer は使用しません。 .devcontainer/ の設定は追加も維持もしないでください。存在する場合は、削除する計画を立ててください。

---

ワークフロー

フェーズ 1：評価

1. プロジェクトの種類を特定します。 明確でない場合は確認してください。Python、Node.js、または混在型のどれですか？

2. loxosceles/project-blueprints から該当するブループリントを読み、目標の構成を確認します。

3. 現在のプロジェクトを監査します。 次の項目を確認してください。

   ファイル／ディレクトリ	現在の状態	目標
   .mise.toml	存在するか？バージョンは何か？	正確なバージョンを固定して存在する必要があります
   .python-version	存在するか？	Python プロジェクトの場合は存在する必要があります
   pyproject.toml + uv.lock	存在するか？	Python プロジェクトの場合は存在する必要があります
   package.json + pnpm-lock.yaml	存在するか？	Node プロジェクトの場合は存在する必要があります
   package.json packageManager フィールド	設定されているか？	バージョンを固定する必要があります（[email protected]）
   .envrc	存在するか？	シークレット以外の環境変数を設定して存在することが望ましい
   .envrc.local.example	存在するか？	必要なシークレットを記載して存在することが望ましい
   apm.yml + apm.lock.yaml	存在するか？	存在する必要があります
   .kiro/steering/	存在するか？	関連するコンテキストを含めて存在することが望ましい
   .devcontainer/	存在するか？	削除する必要があります
   .gitignore	適切か？	.venv/、.envrc.local、apm_modules/ を含める必要があります

4. 移行計画を提示します。 カテゴリごとにまとめてください。変更する既存の各ファイルについて、変更内容と理由を示してください。ユーザーの入力が必要な項目には印を付けてください。

ユーザーの確認を得るまで、このフェーズを先に進めないでください。

フェーズ 2：ブランチの設定

git checkout dev 2>/dev/null || git checkout main
git checkout -b chore/migrate-project-setup

最初に作業ツリーがクリーンであることを確認してください。コミットされていない変更がある場合は、作業を中断して確認してください。

フェーズ 3：移行の実施

カテゴリごとに作業し、各カテゴリの後にコミットします。

ランタイムのバージョン固定（mise）

• .mise.toml が存在する場合：現在固定されているバージョンを、プロジェクトで実際に使用しているものと比較します。バージョンを変更する前に、ユーザーに確認してください。
• .mise.toml が存在しない場合：現在のランタイムのバージョンを特定して作成します。

# .mise.toml
[tools]
python = "3.11"   # or whatever version the project is using
node = "22.22.3"  # if Node project

• Python プロジェクトには .python-version を作成します（.mise.toml の Python バージョンと一致させる必要があります）。

コミット：chore: Add mise toolchain pinning

Python パッケージ（uv）

• pyproject.toml と uv.lock が存在する場合：最新の状態か確認します（uv sync）。
• requirements.txt は存在するが pyproject.toml がない場合：uv への移行を提案します。プロジェクト名と説明を確認します。pyproject.toml を作成し、各依存関係に対して uv add を実行して、uv.lock を生成します。
• .gitignore に .venv/ を追加します。

コミット：chore: Migrate to uv dependency management

Node パッケージ（pnpm）

• package.json が存在する場合：
  • packageManager フィールドを確認します。存在しない場合は、現在の pnpm バージョン（pnpm --version）を特定して追加します。
  • pnpm-lock.yaml が存在し、コミットされていることを確認します。
  • .gitignore に node_modules/ が含まれていることを確認します。
• pnpm-lock.yaml とともに npm または yarn のロックファイルが存在する場合：ユーザーに確認し、どれを残すか決めます。

コミット：chore: Pin pnpm version, verify lockfile

環境変数（direnv）

• .envrc が存在しない場合：最小限のファイルを作成します。

  # .envrc
  export ENVIRONMENT=dev
  # Add project-specific non-secret vars here
  # Load machine-local secrets if file exists (gitignored)
  [[ -f "${PWD}/.envrc.local" ]] && source_env "${PWD}/.envrc.local"
  

• .envrc が存在する場合：.envrc.local に移すべきシークレットがないか確認します。
• 必要なシークレットを記載した .envrc.local.example を作成します。

  # .envrc.local.example — copy to .envrc.local, fill in values, never commit
  # export DATABASE_URL=postgres://localhost:5432/myproject_dev
  # export STRIPE_SECRET_KEY=sk_test_...
  

• .gitignore に .envrc.local を追加します。

コミット：chore: Add direnv environment configuration

エージェントスキル（APM）

• apm.yml が存在しない場合は、標準の dev-skills 依存関係を指定して作成します。

  name: <project-name>
  version: 1.0.0
  targets:
    - kiro
    - claude
    - codex
    - copilot
    - agent-skills
  dependencies:
    apm:
      - loxosceles-dev/dev-skills#main
    mcp: []
  

• apm install を実行して apm.lock.yaml を生成します。
• .gitignore に apm_modules/ を追加します。
• .gitignore に .kiro/hooks/ を追加します。

コミット：chore: Add APM skill dependencies

Devcontainer の削除

.devcontainer/ が存在する場合：

1. 中に何があるかをユーザーに提示します。
2. 次の内容を確認します：「.devcontainer/ を削除します。プロジェクトでは mise/uv/pnpm を直接使用します。よろしいですか？」
3. 確認後、git rm -r .devcontainer/ を実行します。
4. docker-compose.devcontainer.yml などを確認し、devcontainer 専用の場合は削除します。サービス依存関係（Postgres、Redis など）を提供する docker-compose.yml は保持します。

コミット：chore: Remove devcontainer configuration

.gitignore の整理

次の項目が含まれていることを確認します：

.venv/
node_modules/
.envrc.local
.env
.env.*
apm_modules/
.kiro/hooks/
dist/

コミット：chore: Update gitignore for host-native toolchain

フェーズ 4：検証

mise trust && mise install   # runtimes installed
uv sync                      # if Python project
pnpm install                 # if Node project
apm install --frozen         # skills installed
direnv allow                 # env vars loaded

プロジェクト独自のビルド／テストコマンドを実行し、問題がないことを確認します。

フェーズ 5：概要

次の内容を提示します：

• 追加したファイル
• 変更したファイル（変更内容）
• 削除したファイル（devcontainer の成果物）
• ブランチ名：chore/migrate-project-setup
• 次のステップ：dev への PR を開く

---

ルール

• .gitignore の項目は削除せず、追加のみ行います
• ソースコードファイルは変更せず、インフラストラクチャと設定のみ変更します
• devcontainer の .env ファイルに実際のシークレットが含まれている場合は警告し、コミットしないでください
• すべて最後にまとめてではなく、カテゴリごとにコミットします
• Git リモートには SSH を使用する必要があります：[email protected]:user/repo.git

---

継続的な改善

開発者から、このスキルで防止できるはずの動作について修正を受けた場合は、今後同じ修正が発生しないよう、このスキルへの具体的な修正案を提案してください。