이전 기사 『Claude Code와 Codex로 개인 앱 개발을 반자동화한 이야기』에서, Claude Code(기능 개발 담당)와 Codex(리뷰 담당)라는 두 가지 AI 에이전트에게 7일간 앱 개발을 맡긴 이야기를 썼습니다.

그 기사에서는 워크플로(Workflow) 전체의 설계와 운용 결과를 정리했지만, 실제로 이 시스템을 구축하고 가동하는 과정에서는 설계 시점에는 보이지 않았던 예상치 못한 벽이 차례차례 나타났습니다.

본 기사는 개발 워크플로 구축 및 운용에서 빠졌던 6가지 함정에 대해, 증상 → 원인 → 대응 순으로 정리한 것입니다. 비슷한 시스템을 구축하려는 분들이 같은 함정에 빠지지 않도록, 가능한 한 일반화된 형태로 남겨둡니다.

시스템의 전체 모습은 메인 기사인 『Claude Code와 Codex로 개인 앱 개발을 반자동화한 이야기』에, 개별 설계 판단의 근거는 『Claude Code와 Codex의 반자동 개발 워크플로 설계 상세』에 정리되어 있으므로, 그것들도 함께 참조해 주시기 바랍니다.

처음에 맞닥뜨린 벽은 설계의 전제 그 자체였습니다.

당초의 워크플로 설계에서는 main 브랜치에 대해 「PR 필수」, 「CI green 필수」, 「Codex에 의한 리뷰 승인 필수」, 「conversation resolved 필수」라는 브랜치 보호(Branch Protection)를 설정할 계획이었습니다. 여기에 더해, Codex가 리뷰 OK라고 판정한 PR은 GitHub의 auto-merge 기능으로 자동 머지(Merge)된다는 것이 상정된 흐름이었습니다.

하지만 검증해 본 결과, GitHub Free 플랜의 프라이빗 리포지토리(Private Repository)에서는 auto-merge도 branch protection도 애초에 이용할 수 없다는 사실이 판명되었습니다. Pro 이상의 유료 플랜으로의 전환이 필요합니다.

대응책으로는 이층 구조로 대체했습니다.

• 프롬프트(Prompt) 측 규칙: 「Claude Code는 자신의 PR을 머지하지 않는다」, 「Codex는 CI green을 확인한 후 머지한다」를 프롬프트에 명시하여 에이전트의 행동으로서 엄수하게 함
• 설정 측 대응: Claude Code에 대해 .claude/settings.local.json의 deny 리스트에 gh pr merge를 deny 등록하여, 오작동을 이중으로 방지함

GitHub 기능이 보장해 주어야 했던 안전장치를 사용할 수 없기 때문에, 프롬프트와 설정 파일의 2단계로 「머지해서는 안 될 측이 머지하지 않는」 상태를 담보하는 형태가 되었습니다. Pro 플랜으로 전환하면 한 번에 해결될 문제이지만, 개인 개발의 동작 확인 수준이라면 이 다층 방지로도 충분히 실용성을 견딜 수 있었습니다.

설계상의 전제가 무너진 사례는 하나 더 있었습니다.

당초에는 Codex와 Claude Code를 각각 별도의 GitHub App으로 발행하여, Codex 측의 App이 PR의 review API에 승인 코멘트를 남김으로써, GitHub의 self-review 금지 사양에 의해 「구현자와 승인자가 다른 인격임」을 담보할 계획이었습니다.

하지만 검증 과정에서 개인 개발 수준에서는 GitHub App의 발행 및 운용 비용이 과도하다고 판단하여, Codex와 Claude Code 모두를 나의 로컬 Mac 상에서 동일한 계정으로 구동하는 방침으로 전환했습니다.

이 전환으로 인해 한 가지 부작용이 발생합니다. 동일한 계정으로 구동되는 이상, GitHub 측의 self-review 금지 사양이 「Claude Code가 자신의 PR을 승인하는」 케이스를 막아주지 못합니다.

대응책으로서 PR review API를 통한 승인 게이팅(Gating) 자체를 포기하고, 다음과 같은 운용 방식으로 변경했습니다.

• 리뷰는 GitHub의 review API가 아니라 PR 코멘트로 남김
• 머지는 Codex의 PR 리뷰 배치(Batch)가 OK 판정 시 gh pr merge --merge --delete-branch로 직접 실행
• 「Claude Code는 자신의 PR을 머지하지 않는다」를 프롬프트 측 규칙으로서 엄수하게 함

GitHub가 본래 막아주어야 할 안전장치를 프롬프트의 행동 제약으로 대체하는 형태입니다. 에이전트가 순종적이라는 점에 대한 의존도가 높아지기 때문에, 프롬프트를 작성하는 측의 책임이 한 단계 무거워지는 구조적 변화가 일어났습니다.

