apply-template

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apply ai-env Template

应用ai-env模板

Apply the agentic development environment template to the current repository.

Argument: optional path to ai-env clone. No argument = clone from GitHub (primary path).

将Agent开发环境模板应用到当前代码仓库。

参数： ai-env克隆路径（可选）。不提供参数时将从GitHub克隆（首选路径）。

Phase 0 — Pre-flight

阶段0 — 预检查

Clean working tree check

清理工作树检查

Run

git status --porcelain

. If there are uncommitted changes, warn the user and ask whether to proceed or stash first. A dirty tree makes it hard to review what the template changed.

执行

git status --porcelain

命令。如果存在未提交的变更，向用户发出警告并询问是继续执行还是先暂存变更。工作树未清理时很难审查模板带来的变更。

Phase 1 — Source Resolution & Discovery

阶段1 — 源解析与发现

Locate template source

定位模板源

If an argument was provided, use that path and verify it's a clean git checkout

If NO argument was provided, clone from GitHub:

git clone --depth 1 https://github.com/camacho/ai-env.git /tmp/ai-env-template

and use that

If the default local path
```
~/projects/camacho/ai-env
```
exists and no argument was given, prefer the GitHub clone (ensures latest version)
If all fail, tell the user and stop

如果提供了参数，使用该路径并验证它是干净的git检出副本

如果未提供参数，从GitHub克隆：

git clone --depth 1 https://github.com/camacho/ai-env.git /tmp/ai-env-template

并使用该路径

如果默认本地路径
```
~/projects/camacho/ai-env
```
存在且未提供参数，优先使用GitHub克隆版本（确保是最新版本）
如果以上操作都失败，告知用户并终止流程

Read manifest

读取清单

Read

apply-template.manifest.json

from the template source directory. This classifies every file as

copy_if_absent

smart_merge

, or

skip

从模板源目录读取

apply-template.manifest.json

文件。该文件将每个文件分类为

copy_if_absent

（不存在时复制）、

smart_merge

（智能合并）或

skip

（跳过）。

Scan target

扫描目标目录

Check which

copy_if_absent

and

smart_merge

files already exist in the current repo (cwd).

For

copy_if_absent

files that already exist in the target: these will be smart-merged (not skipped) to pick up any new template additions while preserving target customizations.

检查当前仓库（当前工作目录）中已存在哪些

copy_if_absent

和

smart_merge

类型的文件。

对于目标目录中已存在的

copy_if_absent

类型文件：将对其执行智能合并（而非跳过），在保留目标端自定义内容的同时新增模板中的内容。

Present plan

展示执行计划

Show the user a summary:

Template Application Plan:
  Source: <path>
  Target: <cwd>

  Copy (new):        N files — <list>
  Smart merge (new): N files — <list of smart_merge files not in target>
  Smart merge (both): N files — <list of smart_merge files in both>
  Merge (existing copy_if_absent): N files — <list>
  Skipped:           N files (template-specific)

Proceed?

Wait for confirmation before continuing.

向用户展示汇总信息：

模板应用计划:
  源路径: <path>
  目标路径: <cwd>

  复制（新增）:        N个文件 — <列表>
  智能合并（新增）: N个文件 — <目标中不存在的智能合并文件列表>
  智能合并（双方均存在）: N个文件 — <双方都存在的智能合并文件列表>
  合并（已存在的copy_if_absent文件）: N个文件 — <列表>
  跳过:           N个文件（模板专属）

是否继续？

等待用户确认后再继续执行。

Phase 2 — Copy

阶段2 — 复制

For each entry in

copy_if_absent

Directories (entries ending with
```
/
```
):
```
mkdir -p
```
the target directory, then copy all files recursively. Skip individual files that already exist.
Files: if the file does NOT exist in the target, copy it verbatim. If it exists, apply the same smart merge logic as Phase 3 (the file has diverged from template — preserve target intent while adding template additions).

Also ensure these directories exist even if empty:

```
ai-workspace/plans/
```
```
ai-workspace/decisions/
```

对每个

copy_if_absent

条目执行以下操作：

目录（以
```
/
```
结尾的条目）：执行
```
mkdir -p
```
创建目标目录，然后递归复制所有文件。跳过已存在的单个文件。
文件：如果目标中不存在该文件，直接原样复制。如果已存在，应用与阶段3相同的智能合并逻辑（文件已与模板产生差异——在保留目标端意图的同时新增模板内容）。

同时确保以下目录存在，即使为空：

```
ai-workspace/plans/
```
```
ai-workspace/decisions/
```

Phase 3 — Smart Merge

阶段3 — 智能合并

For each file in

smart_merge

, read BOTH the template version and the target version (if it exists). If the target file doesn't exist, just copy the template version. If both exist, merge according to the rules below.

对每个

smart_merge

类型的文件，同时读取模板版本和目标版本（如果存在）。如果目标文件不存在，直接复制模板版本。如果双方都存在，按照以下规则合并。

AGENTS.md — Semantic Merge

AGENTS.md — 语义合并

Understand intent: read both versions completely. Identify the purpose of each section.
Keep from target:
```
## Stack
```
,
```
## Commands
```
,
```
## Architecture
```
,
```
## Gotchas
```
— preserve these sections entirely

Add from template if missing:

## Agent Roles & Dispatch

## Protected Files

