SuperClaude 使用手冊

USER_MANUAL.md

SuperClaude 使用手冊

本手冊將提供 SuperClaude 框架的全面指南，幫助您從安裝到進階使用，充分發揮其強大的功能。

---

目錄

1. 簡介
   • 什麼是 SuperClaude？
   • 核心設計理念
2. 安裝指南
   • 安裝指令
   • 安裝選項
3. 核心概念
   • 認知角色 (Personas)
   • 思考深度控制
   • MCP 整合
   • Token 經濟學
4. 通用旗標 (Universal Flags)
   • 思考深度
   • Token 優化
   • MCP 伺服器控制
   • 執行與規劃
   • 品質與驗證
5. 指令參考
   • 開發 (Development)
     • /build
     • /dev-setup
     • /test
   • 分析與改進 (Analysis & Improvement)
     • /review
     • /analyze
     • /troubleshoot
     • /improve
     • /explain
   • 更多指令...
6. SuperClaude 與軟體開發生命週期 (SDLC)
   • 規劃與需求分析 (Planning & Requirements)
   • 設計與架構 (Design & Architecture)
   • 開發與實作 (Development & Implementation)
   • 測試與品質保證 (Testing & QA)
   • 部署 (Deployment)
   • 維護與優化 (Maintenance & Optimization)
7. 工作流程範例
   • 企業架構設計流程
   • 生產環境問題解決流程
   • 全端功能開發流程

---

1. 簡介

什麼是 SuperClaude？

SuperClaude 是一個為 Claude Code 設計的強化設定框架。它透過一系列專門的指令、9 種認知角色（Personas）和專業開發方法論，將標準的 Claude Code 提升到一個新的層次，使其在處理複雜的軟體開發任務時更加精準、高效且專業。

核心設計理念

• 模組化與可擴展性: 框架本身採用高度模組化的設定，易於維護和擴展。
• 實證基礎 (Evidence-Based): 強調所有分析和建議都應基於可查證的來源，例如引用文件或原始碼。
• Token 經濟學: 內建多種機制（如壓縮模式）來最佳化 Token 使用，以應對大型專案。
• 情境感知: 能夠在整個開發會話中保持上下文，進行連貫的深度分析。
• 專業分工: 透過「認知角色」，讓 AI 能夠模擬不同領域專家的思維模式來解決特定問題。

---

2. 安裝指南

SuperClaude 提供了一個功能強大的安裝腳本 install.sh。

安裝指令

git clone https://github.com/NomenAK/SuperClaude.git
cd SuperClaude

# 執行安裝
./install.sh

預設情況下，所有設定檔會被安裝到您使用者主目錄下的 ~/.claude/ 資料夾。

安裝選項

您可以透過不同的旗標來自訂安裝過程：

旗標	說明
--dir /path/to/dir	指定安裝到自訂目錄。
--update	更新現有的 SuperClaude 安裝，同時保留客製化設定。
--dry-run	預覽安裝過程會發生的變更，但不會實際執行。
--force	跳過所有確認提示，適合自動化腳本。
--log install.log	將所有安裝操作記錄到指定的日誌檔。

---

3. 核心概念

認知角色 (Personas)

這是 SuperClaude 最核心的功能。您可以透過在任何指令後方加上 --persona-<name> 旗標，讓 AI 戴上特定專家的「帽子」來思考。

可用的角色包括：

• architect: 系統架構師，專注於高層次設計、擴展性和模式。
• frontend: 前端工程師，專注於使用者體驗 (UI/UX) 和無障礙設計。
• backend: 後端工程師，專注於 API、資料庫和系統可靠性。
• security: 安全專家，專注於威脅模型、零信任和漏洞評估。
• analyzer: 分析師，擅長根本原因分析和基於證據的調查。
• qa: 品質保證工程師，專注於測試、邊界案例和驗證。
• performance: 效能專家，專注於優化、分析和效率。
• refactorer: 重構專家，專注於程式碼品質和維護性。
• mentor: 導師，擅長教學、解釋概念和知識傳遞。

範例:

# 請安全專家審查這段程式碼
/review --files src/auth.ts --persona-security

# 請前端專家協助建立 UI 元件
/build --feature "Login Form" --persona-frontend

思考深度控制

您可以控制 AI 分析問題的深度，以平衡速度和全面性。

旗標	描述
--think	進行跨檔案分析，擴展上下文。
--think-hard	進行架構層級的深度分析。
--ultrathink	進行關鍵系統的極限深度分析。

MCP 整合

SuperClaude 可以與多種 MCP (Model Context Protocol) 伺服器整合，以擴展其能力。

• Context7 (--c7): 存取外部函式庫文件。
• Sequential (--seq): 進行多步驟的邏輯推理。
• Magic (--magic): 產生 AI 生成的 UI 元件。
• Puppeteer (--pup): 進行瀏覽器自動化測試。

