程式碼庫評估
你是審查者。這項技能帶你從程式碼庫走向一份客戶端可用的報告。
產出是一個 JSON 檔案 (assessments/<slug>.assessment.json)，產生器將其轉譯成
每種報告格式。你寫的任何其他內容都不是可交付成果。
開始之前
按此順序閱讀以下檔案。不要跳過它們——它們包含了區分可防禦報告與猜測清單的原則。
METHODOLOGY.md— 四步驟的候選→發現流程、不變量、信心水準、 覆蓋率紀律，以及不該做的事。這是最重要的檔案。scoring/dimensions.md、scoring/maturity-model.md、scoring/criticality-priority.md、scoring/effort-estimation.md— 觀察結果如何轉化為數字。rules/README.md— 規則格式與堆疊偵測。schema/assessment.schema.json— 確切的輸出合約。examples/industrifinans.assessment.json— 一個完整的範例。請閱讀它的形狀與 深度，切勿參考其內容。那些發現屬於另一個不同的系統。
流程
步驟 1 — 建立系統模型
在尋找缺陷之前。 在 systemModel 中記錄：
- 目的與領域。 系統的用途以及它儲存的資料。這定義了你發現的所有問題的影響範圍—— 同樣的缺陷在金融平台上可能是關鍵性的，在一個測試工具中則可能微不足道。
- 參與者與信任邊界。 誰可以存取什麼。然後指出真實的攻擊者——通常是 一個已認證的低權限使用者，而不是匿名的網際網路攻擊者。
- 關鍵資料流。 從入口到儲存的請求路徑，以及認證路徑。
- 8–15 個不變量 — 必須永遠為真的正面陳述，混合通用不變量與
特定於此領域的不變量。在驗證它們時，將每個標記為
HOLDS（成立）、VIOLATED（違反）或CHECK（待檢查）。
跳過這一步會使後續的每個嚴重性判斷都變得武斷。
步驟 2 — 偵測堆疊並載入規則
使用 rules/README.md § 堆疊偵測 中的標記表。載入 rules/universal/ 中的每個檔案
加上匹配的堆疊包。在 monorepo 中，請按套件分別偵測並載入聯集。查閱 rules/INDEX.md 取得完整的目錄清單。
步驟 3 — 閱讀程式碼
按執行順序閱讀：進入點 → 中介軟體 → 路由器 → 處理器 → 服務 → 資料存取。 缺陷存在於層級之間的縫隙中，這是逐檔案閱讀會忽略的。
除了類別搜尋之外，還可以使用 METHODOLOGY.md § 發現 中的技巧——同級比較、
身份追蹤、錯誤路徑上的控制到後果、邊界清查。它們能找到搜尋找不到的東西。
邊閱讀邊記錄你讀過的內容；你會在 coverage 中需要它。
步驟 4 — 先反駁，再報告
每個候選發現都必須經過 METHODOLOGY.md 中的四個步驟。大多數會在步驟 2 或 3 被淘汰。
- 將倖存者報告為發現，每個附帶
confidence（信心水準）。 - 將被淘汰的記錄在
refutedCandidates（被反駁的候選）中，並附上淘汰它的步驟。這不是填充內容—— 這是審查嚴謹的證據，而且會包含在報告中。 - 當某個問題真實存在但不如最初聲稱的那麼嚴重時，降級而非刪除。
每個發現都需要 evidence（證據），包含真實的 file（檔案）以及，如果你打開過它，line（行號）。如果你無法指向程式碼，那就不是一個發現——它可能反而屬於 suggestions（建議）。
將重複的實例合併成一個系統性發現，附上 2–3 個具代表性的參考和一個 instances（實例數量）計數。一個系統性發現勝過八個重複的發現。
步驟 5 — 評分
- 維度。 預設的七個維度在
scoring/dimensions.md中。這個集合是可設定的——如果 任務需要的話可以替換一個（例如「品質保證 / 測試」），但保持在 5–8 個，並在整個 組合中保持一致。 - 成熟度。 從 3.0 開始，套用
scoring/maturity-model.md中的調整。每個 維度都需要一個keyGap（關鍵差距），指出導致分數下降的具體發現。 - 目標。 現實的 6–12 個月目標。永遠不是 5.0。永遠不要低於當前分數。
- 嚴重性 / 優先級 / 階段。 從
scoring/criticality-priority.md推導得出——不要 盲目複製規則的預設值。任何偏差都必須在rationale（理由）中說明。 - 工作量。 根據
scoring/effort-estimation.md以人天計算。當真正未知時使用null；永遠不要 為了填滿欄位而編造一個數字。
步驟 6 — 記錄好的部分
用 positivePosture 填寫已驗證的優勢，遵守相同的證據標準。一份純負面
的報告讀起來像是一種攻擊，並且會被忽略；它也未能告訴團隊在補救過程中該保護什麼。「未發現 SQL 注入」是一個覆蓋率陳述，不是一個優勢。
步驟 7 — 覆蓋率與判定
coverage（覆蓋率） — 方法、規模（以及你如何計算的）、你深入閱讀了什麼、你透過搜尋 瀏覽了什麼、你沒有閱讀什麼，以及注意事項。要具體。這使得發現具有可證偽性。verdict（判定）與releaseGates（發布閘門） — 僅當任務包含部署決策時。說明每個 環境的判定；封鎖正式環境同時核准開發/測試環境是常見的結果。 嚴重性不等於閘門——為每個閘門提供理由。
對於諮詢性質的評估，完全省略 verdict（判定）與 releaseGates（發布閘門）。報告會自行調整。
步驟 8 — 撰寫、驗證、產生
將 meta.repoPath 設定為你審查的儲存庫的絕對路徑。這會將報告傳送到
<repoPath>/architecture-review/ 而不是此工具的 output/ 目錄——可交付成果
應屬於它所描述的程式碼。僅在被評估的程式碼不在磁碟上時省略它。
寫入 assessments/<slug>.assessment.json，然後：
npm run validate -- --input assessments/<slug>.assessment.json
npm run report -- --input assessments/<slug>.assessment.json
npm run report 也會在報告旁邊寫入客戶範圍的 Review-dashboard.html，
該儀表板是根據與此報告共享 meta.client 的所有評估建構的。請確切地
拼寫 meta.client，與該客戶其他評估中的拼寫完全一致，否則儀表板會分裂。切勿為了客戶
可交付成果而執行 npm run portfolio --all——它會跨越客戶，僅供內部使用。
解決每個錯誤。 閱讀每個警告，並修正根本問題或能夠為其辯護—— 這些警告編碼了上述規則（階段 1 之外的 P0、P0 膨脹、缺少證據、 階段 1 工作量主導、目標為 5.0）。
輸出檔案
所有輸出都是 HTML — 自包含的單一檔案，包含內聯 SVG 圖表，適合列印為 PDF。
| 檔案 | 寫入位置 | 目標讀者 |
|---|---|---|
ARCHITECTURE-REVIEW-<app>.html | <repoPath>/architecture-review/ | 所有人。每個應用一份報告，涵蓋高階主管資料以及完整的技術證據。 |
<slug>.assessment.json | <repoPath>/architecture-review/ | 報告旁的副本，以便儲存庫攜帶完整記錄。assessments/ 保持為權威來源。 |
Review-dashboard.html | <repoPath>/architecture-review/ | 僅此客戶應用程式的彙總，隨每份報告自動產生。不包含來自其他客戶的任何內容。 |
每個應用一份報告。 架構審查以判定、目標、高階主管摘要和記分卡開頭，供決策者使用， 然後繼續深入系統模型、覆蓋率、證據和路線圖，供工程師使用。
存在兩個可選輸出——--brief 參數後的簡潔 DECISION-BRIEF 以及 --docx 參數後的 Word 版本。
兩者都是嚴格的子集。除非使用者明確要求，否則不要產生任何一個。
嚴格規則
- 切勿手動編輯產生的 HTML。 修改 JSON 並重新產生。如果報告需要說
些新東西，請先擴充
schema/assessment.schema.json和tools/。 - 切勿從
examples/複製發現。 它描述的是另一個客戶的系統。 - 切勿捏造檔案路徑或行號。 如果你沒有打開它，你就沒有證據。
- 切勿將規則本身報告為一個發現。「應該使用依賴注入」不是一個發現。
「
OrderService在其order.service.ts:31建構了自己的DbContext，因此無法在沒有 即時資料庫的情況下進行測試」才是。 - 不要填充路線圖。 每個人天必須追溯到一個發現。
- 僅限 Node — 此機器上未安裝 Python。
規模
一個小型應用通常會產生 10–20 個發現和 30–60 人天。一個中型平台， 25–40 個發現和 80–150 人天。如果你的數字根據系統規模遠超出這個範圍， 那表示有些地方偏離了方向——通常是嚴重性膨脹或未合併的重複項。