## Conventions

## Workflow Reference

## Context Loading Rules

Resolve duplicates: if both have a section with the same heading, favor the template version for structural/convention sections, favor the target for project-specific sections
Update: the title line — replace the project name with the target repo's directory name
Preserve: any custom sections the target has that aren't in the template
Cohesion check: after merge, read the result and verify sections don't contradict each other

理解意图： 完整读取两个版本的内容，识别每个部分的用途。
保留目标端内容：
```
## Stack
```
、
```
## Commands
```
、
```
## Architecture
```
、
```
## Gotchas
```
— 完整保留这些部分。

如果缺失则从模板添加：

## Agent Roles & Dispatch

、

## Protected Files

、

## Conventions

、

## Workflow Reference

、

## Context Loading Rules

解决重复： 如果双方有相同标题的部分，结构/约定类部分优先使用模板版本，项目专属部分优先使用目标版本。
更新： 标题行——将项目名称替换为目标仓库的目录名。
保留： 目标端存在但模板中没有的所有自定义部分。
一致性检查： 合并完成后，读取结果并验证各部分内容没有冲突。

tsconfig.json — Deep Merge

tsconfig.json — 深度合并

Start from template base as the foundation
Deep merge
compilerOptions
: overlay target's compilerOptions on top of template's. Target wins on collision.
Preserve from target:
```
include
```
,
```
exclude
```
,
```
references
```
, and any other top-level keys

Inject if missing: these strict options from the template:

strict

noUncheckedIndexedAccess

verbatimModuleSyntax

exactOptionalPropertyTypes

noImplicitOverride

noFallthroughCasesInSwitch

Surface conflicts: if template and target have contradictory values for the same option (e.g.,
```
strict: true
```
vs
```
strict: false
```
), present the conflict to the user for resolution
Cohesion test: after merge, verify
```
compilerOptions
```
don't have contradictory flags (e.g.,
```
module: "commonjs"
```
with
```
verbatimModuleSyntax: true
```
)

以模板版本为基础 作为合并的基础。
深度合并
compilerOptions
：将目标端的compilerOptions覆盖在模板版本之上。发生冲突时目标端优先。
保留目标端内容：
```
include
```
、
```
exclude
```
、
```
references
```
以及所有其他顶层键。

如果缺失则注入： 模板中的这些严格模式选项：

strict

、

noUncheckedIndexedAccess

、

verbatimModuleSyntax

、

exactOptionalPropertyTypes

、

noImplicitOverride

、

noFallthroughCasesInSwitch

暴露冲突： 如果模板和目标端对同一个选项有冲突的值（例如
```
strict: true
```
和
```
strict: false
```
），将冲突展示给用户解决。
一致性测试： 合并完成后，验证
```
compilerOptions
```
中不存在矛盾的标记（例如
```
module: "commonjs"
```
和
```
verbatimModuleSyntax: true
```
同时存在）。

.claude/settings.json

Preserve from target: all existing

permissions.allow

and

permissions.deny

entries,

defaultMode

Union merge:
```
permissions.deny
```
arrays — add template entries not already present (deduplicate)
Union merge hooks: for each hook event (PreToolUse, PostToolUse, etc.), keep all target hooks. Add template hooks only if no hook with the same
```
matcher
```
already exists in the target
Preserve: any other keys the target has (disabledMcpjsonServers, enabledPlugins, etc.)

保留目标端内容： 所有已存在的
```
permissions.allow
```
和
```
permissions.deny
```
条目，以及
```
defaultMode
```
。
并集合并：
```
permissions.deny
```
数组——添加模板中不存在的条目（去重）。
并集合并钩子： 对于每个钩子事件（PreToolUse、PostToolUse等），保留所有目标端钩子。仅当目标端不存在相同
```
matcher
```
的钩子时才添加模板钩子。
保留： 目标端拥有的所有其他键（disabledMcpjsonServers、enabledPlugins等）。

package.json

Preserve from target:
```
name
```
,
```
version
```
,
```
description
```
,
```
main
```
,
```
type
```
,
```
dependencies
```
,
```
repository
```
,
```
license
```
,
```
author
```
— everything except scripts and devDependencies
Merge scripts: add any scripts from template that don't exist in target. Target wins on collision.
Merge devDependencies: add packages from template that aren't in target's devDependencies (commitlint packages, lefthook, @biomejs/biome, typescript). Never remove or downgrade existing deps.
Add if missing:
```
engines
```
,
```
packageManager
```

保留目标端内容：
```
name
```
、
```
version
```
、
```
description
```
、
```
main
```
、
```
type
```
、
```
dependencies
```
、
```
repository
```
、
```
license
```
、
```
author
```
——除了scripts和devDependencies之外的所有内容。
合并scripts： 添加目标端不存在的模板脚本。发生冲突时目标端优先。
合并devDependencies： 添加目标端devDependencies中不存在的模板包（commitlint相关包、lefthook、@biomejs/biome、typescript）。绝不删除或降级已存在的依赖。
如果缺失则添加：
```
engines
```
、
```
packageManager
```

biome.json

Preserve from target: all existing rules,
```
files
```
config,
```
formatter
```
config
Add if missing: linter rules from template that don't exist in target
Never remove any rule the target already has

