系統化代理 (Systematic Agent) — 紀律編碼實務
使用時機
每個編碼任務、修改、除錯工作或實作工作。這項技能是處理任何程式碼變更的基礎作業系統,而非可選的附加功能。
針對所有與程式碼相關的任務自動調用。如果使用者要求你變更、新增、修復或建置程式碼,請遵循此技能。
核心規則
1. 絕不假設專案的事實
在觸碰任何檔案之前,你必須知道實際的內容。讀取檔案。檢查其當前狀態。不要依賴對「應該」存在內容的記憶——請讀取它。
具體行動:
- 對你即將變更的檔案執行
read_file,包括周圍的上下文 - 使用
search_files搜尋相關程式碼、匯入、函式呼叫者和參考 - 在測試變更之前,確認伺服器正在執行且端點有回應
- 驗證設定檔實際上包含你認為它們該有的內容
2. 在變更任何內容之前,檢查相關檔案
不要盲目修補。對於你計畫編輯的每個檔案:
- 讀取完整檔案(或具有足夠上下文的相關章節)
- 了解目前的結構、匯入、依賴關係和模式
- 確定需要變更的內容及其原因
- 然後才編寫修補或編輯
修補時: 在 old_string 中包含足夠的周圍上下文,以使比對唯一。比對到多個位置的修補將會套用至錯誤的位置。
讀取大型檔案時: 使用 offset/limit 增量讀取。如果你只需要一個函式,不要嘗試一次載入一個 1600 行的檔案——但請務必完整讀取你正在變更的函式,包括其簽章和所有呼叫點。
3. 在執行之前制定簡潔的計畫
在進行任何非瑣碎的編碼任務之前,撰寫一個簡短的計畫(3-7 個要點),回答以下問題:
- 哪些檔案需要變更
- 每個變更的作用(每個變更一行說明)
- 變更應以何種順序進行
- 哪些驗證步驟將確認成功
範例:
計畫:
1. 讀取 app.py 第 762-770 行 — 檢查 _get_hermes_response 簽章
2. 在簽章中新增 image_url: str = None 參數
3. 將 image_url=image_url 新增至函式內的所有 5 個 _call_api 呼叫
4. 將 image_url 從 chat() 傳遞給 _get_hermes_response
5. 重新啟動伺服器,使用 curl 影像負載進行測試
在陳述計畫之前,不要開始編碼。 如果計畫錯了,程式碼也會錯。
4. 使用工具驗證聲明,而不是猜測
關於程式碼庫的每項聲明都應有工具輸出作為依據,而非回憶。
| 聲明 | 如何驗證 |
|---|---|
| "檔案 X 有函式 Y" | 對檔案執行 grep -n 或 read_file |
| "伺服器正在執行" | 對健康檢查端點執行 curl |
| "變更有效" | 執行實際測試,不要假設 |
| "API 金鑰已設定" | 讀取 storage/apis.json |
| "CSS 已載入" | 對靜態檔案執行 curl,檢查 HTTP 狀態 |
| "修補已正確套用" | 使用 grep 搜尋新文字,或對該區域執行 read_file |
永遠不要寫出「它應該能運作」的回應,而沒有實際驗證它確實能運作。
5. 在每次重大修改之後,測試或檢查結果
在任何程式碼變更之後:
- 語法檢查:
python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)"— 必須通過才能重新啟動 - 重新啟動伺服器(如果變更在 app.py 中)
- 測試變更後的行為:
- 對於 API 變更:使用代表性的負載對端點執行
curl - 對於前端變更:確認靜態檔案有被提供服務(HTTP 200)
- 對於設定變更:讀取設定檔以確認
- 對於 API 變更:使用代表性的負載對端點執行
- 檢查實際輸出 — 不是你所預期的,而是工具所回傳的
在你看過測試結果之前,變更不算完成。 「我認為它能運作」不是驗證。
6. 如果發生故障,在嘗試另一種方法之前,診斷實際的錯誤
當測試失敗或修補無法套用時:
- 讀取實際的錯誤訊息 — 逐字複製。不要摘要它。
- 找出根本原因 — 具體是什麼失敗了以及為什麼
- 提出關於修正的假設
- 使用工具測試假設 — 不要只是嘗試另一個修補
- 如果修正無效,重新讀取錯誤 — 它可能已變更,或者你可能誤讀了它
要避免的反模式:
- 連續套用三個不同的修補,卻沒有檢查任何一個是否有效
- 根據錯誤類型猜測修正方法,而非閱讀錯誤文字
- 當錯誤只在一個特定位置時,變更不相關的程式碼
- 在未修正阻止啟動的語法錯誤的情況下重新啟動伺服器
7. 在結果被驗證之前,不要說任務已完成
任務只有在以下情況才算完成:
- 程式碼變更已撰寫並通過語法檢查 ✓
- 伺服器正在執行新的程式碼 ✓
- 變更後的行為產生了預期的結果(經由工具輸出驗證) ✓
- 你可以指出證明該結果的具體測試/命令/輸出 ✓
永遠不要因為修補成功套用就宣告「完成」。 修補可能會套用到錯誤的位置、引入語法錯誤,或者實際上並未修復問題。修補套用只是驗證的第一步,而不是結束。
程序
對於任何程式碼變更:
- 讀取 — 檢查你將變更的檔案。了解當前狀態。
- 計畫 — 撰寫 3-7 個要點:變更什麼、順序為何、如何驗證。
- 變更 — 進行編輯。對於多檔案工作,一次進行一個原子變更。
- 語法檢查 — 使用
py_compile或等效工具。在繼續之前修正錯誤。 - 重新啟動 — 如果執行中的伺服器需要新程式碼。
- 測試 — 使用 curl、執行或檢查。驗證實際行為是否符合意圖。
- 報告 — 說明變更了什麼、測試結果為何,以及是否已驗證。
對於除錯:
- 重現 — 取得實際的錯誤輸出。逐字複製。
- 定位 — 找出錯誤在程式碼中的來源。使用
grep、read_file、堆疊追蹤。 - 理解 — 完整讀取失敗的程式碼。不要猜測它做什麼——讀取它。
- 假設 — 什麼具體的變更可以修復這個特定的錯誤?
- 修正 — 進行能解決根本原因的最小變更。
- 驗證 — 重新執行失敗的測試。確認錯誤已消失且沒有破壞其他東西。
- 如果仍然失敗 — 返回步驟 1。錯誤可能已變更。重新讀取它。
對於多步驟任務:
- 一次執行一個步驟。在進行下一個步驟之前驗證每個步驟。
- 如果步驟 3 依賴於步驟 2 的正確性,請先驗證步驟 2。
- 不要批次處理未經驗證的變更——如果步驟 2 錯了,步驟 3 的「修正」也會錯。
陷阱
- 重複讀取相同的行數卻不行動。 如果你已經讀取一個函式三次卻還沒有編輯它,那就是卡住了。要嘛進行變更,要嘛說明什麼阻礙了你。
- 猜測檔案內容。 總是讀取檔案。對於多個修補後「原本存在」的記憶是不可靠的。
- 跳過語法檢查。 修補可以順利套用但仍然破壞語法。務必驗證。
- 沒有重新啟動就進行測試。 如果 app.py 變更了,執行中的伺服器擁有的是舊程式碼。在測試之前重新啟動。
- 在修補成功時宣告完成。 「修補已套用」≠「任務完成」。驗證行為。
- 不讀取錯誤訊息。 錯誤文字告訴你什麼失敗了。讀取它。不要僅從錯誤類型推斷。
- 過度修補。 套用能修復特定問題的最小變更。當只有一行錯誤時,不要重寫整個函式。
驗證清單
在報告編碼任務完成之前,確認每個項目:
- 在變更前已讀取檔案(了解當前狀態)
- 已撰寫計畫(變更什麼、順序為何)
- 語法檢查通過(使用
py_compile或等效工具) - 如果 app.py 變更,伺服器已重新啟動
- 已執行測試(curl、執行或檢查)——已看到實際輸出
- 輸出符合預期行為
- 未引入新的錯誤
此技能如何與其他技能互動
- 這是一項基礎技能——無論哪個其他技能處於活躍狀態,它都適用於所有編碼工作
- 當
test-driven-development處於活躍狀態時,TDD 是測試方法;此技能則管理整體紀律 - 當
systematic-debugging處於活躍狀態時,除錯有其自己的詳細程序;此技能的規則 6 仍然適用 - 當
spike處於活躍狀態時(一次性實驗),「先檢查再變更」和「變更後驗證」的規則仍然適用——實驗可能混亂,但不能粗心 - 當
human-first-ui或webmxerz用於設計工作時,此技能管理實作設計的程式碼變更——設計技能告知「建置什麼」,此技能管理「如何安全地建置」 - 技能透過
skill_view(name)按需載入——它們不是持續活躍的背景程序。一項技能僅在其被載入的工作階段回合中才生效。設計輔助技能(webmxerz、human-first-ui)針對特定的 UI 任務被諮詢;此技能仍作為實作設計的程式碼工作的基礎規範。