Claude Code를 쓰는 팀 대부분은 여전히 인터랙티브 REPL 방식에 머물러 있다. 프롬프트를 치고, 결과를 확인하고, 다시 조정하는 방식. 이건 탐색적 작업엔 맞다. 하지만 CI/CD 파이프라인에 AI를 넣고 싶다면 다른 모드가 필요하다. Claude Code의 헤드리스 모드, 즉 -p 플래그가 그 답이다.
-p(또는 --print) 플래그를 쓰면 Claude는 대화 없이 입력을 받아 stdout으로 결과를 뱉고 종료한다. 같은 모델, 대화 없음, 입력과 출력만 남는다. cat src/lib/auth.ts | claude -p "Review this for security issues" 한 줄이면 파일을 파이프로 넘겨 보안 리뷰를 받을 수 있다. --output-format json 옵션을 붙이면 결과를 구조화해서 jq로 파싱하거나 다음 스텝으로 넘기는 것도 가능하다. dev.to에 공개된 stacknotice의 실전 스크립트들은 이 구조를 세 가지 자동화로 보여준다.
첫째는 changelog 자동 생성이다. git log --oneline --since로 커밋 목록을 뽑아 Claude에 넘기면 Features, Bug Fixes, Improvements로 그룹핑된 마크다운 항목을 받아 CHANGELOG.md에 prepend한다. 둘째는 커밋 메시지 생성이다. git diff --staged를 파이프로 넘기면 conventional commit 형식의 메시지를 돌려준다. git commit -m "$(git diff --staged | ./scripts/commit-msg-gen.sh)" 한 줄로 스테이징된 변경사항을 그대로 커밋할 수 있다. 셋째는 PR 리뷰 자동화다. 변경된 파일을 순회하며 각각 버그, 보안 이슈, 에러 핸들링 누락을 검토한 리포트를 pr-review.md로 생성한다. GitHub Actions에서는 ANTHROPIC_API_KEY를 시크릿으로 넣고 --dangerously-skip-permissions 플래그와 함께 실행하면 된다.
여기서 짚고 넘어갈 게 있다. 헤드리스 모드가 모든 상황의 답은 아니다. 명확하게 정의된 태스크, 배치 파일 처리, 알려진 입출력 형식이 있는 자동화엔 -p가 적합하다. 반면 컨텍스트가 복잡하거나 방향을 수정해가며 진행해야 하는 리팩터링 작업엔 인터랙티브 세션이 낫다. 단일 -p 호출에 복잡한 컨텍스트를 억지로 욱여넣으면 품질이 급격히 떨어진다. 도구의 적합한 사용 경계를 설계하는 것이 먼저다.
그런데 AI가 코드를 생성하거나 리뷰하는 것만으로 품질이 보장된다고 보면 안 된다. 여기서 두 번째 문제가 등장한다. AI가 생성한 코드는 기존 정적 분석 도구가 잡지 못하는 의미론적 결함을 품고 있다. dev.to에 소개된 VibeGuard 사례가 이 문제를 정확히 짚는다.
예시는 직관적이다. save_user()라는 함수가 있다. 입력 검증도 하고, 로그도 찍고, {"status": "saved"}를 반환한다. Pylint, Mypy, Flake8 모두 통과한다. 그런데 실제로 데이터베이스에 INSERT하는 코드가 없다. 함수 이름은 저장을 약속하지만 아무것도 저장하지 않는다. 이게 MISSING_WRITE 패턴이다. LLM은 save_user 함수 주변의 패턴—검증, 로깅, 성공 응답—은 정확하게 생성하지만, 핵심 쓰기 연산을 빠뜨리는 경우가 있다. 구조적으로 완벽해 보이지만 의미적으로 비어 있는 코드다.
MISSING_WRITE 외에도 FAKE_ASYNC(async 함수 안에 await 없이 블로킹 콜), STUB_SKELETON(항상 True나 빈 객체를 반환하는 미완성 로직), INPUT_OUTPUT_DISCONNECTED(파라미터가 반환값에 영향을 주지 않음), DEAD_CALL_RESULT(함수 결과를 무시하고 다음 로직이 그대로 진행) 같은 패턴들이 있다. 모두 AI 생성 코드에서 반복적으로 나타나고, 모두 기존 린터가 잡지 못한다. 구문이 유효하기 때문이다.
VibeGuard의 접근은 간단하다. 스캔 API에 파일을 올리면 패턴 탐지 결과를 JSON으로 반환한다. 이 리포트를 Cursor나 Claude에 그대로 붙여넣으면 AI가 스스로 수정한다. 스캔 → 리포트 → AI 수정 → 재스캔까지 30초. GitHub Actions에 Moonsehwan/aina-vibeguard-action@v1을 추가하면 이 루프가 CI에 들어간다. 현재 베타 기간 중 무료 키(vg_free_test)를 제공하며 Python, JS, TS, Go, Java 등 9개 언어와 48개 패턴을 지원한다.
두 가지를 합치면 하나의 파이프라인 설계가 나온다. Claude Code 헤드리스 모드로 커밋 메시지 생성, changelog 업데이트, PR 리뷰 자동화를 처리하고, VibeGuard로 AI 생성 코드의 의미론적 결함을 CI 단계에서 차단한다. AI가 코드를 만들고, AI가 그 코드를 검토하고, 의미론적 패턴 스캐너가 AI가 놓친 구멍을 막는 구조다. 도구를 교체하는 것이 아니라 루프를 닫는 것이다.
실행 순서를 정리하면 이렇다. 먼저 -p 플래그 기반 스크립트를 한두 개만 만들어서 실제 워크플로우에 붙여보라. changelog 생성이나 커밋 메시지 생성이 진입점으로 적합하다. 그 다음 CI에 VibeGuard 스캔을 추가해서 AI 생성 코드에서 반복되는 패턴이 무엇인지 데이터를 모아라. 패턴이 보이면 그때 프롬프트를 고치거나 리뷰 기준을 강화하면 된다. AI를 파이프라인에 심는 것은 한 번의 설정이 아니라 루프를 점진적으로 좁혀가는 과정이다.