保留目标端内容： 所有已存在的规则、
```
files
```
配置、
```
formatter
```
配置。
如果缺失则添加： 目标端不存在的模板linter规则。
绝不删除 目标端已存在的任何规则。

.gitignore

Union merge: combine every unique line from both files, deduplicated
Preserve: section comments (lines starting with
```
#
```
) and blank line groupings from both files
Order: target's lines first, then new lines from template appended at the end under a
```
# ai-env template
```
comment

并集合并： 合并两个文件中所有唯一的行，去重。
保留： 两个文件中的分段注释（以
```
#
```
开头的行）和空行分组。
顺序： 目标端的行在前，模板新增的行追加到末尾，放在
```
# ai-env template
```
注释下方。

skills-lock.json — Union Merge

skills-lock.json — 并集合并

Union merge
.skills
object: combine all skill entries from both template and target. Each entry has
```
source
```
(git URL or local path, depending on
```
sourceType
```
),
```
sourceType
```
(
```
"git"
```
or
```
"local"
```
), and
```
computedHash
```
(SHA-256 integrity hash).
Template wins on conflict: if the same skill name exists in both, use the template's entry (
```
source
```
,
```
sourceType
```
,
```
computedHash
```
all come from the template)
Never remove: target skills not in the template are always preserved — projects may have custom skills
Top-level
version
: keep the higher integer from either side (this is the lockfile schema version, not a skill version — individual skills do not have version fields)
Post-merge: after writing the merged lockfile, instruct: "Run
```
npx skills install -a claude-code -a codex
```
to materialize any newly added skills for both agents"

Example merge logic:

Template:                                Target:
{ "version": 1, "skills": {             { "version": 1, "skills": {
    "validate": {                            "validate": {
      "source": "git@...ai-skills.git",       "source": "git@...ai-skills.git",
      "sourceType": "git",                     "sourceType": "git",
      "computedHash": "abc..."                 "computedHash": "abc..."
    },                                       },
    "reflect": {                             "custom-lint": {
      "source": "git@...ai-skills.git",       "source": "local",
      "sourceType": "git",                     "sourceType": "local",
      "computedHash": "def..."                 "computedHash": "xyz..."
    }                                        }
}}                                       }}

                    ↓ merged result:
{ "version": 1, "skills": {
    "validate":    { ... },  ← kept (same in both)
    "custom-lint": { ... },  ← preserved (target-only)
    "reflect":     { ... }   ← added from template
}}

并集合并
.skills
对象：合并模板和目标端的所有技能条目。每个条目包含
```
source
```
（git URL或本地路径，取决于
```
sourceType
```
）、
```
sourceType
```
（
```
"git"
```
或
```
"local"
```
）和
```
computedHash
```
（SHA-256完整性哈希）。
冲突时模板优先： 如果双方存在相同的技能名称，使用模板的条目（
```
source
```
、
```
sourceType
```
、
```
computedHash
```
全部来自模板）。
绝不删除： 模板中不存在的目标端技能始终保留——项目可能有自定义技能。
顶层
version
：保留两边更大的整数值（这是锁文件的schema版本，不是技能版本——单个技能没有版本字段）。
合并后操作： 写入合并后的锁文件后，提示："执行
```
npx skills install -a claude-code -a codex
```
来为两个Agent实例化所有新增的技能"

合并逻辑示例：

模板:                                目标:
{ "version": 1, "skills": {             { "version": 1, "skills": {
    "validate": {                            "validate": {
      "source": "git@...ai-skills.git",       "source": "git@...ai-skills.git",
      "sourceType": "git",                     "sourceType": "git",
      "computedHash": "abc..."                 "computedHash": "abc..."
    },                                       },
    "reflect": {                             "custom-lint": {
      "source": "git@...ai-skills.git",       "source": "local",
      "sourceType": "git",                     "sourceType": "local",
      "computedHash": "def..."                 "computedHash": "xyz..."
    }                                        }
}}                                       }}

                    ↓ 合并结果:
{ "version": 1, "skills": {
    "validate":    { ... },  ← 保留（双方一致）
    "custom-lint": { ... },  ← 保留（仅目标端存在）
    "reflect":     { ... }   ← 从模板新增
}}

Directories:

.claude/agents/

.claude/rules/

.claude/skills/

.claude/agents/

、

.claude/rules/

、

.claude/skills/

Recurse into each directory
New files: copy from template
Existing files: apply semantic merge — understand the intent of both versions, preserve target customizations, add missing template sections

递归进入每个目录
新文件： 从模板复制
已存在文件： 应用语义合并——理解两个版本的意图，保留目标端自定义内容，添加缺失的模板部分

Phase 4 — Post-Apply

阶段4 — 应用后处理

Create

ai-workspace/.template-version

with content:

version: <manifest version>
applied: <ISO 8601 timestamp>
source: <template source path>

Dependency check: if devDependencies were added to package.json, detect the package manager (pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm) and ask: "New devDependencies added. Run
```
<pm> install
```
?"

Workflow warning: if any

.github/workflows/

files were copied, check for the secret:

bash

if command -v gh &> /dev/null && gh secret list 2>/dev/null | grep -q "CLAUDE_CODE_OAUTH_TOKEN"; then
  # Secret exists — no warning needed
else
  warn: "GitHub workflows added. You'll need to set CLAUDE_CODE_OAUTH_TOKEN as a repo secret (Settings → Secrets → Actions)."