각 배치(Batch)의 구현 초기에는 Codex의 자동화 과정에서 GitHub API를 직접 호출하는 구성을 일부 시도했습니다. 하지만 운영을 지속하면서 인증 오류(Authentication Error) / 권한 스코프(Permission Scope)의 불일치 / 환경 차이에 따른 응답 동작의 차이가 산발적으로 발생하기 시작했고, 이는 배치가 중단되는 주요 원인 중 하나가 되었습니다.

이에 대한 대응으로, Codex와 Claude Code 양측의 모든 GitHub 조작을 gh CLI 기반으로 통일했습니다. 구체적인 구조는 다음과 같습니다.

• 배치 시작 시 gh auth status -h github.com의 성공 여부를 반드시 확인하고, 실패할 경우 처리를 중단
• git remote URL이 예상대로인지 확인
• GIT_TERMINAL_PROMPT=0 git pull --ff-only origin main을 사용하여, 인증 프롬프트가 필요한 상태가 되면 확실히 중단

gh CLI로 통일하면 인증은 OS의 키체인(Keychain)으로 집약되며, API의 차이도 CLI 측에서 흡수해 줍니다. 직접 API를 호출하는 설계보다 CLI를 한 단계 거치는 것이 AI 에이전트(AI Agent)를 통한 운영과는 더 궁합이 좋다고 느꼈습니다.

이 워크플로(Workflow)에서는 Codex의 상세화 결과나 리뷰 결과를 Issue / PR의 **코멘트(Comment)**로 추가하며, 그 서두에 다음과 같은 마커(Marker) 행을 배치합니다.

## [Codex 상세화 (2026-05-22)]

Claude Code는 이 마커를 통해 최신 Codex 코멘트를 기계적으로 검색하도록 설계되었습니다.

그런데 어느 날, Issue의 상세화 코멘트를 Claude Code가 제대로 포착하지 못하는 현상이 발생했습니다. 원인을 추적해 보니, Codex가 임시 파일을 생성할 때 인덴트(Indent, 들여쓰기)가 포함된 heredoc(셸 스크립트 등에서 여러 줄의 텍스트를 다루는 표기법)을 사용하고 있었고, 이로 인해 파일 전체의 각 행 시작 부분에 공백이 들어간 상태로 gh issue comment --body-file에 전달되고 있었음이 밝혀졌습니다.

GitHub의 마크다운 렌더러(Markdown Renderer)는 행 시작 부분에 공백이 4개 이상인 행을 코드 블록(Code Block)으로 취급하기 때문에, 본래 H2로 해석되어야 할 ## [Codex 상세화 ...] 행이 장식 없는 일반 텍스트(코드 블록 내의 한 줄)로 취급되고 있었습니다. Claude Code 측의 검색 로직은 H2 구조로 남아 있는 마커 행을 기대하고 있었기에, 매칭되지 않는 코멘트만 양산되는 결과로 이어졌던 것입니다.

대응책으로 Codex의 프롬프트에 다음과 같은 고정 절차를 추가했습니다.

• 임시 파일 쓰기 시 인덴트가 포함된 heredoc / textwrap.dedent를 전제로 하는 문자열을 사용하지 말 것
• cat > /tmp/xxx.md <<'EOF' 이후에는 행 시작부터 마커 행을 시작할 것
• 게시 전에 head -n 1 /tmp/xxx.md의 출력이 마커 행과 완전히 일치하는지 확인할 것

단순히 행 시작 부분의 공백 문제처럼 보일 수 있지만, AI 에이전트 간의 문자열 기반 연동에서는 표기법의 미세한 차이가 곧바로 기능의 결여로 직결됩니다. 에이전트 간의 통신 프로토콜은 인간용 문서의 관습보다 더 엄격하게 준수하도록 만들어야 한다는 깨달음을 얻었습니다.

