weekly-audit
Skill547 starsChanged 9 days agoMITView on GitHub
每週一次的專案健康度巡檢,產出 docs/audit/weekly/YYYY-Www.md 報告。當用戶說「週巡檢」「每週檢查」「weekly audit」「幫專案做大整理」「這週新增的圖層有沒有資料」「Supabase 長多大了」「S3/R2 花多少錢」「有沒有圖層掛掉」「文件是不是過時了」「README 數字對不對」「專案結構有沒有跑掉」時觸發。查的是「上線之後過了一段時間,東西還健康嗎」——資料活性、儲存成本、效能退化、文件時效、repo hygiene、跨 repo 契約六組。**唯讀巡檢 + 產報告;只有白名單四類整潔問題會自動修**(各自獨立 commit,可單獨 revert)。不做單一 layer 的上線驗收(→ layer-onboarding)、不做 session 收尾(→ wrap-up)、不 deploy、不 push、不寫 DB。主動更新時機:新增檢查項、收集器誤報漏報、某項連續 3 週無變化該降頻、白名單自動修出過事時。
- Reads credentials
6 other projects use a version of this.
Adopted by
Most recently taken up by
- HurricaHjz/SecondSelftheir own version, first seen Nov 15, 2026
- HurricaHjz/second-yourselftheir own version, first seen Nov 15, 2026
- tw93/MiaoYantheir own version, first seen Nov 8, 2026
- matthewzammit/skillstheir own version, first seen Nov 8, 2026
- xpoes123/claude-skillstheir own version, first seen Oct 20, 2026
- tw93/Moletheir own version, first seen Oct 17, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- tw93/Mole★ 75ksame name
- tw93/MiaoYan★ 8.8ksame name
- HurricaHjz/second-yourself★ 150same name
- HurricaHjz/SecondSelf★ 150same name
- matthewzammit/skills★ 4same name
- xpoes123/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- public/llms.txtllms.txt
- supabase-optimizeSkill
- wrap-upSkill
- accessibility-analysisSkill
- blog-writingSkill
- layer-onboardingSkill
- service-coverageSkill
- supabase-optimizeSkill
- three-3d-componentSkill
- wrap-upSkill
The file
Files
Weekly Audit — 每週巡檢
目的:專案每週都在長(新圖層、新資料源、新疊圖),但所有守門機制都是事件觸發的——
CI 在 PR 時跑、layer-onboarding 在接線時跑、wrap-up 在 session 結束時跑。
沒有人回答「上線三週後這東西還健康嗎」。這個 skill 就是回答這句話的。
設計依據與完整檢查項清單:docs/proposal/weekly-audit-2026-08-21/README.md
何時觸發 / 何時不要
| 觸發 | 不要觸發(該用別的) |
| 「跑一下週巡檢」「這週的檢查」 | 新 layer 剛接好要驗收 → layer-onboarding |
| 「幫專案做大整理」 | session 要收尾、整理記憶 → wrap-up |
| 「Supabase/S3 現在多大」「花多少錢」 | 某個 RPC 慢要優化 → /check-rpc + supabase-optimize |
| 「有沒有圖層掛掉/沒資料」 | 某個 feature 的跨 repo commit 對照 → /handoff |
| 「README/文件過時了嗎」 | 一次性的專題稽核 → 直接做,別套週巡檢格式 |
硬約束(違反即中止)
- 正式 DB 唯讀:只能 SELECT/describe,查詢帶 LIMIT。
每個 session 開頭下
SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;(⚠️ 連線字串的default_transaction_read_only對 Supabase pooler 無效,實測過)。 禁止任何寫入——包含為了「測試唯讀鎖有沒有效」而試寫。 特別是pg_stat_statements_reset():它會清空 C1 的差分基準且不可逆 (2026-08-21 真的被誤觸過一次,8/11~8/21 的統計因此永久遺失)。 要驗證唯讀鎖,用SHOW transaction_read_only;讀狀態,不要真的送 DML。 - 執行時段無限制:這是個人 GIS 專案的 DB。最重的兩支是
probe_upstream(~70s) 與collect_supabase(~64s,A7 亂碼掃描佔其中約 60s;不含 A7 只要 3.8s)。 想什麼時候跑就什麼時候跑。 ⚠️ A7 預設是抽樣(小表全掃、大表抽樣),能可靠抓到「系統性解碼壞掉」, 但抓不到「大表裡孤零零幾筆壞」。要窮盡檢查跑AUDIT_MOJIBAKE_DEEP=1(實測 5 分鐘以上)。 - 報告不得含密鑰:收集器讀 env 但永不 echo 值。產報告前掃一次,
出現疑似 secret 一律
<REDACTED>。 - 大檔一律 HEAD 不 GET:站上有 46MB 級的 geojson。
- 不碰平行 session 的髒檔:本 repo 長期有平行 session。dirty 檔只列不動、 不代為 commit、不 revert。
- 收集器失敗就標 blocked,不因為沒收到資料就寫「無異常」。
_all.json的failed[]必須反映到報告裡。 - 必須在主工作樹跑,不要在
git worktree裡跑(2026-08-21 實測)。 worktree 只有 git 追蹤的檔案——public/的 1125 個檔在 worktree 裡只剩 156 個 (PMTiles/大 GeoJSON 全被 gitignore 走 S3),且../data-collectors等 sibling repo 的相對路徑會失效。結果是 A3/A5 給出嚴重偏低的假數字、上游探測整組失效, 而且不會報錯——它會安靜地告訴你「只有 18 個 PMTiles」。 主樹被平行 session 佔用時,寧可等,不要改在 worktree 跑。
流程
Step 0 — 前置
- 確認在 repo root、
.env可讀(不讀內容,只確認存在)。 - 看一眼現在幾點:落在 10:00–20:00 就提醒用戶這會打到正式 DB。
- 讀上一份報告
docs/audit/weekly/(最新的那份)——趨勢比較的基準來自報告本身, 不是.claude/.cache/(cache 不進版控,換機器就沒了)。
Step 1 — 收集(確定性,不動腦)
bash scripts/audit/weekly/run_all.sh六支收集器依序跑,任一支失敗不中斷其他支,結果彙整到 .claude/.cache/weekly-audit/_all.json。
| 收集器 | 蓋到的檢查項 |
collect_supabase.sh | B1 儲存量/B2 retention 缺口/B3 pg_cron 健康/C1 慢查詢 snapshot/C3 孤兒 RPC/A7 文字欄位亂碼掃描 |
probe_upstream.sh | A1 動態表斷更/F2 next_refresh 到期/上游 repo 狀態 |
probe_layers.ts | A2 RPC 死鏈/A3 A4 線上資產活性/A5 孤兒資產 |
probe_runtime.ts | A6 圖層執行期建置(真的開瀏覽器跑正式站,比對 registry 期望的 sourceId 與實際建起來的) |
probe_production.sh | C4 正式站回應/B6 CDN 快取有效性 |
check_docs.ts | D1 README 數字對帳(14 項:layer 數/dataClass/features 夾/主題數/主題表逐列/上游 dataset/Loader 數/collector 數/nginx location/Three.js Scene)/D2 README 齊全(handoff/backlog/changelog 依契約視需要,只記 metrics)/D3 落後/D4 散檔/D7 params 漂移/D8 頻率覆蓋 |
check_hygiene.sh | E1 未 push/E2 dirty/E3 大檔誤入 git/E4 public 用量 |
參數:--skip-network(離線只跑 docs/hygiene)、--only <name>(只跑一支)。
Step 2 — 對帳與趨勢
拿本週 metrics 對上週報告的趨勢表做差分。要自己算變化量,不要只報當下值。
首跑無基準時:
docs/audit/weekly/找不到上一份報告 → 趨勢表所有「上週」欄一律標—(無基準,本份即基準)。不得推測、不得回填、不得拿 proposal §3 的實測數字冒充上週值。
- Supabase 週增量(>3GB/週 → 🟡,異常跳升 → 🔴)
- 慢 RPC 數量變化。⚠️
pg_stat_statements是自上次 reset 起的累計視圖, 當下均值會混入舊時代 → 用本週 snapshot 減上週 snapshot 的calls/total_exec_time求本週真實均值。 - 斷更表數、線上 404 數、孤兒資產總量的增減。
Step 3 — 判讀(LLM 的活)
收集器只給初判,這步要覆寫成有根據的判斷:
- 慢查詢必附「誰在打」——
pg_stat_statements只給數字不給呼叫者。 逐一grep -r "<rpc_name>" src/、查cron.job.command、必要時查上游 repo。 前端在打 vs 背景 job 在打,嚴重度完全不同。 (實例:health_snapshot均值 23 秒看似重大效能債,查完發現前端根本沒呼叫, 是data-collectors/tasks/monitoring.py的背景監控——從 🔴 降為 🟡。) - 孤兒判定要收斂口徑——「DB 有 1023 個 function」是含 extension 的毛數, 排除 extension-owned、pg_cron 呼叫的、前端用到的之後才是候選(實際約 86 個,不是 800 多)。
- 散檔歸檔看連結不看檔名——
docs/features/water-resources/water-resources-status.md看起來像一次性 status, 實際是全域 MEMORY.md 指定的現行狀態檔。 - 本週新增圖層專章:先
git log --since="7 days ago" --stat src/data/layerManifest.ts看範圍, 要看內容用-U0(不要用-p,這是萬行登記簿,完整 diff 會灌爆 context)抓新 entry, 逐一過 A1~A4(有沒有資料、線上檔在不在、UX 四鐵則有沒有漏)。
Step 4 — 產報告
寫 docs/audit/weekly/YYYY-Www.md(ISO 週編號,date +%G-W%V)。結構:
# Weekly Audit YYYY-Www (YYYY-MM-DD ~ MM-DD)
## 摘要
🔴 N · 🟡 N · 🟢 N | 上週:🔴 N · 🟡 N
(收集器失敗時在這裡標明哪幾項是 blocked)
## 趨勢
| 指標 | 本週 | 上週 | 變化 |
## 🔴 需拍板
- [代號] 標題 → 證據 → 建議動作
## 🟡 已列入 backlog
## 🟢 已自動處理
## 本週新增圖層驗收
## 本次巡檢的盲區
(沒跑到的、被 timeout 的、上游 repo 不在的,據實列出)Step 5 — 自動修(白名單,逐類分開 commit)
先開分支 chore/weekly-audit-YYYY-Www(不要直接 commit 到當前分支——這個 repo 有 39 個
branch、15 個無 upstream、長期有平行 session,整潔 commit 混進別人的 feature 分支會很難拆)。
只有這四類能自動動手,每類一個 commit,方便單獨 revert:
| 動作 | commit 前綴 |
補 .gitignore(大檔誤入版控) | chore(audit): |
| 更新 README 中與 manifest 對不上的數字 | docs(audit): |
補 docs/features/*/ 缺的檔案骨架(照 _TEMPLATE) | docs(audit): |
更新過期的狀態檔數字(如 PMTILES_STATUS.md) | memory: |
不在白名單 = 列進報告等拍板:搬移/刪除文件、改程式碼、改 migration、
動 pg_cron、動 S3/R2 物件、push、deploy、git add -A。
Step 6 — 收尾
- 更新
docs/audit/weekly/README.md的趨勢表(追加一列)。 - 🔴🟡 條目 append 到
.claude/memory/BACKLOG.md,避免報告寫完就沉底。 - 回報用戶:先講 🔴,再講變化最大的趨勢,最後才是清單。
本 skill 不做
- 不做真 render 驗收(圖層畫面是不是空白)——需要 agent-browser,v2 再加。 v1 只驗「資料源活著」,這個界線要在報告裡講清楚。
- 不做單層上線驗收、不做 session 收尾、不做 feature 開發。
- 不重跑
tsc -b/npm test——CI 每個 PR 已經在守,重跑是浪費。 - 不 deploy、不 push、不寫 DB、不動雲端物件。
已知盲區(每份報告都要誠實標示)
本 repo 內查不到「上游資料多久沒更新」。src/data/upstreamRegistry.ts 只做
layer_key ↔ catalog dataset_id 的橋接,沒有頻率/最後更新時間欄位;
頻率目前散在各 handoff.md 的自由文字(44 份中 23 份有寫),無法機器巡檢。
A1 能抓到動態表斷更,半動態/靜態資料的過期只能靠 F2 跨 repo 讀 catalog frontmatter。
長期解是把更新頻率結構化——這是本 skill 之外的獨立工作。
腳本實作陷阱(改收集器前必讀)
src/data/layerParamsSpec.ts含非文字位元組,BSD grep 會判成 binary 並靜默回空(不報錯)。 用 import 讀,或grep -a。- 資料夾層級
git log -1會被批次 commit 洗掉(一個docs(backlog): reorganize…摸過幾乎每個 feature 夾)。staleness 要看單檔,或排除docs:/memory:前綴的 commit。 .claude/.cache/weekly-audit/不進版控——所以趨勢比較的基準是報告本身, 報告的趨勢表必須自帶關鍵數字。- 判定不要拿「結構上本來就會不等」的兩個數字當紅線(2026-08-21 教訓)。
原本 Three.js 檢查用
目錄總項目數 !== *Scene.ts 數判歧義,但src/three/本來就有支援檔與shaders/子目錄——這種判準會永遠亮黃,變成每週噪音。 正確做法是比對「README 宣稱的數」與「該敘述真正對應的實際數」。 - 「30+」「約 N」這種開放式寫法不能當精確值比。collector 差 2 倍才報、 nginx location 差 30% 才報,否則每週都在報一個作者本來就沒打算寫精確的數字。
- A6 期望清單只放首載後應常駐的 source。依 viewport 動態建立的 source
(目前為 JP height)會把 registry entry 當 template,runtime 只建立帶 region suffix
的 sourceId。
window.__overlaySourceIds必須排除這些 template,動態 source 改由 lifecycle 專屬 browser acceptance 驗證;否則會把正常的延遲載入誤報成紅燈。 - README 的「可開關圖層/主題」以 production
THEMES為準,不是 manifest 裡section !== null的筆數。manifest 可保留 release-gated 或 DEV-only recipes,這些是可驗證的 registry entry,但不是正式站 sidebar toggle。總 key數、production toggle 與 orphan 必須分開報。
主動更新時機
- 新增檢查項 → 改對應收集器 + 本檔 Step 1 的表 + proposal 的 §2 總表 + 本檔 frontmatter 的 description, 四處同步(description 若寫死項目數就會 drift,所以它現在只寫「六組」不寫總項數)。
- 收集器誤報/漏報 → 先改腳本,並把踩到的坑寫進上面「腳本實作陷阱」。
- 連續 3 週某項都是 🟢 且沒變化 → 考慮降頻或移除,別讓報告變成噪音。
- 白名單自動修出過事 → 立刻把那類移出白名單,並在此註明原因。
- v2 接上 agent-browser 真 render 驗收後 → 改寫「本 skill 不做」第一條。
Related
- 設計提案:
docs/proposal/weekly-audit-2026-08-21/README.md - 報告索引:
docs/audit/weekly/README.md - 上層生態的跨 repo drift check:
../.gis-agent-system/schedule/ - 相鄰 skill:
layer-onboarding(單層上線驗收)、wrap-up(session 收尾)、supabase-optimize+/check-rpc(慢 RPC 的處置)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

