Appearance
Claude Code 開發規則
核心框架：PIV
每次任務必須遵循 Planning → Implementation → Validation 流程。
Planning（規劃）
在開始寫任何程式碼之前：
- 確認需求：如果指令模糊，先詢問釐清，不要自行猜測
- 明確範圍：確認輸入、輸出、邊界條件
- 拆解任務：大任務拆成小步驟，逐步執行
- 說明計畫：開始前簡述你打算怎麼做，讓使用者確認
Implementation（實作）
執行時遵守以下原則：
- 一次只做一件事：每次只實作一個功能或修改一個檔案
- 保持簡單：用最直接的方式解決問題
- 不做沒被要求的事：不預留擴展、不加額外功能
- 遵循專案慣例：觀察現有程式碼風格並保持一致
Validation（驗證）
完成後必須驗證：
- 執行測試：如果有測試，執行並確認通過
- 展示結果：顯示相關的
git diff或執行結果 - 總結變更：簡述這次改了什麼
三大黃金法則
1. Small Steps（小步迭代）
✅ 正確做法：
- 一個 prompt 完成一個小功能
- 完成後等待確認再繼續
- 每個步驟都可獨立驗證
❌ 避免：
- 一次改動多個不相關的檔案
- 未經確認就連續執行多個大改動
- 產生難以審查的大量變更2. TDD / Test First（測試先行）
當使用者要求新功能時：
建議流程：
1. 先詢問：「要我先寫測試案例嗎？」
2. 若同意，先寫測試，確認測試案例正確
3. 再實作程式碼讓測試通過
4. 執行測試驗證結果若專案已有測試：
- 修改程式碼後主動執行相關測試
- 新增功能時建議補上對應測試
3. YAGNI（不做不需要的事）
✅ 只做：
- 使用者明確要求的功能
- 當前需要的最簡實作
❌ 不要：
- 預留「未來可能用到」的介面
- 加入未被要求的錯誤處理或功能
- 過度抽象或設計模式
- 自作主張的「優化」或「改進」溝通規則
開始任務前
- 如果需求不清楚，先提問
- 說明你理解的任務範圍，請使用者確認
- 若任務較大，提出拆解建議
執行過程中
- 遇到需要決策的地方，暫停詢問
- 發現潛在問題，提出但不擅自處理
- 保持進度透明，讓使用者知道你在做什麼
完成任務後
- 簡潔總結完成了什麼
- 展示驗證結果（測試、執行輸出等）
- 不要冗長解釋，使用者會自己看程式碼
程式碼風格
通用原則
- 變數和函數命名要有意義
- 保持函數簡短，單一職責
- 註解解釋「為什麼」，而非「做什麼」
- 遵循專案現有的命名和格式慣例
錯誤處理
- 只處理預期內的錯誤情況
- 不要過度防禦性編程
- 錯誤訊息要有幫助性
Git 操作
Commit 規範
- 使用有意義的 commit message
- 格式：
type: brief description - 類型：
feat,fix,refactor,test,docs,chore
操作原則
- 改動前確認當前分支
- 大改動前建議先 commit 現有進度
- 不確定的操作先詢問
禁止事項
- 不要在未告知的情況下刪除檔案或程式碼
- 不要修改使用者沒提到的檔案
- 不要安裝未經同意的套件
- 不要執行可能有破壞性的指令（如
rm -rf） - 不要在程式碼中留下
TODO或未完成的部分而不說明
文章上架指令
當使用者說「把 xxx.md 上架到 xx 類別」時，自動執行以下步驟：
類別對應
| 類別 | 目錄 | 索引頁 |
|---|---|---|
| AI | docs/ai/ | docs/ai/index.md |
| 機器人 / robot | docs/robot/ | docs/robot/index.md |
| 專案 / project | docs/project/ | docs/project/index.md |
上架步驟（自動執行）
- 讀取文章：讀取指定的
.md文件，提取標題（第一個#開頭的行） - 確認文章位置：確保文章已在正確的分類目錄下（如
docs/ai/xxx.md） - 更新分類索引頁：在
docs/{分類}/index.md的## Recent Posts下方第一行加入連結 - 更新側邊欄：在
docs/.vitepress/config.ts對應分類的 sidebar items 中，Index 之後加入文章 - 更新首頁：在
docs/index.md的## 📝 最新文章區塊最上方加入文章（需提供日期和摘要） - 本地預覽驗證：執行
npm run build確認無錯誤
上架格式範例
分類索引頁格式：
markdown
- [文章標題](./文章檔名)側邊欄格式：
typescript
{ text: '文章標題', link: '/分類/文章檔名' }首頁格式：
markdown
### [文章標題](/分類/文章檔名)
**分類標籤** · YYYY-MM-DD
文章摘要（1-2 句話）
---注意事項
- 首頁最新文章區塊只保留最新 5 篇，超過的移除
- 日期格式統一使用
YYYY-MM-DD - 分類標籤使用：
AI、機器人、專案 - 若使用者未提供日期和摘要，需詢問
口訣
PIV 打底，小步走，測試領，不貪多。
- Planning：想清楚再動手
- Implementation：一次一小步
- Validation：驗證後才算完成
- Small Steps：小步迭代好追蹤
- TDD：測試先行有保障
- YAGNI：不做多餘的事