과제 제기

일일 개발 업무에 있어, 새로 작성되거나 업데이트된 코드의 품질 체크 및 리뷰는 매우 중요합니다. 하지만 수동 리뷰는 시간과 노력이 들 뿐만 아니라, 특히 작은 변경 사항이라도 매번 사람에게 리뷰를 요청하는 것은 심리적 부담이 크다고 느끼는 분들이 많지 않을까요.

ahic는 13체의 AI 에이전트를 운용하며 일상 업무를 철저히 자동화하고 있습니다. 이러한 경험을 바탕으로, 특정 디렉토리에 새로 생성된 코드 파일을 Claude Code가 자동으로 리뷰하고 그 결과를 개발자에게 피드백하는 시스템을 구축했습니다.

이 시스템을 도입함으로써 개발자는 커밋(Commit)이나 풀 리퀘스트(Pull Request)를 생성하기 전에 AI를 통한 1차 리뷰를 받을 수 있게 됩니다. 이를 통해 코드 품질이 향상되고, 더 높은 품질의 코드를 짧은 시간 안에 작성할 수 있게 됩니다. 본 기사에서는 이 자동 리뷰 시스템을 Claude Code와 Python, 그리고 macOS의 launchd를 사용하여 구축하는 절차를 상세히 해설합니다.

구현 절차

이 자동 리뷰 시스템은 다음과 같은 단계로 구성됩니다.

• 리뷰 대상 디렉토리 감시: Python의 watchdog 라이브러리를 사용하여 특정 디렉토리에서의 파일 생성 이벤트를 감지합니다.
• 신규 파일 감지 시 Claude Code API 호출: 감지된 파일의 콘텐츠를 읽어 Claude Code에 리뷰 요청을 전송합니다.
• 리뷰 결과 취득 및 출력: Claude Code로부터 반환된 리뷰 결과를 표준 출력(Standard Output)으로 출력하거나 파일에 저장합니다.
• Python 스크립트 작성 및 launchd를 통한 상주화: 작성한 Python 스크립트를 launchd에 등록하여 시스템 기동 시 자동으로 실행되게 함으로써, 항상 디렉토리를 감시하는 상태로 만듭니다.

필요한 것

• Python 3.x
• Anthropic API 키
• macOS 환경 (launchd를 이용하기 위해)

1. Python 스크립트 작성

먼저 디렉토리를 감시하고 신규 파일을 Claude Code로 전송하는 Python 스크립트를 작성합니다. code_reviewer.py라는 이름으로 저장해 주세요.

import os
import time
import logging
...

보충:

• TARGET_DIR은 본인의 환경에 맞춰 리뷰 대상 디렉토리 경로로 변경해 주세요.
• on_created 메서드 내에서 if file_path.endswith('.py'):를 통해 Python 파일만을 리뷰 대상으로 하고 있습니다. 다른 파일 형식도 대상으로 하려면 적절히 변경해 주세요.
• time.sleep(1)은 파일이 완전히 쓰여질 때까지 기다리기 위한 것입니다. 큰 파일의 경우 조정이 필요할 수 있습니다.
• get_claude_review 내의 모델은 본인의 용도나 예산에 맞춰 claude-3-opus-20240229 또는 claude-3-sonnet-20240229를 선택해 주세요.

2. launchd 설정 파일 작성

다음으로, 위 Python 스크립트를 백그라운드에서 상주시키기 위한 launchd의 plist 파일을 작성합니다. ~/Library/LaunchAgents/com.ahic.codereviewer.plist라는 이름으로 저장해 주세요.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
...

보충:

• <string>/usr/local/bin/python3</string>은 본인의 Python 실행 파일 경로에 맞춰 변경해 주세요. which python3 명령어로 확인할 수 있습니다.

명령어로 확인할 수 있습니다. -
<string>/Users/ahic/scripts/code_reviewer.py</string>

은(는) 방금 작성한 Python 스크립트의 전체 경로(Full Path)로 교체해 주세요. -
StandardOutPath

와(과) StandardErrorPath

에 지정할 로그 디렉토리(예: /Users/ahic/logs/)

