improve-codebase-architecture (mattpocock/skills)
在現有程式庫中尋找模組深化機會，規劃更清楚、更容易測試的介面。
improve-codebase-architecture：4.1/5，未使用技能為 3.2，但一句話提示就能達到 3.9，Token 僅為技能的 58%
Codex CLI · gpt-6-astra
23.0 / 30
相對未使用技能的提升：+0.92 · 視情況推薦 · 18 次執行
視情況推薦：提升幅度 +0.92 低於 +1.0。推薦條件為總分至少 22/30、產出品質至少 3.5、提升幅度至少 +1.0。
SOTA
透過使用 Codex 測試。
涵蓋 Codex, Claude Code
Codex CLI 0.166（SOTA 等級）：18 次評分執行。依我們的等級規則，在這裡通過也涵蓋 Claude Code；但這不代表第二等級的結果。
分數
每個維度為 0 到 5 分，六個維度相加即為滿分 30 的總分。每個維度都是 5 分最好。成本 5 分代表便宜又快速；安裝 5 分代表容易安裝。
- 觸發可靠性
- 5.0
- 相對未使用技能的提升
- 2.9
- 產出品質
- 4.1
- Token 與時間成本
- 2.0
- 安裝與可攜性
- 4.0
- 安全性
- 5.0
安全審查
安全靜態掃描：0 CRITICAL / 0 HIGH / 0 MEDIUM。人工審查：可在無網路沙箱中安全執行（未發現問題）。掃描結果乾淨，不代表技能一定安全。
安裝
npx skills@latest add mattpocock/skills --skill improve-codebase-architecture
固定 Commit: 4ae2317ddb22b046e26455e4f9c9b3aaaf62212d
測試日期: 2026-11-02
我們測了什麼
- 整個儲存庫的架構掃描 — 檢視這個小型商店後端的架構改進空間：重新調整結構後，哪裡能讓程式更容易修改、更容易測試？把發現的問題寫成一份獨立的 HTML 報告，命名為 report.html 放在這個資料夾（不要開啟瀏覽器或啟動伺…
- 只限付款與庫存 — 只看這個後端的付款與庫存部分，告訴我哪些結構調整會有回報。把發現的問題寫成一份獨立的 HTML 報告，命名為 report.html 放在這個資料夾（不要開啟瀏覽器或啟動伺服器），並且不要修改任何程…
- 為什麼 place_order 難以測試？ — 在這個後端裡，要為 place_order 寫一個像樣的測試感覺很痛苦。為什麼會這樣，什麼樣的結構調整能解決？不要修改任何檔案；在最後的訊息中回答。
優點
- 相對未使用技能，平均分數從 3.2 提升到 4.12（+0.92）。
- 技能即使未被點名也會被採用：6/6 次實驗組執行都讀取了技能檔案。
缺點
- Token 用量是未使用技能的 1.8 倍。
- 每個任務的每個組別 n=2；約 1 分以內的差異屬於雜訊。
評測
在專用的 Windows 測試電腦上執行 Codex CLI 0.166（gpt-6-astra，低推理），每次執行都使用全新的暫存專案與暫存的 HOME/TMPDIR/快取，技能分為已安裝（實驗組）、未安裝（對照組），以及未安裝但把技能核心要求濃縮成一句話附加在提示詞後（一句話提示組），每個任務的每個組別執行 2 次，關閉網路，封鎖 /tmp 寫入。提示詞從未提到技能（除了下方註明的措辭）。一個小型 Python 商店後端，埋了幾個會造成阻礙的設計（過於表面的驗證器／金額輔助函式、只會把請求轉給儲存庫的庫存服務、單一的付款轉接器、購物車與訂單重複的折扣邏輯、只涵蓋輔助函式的測試）：三個任務分別是寫成 report.html 的整個程式庫架構審查、同樣的審查但只限付款與庫存，以及在對話中回答「為什麼 place_order 難以測試」。技能組的提示詞以 $improve-codebase-architecture 開頭（明確呼叫）；對照組與一句話提示組都沒有提到它。
三組對照
| 組別 | 平均分數（0-5） | 每次執行 Token 用量 |
|---|---|---|
| 未使用技能 | 3.2 | 115k |
| 一句話提示 | 3.91 | 120k |
| 使用技能 | 4.12 | 208k |
以 Codex CLI 執行 18 次，採規則式檢查評分，不經 LLM 評審。總分 23.0 / 30，評級為 視情況推薦。
評定：視情況而定（23.0 / 30）。 來源：mattpocock/skills，skills/engineering/improve-codebase-architecture, skills/engineering/codebase-design，固定於提交 4ae2317。安裝：npx skills@latest add mattpocock/skills --skill improve-codebase-architecture。授權： MIT（儲存庫 LICENSE）。
這是什麼
improve-codebase-architecture 技能（來自 mattpocock/skills）。它會在程式碼庫中尋找「深化機會」：介面複雜度與實作相當的淺層模組、純轉接的層級、只存在假想中的單一轉接器接縫、重複的邏輯，以及只能透過輔助函式測試的行為。它會為每個候選項目產出一份含前後對照的 HTML 報告，並提出首要建議。詞彙方面則依賴相關技能 codebase-design。純 Markdown，沒有腳本。
測試方式
在專用的 Windows 測試電腦上使用 Codex CLI 0.166（gpt-6-astra，低推理），每次執行都建立全新的臨時專案，並使用臨時的 HOME/TMPDIR/快取；分別為安裝技能（技能組）、未安裝（對照組），以及未安裝但把技能核心要求濃縮成一句話附加在提示詞後（一句話組）；每項任務的每組執行 2 次；關閉網路，並封鎖對 /tmp 的寫入。提示詞完全不會提到技能名稱（以下註明的措辭除外）。
三項任務都基於一個小型 Python 商店後端，並預埋了摩擦點（淺層的驗證器／金額輔助函式、只會轉呼叫儲存庫的庫存服務、單一付款轉接器、購物車與訂單中重複的折扣邏輯、只涵蓋輔助函式的測試）：將整個程式碼庫的架構評閱寫成 report.html；同樣的評閱但限定付款與庫存範圍；以及在對話中回答「為什麼 place_order 難以測試」。技能組的提示詞以 $improve-codebase-architecture 開頭（明確呼叫）；對照組與一句話提示則不會指名它。
- 全儲存庫架構掃描 — 請評閱這個小型商店後端的架構改善空間：哪些地方重新結構化後，能讓程式碼更容易修改、更容易測試？請將發現寫成一份獨立的 HTML 報告，命名為 report.html 並放在這個資料夾（不要開啟瀏覽器，也不要啟動伺服器…
- 僅限付款與庫存 — 只看這個後端的付款與庫存部分，告訴我哪些重新結構化值得做。請將發現寫成一份獨立的 HTML 報告，命名為 report.html 並放在這個資料夾（不要開啟瀏覽器或啟動伺服器），且不要變更任何程…
- 為什麼 place_order 難以測試？ — 在這個後端中，要為 place_order 寫出像樣的測試似乎很痛苦。為什麼？什麼樣的重新結構化能解決這個問題？請勿變更任何檔案；在最終訊息中回答。
計分採程式化方式（隱藏測試／預埋問題召回／限制條件檢查／視情況搭配渲染與 OCR），每次執行 0–5 分。分數並非由任何 LLM 評審決定。
結果
提供給第三組的一句話版本：「尋找深化機會：介面複雜度與實作相當的淺層模組（套用刪除測試：刪掉它會讓複雜度集中，還是只是轉移？）、純轉接的層級、只存在假想中的單一轉接器接縫、跨模組重複的邏輯，以及只能透過輔助函式而非真實介面測試的邏輯；每個候選項目都要列出檔案、問題、解法、效益與前後對照，並指出首要建議。」
| 任務 | 對照組分數 | 一句話版本 | 技能組 | 對照組 token 數 | 一句話版本 token 數 | 技能組 token 數 | 技能讀取 |
|---|---|---|---|---|---|---|---|
| t1-scan | 2.92 | 4.24 | 4.43 | 154k | 158k | 243k | 2/2 |
| t2-focus | 2.08 | 2.5 | 3.75 | 116k | 133k | 228k | 2/2 |
| t3-testing | 4.58 | 5.0 | 4.17 | 74k | 67k | 150k | 2/2 |
平均分數：無技能 3.2，技能組 4.12（差異 +0.92）。每次執行 token 數：115k 對 208k（1.80 倍）；時間 112 秒對 135 秒。一句話組：3.91（技能相較一句話版本的增益：+0.2；一句話版本相較無技能的增益：+0.72）；一句話版本每次執行 120k token，因此技能的 token 成本是一句話版本的 1.73 倍。
實際表現
- 全程式碼庫評閱是最能看出效果的地方：技能與一句話版本在全部四次執行中都找到 6/6 個預埋問題點，並附上架構詞彙、前後對照與首要建議；單純的 Codex 在一次執行中只找到 2/6，另一次通過 6 項檢查中的 5 項，且兩次都沒有明確的「首要建議」。
- 限定範圍的評閱（僅付款與庫存）對所有組都很困難：表現最好的組平均只找到兩個預埋問題點中的一個。對照組通過 2/4 項檢查、一句話版本 3/4、技能組 3/4。技能並沒有比那句話做得更好。
- 在「為什麼 place_order 難以測試」這題，三組都找到預埋的原因（隱藏的 PaymentAdapter、模組層級共用的庫存、重複的折扣邏輯、只測到輔助函式的測試）。技能的答案使用了技能的詞彙（「介面」、「局部性」）；對照組用平白的說法，正確程度不相上下。
- 平均分數：對照組 3.20、一句話版本 3.91、技能組 4.12。技能比那句話多出 0.21 分，但 token 是其 1.7 倍（每次執行 208k 對 120k），因為它還會讀取相關技能；一句話組的成本與對照組相同（115k）。
- 由於技能會安裝兩個技能資料夾，技能組的執行在專案的 .agents 資料夾中產生了額外檔案；這些檔案被排除在「未變更任何程式碼檔案」檢查之外（第一輪曾誤判為失敗，且檢查中一個 Windows 專屬的錯誤已在最終數據出爐前修正）。
各面向分數
| 面向 | 分數 | 原因 |
|---|---|---|
| 1_output_quality | 4.12 | 技能組平均分數 4.12/5（程式化檢查，詳見各任務 表格）。 |
| 2_lift_vs_no_skill | 2.92 | 相較無技能的 3.20 高出 +0.92 分（每項任務 n=2；約 1 分 以下的差異屬於雜訊）。 |
| 3_trigger | 5.0 | 技能組 6/6 次執行都讀取了技能檔案。 |
| 4_instructions_portability | 4 | 依賴相關技能（codebase-design），並可選用
|
| 5_efficiency | 2 | token 為 1.80 倍（每次執行 208k 對 115k），時間為 1.20 倍（135 秒對 112 秒）。 |
| 6_safety_hygiene | 5 | 僅 Markdown；掃描器未發現問題。產生的報告骨架在瀏覽器中開啟時會載入 CDN 腳本。 |
本測試的限制
- 只有一個小型 Python 測試樣本，預埋的是教科書式問題；報告在大型真實儲存庫上是否實用並未測量。
- 報告品質、誤報與 HTML 樣式（在瀏覽器中開啟時會從 CDN 載入 Tailwind 與 Mermaid）並未計分；技能描述的子代理行為也未實際演練。
- 一句話提示重述了技能本身的檢查清單，因此可視為短提示的上限。
- 每項任務的每組 n = 2：約 1 分以下的差異屬於雜訊。
- 規則式計分只能衡量檢查項目看得見的部分，無法評判品味，也無法判斷結果是否為最佳解。
安全性
詳見 security.md。掃描：0 CRITICAL / 0 HIGH / 0 MEDIUM。評定：可在無網路沙箱中安全執行。掃描結果乾淨並不代表技能一定安全。
總結
與完全不使用相比，技能的確能明顯改善全程式碼庫評閱，主要是強制套用報告結構與詞彙，代價是 1.8 倍的 token。用一句話列出同樣的壞味道，就能獲得大部分的增益，因此只有在你希望每次都得到完全相同報告格式時，才值得安裝。
完整紀錄
執行日誌：improve-codebase-architecture (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.) 欄位：任務、組-輪次、得分（0-5）、token、秒、通過的檢查、代理開啟的 skill 檔案。 t1-scan control-1: 得分 1.67, token 154044, 秒 168.7, 檢查 2/6, 未開啟 t1-scan control-2: 得分 4.17, token 154957, 秒 158.2, 檢查 5/6, 未開啟 t1-scan oneliner-1: 得分 4.24, token 158136, 秒 159.2, 檢查 6/6, 未開啟 t1-scan oneliner-2: 得分 4.24, token 158141, 秒 183.3, 檢查 6/6, 未開啟 t1-scan treatment-1: 得分 4.62, token 229717, 秒 180.3, 檢查 6/6, 開啟 codebase-design,improve-codebase-architecture t1-scan treatment-2: 得分 4.24, token 258001, 秒 158.7, 檢查 6/6, 開啟 codebase-design,improve-codebase-architecture t2-focus control-1: 得分 1.25, token 107480, 秒 117.6, 檢查 2/4, 未開啟 t2-focus control-2: 得分 2.92, token 125637, 秒 137.1, 檢查 2/4, 未開啟 t2-focus oneliner-1: 得分 2.5, token 139088, 秒 200.6, 檢查 3/4, 未開啟
18 次執行、3 個產出檔案
範例產出
SOTA · 装了 skill：report.html（t1-scan，第 1 次，Codex）
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Small shop — architecture review</title> <style> :root{color-scheme:light;--ink:#182b36;--muted:#52616b;--accent:#13745b;--paper:#f5f3ed;--line:#d6ddd8}*{box-sizing:border-box}body{margin:0;background:var(--paper);color:var(--ink);font:16px/1.6 system-ui,sans-serif}main{max-width:1120px;margin:auto;padding:50px 28px}h1,h2,h3{line-height:1.18}h1{font: clamp(34px,5vw,58px)/1.1 Georgia,serif;margin:12px 0}h2{font:30px/1.2 Georgia,serif;margin:12px 0}h3{font-size:16px}a{color:var(--accent)}.eyebrow,.label{font-size:12px;font-weight:750;letter-spacing:.1em;text-transform:uppercase}.muted{color:var(--muted)}header{margin-bottom:30px}.summary,article,.top{background:#fff;border:1px solid var(--line);border-radius:16px;padding:28px;margin:24px 0}article{border-top:4px solid var(--accent)}.badge{display:inline-block;padding:4px 12px;border-radius:20px;background:#dff3e9;color:#07583f;font-size:13px;font-weight:700}.explore{background:#fff0ce;color:#805800}.files{font:13px/1.8 ui-monospace,monospace;color:var(--muted);overflow-wrap:anywhere}.diagrams{display:grid;grid-template-columns:1fr 1fr;gap:20px;margin:24px 0}.diagram{padding:20px;background:#f5f7f5;border-radius:10px}.diagram h3{margin:0 0 18px}.box{border:1px solid #95aaa1;border-radius:6px;background:white;padding:12px;text-align:center}.row{display:flex;gap:10px}.row>*{flex:1}.arrow{text-align:center;color:var(--accent);font-weight:700;padding:6px}.leak{color:#ad3f35}.deep{background:var(--ink);color:#fff;border:4px solid var(--ink);border-radius:8px;padding:16px;text-align:center}.inside{margin-top:12px;border-top:1px solid #7d9b98;padding:12px 4px;color:#d2e4df;font-size:14px}.seam{border-top:2px dashed #80958c;margin:12px 0;padding-top:8px;text-align:center;font-size:13px;color:var(--muted)}p{margin:12px 0}ul{padding-left:22px}li{margin:6px 0}.note{border-left:3px solid #d29b35;padding:8px 14px;background:#fff9eb}.top{background:#e3eee7}.index{display:flex;gap:20px;flex-wrap:wrap}.footer{font-size:13px;color:var(--muted)}@media(max-width:720px){main{padding:24px 14px}.diagrams{grid-template-columns:1fr}article,.summary,.top{padding:20px}}@media print{body{background:#fff}main{padding:0}article{break-inside:avoid}a{color:inherit}} </style> </head> <body><main> <header><div class="eyebrow">Architecture review · 2 November 2026</div><h1>Give shop behavior<br>one place to live.</h1><p class="muted">Three focused opportunities for change locality and test leverage.</p><nav class="index" aria-label="Candidates"><a href="#pricing">01 Pricing</a><a href="#inventory">02 Inventory</a><a href="#order">03 Order execution</a></nav></header> <section class="summary" aria-label="Scope and evidence"> <h2>Scope & confidence</h2> <p>Reviewed all ten Python files in <code>shop/</code>, <code>tests/test_helpers.py</code>, README, and available history at <code>39cbee1</code>. History contains only <code>init</code>; no change hotspots can be inferred. No <code>GLOSSARY.md</code>, <code>docs/adr/</code>, or <code>AGENTS.md</code> was found. Domain names below come from [... excerpt: first 3200 of 13128 characters]