new-workspace

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create New Git Workspace

创建新的Git工作区

Create a branch or Git worktree without confusing project-level management with code-repo management.

Use this skill for code, experiment, baseline, feature, or rebuttal branches. In a full research project, the usual target repo is

<ProjectName>/code/

, and worktrees should live under

<ProjectName>/code-worktrees/

Pair this skill with:

```
safe-git-ops
```
for non-trivial Git state, conflicts, or sandbox write failures
```
research-project-memory
```
to record worktree purpose and exit condition
```
remote-project-control
```
when the worktree will be used on an SSH/HPC server
```
run-experiment
```
when the new workspace immediately launches jobs

创建分支或Git worktree，避免将项目级管理与代码仓库管理混淆。

此技能适用于代码开发、实验、基准测试、功能开发或反驳修正分支。在完整科研项目中，常规目标仓库为

<ProjectName>/code/

，worktree应存放于

<ProjectName>/code-worktrees/

目录下。

可搭配以下技能使用：

```
safe-git-ops
```
：用于处理复杂Git状态、冲突或沙箱写入失败问题
```
research-project-memory
```
：记录worktree的用途和终止条件
```
remote-project-control
```
：当worktree将在SSH/HPC服务器上使用时
```
run-experiment
```
：当新工作区需立即启动任务时

Core Principles

核心原则

Create worktrees for the code repo, not for the whole project root.
Prefer sibling code worktrees under
```
<ProjectName>/code-worktrees/
```
.
Avoid nested worktrees inside
```
code/
```
unless the user explicitly requires that layout.
Every research worktree should have a purpose, linked claim/risk/experiment, and exit condition.
```
experiments/
```
is runnable logic; stable result summaries belong in
```
docs/results/
```
, reports in
```
docs/reports/
```
, and run pointers in
```
docs/runs/
```
.
Each worktree gets its own
```
.venv/
```
after
```
uv sync
```
.

为代码仓库创建worktree，而非整个项目根目录。
优先将代码worktree作为同级目录存放在
```
<ProjectName>/code-worktrees/
```
下。
除非用户明确要求，否则避免在
```
code/
```
目录内嵌套worktree。
每个科研worktree都应具备明确用途、关联的论点/风险/实验，以及终止条件。
```
experiments/
```
目录用于存放可运行逻辑；稳定的结果摘要需放在
```
docs/results/
```
，报告放在
```
docs/reports/
```
，运行指针放在
```
docs/runs/
```
。
执行
```
uv sync
```
后，每个worktree都会拥有独立的
```
.venv/
```
环境。

Step 1 - Classify the Target

步骤1 - 分类目标

Ask the user for:

workspace type:
```
branch
```
or
```
worktree
```

branch type:

feature

exp

baseline

debug

rebuttal

paper-fix

, or custom

branch name without prefix
target repo path, if not obvious
whether to write worktree memory

If running inside

<ProjectName>/

, prefer the

code/

repo for experiment, baseline, debug, and rebuttal implementation work.

If running inside

<ProjectName>/code/

, infer:

text

code repo root:      <ProjectName>/code/
project control root: <ProjectName>/
worktree root:      <ProjectName>/code-worktrees/

If running inside a standalone code repo, use the fallback worktree root:

text

<code-repo-parent>/worktrees/

向用户确认以下信息：

工作区类型：
```
branch
```
或
```
worktree
```
分支类型：
```
feature
```
、
```
exp
```
、
```
baseline
```
、
```
debug
```
、
```
rebuttal
```
、
```
paper-fix
```
或自定义类型
无前缀的分支名称
目标仓库路径（若不明确）
是否需要写入worktree记忆

若在

<ProjectName>/

目录下操作，优先选择

code/

仓库进行实验、基准测试、调试和反驳修正相关的开发工作。

若在

<ProjectName>/code/

目录下操作，可推断：

text

code repo root:      <ProjectName>/code/
project control root: <ProjectName>/
worktree root:      <ProjectName>/code-worktrees/

若在独立代码仓库内操作，使用备用worktree根目录：

text

<code-repo-parent>/worktrees/

Step 2 - Verify Git State

步骤2 - 验证Git状态

In the target repo:

bash

git -C <repo-root> rev-parse --show-toplevel
git -C <repo-root> status --short
git -C <repo-root> branch --show-current
git -C <repo-root> worktree list

If there are uncommitted changes, ask whether to commit, stash, continue with a branch only, or cancel.

在目标仓库中执行以下命令：

bash

git -C <repo-root> rev-parse --show-toplevel
git -C <repo-root> status --short
git -C <repo-root> branch --show-current
git -C <repo-root> worktree list

