[機翻] 我們如何將 Claude Code 整合進 GitHub 工作流程

• 原文：How We Integrated Claude Code Into Our GitHub Workflow | Medium
• 作者：Chamith Madusanka
• 發表日期：Mar 1, 2026

身為一個大型企業平台（Go + React + TypeScript + Terraform）的軟體工程師，我一直在尋找降低日常開發摩擦的方法。Code review 不斷堆積、除錯 CI 失敗佔用了大量工作時數，而讓新成員熟悉我們的程式碼架構模式也需要好幾週的時間。

後來，我們將 Claude Code 直接整合進 GitHub repository——這從根本上改變了我們團隊的運作方式。

最大的改變是什麼？小任務再也不需要在本地 checkout 程式碼了。 當一個小修正、小重構或小功能的工單進來時，我們只需在 issue 上 @claude 並附上清楚的描述。Claude 會接手工作、建立分支、完成修改、執行測試，然後開一個 PR——整個過程不需要任何開發者 pull repo、切換分支或啟動本地開發環境。就像有一個隊友直接從工單佇列處理瑣碎事項，讓其他人專注在複雜的工作上。

在這篇文章裡，我會帶你完整了解我們的設定方式、實際體驗到的效益，以及過程中學到的教訓。

什麼是 Claude GitHub 整合？

Anthropic 提供了一個官方 GitHub Action，名為 anthropics/claude-code-action，讓你可以把 Claude 直接帶入 GitHub 的 issue 和 pull request 流程中。不需要再切換到另一個 AI 對話工具，只要在留言中 @claude，Claude 就會回應——並且完整存取你的程式碼庫。

把它想像成在你的團隊裡加入一位永遠待命的資深工程師，他能：

• 閱讀並理解你的整個程式碼庫
• 修改程式碼、建立 commit、開 PR
• 執行你的 linting、測試和建置流程
• 遵守你的專案特定程式碼規範
• 永遠不會對 code review 感到疲倦

我們的設定：兩個 Workflow、一套強大的系統

我們圍繞兩個獨立的 GitHub Actions workflow 來設計整合，各自服務不同的目的。

Workflow 1：通用助理（claude.yml）

這是我們的主力 workflow。它會在任何人於以下情境 @claude 時觸發：

• Issue 留言
• PR 留言
• PR review 留言
• 新 issue（標題或內文中）
• 帶有 claude 標籤的 issue

核心觸發設定如下：

name: Claude Code

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned, labeled]
  pull_request_review:
    types: [submitted]

讓這個 workflow 強大的關鍵在於條件過濾。我們確保 Claude 只回應人類使用者，不回應自己或其他 bot：

if: |
  github.actor != 'claude[bot]' &&
  github.actor != 'dependabot[bot]' &&
  github.actor != 'github-actions[bot]' &&
  (
    (github.event_name == 'issue_comment' &&
     contains(github.event.comment.body, '@claude')) ||
    ...
  )

這可以防止 Claude 不斷觸發自己而產生無限迴圈——這個細節雖然不起眼，但非常關鍵。

功能範圍：這個 workflow 給予 Claude 完整的讀寫存取權。它可以編輯檔案、建立 commit（並附帶驗證簽章！）、執行 make 目標、跑測試和建置專案。我們明確地白名單列出每個允許的命令：

claude_args: |
  --model claude-opus-4-5-20251101
  --max-turns 30
  --allowedTools "Bash(make build),Bash(make lint-backend),
    Bash(make test-be),Bash(go test ./...),
    Bash(git *),Read,Edit,Write,MultiEdit"

這種白名單方式對安全性至關重要——Claude 只能執行我們預先核准的命令。

Workflow 2：專屬 Code Reviewer（claude-review.yml）

我們的第二個 workflow 專門設計用於結構化的 code review。它有兩種觸發方式：

1. 在任何 PR 上留言 @claude-review——立即獲得 AI code review
2. 從 GitHub Actions UI 手動觸發——輸入 PR 編號即可執行

關鍵差異在哪？這個 workflow 是唯讀的。 Claude 無法修改檔案——它只能閱讀程式碼、執行 lint 和測試，並提供意見回饋：

# 唯讀工具：不含 Edit、Write、MultiEdit
--allowedTools "Bash(git diff *),Bash(git log *),
  Bash(make lint-backend),Bash(make test-be),Read"