Claude Code를 스케줄된 작업(Scheduled Task)으로 실행할 때는 worktree 모드(작업 시작 시 격리된 브랜치와 디렉토리를 자동으로 생성하는 모드)를 사용하고 있었습니다. 이 모드에서는 작업 시작 시 claude/* 또는 cc/*로 시작하는 자동 명명 브랜치가 생성됩니다.

어느 날 배치가 완료된 후, 원격 저장소에 claude/abc123과 같은 명명 규칙 위반 브랜치가 남아 있는 것을 발견했습니다. 본래는 feat/YYYYMMDD-issue-12-15-18이라는 명명 규칙을 따라야 합니다.

원인은 단순했습니다. Issue 구현 배치의 프롬프트가 "현재 브랜치가 main이라면 신규 브랜치를 생성한다"라는 전제로 작성되어 있었고, worktree 모드로 실행된 자동 명명 브랜치에 대해서는 git checkout -b 대신 리네임(Rename) 처리가 전혀 포함되어 있지 않았던 것입니다. 결과적으로 Claude Code는 자동 명명된 브랜치 상태 그대로 구현을 진행했고, 마지막에 그 이름 그대로 push 해버린 것이었습니다.

대응책으로, 프롬프트의 작업 전 체크 로직을 다음과 같이 분기했습니다.

• 현재 브랜치가 main인 경우: git checkout -b <목표브랜치명>으로 새 브랜치를 생성
• 현재 브랜치가 claude/* 또는 cc/*로 시작하는 자동 명명 브랜치인 경우: git branch - m <목표브랜치명>으로 현재 브랜치를 리네임(rename)

여기에 더해, push 전에 정규 표현식 ^feat/[0-9]{8}-issue-[0-9-]+$로 브랜치명을 검증하고, 명명 규칙 위반 시 push 하지 않고 중단하는 체크 로직도 추가했습니다.

에이전트(Agent)를 구동하는 실행 환경(worktree 모드)의 동작을 프롬프트 측에서 모르는 상태로 실행하면, 출력(원격에 남는 브랜치명)에 부작용이 발생합니다. 프롬프트는 '자신이 동작하는 실행 환경'을 전제로 작성해야 한다는 당연한 사실을 실례를 통해 재확인한 셈입니다.

마지막 함정은 운영 초기 단계의 신중함이 그대로 지연으로 이어진 이야기입니다.

첫 시험 운영에서는 각 배치를 1일 1회로 시작했습니다. 폭주나 정체가 발생하지 않는 것을 이틀 정도 확인한 뒤, 3일째에 1일 6회(4시간 주기)로 전환하는 것이 당초 계획이었습니다.

실제로 해보니 1일 1회 시험 운영은 확실히 안정적으로 보였습니다. 하지만 빈도를 6배로 높이는 순간, 지금까지 언급한 함정 4(마커 행의 인덴트(indent) 문제)와 함정 5(worktree 모드의 브랜치 문제)가 연속해서 현상화되었습니다.

이유를 생각해 보면 단순했습니다. 1일 1회 빈도에서는 이러한 문제들을 우연히 밟지 않았거나, 설령 밟았더라도 단 1건뿐이었기에 제가 문제로 인식하지 못했을 뿐이었습니다. 빈도를 6배로 높이면 동일한 확률의 문제가 6배의 빈도로 드러나기 때문에, 재현성 있는 문제로 포착할 수 있게 됩니다. 저빈도에서는 잠복해 있던 문제가 빈도를 높이면 한꺼번에 표면화되는 현상이었습니다.

여기서 얻은 교훈은 빈도 설계(frequency design)를 2단계로 생각했어야 했다는 점입니다. 저빈도 운영은 워크플로우가 폭주하지 않는지 확인하는 데에는 확실히 유효했습니다. 하지만, 발생 빈도가 적은 잠복 버그(latent bug)는 좀처럼 알아차릴 수 없습니다. 시험 운영에 저빈도 스테이지만 두면, 후자를 놓친 채 본격적인 운영에 들어갈 위험이 있습니다.

저의 경우, 결과적으로 빈도를 높인 날에 함정 4와 함정 5가 나타나 그날 안에 수정할 수 있었습니다. 다만, 만약 시험 운영 기간을 1주일로 늘렸다면 이러한 함정들은 본격 운영에 들어간 뒤에 나타났을 가능성이 높습니다. 단기간이라도 고빈도 운영의 부하 테스트(load test)를 포함하는 스테이지를 시험 운영에組み込む(組み込む, 포함하는) 것이 이번 회고를 통해 남은 관점입니다.

6가지 함정을 되돌아보면, 성격이 다른 3가지 레이어로 나뉜다는 것을 알 수 있습니다.

• 설계 전제의 붕괴: 함정 1(Free 플랜 제약) / 함정 2(GitHub App 발행 포기)
• 에이전트 간의 통신 프로토콜 및 실행 환경의 전제: 함정 3(gh CLI 통일) / 함정 4(마커 행의 인덴트) / 함정 5(worktree 모드의 브랜치)
• 시험 운영의 빈도 설계: 함정 6(1일 1회 → 6배의 함정)

각각의 함정은 단독으로 보면 매우 사소한 것이지만, 1일 6사이클로 돌아가는 배치(batch)에서는 눈에 띄기 쉬워집니다. 반대로 말하면, 저빈도 배치에서는 이러한 문제들이 발견되지 않은 채 잠복한다는 뜻이기도 합니다.

반자동 개발의 빈도를 높이면 설계의 왜곡이 솔직하게 드러납니다. 이는 운영해 보기 전까지는 예상하지 못했던 부수적인 효과였습니다.

시스템 전체의 설계와 이러한 함정들이 어떤 맥락에서 등장했는지에 대해서는 메인 기사 『Claude Code와 Codex로 개인 앱 개발을 반자동화한 이야기』에 정리해 두었습니다. 개별 설계 판단의 근거를 심도 있게 다룬 『Claude Code와 Codex의 반자동 개발 워크플로우 설계 상세』와 함께 읽으시면, 동일한 시스템을 구축할 때의 해상도가 한 단계 높아질 것입니다.

이 글과 함께 참고해 주시기 바랍니다.