若存在未提交的更改，询问用户是提交、暂存、仅创建分支还是取消操作。

Step 3 - Choose Branch Name

步骤3 - 选择分支名称

Use:

text

<branch-type>/<branch-name>

Examples:

```
exp/new-loss
```
```
baseline/fair-tuning
```
```
debug/nan-loss
```
```
rebuttal/add-ablation
```
```
feature/data-loader
```

The worktree directory name should be filesystem-friendly:

text

<branch-type>-<branch-name-with-slashes-replaced-by-hyphens>

采用以下命名格式：

text

<branch-type>/<branch-name>

示例：

```
exp/new-loss
```
```
baseline/fair-tuning
```
```
debug/nan-loss
```
```
rebuttal/add-ablation
```
```
feature/data-loader
```

worktree目录名称需符合文件系统规范：

text

<branch-type>-<branch-name-with-slashes-replaced-by-hyphens>

Step 4 - Create a Branch

步骤4 - 创建分支

For branch-only work:

bash

git -C <repo-root> checkout -b <branch-type>/<branch-name>

Then update component memory if the branch has a research purpose.

仅需创建分支时：

bash

git -C <repo-root> checkout -b <branch-type>/<branch-name>

若分支具备科研用途，更新组件记忆。

Step 5 - Create a Worktree

步骤5 - 创建Worktree

Determine the worktree root:

<repo-root>

<ProjectName>/code/

, use

<ProjectName>/code-worktrees/

If
```
<repo-root>/../code-worktrees/
```
exists, use that.
If project memory declares a code worktree root, use that.
Otherwise use
```
<repo-root>/../worktrees/
```
.

Create the worktree:

bash

mkdir -p <worktree-root>
git -C <repo-root> worktree add <worktree-root>/<worktree-dir-name> -b <branch-type>/<branch-name>

If the branch already exists, ask whether to create the worktree from the existing branch:

bash

git -C <repo-root> worktree add <worktree-root>/<worktree-dir-name> <branch-type>/<branch-name>

确定worktree根目录：

若

<repo-root>

为

<ProjectName>/code/

，则使用

<ProjectName>/code-worktrees/

。

若
```
<repo-root>/../code-worktrees/
```
目录存在，则使用该目录。
若项目记忆中声明了代码worktree根目录，则使用该目录。
否则使用
```
<repo-root>/../worktrees/
```
。

创建worktree：

bash

mkdir -p <worktree-root>
git -C <repo-root> worktree add <worktree-root>/<worktree-dir-name> -b <branch-type>/<branch-name>

若分支已存在，询问用户是否基于现有分支创建worktree：

bash

git -C <repo-root> worktree add <worktree-root>/<worktree-dir-name> <branch-type>/<branch-name>

Step 6 - Copy Local Tooling and Link Shared Assets

步骤6 - 复制本地工具配置并关联共享资源

Copy local IDE/tooling directories when present:

text

.vscode/
.cursor/
.claude/

Copy, do not symlink, because each worktree may need independent IDE state.

<repo-root>/.worktree-links

exists, read relative paths from it and symlink shared large assets into the worktree. Typical entries:

text

data/
models/
.env
configs/local_settings.yaml

Use absolute symlink targets so links remain valid from the worktree path.

复制存在的本地IDE/工具目录：

text

.vscode/
.cursor/
.claude/

采用复制而非符号链接的方式，因为每个worktree可能需要独立的IDE状态。

若

<repo-root>/.worktree-links

文件存在，读取其中的相对路径并将大型共享资源符号链接到worktree中。典型条目包括：

text

data/
models/
.env
configs/local_settings.yaml

使用绝对路径作为符号链接目标，确保链接在worktree路径下依然有效。

Step 7 - Prepare Code-Side Evidence Paths

步骤7 - 准备代码端证据路径

In the worktree, ensure:

text

docs/results/
docs/reports/
docs/runs/
.agent/

Use these paths for branch-local evidence:

```
docs/results/
```
: stable result summaries, table notes, figure notes
```
docs/reports/
```
: experiment reports and result narratives
```
docs/runs/
```
: job IDs, config paths, commit hashes, remote paths, short metrics
```
.agent/worktree-status.md
```
: purpose, linked claims/risks, latest reliable state, exit condition

Do not store raw logs, checkpoints, wandb runs, tensorboard caches, or large outputs in

docs/

在worktree中确保以下目录存在：

text

docs/results/
docs/reports/
docs/runs/
.agent/

将这些路径用于分支本地证据存储：

```
docs/results/
```
：稳定的结果摘要、表格说明、图表说明
```
docs/reports/
```
：实验报告和结果叙述
```
docs/runs/
```
：任务ID、配置路径、提交哈希、远程路径、简短指标
```
.agent/worktree-status.md
```
：用途、关联的论点/风险、最新可靠状态、终止条件