Review 遵循定義在自訂 skill 檔案中的專案特定準則，涵蓋從 TypeScript 型別安全到 Go 錯誤處理模式，再到資料庫遷移安全性等所有面向。

秘訣所在：自訂 Skill 與 CLAUDE.md

光有這個整合是有用的，但讓它對我們團隊真正發揮強大效果的，是針對專案的客製化。

CLAUDE.md 檔案

這是你的專案給 Claude 的「大腦轉儲」。它是放在 repository 根目錄的一個 markdown 檔案，Claude 每次被呼叫時都會自動讀取。我們的 CLAUDE.md 包含：

• 架構總覽——技術棧、分層架構、模組結構
• 命名慣例——Go、TypeScript、資料庫和檔案的命名規則
• 程式碼修改流程——Claude 必須遵循的確切順序（格式化 → lint → 測試）
• API 慣例——REST 模式、錯誤處理、控制器模式
• 測試模式——Go 的 table-driven tests、React Testing Library 慣例
• 安全限制——Claude 絕對不能做的事

這意味著 Claude 不只是寫出通用程式碼——它寫出的程式碼符合你們團隊的模式。

自訂 Skill

我們在 .claude/skills/ 中建立了兩個自訂 skill：

code-review——一份全面的 review 檢查清單，涵蓋：

• TypeScript 型別安全（不使用 any 型別、正確的 import 方式）
• React 元件模式（函式元件、適當的 memoization）
• Zustand 狀態管理慣例
• React Query 資料取得模式
• Ant Design 表單模式
• Go 錯誤處理與介面注入
• 資料庫遷移安全性

lint-fix——一個自動化的 lint 修正流程，知道：

• 在跑 linter 前先執行格式化工具
• 依照我們的特定規則修正剩餘問題
• 在認為任務完成前確認全部通過

以下是你的 review skill 在實際應用中的樣子。這只是基本範例——你可以依據專案需求自訂和定義自己的準則：

# Code Review Skill
審查目前的修改並提供建設性的意見回饋。

## TypeScript
- 不使用 `any` 型別——請使用正確的 interface/type
- 型別 import 必須使用 `type` 關鍵字
- Props interface 以元件名稱為前綴

## React 元件
- 只使用函式元件（偏好箭頭函式）
- 對耗費效能的計算使用 `useMemo`
- list 中不使用陣列 index 作為 key

## Go 程式碼
- 所有錯誤都必須適當處理
- 介面注入——控制器薄、服務厚
- 新功能需有測試覆蓋

## 通用
- 不可寫入硬編碼的機密或憑證
- 遵循程式碼庫中的現有模式
- 不要過度設計

實際使用情境範例

以下是我們團隊日常實際使用的方式：

1. 透過 Issue 實作功能

@claude 請實作一個取得使用者偏好設定的新 API endpoint。請遵循程式碼庫中的現有模式。

Claude 會探索程式碼庫、找到類似的 endpoint，按照我們建立的模式建立 controller/service/repository，撰寫測試，並執行 linter——全部在一次互動中完成。

2. 除錯 CI 失敗

@claude CI 建置失敗了。你能查看錯誤 log 並提出修正方案嗎？

Claude 會讀取 CI log、找出根本原因，然後直接修正或提供清楚的說明。

3. 隨需 Code Review

@claude-review

在 PR 上留一則留言，Claude 就會提供結構化的 review，包含具體的檔案路徑、行號和可執行的意見——完全遵循我們團隊的程式碼規範。

讓一切運作的環境設定

有一個容易被忽略的細節：Claude 需要在 CI 環境中安裝好正確的工具。 我們的 workflow 設定了：

• Node.js 22，含 pnpm 和依賴快取
• Go 1.24，含模組和建置快取
• golangci-lint 用於後端 lint
• Nx 快取 用於前端建置效能
• 前端依賴 透過 pnpm install --frozen-lockfile

這樣完整的環境準備確保 Claude 能真正建置、測試和 lint 專案——而不只是讀取檔案。

設定適當的護欄非常重要。你的 claude.md 應該包含修改後需要執行的所有步驟。例如，Claude 應該依據程式碼庫中定義的規則執行適當的格式化和 linting，也應該執行測試以偵測任何破壞性變更。

安全性：真正重要的護欄

我們對安全性非常認真。以下是我們的鎖定方式：

明確的工具白名單

Claude 只能執行我們預先核准的命令。不能 rm -rf、不能 curl、不能執行 Docker 命令。每個 Bash 命令都明確列出。

