Frontier Plan OpenCode Executor
核心原則
前沿計畫是一個強有力的假設,而非絕對真理。
逐步執行計畫的意圖,但在編輯程式碼之前,必須針對實際儲存庫驗證每一項指令。前沿 AI 的計畫經常在以下方面失敗:不存在的檔案名稱、發明的匯入、不可用的函式庫、與儲存庫不符的模式、遺失的測試、理想化的架構以及破壞內部 API。
絕對不要批次處理大型變更。絕對不要跳過驗證。絕對不要隱藏不確定性。未經明確批准,絕對不要執行破壞性操作。
使用時機
- 您收到由前沿 AI 撰寫的詳細、多步驟實作計畫
- 該計畫包含 3 個以上不同的步驟,並帶有特定的檔案路徑和程式碼模式
- 您正在使用一個可從執行紀律中受益的非前沿程式碼模型
- 該計畫存在與實際程式碼庫衝突的風險
請勿用於:
- 單一檔案變更或瑣碎的修復
- 僅包含 1-2 個簡單步驟的計畫
- 您在相同會話中自行撰寫的計畫
- 使用者希望速度優先於安全性的快速迭代
核心工作流程
0. 前置檢查:建立儲存庫基準線
在觸碰任何檔案之前,了解儲存庫狀態並偵測既存失敗。
1. git status --short # 儲存庫是否乾淨?
2. 檢查 package.json # 可用的腳本、依賴項
3. 檢查 AGENTS.md, README.md # 專案慣例、指令
4. 從 package.json 腳本中偵測可用的驗證指令
5. 如果可用,執行成本最低的基準線驗證(lint 或 typecheck)
如果基準線已經失敗:
- 明確記錄失敗:確切指令、退出狀態和簡短的錯誤摘要
- 不要嘗試廣泛清理或修復不相關的問題
- 僅當計畫中的變更可以與既存失敗隔離時才繼續
- 不要將既存失敗歸因於您的實作
危險狀態偵測:
- 如果
git status顯示與計畫無關的未提交變更,請警告使用者 - 如果 lockfiles 被修改,請警告使用者
- 如果儲存庫處於衝突/正在變基的狀態,請停止並詢問
檢查點建議:
- 如果儲存庫在開始前是乾淨的,建議在實作前建立一個檢查點提交
- 除非使用者明確要求,否則不要建立提交
自動提交和自動推送
預設啟用自動提交和自動推送,除非使用者明確停用。
代理程式應提交每個經過驗證的邏輯工作單元,並將其推送到活躍的遠端工作分支,以便使用者稍後可以檢視歷史記錄。
在實作之前:
- 識別當前分支;
- 如果在
main、master、production、release或其他受保護/主線分支上,則根據計畫推斷建立一個新的工作分支; - 如果已經在工作分支上,則繼續使用該分支;
- 絕不直接推送到受保護/主線分支。
如果存在既存的未提交變更:
- 不要自動將它們包含在代理程式的提交中;
- 僅暫存與當前邏輯單元相關的檔案;
- 如果無法安全地分離使用者變更和代理程式變更,請停止並報告衝突。
僅在以下情況全部滿足後才提交:
- 邏輯單元已完成;
- 驗證通過;
- 差異已被檢查;
- 提交具有一個連貫的目的。
使用 Conventional Commits:
type(scope): concise imperative summary
範例:
feat(auth): add session validation helper
fix(api): handle empty webhook payload
refactor(billing): extract invoice mapper
test(auth): cover expired session flow
1. 解析:提取計畫並進行現實檢查
閱讀整個計畫。提取有序的步驟。對於每個步驟,執行現實檢查:
| 檢查項目 | 問題 |
|---|---|
| 檔案 | 引用的檔案是否存在於儲存庫中? |
| 函式庫 | 引用的函式庫是否存在於 package.json 中? |
| 模式 | 儲存庫中是否已經有等效的實用程式/元件? |
| 指令 | 計畫的驗證指令是否可用? |
| 依賴項 | 此步驟是否依賴於前一步驟? |
| 風險 | 低 / 中 / 高 — 打破現有行為的可能性有多大? |
如果某個步驟引用了不存在的檔案、不存在的函式庫、過時的模式或不可用的指令:在實作之前調整該步驟,同時保留計畫的意圖。
2. 追蹤:建立進度追蹤器
如果可用,使用 todowrite(OpenCode 的任務列表工具)。
如果 todowrite 不可用(例如,在預設禁用它的子代理程式中):
- 在您的回應中建立一個可見的 markdown 核取清單
- 在每個步驟後手動更新它
- 將其用作進度的唯一真相來源
- 如果實際上未使用該工具,不要假裝已使用
每個項目必須包含:實作動作、驗證方法以及預期觸及的檔案。
3. 實作:一次一個步驟
將當前步驟標記為 in_progress。僅實作該步驟。
- 在編輯之前讀取目標檔案
- 遵循既有的程式碼庫慣例(導入、命名、模式、架構)
- 使計畫適應現有基礎架構(例如,如果計畫說「建立一個 toast 元件」,但專案使用 Sonner,則包裝 Sonner 而不是從頭開始建置)
- 做出最小的一致變更
- 不要實作未來的步驟,但在做出設計決策時要考慮下游依賴項
- 不要執行不相關的清理、重構或格式化
- 除非獲得明確批准,否則不要安裝依賴項
4. 驗證:分層驗證
在每個步驟之後,執行最狹義、最有意義的驗證。 不要每次都「lint everything」。
| 變更類型 | 最低驗證 | 更強的驗證 |
|---|---|---|
| 新檔案/元件 | lint 或 typecheck | 受影響的 typecheck |
| 型別/介面變更 | typecheck | 受影響的測試 |
| 邏輯/函式變更 | 針對性單元測試 | 完整測試套件 |
| API/伺服器變更 | 針對性整合測試 | 建置 + 端點檢查 |
| UI 變更 | typecheck + build | 視覺/手動冒煙測試 |
| 組態/建置變更 | build | 必要時 clean install/build |
| 資料庫/綱要變更 | dry-run/check 指令 | 需要使用者批准 |
如果某個步驟不存在自動化驗證:執行手動審查並精確說明您檢查了什麼。
如果驗證失敗:
首次失敗 — 修復並重新驗證:
- 僅修復由當前步驟引起的錯誤
- 不要修復既存或不相關的錯誤
- 立即重新驗證
重複失敗 — 不要盲目地繼續修補。 請參閱下方的「重複失敗處理」。
關鍵: 絕不要透過削弱斷言、刪除測試、移除行為、變更公開 API、抑制錯誤或隱藏失敗來使驗證通過 — 除非計畫明確要求且使用者批准。讓警報停止並不等於解決問題。
5. 差異:檢查變更
在驗證通過後,檢查實際變更了什麼:
git diff --stat # 哪些檔案變更了?
git diff # 當差異夠小時進行審查
確認:
- 僅預期的檔案被變更
- 沒有發生不相關的格式化
- 沒有 lockfiles 被變更(除非明確預期)
- 沒有意外編輯到產生的檔案
- 沒有引入機密、本機路徑或除錯日誌
- 沒有意外刪除程式碼
如果差異超出預期範圍,請在繼續之前停止並修正。
6. 確認:標記完成
僅在實作、驗證和差異檢查都乾淨時:
- 將該步驟標記為
completed - 用一句話總結變更內容
- 將下一步驟標記為
in_progress
7. 最終:完整驗證 + 報告
在所有步驟完成後:
- 執行最強的合理檢查:lint + typecheck + build + tests(使用專案指令)
- 報告:完成的步驟、變更的檔案、驗證結果、所做的調整、既存失敗(如果有的話)、任何需要使用者審查的事項
重複失敗處理
如果驗證因相同根本原因而重複失敗,不要繼續應用小的盲目修復。 目標是檢測您是否在每次嘗試中學到了新東西,還是只是在隨機亂試。
當一個步驟多次失敗時:
- 停止修補。 停止進行小的調整並重新執行。
- 仔細重新閱讀錯誤輸出。 完整的堆疊追蹤,而不僅僅是第一行。
- 檢查差異和周遭程式碼。
git diff,閱讀相關的型別、介面、函式。 - 重新評估原始假設。 當前的實作策略是否正確?
- 分類失敗原因:
- 對程式碼庫的假設不正確?
- 儲存庫不匹配(計畫與現實)?
- 選擇了錯誤的抽象?
- 介面或型別不相容?
- 缺少依賴項?
- 過時的產出物?
- 與您的變更無關的既存問題?
- 驗證指令本身配置錯誤?
- 形成一個真正的新假設。 僅在您有了一個新假設後才重試。
- 考慮縮小範圍。 能否將該步驟拆分成更小的部分來隔離失敗?
關鍵規則: 不要重複相同的修復策略,除非從以下方面發現了新資訊:
- 日誌
- 堆疊追蹤
- 差異
- 測試
- 儲存庫檢查
- 文件
如果在多次嘗試後仍未出現新策略,請停止並清楚地報告阻礙:
阻礙:
- 驗證指令:`npm run build`
- 失敗檔案:`src/app/page.tsx`
- 根本問題假設:React Server Component 導入了僅限用戶端的 hook
- 已嘗試的策略:
1. 將導入移至用戶端元件
2. 將 hook 隔離到單獨的檔案中
3. 檢查儲存庫中的現有模式
- 停止原因:
儲存庫中沒有一致的模式可以安全地解決邊界問題
- 可能的下一步行動:
使用者審查或架構釐清
一份清晰的阻礙報告總是比重複「仍然失敗」同時胡亂猜測要好。
使計畫適應現有程式碼
前沿 AI 的計畫經常與實際程式碼庫衝突。當發生這種情況時:
- 識別衝突 — 「計畫說
import { X } from 'uninstalled-lib'但它不在 package.json 中」 - 適應,不要忽略 — 使用現有基礎架構來符合計畫的意圖
- 解釋適應 — 用一句話說明您變更了什麼以及為什麼
- 保留計畫的介面 — 如果計畫導出
useToast(),您的適應仍然應該導出useToast(),即使內部實作不同
關鍵規則:
- 如果儲存庫中已經有等效的原始工具,不要建立新的抽象
- 除非計畫明確要求且使用者批准,否則不要安裝新的依賴項
- 未經正當理由,不要變更架構或模式
未經明確使用者批准禁止進行
這些指令需要使用者說「是」才能執行:
破壞性:
rm -rfgit reset --hardgit clean -fdgit push --force
安裝(變更 lockfiles):
npm installpnpm installyarn installbun installnpm audit fix
資料庫 / 基礎架構:
prisma migrateprisma db pushsupabase db pushdocker compose down -v
組態:
- 變更
.env檔案 - 修改全域工具配置
- 執行部署/取消發布指令
大規模變更:
- 廣泛格式化(對整個儲存庫執行 prettier/eslint --fix)
- 在未經審查的情況下對多個檔案進行尋找和取代
如果不確定某個指令是否安全,請在執行前詢問。
常見錯誤
| 錯誤 | 現實 |
|---|---|
| 「前沿 AI 這麼說,所以它一定是對的」 | 前沿計畫是假設。根據實際儲存庫進行驗證。 |
| 「我會在最後一次驗證所有東西」 | 錯誤會疊加。以適當的粒度驗證每個步驟。 |
| 「我已經讀過計畫了,我可以一次全部實作」 | 批次實作 = 批次錯誤 + 更難除錯。 |
| 「我順便修一下既存的 lint 錯誤」 | 不相關的清理會掩蓋您的變更實際做了什麼。不要這樣做。 |
| 「這個步驟很簡單,我不用檢查 git diff」 | 簡單的編輯也可能意外刪除程式碼或格式化非預期的檔案。 |
| 「我會安裝計畫中提到的缺少的函式庫」 | 先問。該函式庫可能是故意缺席或未經批准的。 |
| 「npm run build 是唯一重要的驗證」 | Build 又慢又廣泛。對中間步驟使用 lint/typecheck。 |
| 「如果失敗了,我就調整一下然後重新執行直到通過」 | 在沒有新資訊的情況下盲目修補就是亂試。重新閱讀錯誤。先形成一個新的假設。 |
| 「又是同一個錯誤,讓我嘗試一個不同的微小變更」 | 相同錯誤 + 相同策略 = 相同結果。改變策略,而不是修補。 |
紅旗 — 停止並重新評估
- 「我之後的下一個步驟也會驗證」 — 現在就驗證。
- 「前沿計畫比儲存庫更懂」 — 儲存庫是唯一真相來源。
- 「這個函式庫沒有安裝但計畫需要它」 — 詢問使用者。不要靜默安裝。
- 「差異比預期大但可能沒問題」 — 在繼續之前檢查並解釋。
- 「我會批次處理步驟 2 和 3,因為它們相關」 — 一個步驟 = 一個驗證 + 差異循環。
- 「有既存的 lint 錯誤,讓我先修復它們」 — 這不是您的工作。記錄它們。保持專注。
- 「讓我在編輯這個檔案時順便格式化它」 — 分開的變更 = 分開的步驟。不要混在一起。
- 「還是失敗,讓我再試一個快速修復」 — 停止修補。重新閱讀錯誤。先形成一個新的假設。
- 「同一個錯誤 3 次了,再做一次微調可能有用」 — 相同錯誤 + 相同策略 = 亂試。改變策略或報告阻礙。
- 「我直接重寫整個東西看看能不能修好」 — 在沒有理解失敗原因的情況下丟掉工作學不到任何東西。先診斷。
- 「使用者很急,我跳過差異檢查」 — 5 秒的
git diff --stat可以防止數小時的除錯。
快速參考
| 階段 | 動作 | 工具 |
|---|---|---|
| 前置檢查 | git status, 偵測指令, 基準線檢查 | Bash |
| 解析 + 現實檢查 | 閱讀計畫, 對照儲存庫驗證每個步驟 | Read + Glob |
| 追蹤 | 建立 todowrite |
…
[為翻譯而截斷]