는 사전에 수동으로 생성해 두어야 합니다. -
EnvironmentVariables

키 안에 ANTHROPIC_API_KEY

를 직접 기술하고 있습니다. 환경 변수로 설정하는 것보다 보안성이 높기 때문에 이 방법을 권장합니다. YOUR_ANTHROPIC_API_KEY

부분을 실제 API 키로 교체해 주세요. -
WatchPaths

는 launchd 자체에 디렉토리 감시를 시키기 위한 것이지만, 이번에는 Python 스크립트의 watchdog가 감시를 수행하기 때문에 주석 처리했습니다.

launchd 등록 및 실행

plist 파일을 작성했다면, 다음 명령어로 launchd에 로드하여 스크립트를 시작합니다.

# 로그 디렉토리 생성 (필요한 경우)
mkdir -p /Users/ahic/logs
# launchd 에이전트 로드
...

이제 /Users/ahic/CodeReviewTarget 디렉토리에 Python 파일이 새로 생성될 때마다 Claude Code에 의한 자동 리뷰가 실행됩니다. 리뷰 결과는 /Users/ahic/logs/com.ahic.codereviewer.stdout.log에 기록됩니다.

주의할 점 (ハマりどころ)

launchd와 환경 변수

launchd는 로그인 셸(Login Shell)과는 다른 환경에서 스크립트를 실행합니다. 따라서 ~/.bash_profile이나 ~/.zshrc에서 설정한 환경 변수가 상속되지 않을 수 있습니다. API 키와 같은 중요한 정보는 plist 파일 내의 <key>EnvironmentVariables</key> 섹션에 직접 기술하거나, 스크립트 내에서 절대 경로를 사용하여 설정하도록 합시다.

경로 문제

launchd로부터 실행되는 스크립트는 예상하고 있는 현재 작업 디렉토리(Current Working Directory)와 다른 위치에서 실행될 수 있습니다. 스크립트 내에서 파일 경로를 다룰 때는 os.path.abspath(__file__) 등을 사용하여 스크립트 자신의 절대 경로를 취득하고, 이를 기준으로 다른 파일의 경로를 구축하는 것이 좋습니다. 본 기사의 스크립트에서는 TARGET_DIR 및 로그 파일의 경로를 절대 경로로 지정함으로써 이 문제를 회피하고 있습니다.

파일 이벤트 트리거

watchdog는 다양한 파일 시스템 이벤트를 포착하지만, 이번 목적은 '신규 파일 생성 시'로 한정됩니다. on_created 메서드로 이벤트 종류를 적절히 핸들링하여 의도하지 않은 리뷰가 실행되지 않도록 주의가 필요합니다. 또한, 파일이 완전히 쓰여지기 전에 리뷰가 시작되지 않도록 time.sleep()으로 짧은 대기 시간을 두는 것도 유효합니다.

Claude Code의 토큰 제한

매우 큰 파일을 리뷰 대상으로 삼을 경우, Claude Code의 토큰 제한에 도달할 가능성이 있습니다. 그럴 때는 파일을 분할하여 전송하거나, 사전에 주요 부분을 추출·요약한 후 API로 보내는 등의 궁리가 필요합니다. 이번 예시에서는 max_tokens=2000을 설정했지만, 파일 크기에 따라 조정해 주세요.

요약

본 기사에서는 Claude Code와 Python, 그리고 macOS의 launchd를 조합하여 특정 디렉토리에 새로 생성된 코드 파일의 자동 리뷰 시스템을 구축하는 방법을 소개했습니다.

이 시스템은 개발 초기 단계에서 AI에 의한 즉각적인 피드백을 제공하여 코드 품질 향상에 기여합니다. 또한, 인간 리뷰어의 부담을 경감하고 더 중요한 태스크에 집중할 수 있는 환경을 만들어 줍니다.

ahic의 AI 에이전트 운용술의 일환으로서, 꼭 여러분의 업무에도 이 자동 리뷰 시스템을 도입해 보세요. 작은 자동화의 축적이 일상의 생산성을 크게 향상시킬 것입니다.

토론 (Discussion)