AI Workflow Conduction

繁體中文

Home
English

繁體中文

Home
English

Appearance

Agent Skill 採用 ​

本提案旨在實施 Agent Skills 進行團隊知識分享和工作流程自動化。重點在於建立團隊 Skills 庫和採用流程。

前置知識： 本提案假設您已熟悉 Agent Skill 概念。請參閱 C8: 流程與知識技能化 了解 Agent Skills 的基礎知識。

問題陳述 ​

當前狀態：重複的脈絡設定 ​

團隊回饋的痛點 ​

痛點對 AI 工作流程的影響
重複提示每次對話都要設定相同脈絡，浪費時間
不一致的方式不同團隊成員獲得不同的 AI 行為
專業知識流失資深開發者的有效提示未被分享
新人入職摩擦新成員不知道團隊的 AI 最佳實踐
缺乏改進循環成功的模式未被擷取以供迭代

錯失機會的證據 ​

場景 1：API 設計審查

資深開發者已完善一套能捕捉常見錯誤的 API 審查提示。但這個提示只存在於他們的對話歷史中。初級開發者持續犯相同的 API 設計錯誤。

場景 2：程式碼遷移

團隊花了數週開發有效的遺留程式碼遷移提示。專案結束，提示遺失。下一個遷移專案從零開始。

場景 3：文件產生

每個開發者有自己請 Claude 撰寫文件的方式。結果不一致。有些遵循團隊慣例，有些則沒有。

提議解決方案：團隊 Skills 庫 ​

目標架構 ​

參考實作：Superpowers ​

Superpowers 是團隊採用 agent skills 的推薦起點。Fork 它、客製化它、並針對團隊特定需求擴展它。

快速開始（30 分鐘） ​

步驟 1：安裝 Superpowers

bash
# Clone 到您的 Claude Code plugins 目錄
git clone https://github.com/obra/superpowers ~/.claude/plugins/superpowers

步驟 2：設定 CLAUDE.md

在專案的 CLAUDE.md 中加入：

markdown
You have access to superpowers skills. Use them for:
- /brainstorming - before any feature work
- /writing-plans - before implementation
- /systematic-debugging - for any bug investigation
- /tdd - for all new code
- /verification-before-completion - before claiming done

步驟 3：驗證啟用

啟動 Claude Code 對話並請求一個功能。代理應該在撰寫任何程式碼前自動觸發 brainstorming。如果它直接跳到編碼，請檢查您的 CLAUDE.md 設定。

步驟 4：第一個團隊 Skill

熟悉後，複製現有的 Superpowers skill 並針對您的領域修改，建立第一個團隊專屬 skill。

客製化指南 ​

Superpowers 設計上就是要被 fork 和擴展的。團隊應該客製化它來編碼特定的工作流程、標準和領域知識。

要客製化的內容：

層級範例優先順序
工作流程 Skills加入您的 API 審查檢查清單、部署程序高
領域 Skills編碼業務規則、命名慣例、架構模式高
工具整合連接到您的 CI/CD、Jira、內部 APIs中
驗證規則定義對您團隊而言「完成」的意義高

建立團隊 Skills：

  1. 識別重複決策 - 資深工程師反覆解釋什麼？那就是 skill 候選。
  2. 從現有 Skills 開始 - 複製類似的 Superpowers skill 作為模板。結構（觸發條件、步驟、驗證）已經過驗證。
  3. 用 Markdown 編碼 - Skills 是帶有結構化區段的純 Markdown 檔案。不需要特殊工具。
  4. 版本控制 Skills - 將團隊 skills 儲存在您的 repository 中。它們與程式碼庫一起演進。

Skill 結構：

skills/
  team/
    api-review.md        # 您的 API 設計標準
    error-handling.md    # 您的錯誤處理模式
    testing-standards.md # 您的覆蓋率要求

這直接實作了原則 C4（流程與知識技能化）- 將團隊專業知識擷取為可重複使用、AI 可執行的形式。

與指導原則的對齊 ​

Superpowers 的設計哲學直接支援白皮書的多項原則：

原則Superpowers 對齊
E1: 設計導向工作Brainstorming skill 強制在編碼前設計；阻止過早實作
E4: 嚴謹驗證Verification-Before-Completion 要求在聲稱完成前提供證據（測試輸出、命令結果）
C1: 脈絡工程所有 skills 都從脈絡收集開始；brainstorming 使用蘇格拉底式提問
C4: 技能化整個框架建立在可組合、可版本控制的 skills 上
G5: AI 可見產出物Skills 是純 Markdown——人類和 AI 代理都可讀

工作流程對齊：

白皮書工作流程主要 Superpowers Skills
功能開發流程brainstorming → writing-plans → tdd → verification
API 設計流程brainstorming → writing-plans → code-review
錯誤修復流程systematic-debugging → tdd → verification

哲學契合：

兩個框架共享核心信念：AI 代理需要明確的流程紀律，而非僅有能力。若不加約束，代理會跳過步驟、合理化捷徑、並過早聲稱完成。結構化 skills 將隱性團隊知識轉換為明確、可執行的工作流程。

團隊 Skill 類別 ​

1. 標準執行 Skills ​

確保 AI 生成的程式碼遵循團隊慣例的 Skills。

yaml
---
name: coding-standards
description: 執行團隊程式碼標準和慣例。撰寫或審查程式碼時使用，
  以確保與專案指南一致。
---

# 程式碼標準

