Codex로 PR을 양산하기 전에, Issue·상태·판단 로그를 연결하는 「문맥 허브(Context Hub)」를 만들기

이 기사는 제가 개인 개발에서 시도하고 있는 Codex + GitHub Issue 기반 개발(Issue-driven development)의 전체상을 AI에게 정리하게 하며 작성한 초안입니다. 이 기사에서는 실제 경험, 가설, 아직 검증되지 않은 운용안을 구분하여 남깁니다.

Codex나 ChatGPT를 사용하게 되면서 작업 그 자체는 상당히 빨라졌습니다.

한편, 작업이 빨라질수록 「무엇을 풀 것인가」, 「누가 결정하는가」, 「어디까지 맡길 것인가」가 모호한 상태라면 오히려 망설임이 늘어나는 상황도 있었습니다.

최근 제 생각으로는, AI 시대에 가치가 올라가는 사람은 무엇이든 스스로 처리하는 사람이 아니라, 문맥(Context)을 정리하여 Issue, 상태표, 판단 로그를 AI에게 전달할 수 있는 형태로 옮겨가는 사람이 아닐까 생각합니다.

이 기사는 그 생각을 정리하는 상위(Parent) 기사입니다.

이 기사에서는 개별 테크닉을 심층적으로 다루기보다, Codex를 사용한 AI 개발 운용의 전체 지도(Map)를 그립니다.

개별적인 이야기는 하위(Child) 기사로 나누어 두었습니다.

테마	하위 기사
작업 단위	AI에게 "적당히 고쳐줘"라고 부탁하는 것을 그만두고, GitHub Issue를 작업의 정본(Source of truth)으로 삼았다
...

제 안에서는 이 구조를 「상위 Qiita / 하위 Qiita」와 같이 파악하고 있습니다.

상위 Qiita = 전체 지도, 사상, 동선
하위 Qiita = 개별 테마의 실천 로그, 템플릿, 실패담

GitHub Issue에서 말하는 상위 Issue / 하위 Issue와 비슷합니다.

상위 Issue가 전체 목적, 의존 관계, 진척도를 갖는 것처럼, 상위 Qiita에서는 시리즈 전체의 사고방식과 읽는 순서를 배치합니다.

처음에는 개별 기사를 쓰는 것만으로도 충분하다고 생각했습니다.

실제로 처음에 쓴 것은 「AI에게 적당히 고쳐줘라고 부탁하는 것을 그만두고, GitHub Issue를 작업의 정본으로 삼았다」라는 기사입니다.

그 후, Codex로 복수의 PR(Pull Request)을 만들게 되면서 화제가 조금씩 나뉘었습니다.

• Issue를 어떻게 작성할 것인가
• 상위 Issue에서 어떻게 제어할 것인가
• CODEX_STATUS로 어떻게 상태를 볼 것인가
• 견적(Estimate)의 논점을 AI와 어떻게 맞출 것인가
• 어디에서 내가 판단할 것인가
• 어디에서 시스템으로 넘길 것인가

개별 기사로는 쓸 수 있습니다.

다만, 개별 기사만 있으면 나중에 읽는 사람에게는 「이것이 무엇의 일부인가」가 보이기 어렵습니다.

그래서 시리즈 전체의 입구로서 상위 Qiita를 두는 것이 좋다고 생각했습니다.

Codex를 사용하면 구현, 조사, 수정, 테스트 추가, 문서 업데이트는 상당히 빨라집니다.

이것은 편리합니다.

하지만 제가 곤란했던 것은 「AI가 느린 것」이 아닙니다.

오히려 AI가 빠르기 때문에 다음과 같은 문제가 더 잘 보이게 되었습니다.

• 어떤 Issue를 먼저 진행해야 할지 모르겠다
• 병렬로 진행해도 되는 PR과 기다려야 하는 PR이 섞인다
• 변경해도 되는 범위가 모호한 채로 작업이 진행된다
• contract(규약)나 저장 형식과 관련된 변경까지 기세로 진행해버릴 것 같다
• merge(병합) 판단이나 release gate(배포 관문)까지 AI에게 흘러가 버릴 것 같다
• 나중에 「왜 이 변경을 했는가」를 추적하기 어렵다

