十一个名字，一个命名空间：把 Coograph 统一在 /coograph-* 之下

Coograph 的技能和斜杠命令原本散落在三种前缀下。从今天起，每个出厂命令都以 /coograph- 开头。本文说明为什么改、改了什么，以及现有项目如何自动接收这次变更。

一个你得费力去记的工具，就是一个你不会用的工具。这是描述本周之前 Coograph 命令面状态最坦诚的方式。

要开新工单，你输入 /project:new-ticket（或者有时只是 new-ticket，取决于哪个工具在托管 Claude）。要提一个 spec 变更，输入 openspec-propose。要重建代码图：rebuild-code-graph。要跑 planner：/project:plan。三种前缀 — openspec-、/project:，外加裸名 — 用在一个产品出厂的所有技能上。自动补全菜单像抛硬币。

自 PR #10（关闭 #9）起，只剩一个前缀。

改名对照

技能：

斜杠命令（Claude Code）：

coograph-init 本来就对，原样保留。

唯一值得多说一句的新名字是 /coograph-search。旧的 /project:explore 是一条战术型的代码库问答命令 — “这个定义在哪、谁调用了那个、查所有用到 X 的地方”。我们另有一个叫 openspec-explore 的技能，实际内容是写 spec 前用的思考模式提示 — 像结对编程一样头脑风暴。两个旧名字里都带”explore”，但它们不是一回事，合并就会丢功能。把代码库搜索的斜杠命令改名成 /coograph-search，两者都保留，这条斜杠命令的新名字也终于描述了它做的事。

为什么以前不顺手 — 为什么我们等到现在

旧的前缀在引入当时各有道理。

openspec-* 来自我们采纳的 OpenSpec 规范格式，用在 Plan → Propose → Apply 工作流。给”这个技能作用在 spec 文件上”起的标签当时合理。然后我们加了一个思考模式提示，叫它 openspec-explore，它其实不是，名字开始对用户撒谎。

/project:* 是 Claude Code 给用户自己在项目里写的斜杠命令准备的命名空间。我们蹭它，因为头三个命令（plan、review、debug）感觉像通用的项目流命令，不是 Coograph 专属。几个月内我们出厂了五个，全是 Coograph 专属。这个命名空间不适配。

new-ticket 和 rebuild-code-graph 只是从缝里掉下来的。它们出现在任何前缀尝试之前。

我们等到现在才修，是因为改名 PR 的开销具有欺骗性。git mv 本身很快。慢的是下游的一切：文档引用、按字符串提到旧名字的代理提示，以及几个月前同步了 .claude/commands/ 的用户的迁移负担。我们想一次做完。

一个 PR 三个阶段

最终发布的变更是三个阶段，每个都有独立的坑，简单过一遍。

阶段一 — 技能改名。 把 .github/skills/ 下的六个目录搬走，更新每个 SKILL.md frontmatter 的 name: 字段使其与目录一致，修好技能之间的所有交叉引用。我们早早抓住一个碰撞风险：改完名的 coograph-explore（思考模式）会和一条同名为 explore 的斜杠命令撞名。我们把斜杠命令拆为 /coograph-search，两个都保住。阶段一动了 ~15 个文件，是最简单的阶段。

阶段二 — 斜杠命令搬迁。 把五个 .claude/commands/project/*.md 文件搬到 .claude/commands/coograph-*.md 顶层，更新 README.md、CLAUDE.md、planner agent、MIGRATION.md，以及本站工作流文档（三种语言）里的每一处文字引用。在阶段一之后做意味着顺序必须是：先改技能 → 改引用技能的命令 → 改引用命令的文档。顺序错了就会在提交之间留下断指针。

阶段三 — sync 脚本。 这才是真正决定现有用户是否能看到变更的阶段。剩余篇幅都给它。

现有项目如何自动接收改名

每个跑过 /coograph-init 的项目都会注册到 Coograph 仓库的 projects.json，进入一个 sync 循环：当 Coograph 产品仓库更新时，post-merge git 钩子会跑 .github/sync.py，遍历每个注册项目，把模板文件复制进去。本地 Coograph 安装就是靠这个保持最新，不用手动重跑 init。

改名前的 sync.py 有两个缺口，会让命名空间变更对老用户不可见：

1. 它只同步 .claude/commands/project/（子目录）。.claude/commands/ 顶层的新 coograph-*.md 包装根本没碰。用户拉完不会看到新的 /coograph-* 斜杠命令。
2. 只有当你的项目启用 vscode 工具时才同步 .github/skills/。Claude-only 的项目收不到新的 coograph-*/ 技能目录。

