| name | tsinswreng-design-before-coding |
| description | 在需求分析之後 編碼實現之前 閱讀此skill |
核心原則
任何代碼修改都必須遵循: 先設計、後實現。
設計階段與實現階段必須嚴格分離:
- 設計階段: 給出多種設計方案、分析優缺點。不寫代碼
- 實現階段: 用戶選定方案後、嚴格按方案實現
禁止在沒有經過設計階段的情況下直接寫實現代碼!
前置依賴
如果本次任務的需求還不夠明確、尚未經過充分的需求分析、 必須尋找需求分析相關skill做需求分析、 拿到用戶確認的需求確認單後、再回到本skill 進入設計階段。
本skill 假設輸入的需求已經是明確的、經過確認的。 如果你發現需求中有模糊不清的地方、也要先回去做需求分析。
通用架構規範
SOLID原則
- S 單一職責: 一個類/模塊只應有一個引起它變化的原因
- O 開閉原則: 對擴展開放、對修改關閉。新增功能應通過擴展而非修改已有代碼實現
- L 里氏替換: 子類必須能夠完全替換其基類
- I 接口隔離: 不應強迫客戶端依賴它們不使用的方法。接口要小而精
- D 依賴反轉: 高層模塊不應依賴低層模塊、二者都應依賴抽象。抽象不應依賴細節、細節應依賴抽象
設計原則
- 優先使用接口(
interface)做抽象、而非類繼承。類繼承僅用作代碼複用手段
- 高內聚、低耦合。相關功能聚合在一起、不相關的功能之間通過明確的接口通信
- 一個函數不超過50行、超過則考慮拆分成子函數
- 函數參數過多時應建立專門的DTO/參數對象
- 禁止字符串硬編碼鍵名。禁止魔法字符串、魔法數字。多用
nameof/枚舉
- 注意代碼複用、發現重複邏輯時抽取公共方法/類
- 考慮可擴展性: 寫代碼時要問自己“如果將來需求變了、這個設計能方便地擴展嗎?”
- 考慮可測試性: 模塊之間應能獨立測試、依賴應可mock
- 考慮性能 考慮時間複雜度和空間複雜度 能流式處理的就不要全部加載進內存
禁止的偷懶做法
寫代碼要考慮全局最優 要考慮長遠的可維護性 可擴展性、不能圖省事搞局部最優。
以下做法屬於“局部最省事”的反模式、嚴格禁止:
- 爲了一時方便而破壞已有的抽象分層。例如在業務層直接操作數據庫連接、繞過Repository層
- 爲了“快”而複製粘貼代碼、造成重複邏輯
- 把不相關的邏輯塞進一個巨大的類/文件中
編寫代碼時的自我檢查
每次寫代碼時、必須在腦中檢查以下問題:
- 是否已經充分理解了需求
- 這段代碼放在當前位置是否合理? 是否符合分層架構?
- 是否引入了不必要的耦合?
- 如果將來需求變化、這個設計能否方便擴展?
- 是否有重複代碼可以抽取?
- 新增的類/方法是否有明確的單一職責?
- 是否依賴了具體實現而非抽象?
- 這個改動會不會對其他模塊產生意想不到的影響?
設計階段規範
何時需要進入設計階段
以下情況必須先進行設計、不能直接寫代碼:
- 新增一個類/接口/模塊
- 修改現有代碼的對外接口或行爲
- 重構現有代碼
- 修改涉及多個文件或模塊
- 需要做技術選型(選用哪種模式/框架/庫)
以下情況可以跳過設計階段:
- 修復一個明確的、範圍限於單一函數內的bug(如空指針、邏輯錯誤)
- 修改註釋/文檔
- 用戶已給出極其詳細的實現指令且說明了原因
設計方案的格式
每個設計方案必須包含以下內容:
- 方案概述: 一兩句話說明整體思路
- 涉及的文件/模塊: 列出需要新建/修改的文件
- 核心類/接口設計: 關鍵的類型定義、接口聲明、類關係
- 數據流/調用流: 關鍵的調用鏈路或數據流向
- 優點: 這個方案好在哪裏
- 缺點/風險: 有什麼代價或潛在問題
- 對現有代碼的影響: 會改動哪些已有代碼、是否破壞向後兼容
最好能給出多種方案供用戶選擇。
方案之間應有明確的差異點(不同的抽象方式/不同的分層策略/不同的技術路線)、 不能只是“方案A用一個類、方案B用兩個類”這種表面差異。
對每個方案給出你的推薦度和理由。
設計時的考量維度
設計方案時必須從以下維度進行考量:
- 可維護性: 代碼是否易於理解和修改
- 可擴展性: 未來需求變化時改動成本如何
- 可測試性: 各模塊能否獨立測試
- 性能: 是否有明顯的性能隱患
- 複用性: 設計中的組件能否在其他場景中複用
- 一致性: 是否與項目現有架構風格保持一致
實現階段規範
- 用戶選定方案後、嚴格按照方案實現、不得偏離
- 實現過程中若發現方案有問題、必須停下來重新進入設計階段、不能自作主張改方案
- 實現時必須遵守本skill中的架構規範
- 實現完成後、主動說明實現了哪些文件/類/方法、與設計方案是否一致
遇到疑問時
設計或實現過程中遇到任何不確定之處、必須立即停止並向用戶確認。包括:
- 對需求理解有疑義
- 發現現有架構設計存在問題
- 方案中的某個點你覺得不合適但拿不準
- 現有代碼中有不合理之處(即使與當前任務無關)
提問時要附上自己想的幾種可能回答/方案、方便用戶快速選擇。
