aryashreep/ctx-audit

上下文稽核

採用此慣例的儲存庫會維護一組小型持久檔案，讓代理無需在每次工作階段中重新推導相同的內容：專案的慣例（AGENTS.md）、已決定的事項及其原因（memory.md），以及程式碼庫的大致組織方式（.agent/graph.md）。此技能會在你依賴這些檔案之前，或在你退而手動掃描儲存庫之前，檢查這些檔案是否存在且為最新狀態。

觸發片語

工作階段開始 / 信任檢查

• "讓我快速了解此儲存庫"
• "你對這個專案了解多少"
• "我應該信任 AGENTS.md / memory.md 嗎"
• "上下文檔案是否為最新"
• "檢查上下文" / "上下文稽核"

過時

• "AGENTS.md 過時了嗎" / "memory.md 過時了嗎"
• "自上次同步以來有多少提交"
• "我的代理檔案是否為最新"
• "檢查上下文是否過時"

Token 成本

• "上下文檔案節省了多少"
• "Token 節省" / "上下文成本"
• "基準測試 Token 節省"
• "基準 vs 策劃 Token"

設定 / 入門

• "搭建 AGENTS.md" / "初始化上下文"
• "安裝 ctx-audit" / "連接上下文鉤子"
• "設定 AI 上下文" / "此專案是否已準備好 AI"

CI / 自動化

• "將 ctx-audit 加入 CI"
• "加入預先推送鉤子"
• "在 CI 中強制執行上下文新鮮度"

架構

• "我有架構圖嗎"
• "產生 graph.md" / "執行 graphify"

如何執行

執行 ctx-audit 的建議方式：

npx ctx-audit

或者，如果作為技能安裝：

node <此技能資料夾路徑>/../scripts/audit.mjs

旗標：

• --json — 機器可讀的輸出（如果你要程式化地根據結果採取行動，請使用此項）。
• --strict — 如果任何項目缺失或過時，則退出碼為 1。
• --ci — --strict --json 的別名。
• --help — 顯示用法並退出。

子命令

# 搭建 AGENTS.md + memory.md（互動式 — 直接將檔案寫入儲存庫根目錄）
npx ctx-audit init

# 一鍵安裝：將技能複製到 ~/.claude/skills/，在 CLAUDE.md 中註冊
npx ctx-audit install

# Git 鉤子：在每次推送時執行 --strict 稽核
npx ctx-audit hook install
npx ctx-audit hook status
npx ctx-audit hook uninstall

# 專案 CLAUDE.md：為代理加入指令區塊
npx ctx-audit claude install
npx ctx-audit claude uninstall

# Token 節省報告（聚焦、可分享的格式）
npx ctx-audit benchmark

代理決策表

狀態	含義	行動
FRESH	自上次同步以來的提交數量少於過時閾值的一半	信任該檔案 — 讀取它，而不是掃描原始原始碼
STALE?	接近閾值（可能過時）	輕微警告 — 在依賴關鍵斷言之前進行抽查
STALE!	超過閾值，視為失敗	將斷言視為未經驗證；對照實際程式碼進行抽查；並在工作階段後更新
STALE	嚴重落後，視為失敗	與 STALE! 相同，但更緊急；在工作階段後立即更新
MISSING（必要）	檔案不存在	執行 npx ctx-audit init；不要假設慣例已就位而繼續
absent（可選）	可選檔案不存在	可以接受；考慮執行 /graphify 來產生 graph.md
over budget	Token 數量超過 maxTokens	檔案過於臃腫 — 請精簡；讀取它可能比它節省的成本更高
dead reference	反引號路徑或 dir/file.ext 在檔案中提及但磁碟上不存在	更新該引用；檔案記錄了過時的結構
SHA bumped	last_synced_commit 已更新但主體未變	驗證檔案是否確實反映了最近的變更；可能只是機械式更新

解讀結果

• MISSING（必要檔案）：不要假設慣例已就位而繼續。 提議搭建一個起始檔案（執行 npx ctx-audit init），而不是在沒有檔案的情況下進行，或默默採用舊的「手動探索一切」的方法。
• FRESH：檔案是最新的。讀取它，而不是掃描原始原始碼。
• STALE?（可能過時）：接近閾值。抽查關鍵斷言。
• STALE!（可能過時）：將其斷言視為未經驗證。對照實際程式碼抽查任何重要事項，並在工作階段後，更新該檔案及其 last_synced_commit。
• STALE：嚴重落後。處理方式與 STALE! 相同，但更緊急。
• Token 計數是基於 ~3.5 字元/Token 的啟發式方法 — 在方向上是有用的，但不精確。如果某個檔案被標記為「over budget」，表示它已經變得過於臃腫，讀取它的成本開始超過它原本節省的成本；建議進行精簡。
• Dead reference 警告：上下文檔案中提及的路徑在磁碟上已不存在。表示該檔案引用了過時的結構。

實際範例

工作階段開始時的基本稽核：

npx ctx-audit

CI 閘門（如果上下文過時則使建置失敗）：

# .github/workflows/ctx-audit.yml
- name: 稽核上下文新鮮度
  run: npx ctx-audit --strict

用於程式化使用的 JSON 輸出：

npx ctx-audit --json | jq '.checks[] | {file, stalenessLevel, stale}'

一鍵入門：

npx ctx-audit install        # 複製技能，在 CLAUDE.md 中註冊
npx ctx-audit hook install   # 加入預先推送防護
npx ctx-audit claude install # 將註解加入專案 CLAUDE.md
npx ctx-audit init           # 搭建 AGENTS.md + memory.md

僅檢查特定子系統的過時情況（透過 frontmatter）：

---
last_synced_commit: abc1234
watches: src/auth/**, src/api/**
---

只有影響 src/auth/ 或 src/api/ 的提交才會計入此檔案的過時程度。

基準測試 Token 節省：

npx ctx-audit benchmark

設定

在儲存庫根目錄中放置 .ctx-audit.json 以自訂行為：

{
  "files": [{ "id": "...", "file": "...", "label": "...", "maxTokens": N, "required": true }],
  "sourceDirs": ["src", "packages/core"],
  "staleThreshold": 10,
  "baselineFileCap": 300
}

Frontmatter

每個上下文檔案應以 frontmatter 開頭：

---
last_synced_commit: <git sha>
watches: src/auth/**, src/api/**
---

watches 欄位（可選）將過時檢查的範圍限制為僅影響那些路徑的提交，而不是所有原始目錄。

如果必要檔案缺失 — 搭建它們

執行 npx ctx-audit init 以產生範本。在 TTY 中，它會直接將檔案寫入儲存庫根目錄；當透過管道傳輸時，它會輸出到 stdout 以供重新導向。傳統的 --init 旗標仍作為向後相容的別名受支援。

AGENTS.md — 穩定的專案慣例：建置/測試/lint 命令、檔案佈局規則、代理絕對不能做的事。應很少變更。

memory.md — 一個持續進行的決策日誌，不是當前程式碼的重述。 每個條目：嘗試了什麼、決定了什麼、為什麼，以及在情況改變時應重新考慮什麼。附加內容，不要改寫歷史。

.agent/graph.md（可選，但建議在儲存庫成長後使用）— 每個主要模組用一段文字描述其職責以及與誰通訊。不是檔案內容，不是詳盡的樹狀結構 — 只要足夠讓代理無需重新閱讀所有內容即可導覽。 提示：執行 /graphify 以從程式碼庫自動產生此檔案，而不是手動編寫。

在搭建或更新這些檔案中的任何一個後，將其 last_synced_commit 更新為當前的 HEAD，這樣下一次稽核就不會立即將其標記為過時。