fi

Hook warning: if
```
.claude/settings.json
```
references hook scripts at
```
~/.claude/hooks/
```
, check if each script exists on disk. Warn about any missing ones.

Dotfiles sync: Ask the user if they want to install user-level configs:

ai-env includes user-level configs for Claude and Codex (hooks, skills, profiles).
Install them? Run: $AI_ENV_ROOT/dotfiles/sync.sh push
(where $AI_ENV_ROOT is the template source directory)
This copies dotfiles/claude/ → ~/.claude/ and dotfiles/codex/ → ~/.codex/

If they agree, run

"$TEMPLATE_SOURCE/dotfiles/sync.sh" push

from the template source directory (not cwd).

Auto-add post-setup todos via TodoWrite:
- "Update AGENTS.md — fill in Stack, Commands, Architecture, Gotchas for your project"
- "Update .claude/agents/ descriptions to reference your project"
- "Run
```
$TEMPLATE_SOURCE/dotfiles/sync.sh push
```
  to deploy user-level configs (if not done above)"
- "Review .claude/settings.json hooks and adjust paths for your environment"
Summary: print a list of all files created, merged, and skipped.

创建

ai-workspace/.template-version

文件，内容为：

version: <清单版本号>
applied: <ISO 8601 时间戳>
source: <模板源路径>

依赖检查： 如果package.json中新增了devDependencies，检测包管理器（存在pnpm-lock.yaml → pnpm，存在yarn.lock → yarn，存在package-lock.json → npm）并询问："已新增devDependencies。是否执行
```
<pm> install
```
？"

工作流警告： 如果复制了任何

.github/workflows/

下的文件，检查密钥：

bash

if command -v gh &> /dev/null && gh secret list 2>/dev/null | grep -q "CLAUDE_CODE_OAUTH_TOKEN"; then
  # 密钥存在 — 无需警告
else
  警告: "已新增GitHub工作流。你需要将CLAUDE_CODE_OAUTH_TOKEN设置为仓库密钥（设置 → 密钥 → Actions）。"
fi

钩子警告： 如果
```
.claude/settings.json
```
引用了
```
~/.claude/hooks/
```
下的钩子脚本，检查磁盘上是否存在每个脚本。对缺失的脚本发出警告。

Dotfiles同步： 询问用户是否要安装用户级配置：

ai-env包含适用于Claude和Codex的用户级配置（钩子、技能、配置文件）。
是否安装？执行: $AI_ENV_ROOT/dotfiles/sync.sh push
（$AI_ENV_ROOT为模板源目录）
该操作会将dotfiles/claude/ → 复制到 ~/.claude/，dotfiles/codex/ → 复制到 ~/.codex/

如果用户同意，从模板源目录（而非当前工作目录）执行

"$TEMPLATE_SOURCE/dotfiles/sync.sh" push

。

通过TodoWrite自动添加后置待办项：
- "更新AGENTS.md — 填写项目的Stack、Commands、Architecture、Gotchas部分"
- "更新 .claude/agents/ 下的描述，关联你的项目"
- "执行
```
$TEMPLATE_SOURCE/dotfiles/sync.sh push
```
  部署用户级配置（如果之前未执行）"
- "审查 .claude/settings.json 中的钩子，调整为适合你的环境的路径"
汇总： 打印所有创建、合并、跳过的文件列表。

Phase 5 — Context Migration (prompted, not automatic)

阶段5 — 上下文迁移（需要用户触发，非自动）

This phase scans for ALL existing AI context, memory, and configuration in the target repo and walks the user through migration interactively. Never delete or overwrite context automatically — every action requires explicit user confirmation.

该阶段扫描目标仓库中所有已存在的AI上下文、记忆和配置，引导用户交互式完成迁移。绝不自动删除或覆盖上下文 — 每个操作都需要用户明确确认。

Discovery scan

发现扫描

Check ALL of the following locations. If none have content, skip this phase entirely with a message: "No existing AI context found — skipping migration."

Project-scoped (in repo):

```
ai-workspace/MEMORY.md
```
— project memory (check if it has content beyond the seed template)
```
ai-workspace/plans/
```
— existing plans (especially
```
.done.md
```
completed plans)
```
ai-workspace/decisions/
```
— existing ADRs
```
ai-workspace/scratchpad.md
```
— working notes
```
ai-workspace/workflow.md
```
— custom workflow (may differ from template)
```
.claude/skills/
```
— pre-existing skills (not from this template run)
```
.claude/agents/
```
— pre-existing agent definitions
```
.claude/rules/
```
— pre-existing rules
```
.claude/settings.json
```
— project permissions, hooks, deny rules
```
.claude/settings.local.json
```
— local-only overrides (not checked in)
```
.codex/config.toml
```
— Codex configuration with profiles
```
CLAUDE.md
```
— existing Claude instruction file
```
AGENTS.md
```
— existing universal instruction file
```
GEMINI.md
```
— Gemini-specific instructions (if present)
```
.cursorrules
```
or
```
.cursor/rules/
```
— Cursor-specific rules (if present)
```
.claudeignore
```
/
```
.codexignore
```
— existing context exclusions

.github/workflows/claude.yml

claude-code-review.yml

— existing CI workflows

User-scoped (outside repo — read-only, inform user):

