tsinswreng-design-before-coding

name	tsinswreng-design-before-coding
description	在需求分析之後 編碼實現之前 閱讀此skill

核心原則

任何代碼修改都必須遵循: 先設計、後實現。

設計階段與實現階段必須嚴格分離:

• 設計階段: 給出多種設計方案、分析優缺點。不寫代碼
• 實現階段: 用戶選定方案後、嚴格按方案實現

禁止在沒有經過設計階段的情況下直接寫實現代碼!

前置依賴

如果本次任務的需求還不夠明確、尚未經過充分的需求分析、 必須尋找需求分析相關skill做需求分析、 拿到用戶確認的需求確認單後、再回到本skill 進入設計階段。

本skill 假設輸入的需求已經是明確的、經過確認的。 如果你發現需求中有模糊不清的地方、也要先回去做需求分析。

通用架構規範

SOLID原則

• S 單一職責: 一個類/模塊只應有一個引起它變化的原因
• O 開閉原則: 對擴展開放、對修改關閉。新增功能應通過擴展而非修改已有代碼實現
• L 里氏替換: 子類必須能夠完全替換其基類
• I 接口隔離: 不應強迫客戶端依賴它們不使用的方法。接口要小而精
• D 依賴反轉: 高層模塊不應依賴低層模塊、二者都應依賴抽象。抽象不應依賴細節、細節應依賴抽象

設計原則

• 優先使用接口(interface)做抽象、而非類繼承。類繼承僅用作代碼複用手段
• 高內聚、低耦合。相關功能聚合在一起、不相關的功能之間通過明確的接口通信
• 一個函數不超過50行、超過則考慮拆分成子函數
• 函數參數過多時應建立專門的DTO/參數對象
• 禁止字符串硬編碼鍵名。禁止魔法字符串、魔法數字。多用nameof/枚舉
• 注意代碼複用、發現重複邏輯時抽取公共方法/類
• 考慮可擴展性: 寫代碼時要問自己“如果將來需求變了、這個設計能方便地擴展嗎?”
• 考慮可測試性: 模塊之間應能獨立測試、依賴應可mock
• 考慮性能 考慮時間複雜度和空間複雜度 能流式處理的就不要全部加載進內存

禁止的偷懶做法

寫代碼要考慮全局最優 要考慮長遠的可維護性 可擴展性、不能圖省事搞局部最優。

以下做法屬於“局部最省事”的反模式、嚴格禁止:

• 爲了一時方便而破壞已有的抽象分層。例如在業務層直接操作數據庫連接、繞過Repository層
• 爲了“快”而複製粘貼代碼、造成重複邏輯
• 把不相關的邏輯塞進一個巨大的類/文件中

編寫代碼時的自我檢查

每次寫代碼時、必須在腦中檢查以下問題:

1. 是否已經充分理解了需求
2. 這段代碼放在當前位置是否合理? 是否符合分層架構?
3. 是否引入了不必要的耦合?
4. 如果將來需求變化、這個設計能否方便擴展?
5. 是否有重複代碼可以抽取?
6. 新增的類/方法是否有明確的單一職責?
7. 是否依賴了具體實現而非抽象?
8. 這個改動會不會對其他模塊產生意想不到的影響?

設計階段規範

何時需要進入設計階段

以下情況必須先進行設計、不能直接寫代碼:

• 新增一個類/接口/模塊
• 修改現有代碼的對外接口或行爲
• 重構現有代碼
• 修改涉及多個文件或模塊
• 需要做技術選型(選用哪種模式/框架/庫)

以下情況可以跳過設計階段:

• 修復一個明確的、範圍限於單一函數內的bug(如空指針、邏輯錯誤)
• 修改註釋/文檔
• 用戶已給出極其詳細的實現指令且說明了原因

設計方案的格式

每個設計方案必須包含以下內容:

1. 方案概述: 一兩句話說明整體思路
2. 涉及的文件/模塊: 列出需要新建/修改的文件
3. 核心類/接口設計: 關鍵的類型定義、接口聲明、類關係
4. 數據流/調用流: 關鍵的調用鏈路或數據流向
5. 優點: 這個方案好在哪裏
6. 缺點/風險: 有什麼代價或潛在問題
7. 對現有代碼的影響: 會改動哪些已有代碼、是否破壞向後兼容

最好能給出多種方案供用戶選擇。

方案之間應有明確的差異點(不同的抽象方式/不同的分層策略/不同的技術路線)、 不能只是“方案A用一個類、方案B用兩個類”這種表面差異。

對每個方案給出你的推薦度和理由。

設計時的考量維度

設計方案時必須從以下維度進行考量:

• 可維護性: 代碼是否易於理解和修改
• 可擴展性: 未來需求變化時改動成本如何
• 可測試性: 各模塊能否獨立測試
• 性能: 是否有明顯的性能隱患
• 複用性: 設計中的組件能否在其他場景中複用
• 一致性: 是否與項目現有架構風格保持一致

實現階段規範

• 用戶選定方案後、嚴格按照方案實現、不得偏離
• 實現過程中若發現方案有問題、必須停下來重新進入設計階段、不能自作主張改方案
• 實現時必須遵守本skill中的架構規範
• 實現完成後、主動說明實現了哪些文件/類/方法、與設計方案是否一致

遇到疑問時

設計或實現過程中遇到任何不確定之處、必須立即停止並向用戶確認。包括:

• 對需求理解有疑義
• 發現現有架構設計存在問題
• 方案中的某個點你覺得不合適但拿不準
• 現有代碼中有不合理之處(即使與當前任務無關)

提問時要附上自己想的幾種可能回答/方案、方便用戶快速選擇。