즉, 작업 속도가 올라갈수록 작업의 전후에 있는 문맥(Context)이 중요해집니다.

여기서 말하는 문맥 허브(Context Hub)는 사람의 역할 명칭이라기보다, Codex에 전달할 전제 조건을 정리해 두는 구조를 말합니다.

제 안에서는 다음과 같이 파악하고 있습니다.

Issue, PR, 판단, AI, 지식(Knowledge)을 연결하여, 다음으로 진행할 수 있는 상태를 만드는 접속점

Codex에 작업을 넘기기 전에 다음 사항들이 갖춰진 상태입니다.

• 무엇을 풀 것인가
• 무엇을 풀지 않을 것인가
• 어디를 변경해도 되는가
• 어디를 변경해서는 안 되는가
• 무엇을 통과하면 완료인가
• 어떤 Issue가 먼저 필요한가
• 어떤 PR은 병렬로 해도 되는가
• 어디에서 나의 판단으로 되돌릴 것인가
• 판단 로그는 어디에 남길 것인가

이것을 머릿속에만 두면, AI에게 넘길 전제 조건도, 나중에 다시 보는 나의 판단도 흔들립니다.

그래서 Issue, 상위 Issue, CODEX_STATUS, PR 본문, 판단 로그에 조금씩 옮겨갑니다.

이것이 제 안의 「문맥 허브」입니다.

개인 개발에서는 자신의 머릿속에 문맥이 쌓이기 쉽습니다.

예를 들어, 다음과 같은 판단입니다.

• 이 Issue는 먼저 한다
• 이것은 아직 구현하지 않는다
• 이것은 조사 단계에서 멈춘다
• 이것은 PR을 만들어도 되지만, merge는 나중에 확인한다
• 이 변경은 다른 Issue와 충돌할 것 같다
• 이 검증이 통과할 때까지 다음으로 진행할 수 없다

혼자서만 작업한다면 머릿속에 기억하고 있어도 어떻게든 되는 경우가 있습니다.

하지만 Codex에 작업을 맡기기 시작하자, 그것만으로는 부족해졌습니다.

AI에게 매번 긴 설명을 전달하다 보면, 대화마다 전제 조건이 조금씩 흔들리게 됩니다.

그래서 머릿속에 있는 판단을 가능한 한 Issue나 상태표로 옮기려고 노력하고 있습니다.

머릿속에 흔히 있는 문맥	외부로 내보내는 장소
무엇을 해결할 것인가	GitHub Issue
...

이것은 깔끔한 관리표를 만들고 싶다는 이야기가 아닙니다.

Codex에게 전달할 전제를 매번의 채팅이 아니라, 나중에 다시 볼 수 있는 곳에 두기 위한 고안입니다.

제 관점에서는 문맥(Context)에는 두 가지 종류가 있습니다.

종류	예시	취급
품고 있는 문맥 (Internal Context)	위화감, 우선순위에 대한 감각, 아직 언어화되지 않은 불안	우선 스스로 파악함
전달할 수 있는 문맥 (Transferable Context)	Goal, Scope, Done, Out of scope, blocked by, 검증 결과	Issue나 표로 옮김

처음부터 전부를 언어화하는 것은 어렵습니다.

하지만 Codex에게 맡기는 작업에 대해서는, 적어도 "전달할 수 있는 문맥"까지 정리한 후에 의뢰하는 것이 안정적이었습니다.

특히 효과적이었던 것은 다음 세 가지입니다.

• 변경해도 좋은 범위를 작성한다
• 이번에 하지 않을 것을 작성한다
• 진행해도 좋은 상태인지 상위 Issue나 CODEX_STATUS로 확인한다

이 부분이 모호한 상태로 두면, Codex가 내놓는 PR(Pull Request)이 아무리 빠르더라도 나중에 검토하는 자신의 부하가 커집니다.

저의 개인 개발에서는 문맥 허브(Context Hub)를 다음과 같은 요소로 구성하고 있습니다.

요소	역할
GitHub Issue	무엇을 해결할 것인가를 고정한다
...

전부를 처음부터 정돈할 필요는 없습니다.