第三个缺口 — sync 只添加、不删除 — 会让老的 openspec-*/、new-ticket/、rebuild-code-graph/ 目录与新目录并排留下。自动补全里旧新两套名字会永远共存。

阶段三把三个缺口全堵上：

# .github/sync.py — 新增的模块级常量

OBSOLETE_PATHS = (
    # 2026-05-18 coograph-skill-rename — 旧技能目录
    ".github/skills/openspec-propose",
    ".github/skills/openspec-apply",
    ".github/skills/openspec-archive",
    ".github/skills/openspec-explore",
    ".github/skills/new-ticket",
    ".github/skills/rebuild-code-graph",
    # 2026-05-18 coograph-skill-rename — 旧斜杠命令包装
    ".claude/commands/project/new-ticket.md",
    ".claude/commands/project/plan.md",
    ".claude/commands/project/review.md",
    ".claude/commands/project/verify.md",
    ".claude/commands/project/debug.md",
    ".claude/commands/project/explore.md",
)

新的 _cleanup_obsolete(project_path) 帮助函数在每次 sync 之后遍历这个元组，删除消费端仍然存在的项。往 OBSOLETE_PATHS 添加条目从此成为把改名/删除推送到整个安装基的标准做法 — 不再需要逐用户的手动 rm。

.github/skills/ 从 VS Code 段提升到常驻复制段，对齐 coograph-init 在安装时已经做的事。Claude 工具路径里新加的一小段会 glob .claude/commands/coograph-*.md，把每个顶层包装复制过去。

最后一件：--dry-run 旗标。sync 现在是有破坏性的（清理会删文件），所以我们想要一种方式在不实际执行的情况下预览。python .github/sync.py --dry-run 会读注册表、用 [DRY-RUN] 前缀打印它将要做的每个动作、跳过 _ensure_hooks()、跳过代码图重建。一份针对错误 OBSOLETE_PATHS 条目的廉价保险。

你需要做什么

如果你的项目注册在 projects.json（凡是跑过 /coograph-init 的都是默认注册）：

cd path/to/coograph
git pull

完事。post-merge 钩子触发，sync 跑起来，你的项目拿到新的 .claude/commands/coograph-*.md 文件，旧的 openspec-*/ 技能目录消失，旧的 project/*.md 包装消失，你已有的 CLAUDE.md 和 copilot-instructions.md 不动（它们在 SKIP_FILES 里 — 用户所有）。

想先预览：

python .github/sync.py --dry-run

如果你的项目没注册，或者你 pin 在 pre-rename 的 sync.py 上，Coograph 仓库的 MIGRATION.md 里有手动指南。两条 rm -rf 和一条用我们给的 grep 手工更新 CLAUDE.md 引用。

我们故意留在地上的东西

这次 PR 里我们故意没出的清理是一项检查 — 检查你的仓库或 CI 是否还引用旧名字。我们的路线图里有一条”跨工具漂移检查” — 路线图 #2 — 会在 lint 阶段抓住残留引用。把漂移检查塞进这次改名 PR 很有吸引力；我们说不，因为改名已经三阶段了，我们想要干净的爆炸半径。

coograph.com/roadmap 上 #9 路线图条目的 brief 字段仍然引用旧名字，因为它是刚刚出厂工作的历史性描述。它会在关闭 GitHub issue 的同时由另一个 PR 撤下。

一个更小的元论点

命名是那种代价随使用量线性累积、修复成本随触达面规模化的事。我们大概有几十到几百个安装（注册表是本地的，我们不追踪），这次改名跨两个仓库动了 23 个文件。六个月后会动两倍。

如果你在做人类要敲字的工具 — 斜杠命令、CLI 子命令，任何 — 教训是第一天就选好规范前缀，从此不再引入第二个。我们没做到，这个 PR 就是补课的样子。

如果你是 Coograph 用户，你什么都不用做。git pull 替你做。这是我们最自豪的部分。