```
~/.claude/projects/<path-encoded-cwd>/memory/
```
— Claude Code auto-memories for this project
- Path encoding: replace
```
/
```
  with
```
-
```
  , e.g.,
```
-Users-patrickcamacho-projects-myapp
```
- Each
```
.md
```
  file has frontmatter with
```
name
```
  ,
```
description
```
  ,
```
type
```
  (user/feedback/project/reference)

~/.claude/projects/<path-encoded-cwd>/MEMORY.md

— auto-memory index for this project

```
~/.claude/CLAUDE.md
```
— user's global instructions (may reference project patterns)
```
~/.claude/hooks/
```
— global hook scripts that project hooks may duplicate
```
~/.claude/agents/
```
— global agent definitions that project agents may shadow
```
~/.claude/commands/
```
— global slash commands (catchup, reflect, etc.)
```
~/.claude/plugins/
```
— installed plugins (check
```
enabledPlugins
```
in settings)

检查以下所有位置。如果所有位置都没有内容，跳过该阶段并提示："未找到已存在的AI上下文 — 跳过迁移。"

项目范围（仓库内）：

```
ai-workspace/MEMORY.md
```
— 项目记忆（检查是否包含种子模板之外的内容）
```
ai-workspace/plans/
```
— 已存在的计划（特别是
```
.done.md
```
结尾的已完成计划）
```
ai-workspace/decisions/
```
— 已存在的架构决策记录(ADR)
```
ai-workspace/scratchpad.md
```
— 工作笔记
```
ai-workspace/workflow.md
```
— 自定义工作流（可能与模板不同）
```
.claude/skills/
```
— 预先存在的技能（非本次模板运行新增）
```
.claude/agents/
```
— 预先存在的Agent定义
```
.claude/rules/
```
— 预先存在的规则
```
.claude/settings.json
```
— 项目权限、钩子、拒绝规则
```
.claude/settings.local.json
```
— 仅本地生效的覆盖配置（不提交到仓库）
```
.codex/config.toml
```
— 带配置文件的Codex配置
```
CLAUDE.md
```
— 已存在的Claude指令文件
```
AGENTS.md
```
— 已存在的通用指令文件
```
GEMINI.md
```
— Gemini专属指令（如果存在）
```
.cursorrules
```
或
```
.cursor/rules/
```
— Cursor专属规则（如果存在）
```
.claudeignore
```
/
```
.codexignore
```
— 已存在的上下文排除规则

.github/workflows/claude.yml

或

claude-code-review.yml

— 已存在的CI工作流

用户范围（仓库外 — 只读，仅告知用户）：

```
~/.claude/projects/<路径编码后的当前工作目录>/memory/
```
— Claude Code为该项目自动生成的记忆
- 路径编码规则：将
```
/
```
  替换为
```
-
```
  ，例如
```
-Users-patrickcamacho-projects-myapp
```
- 每个
```
.md
```
  文件包含带有
```
name
```
  、
```
description
```
  、
```
type
```
  （user/feedback/project/reference）的前置元数据

~/.claude/projects/<路径编码后的当前工作目录>/MEMORY.md

— 该项目的自动记忆索引

```
~/.claude/CLAUDE.md
```
— 用户的全局指令（可能引用项目模式）
```
~/.claude/hooks/
```
— 全局钩子脚本，项目钩子可能重复这些内容
```
~/.claude/agents/
```
— 全局Agent定义，项目Agent可能覆盖这些定义
```
~/.claude/commands/
```
— 全局斜杠命令（catchup、reflect等）
```
~/.claude/plugins/
```
— 已安装的插件（检查settings中的
```
enabledPlugins
```
）

Present findings

展示发现结果

Show the user a categorized summary:

Context Migration — Found <N> items across <M> locations:

  Memory:
    - ai-workspace/MEMORY.md (42 lines, last updated 2026-03-15)
    - ~/.claude/projects/.../memory/ (6 files: 2 user, 2 feedback, 2 project)

  Plans & Decisions:
    - ai-workspace/plans/001-feature.done.md (completed, immutable)
    - ai-workspace/decisions/001-architecture.md

  Skills:
    - .claude/skills/deploy/SKILL.md (custom, not in template)
    - .claude/skills/validate/SKILL.md (CONFLICTS with template version)

  Agents & Rules:
    - .claude/agents/implementer.md (customized from template)
    - .claude/rules/feature-branches.md (matches template)

  Configuration:
    - .claude/settings.json (12 allow rules, 3 hooks, 2 deny rules)
    - .codex/config.toml (custom profiles: review, deploy)

  Instruction Files:
    - CLAUDE.md (project-specific, references @AGENTS.md)
    - AGENTS.md (customized — 5 sections differ from template)

  CI Workflows:
    - .github/workflows/claude.yml (existing, may need permission updates)

  User-scoped (informational):
    - ~/.claude/projects/.../memory/feedback_testing.md
    - ~/.claude/hooks/post-edit-format.sh (also referenced in project settings)

Wait for user to review before proceeding to migration steps.

向用户展示分类汇总：

