Communitygithub.com

V4TIME/V4SKILL

強制執行紀律編碼實務——在修改前檢查、在執行前規劃、在修改後驗證、在重試前診斷。適用於每個編碼任務。

V4SKILL 是什麼?

V4TIME/V4SKILL 是一個 AI Agent 的基礎技能,旨在為所有程式碼修改工作強制執行嚴謹的紀律。它並非可選的附加功能,而是作為處理任何程式碼變更的底層作業系統,不論是修改、除錯還是實作新功能。該技能的核心規則包括:絕不假設專案狀態(必須讀取檔案)、修改前徹底檢查相關檔案、在執行前制定簡潔計畫、使用工具驗證聲明而非猜測、每次重大修改後進行測試與檢查、發生錯誤時診斷實際原因而非盲目嘗試,以及確認結果已驗證後才能宣告任務完成。此技能支援所有程式碼相關任務,並會自動觸發。它與其他技能(如測試驅動開發、系統性除錯)協同運作,作為共同規範,確保所有程式碼變更都以審慎、可驗證且可靠的方式進行,最終減少錯誤、提升程式碼品質與開發效率。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/V4TIME/V4SKILL/tree/HEAD/systematic-agent

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

系統化代理 (Systematic Agent) — 紀律編碼實務

使用時機

每個編碼任務、修改、除錯工作或實作工作。這項技能是處理任何程式碼變更的基礎作業系統,而非可選的附加功能。

針對所有與程式碼相關的任務自動調用。如果使用者要求你變更、新增、修復或建置程式碼,請遵循此技能。

核心規則

1. 絕不假設專案的事實

在觸碰任何檔案之前,你必須知道實際的內容。讀取檔案。檢查其當前狀態。不要依賴對「應該」存在內容的記憶——請讀取它。

具體行動:

  • 對你即將變更的檔案執行 read_file,包括周圍的上下文
  • 使用 search_files 搜尋相關程式碼、匯入、函式呼叫者和參考
  • 在測試變更之前,確認伺服器正在執行且端點有回應
  • 驗證設定檔實際上包含你認為它們該有的內容

2. 在變更任何內容之前,檢查相關檔案

不要盲目修補。對於你計畫編輯的每個檔案:

  1. 讀取完整檔案(或具有足夠上下文的相關章節)
  2. 了解目前的結構、匯入、依賴關係和模式
  3. 確定需要變更的內容及其原因
  4. 然後才編寫修補或編輯

修補時: 在 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. 在每次重大修改之後,測試或檢查結果

在任何程式碼變更之後:

  1. 語法檢查: python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)" — 必須通過才能重新啟動
  2. 重新啟動伺服器(如果變更在 app.py 中)
  3. 測試變更後的行為:
    • 對於 API 變更:使用代表性的負載對端點執行 curl
    • 對於前端變更:確認靜態檔案有被提供服務(HTTP 200)
    • 對於設定變更:讀取設定檔以確認
  4. 檢查實際輸出 — 不是你所預期的,而是工具所回傳的

在你看過測試結果之前,變更不算完成。 「我認為它能運作」不是驗證。

6. 如果發生故障,在嘗試另一種方法之前,診斷實際的錯誤

當測試失敗或修補無法套用時:

  1. 讀取實際的錯誤訊息 — 逐字複製。不要摘要它。
  2. 找出根本原因 — 具體是什麼失敗了以及為什麼
  3. 提出關於修正的假設
  4. 使用工具測試假設 — 不要只是嘗試另一個修補
  5. 如果修正無效,重新讀取錯誤 — 它可能已變更,或者你可能誤讀了它

要避免的反模式:

  • 連續套用三個不同的修補,卻沒有檢查任何一個是否有效
  • 根據錯誤類型猜測修正方法,而非閱讀錯誤文字
  • 當錯誤只在一個特定位置時,變更不相關的程式碼
  • 在未修正阻止啟動的語法錯誤的情況下重新啟動伺服器

7. 在結果被驗證之前,不要說任務已完成

任務只有在以下情況才算完成:

  • 程式碼變更已撰寫並通過語法檢查 ✓
  • 伺服器正在執行新的程式碼 ✓
  • 變更後的行為產生了預期的結果(經由工具輸出驗證) ✓
  • 你可以指出證明該結果的具體測試/命令/輸出 ✓

永遠不要因為修補成功套用就宣告「完成」。 修補可能會套用到錯誤的位置、引入語法錯誤,或者實際上並未修復問題。修補套用只是驗證的第一步,而不是結束。

程序

對於任何程式碼變更:

  1. 讀取 — 檢查你將變更的檔案。了解當前狀態。
  2. 計畫 — 撰寫 3-7 個要點:變更什麼、順序為何、如何驗證。
  3. 變更 — 進行編輯。對於多檔案工作,一次進行一個原子變更。
  4. 語法檢查 — 使用 py_compile 或等效工具。在繼續之前修正錯誤。
  5. 重新啟動 — 如果執行中的伺服器需要新程式碼。
  6. 測試 — 使用 curl、執行或檢查。驗證實際行為是否符合意圖。
  7. 報告 — 說明變更了什麼、測試結果為何,以及是否已驗證。

對於除錯:

  1. 重現 — 取得實際的錯誤輸出。逐字複製。
  2. 定位 — 找出錯誤在程式碼中的來源。使用 grep、read_file、堆疊追蹤。
  3. 理解 — 完整讀取失敗的程式碼。不要猜測它做什麼——讀取它。
  4. 假設 — 什麼具體的變更可以修復這個特定的錯誤?
  5. 修正 — 進行能解決根本原因的最小變更。
  6. 驗證 — 重新執行失敗的測試。確認錯誤已消失且沒有破壞其他東西。
  7. 如果仍然失敗 — 返回步驟 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 任務被諮詢;此技能仍作為實作設計的程式碼工作的基礎規範。

Individual skills in this repo

This repo contains 12 individual skills — each has its own dedicated page.

相關技能