system-dev-template/docs/why.md

為什麼需要這個模板

CC 是個優秀的工程師，但不是個好的專案經理

Claude Code 執行力強、速度快。小專案裡這是優點，大專案裡變成問題：

問題一：改這個壞那個 CC 沒有全局觀。它在每個 session 裡從零開始，不知道上次做了什麼、哪些東西不能動、 為什麼做了這個決定。結果就是：修了 A，壞了 B，下次又把 B 修回來，再壞了 A。

問題二：文件越來越亂，記憶不可靠 隨著開發，對話裡累積了大量決策、踩坑記錄、架構說明。但這些知識：

• 存在對話歷史裡，新 session 全部消失
• 就算寫成文件，散落在根目錄、各種 md 裡，CC 找不到
• 即使找到了，是給人看的語言，不是給 LLM 的格式

最後的結果：你變成那個唯一的記憶。你要重複解釋同樣的事， CC 要重複犯同樣的錯。

---

兩套系統，解決兩個問題

SDD 系統：給 CC 全局觀

靈感來自 Kiro 的做法。核心原則只有一條：動手前必須有設計文件。

使用者提需求
    ↓
CC 找對應 SDD（docs/3-specs/[子系統]/design.md）
    ↓
找到 → 讀 design.md + tasks.md，宣告範圍再動手
找不到 → 停手問使用者，不自行猜測

SDD 強制 CC 在動手前先思考：這個修改影響哪些地方？有沒有超出範圍？ 有沒有違反既定的技術限制？

LLM Wiki：給 CC 可累積的記憶

靈感來自 Andrej Karpathy 的 LLM Wiki 概念——不用 embedding， 只靠 pre-compile 把知識整理成 LLM 友善的格式。

雙空間設計：

• docs/：人寫的原始文件，依照開發生命週期分類
• system-dev/wiki/：CC 整理的 LLM 友善知識，每次 session 累積

每次 session 開始，CC 讀 wiki，不需要重新學習。 每次 session 結束，CC 更新 wiki，知識不再消失。

---

設計原則

疊加，不覆蓋 接入已有專案時，現有的規範、文件、CLAUDE.md 全部保留， 新系統疊加上去，不破壞已有的東西。

結構即協議 固定的目錄結構讓 CC 和你共用同一套分類規則。 你把任何文件丟進來，CC 知道要收到哪裡。

CLAUDE.md 不增長 CLAUDE.md 是導航牌，不是內容倉庫。超過 100 行就是架構出問題， 不是加更多內容的信號。

對話結論必須 capture 最重要的知識往往在對話裡，不在文件裡。 /wiki-capture 解決這個問題：討論完當場存，知識不再隨對話消失。