Issue Worktree

概览

把“issue → 可工作的本地目录”这件事做成可重复、低认知负担的流程：解析 GitHub/Linear issue，生成稳定的分支名与 worktree 路径，并用 git worktree 创建/复用工作区。

路径说明：以下命令以“项目级 skill”路径 .claude/skills/issue-worktree 为例；如果你把它安装到个人目录，请把路径替换为 ~/.claude/skills/issue-worktree。

•
让用户给出“issue 标识”即可（GitHub 或 Linear 其一）。如果用户没说清来源，优先从形态推断：
- •GitHub：#123 / 123 / owner/repo#123 / https://github.com/.../issues/123
- •Linear：ABC-123 / https://linear.app/.../ABC-123

需要确认的偏好（只在不确定时问，避免追问过多）：

第一性原理：git worktree 只需要一个分支名就能工作；issue 的 title/url 只是为了生成更可读的 <slug> 与便于输出提示。

因此建议把“取 issue 信息”交给 MCP（GitHub/Linear 都可以），再把 title/url 传给脚本，避免本机依赖 gh / LINEAR_API_KEY。

如果你已经配置了对应的 MCP：

然后执行脚本时带上 --title/--url（脚本会跳过外部 fetch）：

bash

python scripts/issue_worktree.py "<issue>" \
  --title "<title-from-mcp>" \
  --url "<url-from-mcp>"

在目标 git 仓库内执行（或用 --repo 指定仓库路径）：

bash

python scripts/issue_worktree.py "<issue>"

常用参数：

bash

python scripts/issue_worktree.py "<issue>" \
  --base main \
  --worktrees-root ../worktrees \
  --dry-run

完全离线（不尝试从任何渠道拉取 issue 元信息）：

bash

python scripts/issue_worktree.py "<issue>" --no-fetch

如果你已经在上层逻辑里生成好了分支名（例如用 MCP + 自定义规则），也可以直接传 --branch：

bash

python scripts/issue_worktree.py --branch "issue/gh-123-some-slug"

脚本行为约定（保持 KISS + 可预测）：

在仓库根目录放一个仅个人使用的 JSON（建议 gitignore）：.worktree-links.local.json，脚本会在创建 worktree 后自动应用。

示例：

json

[
  { "src": "~/.secrets/myrepo/.env", "dest": ".env" },
  { "src": "~/.ssh/config", "dest": ".ssh/config" }
]

说明：

•若你希望“必须校验 issue 存在”，推荐用 MCP 做校验（脚本默认允许降级继续执行）
•解析 #123 失败：检查 origin remote 是否存在且指向 GitHub；必要时用 owner/repo#123 或 issue URL 明确仓库
•Linear 解析失败：确认输入是 ABC-123 或 Linear URL；若需要 title/slug，请确保 MCP 或其他渠道能提供 title