ponytail-audit
整個 repo 的品質稽核，找 bug、風險、慢的地方和該刪的程式碼
中文翻譯
---
name: ponytail-audit
description: >
對整個 repo 做品質稽核：bug、安全漏洞、真實負載下會壞掉的地方、
沒有測試的高風險程式碼、慢的路徑，以及哪些該刪除、合併或
拆分。依重要性排序，每個發現都用白話解釋。一次性報告，
不改任何東西。用於「audit this codebase」、「review the whole repo」、
「find bloat」、「what can I delete」、/ponytail-audit。
---
像一個剛接手 repo、壞掉時會被叫起來處理的資深工程師那樣，
稽核整個 repo。重要性順序：正確、安全、扛得住
負載、有測試、快、精簡。精簡仍然重要：每多一行，之後都要有人讀、
測試、修。這是使用者要求的報告，所以要完整給出。
## 1. 先畫地圖
- 稽核使用者指名的範圍：資料夾、套件，或整個 repo。
沒指名就是整個 repo。
- 讀 README、deploy 和 build 設定、相依套件清單、
進入點（main、routes、handlers、jobs、CLI 指令）和測試。
- 找出預期的負載：是一個人跑腳本，還是很多使用者和
行程同時在用。以此判斷規模，並說明你假設的是哪種負載。
- 把主要流程從頭追到尾：資料從哪裡進來、存了什麼、
又送出什麼。這些路徑要完整讀過：使用者的輸入、金流、驗證、
資料寫入、背景工作、行程之間共用的任何東西。
- repo 很大：深入看出錯代價最高的地方，不要一個檔案一個檔案看。要說明
哪些部分你沒讀。
## 2. 要找什麼
1. **Bug：** 結果錯誤、崩潰、漏掉的邊界情況（空值、零、最後一項、
四捨五入、時區）、呼叫端和函式回傳值對不上、
同一條規則在兩個地方套用得不一樣。
2. **風險：** 安全漏洞（injection、弱隨機性、程式碼裡的密鑰、
沒檢查使用者的輸入）、資料遺失（錯誤被吞掉、寫入
順序錯誤、沒有 transaction）。
3. **規模：** 一個使用者沒問題，很多使用者就錯：先檢查再寫入的 race、
每個行程都做同一份工作、只增不減的記憶體或清單、每個項目
一個 query、大量輸入下的 O(n^2)、本來應該共用卻是各行程自己持有的狀態。
4. **缺少測試：** 高風險的邏輯（分支、parser、金流、安全、資料
寫入），沒有任何一個在它壞掉時會失敗的測試。要一個好測試，不是追求覆蓋率。
5. **速度：** 大幅變慢是問題。小幅改善（熱迴圈裡重複的工作）
是建議；有些軟體連每一毫秒都計較。
6. **精簡：** 不該存在或該更小的程式碼。
- delete：死碼、沒用到的選項、旗標和設定、投機性的功能
- reuse：兩個做同一件事的 helper（留一個，指出是哪條路徑）
- stdlib / native：標準函式庫或平台本來就做得到；
相依套件做的事，幾行程式碼或平台就做得到
- yagni：只有一個實作的介面、只有一個產品的 factory、
只是把呼叫轉傳的 wrapper
- merge：必須一起改的近乎複製貼上的程式碼
- split：一個函式或類別做了好幾件不相關的工作，所以
難讀也難測。要依工作拆，絕對不要依行數拆，也絕對不要拆成
只為了讓函式變短而存在的 helper。
## 3. 回報之前先檢查
- 每個發現都要有具體的案例：「這個輸入或情境會導致這個
錯誤的結果」。沒有案例，就不算發現。
- 在說某段程式碼沒用到之前，先在整棵樹 grep 它，包括測試、
fixture、設定，以及字串或動態參照。
- 標了 `shortcut:`（或較舊的 `ponytail:`）註解並寫明限制的捷徑，是一個
決定，不是發現，除非預期的負載已經超過那個限制。
- 提出能運作的最小修法。偏好刪程式碼的修法。絕對不要
加問題不需要的分層、框架或設定。
- 不要個人品味的風格意見，不要「建議考慮」，不要模糊的擔憂。
## 4. 輸出
用非常簡單的英文：短句、日常用字。第一次用到技術
術語時要解釋。讀的人可能從來沒看過這份程式碼。
開頭先寫 `What this repo does:`，兩三句話，再寫你假設的
負載。
然後把發現分成三組，最重要的放最前面，空的組別跳過：
- **Must fix：** bug、安全、資料遺失、在預期負載下會壞掉。
- **Should fix：** 沒有測試的高風險程式碼、真正的慢、重複、
一個函式混了好幾種工作、不該存在的程式碼。
- **Nice to have：** 小幅提速、更短的寫法。
發現要跨組連續編號，這樣使用者可以說「修 2 和 5」。
最多 20 個發現；如果你省略了比較小的，要說省略了幾個。
每個發現都要有完整的四個部分，每部分一兩句短句：
2. **訂單落在錯的日期**（`billing/close_day.py:L40-52`）
- **這是什麼：** 這個工作在午夜結算當天，並對當天所有訂單收費。
- **問題：** 它從伺服器時鐘取得「今天」，而伺服器用的是 UTC。柏林時間
00:30 下的訂單，會被算到前一天。
- **修法：** 在商店的時區裡，只算一次日期：
`datetime.now(ZoneInfo("Europe/Berlin")).date()`。一行，其他都不用動。
- **如果不修：** 晚下的訂單會顯示錯的日期，會計得手動修正。
結尾要有：
- `Verdict:` 一行：健康，或是該先修什麼。
- `Lean: -<N> lines, -<M> dependencies possible.`，有精簡類的發現時才寫。
- `Not checked:` 你沒讀或沒辦法執行的部分。
什麼都沒發現：寫 `What this repo does:`，然後寫 `Healthy. Nothing to fix.`，
再加一行說明你檢查了什麼。
一次性報告，不改任何程式碼。英文原文
---
name: ponytail-audit
description: >
Quality audit of a whole repo: bugs, security holes, what breaks under real
load, risky code without tests, slow paths, and what to delete, merge or
split. Ranked, each finding explained in plain English. One-shot report,
changes nothing. Use for "audit this codebase", "review the whole repo",
"find bloat", "what can I delete", /ponytail-audit.
---
Audit the whole repo like the senior developer who just inherited it and
will be paged when it breaks. Order of importance: correct, safe, holds under
load, tested, fast, lean. Lean still matters: every extra line must be read,
tested and fixed later. This is a report the user asked for, so give it in full.
## 1. Map first
- Audit what the user names: a folder, a package, or the whole repo.
Nothing named: the whole repo.
- Read the README, the deploy and build config, the dependency list, the
entry points (main, routes, handlers, jobs, CLI commands) and the tests.
- Find the expected load: one person running a script, or many users and
processes at once. Judge scale against that, and say which load you assumed.
- Trace the main flows end to end: where data comes in, what is stored,
what goes out. Read those paths fully: input from users, money, auth,
data writes, background jobs, anything shared between processes.
- Big repo: go deep where a mistake costs the most, not file by file. Say
which parts you did not read.
## 2. Look for
1. **Bug:** wrong result, crash, missed edge case (empty, zero, last item,
rounding, time zones), callers that disagree with what a function returns,
the same rule applied differently in two places.
2. **Risk:** security holes (injection, weak randomness, secrets in code,
missing checks on input from users), data loss (errors swallowed, writes
in the wrong order, no transaction).
3. **Scale:** fine for one user, wrong for many: check-then-write races, the
same work done by every process, memory or lists that only grow, a query
per item, O(n^2) on big input, per-process state that must be shared.
4. **Missing test:** risky logic (a branch, a parser, money, security, data
writes) with no test that fails when it breaks. One good test, not coverage.
5. **Speed:** big slowdowns are problems. Small wins (work repeated in a hot
loop) are suggestions; some software counts every millisecond.
6. **Lean:** code that should not exist or should be smaller.
- delete: dead code, unused options, flags and config, speculative features
- reuse: two helpers doing the same thing (keep one, name the path)
- stdlib / native: the standard library or platform already does it;
a dependency doing what a few lines or the platform can do
- yagni: interface with one implementation, factory with one product,
wrapper that only passes calls through
- merge: near-copies that must change together
- split: one function or class doing several unrelated jobs, so it is
hard to read or test. Split by job, never by line count, and never into
helpers that exist only to make a function shorter.
## 3. Check before you report
- Every finding needs a concrete case: "this input or situation leads to this
wrong result". No case, no finding.
- Before calling code unused, grep the whole tree for it, including tests,
fixtures, config, and string or dynamic references.
- A shortcut marked with a `shortcut:` (or older `ponytail:`) comment that names its limit is a
decision, not a finding, unless the expected load already crosses it.
- Propose the smallest fix that works. Prefer fixes that delete code. Never
add layers, frameworks or config the problem does not need.
- No style taste, no "consider", no vague worries.
## 4. Output
Very simple English: short sentences, everyday words. Explain a technical
term the first time you use it. The reader may never have seen this code.
Start with `What this repo does:` in two or three sentences, and the load
you assumed.
Then the findings in three groups, most important first, skip empty groups:
- **Must fix:** bug, security, data loss, breaks at the expected load.
- **Should fix:** risky code without a test, real slowness, duplication, a
function that mixes jobs, code that should not exist.
- **Nice to have:** small speed-ups, shorter forms.
Number findings across all groups, so the user can say "fix 2 and 5". At
most 20 findings; if you left smaller ones out, say how many.
Every finding has all four parts, each one or two short sentences:
2. **Orders land on the wrong day** (`billing/close_day.py:L40-52`)
- **What this is:** At midnight this job closes the day and bills all orders of that day.
- **Problem:** It takes "today" from the server clock, which runs in UTC. An order placed
at 00:30 in Berlin is billed on the day before.
- **Fix:** Compute the day once in the shop's time zone:
`datetime.now(ZoneInfo("Europe/Berlin")).date()`. One line, nothing else changes.
- **If we skip it:** Late orders show the wrong date, and accounting fixes them by hand.
End with:
- `Verdict:` one line: healthy, or what to fix first.
- `Lean: -<N> lines, -<M> dependencies possible.` when lean findings exist.
- `Not checked:` the parts you did not read or could not run.
Nothing found: `What this repo does:`, then `Healthy. Nothing to fix.` and
one line on what you checked.
One-shot report, changes no code.