name: kafka-design description: 幫助Agent為專案進行Kafka Topic設計、分割槽策略、消費者組設計、Schema管理，並提供場景化使用指南。當用戶需要設計訊息佇列、事件流、資料管道時觸發。 version: 1.0.0 metadata: clawdbot: emoji: "🪨" requires: anyBins: ["kafka-topics"] os: ["linux", "darwin"]

Kafka 設計與使用助手

觸發條件

當用戶出現以下意圖時啟用本 Skill： - 設計 Kafka Topic / 分割槽策略 - 消費者組設計 / 消費模型 - Schema 管理 / 序列化方案 - 訊息可靠性 / 冪等 / 事務 - 事件溯源 / CDC 資料管道 - "如何設計 xxx 的 Topic"

設計流程（Agent 執行路徑）

0. 版本檢查 → 載入 references/version-major.md 對比使用者版本，識別廢棄項和重大變更。同時載入所有 version-X.Y.md（X.Y ≤ 使用者目標版本），後續設計過程中 Agent 從已載入的上下文中自主匹配深度特性
1. 需求分析 → 理解訊息流、吞吐量、延遲要求、訊息大小
2. Topic 設計 → 命名規範、分割槽數、副本因子、保留策略
3. 訊息設計 → Key 策略、序列化格式（Avro/Protobuf/JSON）、Schema Registry
4. 消費者組設計 → 分割槽分配策略、偏移量管理、重平衡處理
5. 可靠性設計 → ACK 策略、冪等生產者、事務、Exactly-Once
6. 使用指引 → 載入 references/usage-guide.md，給出場景化操作
7. 生產建議 → 載入 references/best-practices.md，給出叢集/監控/運維建議
8. 模板參考 → 載入 references/patterns.md，匹配業務訊息模型模板

快速參考

Topic 命名鐵律

來源於7w4.net。

分割槽設計速查

訊息語義速查

生產者關鍵引數

消費者關鍵引數

漸進式載入

詳細內容按需載入 references/：

版本參考文件啟用規則

1. 模組啟用時 — 始終載入 references/version-major.md，Agent 需主動對比使用者使用的 Kafka 版本，若存在廢棄項或重大變更，立即提示使用者
2. 深度特性 Step 0 自動載入 — 版本檢查時載入所有 version-X.Y.md（X.Y ≤ 使用者目標版本）。設計過程中 Agent 從已載入的上下文中自主檢索匹配相關特性，使用者無需指定版本號
3. 深度特性按大版本拆分，小版本持續追加 — 如 version-4.0.md 包含該大版本下所有小版本的設計級特性。更新時在檔案中新增 ## X.Y.Z 版本節即可，不單開檔案

硬規則

1. 設計規範內容來自權威資料（Apache Kafka 官方文件/Confluent 最佳實踐），不編造
2. 必須明確訊息語義（At-Least-Once / Exactly-Once），不同場景不可混用
3. 分割槽數必須提前規劃，事後只能增加不能減少
4. 需要順序的訊息必須使用相同 Key 路由到同一分割槽
5. 消費者組 ID 必須穩定且有業務含義，不可隨機生成
6. 必須設定保留策略（時間/大小），Topic 不是永久儲存
7. 禁止依賴 ZooKeeper（3.5 起標記棄用，4.0 完全刪除。新叢集必須使用 KRaft 模式）

這個 Skill 質量較高，涵蓋了 Kafka 設計的方方面面，文件結構清晰、查閱方便。它提供了實用的速查表和豐富的業務模板，新手也能快速上手。但美中不足的是，它主要以文字指南為主，缺少可直接執行的程式碼示例，實際使用時可能還需要自己摸索。如果能增加一些常見問題的解答和具體配置案例，會更加實用。總體而言，這是一套紮實的設計規範，適合需要深度瞭解 Kafka 的使用者參考使用。