claude-code/claude-zh/commands/build-fix.md

建置與修復

以最小、安全的修改逐步修復建置和型別錯誤。

步驟 1：偵測建置系統

識別專案的建置工具並執行建置：

指標	建置指令
package.json 含 build 腳本	npm run build 或 pnpm build
tsconfig.json（僅 TypeScript）	npx tsc --noEmit
Cargo.toml	cargo build 2>&1
pom.xml	mvn compile
build.gradle	./gradlew compileJava
go.mod	go build ./...
pyproject.toml	python -m py_compile 或 mypy .

步驟 2：解析並分組錯誤

1. 執行建置指令並擷取 stderr
2. 依檔案路徑分組錯誤
3. 依依賴順序排序（先修 import/型別，再修邏輯錯誤）
4. 計算總錯誤數以追蹤進度

步驟 3：修復迴圈（一次一個錯誤）

對每個錯誤：

1. 讀取檔案 — 使用 Read 工具查看錯誤前後 10 行的情境
2. 診斷 — 識別根本原因（缺少 import、型別錯誤、語法錯誤）
3. 最小修復 — 使用 Edit 工具做最小幅度的修改來解決錯誤
4. 重新建置 — 確認錯誤已消失且未引入新錯誤
5. 繼續下一個 — 處理剩餘錯誤

步驟 4：防護機制

遇到以下情況時停止並詢問使用者：

• 修復引入的錯誤比解決的更多
• 同一錯誤在 3 次嘗試後仍然存在（可能是更深層的問題）
• 修復需要架構變更（不只是建置修復）
• 建置錯誤源自缺少依賴（需要 npm install、cargo add 等）

步驟 5：摘要

顯示結果：

• 已修復的錯誤（含檔案路徑）
• 剩餘的錯誤（若有）
• 引入的新錯誤（應為零）
• 未解決問題的建議後續步驟

恢復策略

情況	行動
缺少模組/import	檢查套件是否已安裝；建議安裝指令
型別不匹配	讀取兩個型別定義；修正較窄的型別
循環依賴	用 import 圖識別循環；建議提取
版本衝突	檢查 package.json / Cargo.toml 的版本約束
建置工具設定錯誤	讀取設定檔；與正常預設值比較

為安全起見，一次修復一個錯誤。優先最小差異而非重構。