遷移佈局 是做什麼的？
概覽
上游的 agent-skills 將工作檔案放在專案根目錄。團隊則將它們放在 .claude-work/（請參閱團隊覆寫中的路徑表）。此技能將正在進行中的專案遷移到團隊佈局，並使用單一 commit。每個檔案都會保留其 git 歷史。任務核取方塊會隨著檔案移動，因此工作可以從中斷處繼續進行。
引數是規劃和工作檔案的 <id>，例如 /agent-skills-jksim:migrate-layout fl-debug。
使用時機
- 專案根目錄存在
SPEC.md、tasks/plan.md、tasks/todo.md或CONSTRAINTS.md。 - 專案同時存在根工作檔案和
.claude-work/。
不要在全新專案中使用。spec 階段從一開始就會寫入 .claude-work/。
流程
1. 檢查起始狀態
當以下任一情況成立時，停止並告知使用者：
- 該資料夾不是 git 儲存庫。
git status --porcelain --untracked-files=no顯示已追蹤檔案有變更。要求使用者先 commit 或 stash 這些變更。未追蹤的檔案可以保留：步驟 8 使用git add -u進行暫存，它永遠不會加入未追蹤的檔案。git check-ignore -q .claude-work/spec/SPEC.md執行成功。檢查檔案路徑：像.claude-work/這樣的模式在資料夾存在之前無法匹配它。消費端專案會 commit.claude-work/。
2. 找出舊檔案
僅查看以下路徑（相對於專案根目錄）：
| 舊路徑 | 團隊路徑 |
|---|---|
SPEC.md、docs/SPEC.md | .claude-work/spec/SPEC.md |
SPEC-<module>.md | .claude-work/spec/SPEC-<module>.md |
CAPABILITY-MAP.md | .claude-work/spec/CAPABILITY-MAP.md |
tasks/plan.md | .claude-work/tasks/plan-<id>.md |
tasks/todo.md | .claude-work/tasks/todo-<id>.md |
CONSTRAINTS.md | .claude-work/docs/CONSTRAINTS.md |
docs/ideas/<name>.md | .claude-work/docs/ideas/<name>.md |
docs/intent/<topic>.md | .claude-work/docs/intent/<topic>.md |
docs/decisions/ | 保留。詢問（請參閱步驟 4） |
不要碰 spec/。RSpec 和其他測試佈局會使用它。
僅使用 git 追蹤的檔案（git ls-files）。git mv 在其他檔案上會失敗。列出任何未追蹤或被忽略的舊檔案，並詢問使用者。
當沒有舊檔案存在時，告知使用者沒有東西可以遷移。停止。
3. 取得 <id>
使用引數。如果沒有引數，從專案名稱建議一個簡短的 kebab-case id，並詢問使用者。當沒有 tasks/plan.md 或 tasks/todo.md 時，跳過此步驟。
4. 顯示計畫並等待批准
顯示一個表格：舊路徑、新路徑。然後列出每個衝突並詢問：
- 目標已存在： 團隊路徑上已有檔案。不要移動該檔案。詢問該如何處理。
- 兩個 spec：
SPEC.md和docs/SPEC.md同時存在。詢問哪一個是 spec。 tasks/中的其他檔案： 僅移動plan.md和todo.md。列出其他檔案。docs/decisions/存在： 預設是保留它，因為專案會保留自己的 ADR 資料夾。僅在使用者要求時，才將其移動到.claude-work/docs/adr/。
在使用者批准表格之前，不要移動任何東西。
5. 使用 git mv 移動
對每個檔案執行 git mv <old> <new>。先建立目標資料夾（mkdir -p）。絕對不要複製後刪除：git mv 可以保留歷史。如果 tasks/ 變成空的，則執行 rmdir tasks。
6. 修正即時參照
在專案中搜尋舊路徑：git grep -n -E 'SPEC(-[A-Za-z0-9_-]+)?\.md|CAPABILITY-MAP\.md|CONSTRAINTS\.md|tasks/(plan|todo)\.md|docs/(ideas|intent|decisions)/'。
同時搜尋裸檔案名稱，因為已移動的檔案可能會在沒有資料夾的情況下提及它的夥伴：git grep -n -E '(^|[^-/A-Za-z0-9_])(plan|todo)\.md'。範例：計畫中的 "detail in todo.md" 會變成 "detail in todo-.md"。
即時參照 告訴讀者或 agent 檔案現在的位置。修改它：
CLAUDE.md："SPEC.md: approved spec" 變成 ".claude-work/spec/SPEC.md: approved spec"。README.md：[SPEC.md](SPEC.md)變成[SPEC.md](.claude-work/spec/SPEC.md)。- 已移動檔案中的相對連結：舊的
tasks/plan.md中的../SPEC.md變成.claude-work/tasks/plan-<id>.md中的../spec/SPEC.md。 CLAUDE.md中的約束指標行。- 每個已移動檔案中的其他相對連結。已移動的檔案位於新的深度，因此指向未移動檔案的連結也會中斷。範例：根目錄
SPEC-foo.md中的[x](src/a.kt)會變成.claude-work/spec/SPEC-foo.md中的[x](../../src/a.kt)。
記錄 告訴我們過去發生的事情。保持原樣：
- 已完成的任務條目："檔案： README.md、SPEC.md"。
- 變更日誌、審查註記或 commit 訊息。
當你不確定時，保留文字並在步驟 7 中列出它。
7. 顯示結果
顯示 git status、已變更參照的 diff，以及你未變更的舊路徑參照列表，並附上每個項目的原因。
8. 一次性提交
git mv 已經暫存了移動操作。使用 git add -u 暫存已編輯的參照。不要使用 git add -A：它可能會加入不相關的檔案。使用訊息 Move working files to .claude-work 進行提交。不要推送。
如果鉤子 (hook) 拒絕了提交，則停止並回報。不要使用 --no-verify。
9. 回報下一步
告訴使用者哪些檔案已移動、哪些保留了。如果 .claude-work/docs/VOCABULARY.md 不存在，則說明下一個 spec 階段會建立它（規則 2）。現在不要建立它。
常見的合理化理由
| 合理化理由 | 現實情況 |
|---|---|
"複製比 git mv 簡單。" | 複製會遺失檔案歷史。審查者和 git log --follow 需要它。 |
"我會更新 SPEC.md 的每個提及。" | 記錄描述過去。修改它們等於改寫歷史。 |
| "工作目錄樹有點髒而已。" | 未提交的工作最終會進入遷移 commit。先詢問使用者。 |
| "計畫很明顯，所以我就跳過批准了。" | 使用者決定 <id> 和每個衝突。請等待。 |
紅旗標誌
git log --follow在遷移 commit 之前沒有顯示歷史。- 已完成的任務條目或變更日誌提到了當時不存在的團隊路徑。
spec/或docs/decisions/在未經使用者批准的情況下移動了。- 超過一個 commit，或進行了推送。
驗證
- 每個舊檔案都在其團隊路徑上。根目錄下沒有留下舊檔案，除非使用者選擇保留的檔案。
-
git log --follow <new path>顯示了舊歷史。 - 即時參照指向團隊路徑。記錄保持不變。
- 任務核取方塊保持不變。
- 一個 commit，訊息為 "Move working files to .claude-work"。
git status是乾淨的。沒有推送任何東西。