Codex로 PR을 병렬로 생성하기 전에, 상위 Issue를 제어면(Control Plane)으로 활용하는 이야기

이 기사는 개인 개발에서 시도하고 있는 Codex + GitHub Issue 기반 개발(Issue-driven development)의 운용 메모입니다. AI에게 Issue를 전달하는 것만으로는 여러 Issue의 순서나 의존 관계가 무너지기 쉬워졌기 때문에, 상위 Issue를 제어면(Control Plane)으로 사용하게 된 이야기를 쓰고자 합니다. 실제 경험과 아직 검증되지 않은 운용 가설을 나누어 기록합니다.

이전 기사: AI에게 "적당히 고쳐줘"라고 부탁하는 것을 그만두고, GitHub Issue를 작업의 정본(Source of Truth)으로 삼기

Codex로 작은 PR을 여러 개 만들게 되면서, 처음에 곤란했던 것은 "작업할 수 있는 Issue가 많다는 것"이 아니라, "어느 것을 먼저 진행해도 되는지 모른다는 것"이었다.

Issue 단독으로는 Goal(목표)이나 Scope(범위)를 작성한다. 그럼에도 불구하고 여러 Issue가 얽히게 되면, contract(계약) 변경, docs(문서) 정비, tester feedback(테스터 피드백), release gate(릴리스 게이트)가 동일한 목록에 나열되어 보이게 된다.

그래서 최근에는 상위 Issue를 단순한 요약본이 아니라, AI 작업의 제어면(Control Plane)으로 사용하고 있다.

이 기사에서 다루는 것은 상위 Issue, critical path(임계 경로), parallel lane(병렬 레인)의 개념이다. CODEX_STATUS의 자세한 표나 Codex에 대한 요청 문구 템플릿은 후속편에서 나누어 작성하겠다.

Q: Issue에 Goal과 Scope를 적어두면 충분하지 않은가?

A: 단발성 Issue라면 상당히 효과적이다. 다만, 여러 Issue가 동시에 움직이기 시작하면 그것만으로는 순서와 의존성을 파악할 수 없게 되었다.

AI에게 Issue를 전달하기만 하면 단발성 작업은 진행된다.

하지만 개발 규모가 조금 커지자 다음과 같은 문제들이 나타났다.

• 어떤 Issue가 먼저 끝나야 하는지 알 수 없다
• 병렬로 진행해도 되는 Issue와 기다려야 하는 Issue가 섞인다
• Codex가 서로 다른 PR을 만들면, 상위 Issue 측의 진척도를 추적하기 어렵다
• contract 변경이나 release gate처럼 인간의 리뷰가 필요한 것까지 기세 좋게 진행되어 버릴 것 같다

그래서 지금은 GitHub Issue를 단순한 태스크가 아니라, 개발 그래프(Development Graph)로 취급하고 있다.

나의 운용 방식에서는 상위 Issue에 다음 사항들을 둔다.

• critical path (임계 경로)
• parallel lane (병렬 레인)
• blocked / deferred / done 상태
• 담당 agent 및 PR
• merge(병합) 전에 필요한 gate
• 다음 병렬 wave

Issue 기반 개발이라기보다, Issue를 제어면으로 삼은 Codex 병렬 개발에 가깝다.

이런 분들에게 추천합니다:

• Codex / Claude Code / GitHub Copilot coding agent 등으로 PR을 만들고 있는 분
• GitHub Issue를 사용하고 있지만, 여러 Issue가 얽히면 우선순위가 무너지는 분
• 작은 PR을 병렬로 진행하고 싶지만, 어디서 멈춰야 할지 망설여지는 분
• 상위 Issue나 label을 AI 개발의 판단 자료로 사용하고 싶은 분

이 기사에서 배우는 내용:

• 상위 Issue를 "작업 목록"이 아닌 "제어면"으로 사용하는 사고방식
• critical path / parallel lane / blocked를 나누는 최소 패턴
• Codex에게 진행시키게 할 Issue와 인간 리뷰로 돌려보낼 Issue를 나누는 방법

