OpenSpec 項目實戰（五）｜UI 視覺打磨 + 改 template 讓 AI 寫出規範任務

術哥發現前四期 tasks.md 嘅格式全部都用 ## 1. 開頭，而唔係 instruction 要求嘅 ### 任務 N：。即使 instruction 寫明「必須嚴格遵守」，AI 都冇一次遵守。

根因係 template 嘅優先級高過 instruction：LLM 會將 template 當作具體格式示例，而 instruction 只係補充說明。

舊 template 用 ## 1. 格式，AI 就跟住出 ## 1.。呢個唔係偶然，而係系統性問題。

4 期文章、4 個不同 change、幾十個任務，冇一個出 ### 任務 N 格式。

LLM 面對 template 同 instruction 時，會先睇 template 嘅格式示例，然後先睇 instruction 嘅文字描述。

術哥直接修改 openspec/schemas/with-review/templates/tasks.md，將標題從 ## 1. 改做 ### 任務 1：，加上「涉及文件」列表，每步跟 TDD 五步結構。

### 任務 1：<!-- Task Group Name -->
**涉及文件：**
- 新建/修改：exact/path/to/file
- 測試：tests/exact/path/to/test
- [ ] 1.1 **寫失敗測試**
```typescript
// test code here
```
- [ ] 1.2 **運行測試——確認失敗**
命令：`npx vitest run tests/path/test.ts`
預期：FAIL
- [ ] 1.3 **寫最小實現**
```typescript
// implementation code here
```
- [ ] 1.4 **運行測試——確認通過**
命令：`npx vitest run tests/path/test.ts`
預期：PASS
- [ ] 1.5 **提交**
```bash
git add path/to/files
git commit -m "feat: description"
```

今期 ui-visual-polish 係第一次驗證。AI 生成嘅任務開頭變咗「### 任務 1：安裝 lucide-react + 重建 tokens.css 配色」，後續仲有涉及文件同代碼塊，格式完全正確。

改 template 確實有效，格式問題一次解決。

新 template 令 AI 自然輸出涉及文件列表同代碼塊，歷史首次。

對比改造前嘅 ## 1. 格式，新 template 令輸出脱胎換骨。

視覺升級方面，品牌色由 Tailwind 默認藍轉做藍紫（#8B5CF6），用 Lucide 圖標系統，分類各有專屬圖標，Badge 用 Beaker 同 ClipboardList。

Apply 過程有33步，出現三個小插曲：Flask 圖標唔存在，AI 自動改用 Beaker；index.css 意外被覆蓋，AI 自己補返；NotFound.tsx 無需修改，因為用 CSS 變量自動跟隨。

AI 嘅自適應同自我修復能力令執行過程更順暢，係純腳本自動化做唔到嘅。

CSS 變量體系令換色變成改一行值嘅事，之前嘅投資回報顯現。

Badge 從純文字變成圖標+文字，更加專業。

今期最重要嘅發現係：template 管格式，instruction 管內容，兩者要對齊。改 template 係解決格式問題嘅正確手段，而改 instruction 隻影響內容質量。

呢個結論唔單止適用於 OpenSpec，對任何 prompt+template 模式嘅 AI 工具都有啟發。

改 instruction 佔 20% 投入獲 80% 質量提升，但那 80% 嘅質量提升裏可能有結構性缺陷。

另外，視覺類變更難以嚴格執行 TDD 五步，實際更接近回歸測試模式。呢個係正常現象，唔需要強求。