AI/Claude Code

Claude Code Review GitHub Action, 최신 템플릿으로 설치하면 리뷰 코멘트가 안 달립니다

2026년 1월 이후 Claude Code Review 설치 템플릿이 플러그인 방식으로 바뀌면서 PR 코멘트가 포스팅되지 않는 문제가 발생합니다. 실제 GitHub Issues 분석과 함께 공식 권장 해결법을 정리합니다.

uppinote

17 2월 2026 • 13 min read

1. 문제 상황

여러 사이드 프로젝트에 Claude Code Review GitHub Action을 사용하고 있습니다. 이전 프로젝트에서는 2025년 12월에 설치한 직접 프롬프트 방식 템플릿으로 문제 없이 잘 돌아가고 있었습니다.

그런데 새 프로젝트에 2026년 2월 초 GitHub 인스톨러로 설치하니, 템플릿이 바뀌어 있었습니다. 그대로 사용했더니 Action은 성공적으로 완료되지만 PR에 리뷰 코멘트가 전혀 달리지 않는 현상이 발생했습니다.

증상 정리

GitHub Actions 워크플로우는 success (녹색 체크)
실행 시간 8~11분 (기존 프로젝트에서는 ~4분이었는데 비정상적으로 길음)
Action Summary에는 리뷰 내용이 보임
하지만 PR 코멘트, 인라인 코멘트 모두 0건
로그를 뒤져보면 Claude가 리뷰를 완료하고 코멘트를 남기려는 tool call까지 생성했으나, 실행되지 않고 세션이 종료됨

// Action 로그 마지막 부분
"num_turns": 24,
"tool_name": "Bash",
"command": "gh pr review 15 --comment --body \"## Code Review ...\"",
// ↑ 이 명령이 실행되지 않고 세션 종료
Log saved to /home/runner/work/_temp/claude-execution-output.json

혼란스러운 부분

같은 리포지토리의 이전 PR(작은 변경)에서는 코멘트가 정상적으로 달렸습니다. 그래서 처음에는 "PR이 크면 안 되나?" 싶었는데, 진짜 원인은 다른 곳에 있었습니다.

2. 디버깅 과정

원인을 찾기 위해 3번 재시도했습니다. 이 과정 자체가 꽤 삽질이었는데, 같은 상황에 처한 분들을 위해 기록합니다.

1차 시도: 기본 설정 그대로

num_turns: 24 (기본 max_turns=25에서 1턴 부족)
결과: 마지막 tool call 미실행

24턴을 써서 리뷰를 완성하고, 25번째 턴에서 코멘트를 포스팅하려 했으나 세션이 종료되었습니다. "턴이 부족한 거구나" 싶어서 max_turns를 늘려보기로 했습니다.

2차 시도: `max_turns`를 직접 input으로 추가

- uses: anthropics/claude-code-action@v1
  with:
    max_turns: 40  # ← 이것은 유효한 input이 아닙니다!

워크플로우는 성공했지만, 로그를 자세히 보니 경고가 있었습니다:

##[warning] Unexpected input(s) 'max_turns',
valid inputs are [..., 'claude_args', ...]

max_turns는 Action의 직접 input이 아닙니다. claude_args를 통해 CLI 인자로 전달해야 합니다. GitHub Actions는 알 수 없는 input에 대해 warning만 표시하고 무시하므로, 워크플로우는 "성공"으로 표시되지만 설정은 적용되지 않았습니다. 이 warning을 놓치면 "설정했는데 왜 안 되지?"하고 한참 헤맬 수 있습니다.

# ❌ 잘못된 방법 (무시됨, warning만 표시)
max_turns: 40

# ✅ 올바른 방법
claude_args: '--max-turns 40'

3차 시도: 올바른 방법으로 전달

claude_args: '--max-turns 40'

num_turns: 32 (40턴 중 32턴 사용)
결과: 여전히 마지막 tool calls 미실행

이번에는 턴이 충분했습니다(32/40). 그런데도 코멘트가 달리지 않았습니다. 로그를 다시 확인해보니 패턴이 보였습니다:

Claude가 MCP 인라인 코멘트 도구(mcp__github_inline_comment__*)를 호출하려 시도 → 도구가 등록되지 않아 실패
fallback으로 gh api를 사용해 직접 코멘트를 남기려 시도
여러 gh api 호출과 gh pr review 호출을 한 번에 요청
이 마지막 tool call 배치가 로그에만 기록되고 실행되지 않은 채 세션 종료

MCP 도구 실패 → 대안 탐색 → 턴 소모라는 악순환이 반복되면서, 정작 코멘트를 포스팅하는 최종 명령이 실행되지 못한 것입니다.