## 命名慣例
- 變數和函式使用 camelCase
- 類別和元件使用 PascalCase
- 常數使用 SCREAMING_SNAKE_CASE

## 檔案組織
- 每個檔案一個元件
- 將相關工具程式分組在目錄中
- 測試與原始碼共置

## Import 順序
1. 外部套件
2. 內部套件
3. 相對路徑 imports

2. 工作流程自動化 Skills ​

自動化常見開發工作流程的 Skills。

yaml
---
name: commit
description: 依照 Conventional Commits 規範建立結構良好的 git commits。
  提交程式碼變更時使用，確保語意化的 commit 訊息，支援自動化 changelog
  產生與版本號遞增。
---
markdown
# Commit

依照 Conventional Commits 格式建立 commits。

## 格式

  [type]([scope]): [subject]

  [body]

  [footer]

## 類型

- `feat` - 新功能（觸發 minor 版本遞增）
- `fix` - 錯誤修復（觸發 patch 版本遞增）
- `docs` - 僅文件變更
- `refactor` - 非功能/修復的程式碼變更
- `test` - 新增或更新測試
- `chore` - 維護任務

## 規則

- 標題：祈使語氣，最多 50 字元，不加句號
- 內文：每行 72 字元換行，說明做了什麼及為什麼
- Footer：引用 issues，註記破壞性變更
- 破壞性變更：在 type 後加 `!` 或在 footer 加 `BREAKING CHANGE:`

3. 品質保證 Skills ​

確保程式碼品質的 Skills。

yaml
---
name: security-review
description: 對程式碼變更執行安全審查。審查程式碼的安全漏洞、
  驗證問題或資料處理疑慮時使用。
allowed-tools: Read Grep Glob
---

# 安全審查

## OWASP Top 10 檢查
1. 注入漏洞
2. 驗證破損
3. 敏感資料暴露
4. XML 外部實體
5. 存取控制破損
...

## 要標記的程式碼模式
- 寫死的憑證
- SQL 字串串接
- 未驗證的使用者輸入
- 缺少驗證檢查

實施階段 ​

階段 1：基礎 ​

目標： 建立 Skills 基礎建設並建立首批團隊 Skills。

交付項目：

  • 在團隊 repositories 中建立 .claude/skills/ 目錄
  • 記錄 Skill 建立指南
  • 為最常見的工作流程建立初始 Skills
  • 建立命名慣例

階段 2：採用 ​

目標： 推動團隊採用並建立改進流程。

交付項目：

  • 為團隊舉辦 Skill 使用培訓
  • 收集使用回饋
  • 迭代 Skill 有效性
  • 建立 Skill 維護流程

階段 3：持續改進 ​

目標： 維持 Skill 品質和相關性。

活動：

  • 定期 Skill 審查和清理
  • 透過 PR 提出新 Skill 提案
  • 棄用過時 Skills
  • 跨團隊 Skill 分享

CLAUDE.md 整合 ​

加入專案 CLAUDE.md：

markdown
## 團隊 Skills

### 可用 Skills
本專案在 `.claude/skills/` 包含團隊 Skills：

- **coding-standards** - 團隊程式碼慣例和模式
- **code-review** - 標準化審查檢查清單
- **api-design** - REST API 設計標準
- **testing** - 測試建立指南

### 使用 Skills
Skills 會根據脈絡自動被發現。您不需要明確觸發它們。當您的請求
匹配某個 Skill 的描述時，Claude 會載入並應用該 Skill。

### 建立新 Skills
1. 在 `.claude/skills/[skill-name]/` 建立目錄
2. 撰寫含 frontmatter（name、description）的 `SKILL.md`
3. 視需要新增支援檔案
4. 提交 PR 供團隊審查

### Skill 標準
- 使用動名詞命名：`reviewing-code`、`designing-apis`
- SKILL.md 保持在 500 行以下
- 連結到支援檔案以獲取詳情
- 描述使用第三人稱撰寫

Skill 開發工作流程 ​

從模式到 Skill ​

步驟 ​

  1. 識別模式：注意到您持續解釋相同脈絡
  2. 記錄模式：寫下您不斷告訴 Claude 的內容
  3. 建立 Skill：以適當 frontmatter 結構化為 SKILL.md
  4. 測試：在類似任務上使用 Skill
  5. 迭代：根據 Claude 的行為調整
  6. 分享：提交到 repository 供團隊存取

成功指標 ​

指標目標如何測量
Skill 覆蓋率>80% 常見工作流程審計團隊活動 vs 可用 Skills
重複提示-70%調查：「您多常重複脈絡？」
AI 輸出一致性高比較不同團隊成員的輸出
新成員入職-50% 時間測量達到有效 AI 使用的時間
Skill 採用率>90% 團隊追蹤誰在工作流程中使用 Skills
Skill 貢獻每成員 1+ 個計算新增/改進 Skills 的 PR

快速開始指南 ​

建立您的第一個 Skill ​

bash
# 1. 建立 skill 目錄
mkdir -p .claude/skills/my-first-skill

# 2. 建立 SKILL.md
cat > .claude/skills/my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: [它做什麼以及何時使用]
---

# 我的第一個 Skill

## 指令
[清晰、逐步的指導]

## 範例
[具體範例]
EOF

# 3. 測試它
# 詢問 Claude 匹配您描述的內容

# 4. 提交並分享
git add .claude/skills/
git commit -m "Add my-first-skill for [用途]"
git push

相關提案 ​

相關原則 ​

相關： AI 代理友善知識庫 | 返回： 提案概覽