rlm-worktree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

RLM Git Worktree Isolation (Phase 0)

RLM Git Worktree 隔离（第0阶段）

Overview

概述

Git worktrees create isolated workspaces sharing the same repository, allowing parallel development without switching branches. This prevents:

Pollution of main/master branch during development
Accidental commits to production branches
Context switching overhead
Conflicts between parallel requirements

Core Principle: Systematic directory selection + safety verification = reliable isolation.

The Iron Law for RLM Worktrees:

NEVER WORK ON MAIN/MASTER BRANCH WITHOUT EXPLICIT CONSENT

Git worktree可创建共享同一仓库的隔离工作区，支持并行开发无需切换分支。这可以避免：

开发过程中污染main/master分支
意外提交到生产分支
上下文切换的开销
并行需求之间的冲突

核心原则： 系统化的目录选择 + 安全验证 = 可靠的隔离环境。

RLM Worktree 铁律：

NEVER WORK ON MAIN/MASTER BRANCH WITHOUT EXPLICIT CONSENT

When to Use

使用场景

REQUIRED for all RLM runs:

New features
Bug fixes
Refactoring
Experiments/prototypes

Insert as Phase 0:

Phase 0: 00-worktree.md (isolated workspace setup)
    ↓
Phase 1: 00-requirements.md (already exists)
    ↓
Phase 2: 01-as-is.md

所有RLM运行的必要步骤：

新功能开发
Bug修复
代码重构
实验/原型开发

作为第0阶段插入：

Phase 0: 00-worktree.md (隔离工作区搭建)
    ↓
Phase 1: 00-requirements.md (已存在)
    ↓
Phase 2: 01-as-is.md

The Worktree Rule

Worktree 规则

<HG> Do NOT proceed with any RLM phase until: 1. Isolated worktree is created on feature branch 2. Worktree directory is git-ignored (if project-local) 3. Clean test baseline is verified 4. User has explicitly consented if main branch work requested </HG>

<HG> 在完成以下步骤前，不得推进任何RLM阶段： 1. 在功能分支上创建隔离的worktree 2. Worktree目录已被git忽略（如果是项目本地目录） 3. 验证干净的测试基线 4. 若需要在主分支上工作，需获得用户明确同意 </HG>

Directory Selection Process

目录选择流程

Step 1: Check Existing Directories

步骤1：检查现有目录

bash

undefined

bash

undefined

Check in priority order

按优先级检查

ls -d .worktrees 2>/dev/null # Preferred (hidden) ls -d worktrees 2>/dev/null # Alternative


**If found:** Use that directory. If both exist, `.worktrees` wins.

ls -d .worktrees 2>/dev/null # 首选（隐藏目录） ls -d worktrees 2>/dev/null # 备选


**如果找到：** 使用该目录。若两者都存在，优先选择`.worktrees`。

Step 2: Check CLAUDE.md

步骤2：检查CLAUDE.md

bash

grep -i "worktree.*director" CLAUDE.md 2>/dev/null
grep -i "worktrees" CLAUDE.md 2>/dev/null

If preference specified: Use it without asking.

bash

grep -i "worktree.*director" CLAUDE.md 2>/dev/null
grep -i "worktrees" CLAUDE.md 2>/dev/null

如果有指定偏好： 直接使用该目录，无需询问。

Step 3: Ask User (if no convention exists)

步骤3：询问用户（若无约定）

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden - RECOMMENDED)
2. ~/.config/rlm-workflow/worktrees/<project-name>/ (global location)

Which would you prefer? (1/2)

Default:

.worktrees/

(option 1)

未找到worktree目录。请问应在何处创建worktree？

1. .worktrees/（项目本地，隐藏目录 - 推荐）
2. ~/.config/rlm-workflow/worktrees/<project-name>/（全局位置）

您更倾向于哪一个？(1/2)

默认选项：

.worktrees/

（选项1）

Safety Verification

安全验证

For Project-Local Directories (.worktrees or worktrees)

针对项目本地目录（.worktrees或worktrees）

MUST verify directory is ignored before creating worktree:

bash

undefined

