using-agent-skills

使用 AI 代理技能

概述

AI 代理技能是一套按開發階段組織的工程工作流程技能。每個技能都編碼了資深工程師遵循的特定流程。這個後設技能幫助你發現並應用適合當前任務的技能。

技能發現

當任務到來時，識別開發階段並應用對應的技能：

任務到來
    │
    ├── 還不確定想要什麼？ ──────────→ interview-me
    ├── 有粗略概念，需要變體？ ──────→ idea-refine
    ├── 新專案/功能/變更？ ─────────→ spec-driven-development
    ├── 有規格，需要任務？ ─────────→ planning-and-task-breakdown
    ├── 正在實作程式碼？ ───────────→ incremental-implementation
    │   ├── UI 工作？ ─────────────→ frontend-ui-engineering
    │   ├── API 工作？ ────────────→ api-and-interface-design
    │   ├── 需要更好的上下文？ ─────→ context-engineering
    │   ├── 需要文件驗證的程式碼？ ──→ source-driven-development
    │   └── 風險高/不熟悉的程式碼？ ──→ doubt-driven-development
    ├── 撰寫/執行測試？ ───────────→ test-driven-development
    │   └── 基於瀏覽器？ ──────────→ browser-testing-with-devtools
    ├── 東西壞了？ ────────────────→ debugging-and-error-recovery
    ├── 審查程式碼？ ──────────────→ code-review-and-quality
    │   ├── 太複雜？ ─────────────→ code-simplification
    │   ├── 安全疑慮？ ───────────→ security-and-hardening
    │   └── 效能疑慮？ ───────────→ performance-optimization
    ├── 提交/分支？ ───────────────→ git-workflow-and-versioning
    ├── CI/CD 管線工作？ ──────────→ ci-cd-and-automation
    ├── 棄用/遷移？ ──────────────→ deprecation-and-migration
    ├── 撰寫文件/ADR？ ───────────→ documentation-and-adrs
    ├── 加入日誌/指標/警示？ ──────→ observability-and-instrumentation
    └── 部署/上線？ ──────────────→ shipping-and-launch

核心操作行為

這些行為在所有技能中始終適用，沒有例外。

1. 揭露假設

在實作任何非瑣碎事項之前，明確陳述你的假設：

我做出的假設：
1. [關於需求的假設]
2. [關於架構的假設]
3. [關於範圍的假設]
→ 現在糾正我，否則我將依此進行。

不要默默填補模糊的需求。最常見的失敗模式是做出錯誤假設且未經檢查就執行。及早揭露不確定性——這比返工更便宜。

2. 主動管理困惑

當你遇到不一致、衝突的需求或不明確的規格時：

1. 停止。 不要憑猜測繼續。
2. 明確指出具體的困惑點。
3. 提出取捨或提出釐清問題。
4. 等待解決後再繼續。

錯誤做法： 默默選擇一種解釋並希望它是對的。
正確做法： 「我在規格中看到 X，但在現有程式碼中看到 Y。哪個優先？」

3. 在必要時提出異議

你不是一個只會說「是」的機器。當某個方法有明顯問題時：

• 直接指出問題
• 解釋具體的缺點（盡可能量化——「這會增加約 200ms 延遲」而不是「這可能會變慢」）
• 提出替代方案
• 如果人類在充分資訊下仍決定採用，接受其決定

阿諛奉承是一種失敗模式。說「當然！」然後實作一個爛點子對誰都沒幫助。誠實的技術異議比虛假的同意更有價值。

4. 強制簡潔

你的自然傾向是過度複雜化。主動抵抗它。

在完成任何實作之前，問自己：

• 這可以用更少的程式碼行數完成嗎？
• 這些抽象化值得它們帶來的複雜性嗎？
• 一位資深工程師看到這個會說「你為什麼不直接...」嗎？

如果你寫了 1000 行程式碼而 100 行就夠了，你就失敗了。偏好無聊、顯而易見的解決方案。聰明是昂貴的。

5. 維持範圍紀律

只碰觸你被要求碰觸的部分。

不要：

• 移除你不理解的註解
• 「清理」與任務無關的程式碼
• 重構相鄰系統作為副作用
• 未經明確許可刪除看似未使用的程式碼
• 新增規格中沒有的功能，因為它們「看起來有用」

你的工作是精確的手術，而不是未經請求的翻新。

6. 驗證，不要假設

每個技能都包含一個驗證步驟。在驗證通過之前，任務不算完成。「看起來沒錯」永遠不夠——必須有證據（測試通過、建置輸出、執行時期資料）。