注意: 您需要在 Claude Code 的設定中單獨安裝和啟用這些 MCP 伺服器。

Token 經濟學

• --uc 或 --ultracompressed: 啟用超壓縮模式，可以顯著減少複雜任務中的 Token 消耗。
• --no-mcp: 停用所有 MCP 工具，僅使用原生功能，以節省 Token。

---

4. 通用旗標 (Universal Flags)

以下旗標適用於所有 SuperClaude 指令。

思考深度

• --think: 標準深度分析。
• --think-hard: 架構級深度分析。
• --ultrathink: 極限深度分析。

Token 優化

• --uc, --ultracompressed: 啟用超壓縮模式。

MCP 伺服器控制

• --c7, --seq, --magic, --pup: 分別啟用指定的 MCP 伺服器。
• --all-mcp: 啟用所有 MCP 伺服器。
• --no-mcp: 禁用所有 MCP 伺服器。

執行與規劃

• --plan: 在執行前顯示詳細的執行計畫。
• --dry-run: 預覽變更而不實際執行。
• --watch: 持續監控並提供即時回饋。
• --interactive: 進入步驟式引導模式。
• --force: 強制執行，跳過安全檢查。

品質與驗證

• --validate: 執行前進行增強的安全檢查。
• --security: 進行以安全為核心的分析。
• --coverage: 產生程式碼覆蓋率分析。
• --strict: 啟用零容忍模式，進行最嚴格的驗證。

---

5. 指令參考

以下是 SuperClaude 提供的部分核心指令。

開發 (Development)

/build - 通用專案建構器

用於建構專案、功能和元件。

• --init: 初始化一個新專案。
• --feature "name": 在現有專案中實作一個新功能。
• --tdd: 採用測試驅動開發流程。
• --react, --api, --fullstack: 使用預設的技術棧範本（React, Node.js API, 全端）。

範例:

# 初始化一個新的 React 專案，並採用 TDD
/build --init --react --tdd --persona-frontend

# 在現有專案中新增一個 "使用者認證" 功能
/build --feature "User Authentication" --tdd --persona-backend

/dev-setup - 開發環境設定

設定專業的開發環境。

• --install: 安裝與設定依賴。
• --ci: 設定 CI/CD 管線。
• --monitor: 設定監控與觀測性工具。
• --docker: 設定容器化環境。

範例:

# 設定包含 CI 和監控的完整開發環境
/dev-setup --install --ci --monitor

/test - 綜合測試框架

建立、執行和維護測試。

• --e2e, --integration, --unit: 指定測試類型（端到端、整合、單元）。
• --performance: 進行效能測試。
• --accessibility: 進行無障礙功能測試。
• --parallel: 平行執行測試。

範例:

# 使用 Puppeteer 執行完整的端到端測試並計算覆蓋率
/test --coverage --e2e --pup --persona-qa

分析與改進 (Analysis & Improvement)

/review - AI 程式碼審查

提供基於證據的程式碼審查。

• --files <path>: 指定要審查的檔案或目錄。
• --commit <hash>: 審查特定 commit 的變更。
• --pr <number>: 審查指定的 Pull Request。
• --quality: 專注於程式碼品質問題。
• --evidence: 為所有建議提供來源文件或證據。
• --fix: 直接建議修正方案。

範例:

# 請安全專家審查 `src/` 目錄下的所有檔案
/review --files src/ --persona-security --evidence

/analyze - 多維度分析

對程式碼、架構、效能進行全面分析。

• --code: 程式碼品質分析。
• --architecture: 系統設計評估。
• --profile: 效能分析。
• --deps: 依賴項分析。

範例:

# 對整個專案的程式碼和架構進行深度分析
/analyze --code --architecture --think-hard --seq --persona-architect

/troubleshoot - 專業除錯

系統化地解決問題。

• --investigate: 進行系統性問題分析。
• --five-whys: 使用「五個為什麼」方法進行根本原因分析。
• --prod: 針對生產環境問題進行除錯。
• --perf: 針對效能問題進行調查。

範例:

# 調查生產環境的錯誤，並找出根本原因
/troubleshoot --prod --five-whys --seq --persona-analyzer

/improve - 增強與優化

進行有衡量指標的改進。

• --quality: 改善程式碼結構。
• --performance: 進行效能優化。
• --refactor: 進行系統性重構。
• --modernize: 更新老舊的技術棧。

範例:

# 迭代地重構程式碼，直到品質分數達到 95%
/improve --quality --refactor --iterate --threshold 95% --persona-refactorer

/explain - 技術文件生成

產生各種技術文件。

• --depth <level>: 指定解釋的深度 (ELI5 到 expert)。
• --visual: 產生圖表（如 Mermaid.js）。
• --api: 產生 API 文件。
• --tutorial: 產生教學文件。