종류	내용
실체험	private repo에서 GitHub Issue를 작업 단위로 삼아, Codex로 여러 PR을 진행 중
...

Q: Issue를 세분화하면 병렬로 진행하기 쉬워지지 않을까?

A: 세분화하는 것만으로는 모든 것이 같은 무게로 보인다. 문제는 입도(Granularity)뿐만 아니라, 어떤 것이 후속 작업을 막고 있는가였다.

이전 단계에서는 AI에게 "적당히 고쳐줘"라고 부탁하는 것을 그만두고, GitHub Issue를 작업의 정본으로 만드는 것을 중시했다.

Issue에는 최소한 다음을 작성한다.

Goal
Scope
Done
...

이것은 지금도 유효하다.

단발성 Issue라면 이 형식만으로도 상당히 진행하기 쉽다.

다만, VS Code 확장, Desktop, Obsidian Plugin, parser contract, release gate와 같이 여러 레인이 얽히기 시작하면 Issue 단독으로는 부족해졌다.

여러 Issue를 나열하면 모두가 같은 무게로 보인다.

하지만 실제로는 다르다.

예를 들어, 다음과 같은 Issue가 동일한 목록에 나열된다.

• stable node id contract
• Obsidian Plugin PoC
• host adapter 설계
• i18n foundation
• tester feedback
• release gate
• export 품질
• map-aware diff

이때 AI에게 단순히 "open issue를 진행해줘"라고 전달하는 것만으로는 위험하다.

먼저 contract(계약)를 결정하지 않으면 진행해서는 안 되는 Issue가 있는가 하면, 병렬로 진행해도 좋은 docs/design issue도 있다.

추상적인 논의만으로는 이해하기 어려우므로, private repo에서 실제로 사용 중인 Issue를 공개 가능한 수준으로 익명화하면 다음과 같습니다.

종류	실례	수행한 작업	처리 방식
critical path	tester feedback 이후의 UI gate	toolbar 표시, 선택 위치의 reveal, zoom 조작과 같이 다음 tester 확인을 직접적으로 차단하는 UX 결함을 수정함	후속 확인 전에 먼저 종료함
...

이 표를 통해 전달하고 싶은 점은, critical-path가 붙은 Issue만이 중요한 것이 아니라는 점이다.

release evidence나 runbook과 같은 docs/evidence 계열은 product code를 직접 변경하지 않으므로 병렬로 진행하기 쉽다. Codex에 맡기기에 궁합이 좋다.

반면, stable node id contract와 같은 작업은 겉보기에는 "ID 저장 형식을 결정할 뿐"처럼 보이지만, 실제로는 parser, serializer, validation, patch, webview protocol에 영향을 미친다. 이런 Issue는 의욕만 앞서 구현에 들어가기보다, 먼저 contract boundary(계약 경계)를 분리하여 review 대기 상태로 만드는 것이 더 안전했다.

또한, tester feedback 이후의 UX 수정은 사용자가 다음에 접하게 될 경험을 직접적으로 차단하기 때문에 critical path로 취급했다. 모든 것을 병렬로 만드는 것이 아니라, 먼저 종료해야 할 것을 상위 Issue 측에서 명시한다.

나의 운영 방식에서는 이와 같이 Issue를 다음 3가지 유형으로 나누고 있다.

지금 바로 종료해야 하는 critical path
병렬로 진행 가능한 docs / evidence / polish
review 없이 진행해서는 안 되는 contract 변경

A: 상위 Issue는 진행 메모로 사용하면 되지 않나요?

B: 처음에는 그것으로 충분했다. 다만, Codex에 작업을 넘긴다면 "다음에 무엇을 해도 되는지"를 읽을 수 있는 형태로 만드는 것이 더 안정적이었다.

나의 private repo에서는 상위 Issue에 phase 전체의 상태를 적고 있다.

