迁移指南：v1.0 → v1.1 project.yaml¶

本指南涵盖如何将现有项目的配置文件转换为 project.yaml。它与 UPGRADING.md 中的模板差异说明不同——该文件告诉你哪些 技能与代理文件 在版本之间发生了变化，以及它们是否可以安全覆盖。本指南则涵盖你项目自身的数据：你在 production/stage.txt、production/review-mode.txt 和 .claude/docs/technical-preferences.md 中配置的值。

如果你要在 v1.1 上搭建全新项目，则不需要本指南——/start 会直接写入 project.yaml，且所有旧版文件均不适用。

你需要迁移吗？¶

如果你的仓库根目录不存在 project.yaml，且以下文件至少存在一个，则说明你有一个需要迁移的 v1.0 项目：

production/stage.txt
production/review-mode.txt
.claude/docs/technical-preferences.md 且包含真实值（仍充满 [TO BE CONFIGURED] 占位符的副本是未改动的模板默认值，不是可迁移数据，不计入）

运行 /adopt，它会自动检测到这种情况（Phase 2g），并引导你完成以下步骤。你也可以直接运行转换器。

会保留哪些内容¶

From	To (`project.yaml`)
`production/stage.txt`	`project.stage`
`production/review-mode.txt`	`modes.review_mode`
`technical-preferences.md` → 引擎与语言	`engine.name`, `engine.version`, `engine.language`, `engine.rendering`, `engine.physics`
`technical-preferences.md` → 输入与平台	`platform.targets`, `platform.primary_input`, `platform.gamepad_support`, `platform.touch_support`
`technical-preferences.md` → 命名约定	`naming.classes`, `naming.variables`, `naming.constants`, `naming.signals`, `naming.files`, `naming.scenes`
`technical-preferences.md` → 性能预算	`performance.target_framerate`, `performance.frame_budget_ms`, `performance.draw_call_limit`, `performance.memory_ceiling_mb`
`technical-preferences.md` → 测试	`testing.framework`, `qa.coverage_minimum`
`technical-preferences.md` → 引擎专家	`specialists.code`, `specialists.shader`, `specialists.ui`, `specialists.additional`

在 v1.0 中完全不存在的设置（modes.rigor、qa.level、docs.density、team.size、modes.story_granularity 以及 v1.1 modes 系统的其余部分）会获得硬编码的 v1.1 默认值——它们没有可保留的内容。

有一个值被重命名了： v1.0 的 review-mode.txt: none（“无总监评审”）在 v1.1 中变为 modes.review_mode: solo，这是新名称下的同一级别。转换器会映射该值，并在迁移报告的 Warnings 部分明确标出，因此你会看到这次重命名，而不是让它悄悄发生。

有意不迁移的内容： technical-preferences.md 中的 Forbidden Patterns 和 Allowed Libraries 部分在 project.yaml 中没有对应内容。正因如此，转换器永远不会删除该文件——参见下文“完成收尾（Finalizing）”。

运行迁移¶

该转换是一个经过测试的脚本，而非由 AI 手工编辑的内容——v1.1 计划将迁移期间的数据丢失列为最高严重性风险，而用叙述性文字进行的迁移无法像脚本那样进行单元测试。/adopt 会替你运行它，你也可以自行运行：

# 1. Preview — writes nothing, just reports what it would do
bash .claude/scripts/migrate-v1-config.sh --dry-run

# 2. Migrate — writes project.yaml + production/migration-report.md
#    Every legacy file is left in place, untouched.
bash .claude/scripts/migrate-v1-config.sh

# 3. Read the report before finalizing
cat production/migration-report.md

# 4. Finalize — deletes legacy files, ONLY after re-verifying each one's
#    value made it into project.yaml. Refuses (exit 4) and deletes nothing
#    on any mismatch.
bash .claude/scripts/migrate-v1-config.sh --finalize

第 4 步是可选的，并且有意单独列出。跳过它完全没问题——对于 project.yaml 中没有的任意键，每个技能（skill）和钩子（hook）都会回退到旧版文件，因此两者可以无限期共存。当你确信 project.yaml 正确，并希望用一个配置文件代替三个时，再运行它。

即使使用 --finalize，technical-preferences.md 也永远不会被删除——Forbidden Patterns 和 Allowed Libraries 仍然且将始终保留在该文件中，因为 v1.1 尚未为它们提供对应的结构。

阅读 `production/migration-report.md`¶

报告包含五个部分：

检测到的源文件 —— 转换器找到的旧版文件
保留的值 —— 每个源文件、每项设置写入 project.yaml 的内容
已应用的默认值 —— 没有可迁移来源的 v1.1 新设置
警告 —— 任何转换器无法干净解析的内容（见下文）
人工复核 —— 它找到但拒绝猜测的内容（例如某个 fork 的 technical-preferences.md 中的自定义部分）

可能出现的问题（以及脚本如何处理）¶

情形	行为
某个旧版文件格式错误 / 无法解析	按文件给出警告，保持该文件不变，继续迁移其余所有能够解析的内容。`project.yaml` 获得它可以读取的值，其余部分使用默认值。
已解析的值与 v1.1 枚举不匹配（例如某个自定义 fork 的 `stage: Alpha`）	按原样写入并附上警告注释，标记为需人工处理——转换器不会静默地强制转换或丢弃该值。
`project.yaml` 和旧版文件都已存在	拒绝运行（退出码 3）。脚本不会在两个“真相来源”之间猜测你最后编辑的是哪一个——请先自行解决（决定哪个具有权威性，删除或重命名另一个）。
fork 的 `technical-preferences.md` 中的自定义部分	在迁移报告中记录为“未迁移——请手动整合。”不会静默丢弃任何内容。

如果你遇到脑裂（split-brain）情况（两者同时存在），这通常意味着你要么在一个还留有旧版文件的项目上运行了 /start，要么手动进行了部分迁移。选择包含你真实值的那一个，删除或备份另一个，然后重新运行 --dry-run。

迁移后¶

将 project.yaml 与旧的 technical-preferences.md 进行抽查对照——尤其是引擎、命名和性能值。
运行 /settings 查看技能将读取到的有效配置。
无论你是否运行过 --finalize，框架中的其他一切工作方式都完全相同——不必急于一时。

对于 v1.0 中不存在的新设置（尤其是 modes.rigor），请参阅 README 的 Configuration 部分以及 .claude/docs/effects-map.md 中的完整规范。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/Claude-Code-Game-Studios