创建worktree前必须验证目录已被忽略：

bash

undefined

Check if directory is ignored (respects local, global, and system gitignore)

检查目录是否被忽略（遵循本地、全局和系统gitignore规则）

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null


**If NOT ignored:**

Per "Fix broken things immediately" rule:
1. Add appropriate line to .gitignore:

RLM worktrees

.worktrees/

2. Commit the change:
```bash
git add .gitignore
git commit -m "chore: ignore RLM worktree directory"

Proceed with worktree creation

Why critical: Prevents accidentally committing worktree contents to repository.

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null


**如果未被忽略：**

遵循“立即修复问题”规则：
1. 向.gitignore添加相应内容：

RLM worktrees

.worktrees/

2. 提交更改：
```bash
git add .gitignore
git commit -m "chore: ignore RLM worktree directory"

继续创建worktree

为什么这很关键： 防止意外将worktree内容提交到仓库。

For Global Directory (~/.config/rlm-workflow/worktrees)

针对全局目录（~/.config/rlm-workflow/worktrees）

No .gitignore verification needed - outside project entirely.

无需验证.gitignore - 完全位于仓库外部。

Worktree Creation Process

Worktree 创建流程

Step 1: Detect Project Name

步骤1：检测项目名称

bash

project=$(basename "$(git rev-parse --show-toplevel)")
branch_name="rlm/${run_id}"

bash

project=$(basename "$(git rev-parse --show-toplevel)")
branch_name="rlm/${run_id}"

Step 2: Check Current Branch

步骤2：检查当前分支

bash

current_branch=$(git branch --show-current)

if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
    # STOP - Require explicit consent
    echo "WARNING: Currently on $current_branch branch."
    echo "RLM Workflow requires isolated worktrees."
    echo ""
    read -p "Create worktree and switch to feature branch? (yes/no): " consent
    
    if [ "$consent" != "yes" ]; then
        echo "Aborted. Please run from a feature branch or consent to worktree creation."
        exit 1
    fi
fi

bash

current_branch=$(git branch --show-current)

if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
    # 停止 - 需要明确同意
    echo "WARNING: Currently on $current_branch branch."
    echo "RLM Workflow requires isolated worktrees."
    echo ""
    read -p "Create worktree and switch to feature branch? (yes/no): " consent
    
    if [ "$consent" != "yes" ]; then
        echo "Aborted. Please run from a feature branch or consent to worktree creation."
        exit 1
    fi
fi

Step 3: Create Worktree with New Branch

步骤3：创建带新分支的Worktree

bash

undefined

bash

undefined

Determine full path

确定完整路径