Repository 限制

我們的 CLAUDE.md 定義了硬性限制：

• 禁止修改 workflow 檔案或 CI/CD 設定
• 禁止未經核准安裝新依賴套件
• 禁止修改 .env 檔案或機密
• 禁止直接 push 到 main 或 develop
• 禁止執行破壞性命令
• 禁止暴露環境變數

分支保護

Claude 會建立 PR——它永遠不會直接 push 到受保護的分支。合併前至少需要一位人類核准。

唯讀 Review

我們的 review workflow 刻意拿掉了寫入權限。Claude 只能分析，不能修改。

Commit 簽章

所有由 Claude 建立的 commit 都有加密簽章：

use_commit_signing: true

這提供了 AI 生成變更的清楚稽核軌跡。

我們實際體驗到的效益

使用這個整合數個月後，以下是改變的事：

1. 更快的 Code Review

過去需要資深工程師花 30–60 分鐘的初步審查，現在在 5 分鐘以內就能完成第一輪。人工審查者可以專注在架構和業務邏輯，讓 Claude 抓出風格問題、缺少的錯誤處理和模式違規。

2. 一致的程式碼品質

Claude 每一次都確實執行我們的規範。

3. 降低新貢獻者的門檻

新成員可以直接在 issue 或 PR 中詢問 Claude 問題。「身份驗證 middleware 是怎麼運作的？」會得到深入、符合情境的解答——而不是一個 Stack Overflow 連結。

4. 減少情境切換

開發者不需要離開 GitHub 去和 AI 對話，AI 主動來到他們所在之處，並帶著完整的情境。

5. 自動化繁瑣工作

lint 修正、格式化校正、樣板程式碼生成——Claude 處理機械性的工作，讓人類專注在創造性的問題解決上。

學到的教訓

從唯讀開始

我們建議在開啟寫入存取之前，先從僅 review 的 workflow 開始。這讓你的團隊有時間建立對 Claude 理解你程式碼庫的信任感。

投資 CLAUDE.md

Claude 產出的品質與你的專案文件品質直接相關。一份寫好的 CLAUDE.md 是你能做的單一最高投資報酬率的事。

對允許的工具保持明確

不要給 Claude 全部存取權。白名單只開放它需要的命令。這既是安全措施，也是防止意外行為的護欄。

使用自訂 Skill

通用 AI 有用。知道你的團隊特定 TypeScript 模式、Go 錯誤處理慣例和資料庫遷移規則的 AI，才是真正的改變。

設定合理的逾時時間

我們對一般任務設定 15 分鐘，對 review 設定 10 分鐘。這可以在給 Claude 足夠時間做完整工作的同時，防止失控的 workflow 佔用資源。

入門指南：最小可行設定

如果你想自己嘗試，以下是你需要的：

1. 在你的 repository 上安裝 Claude GitHub App
2. 在 repository secrets 中新增 CLAUDE_CODE_OAUTH_TOKEN（需要 Claude Pro/Max 訂閱）
3. 建立 .github/workflows/claude.yml，使用 anthropics/claude-code-action@v1 action
4. 在 repository 根目錄建立 CLAUDE.md，寫入你的專案慣例
5. 在 main 分支上設定分支保護——要求至少一位人類核准
6. 在 issue 上留言 @claude，然後見證魔法發生

結語

將 Claude 整合進我們的 GitHub 工作流程，不只是新增一個 AI 工具的問題——而是重新思考我們如何作為一個團隊協作。Claude 處理那些過去佔用我們創造力時間的重複性、模式配對工作。它在不死板的前提下確保一致性。它全天候待命，永遠不會精疲力竭。

它能取代人類工程師嗎？差遠了。但作為力量倍增器？它是多年來我們開發工作流程中最好的新增成員。

真正理解你程式碼庫的 code review bot。永遠不需要喝咖啡休息的配對程式設計師。讀過每一行 CLAUDE.md 並確實遵守的團隊成員。

這就是 GitHub 上的 Claude。

完整的設定檔案（四個檔案）已發布為 GitHub Gist，可作為你自己設定的起點：

• claude.yml——具完整讀寫存取的通用助理
• claude-review.yml——用於結構化 PR review 的唯讀 code reviewer
• code-review-SKILL.md——自訂 review 準則（TypeScript、React、Go、遷移）
• lint-fix-SKILL.md——自動化先格式化再 lint 的工作流程