빠른 설정

name: Claude Code

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

연동 흐름

댓글 기반과 prompt 기반을 구분한다

Claude Code GitHub Actions는 PR이나 issue 댓글의 @claude 언급에 반응하는 흐름과, workflow가 실행될 때 prompt를 바로 넘기는 자동화 흐름을 모두 지원합니다. 사람의 요청에 반응해야 하면 댓글 기반이 자연스럽고, 정기 리포트나 PR 생성 시 자동 리뷰처럼 이벤트가 명확하면 prompt 기반이 더 단순합니다.

@claude 댓글
  -> 사용자가 필요한 순간 호출

prompt 입력
  -> workflow 이벤트가 곧 작업 지시

두 방식을 한 파일에 섞을 수는 있지만, 팀 운영에서는 "언제 Claude가 자동으로 움직이는가"를 명확히 하는 것이 더 중요합니다.

설치보다 권한과 secret 경계를 먼저 정한다

GitHub Action은 저장소 파일을 읽고, PR에 댓글을 달고, 경우에 따라 변경을 푸시할 수 있습니다. 따라서 ANTHROPIC_API_KEY는 반드시 GitHub Secrets에 두고, workflow permission은 필요한 범위로 제한해야 합니다. 설치 자체는 /install-github-app이나 수동 workflow 추가로 할 수 있지만, 운영 사고는 대부분 secret 노출과 과도한 권한에서 생깁니다.

필수 확인
- API key를 workflow 파일에 직접 쓰지 않는다.
- GitHub App 권한을 목적에 맞게 제한한다.
- 자동 커밋/PR 생성 범위를 팀 규칙으로 정한다.
- Claude가 따를 `CLAUDE.md` 기준을 저장소 루트에 둔다.

prompt와 claude_args는 역할이 다르다

prompt는 Claude에게 맡길 작업 지시입니다. claude_args는 Claude Code CLI 실행 옵션을 넘기는 통로입니다. 모델, turn 제한, system prompt 추가 같은 실행 제어는 claude_args로 두고, 작업 내용은 prompt에 두면 workflow를 읽기 쉽습니다.

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Review this PR for security issues"
    claude_args: |
      --max-turns 10
      --model claude-sonnet-4-6

언제 붙일까

주의할 점

자동 리뷰나 자동 수정은 편하지만 비용과 실행 시간이 누적됩니다. PR마다 필요한 작업인지, 사용자가 @claude로 호출할 때만 충분한지 먼저 구분해야 합니다.