十一個名字，一個命名空間：把 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，以及本站工作流程文件（三種語言）裡的每一處引用。在階段一之後做意味著順序必須是：先改技能 → 改引用技能的命令 → 改引用命令的文件。順序錯了會在 commit 間留下指向錯誤的指標。

階段三 — 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 替你做。這是我們最自豪的部分。