이 기사는 개인 개발에서 시도하고 있는 Codex + GitHub Issue 주도 개발(Issue-driven development)의 운용 메모입니다. 지난번에는 여러 Issue를 다루기 위해 상위 Issue(Parent Issue)를 제어 측면에서 활용하는 방법에 대해 썼습니다. 이번에는 그 상위 Issue에 배치하는 CODEX_STATUS와 parallel-safe / blocked / needs-human-review의 구분 방법을 작성합니다.

전제 기사:

Codex에 여러 Issue를 전달하면 PR(Pull Request) 생성까지는 빠릅니다.

하지만 PR이 빠르게 나올수록, "그것이 지금 진행해도 되는 Issue인가?"를 사전에 확인하지 않으면 위험합니다.

저는 그 확인을 위해 상위 Issue에 두는 작은 상태 표를 사용하고 있습니다.

이 기사에서 다루는 것은 Codex에 작업을 넘기기 직전의 판단 재료입니다. 측정 방법은 별도의 기사에서 다룹니다.

A: label을 붙이면 AI도 판단할 수 있지 않을까?

B: label은 입구가 됩니다. 하지만 blocked by, blocks, PR, notes까지 확인하지 않으면 지금 진행해도 되는지 알 수 없었습니다.

Codex에게 병렬로 PR을 만들게 하면 빠르게 진행될 때가 있습니다.

단, 병렬화해서는 안 되는 Issue까지 동시에 진행하면 contract(계약)나 저장 형식이 깨지기 쉽습니다.

저는 최근 상위 Issue에 CODEX_STATUS라는 상태 표를 두어 다음과 같이 구분하고 있습니다.

• 먼저 종료해야 할 critical path
• 병렬로 진행해도 좋은 parallel-safe
• 구현하지 않고 중단하는 blocked
• merge 판단을 인간에게 남겨두는 needs-human-review

CODEX_STATUS는 GitHub의 정식 기능이 아닙니다. 저만의 운용 명칭입니다. 상위 Issue의 본문 또는 코멘트에 두는 AI 작업용 상태 표로 사용하고 있습니다.

• Codex에 여러 Issue를 전달하고 있는 사람

• parallel-safe나 blocked를 label만으로 판단하기에 불안함이 있는 사람

• PR을 작게 만들고 싶지만, 동일한 contract를 건드리는 병렬 PR은 피하고 싶은 사람

• merge 판단이나 release gate는 인간 측에 남겨두고 싶은 사람

• 상위 Issue에 두는 CODEX_STATUS table의 최소 형태

• critical-path / parallel-safe / blocked / needs-human-review의 구분 방법

• Codex에 작업 전 확인을 요청하는 프롬프트(依頼文) 템플릿

A: GitHub Projects나 sub-issues로 관리하면 되지 않을까?

B: 그것도 선택지라고 생각합니다. 다만, Codex에게 짧게 읽히기 위해서는 상위 Issue 상의 하나의 표가 다루기 쉬웠습니다.

예를 들어, 다음과 같은 표를 둡니다.

| ID | Issue | Lane | State | Blocked by | Blocks | Agent | PR | Notes |
|---|---|---|---|---|---|---|---|---|
| P7-01 | stable node id contract | Contract | blocked | human review | P7-03, P7-04 | - | - | 저장 형식 미확정 |
...

이것은 인간을 위한 진척 표이기도 하지만, Codex에게도 중요한 컨텍스트(Context)가 됩니다.

특히 효과적인 것은 Blocked by와 Blocks입니다.

Issue 목록만 보면 "전부 open" 상태로 보이지만, CODEX_STATUS를 보면 어디서 멈춰야 할지를 알 수 있습니다.

AI 병렬 개발에서 가장 위험한 것은 "병렬화해서는 안 되는 것까지 병렬화하는 것"이었습니다.

그래서 Issue에 다음과 같은 의미를 부여하도록 했습니다.

예를 들어, 다음과 같은 작업은 critical path (임계 경로)가 되기 쉽습니다.

• data format contract (데이터 포맷 계약)
• parser (파서) / serializer (직렬화 도구) / validation (검증) / patch (패치)에 걸친 변경
• release gate (릴리스 게이트)
• parent issue (상위 이슈) coordination (조정)
• human review (인간 검토)가 필요한 설계 판단
• tester (테스터)가 다음에 접하게 될 동선, 선택 상태, 저장·복원, release (릴리스) 전의 주요 조작

반대로, 다음과 같은 작업은 parallel-safe (병렬 작업 안전)가 되기 쉽습니다.

• docs-only (문서 전용) design note (설계 노트)
• 표시 문구, 빈 상태, docs (문서)에 가까운 경미한 UI polish (UI 다듬기)
• i18n (국제화) foundation (기반)의 재점검
• tester feedback template (테스터 피드백 템플릿)
• export (내보내기) 형식 조사

물론, 실제로는 Issue (이슈) 본문을 읽을 필요가 있습니다.

label (라벨)만으로 완벽하게 판단하지는 않습니다.

다만, label이 있는 것만으로도 Codex에 전달할 초기 판단이 상당히 안정됩니다.

A: 매번 이런 요청을 쓰는 것은 번거롭지 않나요?

B: 번거롭습니다. 하지만 contract (계약)나 release gate (릴리스 게이트)를 건드리는 Issue (이슈)에서 너무 앞서 나가는 것보다는 비용이 저렴하다고 느끼고 있습니다.

Issue (이슈)를 AI에게 전달할 때, 최근에는 단순히 "이 Issue를 구현해줘"가 아니라, 다음과 같은 요청을 하고 있습니다.

