using-jj-workspaces

使用 JJ Workspace

你需要帮助用户设置一个隔离的 jj workspace，以便并行开发，而不影响当前 workspace。

核心工作流：系统化选择目录并进行安全验证

1. 目录选择（按优先级排序）

按以下顺序检查 workspace 目录偏好：

1. 首先：检查项目根目录中是否存在 .workspaces/ 或 workspaces/ 目录
2. 其次：查看 CLAUDE.md 或类似的项目文档，了解 workspace 偏好
3. 最后：如果以上都不存在，询问用户：
   • 选项 A：创建项目本地目录（.workspaces/ 或 workspaces/）
   • 选项 B：使用全局位置（例如 ~/workspaces/）

绝不要自行假设——务必遵循此优先级顺序。

2. 安全验证（对项目本地目录至关重要）

如果使用项目本地目录（.workspaces/、workspaces/ 等）：

1. 检查 .gitignore（或 .jjignore，如果存在）中是否包含 workspace 目录模式
2. 如果未包含在 .gitignore 中：
   • 立即添加：echo "workspaces/" >> .gitignore（或 .workspaces/）
   • 提交此更改：jj describe -m "gitignore: Add workspaces directory"
   • 这样可以防止意外跟踪 workspace 内容

绝不要跳过此验证——这是一项关键的安全检查。

3. 创建 Workspace

# Detect project name from git/jj repository
PROJECT_NAME=$(basename $(jj workspace root))

# Construct workspace path
WORKSPACE_PATH="<selected-directory>/${PROJECT_NAME}-<branch-or-feature-name>"

# Create the workspace
jj workspace add "$WORKSPACE_PATH"

# JJ will automatically:
# - Create the directory
# - Set up a new workspace tracking the current repository
# - Create a new working-copy commit

4. 项目设置（自动检测并运行）

创建 workspace 后，检测项目类型并运行相应的设置：

检测模式：

• package.json → npm install 或 yarn install 或 pnpm install
• Cargo.toml → cargo build
• pyproject.toml → poetry install 或 pip install -e .
• flake.nix → nix develop 或 hey shell
• Gemfile → bundle install
• go.mod → go mod download

始终执行：

1. 切换到 workspace 目录：cd "$WORKSPACE_PATH"
2. 运行相应的设置命令
3. 向用户报告任何设置错误

5. 基线验证

报告成功之前，运行项目测试以确保状态正常：

# Attempt to run tests based on project type
# Examples:
npm test
cargo test
pytest
nix flake check
# etc.

如果基线测试失败：

• 向用户报告失败情况
• 除非用户明确同意，否则不要继续实施
• workspace 可能继承了不稳定的状态

6. 报告状态

提供清晰的摘要：

✓ JJ workspace created at: <path>
✓ Project setup completed: <command run>
✓ Baseline tests: <passed/failed>
✓ Ready to work on: <feature/branch name>

To switch to this workspace:
  cd <workspace-path>

To return to main workspace:
  cd <original-path>

To list all workspaces:
  jj workspace list

JJ Workspace 命令参考

# Create new workspace
jj workspace add <path>

# List all workspaces
jj workspace list

# Remove a workspace (doesn't delete files)
jj workspace forget <workspace-name>

# Show workspace root
jj workspace root

# Update workspace to latest changes
jj workspace update-stale

关键规则

1. 对项目本地 workspace 目录，绝不要跳过 .gitignore 验证
2. 始终遵循目录优先级系统——不要自行假设位置
3. 如果基线测试失败，必须先获得明确许可才能继续
4. workspace 就绪后，清楚地报告所有相关路径和命令
5. 自动检测并运行设置——不要让用户手动操作

JJ 特有注意事项

与 git worktree 不同，jj workspace：

• 共用同一份操作日志（可通过 jj op log 查看）
• 每个 workspace 都有自己的工作副本提交
• 一个 workspace 中的更改不会影响其他 workspace，除非明确移动或变基
• 无需指定分支——jj 会自动创建新的工作副本提交
• 使用 @ 指代当前 workspace 的工作副本提交

集成说明

此技能通常用于：

• 需要与主要工作隔离的功能开发
• 在不影响当前 workspace 的情况下测试更改
• 并行开发多个功能
• 可能会放弃的实验

适合搭配：

• 用于完成工作的 JJ squash 工作流
• JJ split，用于在移回主 workspace 前整理更改