python-plan-optimization

python-plan-optimization 技能提供了一套嚴謹的 6 階段唯讀分析工作流程，專門用於評估嵌入在 Markdown 設計文件中的 Python 程式碼區塊。此工具適合軟體工程師、架構師和技術主管，協助他們在實作前確保設計文件符合行業最佳實踐（如 SOLID、DRY、KISS 和 YAGNI）。透過處理一份或多份文件，該代理程式能生成詳細報告，指出設計原則違規、程式碼異味 (code smells)，以及採用現代 Python 功能（如型別提示和 dataclasses）的改進機會。

• 多階段分析管線：在 6 個不同階段進行系統性的發現、評估與驗證。
• 情境感知閾值：根據專案成熟度等級（POC、MVP、Private、Enterprise 和 Open Source）調整敏感度和分析深度。
• 嚴格的唯讀執行：在不修改原始檔案的前提下運作，確保文件的完整性，同時提供可行的建議。
• 架構合規性檢查：根據明確的專案決策、選定的工具和架構理由，對擬議的程式碼進行驗證。
• 實證驗證：要求針對第三方 API 聲明進行 WebSearch，並透過周圍情境檢查驗證邏輯，有效減少誤報。

使用注意事項與限制包括：

• 請確保提供專案類型情境（例如透過前置的判定技能），以便配置正確的報告嚴重程度與深度。
• 工具要求所有發現都必須附帶精確的程式碼引用；若無法驗證程式碼邏輯或引用不足，分析將會失敗。
• 工具會刻意忽略 # TODO 或存根實作，專注於結構和模式導向的分析。
• 輸出結構為專業分析報告而非程式碼修改，旨在作為設計階段的諮詢層。
• 開發人員應注意，在開源模式下，代理程式會強制進行額外的公開 API 文件檢查與型別標註覆蓋率驗證。
• 該代理程式作為分析護欄，可防止推薦尚未發布的 Python 特性或可能導致架構負債的過時資料快取模式。