AGENTS.md 稽核
根據專案狀態和既定政策稽核指令。優先處理可能誤導代理器的聲明。文件形狀和編輯頻率本身並不構成缺陷。當檢查結果顯示無缺陷時,請報告無缺陷;簡短的引導文件和未更改的正確指令可能已足夠。
預設情況下,保持稽核為唯讀,包括索引和 Git 歷史記錄。準備更正和檢查點訊息以供審查。當請求授權該動作時,套用修正或建立檢查點;使用現有權限,無需再次請求。執行檢查時不使用自動修正或其他寫入來源的選項,並報告不可用的執行先決條件。
覆蓋範圍
記錄實際檢查的檔案、聲明、歷史記錄和檢查項目。
- 記錄儲存庫修訂版和工作區樹狀結構狀態。盤點儲存庫中的指令檔案、相關的祖先規則、覆寫、匯入、連結和模組對應。包括現有的 CLAUDE.md 系統,而不是假設 AGENTS.md 是它們的活動入口點。
- 確認預期的引導程序會發現哪些檔案,以及哪些檔案需要明確讀取。根據可用的配置或目前的引導程序文件,檢查相關的載入路徑和大小預算。將未知的交付標記為未驗證;僅憑檔案名稱和目錄位置並不能證明載入。
- 說明要驗證的檔案和聲明、任何抽樣、命令先決條件以及可用的歷史記錄。當儲存庫處於髒狀態、歷史記錄淺層或不可用、或檢查無法執行時,限制裁決。分別稽核本地變更與已提交的快照;不要將它們歸因於其 SHA。當檢查在與已提交快照不同的檔案上執行時(例如包含本地變更的工作區),請說明檢查在哪裡執行以及哪些路徑不同。
歷史記錄和先前的發現
對於 Git 儲存庫,在檢查中間變更之前選擇基線。如果沒有 Git 歷史記錄,請檢查目前狀態並報告歷史驗證不可用。
一個完成的稽核已完成其對整個儲存庫的宣告檢查;它可以報告缺陷、抽樣和帶有明確限制的不可用檢查。一個乾淨的結果意味著在完成的檢查中沒有發現缺陷。無法完成的稽核會產生報告,但不會產生檢查點。
一個檢查點是一個空的、單親的 Git 提交,其訊息儲存了已完成稽核的報告以及檢查點訊息模板的尾部。其唯一的父提交是受稽核的修訂版,即該稽核檢查的已提交快照。本地變更與該快照分離。只有當一個提交滿足基線選擇下的所有條件時,它才是檢查點;任何其他提交都是普通提交,無論其訊息內容如何。
一個基線是目標分支第一父代歷史記錄上最近的檢查點。它設定了歷史邊界,即稽核檢查從該修訂版之後到受稽核修訂版之間的變更。其新的和帶入的發現是完整的開放先前發現集合。未產生檢查點的稽核不會更改基線。
引導輸出在被驗證之前仍是候選文件,並且本身不能提供基線。
基線選擇
從 HEAD 開始遍歷目標分支的第一父代歷史記錄。將帶有 Agents-Audit-Version 尾部的提交視為候選提交;透過尾部而不是主旨來識別它們。例如:
git log --first-parent --format='%H' --grep='^Agents-Audit-Version: 1$' HEAD
git show -s --format=%B <candidate> | git interpret-trailers --parse
這些命令會找到候選提交。一個候選提交僅在滿足以下所有條件時才是檢查點:
- 訊息模板中的每個尾部都有一個非衝突的值,版本受支援,並且技能修訂版或內容哈希是可識別的。
- 該提交只有一個父提交。該父提交的完整 SHA 等於
Agents-Audit-Commit,並且父提交和提交的樹狀結構都等於Agents-Audit-Tree。僅樹狀結構相等無法檢測到可能產生相同檔案的不同歷史記錄上的重放。 - 該提交位於目標的第一父代歷史記錄上。
Agents-Audit-Previous指定受稽核修訂版第一父代歷史上最近的較早檢查點,或者對於明確設定的初始歷史邊界指定none。命名的提交本身必須是一個檢查點。- 訊息包含模板的每個報告部分,並附有聲明的覆蓋範圍。除非
Agents-Audit-Previous是none,否則命名檢查點中「新發現」或「帶入發現」下的每個 ID 都出現在「帶入發現」或「已關閉發現」下。
因為每個前身都必須本身是一個檢查點,所以從最舊的開始向前檢查候選提交並重複使用每個結果;這樣每個提交只會被檢查一次。選擇滿足這些條件的最近候選提交作為基線。將任何其他候選提交視為歷史視窗中的普通提交:不要從其訊息中讀取任何發現或關閉,並將其排除在報告和檢查點訊息之外。 當前身不可用或淺層歷史記錄阻止這些檢查時,說明差距。不要用最後幾個提交靜默替換已知的歷史邊界,或將工作聲明為首次稽核。如果無法建立基線,請在明確限制內檢查目前狀態,並將歷史覆蓋範圍保留為未驗證。對於沒有較早檢查點的真實首次稽核,請驗證當前狀態並說明明確的初始歷史邊界。
Rebase、cherry-pick 和 squash 會為提交提供新的父提交,因此在重寫歷史記錄後再次檢查條件。在整合後(當功能歷史記錄被壓縮時)建立持久的檢查點。
檢查
準確性和政策
- 根據專案配置及其先決條件驗證命令。在合適的環境中執行可行的檢查。將失敗歸因於過時的調用、實作缺陷、不可用的先決條件或不完整的檢查;找到回歸的有效測試命令不是過時的。
- 解析命名的引用、路徑、匯入和模組對應條目。在稱指令缺失之前,檢查重新命名、共享所有權和適用的祖先規則。演示缺陷,然後根據代理器遵循指令可能的後果來判斷其嚴重性,而不僅僅是缺失符號。
- 根據實作和測試驗證重要的不變量,將文件和註釋視為聲明而非證據。使用條件兩側的輸入檢查條件性聲明。區分描述與政策:意圖良好的程式碼仍然可能違反既定邊界。使用任務的權威和記錄的決策來解決衝突;不要僅僅為了匹配違反它的程式碼而改寫政策。
- 針對具體的失敗或回歸路徑檢查警告。刪除過時或膚淺的細節,當繞過它仍然是一個現實風險時保留有用的防護欄,並修剪已被測試或強制執行充分承載的解釋。優先考慮當前的指導而不是已修復失敗的歷史記錄。
將已證實的缺陷報告為過時、矛盾、缺失、政策衝突或過時的警告。將不確定的聲明保留在未驗證的檢查下。包括受影響的指令、儲存庫證據、後果和建議的更正。
維護
檢查自歷史邊界以來的程式碼、配置、依賴項和指令變更。將每個相關變更對應到它可能使其無效的聲明,包括未更改的指令檔案。使用提交訊息關鍵字和可選的同時更改程式碼和指令的提交計數來選擇要檢查的變更,而不是判斷文件品質。
僅當變更使記錄的聲明無效或遺漏了必要的指令時,才報告維護缺陷。允許精確的不變量在許多變更中保持不變。將獨立更正、引導提交、稽核修復和檢查點提交視為合法工作。跨模組重構不需要編輯其聲明仍然為真的指令。
決策和警告
獨立於錯誤修復發現來檢查架構決策。尋找其後果應限制未來變更且其原因不能從程式碼中明顯看出的已接受選擇。使用記錄的解釋或決策者的確認;diff 證明變更,而非其意圖。僅當有證據且仍然有用時,才起草規則、理由和重新考慮的條件。將值得提及的被拒絕的替代方案留給它影響的原始碼中的註釋,更改該程式碼的代理器會在那裡找到它。在引導期間,僅繼續使用當前來源;不要挖掘 Git 歷史記錄尋找原因或編造理由。
對於已診斷出的重大錯誤,檢查教訓是否仍然能防止代價高昂或反覆出現的錯誤。僅當它增加了有用的指導時,才提議一個記錄症狀、機制和識別或避免方法的簡潔條目。當繞過抽象可能會重新引入失敗時,將警告重新表述為簡潔的防護欄並解釋原因。當機制已消失、錯誤是膚淺的或強制執行已充分承載教訓時,提議刪除。將不確定的機制保留為提案以待確認。
格式
在準確性之後檢查格式。將儲存庫範圍的規則放置在根檔案中,模組共用的規則放置在原始碼根目錄或套件檔案(中樞)中,不同的模組規則放置在本地檔案(葉子)中。僅使用需要單獨指導的範圍;允許單檔案專案、多個中樞和省略空部分。保留一個規範的解釋,並在能改善發現度時允許一個簡短的範圍提醒和連結。保留適用的版本、驗證日期、平台和測量條件。刪除過時的進度敘述、編造的理由、不必要的重複以及不再有助於變更的指令。根據有用的決策來判斷具體性,而不是根據文字更改的頻率。
報告
說明檢查的指令是否準確,並將該結論限制在檢查的聲明範圍內。記錄修訂版、已檢查的髒內容或忽略的內容、指令清單、已驗證或抽樣的聲明、歷史邊界、命令結果、相關環境和版本以及未解決的檢查。使報告能從儲存庫本身解釋,使用儲存庫相對路徑和 Git 修訂版作為證據。
在最終確定報告之前,重新檢查基線中的每個開放發現,並將其置於「帶入發現」或「已關閉發現」下。
將發現分為以下部分;當一個部分為空時,寫 None:
- 記錄新的發現,附上全新的穩定 ID、受影響的指令、證據、後果和所需的更正。
- 帶入來自基線的每個未解決的發現,包括其列為新的發現,附上其 ID、其來源檢查點(首次記錄它的檢查點)以及其證據、後果和所需更正的完整說明。當其解決方案無法驗證時,保持發現為開放狀態,並揭露無法驗證的證據。
- 關閉具有已驗證解決方案或取代方案的發現,並提供支援證據。記錄每個關閉一次,然後從後續報告中省略它。將其歷史記錄保留在較早的檢查點中,而不是在每個報告中增加存檔。
分配 ID,不要重複使用已退休的 ID;例如,使用稽核特定的 UTC 時間戳加上計數器,並在之後保留該 ID。在報告中說明稽核是否完成;中斷或未完成的稽核以報告結束。僅在證明它的檢查範圍內聲明一個乾淨的結果。
檢查點訊息
準備以下訊息作為已完成稽核交付成果的一部分。包含稽核報告本身,而不是指向外部問題跟蹤器、本地報告或其他外部來源的指針。完全按照所示使用無標題的主題和尾部,報告部分使用 ## 標題和空行。記錄完整的物件 ID 和可識別的技能修訂版或哈希,而不是依賴已安裝的路徑。
chore: 記錄代理文件稽核
## 覆蓋範圍
已檢查 <儲存庫相對路徑的指令檔案或目錄>。
已驗證 <執行的聲明和檢查,包括任何抽樣>。
已檢查從 <歷史邊界> 到受稽核修訂版的歷史記錄。
使用了 <相關環境和工具版本,以及檢查在哪裡執行>。
## 未驗證的檢查
<未完成的檢查及其原因,或 None。>
## 新發現
<每個新發現的穩定 ID、受影響的指令和章節、發現內容、證據、後果和所需的更正;或 None。>
## 帶入發現
<每個未解決發現的穩定 ID、來源檢查點以及自包含的說明,包括證據、後果和所需的更正;或 None。>
## 已關閉發現
<每個本次稽核關閉的發現的穩定 ID、解決方案或取代方案,以及支援證據;或 None。>
Agents-Audit-Version: 1
Agents-Audit-Commit: <完整的受稽核父提交 SHA>
Agents-Audit-Tree: <受稽核的樹狀結構 SHA>
Agents-Audit-Skill-Revision: <技能修訂版或內容哈希>
Agents-Audit-Previous: <基線檢查點 SHA 或 none>
檢查點建立
僅為完成的稽核且僅在獲得該寫入操作的授權時才建立檢查點。要求受稽核的修訂版仍然是 HEAD,並且受稽核的指令和程式碼在其樹狀結構中都有體現。首先提交經授權的更正,然後在記錄其檢查點之前驗證生成的快照。如果更正更改了受稽核的修訂版,請重新整理報告和尾部以描述該已驗證的快照。將未提交或忽略的內容排除在關於已提交快照的聲明之外,並記錄任何由此產生的覆蓋範圍限制。拒絕為觀察到的髒狀態記錄檢查點,如同該快照未經稽核一樣。
[為翻譯而截斷]