範例:

# 為專案的 API 產生專家級別的、包含圖表和範例的參考文件
/explain --api --depth expert --visual --examples --seq --persona-mentor

更多指令

SuperClaude 還包含了用於操作 (Operations) 和 設計 (Design) 的指令，如 /deploy, /migrate, /scan, /design 等，它們同樣支援上述的通用旗標和認知角色。

---

6. SuperClaude 與軟體開發生命週期 (SDLC)

SuperClaude 的指令集完整覆蓋了現代軟體開發生命週期（SDLC）的各個階段。您可以將 SuperClaude 視為在整個開發流程中與您協作的 AI 工程師團隊。

以下是 SDLC 各階段如何對應到 SuperClaude 指令的範例：

1. 規劃與需求分析 (Planning & Requirements)

在這個初始階段，您需要定義專案的範圍、目標和可行性。

• /explain: 澄清複雜的技術概念或商業邏輯。
• /estimate: 評估專案的複雜度和所需工作量。

範例:

# 解釋微服務架構的優缺點
/explain --architecture "microservices" --depth intermediate --persona-mentor

# 估算開發一個電商網站所需的工作
/estimate --feature "e-commerce website" --detailed --seq

2. 設計與架構 (Design & Architecture)

定義系統的技術架構、資料庫結構和 API 介面。

• /design: 進行系統架構和 API 設計。
• /analyze: 分析現有程式碼或架構以供參考。

範例:

# 使用 DDD 設計一個新的訂單管理系統 API
/design --api --ddd --bounded-context "Order Management" --persona-architect

# 產生 API 的 OpenAPI (Swagger) 文件
/explain --api --reference --persona-backend

3. 開發與實作 (Development & Implementation)

撰寫程式碼，實現功能。

• /build: 根據設計建立專案、功能或元件。
• /dev-setup: 配置開發環境。

範例:

# 根據設計稿，使用 TDD 方式建立使用者認證功能
/build --feature "User Authentication" --tdd --persona-backend

# 建立一個包含監控的 CI/CD 開發環境
/dev-setup --ci --monitor

4. 測試與品質保證 (Testing & QA)

確保軟體品質，找出並修復錯誤。

• /test: 執行各種測試（單元、整合、E2E）。
• /review: 進行程式碼審查以發現潛在問題。
• /scan: 掃描程式碼中的安全漏洞。

範例:

# 對整個專案執行端到端測試，並檢查程式碼覆蓋率
/test --e2e --coverage --pup --persona-qa

# 請安全專家審查所有關於驗證的程式碼
/review --files "src/auth" --persona-security

5. 部署 (Deployment)

將應用程式發佈到生產環境。

• /deploy: 規劃與執行部署流程。
• /scan: 在部署前進行最後的安全驗證。

範例:

# 規劃一個到 AWS 生產環境的藍綠部署計畫
/deploy --env prod --plan --strategy blue-green --persona-architect

# 部署前掃描所有依賴項的漏洞
/scan --deps --security --validate

6. 維護與優化 (Maintenance & Optimization)

監控線上狀況、修復問題並進行效能優化。

• /troubleshoot: 調查並解決生產環境中的問題。
• /improve: 針對效能、可讀性等方面進行重構與優化。
• /cleanup: 移除無用程式碼或依賴。

範例:

# 調查生產日誌中回報的 "502 Bad Gateway" 錯誤
/troubleshoot --prod --investigate "502 Bad Gateway" --persona-analyzer

# 針對資料庫查詢進行效能優化
/improve --performance --refactor "database queries" --persona-performance

---

7. 工作流程範例

企業架構設計流程

1. 設計: /design --api --ddd --persona-architect (使用領域驅動設計來設計 API)
2. 估算: /estimate --detailed --seq (詳細估算開發資源)
3. 審查: /scan --security --validate --persona-security (進行安全審查)
4. 建構: /build --api --tdd --persona-backend (以 TDD 方式建構 API)

生產環境問題解決流程

1. 調查: /troubleshoot --investigate --prod --persona-analyzer (調查生產問題)
2. 分析: /analyze --profile --perf --seq (分析效能瓶頸)
3. 改進: /improve --performance --threshold 95% --persona-performance (進行效能優化)
4. 驗證: /test --integration --e2e --pup (進行整合測試以驗證修復)

全端功能開發流程

1. 前端: /build --react --magic --watch --persona-frontend (使用 AI 元件開發 UI)
2. 後端: /build --api --feature "New Endpoint" --tdd --persona-backend (開發後端 API)
3. 品保: /test --coverage --e2e --strict --persona-qa (進行嚴格的 QA 測試)
4. 安全: /scan --validate --deps --persona-security (部署前進行安全掃描)