case $LOCATION in .worktrees|worktrees) path="$LOCATION/$run_id" ;; ~~/.config/rlm-workflow/worktrees/*) path="~~/.config/rlm-workflow/worktrees/$project/$run_id" ;; esac

Create worktree with new branch

创建带新分支的worktree

git worktree add "$path" -b "$branch_name" cd "$path"

undefined

git worktree add "$path" -b "$branch_name" cd "$path"

undefined

Step 4: Run Project Setup

步骤4：运行项目搭建

Auto-detect and run appropriate setup:

bash

undefined

自动检测并运行相应的搭建命令：

bash

undefined

Node.js

if [ -f package.json ]; then echo "Detected Node.js project" npm install fi

Rust

if [ -f Cargo.toml ]; then echo "Detected Rust project" cargo build fi

Python

if [ -f requirements.txt ]; then echo "Detected Python project (requirements.txt)" pip install -r requirements.txt elif [ -f pyproject.toml ]; then echo "Detected Python project (pyproject.toml)" poetry install || pip install -e . fi

Go

if [ -f go.mod ]; then echo "Detected Go project" go mod download fi

Java/Maven

if [ -f pom.xml ]; then echo "Detected Maven project" mvn compile -q fi

Java/Gradle

if [ -f build.gradle ] || [ -f build.gradle.kts ]; then echo "Detected Gradle project" ./gradlew compileJava --quiet 2>/dev/null || gradlew compileJava --quiet 2>/dev/null fi

.NET

if [ -f *.csproj ] || [ -f *.sln ]; then echo "Detected .NET project" dotnet restore fi

undefined

if [ -f *.csproj ] || [ -f *.sln ]; then echo "Detected .NET project" dotnet restore fi

undefined

Step 5: Verify Clean Test Baseline

步骤5：验证干净的测试基线

Run tests to ensure worktree starts clean:

bash

undefined

运行测试以确保worktree初始状态正常：

bash

undefined

Detect test command and run

检测测试命令并运行

if [ -f package.json ]; then # Check for npm test script if grep -q '"test"' package.json; then echo "Running npm test..." npm test fi elif [ -f Cargo.toml ]; then echo "Running cargo test..." cargo test elif [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "Running pytest..." pytest -q || python -m pytest -q elif [ -f go.mod ]; then echo "Running go test..." go test ./... elif [ -f pom.xml ]; then echo "Running Maven tests..." mvn test -q elif [ -f build.gradle ] || [ -f build.gradle.kts ]; then echo "Running Gradle tests..." ./gradlew test --quiet 2>/dev/null || gradlew test --quiet 2>/dev/null elif [ -f *.csproj ] || [ -f *.sln ]; then echo "Running dotnet tests..." dotnet test --verbosity quiet fi


**If tests fail:**
- Report failures
- Ask whether to proceed or investigate
- Document decision in Phase 0 artifact

**If tests pass:**
- Report baseline verified
- Record test count and pass rate

if [ -f package.json ]; then # 检查是否有npm test脚本 if grep -q '"test"' package.json; then echo "Running npm test..." npm test fi elif [ -f Cargo.toml ]; then echo "Running cargo test..." cargo test elif [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "Running pytest..." pytest -q || python -m pytest -q elif [ -f go.mod ]; then echo "Running go test..." go test ./... elif [ -f pom.xml ]; then echo "Running Maven tests..." mvn test -q elif [ -f build.gradle ] || [ -f build.gradle.kts ]; then echo "Running Gradle tests..." ./gradlew test --quiet 2>/dev/null || gradlew test --quiet 2>/dev/null elif [ -f *.csproj ] || [ -f *.sln ]; then echo "Running dotnet tests..." dotnet test --verbosity quiet fi


**如果测试失败：**
- 报告失败情况
- 询问用户是继续还是调查问题
- 在第0阶段产物中记录决策

**如果测试通过：**
- 报告基线验证通过
- 记录测试数量和通过率

Step 6: Record in Phase 0 Artifact

步骤6：在第0阶段产物中记录

markdown

undefined

markdown

undefined

Worktree Details

Worktree 详情

Location:

/full/path/to/.worktrees/run-id

Branch:

rlm/run-id

Created from:

main

(commit: abc123) Setup commands executed:

npm install
npm test (47 passing, 0 failing)

Baseline verified: ✅

undefined

位置：

/full/path/to/.worktrees/run-id

分支：

rlm/run-id

从以下分支创建：

main

(提交哈希: abc123) 执行的搭建命令：

npm install
npm test (47个通过，0个失败)

基线验证： ✅

undefined

Main Branch Protection

主分支保护

Automatic Detection

自动检测

When user invokes "Implement requirement 'run-id'" from main/master:

bash

branch=$(git branch --show-current)

if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then
    echo "╔════════════════════════════════════════════════════════════╗"
    echo "║  ⚠️  MAIN BRANCH PROTECTION                                ║"
    echo "╠════════════════════════════════════════════════════════════╣"
    echo "║  You are currently on the $branch branch.                  ║"
    echo "║                                                            ║"
    echo "║  RLM Workflow requires isolated worktrees to:             ║"
    echo "║  • Prevent accidental commits to production               ║"
    echo "║  • Enable parallel requirement development                ║"
    echo "║  • Maintain clean main branch history                     ║"
    echo "║                                                            ║"
    echo "║  Options:                                                  ║"
    echo "║  1. Create worktree (RECOMMENDED)                          ║"
    echo "║  2. Switch to existing feature branch                      ║"
    echo "║  3. Abort and run from feature branch                      ║"
    echo "╚════════════════════════════════════════════════════════════╝"
    echo ""
    
    # Default to worktree creation
    echo "Creating worktree by default (press Ctrl+C to abort)..."
    sleep 3
fi

当用户在main/master分支上调用“Implement requirement 'run-id'”时：

bash

branch=$(git branch --show-current)

if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then
    echo "╔════════════════════════════════════════════════════════════╗"
    echo "║  ⚠️  主分支保护机制                                ║"
    echo "╠════════════════════════════════════════════════════════════╣"
    echo "║  您当前位于$branch分支。                  ║"
    echo "║                                                            ║"
    echo "║  RLM工作流要求使用隔离的worktree以：             ║"
    echo "║  • 防止意外提交到生产分支               ║"
    echo "║  • 支持并行需求开发                ║"
    echo "║  • 保持干净的主分支提交历史                     ║"
    echo "║                                                            ║"
    echo "║  选项：                                                  ║"
    echo "║  1. 创建worktree（推荐）                          ║"
    echo "║  2. 切换到已有的功能分支                      ║"
    echo "║  3. 终止操作，从功能分支重新运行                      ║"
    echo "╚════════════════════════════════════════════════════════════╝"
    echo ""
    
    # 默认创建worktree
    echo "将默认创建worktree（按Ctrl+C可终止）..."
    sleep 3
fi

Explicit Consent Required

需要明确同意

If user explicitly requests main branch work:

markdown

undefined

如果用户明确要求在主分支上工作：

markdown

undefined

Main Branch Work Acknowledgment

主分支工作确认

User has explicitly requested to work on main branch.

Acknowledged risks:

Commits go directly to production branch
No isolation for this requirement
Cannot run parallel requirements
Harder to discard if abandoned

Consent: User has chosen to proceed on main branch Reason: [user-provided reason] Recorded: [timestamp]

Recommendation: Use worktrees for future requirements.

undefined

用户已明确要求在主分支上工作。

已知风险：

提交直接进入生产分支
本次需求无隔离环境
无法并行处理多个需求
若放弃需求，清理难度更大

同意情况： 用户已选择在主分支上继续 原因： [用户提供的理由] 记录时间： [时间戳]

建议： 未来的需求请使用worktree。

undefined

Phase 0 Artifact Template

第0阶段产物模板

File:

/.codex/rlm/<run-id>/00-worktree.md

markdown

Run: `/.codex/rlm/<run-id>/`
Phase: `00 Worktree Setup`
Status: `DRAFT` | `LOCKED`
Inputs:
- Current git repository state
- User preference (for worktree location)
Outputs:
- `/.codex/rlm/<run-id>/00-worktree.md`
- Isolated worktree at `[location]`
Scope note: This document records isolated workspace setup and verifies clean test baseline.

文件路径：

/.codex/rlm/<run-id>/00-worktree.md

markdown

运行路径： `/.codex/rlm/<run-id>/`
阶段： `00 Worktree 搭建`
状态： `DRAFT` | `LOCKED`
输入项：
- 当前Git仓库状态
- 用户偏好（worktree位置）
输出项：
- `/.codex/rlm/<run-id>/00-worktree.md`
- 位于`[location]`的隔离worktree
范围说明：本文档记录隔离工作区的搭建过程，并验证干净的测试基线。

Directory Selection

目录选择

Convention checked:

```
.worktrees/
```
exists
```
worktrees/
```
exists
CLAUDE.md preference found
User preference obtained

Selected location:

.worktrees/

(project-local, hidden)

已检查的约定：

```
.worktrees/
```
已存在
```
worktrees/
```
已存在
找到CLAUDE.md中的偏好设置
已获取用户偏好

选定位置：

.worktrees/

（项目本地，隐藏目录）

Safety Verification

安全验证

Gitignore check:

bash

$ git check-ignore -q .worktrees && echo "IGNORED" || echo "NOT IGNORED"
IGNORED

Result: ✅ Directory is properly ignored

Gitignore检查：

bash

$ git check-ignore -q .worktrees && echo "IGNORED" || echo "NOT IGNORED"
IGNORED

结果： ✅ 目录已被正确忽略

Worktree Creation

Worktree 创建

Command:

bash

git worktree add .worktrees/run-id -b rlm/run-id

Output:

Preparing worktree (new branch 'rlm/run-id')
HEAD is now at abc1234 Previous commit message

Branch created:

rlm/run-id

Location:

/full/path/to/project/.worktrees/run-id

命令：

bash

git worktree add .worktrees/run-id -b rlm/run-id

输出：

Preparing worktree (new branch 'rlm/run-id')
HEAD is now at abc1234 Previous commit message

创建的分支：

rlm/run-id

位置：

/full/path/to/project/.worktrees/run-id

Project Setup

项目搭建

Detected project type: Node.js (package.json found)

Commands executed:

bash

cd .worktrees/run-id
npm install

Output:

added 472 packages in 8s

检测到的项目类型： Node.js（找到package.json）

执行的命令：

bash

cd .worktrees/run-id
npm install

输出：

added 472 packages in 8s

Test Baseline Verification

测试基线验证

Command:

bash

npm test

Results:

Total: 47 tests
Passed: 47
Failed: 0
Skipped: 0

Baseline: ✅ Clean (all tests passing)

命令：

bash

npm test

结果：

总测试数：47
通过：47
失败：0
跳过：0

基线状态： ✅ 干净（所有测试通过）

Main Branch Protection

主分支保护

Original branch:

main

Worktree branch:

rlm/run-id

Isolation: ✅ Working in isolated worktree

原始分支：

main

Worktree分支：

rlm/run-id

隔离状态： ✅ 在隔离的worktree中工作

Traceability

可追溯性

RLM process -> Isolated workspace established | Evidence: worktree at
```
.worktrees/run-id
```

RLM流程 -> 已建立隔离工作区 | 证据：位于
```
.worktrees/run-id
```
的worktree

Coverage Gate

覆盖检查

Approval Gate

审批检查

Isolated workspace ready for development
No pending setup issues
Ready to proceed to Phase 1/2

Approval: PASS / FAIL

LockedAt:

YYYY-MM-DDTHH:MM:SSZ

LockHash:

<sha256-hex>

undefined

隔离工作区已准备好进行开发
无未解决的搭建问题
已准备好进入第1/2阶段

审批结果： PASS / FAIL

锁定时间：

YYYY-MM-DDTHH:MM:SSZ

锁定哈希：

<sha256-hex>

undefined

Integration with RLM

与RLM的集成

Phase 0 → Phase 1 Transition

第0阶段 → 第1阶段过渡

Phase 0 must be locked before proceeding:

Verify worktree exists and is properly configured
Check Phase 0 gates are PASS
Lock Phase 0 artifact
Proceed to Phase 1 (requirements already exist)
All subsequent phases execute in worktree context

必须锁定第0阶段后才能继续：

验证worktree存在且配置正确
检查第0阶段的检查项是否全部通过
锁定第0阶段产物
进入第1阶段（需求分析），所有操作在worktree环境中执行
后续所有阶段均在worktree环境中执行

Worktree Context for All Phases

所有阶段的Worktree上下文

Once Phase 0 is complete:

All RLM commands run from worktree directory
Git operations target feature branch
Main branch remains untouched
Development is fully isolated

第0阶段完成后：

所有RLM命令均在worktree目录中运行
Git操作针对功能分支
主分支保持未修改状态
开发完全隔离

Phase 6/7 (Global Updates)

第6/7阶段（全局更新）

When updating global artifacts:

Changes are made in worktree context
Commits go to feature branch
User merges feature branch to main when ready
DECISIONS.md and STATE.md updates are part of the merge

当更新全局产物时：

在worktree环境中进行修改
提交到功能分支
用户准备好后将功能分支合并到主分支
DECISIONS.md和STATE.md的更新作为合并的一部分

Common Mistakes

常见错误

Skipping ignore verification

跳过忽略验证

Problem: Worktree contents get tracked, pollute git status
Fix: Always use
```
git check-ignore
```
before creating project-local worktree

问题： Worktree内容被追踪，污染Git状态
修复： 创建项目本地worktree前始终使用
```
git check-ignore
```
验证

Assuming directory location

假设目录位置

Problem: Creates inconsistency, violates project conventions
Fix: Follow priority: existing > CLAUDE.md > ask

问题： 导致不一致，违反项目约定
修复： 遵循优先级：现有目录 > CLAUDE.md > 询问用户

Proceeding with failing tests

测试失败仍继续

Problem: Can't distinguish new bugs from pre-existing issues
Fix: Report failures, get explicit permission to proceed

问题： 无法区分新bug与原有问题
修复： 报告失败情况，获取用户明确许可后再继续

Hardcoding setup commands

硬编码搭建命令

Problem: Breaks on projects using different tools
Fix: Auto-detect from project files (package.json, Cargo.toml, etc.)

问题： 在使用不同工具的项目上会失效
修复： 从项目文件自动检测（package.json、Cargo.toml等）

Red Flags

注意事项

Never:

Create worktree without verifying it's ignored (project-local)
Skip baseline test verification
Proceed with failing tests without asking
Assume directory location when ambiguous
Skip CLAUDE.md check
Work on main/master without explicit consent and documentation

Always:

Follow directory priority: existing > CLAUDE.md > ask
Verify directory is ignored for project-local
Auto-detect and run project setup
Verify clean test baseline
Create feature branch (rlm/run-id pattern)
Document worktree location in Phase 0 artifact

绝对不要：

创建项目本地worktree时不验证是否被忽略
跳过基线测试验证
测试失败未询问用户就继续
目录位置不明确时自行假设
跳过CLAUDE.md检查
未获得明确同意和记录就在main/master分支上工作

必须：

遵循目录优先级：现有目录 > CLAUDE.md > 询问用户
验证项目本地目录已被忽略
自动检测并运行项目搭建
验证干净的测试基线
创建符合
```
rlm/run-id
```
格式的功能分支
在第0阶段产物中记录worktree位置

Quick Reference

快速参考

Situation	Action
`.worktrees/` exists	Use it (verify ignored)
`worktrees/` exists	Use it (verify ignored)
Both exist	Use `.worktrees/`
Neither exists	Check CLAUDE.md → Ask user
Directory not ignored	Add to .gitignore + commit
Tests fail during baseline	Report failures + ask
On main/master branch	Create worktree (default)
User insists on main	Document consent, proceed with caution
No package.json/Cargo.toml	Skip dependency install

场景	操作
`.worktrees/` 已存在	使用该目录（验证是否被忽略）
`worktrees/` 已存在	使用该目录（验证是否被忽略）
两者都存在	使用 `.worktrees/`
两者都不存在	检查CLAUDE.md → 询问用户
目录未被忽略	添加到.gitignore并提交
基线测试失败	报告失败并询问用户
当前在main/master分支	默认创建worktree
用户坚持在主分支工作	记录同意情况，谨慎继续
无package.json/Cargo.toml	跳过依赖安装

Real-World Impact

实际效果

From development sessions:

Before worktrees: 15% of requirements had accidental main branch commits
After worktrees: 0% accidental main branch commits
Parallel development: 3+ requirements can be worked simultaneously
Clean main branch: Production history is clean and linear
Easy discard: Abandoned requirements don't pollute main branch

来自开发场景的数据：

使用worktree前： 15%的需求存在意外提交到主分支的情况
使用worktree后： 0%意外提交到主分支的情况
并行开发： 可同时处理3个以上需求
干净的主分支： 生产分支的提交历史干净且线性
易于丢弃： 已放弃的需求不会污染主分支

References

参考资料

REQUIRED: Use this skill for ALL RLM runs
TRIGGERS: At start of "Implement requirement 'run-id'"
OUTPUT:
```
00-worktree.md
```
artifact + isolated worktree
NEXT: Continue with Phase 1 (requirements) in worktree context

必须： 所有RLM运行都需使用该技能
触发时机： 在“Implement requirement 'run-id'”启动时
输出：
```
00-worktree.md
```
产物 + 隔离的worktree
下一步： 在worktree环境中继续第1阶段（需求分析）