AI가 엔지니어 전부인 오픈소스 PR 검토기 IntentGuard를 Claude로 만든 경험기

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

창업자가 Claude를 단독 엔지니어로 활용해 GitHub Action 형태의 IntentGuard를 개발했고 이 도구는 PR 본문을 Linear 이슈와 대조해 ALIGNED/MISALIGNED/UNCLEAR를 판정하도록 설계됐다. 판정 엔진은 모델 출력을 강제된 툴 호출과 Zod 호환 JSON 스키마로 검증하고 실패 시 단일 교정 재시도를 적용했으며 106개의 키 없는 테스트를 포함해 재현 가능한 산출물을 확보했다. 보안 측면에서는 PR 텍스트를 비신뢰 입력으로 처리해 코드 체크아웃 금지, pull_request_target 비사용, 주입 방지용 구분자, 시크릿 마스킹을 적용했으며 이 점이 자동 생성된 보안 관행의 핵심이었다. 실무적 한계로는 GitHub UI의 자동화 방어와 인증 단계에서 사람의 개입이 필요했고 작성자는 코드·프롬프트·스펙 문서 공개와 플레이그라운드 링크를 통해 추가 검증을 허용했다.

실용적 조언

PR 콘텐츠를 외부 공격자가 제어하는 입력으로 가정해 설계하면 공격 표면을 줄일 수 있다. 구체적으로 코드 체크아웃을 금지하고 pull_request_target 이벤트를 쓰지 않으며 입력 구분자와 시크릿 마스킹을 도입하면 모델에게 전달되는 정보량과 위험을 통제할 수 있다. 또한 모델 출력을 엄격한 JSON 스키마에 매핑하고 검사 실패 시 단일 교정 재시도를 적용함으로써 불확실한 출력을 운영 가능 수준으로 끌어올릴 수 있다.
API 의존성을 최소화하기 위해 오프라인 모드나 API 키 없이 실행 가능한 테스트 스위트를 먼저 마련하면 개발 초기 단계에서 반복 검증이 쉬워진다. 브라우저 자동화가 실패하는 경우에는 자동 클릭 대신 폼을 미리 채워 인간이 마지막 제출을 하는 하이브리드 워크플로를 적용하는 것이 현실적인 대비책이다. 인증 관련 단계는 가능한 범위에서 토큰 교환을 사람 주도 프로세스로 유지하고 자동화 레벨을 점진적으로 높이는 것이 안전하다.

섹션별 상세

작성자는 Claude를 전체 엔지니어링 팀으로 삼아 리포지토리 초기화부터 마켓플레이스 게시까지 수행하는 실험을 진행했다. 이 실험은 약 5회 세션으로 이루어졌고 README 우선 접근과 오프라인 모드 설계 같은 단계별 산출물이 생성됐다. 실험 산출물로는 완성된 GitHub 리포지토리와 데모 GIF, 마켓플레이스 등록, 플레이그라운드 리포가 존재한다. 이 사례는 LLM을 엔지니어링 워크플로의 핵심 자동화 요소로 직접 적용할 때의 운영적 가능성을 보여준다.

구현 측면에서 Claude는 GitHub 및 Linear 커넥터와 판정 엔진을 작성했고 판정 엔진은 강제된 툴 호출과 Zod와 일치하는 JSON 스키마, 한 번의 교정 재시도와 결정적 폴백으로 동작하도록 설계됐다. 작성자는 모델 출력이 미리 정의된 스키마와 매핑되도록 유효성 검사를 구성했고 테스트 수를 106개까지 작성해 API 키 없이도 실행 가능하게 만들었다. 이 접근은 LLM 출력 불확실성을 스키마 기반 검증과 재시도로 관리하는 구체적 방법을 제시했다. 스키마-검증-재시도 패턴은 자동 리뷰 파이프라인에서 신뢰도를 높이는 실무적 조치로 작동한다.

보안 설계에서는 PR 텍스트를 공격자가 제어하는 입력으로 가정하는 원칙을 적용했고 그 결과 코드 체크아웃 금지, pull_request_target 이벤트 미사용, 주입 방지용 구분자 사용, 모델에 전달되기 전의 시크릿 마스킹 같은 방어가 자동으로 포함됐다. 작성자는 이러한 보안 조치가 모델에게 'PR 내용은 신뢰할 수 없는 입력'으로 명시한 한 줄의 스펙 이후에 모델로부터 나오기 시작했다고 기록했다. 이 관행은 LLM 기반 파이프라인에서 공격 표면을 줄이는 방식으로 구체화됐다. 보안 우선 설계는 자동화된 코드 생성·리뷰 시스템에서 필수적이라는 실무적 결론을 뒷받침한다.

자동화의 한계로는 GitHub UI의 자동화 방지 동작과 인증 단계에서 사람의 개입이 필요했던 점이 지적됐다. 모델은 브라우저 자동화 과정에서 Create 버튼 클릭이 무효화되는 상황을 반복했고 작성자는 최종적으로 폼을 미리 채운 뒤 사람이 클릭하도록 워크플로를 변경했다. 또한 인증·권한 부여 관련 작업은 작성자의 수동 개입이 계속 필요했으며 이는 완전한 무인 배포의 현실적 제약을 드러냈다. UI 자동화와 민감한 인증 흐름은 LLM 중심 자동화에서 외부적 병목으로 남는다.

용어 해설

GitHub Actions: — 소스 코드 변경 사항에 따라 자동 작업을 실행하는 CI/CD 워크플로 도구로서, 리포지토리 이벤트(예: pull_request)에 반응해 스크립트·검증·배포를 수행하며 이 프로젝트에서는 PR 리뷰 자동화를 트리거하는 런타임으로 사용됐다.
Zod 스키마 검증 라이브러리(Zod): — 타입 안전성을 제공하는 런타임 스키마 검증 라이브러리로서 JSON 입력을 선언적 스키마와 대조해 유효성 검사하고 이 프로젝트에서는 모델 출력을 엄격한 JSON 스키마와 대응시키는 검증층으로 활용됐다.
pull_request_target 이벤트(pull_request_target): — GitHub Actions의 이벤트 유형 가운데 하나로서 타깃 브랜치 컨텍스트에서 워크플로를 실행해 권한과 시크릿 접근권이 달라 보안상 위험을 유발할 수 있으며, 이 글에서는 이를 사용하지 않는 설계 선택으로 공격 표면을 축소했다.

언급된 도구

Claude추천

LLM을 엔지니어링 작업 전체에 투입해 리포지토리 생성·커넥터 작성·판정 엔진 구현 등을 수행

GitHub Actions추천링크

PR 이벤트 기반 자동화와 Marketplace 배포 트리거로 사용

Linear중립

PR이 참조하는 티켓과 스프린트를 매칭하기 위한 이슈 트래커 연동 대상

Zod추천

모델 출력의 JSON 스키마 검증을 위해 사용된 스키마 라이브러리

언급된 리소스

GitHubIntentGuard 저장소

DemoIntentGuard Playground