mcpField
P
project-migration

project-migration

github.com/loxosceles-dev开发131 次安装
代码仓库

关于 project-migration

面向现有项目的工具链迁移技能，目标是采用主机原生工具链并保留项目代码。它要求先评估并取得确认，再在指定分支分阶段调整配置、验证构建与测试，且不覆盖文件或修改源代码。

主要功能

  1. 01迁移前评估项目与配置
  2. 02确认后按阶段执行迁移
  3. 03通过专用分支隔离变更
  4. 04配置 mise、uv、pnpm 与 direnv
  5. 05移除 devcontainer 配置并验证

适用场景

  1. 01将现有 Python 项目迁移到 uv 与 mise
  2. 02将 Node.js 项目切换为固定版本的 pnpm
  3. 03迁移项目配置并移除 devcontainer

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/loxosceles-dev/dev-skills --skill project-migration

安装后在 Claude Code 中输入/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。
  • 将 .venv/ 添加到 .gitignore。

提交：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_...
  • 将 .envrc.local 添加到 .gitignore。

提交：chore: Add direnv environment configuration

Agent Skills（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。
  • 将 apm_modules/ 添加到 .gitignore。
  • 将 .kiro/hooks/ 添加到 .gitignore。

提交：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

渐进式改进

如果开发者纠正了此技能本应避免的行为，请建议对该技能进行具体修改，以防止将来再次出现相同的纠正。

评论

支持 Markdown