這是一個 Claude Code skill,用於指導 Agent 遵循數據分析後端的架構設計原則和開發流程。
# 1. 複製到 Claude Code skills 目錄
# Windows (PowerShell)
xcopy /E /I . "$env:USERPROFILE\.claude\skills\data-analysis-backend"
# macOS/Linux
cp -r . ~/.claude/skills/data-analysis-backend
# 2. 重啟 Claude Code
# 3. 測試 skill
# 在 Claude Code 中問: "幫我新增一個數據分析 endpoint"安裝後，嘗試以下任務來體驗 skill:
-
新增 Endpoint
幫我實作一個按渠道分析收入的 endpointAgent 會遵循 8-step pipeline 建立完整的 endpoint
-
新增 Aggregation
幫我新增一個轉換率分析的 aggregationAgent 會建立 AggregationSpec 和 MetricContracts
-
Code Review
請檢查這段 code 是否符合數據分析後端的架構原則 [貼上你的 code]Agent 會檢查是否遵循層級職責和避免 anti-patterns
- 指導開發流程: 明確告訴 Agent 在新增 endpoint、aggregation、dimension、formatter 時需要做哪些改動
- 維護架構一致性: 確保所有實作遵循三層架構和依賴反轉原則
- 防止常見錯誤: 明確標示每一層該出現和不該出現的邏輯
- 提供完整參考: 包含資料流 pipeline、層級依賴關係和程式碼範例
data_analysis_skill/
├── SKILL.md # 主指引文件 (核心內容)
├── README.md # 本文件
│
├── references/ # 詳細參考文件
│ ├── domain-models.md # Domain Model 詳解
│ ├── query-builder-guide.md # Query Builder 架構指南
│ └── formatter-guide.md # Formatter 指南
│
└── assets/ # 程式碼範例和模板
├── templates/
│ └── standard-endpoint.ts # 標準 endpoint 完整範例
│
├── examples/
│ ├── dimension-spec.ts # DimensionSpec 範例
│ ├── aggregation-spec.ts # AggregationSpec 範例
│ ├── metric-contract.ts # MetricContract 範例
│ └── logical-query.ts # LogicalQuery 範例
│
└── anti-patterns/ # 反面教材 (常見錯誤)
├── sql-in-aggregation.ts # ❌ Aggregation 包含 SQL
├── db-fields-in-dimension.ts # ❌ Dimension 混入 DB 欄位
├── formatter-computation.ts # ❌ Formatter 重新計算數值
└── divergent-endpoint.ts # ❌ Endpoint 流程偏離標準
所有數據分析 endpoint 必須遵循此標準流程:
- Validate Request (Endpoint Layer)
- Build DimensionSpec (Endpoint → Service)
- Resolve AggregationSpec (Service)
- Build QueryPlan (Service → Infrastructure)
- Execute Query (Infrastructure)
- Aggregate Result (Service)
- Format Visualization (Service → Endpoint)
- Return Response (Endpoint)
Endpoint Layer (HTTP)
↓
Application Service Layer (Orchestration)
↓
Domain Layer (Business Logic)
↓
Infrastructure Layer (DB/SQL)
- DimensionSpec: 語意化的維度定義 (不知道 DB schema)
- AggregationSpec: Metric contracts + 計算邏輯 (pure function)
- MetricContract: 單一指標的定義 (name, type, aggregation)
- LogicalQuery: 中間層 query representation (連接 semantic 和 physical)
這是最簡單直接的方法:
-
找到 Claude Code 的 skills 目錄
# Windows %USERPROFILE%\.claude\skills\ # macOS/Linux ~/.claude/skills/
-
複製整個 skill 目錄
# Windows (在 PowerShell 或 CMD) xcopy /E /I C:\Users\andyc\Projects\data_analysis_skill %USERPROFILE%\.claude\skills\data-analysis-backend # macOS/Linux cp -r /path/to/data_analysis_skill ~/.claude/skills/data-analysis-backend
-
驗證安裝
- 重啟 Claude Code (如果正在運行)
- 檢查 skills 目錄中是否有
data-analysis-backend資料夾 - 確認
SKILL.md檔案存在且有正確的 YAML frontmatter
-
測試 skill
- 開啟 Claude Code
- 詢問: "幫我新增一個數據分析 endpoint"
- Agent 應該會自動使用此 skill 並遵循 8-step pipeline
如果你想要持續更新 skill 並立即看到效果:
# Windows (需要管理員權限)
mklink /D "%USERPROFILE%\.claude\skills\data-analysis-backend" "C:\Users\andyc\Projects\data_analysis_skill"
# macOS/Linux
ln -s /path/to/data_analysis_skill ~/.claude/skills/data-analysis-backend這樣修改原始檔案就會立即反映到 Claude Code 中。
如果你有 Claude Code 的 packaging tools:
-
打包 skill
# 假設有 package_skill.py 工具 python package_skill.py data_analysis_skill -
安裝打包後的 .skill 檔案
# 將 .skill 檔案複製到 skills 目錄 cp data-analysis-backend.skill ~/.claude/skills/
-
驗證
# 假設有 quick_validate.py 工具 python quick_validate.py ~/.claude/skills/data-analysis-backend.skill
-
檢查檔案結構
# 確認以下檔案存在 ~/.claude/skills/data-analysis-backend/ ├── SKILL.md # 必須存在 ├── README.md ├── references/ │ ├── domain-models.md │ ├── query-builder-guide.md │ └── formatter-guide.md └── assets/ ├── templates/ ├── examples/ └── anti-patterns/
-
檢查 YAML Frontmatter
- 打開
SKILL.md - 確認開頭有正確的 YAML frontmatter:
--- name: data-analysis-backend description: "Use when implementing or modifying data analysis backend features..." ---
- 打開
-
重啟 Claude Code
- 完全關閉 Claude Code
- 重新啟動
- Skills 會在啟動時自動載入
如果需要移除此 skill:
# Windows
rmdir /S /Q "%USERPROFILE%\.claude\skills\data-analysis-backend"
# macOS/Linux
rm -rf ~/.claude/skills/data-analysis-backend當 Agent 需要實作或修改數據分析後端功能時,會自動使用此 skill,包括:
- 新增 endpoint
- 新增 aggregation
- 新增/修改 dimension
- 新增/修改 formatter
你也可以明確要求使用此 skill:
使用 data-analysis-backend skill 幫我新增一個收入分析的 endpoint
當 Agent 使用此 skill 時,你會看到:
- Agent 會提到 "8-step pipeline"
- Agent 會建立 DimensionSpec 和 AggregationSpec
- Agent 會明確分離 Endpoint/Service/Domain/Infrastructure layers
- Agent 會避免在 Domain Layer 使用 SQL
問題: Agent 沒有使用此 skill
解決方法:
-
檢查 SKILL.md 的 description 是否包含觸發關鍵字:
- "data analysis backend"
- "endpoint", "aggregation", "dimension", "formatter"
-
嘗試明確提到這些關鍵字:
幫我實作一個數據分析的 endpoint (data analysis endpoint) -
手動指定 skill:
使用 data-analysis-backend skill
問題: 不確定 skills 目錄在哪裡
解決方法:
# 在 Claude Code 中執行
echo $HOME/.claude/skills/ # macOS/Linux
echo %USERPROFILE%\.claude\skills\ # Windows
# 或者使用 Claude Code 命令 (如果支援)
/skills list問題: Skill 無法載入,可能是 YAML 格式問題
解決方法:
-
確認 SKILL.md 開頭的 YAML 格式:
--- name: data-analysis-backend description: "Use when implementing..." ---
-
注意事項:
---必須在檔案第一行- name 和 description 是必須的
- description 需要用雙引號包起來
- YAML 結束也需要
---
問題: 無法複製檔案到 skills 目錄
解決方法:
# 檢查權限
ls -la ~/.claude/skills/ # macOS/Linux
dir %USERPROFILE%\.claude\skills\ # Windows
# 如果目錄不存在,手動建立
mkdir -p ~/.claude/skills/ # macOS/Linux
mkdir %USERPROFILE%\.claude\skills\ # Windows問題: Windows 建立 symbolic link 失敗
解決方法:
- 以管理員身份執行 PowerShell 或 CMD
- 或者使用方法 1 (直接複製) 代替
驗證步驟:
- 重啟 Claude Code
- 執行以下測試:
請告訴我你有哪些可用的 skills? - 如果 Agent 提到 "data-analysis-backend",表示載入成功
如果修改了 skill 內容:
- 直接複製: 重新複製整個目錄
- Symbolic Link: 修改會自動生效
- 重啟 Claude Code: 確保變更被載入
- 快速開始: 閱讀
SKILL.md的 Overview 和 8-Step Pipeline - 開發任務: 查看
SKILL.md的 Development Workflows 對應的檢查清單 - 詳細實作: 參考
references/下的詳細指南 - 程式碼範例: 查看
assets/templates/和assets/examples/ - 避免錯誤: 檢查
assets/anti-patterns/的反面教材
- 閱讀
SKILL.md→ "Workflow 1: Adding a New Endpoint" - 參考
assets/templates/standard-endpoint.ts的完整範例 - 遵循 8-step pipeline 實作
- 檢查
assets/anti-patterns/divergent-endpoint.ts避免常見錯誤
- 閱讀
SKILL.md→ "Workflow 2: Adding a New Aggregation" - 參考
assets/examples/aggregation-spec.ts的範例 - 定義 MetricContracts (參考
assets/examples/metric-contract.ts) - 實作 compute 函數 (pure function, 無 SQL)
- 註冊到 AggregationRegistry
- 檢查
assets/anti-patterns/sql-in-aggregation.ts避免 SQL 耦合
- 閱讀
SKILL.md→ "Workflow 3: Adding/Modifying Dimensions" - 參考
assets/examples/dimension-spec.ts - 更新 QueryBuilder 的 dimensionMapping (Infrastructure Layer)
- 測試所有現有 Aggregations
- 檢查
assets/anti-patterns/db-fields-in-dimension.ts避免 schema leakage
- 閱讀
SKILL.md→ "Workflow 4: Adding/Modifying Output Formats" - 參考
references/formatter-guide.md - 實作 IVisualizationFormatter interface
- 確保只做資料重組,不重新計算
- 檢查
assets/anti-patterns/formatter-computation.ts避免重複計算
Endpoint Layer
- ✅ Request validation
- ✅ Response formatting
- ✅ HTTP status codes
Service Layer
- ✅ Orchestration logic
- ✅ Spec composition
- ✅ Result aggregation
Domain Layer
- ✅ Business rules
- ✅ Semantic definitions
- ✅ Contracts (interfaces)
Infrastructure Layer
- ✅ SQL generation
- ✅ DB connections
- ✅ Query execution
Endpoint Layer
- ❌ Business logic
- ❌ SQL queries
- ❌ Data transformation
Service Layer
- ❌ HTTP concerns
- ❌ SQL generation
- ❌ DB connection
Domain Layer
- ❌ DB schema knowledge
- ❌ SQL strings
- ❌ Join logic
Infrastructure Layer
- ❌ Business rules
- ❌ Aggregation logic
- ❌ Visualization logic
在 commit 前檢查:
- 所有 endpoint 遵循 8-step pipeline
- DimensionSpec 無 DB column names
- AggregationSpec compute 無 SQL
- Formatter 無重新計算 metrics
- Domain Layer 無 import DB client
- 所有 semantic names 有對應的 QueryBuilder mapping
這個 skill 成功的標準:
- 清晰度: Agent 能立即知道在特定任務時需要做什麼
- 完整性: 涵蓋所有開發場景
- 防護性: 明確標示各層職責邊界,防止架構腐化
- 實用性: 提供完整可執行的程式碼範例
- 可維護性: 結構清晰,易於後續擴充和更新
A: 適合任何需要數據分析後端的專案,特別是:
- BI/Analytics 平台
- Dashboard 後端 API
- 報表系統
- 數據查詢服務
- 多維度分析系統
A: 不完全是。這個 skill 是指導手冊,它會:
- ✅ 告訴 Agent 該遵循什麼架構原則
- ✅ 提供完整的 code 範例供參考
- ✅ 防止 Agent 犯常見的架構錯誤
- ✅ 確保 Agent 遵循標準 pipeline
Agent 仍然會根據你的具體需求寫 code,但會遵循這個 skill 的指引。
A: 當然可以！這個 skill 是開源的,你可以:
- 修改 SKILL.md 的內容
- 新增你自己的範例到 assets/examples/
- 加入更多 anti-patterns 到 assets/anti-patterns/
- 調整 references/ 的詳細文件
修改後,如果使用 Symbolic Link 安裝,會立即生效;如果是直接複製,需要重新複製。
A: 不會。這個 skill 專注於數據分析後端架構,與其他 skills (如 UI/UX, testing, deployment) 是互補的。
A: 可以,但可能需要調整。這個 skill 基於:
- Clean Architecture
- Three-Layer Architecture (Endpoint-Service-Domain-Infrastructure)
- Dependency Inversion Principle
如果你的專案使用不同架構,可以修改 SKILL.md 的內容來匹配你的架構。
A: 不會。Skill 設計採用漸進式揭露:
- Agent 會先讀 SKILL.md (主指引)
- 需要詳細資訊時才讀 references/
- 需要範例時才讀 assets/
這樣可以避免 context 過載。
A: 觀察 Agent 的回應:
- 會提到 "8-step pipeline"
- 會明確建立 DimensionSpec, AggregationSpec
- 會避免在 Aggregation 寫 SQL
- 會分離 Endpoint/Service/Domain layers
如果沒有,可以明確說: "請使用 data-analysis-backend skill"
A: 範例使用 TypeScript,但概念適用於任何語言:
- Python: FastAPI + SQLAlchemy
- Java: Spring Boot + JPA
- C#: ASP.NET Core + Entity Framework
- Go: Gin + GORM
架構原則是語言無關的。
A: 當然可以！建議方式:
- 將此 skill 加入你的專案 repo
- 在 README 說明如何安裝
- 團隊成員各自安裝到自己的 ~/.claude/skills/
這樣整個團隊都會遵循相同的架構原則。
A: 目前版本是 1.0.0。建議:
- 根據團隊實際使用經驗更新
- 發現新的 anti-patterns 時加入
- 有更好的範例時替換
- 架構演進時同步更新
如果你有改進建議:
- 修改對應的檔案
- 測試修改後的效果
- 分享你的經驗
建議的改進方向:
- 新增更多程式語言的範例
- 加入更多 anti-patterns
- 補充更多 edge cases 的處理方式
- 新增效能優化的指引
analytics_backend_plan.md: 原始架構設計計劃SKILL.md: 主要指引文件 (必讀)summary.md: 實作總結
本 skill 為開源專案,可自由使用、修改和分發。
- Version: 1.0.0
- Last Updated: 2026-01-31
- Author: Andy Chen (with Claude)
如果遇到問題:
- 查看本 README 的「故障排除」章節
- 檢查 SKILL.md 的內容是否正確
- 確認 Claude Code 已正確安裝並運行
開始使用: 返回到快速開始章節開始安裝!