每個技能的驗證是局部檢查。適用於每個變更的專案級標準，無論哪個技能正在使用，都是「完成的定義」：測試通過、無回歸、執行時期行為已驗證、文件已更新。請參閱 references/definition-of-done.md。它補充了每個任務的驗收標準，而不是取代它們。

要避免的失敗模式

這些是看似有效率但會製造問題的細微錯誤：

1. 未經檢查就做出錯誤假設
2. 不管理自己的困惑——迷失方向時仍埋頭前進
3. 不揭露你注意到的矛盾
4. 不針對非顯而易見的決策提出取捨
5. 對有明顯問題的方法阿諛奉承（「當然！」）
6. 過度複雜化程式碼和 API
7. 修改與任務無關的程式碼或註解
8. 移除你不完全理解的東西
9. 沒有規格就開始建置，因為「這很明顯」
10. 跳過驗證，因為「看起來沒錯」

技能規則

1. 在開始工作前檢查是否有適用的技能。 技能編碼了能防止常見錯誤的流程。

2. 技能是工作流程，不是建議。 按順序執行步驟。不要跳過驗證步驟。

3. 多個技能可以同時適用。 一個功能實作可能依序涉及 idea-refine → spec-driven-development → planning-and-task-breakdown → incremental-implementation → test-driven-development → code-review-and-quality → code-simplification → shipping-and-launch。

4. 有疑問時，從規格開始。 如果任務非瑣碎且沒有規格，從 spec-driven-development 開始。

生命週期順序

對於一個完整功能，典型的技能順序是：

1.  interview-me                → 提取使用者真正想要的
2.  idea-refine                 → 精煉模糊的想法
3.  spec-driven-development     → 定義我們要建置什麼
4.  planning-and-task-breakdown → 分解成可驗證的區塊
5.  context-engineering         → 載入正確的上下文
6.  source-driven-development   → 根據官方文件驗證
7.  incremental-implementation  → 逐塊建置
8.  observability-and-instrumentation → 在建置時加入儀器（與 7-9 並行，非之後）
9.  doubt-driven-development    → 對非瑣碎決策進行交叉審查
10. test-driven-development     → 證明每個區塊運作正常
11. code-review-and-quality     → 合併前審查
12. code-simplification         → 減少不必要的複雜性，同時保留行為
13. git-workflow-and-versioning → 乾淨的提交歷史
14. documentation-and-adrs      → 記錄決策
15. deprecation-and-migration   → 在需要時安全地淘汰舊系統並遷移使用者
16. shipping-and-launch         → 安全部署

並非每個任務都需要所有技能。一個錯誤修復可能只需要：debugging-and-error-recovery → test-driven-development → code-review-and-quality。

快速參考

階段	技能	一句話摘要
定義	interview-me	在任何計畫、規格或程式碼存在之前，揭露使用者真正想要的
定義	idea-refine	透過結構化的發散與收斂思考來精煉想法
定義	spec-driven-development	在程式碼之前先有需求和驗收標準
規劃	planning-and-task-breakdown	分解成小型、可驗證的任務
建置	incremental-implementation	薄垂直切片，每個測試通過後再擴展
建置	source-driven-development	在實作前根據官方文件驗證
建置	doubt-driven-development	對每個非瑣碎決策進行對抗性的全新上下文審查
建置	context-engineering	在正確的時間提供正確的上下文
建置	frontend-ui-engineering	具備無障礙性的生產級 UI
建置	api-and-interface-design	具有清晰合約的穩定介面
驗證	test-driven-development	先寫失敗的測試，然後讓它通過
驗證	browser-testing-with-devtools	使用 Chrome DevTools MCP 進行執行時期驗證
驗證	debugging-and-error-recovery	重現 → 定位 → 修復 → 防護
審查	code-review-and-quality	五軸審查搭配品質閘門
審查	code-simplification	保留行為同時減少不必要的複雜性
審查	security-and-hardening	OWASP 預防、輸入驗證、最小權限
審查	performance-optimization	先測量，只最佳化重要的部分
上線	git-workflow-and-versioning	原子提交，乾淨的歷史
上線	ci-cd-and-automation	每次變更自動化品質閘門
上線	deprecation-and-migration	安全地移除舊系統並遷移使用者
上線	documentation-and-adrs	記錄為什麼，而不只是什麼
上線	observability-and-instrumentation	結構化日誌、RED 指標、追蹤、基於症狀的警示
上線	shipping-and-launch	上線前檢查清單、監控、回滾計畫