Parent issue (상위 이슈)를 확인해 주세요.
1. CODEX_STATUS를 읽고, 이번 Issue가 critical-path / parallel-safe / blocked / needs-human-review 중 어느 것인지 판정해 주세요.
2. downstream contract (하류 계약), 저장 형식, API, schema (스키마), release gate (릴리스 게이트)를 건드리는 경우에는 구현 전에 중단 조건을 명시해 주세요.
...

이 요청문을 넣어두면, 적어도 Issue (이슈) 단체만 보고 너무 앞서 나가는 리스크를 낮추기 쉽습니다.

포인트는 "작업을 시작하기 전에, 작업을 해도 좋은 상태인지 판정하게 하는 것"입니다.

Codex를 병렬로 진행시킬 때는, 쓰기 범위(writing scope)를 나눕니다.

나쁜 예.

Issue A: parser (파서)를 변경한다
Issue B: serializer (직렬화 도구)를 변경한다
Issue C: validation (검증)을 변경한다

이 세 가지는 동일한 contract (계약)를 건드리고 있을 가능성이 높으므로, 병렬로 진행하면 위험합니다.

좋은 예.

Issue A: i18n (국제화) dictionary (사전)와 package.nls를 추가한다
Issue B: tester feedback template (테스터 피드백 템플릿)을 docs (문서)에 추가한다
Issue C: export (내보내기) 형식 조사표를 docs (문서)에 추가한다

쓰기 범위와 계약 측면이 분리되어 있다면, 병렬로 진행하기 쉽습니다.

Codex가 PR (풀 리퀘스트)을 만들 수 있게 되면, merge (병합)까지 자동화하고 싶어집니다.

하지만 현재 운용에서는 다음 사항들은 인간의 판단을 남겨둡니다.

needs-human-review가 붙은 contract (계약) 변경 - stable ID와 같은 저장 형식 변경

• release tag (릴리스 태그) / public release (공개 릴리스)
• billing/spending limit (결제/지출 한도) 등 환경 유래 failure (실패)를 포함하는 CI (지속적 통합) 판단
• parent issue (상위 이슈)의 critical path (임계 경로) 업데이트

AI에게 맡기는 것은 작업과 검증의 가속화입니다.

어떤 contract (계약)를 채택할지, 어떤 release gate (릴리스 게이트)를 통과할지는 아직 인간이 확인합니다.

갑자기 큰 규모의 운용으로 바꾸지 않아도 됩니다.

처음에는 상위 Issue (이슈)에 이 표만 두어도 충분하다고 생각합니다.

| ID | Issue | Lane | State | Blocked by | Blocks | Agent | PR | Notes |
|---|---|---|---|---|---|---|---|---|
| issue-a | Contract | blocked | human review | issue-c issue-d | - | - | human review 대기 |
...

그리고 Issue (이슈)에는 최소한 이 label (라벨)을 붙입니다.

critical-path
parallel-safe
blocked
...

이것만으로도 AI에게 전달할 때의 판단 재료가 늘어납니다.

label (라벨)은 입구일 뿐, 판단 그 자체는 아닙니다.

Issue (이슈) 본문, 상위 Issue (이슈), 관련 PR (풀 리퀘스트), CODEX_STATUS를 읽을 필요가 있습니다.

상위 Issue (이슈)의 상태가 오래되면, Codex는 오래된 전제를 바탕으로 동작합니다.

따라서 PR (Pull Request) 본문에 「상위 Issue의 CODEX_STATUS 업데이트 제안」을 작성하도록 하고 있다. 상위 Issue를 직접 편집하게 하는 것보다, 리뷰 (review) 시에 반영 누락을 찾아내기가 더 쉽기 때문이다.

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

정말로 downstream (하류 공정)을 중단시키는 요소로만 범위를 좁혀야 한다.

parser (파서) / serializer (시리얼라이저) / validation (검증) / patch (패치)와 같은 횡단 계약 (cross-cutting concerns)은 병렬화하기 어렵다.

이 부분은 deep + review (심층 + 리뷰) 대상으로 취급한다.

Codex에게 병렬로 작업을 맡기기 전에, Issue를

critical-path

/ parallel-safe

/ blocked

/ needs-human-review

로 분류해 두면, 진행해도 좋은 작업과 중단해야 할 작업을 분리하기 쉽다.

중요한 것은 라벨 (label)을 붙이는 행위 자체가 아니다.

상위 Issue의 CODEX_STATUS, Issue 본문, 관련 PR을 읽게 한 뒤, Codex에게 「이 작업을 지금 진행해도 되는가」를 먼저 판정하게 하는 것이다.

처음부터 완벽한 운영 체계를 갖출 필요는 없다.

우선 Codex에게 Issue를 넘기기 전에 다음 세 가지만 확인하게 하는 것만으로도, 사고를 상당히 줄일 수 있다.

이 Issue는 무엇에 의해 blocked (차단)되어 있는가
이 Issue는 무엇을 blocks (차단)하고 있는가
이 PR 이후에 상위 Issue로 무엇을 되돌려주어야 하는가

이 기사에서는 Codex에게 넘기기 전의 상태표와 의뢰문을 작성하였다.

속편에서는 이 운영이 효과적인지를 「몇 배 빨라졌는가」가 아니라, 제어 품질 (control quality)로서 어떻게 측정할지를 다룬다.

• CODEX_STATUS 업데이트를 어디까지 자동화할 수 있는가
• GitHub Projects나 sub-issues (하위 이슈)와의 활용 구분
• 다인원 팀에서 동일한 표를 유지보수할 수 있는가