예를 들어, 상위 Issue에는 다음과 같은 정보를 둔다.

P7-01 -> P7-06

이것은 "P7-01에서 P7-06으로 진행함"을 나타내는 critical path이다.

나아가 병렬 레인(parallel lane)도 갖춘다.

Import/Export: P7-01, P7-03
Integrations: P7-02
Map Semantics: P7-04
...

이런 형식을 갖추면 Codex에 전달할 때도 "어떤 Issue를 할 것인가"뿐만 아니라, "어떤 Issue는 병렬로 해도 되는가", "어떤 것이 gate인가"를 판단하기 쉬워진다.

도식화하면 흐름은 대략 다음과 같다.

[IMG:1]

중요한 점은 하위 Issue를 모두 동일하게 취급하지 않는다는 것이다.

상위 Issue는 "작업 목록"이 아니라, 어떤 하위 Issue를 먼저 진행할지, 어떤 것을 병렬로 해도 될지, 어디서 인간의 판단으로 돌아갈지를 나타내는 제어면 (Control Plane)으로 사용한다.

• 상위 Issue에 상태가 모여 있으므로 매번 긴 설명을 할 필요가 없다.
• docs, evidence, 경미한 polish와 같이 본류의 contract를 건드리지 않는 것을 찾기 쉽다.
• blocked나 needs-human-review가 있으면 AI가 과하게 진행하는 것을 방지하기 쉽다.
• Issue 단위로 Scope(범위)가 결정되므로 PR의 범위도 작게 유지하기 쉽다.

모든 것을 critical path로 설정하면 아무것도 병렬화할 수 없게 된다.

critical path는 "중요한 Issue"가 아니라, "놓치면 후속 Issue나 release gate가 멈추는 Issue"로 취급한다.

상위 Issue는 편리하지만, 업데이트되지 않으면 오히려 위험해진다.

PR 본문에 "상위 Issue의 업데이트 제안"을 쓰도록 해두면, review 시에 반영 누락을 찾기 쉽다.

label은 입구일 뿐, 판단 그 자체는 아니다.

Issue 본문, 상위 Issue, 관련 PR을 읽을 필요가 있다.

AI 개발에서 Issue를 사용하는 것만이라면 단발성 작업은 진행하기 쉬워진다.

하지만 여러 Issue가 얽힌 개발에서는 Issue를 작업 단위로서뿐만 아니라, 의존 관계와 병렬화의 제어면 (Control Plane)으로서 다룰 필요가 생겼다.

현재 나의 운영 방식에서는 상위 Issue에 critical path(임계 경로)와 parallel lane(병렬 경로)을 배치하고, Codex가 해당 상태를 읽게 한 뒤 작업을 수행하도록 하고 있다.

이것은 아직 완성된 방법론은 아니다.

다만, AI에게 "Issue를 전달하는" 단계에서, "Issue graph를 읽게 하여 병렬 개발을 수행하는" 단계로 진보해 왔다는 감각이 있다.

먼저 작게 시도해 본다면, 상위 Issue에 다음 세 줄만 배치하는 것부터 시작해도 좋다고 생각한다.

critical path: 먼저 종료하지 않으면 후속 작업이 중단되는 Issue
parallel lane: docs/evidence 등, 병렬로 진행하기 쉬운 Issue
blocked: contract(규약)나 저장 형식이 미확정되어 중단하는 Issue

이 기사에서는 상위 Issue를 제어면(Control Plane)으로 삼는 사고방식에 대해 작성하였다.

속편에서는 상위 Issue에 배치할 상태표 CODEX_STATUS와 Codex에 전달할 요청문 템플릿을 작성할 예정이다.

• 이 운영을 통해 PR lead time(리드 타임)이 얼마나 단축되는가
• review(리뷰) 부하가 줄어드는가
• 다수 인원 팀에서도 성립하는가
• GitHub sub-issues나 Projects와의 구분 사용법