PROJECT.md 역할분담을 명시하다

AI 사건일지에서 언급한 것처럼 프로젝트 전체를 아는 사람이 없어졌고, MyStock 리팩토링 시점부터 ChatGPT & Codex 그리고 나 사이에서 개발 방향의 초점이 계속 어긋나기 시작했다. 그동안 미루고 미루던 PROJECT.md 규칙을 시급하게 적용해야 할 시점이 온 것 같다.

최신 트렌드에 둔감한 나는 TPUB.md도 처음에는 일련의 명령어를 실행하는 스크립트나 배치파일처럼 이해하고 있었다. 전통적인 개발 방식처럼 "내가 명령을 내리면 정해진 순서대로 무조건 실행한다"는 의미로 생각했던 것이다. 하지만 AI는 그렇게 움직이지 않았다. 문서에 정의된 절차와 규칙을 참고하면서, 현재 작업의 목적과 상황을 판단해 필요한 내용을 적용하고 있었다.

프롬프트가 들쭉날쭉했던 이유도 보였다

여기서 한가지 재밌는 사실은... MyStock을 진행하는 동안 PROJECT.md 규칙의 필요성은 인지하고 있었으나, 조금 귀찮더라도 그냥 저냥 진행하는데 큰 문제가 없었고, 가끔 ChatGPT가 빼먹을 수도 있다고 생각했었다. 하지만 이것은 내 생각이 잘못된 것이며, 몇 주간 나의 작업 패턴을 인식하거나 학습한 ChatGPT가 내 일하는 방식으로 맞추고 있었던 것이다.

잘 생성하던 프롬프트가 누락되는 이유는 이전 대화의 포커싱이 집중되어 devlog 파일 생성 규칙 같은 것이 누락되었기 때문이다. 이런 동작 방식의 차이를 이해하지 못한 나는 매번 ChatGPT한테 불평불만을 토로하게 됐다. 그래서 PROJECT.md가 필요했다. 모든 작업에 모든 규칙을 기계적으로 적용시키기 위해서가 아니라, ChatGPT가 작업 상황을 판단할 때 반드시 참고해야 할 기준을 외부에 명시해두기 위해서였다. TPUB처럼 특정 명령에 정해진 절차가 필요한 작업과, 현재 상황에 따라 필요한 규칙을 선택해 적용해야 하는 개발 작업은 성격도 달랐다.

devlog는 코드가 아니라 이유를 남겨야 했다

그런데 PROJECT.md만 만든다고 프로젝트의 맥락이 복구되는 것은 아니었다. GitHub의 현재 코드를 보면 지금 어떻게 만들어져 있는지는 확인할 수 있다. 하지만 리팩토링 과정에서 왜 이런 구조를 선택했는지, 어떤 문제 때문에 책임을 분리했는지 같은 과거의 판단 이유까지 코드가 알려주지는 않는다.

그 역할은 그동안 작업 과정에서 작성해 온 devlog가 맡을 수 있었다. 처음에는 devlog에 클래스와 모듈, thread lifecycle 같은 코드 수준의 내용이 너무 많은 것은 아닌가 싶었다. 하지만 다시 살펴보니 어느 정도의 코드 정보는 필요했다. 새 대화방의 ChatGPT가 현재 코드와 과거의 판단을 연결하려면 최소한의 근거가 있어야 하기 때문이다.

대신 구현 과정을 세세하게 기록할 필요는 없었다. 무엇을 어떻게 코딩했는지가 아니라, 왜 이런 구조가 되었는지를 다시 판단할 수 있을 정도의 근거만 남기면 됐다. 결국 devlog의 역할도 명확했으며, GitHub가 현재의 결과를 보여준다면, devlog는 그 결과에 도달한 이유를 남긴다. 파일도 Step마다 계속 만들기보다 원칙적으로 PR 하나에 하나의 devlog를 두고, 작업 과정에서 나온 중요한 판단과 최종 설계를 함께 남기는 방향으로 정리했다.

PROJECT.md가 명세한 각자의 역할 (업무규칙)

여기까지 정리하고 나니 내가 만들고 있던 것은 프로젝트 설명서보다 역할분담에 가까웠다. 농담처럼 나온 비유지만 역할 분담은 꽤 정확했다.

LOGON 개발팀 업무규칙

구성원: 2명 + 작업자 1명

• 나      : 팀장(사수)
• ChatGPT : 유능하지만 가끔 앞서가꼬 뭐하나 꼭 빼먹는 주니어
• Codex   : 말없이 코드 치는 외주(?)

나는 작업 방향과 요구사항, 최종 판단을 맡는다.
ChatGPT
- GitHub와 devlog, 현재 대화를 바탕으로 맥락을 복구하고 작업을 구조화한다.
- 현재 작업에 필요한 내용을 Codex가 실행할 수 있는 프롬프트로 만든다.
Codex는 실제 코드 분석과 구현, 테스트와 검증 및 devlog 작성을 수행한다.

내가 ChatGPT를 실력은 좋지만 가끔 앞서가거나 종종 구멍을 만드는 주니어처럼 생각하고 일을 시켜온 이유와도 잘 맞았다.

새 대화방에서는 규칙을 어떻게 찾게 할까

PROJECT.md를 만들어도 새 대화방에서 그 파일을 읽으라는 지시가 없으면 다시 긴 인스트럭션을 붙여 넣어야 한다. 기존 TPUB도 같은 문제가 있었다. 그래서 ChatGPT의 개인 맞춤 설정에는 실제 업무규칙을 넣지 않고 작은 bootstrap instruction만 두기로 했다.

역할은 단순하다. TPUB 발행해줘라고 하면 Google Drive의 최신 TPUB.md를 읽고, <프로젝트명> 프로젝트 컨텍스트 복구해줘라고 하면 최신 PROJECT.md를 읽는다. 실제 업무규칙은 Drive에 두고 개인 맞춤 설정은 규칙을 찾아가는 loader 역할만 맡긴다. 설정을 저장한 뒤 다른 새 대화방에서 별도의 인스트럭션을 입력하지 않고 프로젝트 컨텍스트 복구를 실행해봤다. 성공했다. ㅋㅋㅋ

기억시키는 대신 다시 찾을 수 있게 만들었다

처음에는 새 대화방에서 맥락이 끊기는 문제를 해결하려고 했다. 결국 AI에게 모든 것을 기억시키는 방향이 아니라, 언제든 같은 기준으로 다시 프로젝트 상태를 복구할 수 있는 구조를 만들게 됐다. 개인 맞춤 설정은 최신 규칙을 찾고, PROJECT.md는 팀의 업무 방식을 정의한다. GitHub는 현재 구현 상태를 보여주고, devlog는 왜 그런 구조가 되었는지를 남긴다. ChatGPT는 이 정보를 현재 작업에 맞게 정리해 Codex에게 전달한다. 처음에는 PROJECT.md 하나 만들 생각이었다.

결과적으로 사람 한 명, ChatGPT 한 명, Codex 한 명이 같이 일하기 위한 작은 개발팀 업무 체계를 만들고 있었다.

저작자표시 비영리 동일조건 (새창열림)