Claude Task Master를 활용한 PR 기반 개발 자동화

Claude Task Master (claudetm)는 목표가 달성될 때까지 Claude를 작동시키는 커맨드 라인 도구입니다. 이 도구는 Claude Agent SDK를 기반으로 구축되었으며 엄격한 PR(Pull Request) 기반 워크플로우를 따릅니다. 본 글에서는 이 도구를 설정하는 방법, 작업이 어떻게 오케스트레이션되는지, 그리고 REST API 및 웹훅 시스템을 통해 어떻게 확장할 수 있는지 설명합니다.

핵심 개념 (Core Concepts)

이 도구는 계획(planning), 작업(working), PR 생명주기(PR lifecycle), 검증(verification)의 네 단계로 구성된 루프를 통해 작동합니다. 계획 단계에서는 코드베이스를 읽고, 작업 목록을 생성하며, 성공 기준을 정의합니다. 작업 단계에서는 코드 변경을 수행하고, 테스트를 실행하며, 각 변경 사항을 커밋하고 푸시합니다. PR 생명주기 단계에서는 풀 리퀘스트(pull request)를 열고, CI(Continuous Integration)를 기다리며, 실패를 수정하고 리뷰 코멘트를 처리합니다. 마지막으로 검증은 모든 성공 기준이 충족되었는지 확인하기 위해 최종 일련의 체크를 실행한 후 작업을 완료로 표시합니다.

PLANNING → WORKING → PR LIFECYCLE → VERIFICATION

모든 작업은 풀 리퀘스트를 통해 이루어지므로, 코드가 main 브랜치에 직접 커밋되지 않습니다. 이 접근 방식은 팀에게 명확한 감사 추적(audit trail)을 제공하며 기존의 리뷰 프로세스와 자연스럽게 통합됩니다.

시작하기 (Getting Started)

pip, uv 또는 Docker를 사용하여 패키지를 설치합니다. 다음 예제는 uv를 사용합니다:

uv tool install claude-task-master

먼저 Claude Code로 인증합니다:

claude login

그런 다음 프로젝트 디렉토리에서 작업을 실행합니다:

cd my-project
claudetm start "테스트와 함께 사용자 인증 추가"

CLI는 계획을 생성하고, 풀 리퀘스트를 열고, CI 실패를 처리하며, PR이 승인되면 병합(merge)합니다. 프로세스가 중단되어도 도구는 상태를 유지하고 이전에 멈춘 지점부터 정확하게 재개됩니다.

병렬 인스턴스를 위한 프로필 (Profiles for Parallel Instances)

Claude Task Master는 여러 개의 격리된 프로필을 지원합니다. 프로필은 별도의 Claude Code 설정 디렉토리를 사용하는 oauth 프로필일 수도 있고, 직접 Anthropic과 호환되는 엔드포인트를 가리키는 api-key 프로필일 수도 있습니다.

claudetm --profile my-team start "결제 게이트웨이 구현"

프로파일을 사용하면 두 개의 Claude 구독이 서로 충돌하는 것을 방지하고 팀이 여러 인스턴스를 병렬로 실행할 수 있게 합니다.

REST API, MCP 서버 및 웹훅

CLI 외에도 이 도구는 REST API와 MCP 서버를 노출합니다. 이러한 인터페이스를 통해 외부 시스템이 작업을 디스패치(dispatch)하고, 진행 상황을 모니터링하며, 메일박스 업데이트에 반응할 수 있습니다. 웹훅은 HMAC 서명되어 안전한 통신을 보장합니다.

일반적인 웹훅 페이로드에는 작업 식별자, 현재 단계 및 메일박스에서 온 모든 메시지가 포함됩니다. 이를 사용하여 대시보드를 업데이트하거나 추가 자동화를 트리거할 수 있습니다.

기존 풀 리퀘스트 병합하기

CI 처리가 필요한 기존 PR이 있다면 Claude Task Master에 맡길 수 있습니다:

claudetm merge-pr 42

이 도구는 CI 루프를 담당하고, 실패를 수정하며, 리뷰 코멘트를 처리하고, PR이 병합 가능해지면 병합합니다. 이 기능은 프로젝트 자체 저장소의 PR #147-#150을 병합하는 데 사용되었습니다.

Claude Task Master를 사용할 때

이 도구는 이미 Claude Code를 사용하며 PR 수명 주기 전체에 걸친 자동화를 원하는 팀에 적합합니다. 명시적인 성공 기준과 비교하여 검증할 수 있는 잘 정의된 목표와 함께 가장 잘 작동합니다. 여러 개의 Claude 구독을 운영하는 팀은 프로파일 격리(profile isolation)의 이점을 누릴 수 있습니다.

결론

Claude Task Master는 상태를 유지하고, 병렬 인스턴스를 지원하며, REST API와 웹훅을 통해 프로그램적 제어를 제공하는, PR 중심의 손쉬운 워크플로우를 제공합니다. 이는 MIT 라이선스 하에 오픈 소스로 공개되었으며 PyPI 또는 Docker를 통해 설치할 수 있습니다. 다음 기능 구현 시 사용해 보고, 도구가 개발 과정의 반복적인 부분을 처리하도록 맡겨보세요.

GitHub Repository