저도 처음부터 이런 형태였던 것은 아닙니다.

처음에는 Issue에 Goal / Scope / Done / Out of scope를 작성하는 것부터 시작했습니다.

거기서부터 상위 Issue, CODEX_STATUS, 견적(Estimate), 판단 로그로 조금씩 확장해 나가고 있습니다.

지금부터 읽으신다면, 다음 순서가 이해하기 쉬울 것입니다.

가장 먼저 할 일은 AI에게 전달할 작업 단위를 채팅이 아닌 Issue로 만드는 것입니다.

Goal / Scope / Done / Out of scope를 작성하는 것만으로도 PR의 경계가 더 잘 보이게 됩니다.

Issue가 늘어나면 모든 것이 같은 무게로 보이게 됩니다.

그래서 상위 Issue에 critical path, parallel lane, blocked, human review를 둡니다.

Codex에게 "이 Issue를 수행해줘"라고 넘기기 전에, 해당 Issue가 지금 진행해도 좋은 상태인지 확인합니다.

Blocked by, Blocks, Agent, PR, Notes가 있는 것만으로도, 너무 앞서 나가는 리스크를 줄이기 쉬워집니다.

AI를 의사결정자로 만드는 것이 아니라, 견적의 논점을 맞추는 참여자로서 사용합니다.

인간이 놓치기 쉬운 리스크나 불확실성을 도출하게 함으로써, 견적 전의 대화를 원활하게 만듭니다.

향후에는 다음과 같은 하위 글들을 나누어 쓰고 싶습니다.

테마	쓰고 싶은 내용
Out of scope	Codex에게 맡기는 Issue에는 Done보다 먼저 Out of scope를 쓰는 것이 좋았다
...

이 상위 글은 한 번 쓰고 끝내는 것이 아니라, 하위 글이 늘어나면 업데이트해 나갈 생각입니다.

처음부터 전체상을 깔끔하게 만드는 것이 아니라, 실제로 Codex를 사용하며 겪은 어려움, 시도한 것, 실패한 것을 하위 글들로 나누어 쓰고, 나중에 상위 글으로 다시 연결하는 형태입니다.

그렇게 하면 개별 글만으로는 흘러가 버릴 배움을 시리즈 전체의 지도로 남기기 쉬워집니다.

제 관점에서는 이것이 GitHub Issue 운영 방식과도 유사합니다.

하위 Issue가 늘어나면 상위 Issue로 돌아온다.

하위 Qiita 글이 늘어나면 상위 Qiita 글로 돌아온다.

이런 구조로 만들어 두면 독자에게도, 저 자신에게도 "지금 어디를 읽어야 하는가"가 명확히 보일 것이라고 생각합니다.

이 운영 방식은 아직 저의 개인 개발에서 테스트하고 있는 단계입니다.

다음 사항들은 아직 단정 지을 수 없습니다.

• 어떤 팀에서도 동일하게 효과가 있는가
• 다인 개발에서도 동일하게 운영할 수 있는가
• GitHub Projects나 sub-issues보다 우월한가
• 실제로 리뷰 시간이 몇 % 감소했는가
• PR의 재작업(rework)이 얼마나 줄었는가

따라서 이 글에서는 "이것이 정답이다"라고 쓰지 않겠습니다.

현재로서는 저의 환경에서 Codex에게 작업을 맡기기 전에 Issue, 상태, 판단 로그를 연결하는 문맥 허브를 만들면 다루기 쉽다고 느끼고 있습니다.

Codex를 사용하면 작업 그 자체는 빨라집니다.

다만, 작업이 빨라질수록 무엇을 풀 것인지, 어디까지 맡길 것인지, 어디서 멈출 것인지가 중요해집니다.

이를 위해 저는 GitHub Issue, 상위 Issue (Parent Issue), CODEX_STATUS, PR 본문, 판단 로그를 연결하는 문맥 허브 (Context Hub)를 만들려고 노력하고 있습니다.

제가 머릿속으로 보고 있는 문맥을 조금씩 Issue나 상태표로 옮기는 것.

그것이 Codex를 사용한 AI 개발을 안정화하는 데 있어 중요하다고 생각합니다.