上下文迁移 — 在<M>个位置共找到<N>个条目：

  记忆:
    - ai-workspace/MEMORY.md (42行，最后更新于2026-03-15)
    - ~/.claude/projects/.../memory/ (6个文件：2个用户类、2个反馈类、2个项目类)

  计划与决策:
    - ai-workspace/plans/001-feature.done.md (已完成，不可变更)
    - ai-workspace/decisions/001-architecture.md

  技能:
    - .claude/skills/deploy/SKILL.md (自定义，不在模板中)
    - .claude/skills/validate/SKILL.md (与模板版本冲突)

  Agent与规则:
    - .claude/agents/implementer.md (基于模板自定义)
    - .claude/rules/feature-branches.md (与模板一致)

  配置:
    - .claude/settings.json (12条允许规则、3个钩子、2条拒绝规则)
    - .codex/config.toml (自定义配置文件：review、deploy)

  指令文件:
    - CLAUDE.md (项目专属，引用@AGENTS.md)
    - AGENTS.md (已自定义 — 5个部分与模板不同)

  CI工作流:
    - .github/workflows/claude.yml (已存在，可能需要更新权限)

  用户范围（仅告知）:
    - ~/.claude/projects/.../memory/feedback_testing.md
    - ~/.claude/hooks/post-edit-format.sh (同时在项目配置中被引用)

等待用户确认后再进入迁移步骤。

1. Memory — ai-workspace/MEMORY.md

1. 记忆 — ai-workspace/MEMORY.md

If both template and target have

ai-workspace/MEMORY.md

with real content:

Merge strategy (semantic, not line-by-line):

Read both files completely. The template MEMORY.md has this seed structure:

markdown

# Project Memory
> Living document updated by /reflect after each task. 200-line limit.
> Last updated: —

## Key Decisions
## Implementation Status
## Gotchas

Preserve ALL content from the target's MEMORY.md — this is accumulated project knowledge
If the target is missing sections from the template seed (Key Decisions, Implementation Status, Gotchas), add them as empty sections at the end
If the target has extra sections not in the template, keep them
Update the header comment to include the template's
```
> Living document...
```
line if missing
Present the merged result and ask the user to confirm

If only target has content: keep it, add missing template sections. If only template has content: copy the seed template (fresh start).

如果模板和目标端都包含有实际内容的

ai-workspace/MEMORY.md

：

合并策略（语义合并，而非逐行合并）：

完整读取两个文件。模板的MEMORY.md包含以下种子结构：

markdown

# 项目记忆
> 动态文档，每次任务完成后通过/reflect命令更新。上限200行。
> 最后更新: —

## 关键决策
## 实现状态
## 注意事项

保留目标端MEMORY.md中的所有内容 — 这是积累的项目知识。
如果目标端缺少模板种子中的部分（关键决策、实现状态、注意事项），将它们作为空部分添加到末尾。
如果目标端有模板中不存在的额外部分，保留它们。
如果缺失，在头部注释中添加模板的
```
> Living document...
```
行。
展示合并结果并请求用户确认。

如果仅目标端有内容： 保留内容，添加缺失的模板部分。 如果仅模板有内容： 复制种子模板（全新开始）。

2. Memory — Claude Code auto-memories (~/.claude/projects/)

2. 记忆 — Claude Code自动记忆 (~/.claude/projects/)

These are user-scoped and managed by Claude Code's built-in memory system. They live outside the repo and are NOT migrated automatically. Instead, inform the user:

List each memory file with its
```
name
```
,
```
type
```
, and
```
description
```
from frontmatter
Explain: "These are Claude Code's per-project memories stored at
```
~/.claude/projects/.../memory/
```
. They persist across sessions and inform Claude's behavior for this project."
Ask: "Are any of these stale or incorrect? I can flag them for your review but won't modify them during template application."
If any
```
project
```
or
```
reference
```
type memories contain information that should be in
```
ai-workspace/MEMORY.md
```
instead (so other agents can see it), suggest the user move that content manually

这些属于用户范围，由Claude Code内置的记忆系统管理。它们存储在仓库外，不会自动迁移。需要告知用户：

列出每个记忆文件的前置元数据中的
```
name
```
、
```
type
```
和
```
description
```
说明："这些是Claude Code的项目专属记忆，存储在
```
~/.claude/projects/.../memory/
```
。它们会跨会话保留，为Claude处理该项目的行为提供上下文。"
询问："这些记忆中是否有过期或错误的内容？我可以标记出来供你审查，但在模板应用过程中不会修改它们。"
如果有任何
```
project
```
或
```
reference
```
类型的记忆包含应该放到
```
ai-workspace/MEMORY.md
```
中的信息（以便其他Agent也能访问），建议用户手动迁移这些内容。

3. Plans and decisions

3. 计划与决策

Completed plans (
```
*.done.md
```
): Always preserve — these are immutable records. Inform the user they exist.
Active plans (no
```
.done.md
```
suffix): Ask if still in progress or should be marked done.
ADRs: Always preserve — immutable after commit. Check if any reference patterns that the template changes (warn if so).
Templates (
```
TEMPLATE.md
```
): Replace with template version if different (these are scaffolding, not content).
scratchpad.md: If non-empty, ask user whether to preserve, archive, or reset.
workflow.md: If target has a custom workflow that differs from template, present both and ask which to keep (or merge).

