From cc-nexs
cc-nexs 创建新需求或恢复需求工作时确保自己处在隔离 git worktree 内,让多个需求可以并行开发互不干扰。流程:检测已有隔离 → git worktree 兜底创建 → 验证 .gitignore → 切目录与分支。触发词:worktree、并行需求、隔离工作目录、init 前准备、多需求并行、独立工作树。
How this skill is triggered — by the user, by Claude, or both
Slash command
/cc-nexs:using-worktreesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> cc-nexs 多需求并行开发的 worktree 管理 skill。三个核心约定:
cc-nexs 多需求并行开发的 worktree 管理 skill。三个核心约定:
- 不使用 Claude Code 内置 EnterWorktree——cc-nexs 要求 worktree 落在仓库的
.worktrees/<id>-<slug>/(项目根隐藏目录),与内置工具的.claude/worktrees/路径不一致。直接用git worktree add保证路径可控。- 嵌套 refuse:cc-nexs 一个 worktree 对应一个需求,禁止在 worktree 内再 init 新需求。
- gitignore 自治:skill 自动给宿主仓库加
.worktrees/到.gitignore并 commit(仅当未 ignore 时)。
/cc-nexs:init 默认调用本 skill 创建新 worktree(除非 --no-worktree)/cc-nexs:run 调用——run 只做 sanity check(detect cwd 是否在期望 worktree 内)调用方传入两个必需值:
feature_id(如 01、14.2)feature_slug(如 api-health-check)派生:
<repo-root>/.worktrees/<feature_id>-<feature_slug>/feature/<feature_id>-<feature_slug>执行结束后返回(在最后一行 echo 一段固定格式):
WORKTREE_PATH=<absolute path>
BRANCH=feature/<id>-<slug>
STATUS=created | reused | refused_nested | failed_fallback_inplace
调用方(init.md)按 STATUS 分支:
created / reused → 后续步骤在 worktree 内执行refused_nested → 调用方应 abort,提示用户回主仓库failed_fallback_inplace → 调用方退回 git checkout -b 旧路径GIT_DIR=$(cd "$(git rev-parse --git-dir 2>/dev/null)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null && pwd -P)
SUPERPROJECT=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
判断:
[ -n "$SUPERPROJECT" ] → 在 submodule,当作普通仓库继续(不是 worktree)[ "$GIT_DIR" != "$GIT_COMMON" ] 且非 submodule → 已在 linked worktree❌ 当前已在 worktree(路径:<cwd>,分支:<branch>)
cc-nexs 不允许在 worktree 内再 init 新需求。
请先 cd 回主仓库再执行 /cc-nexs:init。
输出 STATUS=refused_nested,直接返回,不再走 Step 1+。
REPO_ROOT=$(git rev-parse --show-toplevel)
WORKTREE_PATH="${REPO_ROOT}/.worktrees/${ID}-${SLUG}"
BRANCH="feature/${ID}-${SLUG}"
如果 $WORKTREE_PATH 已存在(比如用户重跑 init):
git worktree list | grep -F "$WORKTREE_PATH")STATUS=reused,cd 进去,跳过创建.worktrees/ 在 .gitignorecd "$REPO_ROOT"
if ! git check-ignore -q .worktrees 2>/dev/null; then
# 未被 ignore,追加并 commit
GITIGNORE="${REPO_ROOT}/.gitignore"
if [ -f "$GITIGNORE" ] && grep -qE '^\.worktrees/?$' "$GITIGNORE"; then
: # 已经写了但 git 还不识别(比如 .gitignore 本身没 commit)
else
printf '\n# cc-nexs worktrees(每个需求一个隔离工作树,不入主仓库)\n.worktrees/\n' >> "$GITIGNORE"
fi
git add .gitignore
git commit -m "chore: ignore .worktrees/ for cc-nexs"
fi
边界:若
.gitignore处于 staged 但未 commit 的中间状态,commit 会把用户其他改动一起带进来——所以git add只点名.gitignore,不用-A。
git worktree add "$WORKTREE_PATH" -b "$BRANCH"
失败处理:
git worktree add "$WORKTREE_PATH" "$BRANCH"(不带 -b,复用现有分支)STATUS=failed_fallback_inplace,让调用方退回原地建分支STATUS=failed_fallback_inplacecd "$WORKTREE_PATH"
最后输出:
✅ Worktree 已就绪
路径: <绝对路径>
分支: feature/<id>-<slug>
宿主: <主仓库路径>
WORKTREE_PATH=<绝对路径>
BRANCH=feature/<id>-<slug>
STATUS=created
注意:Bash 工具的 cwd 状态不跨 tool call 持久化。所以"cd 进去"在单条 Bash 命令链里有效,多条命令必须在同一次 Bash 调用里串起来(用
&&),或者由调用方在每条命令前主动cd "$WORKTREE_PATH"。init.md 处理这个细节。
| 情况 | 行为 |
|---|---|
| 已在 linked worktree(非 submodule) | refuse_nested,让用户回主仓库 |
| 在 submodule 内 | 当普通仓库继续 |
.worktrees/<id>-<slug> 已存在且是有效 worktree | reused |
.worktrees/<id>-<slug> 已存在但不是 worktree(孤儿目录) | 报错让用户手动清理 |
.worktrees/ 未被 gitignore | 自动追加并 commit |
git worktree add 因权限失败 | failed_fallback_inplace |
| 分支已存在 | 复用(不加 -b) |
Claude Code 内置 EnterWorktree 工具会把 worktree 放到 .claude/worktrees/。cc-nexs 的产品决策是固定 .worktrees/(仓库根隐藏目录)让多机器多协作者路径一致,所以不用内置工具——这是路径稳定性优先于工具复用的有意取舍。
cc-nexs 的语义是 1 个 worktree = 1 个需求。嵌套 init 会让分支命名、.worktrees/ 检测、清理流程都混乱。Step 0 直接 refuse。
只在工作区写 .worktrees/ 不够——git check-ignore 用的是 staged + committed 状态。skill 里 git add .gitignore && git commit 是必须的。
git add -A宿主仓库可能有未 commit 的工作。skill 只 git add .gitignore,不要污染用户其他改动。
worktree 对状态机透明:
progress.md 记录的 current_state 不变doc/<id>/ 下读写/cc-nexs:run 只在 Step -1 做 cwd 一致性检查(在主仓库直接 run 会被拒)/cc-nexs:run 末尾打印手动清理指令清理时机由用户决定(典型流程):
cd <repo-root>git worktree remove .worktrees/<id>-<slug>git branch -d feature/<id>-<slug>(已 merge 的本地分支)npx claudepluginhub tanageleee/cc-nexs --plugin cc-nexsGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.