max_turns가 근본 원인이 아니었습니다. 이 시점에서 GitHub Issues를 뒤져보기 시작했습니다.

3. 원인: 인스톨러 템플릿이 바뀌었습니다

2025년 12월 말과 2026년 1월 중순 사이에, Claude Code Review의 설치 템플릿이 근본적으로 변경되었습니다(#825).

이전 템플릿 (2025년 12월, 정상 작동):

- name: Run Claude Code Review
  uses: anthropics/claude-code-action@v1
  with:
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    prompt: |
      REPO: ${{ github.repository }}
      PR NUMBER: ${{ github.event.pull_request.number }}

      Please review this pull request and provide feedback on:
      - Code quality and best practices
      - Potential bugs or issues
      - Security concerns
      - Test coverage

      Use `gh pr comment` with your Bash tool to leave your review
      as a comment on the PR.

    claude_args: '--allowedTools "Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"'

새 템플릿 (2026년 1월, 문제 발생):

- name: Run Claude Code Review
  uses: anthropics/claude-code-action@v1
  with:
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'  # ← 추가됨
    plugins: 'code-review@claude-code-plugins'                            # ← 추가됨
    prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
    # ↑ 직접 프롬프트 대신 플러그인 스킬 호출로 변경

핵심 차이점:

직접 프롬프트 → 플러그인 마켓플레이스 + 스킬 호출 방식으로 전환
gh pr comment 명시적 지시 제거
--allowedTools 설정 제거

플러그인 방식의 알려진 이슈들

GitHub Issues를 찾아보니, 이 변경으로 인한 문제가 저만의 경험이 아니었습니다. 최소 4개의 알려진 이슈가 존재하고, 2026년 2월 현재 대부분 미해결 상태입니다.

MCP 도구 로드 실패 (#548)

제가 겪은 문제의 직접적인 원인입니다. 플러그인이 사용하는 MCP 도구가 로드되지 않습니다.

mode detection 로직에서 allowedTools 배열이 빈 상태로 MCP 설정에 전달됩니다:

// src/modes/tag/index.ts:123
const hasInlineCommentTools = allowedToolsList.some((tool) =>
  tool.startsWith("mcp__github_inline_comment__")
);
// ↑ allowedToolsList가 비어있으므로 항상 false → MCP 서버 미등록

Claude가 리뷰를 완료한 후 코멘트를 남기려 하면:

Error: No such tool available: mcp__github_comment__update_claude_comment

v1.0.6에서 수정되었다고 되어 있지만, 커뮤니티 기여자가 실제로는 미해결이라고 확인했습니다.

제네릭 메시지만 포스팅 (#609)

MCP 도구 실패의 또 다른 증상입니다. 실제 리뷰 대신 이런 메시지만 PR에 달립니다:

"The code review has been completed successfully.
Please check the GitHub Actions summary for detailed results."

상세 리뷰는 Actions Summary에만 있고, PR 코멘트에는 나타나지 않습니다. 리뷰어가 Actions 로그를 직접 열어봐야 하므로 자동화의 의미가 사라집니다.

2.5배 느린 실행 속도 (#825)

플러그인 마켓플레이스 로딩과 MCP 서버 초기화에 추가 시간이 소요됩니다.

메트릭	직접 프롬프트	플러그인 방식
리뷰 시간	~4분	~10분
품질	높음 (명시적 기준)	낮음 (vague prompt)

이슈 작성자는 "기존 템플릿으로 되돌려 달라"고 요청했으며, bug, performance, area:installation 라벨이 달려있습니다.

재실행 시 리뷰 스킵 (#19618)

code-review 플러그인에 하드코딩된 스킵 조건이 있습니다:

<!-- code-review.md의 18번째 줄 -->
- Claude has already commented on this PR
  (check `gh pr view <PR> --comments` for comments left by claude)

이 때문에 다음 시나리오가 깨집니다:

PR 생성 → Claude 리뷰 → 코멘트 포스팅
개발자가 피드백 반영하여 커밋 push
synchronize 이벤트로 워크플로우 재실행
Claude가 이미 코멘트를 남겼으므로 리뷰 스킵 ← 문제

--force 플래그도, 설정 옵션도 없습니다. iterative한 PR 워크플로우에서 자동 리뷰가 의미를 잃습니다.

4. 해결 방법: 직접 프롬프트로 전환

공식 문서(docs/solutions.md)에서도 플러그인을 사용하지 않는 직접 프롬프트 방식을 권장합니다. 이전 프로젝트들에서 사용하던 바로 그 방식입니다.

전체 워크플로우 (Before → After)

Before (플러그인 방식):

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
      id-token: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
          plugins: 'code-review@claude-code-plugins'
          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'

After (직접 프롬프트 방식):

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]               # ← 불필요한 이벤트 제거

jobs:
  claude-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: read                              # ← write → read (최소 권한)
      id-token: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Run Claude Code Review
        uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            REPO: ${{ github.repository }}
            PR NUMBER: ${{ github.event.pull_request.number }}

            Please review this pull request and provide feedback on:
            - Code quality and best practices
            - Potential bugs or issues
            - Performance considerations
            - Security concerns
            - Test coverage

            Use the repository's CLAUDE.md for guidance on style
            and conventions. Be constructive and helpful.

            Use `gh pr comment` with your Bash tool to leave your
            review as a comment on the PR.

          claude_args: '--model claude-opus-4-5-20251101 --allowedTools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'

왜 이렇게 바꾸면 되는지

각 변경 포인트를 하나씩 설명합니다.

`plugin_marketplaces`, `plugins` 제거

# 삭제
plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
plugins: 'code-review@claude-code-plugins'

MCP 도구 로드 실패, 느린 속도, 재실행 스킵 버그를 한 번에 해결합니다. 플러그인이 하던 일(diff 읽기, 코드 분석, 코멘트 작성)은 Claude가 gh CLI로 직접 수행합니다.

`REPO`, `PR NUMBER` 명시

prompt: |
  REPO: ${{ github.repository }}
  PR NUMBER: ${{ github.event.pull_request.number }}

이 두 변수가 없으면 Claude가 PR 컨텍스트를 찾지 못해 제네릭 응답을 반환합니다(#557).

`gh pr comment` 사용 명시

prompt: |
  ...
  Use `gh pr comment` with your Bash tool to leave your review
  as a comment on the PR.

코멘트 포스팅 방법을 명시적으로 지시합니다. MCP 도구에 의존하지 않으므로 도구 로드 실패 문제가 원천 차단됩니다.

`--allowedTools` 설정

claude_args: '--allowedTools "Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"'

Claude가 사용할 수 있는 도구를 명시적으로 허용합니다. 이 설정이 없으면 agent mode에서 코멘트 관련 도구가 비활성화될 수 있습니다(#621).

참고로 공식 문서에서는 camelCase(--allowedTools)를 사용합니다. CLI에서는 kebab-case(--allowed-tools)도 동작하지만, 혼동을 피하려면 공식 표기를 따르세요.

두 방식 비교 요약

항목	플러그인 방식	직접 프롬프트
설정 복잡도	높음 (marketplace + plugin + skill)	낮음 (prompt + claude_args)
실행 시간	~10분	~4분
코멘트 포스팅	MCP 도구 의존 (불안정)	`gh` CLI (안정)
재실행 지원	스킵 버그 있음	매번 정상 실행
커스터마이징	플러그인 내부 로직에 의존	프롬프트에서 자유롭게 제어
공식 권장	비권장	권장 (docs/solutions.md)

5. 체크리스트와 디버깅 가이드

설정 체크리스트

[ ] plugin_marketplaces와 plugins 사용하지 않기 (직접 프롬프트 방식 사용)
[ ] prompt에 REPO와 PR NUMBER 포함하기
[ ] prompt에 gh pr comment 사용 명시하기
[ ] claude_args에 --allowedTools 설정하기
[ ] 트리거 이벤트는 opened와 synchronize만 사용하기
[ ] permissions에서 pull-requests: write 확인하기

코멘트가 안 달릴 때 디버깅 순서

1단계: Actions 로그에서 num_turns 확인

"num_turns": 24,

기본값(25) 근처라면 턴이 부족할 수 있습니다. claude_args: '--max-turns 40'으로 늘려보세요. 단, 이것만으로 해결되지 않을 수 있습니다.

2단계: Warning 확인

##[warning] Unexpected input(s) 'max_turns'

이 경고가 보이면 max_turns를 직접 input으로 넣은 것입니다. claude_args를 통해 전달하세요.

3단계: MCP 에러 확인

Error: No such tool available: mcp__github_comment__update_claude_comment

이 에러가 보이면 플러그인 방식의 MCP 도구 로드 실패입니다. 직접 프롬프트 방식으로 전환하세요.

4단계: 마지막 tool calls 확인

로그 끝에 실행되지 않은 tool call이 JSON으로 기록되어 있으면, Claude가 코멘트를 남기려 했지만 세션이 먼저 종료된 것입니다. 플러그인 내부의 MCP 도구 실패 → 재시도 → 턴 소모 악순환이 원인입니다.

6. FAQ

Q: 기존에 플러그인 방식으로 잘 되고 있었는데, 바꿔야 하나요?

A: 현재 정상 작동하고 있다면 급하게 바꿀 필요는 없습니다. 다만 재실행 스킵 버그(#19618)가 있으므로, 반복적인 리뷰가 필요한 PR에서 문제가 발생할 수 있습니다. 직접 프롬프트 방식이 공식 권장이므로 전환을 권합니다.

Q: mcp__github_inline_comment__create_inline_comment도 --allowedTools에 추가해야 하나요?

A: 추가할 수 있지만, MCP 도구 로드 실패 이슈(#548)가 완전히 해결되지 않았으므로 의존하지 않는 것이 안전합니다. gh pr comment만으로도 충분한 리뷰가 가능합니다.

Q: anthropic_api_key 대신 claude_code_oauth_token을 사용해도 되나요?

A: 네, 둘 다 지원됩니다. claude_code_oauth_token은 Claude Code OAuth를 통한 인증이고, anthropic_api_key는 Anthropic Console API 키입니다. 조직 환경에서는 API 키 관리가 더 편할 수 있으므로 anthropic_api_key도 고려해보세요.

Q: 리뷰 품질을 높이려면 어떻게 해야 하나요?

A: prompt에 구체적인 리뷰 기준을 추가하세요. 프로젝트에 CLAUDE.md가 있으면 Claude가 자동으로 참조합니다. "한국어 주석 사용 여부 확인", "특정 라이브러리 사용 여부 확인" 등 프로젝트 고유의 규칙을 포함하면 리뷰 품질이 크게 올라갑니다.

Q: pull_request_target 이벤트를 사용하면 어떻게 되나요?

A: agent mode가 자동 선택되어 코멘트 포스팅이 비활성화됩니다(#621). Dependabot 등 외부 PR 리뷰가 필요하면 --allowedTools를 반드시 설정하세요.

Claude Code Review GitHub Action, 최신 템플릿으로 설치하면 리뷰 코멘트가 안 달립니다

uppinote

1. 문제 상황

증상 정리

혼란스러운 부분

2. 디버깅 과정

1차 시도: 기본 설정 그대로

2차 시도: `max_turns`를 직접 input으로 추가

3차 시도: 올바른 방법으로 전달

3. 원인: 인스톨러 템플릿이 바뀌었습니다

플러그인 방식의 알려진 이슈들

MCP 도구 로드 실패 (#548)

제네릭 메시지만 포스팅 (#609)

2.5배 느린 실행 속도 (#825)

재실행 시 리뷰 스킵 (#19618)

4. 해결 방법: 직접 프롬프트로 전환

전체 워크플로우 (Before → After)

왜 이렇게 바꾸면 되는지

`plugin_marketplaces`, `plugins` 제거

`REPO`, `PR NUMBER` 명시

`gh pr comment` 사용 명시

`--allowedTools` 설정

두 방식 비교 요약

5. 체크리스트와 디버깅 가이드

설정 체크리스트

코멘트가 안 달릴 때 디버깅 순서

6. FAQ

7. 참고 자료

공식 문서

관련 GitHub Issues

1. 문제 상황

증상 정리

혼란스러운 부분

2. 디버깅 과정

1차 시도: 기본 설정 그대로

2차 시도: max_turns를 직접 input으로 추가

3차 시도: 올바른 방법으로 전달

3. 원인: 인스톨러 템플릿이 바뀌었습니다

플러그인 방식의 알려진 이슈들

MCP 도구 로드 실패 (#548)

제네릭 메시지만 포스팅 (#609)

2.5배 느린 실행 속도 (#825)

재실행 시 리뷰 스킵 (#19618)

4. 해결 방법: 직접 프롬프트로 전환

전체 워크플로우 (Before → After)

왜 이렇게 바꾸면 되는지

plugin_marketplaces, plugins 제거

REPO, PR NUMBER 명시

gh pr comment 사용 명시

--allowedTools 설정

두 방식 비교 요약

5. 체크리스트와 디버깅 가이드

설정 체크리스트

코멘트가 안 달릴 때 디버깅 순서

6. FAQ

7. 참고 자료

공식 문서

관련 GitHub Issues

2차 시도: `max_turns`를 직접 input으로 추가

`plugin_marketplaces`, `plugins` 제거

`REPO`, `PR NUMBER` 명시

`gh pr comment` 사용 명시

`--allowedTools` 설정