已完成计划（
```
*.done.md
```
）：始终保留 — 这些是不可变更的记录。告知用户这些文件存在。
活跃计划（无
```
.done.md
```
后缀）：询问是否仍在进行中，还是应该标记为已完成。
ADR：始终保留 — 提交后不可变更。检查是否有引用模板变更的模式，如果有则发出警告。
模板文件（
```
TEMPLATE.md
```
）：如果与模板版本不同则替换为模板版本（这些是脚手架，不是内容）。
scratchpad.md：如果非空，询问用户是保留、归档还是重置。
workflow.md：如果目标端有与模板不同的自定义工作流，展示两个版本并询问用户保留哪个（或合并）。

4. Skills

4. 技能

For each skill directory in

.claude/skills/

Not in template (custom skill): Keep as-is. Inform user it's preserved.
Same name as template skill (e.g., both have
```
validate/SKILL.md
```
):
- Diff the two versions
- Present the differences to the user
- Options: keep target version, replace with template, or merge (user reviews merged output)
Template has new skills not in target: These were already copied in Phase 2. Just inform the user.

对

.claude/skills/

下的每个技能目录：

不在模板中（自定义技能）：原样保留。告知用户该技能已被保留。
与模板技能同名（例如双方都有
```
validate/SKILL.md
```
）：
- 对比两个版本的差异
- 向用户展示差异
- 选项：保留目标版本、替换为模板版本、或合并（用户审查合并结果）
模板新增的技能（目标端不存在）：这些已在阶段2中复制。仅告知用户即可。

5. Agents, rules, and commands

5. Agent、规则与命令

For each file in

.claude/agents/

and

.claude/rules/

Same file exists in both: Diff them. If target has customizations (model changes, extra instructions, project-specific context), present the diff. Default: keep target version for agents (they're often customized), keep template version for rules (they're more structural).
New from template: Already copied in Phase 2. Inform user.
Target-only (custom): Preserve. Inform user.

Check for shadowing between global and project agents:

If
```
~/.claude/agents/architect.md
```
and
```
.claude/agents/architect.md
```
both exist, note that the project version takes precedence.

对

.claude/agents/

和

.claude/rules/

下的每个文件：

双方都存在相同文件： 对比差异。如果目标端有自定义内容（模型变更、额外指令、项目专属上下文），展示差异。默认规则：Agent文件优先保留目标版本（通常会被自定义），规则文件优先保留模板版本（更偏向结构规范）。
模板新增文件： 已在阶段2中复制。告知用户即可。
仅目标端存在（自定义）： 保留。告知用户即可。

检查全局Agent和项目Agent的覆盖情况：

如果
```
~/.claude/agents/architect.md
```
和
```
.claude/agents/architect.md
```
都存在，提示项目版本优先级更高。

6. Settings and permissions

6. 设置与权限

For

.claude/settings.json

This was already smart-merged in Phase 3. Summarize what was added/changed.
Specifically call out:
- Hooks: List which hooks exist in both global (
```
~/.claude/settings.json
```
  ) and project. Per the hook placement rule: global hooks = personal workflow, project hooks = codebase contract. Warn if the same hook appears in both (unnecessary duplication of expensive hooks).
- Deny rules: Any new deny patterns from the template
- Allow rules: Any new allow patterns (user should review these)
- Plugins: If
```
enabledPlugins
```
  or
```
disabledMcpjsonServers
```
  are present, list them

For

.claude/settings.local.json

Never touch. Inform user it exists and what it contains.

For

.codex/config.toml

If target has custom profiles, preserve them. Merge any new template profiles that don't collide.

对于

.claude/settings.json

：

该文件已在阶段3中完成智能合并。汇总展示新增/变更的内容。
特别说明：
- 钩子： 列出同时存在于全局（
```
~/.claude/settings.json
```
  ）和项目中的钩子。根据钩子放置规则：全局钩子 = 个人工作流，项目钩子 = 代码库约定。如果同一个钩子在两边都存在则发出警告（不必要的重复，会增加开销）。
- 拒绝规则： 所有从模板新增的拒绝模式。
- 允许规则： 所有从模板新增的允许模式（用户应审查这些内容）。
- 插件： 如果存在
```
enabledPlugins
```
  或
```
disabledMcpjsonServers
```
  ，列出这些内容。

对于

.claude/settings.local.json

：

绝不修改。告知用户该文件存在及其内容。

对于

.codex/config.toml

：

如果目标端有自定义配置文件，保留它们。合并不冲突的模板新增配置文件。

7. Instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules)

7. 指令文件（CLAUDE.md、AGENTS.md、GEMINI.md、.cursorrules）

AGENTS.md: Already merged in Phase 3. Summarize what sections were added/preserved.
CLAUDE.md: If target has a custom CLAUDE.md that doesn't just
```
@AGENTS.md
```
:
- Read it. Identify project-specific instructions vs boilerplate.
- Preserve project-specific content. Add template boilerplate sections if missing.
GEMINI.md: If present, inform user. Template doesn't provide one — this is the user's custom file. Preserve.
.cursorrules: If present, inform user that AGENTS.md is the preferred universal format. Ask if
```
.cursorrules
```
content should be merged into AGENTS.md or kept separately.

AGENTS.md： 已在阶段3中完成合并。汇总展示新增/保留的部分。
CLAUDE.md： 如果目标端有自定义的CLAUDE.md，且内容不只是
```
@AGENTS.md
```
：
- 读取内容。区分项目专属指令和样板内容。
- 保留项目专属内容。如果缺失则添加模板的样板部分。
GEMINI.md： 如果存在，告知用户。模板不提供该文件 — 这是用户的自定义文件，予以保留。
.cursorrules： 如果存在，告知用户AGENTS.md是推荐的通用格式。询问是否要将
```
.cursorrules
```
的内容合并到AGENTS.md中，还是单独保留。