请勿在

docs/

目录中存储原始日志、检查点、wandb运行记录、tensorboard缓存或大型输出文件。

Step 8 - Sync Environment

步骤8 - 同步环境

pyproject.toml

exists in the worktree:

bash

cd <worktree-path>
uv sync

uv sync

fails, report the error but do not delete the worktree. The user may still want to inspect or fix the branch.

若worktree中存在

pyproject.toml

文件：

bash

cd <worktree-path>
uv sync

若

uv sync

执行失败，报告错误但不删除worktree。用户可能仍需检查或修复分支。

Step 9 - Write Worktree Memory

步骤9 - 写入Worktree记忆

If the workspace has a research purpose, create or update:

text

<worktree>/.agent/worktree-status.md

Include:

branch
path
created date
parent branch
purpose
linked claims, experiments, risks, or reviewer issues
expected difference from main branch
result/output paths
exit condition: merge, continue, park, or kill
next verification step

If project memory exists, also add a short pointer to:

```
memory/component-index.yaml
```
: known worktree path
```
memory/action-board.md
```
: next action for the worktree
```
memory/current-status.md
```
: only if this is the active focus

若工作区具备科研用途，创建或更新以下文件：

text

<worktree>/.agent/worktree-status.md

文件需包含：

分支信息
路径
创建日期
父分支
用途
关联的论点、实验、风险或审稿人问题
与主分支预期的差异
结果/输出路径
终止条件：合并、继续、暂停或删除
下一步验证步骤

若存在项目记忆，还需添加指向以下文件的简短指针：

```
memory/component-index.yaml
```
：已知worktree路径
```
memory/action-board.md
```
：worktree的下一步操作
```
memory/current-status.md
```
：仅当此worktree为当前重点时添加

Step 10 - Final Summary

步骤10 - 最终总结

Report:

text

Workspace created

Repo: <repo-root>
Branch: <branch-type>/<branch-name>
Worktree: <path or branch-only>
Evidence paths:
  docs/results/
  docs/reports/
  docs/runs/
Memory:
  .agent/worktree-status.md <created|skipped>

Next:
  cd <worktree-path>
  uv sync
  run or edit the planned experiment

报告内容示例：

text

工作区已创建

仓库：<repo-root>
分支：<branch-type>/<branch-name>
Worktree：<路径或仅分支>
证据路径：
  docs/results/
  docs/reports/
  docs/runs/
记忆：
  .agent/worktree-status.md <已创建|已跳过>

下一步操作：
  cd <worktree-path>
  uv sync
  运行或编辑计划中的实验

Error Handling

错误处理

Not a Git repo: stop and ask for the target repo.
Dirty tree: ask whether to commit, stash, continue, or cancel.
Branch exists: ask whether to use existing branch or choose a new name.
Worktree path exists: ask whether to choose a new name or inspect existing path.
Sandbox blocks Git metadata writes: treat as a permission issue and use
```
safe-git-ops
```
.
UV sync fails: keep the worktree and report the environment issue.

非Git仓库：停止操作并询问目标仓库路径。
未提交更改：询问用户是提交、暂存、继续还是取消操作。
分支已存在：询问用户是使用现有分支还是选择新名称。
Worktree路径已存在：询问用户是选择新名称还是检查现有路径。
沙箱阻止Git元数据写入：视为权限问题，使用
```
safe-git-ops
```
技能处理。
UV sync失败：保留worktree并报告环境问题。

Configuration File Template

配置文件模板

.worktree-links

does not exist, offer to create:

text

undefined

若

.worktree-links

文件不存在，可提供创建模板：

text

undefined

.worktree-links

Symlinks to create in new worktrees.

在新worktree中创建的符号链接。

List paths relative to the code repo root.

列出相对于代码仓库根目录的路径。

data/

models/

.env

configs/local_settings.yaml

undefined

undefined

Final Sanity Check

最终检查

Before finishing:

branch or worktree was created in the intended code repo
worktree is not nested inside
```
code/
```
unless explicitly requested
```
git worktree list
```
shows the expected path
evidence paths exist in the worktree
worktree memory records purpose and exit condition when relevant
project memory is updated only with durable pointers, not logs

完成操作前确认：

分支或worktree已在预期的代码仓库中创建
worktree未嵌套在
```
code/
```
目录内（除非明确要求）
```
git worktree list
```
显示预期路径
worktree中存在证据路径
相关情况下，worktree记忆已记录用途和终止条件
仅使用持久化指针更新项目记忆，而非日志