koleso-webestimator — 針對 Umbraco / .NET 的代理校準估算
針對 Umbraco/.NET 網頁工作的估算，其中AI 代理寫程式碼，人類進行審查。
此技能背後最重要的單一事實，來自 10 個 Umbraco 專案約 300 個真實工單：
真正讓估算失準的，很少是編碼本身。 以人類開發者工作日估算的大型工作，超標約 4 倍。號稱「2-3 小時」的小型工單，則低估了 2-3 倍。兩者的誤差源於同一個地方：程式碼周邊的工作——部署、uSync 匯入、每個環境的手動步驟、測試無法看到的真實 CMS 行為、QA 波次，以及客戶確認往返——不是被當作「緩衝」灌水，就是完全被忽略。
因此，這裡的每個估算都有兩個帳本：
- 工時 — 某人實際工作的時數：代理編碼 + 審查，加上那些不會縮減的固定開銷。
- 日曆時間 — 經過的時間，主要受等待回覆、部署窗口和 QA 佇列支配。絕不與工時混為一談。
參考檔案（當步驟要求時讀取）：
references/calibration.md— 代理速度編碼率與不會縮減的固定開銷及其預設大小references/patterns.md— 常見 Umbraco / Razor / Vue / 後台任務的參考時間references/platform-risks.md— 會導致額外部署-驗證輪次的 CMS 行為references/honesty-rules.md— 強制規則與升級門檻references/output-format.md— 內部細項與給客戶的回覆格式references/calibration-log.md— 如何記錄估算 vs 實際數據以便改善references/review-checklist.md— 審查模式：檢查已存在的估算
工作流程
步驟 0 — 尋找規格與計畫，決定估算基礎
在閱讀程式碼之前，搜尋與此任務相關的規劃文件。檢查：
- 儲存庫：
spec.md、SPEC.md、docs/spec/**、docs/specs/**、docs/plans/**（檔名包含*-plan.md、*-design.md、*-analysis.md、*-spec*.md的檔案）、docs/handover/**、docs/adr/**，以及任何檔名包含工單金鑰或功能代號的檔案； - 工單：其描述、附件與評論，以及其中連結的任何規格頁面（例如 Confluence）；
- 同一個工單先前的估算。先前的估算、被拒絕的方案或未解決的問題都會改變數字。
然後為此估算選擇一個基礎，並在輸出頂端說明是哪個：
A. 基於計畫的估算。 存在規格和/或功能計畫。
- 完整閱讀找到的每份文件，而不只是標題：需求、驗收標準、階段、檔案列表、未解決問題、修訂/偏差與審查決策。
- 按計畫階段進行估算，使用計畫自己的檔案列表和步驟作為子任務骨架（步驟 4）。
- 將每個規格需求/驗收標準對應到估算的一行。列出任何沒有階段涵蓋的需求，以及任何沒有需求要求的階段。
- 將計畫中的未解決問題帶入輸出的問題列表，每個問題附上其預設答案。
- 檢查計畫是否過時：將計畫中提到的名稱（檔案、別名、文件類型）與當前程式碼進行比較。不再匹配的行是需要標記的假設，而不是默默地為其定價。
- 範圍可以更窄，信心水準更高（請參閱
references/honesty-rules.md）。
B. 快速估算（可見範圍）。 找不到規格和計畫。
- 在頂端明確說明：「找不到規格或功能計畫——這是基於可見範圍的快速估算。」 列出你搜尋過的位置。
- 僅根據工單文字和程式碼進行估算。範圍較寬，信心水準上限為中等。
- 列出需要規格或計畫才能確定的項目（問題、你無法確定的受影響領域），以便讓數字更明確。
- 提供下一步：為該工單撰寫計畫，然後根據計畫重新估算（基礎 A）。說明你預期基於計畫的數字會朝哪個方向變動，以及原因。
如果僅存在部分文件（例如有規格但無計畫，或僅有不同階段的計畫），則對其涵蓋的部分使用基礎 A，其餘部分使用基礎 B，並標記每一行。
此外：如果存在校準日誌（references/calibration-log.md 說明了位置），請讀取類似工作類型的最新條目。
步驟 1 — 偵測技術堆疊
使用你的檔案搜尋工具（不要使用特定 shell 的命令——這通常會在 Windows 上執行）。記錄：
| 搜尋目標 | 告訴你什麼 |
|---|---|
*.csproj → Umbraco.Cms PackageReference 版本、TargetFramework | Umbraco 主要版本（10/13 = AngularJS 後台；14+ = Bellissima Lit/TS）和 .NET 版本 |
appsettings*.json 中的 ModelsMode、產生的模型資料夾 | 強型別模型 vs 動態 IPublishedContent |
uSync/ 資料夾 + uSync 設定（ExportOnSave、ImportOnFirstBoot、停用的處理器） | 架構變更是否需要每個環境手動匯入 |
App_Plugins/*/package.manifest vs umbraco-package.json + Client/ Vite 專案 | 後台擴充技術 |
package.json 檔案：vue、nuxt、react、lit、jquery；建置輸出位置 | 前端類型及其建置輸出是否被提交 |
SCSS 編譯器設定、已提交的編譯後 CSS、rtl/ltr 資料夾 | 樣式管線與 RTL 複製 |
uSync Languages/ 中的語言、佈局中的 dir="rtl" | 文化數量和 RTL 驗證成本 |
| 測試專案（xUnit/NUnit/Playwright）、Razor 是否在建置時編譯 | 綠色測試執行實際上證明了什麼 |
Composers/、Hangfire、Examine 索引設定、遷移、自訂資料庫表格 | 背景工作、搜尋、自訂資料 |
| CI/部署檔案、代管提示（App Service、IIS、Docker） | 有多少環境以及部署是否為手動 |
如果你無法讀取程式碼庫，請在輸出中說明，並將所有範圍擴大 2-3 倍（請參閱誠信規則）。
步驟 2 — 讀取最接近任務的程式碼
尋找現有範例：最近似的現有文件類型、部分檢視、控制器、Vue 島嶼、後台元素或匯入。閱讀 2-4 個這類檔案。在估算中做出的每個事實性陳述，都要對照程式碼或 uSync 架構進行驗證——例如，在寫入「該欄位不存在」之前，請搜尋內容類型設定。一個錯誤的陳述會導致完整的客戶往返。
步驟 3 — 分類
| 維度 | 選項 |
|---|---|
| 工作類型 | 請參閱 references/calibration.md 中的表格（文件類型/架構、Razor 頁面 vs 設計、Vue 島嶼、後台擴充、API/控制器、搜尋、背景工作、客戶資料匯入、第三方整合、升級、調查、錯誤） |
| 現有範例 | 高 / 中 / 低 |
| 規格清晰度 | 清晰 / 部分 / 模糊 |
| 是否寫入 CMS 資料？ | 程式碼是否建立、儲存或發佈內容、區塊、媒體或各文化別的值？ |
| 前端是否對照設計？ | 需像素檢查的 Figma 工作會觸發 QA 波次 |
| 文化數 × 斷點 | 例如 3 種語言（其中一種是 RTL）× 桌面/行動 |
| 必須到達的環境 | 本機、開發、暫存、正式——以及哪些步驟在每個環境是手動的 |
| 外部方 | 客戶內容、供應商 API、第三方腳本、其他團隊的管線 |
步驟 4 — 分解並以代理速度評估編碼規模
有計畫時（基礎 A），計畫的階段是頂層分組，其步驟/檔案列表是子任務；不要發明不同的分解方式。沒有計畫時（基礎 B），自行建立分解方式。
將工作分解為15 分鐘至 2 小時的代理工作的子任務。根據 references/patterns.md 和 references/calibration.md 中的速率來估算其規模。然後加上審查時間（生產環境程式碼的預設為代理編碼的 30-50%；測試和樣式的時間較少）。
切勿以人類開發者工作日來估算編碼規模，然後「加上緩衝」。 那正是導致約 4 倍超標的原因。如果你使用的參考是基於人類時間，請使用 calibration.md 中的乘數進行換算。
步驟 5 — 加上不會縮減的固定開銷
從 references/calibration.md →「不會縮減的固定開銷」。將每個適用的項目作為獨立的一行加入，並附上各自的範圍：
- 每個環境的交付開銷（建置、部署、uSync 匯入、字典/內容編輯、重新儲存、煙霧測試）
- 當程式碼寫入 CMS 資料或依賴執行時期行為時的真實 CMS 驗證輪次（
platform-risks.md） - 擁有者/本機執行 + QA 交接
- 針對需對照設計的前端工作的 QA 波次（分類、修正、「非錯誤」回覆）
- 多語系 / RTL 驗證矩陣
- 在範圍確定前預期的澄清往返
- 版本升級的升級尾端（回歸測試、操作手冊、預演、部署後修正）
- 流程開銷如果團隊為每個工單撰寫計畫、審查、驗證文件和交接事項
應用小型工單下限：任何必須到達共享環境的工單，即使程式碼只有一行，至少也要承擔交付開銷。
步驟 6 — 日曆時間
列出經過時間取決於哪些因素：給客戶的未解決問題、客戶必須提供的內容、供應商回覆、部署窗口、QA 可用性。分別給出日曆時間（例如「工時 2-3 小時；實際上需要 1-2 週，等待問題 1-4 的回覆」）。
步驟 7 — 自我檢查
- 子任務範圍加總等於總數。
- 沒有任何單一子任務超過 2 小時的代理工作而未進行拆分。
- 已考慮每個不會縮減的固定開銷；跳過的項目是有意為之（說明原因）。
- 任何地方都沒有使用人類開發者工作日；全程使用單一單位（小時）。
- 每個「不存在」/「已支援」的陳述都已對照程式碼或架構進行驗證。
- 信心水準與
honesty-rules.md中的修飾符一致。 - 總計 > 40 小時 → 拆分為里程碑並分別估算。
- 在頂端敘述估算基礎（基於計畫/快速/混合）。有計畫時，每個規格需求都對應到一行，每個計畫階段都已定價。沒有計畫時，輸出中需說明並列出搜尋位置。
步驟 8 — 輸出
使用 references/output-format.md：提供給開發人員的內部細項，以及給客戶的回覆（包含小時範圍表格、總範圍、分別定價的選項、假設、每個附有估算假設的預設答案的編號問題、風險、日曆備註）。
然後將估算記錄到校準日誌中（references/calibration-log.md）：如果使用者的指示指定了日誌位置，則自動記錄；否則提供開始記錄的選項。記錄技能產出的內容，以及（如果已知）實際發送給客戶的內容。
模式
單一 — 上述工作流程。
批次 — 適用於規格、史詩或待辦事項：執行步驟 0-2 一次，然後對每個項目執行步驟 3-7（每個項目 2-5 個子任務）。輸出一個表格（項目、層級、工時範圍、規模、信心水準、主要風險）、共享假設、跨項目依賴關係、建議的順序，以及一次性適用於整個批次的不會縮減固定開銷（當它們確實是共享時：一次部署 + 一次 uSync 匯入可以承載多個項目；每個頁面一次 QA 波次，而不是每個項目一次）。
重新估算 — 在客戶回答問題或範圍變更後：僅顯示差異（移除的行、新增的行、修訂後的總數、導致變化的問題）。客戶回答問題後要求確認數字——讓差異易於核准。
審查 — 當估算已存在（在規格、計畫、工單評論中）且你被要求檢查時：不要從頭開始重新估算。遵循 references/review-checklist.md：
- 收集每個版本：已提交的文件、給客戶的副本、它引用的程式碼；
- 檢查算術，然後檢查基礎和信心水準是否符合誠信規則；
- 檢查結構（審查份額、固定開銷、需求涵蓋範圍、選項、預設值）；
- 在程式碼和架構中重新驗證關鍵事實，並尋找它遺漏的平台風險。
區分內部修正和客戶必須看到的變更。僅當數字變更時才建議重新發佈數字。
校準 — 當被要求評估估算的準確性時（「我們有多準確」、「校準此技能」、「估算回顧」），或在試用期結束時：
- 讀取整個校準日誌。對於每個已關閉的條目，填寫或檢查實際數據及其來源（自己的時間、工單工作記錄——注意是否為團隊總計——、git 活躍天數）；對於遺失的實際數據，要求提供而不是猜測。
- 針對每個工作類型和固定開銷，計算發送給客戶的數字和技能數字的比率。
- 找出系統性的誤差：哪些工作類型、哪些固定開銷（QA 波次、交付開銷、驗證輪次、澄清）、哪些規則（信心水準、小型工單下限）是錯誤的，以及人類的覆蓋在哪裡是正確的。
- 提出對
references/calibration.md、patterns.md、platform-risks.md或規則的具體修改建議，每個修改都需與證明其合理性的日誌行相關聯。對於一個類型的數據點少於約 3 個：註記，不要變更。 - 僅套用使用者核准的修改，在技能的 README 中新增一個帶有日期的變更日誌條目，並在日誌中新增一行，說明下一個估算使用哪次校準。
調查 — 適用於「找出原因…」的工單：設定時間盒（通常為 0.25-1 小時），說明時間盒能換取什麼，並列出可能的結果，包括「非錯誤」、「已內建」和「上游 CMS 錯誤 — 等待 X 版本」。這些結果很常見且成本低；不要將調查當作修復已確定的情況來定價。