8. CI workflows

8. CI工作流

.github/workflows/claude.yml

claude-code-review.yml

existed before template application:

Diff with template versions
Call out permission differences (
```
contents: read
```
vs
```
write
```
, missing
```
allowed_tools
```
)
Present upgrade path if target workflows have weaker permissions

如果模板应用前已存在

.github/workflows/claude.yml

或

claude-code-review.yml

：

与模板版本对比差异
说明权限差异（
```
contents: read
```
与
```
write
```
、缺失的
```
allowed_tools
```
）
如果目标工作流的权限更宽松，提供升级路径。

9. Context exclusions (.claudeignore, .codexignore)

9. 上下文排除规则（.claudeignore、.codexignore）

```
.claudeignore
```
: Handle separately from
```
.gitignore
```
. Check if target has one. If so, union-merge (same strategy as
```
.gitignore
```
). If not, copy template version.
```
.codexignore
```
: If present, preserve. Template doesn't provide one.

```
.claudeignore
```
：与
```
.gitignore
```
分开处理。检查目标端是否存在该文件。如果存在，执行并集合并（与
```
.gitignore
```
的合并策略相同）。如果不存在，复制模板版本。
```
.codexignore
```
：如果存在，予以保留。模板不提供该文件。

Summary prompt

汇总确认

After presenting all findings, ask:

Ready to apply these migration decisions? (y/n)

You can also:
  - "skip" to skip migration entirely (all files from Phases 2-4 are already applied)
  - "details <item>" to see the full diff for any item above

Key principle: This phase is informational and advisory. The user has final say on every decision. Present what exists, explain what the template expects, and recommend — but never act without confirmation.

展示所有发现结果后，询问：

是否准备好应用这些迁移决策？(y/n)

你也可以：
  - 输入"skip"完全跳过迁移（阶段2-4的所有文件已完成应用）
  - 输入"details <条目>"查看任意上述条目的完整差异

核心原则： 该阶段仅提供信息和建议。用户对所有决策拥有最终决定权。展示现有内容，说明模板的预期，给出建议 — 但绝不未经确认就执行操作。

Re-application

重复应用

When running on a repo that already has

ai-workspace/.template-version

```
copy_if_absent
```
files are smart-merged if present (picks up template additions while preserving customizations)
```
smart_merge
```
files are always re-merged (this is how template updates flow)
If the user passes
```
--force
```
, overwrite
```
copy_if_absent
```
files completely instead of merging

在已存在

ai-workspace/.template-version

的仓库上运行时：

```
copy_if_absent
```
类型的文件如果已存在则执行智能合并（在保留自定义内容的同时新增模板内容）
```
smart_merge
```
类型的文件始终重新合并（这是模板更新的推送方式）
如果用户传入
```
--force
```
参数，直接覆盖
```
copy_if_absent
```
类型的文件，而非合并

apply-template

Original

Translation

Apply ai-env Template

应用ai-env模板

Phase 0 — Pre-flight

阶段0 — 预检查

Clean working tree check

清理工作树检查

Phase 1 — Source Resolution & Discovery

阶段1 — 源解析与发现

Locate template source

定位模板源

Read manifest

读取清单

Scan target

扫描目标目录

Present plan

展示执行计划

Phase 2 — Copy

阶段2 — 复制

Phase 3 — Smart Merge

阶段3 — 智能合并

AGENTS.md — Semantic Merge

AGENTS.md — 语义合并

tsconfig.json — Deep Merge

tsconfig.json — 深度合并

.claude/settings.json

.claude/settings.json

package.json

package.json

biome.json

biome.json

.gitignore

.gitignore

skills-lock.json — Union Merge

skills-lock.json — 并集合并

Directories: .claude/agents/, .claude/rules/, .claude/skills/

目录: .claude/agents/、.claude/rules/、.claude/skills/

Phase 4 — Post-Apply

阶段4 — 应用后处理

Phase 5 — Context Migration (prompted, not automatic)

阶段5 — 上下文迁移（需要用户触发，非自动）

Discovery scan

发现扫描

Present findings

展示发现结果

1. Memory — ai-workspace/MEMORY.md

1. 记忆 — ai-workspace/MEMORY.md

2. Memory — Claude Code auto-memories (~/.claude/projects/)

2. 记忆 — Claude Code自动记忆 (~/.claude/projects/)

3. Plans and decisions

3. 计划与决策

4. Skills

4. 技能

5. Agents, rules, and commands

5. Agent、规则与命令

6. Settings and permissions

6. 设置与权限

7. Instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules)

7. 指令文件（CLAUDE.md、AGENTS.md、GEMINI.md、.cursorrules）

8. CI workflows

8. CI工作流

9. Context exclusions (.claudeignore, .codexignore)

9. 上下文排除规则（.claudeignore、.codexignore）

Summary prompt

汇总确认

Re-application

重复应用

Directories:
`.claude/agents/`
,
`.claude/rules/`
,
`.claude/skills/`

目录:
`.claude/agents/`
、
`.claude/rules/`
、
`.claude/skills/`