오늘 팀원들이랑 "AI 시대의 개발 문화 컨벤션"을 주제로 한참 떠들었다
누구는 가제코드, 누구는 OMO를, 누구는 자체 하네스를 구축해서 쓰고 있었다
그렇다면, 각각이 쓰는 AI가 다르니 문서도, 스킬 플로우도, AI에게 강제하는 rule도 전부 다르니 결과물의 퀄리티 또는, 각각의 Agent들의 프로젝트 이해 수준이 달라질 수 밖에 없었다
그렇다면 팀 내에서 AI를 어떻게 써야 할까...?
각자 AI 코딩 도구를 쓰기 시작한 지는 꽤 됐다.
문제는 각자 다르게 쓴다는 것이었다.
누구는 플랜부터 세우고 들어가고, 누구는 바로 구현시키고, 누구는 이슈 없이 브랜치부터 파고, 누구는 테스트를 나중에 붙인다.
뭐... 물론 이게 개인 작업이면 아무 문제 없다.
취향이니까.
근데 이게 팀 작업이 되는 순간 얘기가 달라진다.
내가 만든 산출물이 남의 AI 세션의 입력이 되기 때문이다.
내 플랜 문서가 팀원의 구현 스킬로 섞여 들어가고, 팀원이 판 issue가 내 AI의 출발점이 된다.
그래서 첫 안건이 이거였다.
사용하는 스킬을 통일하자.
1. 스킬 지도 그리기!
무슨 스킬이 우리 모두가 쓰는 스킬인건데...?
그래서 우리가 실제로 AI에게 시키는 일을 단계별로 늘어놔 보았다.
이 플로우는 모든 팀원이 동의하고 있는 플로였다.
그렇다면 AI가 이해할 수 있도록 이를 구조화 하면 어떻게 될까?
공통적으로 크게 보았을 떄에 설계(기획) -> 실행(구현) -> 검증 -> 깃 작업 플로우로 작업을 하고 있었다.
다만, 이 지도를 그려놓고 보니 한 가지가 분명해졌다.
스킬은 통일하려면 통일할 수 있다.
하지만 사람의 워크플로우를 통일하지 않으면 스킬을 통일한다고 한들 의미가 없다.
무슨 말이냐면, "브레인스토밍에 어떤 스킬을 쓰느냐"는 사실 별로 중요하지 않다.
사람마다 잘 맞는 게 다르고, 도구는 3개월이면 바뀐다.
진짜 중요한 건 브레인스토밍의 결과물이 어떤 형식으로 플랜 작성 단계에 넘어가느냐였다.
여러가지 질문들이 자연스럽게 따라왔다.
플랜의 산출물이 issue의 어느 칸을 채우는가?
issue의 어느 칸이 구현 스킬의 입력이 되는가?
검증 단계는 이슈의 어떤 항목을 근거로 통과/실패를 판정하는가?
워크플로우만 고정되면 각 칸의 도구는 갈아끼워도 파이프라인이 안 깨진다.
하지만 워크플로우에 대한 통일이 없으면 도구를 아무리 통일해도 중간에 사람이 개입해야 한다는 문제가 있었다.
그리고 우린 이 지도의 모든 접합부가 통과하는 병목을 하나 발견할 수 있었다.
ISSUE
2. Issue에 대해 알아낸 세 가지
병목이 이슈라는 게 정해지고 나서 남은 질문은 두 개였다.
이슈는 어느 수준까지 정보를 담고 있어야 하며, 어느 시기에 만들어져야 하는가?
어디까지가 사람의 컨벤션이고 손으로 해야 하는 거고, 어디까지가 AI가 가져가는 작업이며, 어디까지가 AI에게 강제성을 부여해야 하는 부분인가?
강제선이라는 개념 - 이게 가장 중요한 단어다.
사람이 하는 일과 AI가 하는 일을 나누는 건 누구나 생각한다.
근데 거기엔 칸이 하나 더 있다.
AI가 알아서 하되, 안 하면 진행이 막히는 구간.
문서에 적어두고 "잘 지켜주세요"가 아니라, 안 지키면 파이프라인이 멈추는 구간.
문서에 적힌 컨벤션은 지침이고, 게이트로 박힌 컨벤션은 물리 법칙이다.
그리고 AI에게 지침은 확률이고 물리 법칙만 보장이다.
문제는, hooks를 써서 AI에게 강제를 한다고 한 들, 사람이 이 hook이 발동하지 않게 작업을 한다면 이 장치가 아무 의미가 없다.
우리 팀은 어떤 플로우로 일하고 있었나?
일단 우리 프로젝트 팀은 기획자가 없다.
개발자만 넷 이었고, 아래와 같은 플로우로 일을 하고 있었다.
간단하다.
기본적인 loop 엔지니어링을 사용해서 작업을 한다.
하지만 여기서 문제가 발생한다.
파생된 문제가 커서, 하나의 loop가 몇시간동안 돌아가기도 한다.
그로 인해서 컨텍스트가 오염되는 문제가 발생한다.
나는 여기서 고민하기 시작했다.
플로우는 고정하되, 컨텍스트 오염시키지 않고, 작업은 이어지게 하는 방법이 없는가?
내가 찾은 해답은
graph 엔지니어링 개념이었다.
Graph Engineering
- 기본적인 작업의 단위는 Parent Issue이다.
- loop를 사용하지 않는 대신에, 파생된 문제가 생기면 새로운 Sub Issue를 만들고 작업을 한다.
- 각각의 Sub Issue는 독립적인 새로운 세션이며, 그 안에서 단일 목표를 완수하기 위한 loop 사용은 허용한다.
- 하나의 Parent Issue는 Orchestratior 역할을 하며, 필요하다면 subIssue를 파고, Sub Issue 작업이 끝나기 전까지 작업을 중단하는 것을 허용한다.
그래프로 보자면 이렇다.
그렇다면 이 워크플로우를 해치지 않기 위해서, 즉 AI가 일하는 것에서 사람의 개입을 최소화 하려면 Issue 구성을 어떻게 해야 하는가?
😚 제 1 원칙 : 이슈에는 코드를 읽어서 안 나오는 것만 적는다
처음엔 이슈 양식에 '작업으로 인한 예상 변경 지점' 을 넣을지를 놓고 얘기했다.
어느 파일이 바뀔지 미리 적어두면 AI가 헤매지 않을 거라는 발상이었다.
근데 잘 굴러가는 양식들엔 그 칸이 없다.
대신 이런 항목들이 들어간다.
- 배경 — 왜 이걸 하는가
- 설계 — 어떤 방향으로 풀 것인가
- 구현 범위 — 어디까지가 이번 작업인가
- 성능 과제 — 인프라 작업일 때
- 검증 — 무엇을 만족하면 끝인가 (필요한 테스트 코드 등)
- 참고 문서
이게 왜 합리적이냐면, 예상 변경 지점은 코드베이스를 실제로 읽어야 나오는 정보고 그건 AI가 사람보다 압도적으로 잘한다.
사람이 손으로 적어봐야 틀리거나, 맞았어도 일주일이면 낡는다.
반대로 "어디까지가 이번 작업이냐"와 "무엇을 만족하면 끝이냐"는 코드를 아무리 읽어도 안 나온다.
그건 판단이다.
나는 여기서 가져갈 것을 추려보았다.
AI가 작업을 가장 잘하기 위한 정보만을 추리는 것이다.
가져갈 것.
이슈에는 코드를 읽어서 나오지 않는 정보만 적는다.
코드에서 나오는 건 AI가 채우게 두고, 이슈는 판단만 담는다.
🤔 제 2 원칙 : 이슈는 불변에 가깝게 다뤄야 한다
작업하다 보면 범위가 예상보다 커진다.
이때 선택지는 셋이다.
이슈 본문을 수정하거나, 그냥 두고 PR에서 얘기하거나, 새 이슈를 파거나.
내가 결정한 정답은 후속 이슈를 바로 판다였다.
이유는
컨텍스트 오염을 막기 위함 이었다.
사람만 있는 팀이면 이슈 본문 수정은 별 비용이 아니다.
사람은 "아 이건 나중에 추가된 거구나" 하고 알아서 읽는다.
근데 이슈가 AI의 입력 명세가 되는 순간, 이슈 본문에 섞여 들어간 뒤늦은 요구사항은 오염이다.
AI는 초기 요구와 추가 요구를 구분해서 우선순위를 두지 않는다.
전부 동등한 지시로 읽는다.
하나의 이슈가 두 개의 목표를 담으면, 그 이슈에서 시작된 세션은 두 목표를 섞어서 만족시키려 든다.
컨텍스트를 깨끗하게 유지하는 비용보다 새 이슈를 파는 비용이 싸다는 판단이었다.
후속 이슈는 게으름이 아니라 위생이다.
가져갈 것.
이슈는 불변(immutable)에 가깝게 다룬다.
범위가 커지면 수정이 아니라 분기.
본문 수정은 오타나 명백한 오류 정정 수준으로 제한한다.
☺️ 제 3 원칙 : 이슈는 기획의 산출물이지 기획의 그릇이 아니다
"일단 이슈 파고 거기서 생각하자."
나도 자주 하던 거다.
이게 이 모델에서는 금지다.
순서가 반대여야 한다.
기획이 나와야 이슈를 만들 수 있다.
이슈는 "무엇을 만들지"를 정하는 자리가 아니라 "정해진 걸 어떻게 개발할지"를 적는 개발 티켓이다.
기획서 단계에서 기능별 구체화가 다 끝나고, 큼지막한 블록은 에픽(parent 이슈)으로, 그 아래 단계별 스토리를 서브 이슈로 설계한다.
왜 이 순서여야 하는지는 이슈 안에서 기획을 하면 오염이 구조적으로 발생하기 떄문이다.
기획이 진행될수록 이슈 본문이 계속 바뀔 수밖에 없으니까.
이 플로우가 고정되니, 자연스럽게 아래 문제가 해결된다.
스킬 A의 출력을 스킬 B의 입력으로 사람이 매번 복사 - 붙여넣기 하는 게 아니라, 스킬들을 묶어둔 스킬 - 순서와 전달을 책임지는 오케스트레이션 커맨드 하나가 그걸 한다.
가져갈 것.
순서는기획 → 에픽 → 스토리 이슈 → 작업으로 고정한다.
3. 이번에는 AI 책임과 사람 책임을 분리해보자!
이제 두 번째 질문으로 돌아간다.
강제선을 어디에 그을 것인가.
다만 한 가지 제약사항이 이 강제선을 강제한다.
개발 서버, 스테이징 서버, 운영 서버.
개발 서버(dev) ← 아무나 언제든. 깨져도 됨.
↓ 승급 게이트: 기능 동작 + 테스트 통과
스테이징(staging) ← 팀 공용. 깨지면 남의 시간이 날아감.
↓ 승급 게이트: 사람의 최종 확인
운영(prod) ← 사용자. 깨지면 되돌릴 수 없는 게 생김.우리는 강제선을 새로 발명할 필요가 없다.
이미 있는 강제선을 코드 안쪽으로 한 칸 더 당기면 된다.
나는 우리가 자연스럽게 하고 있던 경계선을 표 형식으로 나타내보았다.
| 구간 | 누가 | 되돌리기 비용 | 근거 |
|---|---|---|---|
| 기획 (무엇을 왜) | 사람 | 최상 | 코드를 읽어도 안 나오는 판단 |
| 에픽/스토리 분해 | 사람 주도, AI 보조 | 상 | 경계 설정은 판단, 열거는 기계 |
| 이슈 확정 | 사람 | 상 | AI에게 주는 계약서 |
| 예상 변경 지점 조사 | AI | 무 | 코드베이스 전수 조사 |
| 워크트리 분기 | 강제 | 무 | 어길 수 없게 자동 |
| 구현 | AI | 무 | 본체 |
| 코딩 컨벤션 | 강제 | 무 | 지침 아님, 게이트 |
| 테스트 (TDD) | 강제 | 무 | 통과 못 하면 진행 불가 |
| 범위 초과 시 후속 이슈 | 강제 | 무 | 오염 차단은 자동이어야 의미 있음 |
| 개발 서버 배포 | 강제 | 무 | 자동, 사람 승인 없음 |
| 코드 리뷰 1차 | AI | 하 | 사람 리뷰 전 필터 |
| 코드 리뷰 최종 · 머지 | 사람 | 중 | 팀 시간이 걸림 |
| 스테이징 승급 | 사람 | 중 | 공용 자원 점유 |
| 운영 배포 | 사람 | 최상 | 되돌릴 수 없는 게 생김 |
쭉 나열하고 보니 표에서 세 가지가 읽혔다.
- 강제 해야 하는 작업들은, 강제하지 않으면 티가 안난다.
- 사람이 해야 하는 작업은, 판단과 되돌리기에 분포한다.
- 사람이 하는 일은 되돌리기 비용이 보통 크다.
이 말이 무엇이냐면
사람 책임져야 하는 큰 결정이 발생하는 순간이, AI가 작업을 멈추는 순간이 된다는 뜻이다.
4. 야간 자율 주행 - 도착지는 개발 서버까지
지금 이 워크플로우를 만든 진짜 이유는 이것이었다.
Issue에서 시작하여 밤에 사람이 자고 있을 때에 작업을 하는 경우가 많다.
-> 사람의 손을 최대한 타지 않아야 한다.
이걸 야간 자율 주행이라고 부르자.
이슈 하나를 목적지로 찍어놓고 자면, 아침에 결과물이 와 있는 상태.
밤중에 갈 수 있는 최대 거리는 개발 서버까지다.
워크트리 분기부터 구현, 테스트, AI 1차 리뷰, 개발 서버 배포까지 - 전부 되돌리기 비용 0 구간이고, 전부 무인 통과 가능하다.
아침에 사람이 하는 일은 운전이 아니라 승급 심사다.
개발 서버에 올라가 있는 결과물을 보고 스테이징으로 올릴지 판정한다.
여기까지 왔으면 이슈의 시점과 워크플로우가 사실상 결정된다.
Q. 이슈가 기획 이후에 나와야 하는 이유는?
A. 자는 사람에게 되물을 수 없으니까.
Q. 이슈에 검증 칸이 있어야 하는 이유는?
A. 사람이 자고 있는 밤에 AI가 "이제 다 됐나?"를 판단할 근거는 이슈의 검증 항목뿐이다.
그리고 그 판정이 실제로 내려지는 장소가 개발 서버다.
이슈의 검증 칸은 개발 서버에서 기계가 판정 가능한 문장으로 쓰여야 한다.
Q. 범위 초과 시 후속 이슈로 작업을 넘겨야 하는 이유는?
A. 밤중에 스스로 목적지를 늘려버리면 아침에 뭘 받았는지 알 수 없다. (또한 사람이 원치 않는 작업을 해버릴 수도 있고, 나중에 하려 했던 이슈를 미리 감지하고 처리해버리는 상황도 발생할 수 있다.)
따라서 늘어난 범위는 새 목적지로 등록하고, 이번 주행은 원래 목적지에서 끝낸다.
하나의 이슈 = 하나의 승급 단위.
Q. 컨벤션이 게이트여야 하는 이유는?
A. 가드레일은 운전자가 볼 때만 작동하는 게 아니다.
감시자가 없는 시간에도 유지되는 규칙만 진짜 규칙이다.
한 문장으로 줄이면 이거다.
목적지는 사람, 주행은 AI, 가드레일은 코드, 그리고 밤에 갈 수 있는 데까지가 개발 서버다.
5. 하네스를 고도화해야 하는 것들...
-
이슈의 최소 정보량은 정확히 얼마인가.
AI에겐 이슈가 작업의 전부다.
AI용 이슈가 더 두꺼워야 하는지, 아니면 두꺼운 이슈가 오히려 탐색을 죽이는지를 실측해야 한다.
(개인적으로는 모델의 영향도 많이 받을 것 같긴 하다.) -
검증 칸을 어디까지 기계 판정으로 만들 수 있나.
개발 서버에서 자동 판정되는 항목과, 결국 사람이 눈으로 봐야 하는 항목의 비율.
후자가 많으면 밤에 AI가 할 수 있는 작업이 단적으로 줄어든다. -
강제를 무엇으로 구현할 것인가.
훅인지, CI인지, 커맨드 안의 단계 강제인지.
우리 배포 파이프라인엔 이미 답이 있는데 개발 파이프라인엔 아직 없다. -
아침 승급 심사의 형식.
이것 또한 AI에게 시키는가? 아니면 사람이 일일이 다 확인하기? -
스킬 선정의 근거를 어떻게 비교할 것인가.
같은 이슈를 여러 스킬 조합으로 돌려 개발 서버 도달률을 비교하는 것 말고 방법이 있나 싶다.
에필로그
시작은 "우리 스킬 좀 통일하자"였다.
반나절 얘기하고 나니 그건 문제의 표면이었다.
진짜 문제는 이거였다.
AI에게 일을 넘기려면, 사람끼리는 암묵적으로 넘기던 것들을 전부 명시적으로 적어야 한다.
사람 팀에서 이슈 한 줄로 통하던 건 옆자리에서 물어볼 수 있었기 때문이고, 컨벤션 문서가 지켜지던 건 리뷰어가 사람이었기 때문이다.
그러니까 AI 컨벤션을 만드는 일은 새로운 규칙을 발명하는 일이 아니다.
우리가 원래 지키고 있다고 믿었던 것들이 실은 사람의 눈치와 기억으로 굴러가고 있었다는 걸 확인하는 일에 가깝다.
진짜 하고 싶은 말
이제는 하루 종일 사람이 개발하는 것 보다 아침에 와서 AI가 해 둔 작업을 확인하는 것이 일상이 되었다.
그런데 사람이 일하는 방식은 바뀌지 않았다.
사람의 워크플로우에 AI를 맞추기.
근데 나는 이게 반대가 되지 않았나 싶다.
AI로 생산성을 극대화 하는 방법을 생각하다보니
사람이 병목임을 알게 되었고,
그렇다고 책임 소지를 사람이 가지고 있으니 병목을 없앨수는 없었다.
그렇다면 사람의 작업 방식을 AI에게 최적화 해야 할텐데,
그 시작점이 워크플로우였다고 생각한다.
AI에게 맞추는 것이 거부감이 느껴지는가?
그렇다면 이렇게 생각해보자.
AI라는 사람과 내가 협업을 해야 하는데, AI의 일정이 정해져 있기 때문에 그 사람의 작업 방식을 따라갈 뿐이라고
멋져요