Jujutsu 工作流程
對於代理式編碼，只要存在 .jj/ 目錄，就優先使用 jj (Jujutsu) 而非原始 git — 它是更優越的本地變更層。Git 保留作為遠端/PR/CI/稽核的標準介面：使用 jj 進行變更，使用唯讀的 Git 進行驗證。
1. 偵測與閘控
執行 ${CLAUDE_SKILL_DIR}/scripts/detect_jj_state.sh，或手動檢查：
- 存在
.jj/→ 這是 jj 儲存庫：使用jj，絕不使用會改變狀態的原始git。 - 同時存在
.jj/和.git/→ 共置儲存庫：使用jj進行變更，使用 git 讀取，切勿碰觸 git 的索引/暫存區。 - 僅有
.git/→ 純 Git 儲存庫：除非被要求，否則不要引入jj。
請參閱 references/git-interop.md。
2. 代理安全規則（不可協商）
- 所有輸出指令務必加上
--no-pager；設定jj config set --user ui.paginate never。 - 務必加上
-m。絕不執行編輯器或 TUI 表單 — 單純的jj describe|commit|squash、jj split（互動式）、jj squash -i、jj resolve、jj diffedit— 這些都會卡住代理。 jj僅在執行 jj 指令時對工作目錄進行快照，並非每次檔案寫入時。
請參閱 references/agent-safety.md。
3. 編輯循環
jj --no-pager status
# 編輯檔案（將在下一個 jj 指令執行時進行快照）
jj --no-pager diff
jj describe -m "<專案慣例的提交訊息>"
j new -m "<下一個單元>" # 每個邏輯單元一個變更 — 避免產生一個巨大的提交
非互動式地拆分一個混合變更：jj split <path> -m "<訊息>"。請參閱 references/command-map.md。
4. 復原（可逆）
jj --no-pager op log → jj undo（復原上一次操作）或 jj op restore <id>。衝突是一等公民：jj status 會標記它們；透過編輯衝突標記解決衝突，然後驗證。請參閱 references/recovery-playbook.md。
5. 透過 Git 交接
jj git fetch
jj rebase -d <預設分支>
jj bookmark create <分支名稱> -r @-
jj git push --bookmark <分支名稱> # 新的書籤可直接推送
切勿推送到受保護的/預設分支；除非被允許，否則絕不重寫公開歷史。使用 gh/glab 開啟 PR。請參閱 references/pr-handoff.md。
6. 並行代理
每個並行代理使用各自的 jj workspace — 絕不共用一個工作目錄。請參閱 references/parallel-agents.md。
7. 完成前驗證
執行 ${CLAUDE_SKILL_DIR}/scripts/verify_handoff.sh，或報告 jj --no-pager status、jj --no-pager log --limit 10、jj --no-pager diff --stat、git status --short --branch。報告確切的指令與輸出；未經此步驟，絕不能聲稱「完成/已測試/準備就緒」；必須揭露強制推送、復原操作和衝突。
為什麼 jj 比 git 更適合代理（以及何時不該使用）：references/why-jj-for-agents.md。