AI 개발팀 프로세스를 묻길래 검사기 23개를 보여줬다
- 공유 링크 만들기
- X
- 이메일
- 기타 앱
쓰다보니 꼬였네요.
자정 가까운 시각에 오픈 채팅방에 내가 적은 문장이다.
밤 10시쯤 질문이 하나 올라왔다. 회사에 AI 개발팀이 새로 생겨서 팀장을 맡았는데, 그동안 보안 일만 해서 개발 프로세스를 어떻게 잡을지 모르겠다는 얘기였다. 표준화나 절차를 어디서부터 하냐고. 길게 쓸 생각은 없어서 내가 AI한테 던지는 지시문 형식을 그냥 복사해 붙여 줬다. 얘기가 꽤 이어졌다. 다른 분이 AI 조직은 사내 이해관계가 제일 많이 부딪히는 데라 피곤할 거라고 거들었고, 나는 4단계 얘기까지 했고, 자정 넘어서 고맙다는 답이 왔다.
ADR 얘기를 꺼내려다 표준화 얘기로 새서 스스로 끊은 거였다. 그날 밤엔 그냥 문장이 엉킨 줄 알았다. 다음 날 다른 이유로 게임 저장소를 열었다가, 왜 꼬였는지 알았다.

그날 밤 붙여준 지시문 형식은 이랬다.
너는 다년간 아키텍처 설계 및 코딩을 해온 시니어야.
나는 보안쪽 업무를 다년간 해왔어. 이번에 개발팀에 팀장역할을 맡게 되었어.
너의 역할은 심층검색과 분석을 통해 나에게 개발 프로세스 및
표준화 절차 가이드를 제공하는거야.
문서의 양식은 마크다운과 html 두 가지 양식으로 제공 받길 원해.
---
이런 형식으로 지시하려해 부족한 부분이 있어?
역할 목적 결과 또 뭐가 필요하지?
중요한 건 구분선 아래 두 줄이다. 시키기 전에 지시문부터 같은 AI한테 검사받는 거다. 이걸 붙이면 첫 답이 문서가 아니라 질문으로 온다. 회사가 몇 명이냐, 이슈 트래커는 뭐 쓰냐, 문서는 어디까지 있냐. 거기 답하고 다시 시키면 같은 모델인데 결과가 꽤 달라진다.
안 붙였다가 크게 데인 적이 있다. "코드 재설계 해줘" 한 줄로 시작한 리팩토링이 초반엔 빨리 가다가 끝에서 같은 데서 몇 번이나 무너졌다. 지시가 얕다고 결과가 얕게 나오진 않는다. 그럴듯하게 나와서 한참 뒤에야 문제가 보인다.
채팅방에서 내가 한 얘기의 골자는 이거였다. 개발 방법론은 계속 바뀌지만 안 바뀌는 게 있고, 그건 분석, 설계, 구현, 테스트 네 단계다.
이 네 개는 유행이 아니라 구조라서 벗어날 방법이 없다. 뭘 만들지 알아내지 않고 어떻게 만들지 정할 수 없고, 정하지 않고 만들 수 없고, 만든 게 맞는지 안 보고 끝낼 수 없다. 애자일이 폭포수를 이겼다고 할 때 없어진 건 단계가 아니라 단계 사이의 대기 시간이었다.
방법론 이름들을 쭉 놓고 보면 대부분 설계 얘기다. 요구사항을 얼마나 크게 자를지, 언제 설계하고 언제 코드로 넘길지. 근데 AI가 오면서 그게 좀 가벼워졌다. 말하면 코드가 나오고, 맘에 안 들면 다시 말하면 된다. 설계를 앞에 둘지 뒤에 둘지로 방법론 고르는 게 예전만큼 중요하지 않다.
유니티 저장소에서 이미 겪었다. 4월 첫 주는 fix 도배였고, 중순에 설계서를 열댓 개 쓰고 소스를 다 지웠고, 5월에 작업마다 Step 번호를 붙였더니 fix가 3개로 줄었다. 효과를 본 건 설계서가 아니라 번호였다. 번호가 있으니 확인할 데가 생겼다.
그래서 채팅방에서 마지막에 요즘 회사 트렌드도 4단계 각각의 결과를 검증하는 방향으로 옮겨가고 있다고 적었다. 적을 때는 남 얘기하듯이 적었다.
게임 저장소
다음 날 아들과 만든 로블록스 게임 저장소를 열었다. 다른 작업을 하려던 참이었는데 앞의 대화가 신경 쓰여서 먼저 세어봤다.
Luau 파일 40개 남짓에 3만 줄 가까이. 문서는 열한 개에 10만 자쯤. 커밋은 열댓 개, 8일치다.
문서를 크기순으로 보면 배포 가이드가 제일 크고, 수익화 전략, 브랜딩 전략, 게임 설계서 순이다. 구현 명세서랑 테스트 명세서는 없다.
채팅방에서 분석서, 설계서, 구현 명세서, 테스트 명세서를 만들면 좋지만 요즘은 잘 안 만든다고 적었었다. 업계 얘기라고 생각했는데 내 저장소가 딱 그랬다. 앞의 둘은 두껍고 뒤의 둘은 없다. 그런데 그게 터진 방식은 생각과 좀 달랐다.
어느 날 밤 밸런스 패치 하나를 코드리뷰했다. 수치가 이상하다는 느낌이 들어서 열어본 건데, 나온 건 수치 문제가 아니었다.
지연 스폰이라는 게 있다. 층이 30개까지 늘어나면서 서버 시작할 때 NPC 300기를 다 세우면 안 되니까, 플레이어가 들어간 층만 세우도록 만든 기능이다. Config에 LazySpawn 값이 있었다. 그 옆에 왜 필요한지 설명하는 주석도 있었다. 설계 문서에도 적혀 있었다.
근데 Npc.start는 옛날 코드 그대로 서버 시작할 때 30층을 다 세우고 있었다. 층 인자에 문자열 키 대신 순서 번호를 넘겨서 배율 계산이 층을 못 찾았고, 전 층이 1층 수치로 섰다. 플레이어가 들어가면 그 층을 한 벌 더 세우니까 NPC가 두 겹으로 깔렸다. 빈 층을 치우는 deactivateStage 는 정의만 있고 부르는 데가 없었다.
보상도 어긋나 있었다. 주석에는 30분 하면 술식 하나 살 수 있다고 돼 있었고 술식은 8,000젬이다. 계산해 보니 30분에 8만 젬쯤 들어왔다. 10배다. 분당 얼마 버는지 한 번도 안 따져 봐서 아무도 몰랐다. 나도 몰랐고 처음 그 값을 쓴 누군가도 몰랐을 거다.
그날 커밋 메시지에 내가 적은 문장이 이거다.
Config 에 값이 있다고 기능이 있는 건 아니다. LazySpawn·IdleDespawn 은 값도 주석도 있었지만 읽는 코드가 0줄이었다 → 새 Config 항목에는 검사기 한 줄을 같이.
문서에도 있고, Config에도 있고, 주석에도 있었다. 코드만 없었다. 빌드는 됐고 게임은 떴고 화면상 아무 차이가 없었다. 기능이 아예 없으면 없는 줄 안다. 그런데 있는데 안 도는 건 있는 줄 알고 넘어간다.
그 뒤에 검사기 소스를 다시 읽어 봤다. check_refs.py, 천사백 줄쯤 되는 파이썬 스크립트다. "조용히"라는 말이 아홉 번쯤 나온다. 뽑기는 확률표가 깨져도 조용히 동작해버리고, 드롭 표 키에 오타가 나면 조용히 "드롭 없음"이 되고, 결계막은 서버와 클라 한쪽만 있으면 조용히 죽는다.
다 겪고 나서 적은 문장이다. AI가 쓴 코드는 대개 이렇게 실패한다. 컴파일 에러는 안 난다. 문법 검사도 빌드도 다 통과한다. 그렇게 아무것도 안 하는 코드가 그냥 들어간다.
마지막 날 새벽에 증상 세 개가 한꺼번에 들어왔다. 주간 순위표가 "불러오는 중"에서 멈추고, 제령장에 들어갈 수 없고, 1대1 매칭이 안 됐다. 서로 무관한 시스템 세 개다.
씨앗은 MapBuilder.lua 안의 한 줄이었다. 문 번호가 들어가야 할 인자에 stage.floorColor를 넘겼다. Color3 값은 산술 연산이 안 되니까 런타임 에러가 났다. MapBuilder.build()가 서버 진입점의 평범한 한 줄이라 스크립트가 거기서 그냥 끝났고, 뒤에 서 있던 MatchService.start_loop(), LeaderboardService.start(), NpcService.start()가 하나도 실행되지 않았다.
오타는 15분쯤 만에 고쳤다. 하지만 고친 건 씨앗뿐이고, 한 군데 죽으면 다 같이 죽는 구조는 그대로였다. 그날 새벽에 버전을 하나 더 올려서 부팅 단계를 하나씩 xpcall로 감싸는 Util.boot을 만들고, 서버 단계 서른몇 개, 클라이언트 컨트롤러, 맵 구획까지 전부 따로 끊어 놨다. 클라이언트를 끊으면서 커밋 메시지에 "여기가 더 아프다"고 적었는데, 진행도 UI가 죽으면 그 아래 입력 처리가 안 돌아서 조작 자체가 안 된다. 사용자한테는 그냥 게임이 안 켜지는 걸로 보인다.
저 새벽에 순위표 담당, 매칭 담당, 제령장 담당을 각각 붙였으면 셋 다 자기 코드에서 아무것도 못 찾았을 거다.
그보다 며칠 전엔 2층에서 캐릭터가 공처럼 튕긴다는 보고가 들어왔다. 2층엔 적이 8기 있고, 맞을 때마다 넉백이 걸리고, 적 공격은 2초가 안 돼서 다시 돈다. 8기가 다 붙으면 1초에 네다섯 번 밀린다.
넉백도 쿨타임도 적 수도 하나씩 보면 다 설계대로인데, 다 겹치면 이상했다. 그래서 값을 깎는 대신 넉백이 겹칠 때 점점 약해지게 하고 바닥값을 뒀다.
다음 패치에선 층 가운데 서면 그 층 적이 한꺼번에 달려들었다. 그래서 동시에 때리는 적을 4기로 막았는데, 나중에 보니 난이도 주석에 이미 "3~4기 동시"라고 적혀 있었다. 설계할 땐 그렇게 생각해 놓고 코드는 안 막고 있었던 거다.
check_refs.py는 8일 만에 천사백 줄쯤 됐다. 검사 항목은 23종이다. 스킬 id가 실제로 있는지, 소환 확률 합이 딱 100%인지, 광장 시설끼리 안 가리는지, 플레이 화폐랑 결제 화폐가 나뉘어 있는지, 부팅이 따로 끊겨 있는지 같은 것들.
유닛 테스트는 아니다. 게임 코드에는 테스트가 한 줄도 없다. 로블록스 런타임 없이 돌릴 수 없어서다. 검사기는 소스를 텍스트로 읽어 "여기 있는 이름이 저기에도 있는가"를 대조한다. 원시적이지만 앞의 조용한 실패들은 대부분 이름이 한쪽에만 있는 형태로 나타났다.
검사기 주석에 "여기서 막는 사고"라고 적어둔 곳이 세 군데 있다.
실제로 겪은 사고: 순위판이 스폰→주구상점 시선 위에 서서 상점이 안 보였다.
층이 2개일 때는 눈으로 확인할 수 있었다. 30개가 되면 못 한다.
이 검사가 없으면 다음 세션에서 "매출원이 적다" 며 저주석 팩을 다시 만든다
마지막 걸 이해하는 데 제일 오래 걸렸다. 저 검사기가 막는 건 버그가 아니라 다음 세션의 AI다. 화폐를 나눈 이유는 대화하다 합의한 건데, 세션 끝나면 그 대화는 없어진다. 다음에 매출 늘려 달라고 하면 제일 자연스러운 답이 결제 화폐 팩을 늘리는 거다. 검사기가 그걸 실패로 만들어 준다. 문서는 AI가 안 읽고 넘어가는데 검사기는 안 읽어도 걸린다.
검사기 자체가 틀린 적도 있다. 소환 카탈로그 검사가 파일 전체를 뒤지는 방식이라, 소환은 플레이 화폐 전용이라는 설계 근거를 주석으로 적는 것조차 오류로 잡았다. 근거를 남길 수 없는 검사는 언젠가 주석과 함께 지워질 것 같다.
검사기를 추가할 땐 일부러 틀린 코드를 넣어 보고 진짜 잡히는지 본 다음에 커밋한다. 검사를 몇 개 만들면 그 수만큼 일부러 틀려 봤다.
커밋 절반쯤에 "실기 검증은 없다"는 문장이 들어 있다. 표현만 조금씩 다르다. 실기 플레이는 미검증, 실기 재확인은 아직.
사람이 봐야 하는 항목은 따로 있다. F5를 눌러서 대기하는 저주의 그림이 의도한 대로인지, 보상을 고친 뒤 체감 소득이 어떤지, 폰에서 점프가 진짜 되는지. 폰 점프는 실제로 한 번 크게 데인 부분이다. PC에서는 멀쩡한데 폰에서 처음부터 끝까지 한 번도 안 뛰어졌다. 로블록스 기본 컨트롤 모듈이 매 프레임 humanoid.Jump에 값을 대입하고 있어서 우리가 켠 값이 물리 단계에 도달하기 전에 덮이고 있었다. 이건 어떤 정적 검사로도 못 잡는다. 폰을 손에 들고 점프 버튼을 눌러봐야 안다.
검사기가 늘수록 이 경계는 더 뚜렷해진다. 같은 문장이 계속 나온다는 건 그 칸을 매번 비워 두고 커밋했다는 거고, 지금 이 저장소에서 제일 큰 부채가 그거다.
요즘 내가 AI에게 일 시키는 걸 돌아보면 이 네 단계가 안 보인다. 없어진 건 아니고 한 턴 안으로 접혀 들어간 것뿐이다.
"제령장을 30층으로 늘려줘" 한 줄이면 그 안에서 네 개가 다 돈다. 뭐가 필요한지 보고, 층 구조랑 배율 정하고, 코드 쓰고, 문법 확인까지 한다. 몇 분 뒤 결과가 나오는데 그 사이 판단들은 로그에 흩어지거나 아예 안 남는다. 사람은 마지막 결과만 본다. 빌드되나, 화면 뜨나. 나도 그랬다.
지연 스폰은 설계가 맞고 구현이 없었다. 나는 값과 주석과 문서를 보고 설계가 됐다고 넘어갔는데, 그건 설계를 검증한 게 아니라 설계 산출물이 있다는 걸 확인한 거였다. 보상 배율은 분석이 아예 없었다. 분당 소득이 얼마여야 하는지를 아무도 안 물었다. 넉백은 값 하나하나가 설계대로였고 겹쳤을 때만 틀렸다. 값들이 겹치면 어떻게 되는지 보는 단계가 없었다.
나는 AI가 못했다고 보지 않는다. 네 단계를 다 하기는 했다. 한 턴 안에서 네 개가 연달아 돌면 그 사이에 사람이 손을 넣을 틈이 없었을 뿐이다. 맨 앞에 붙여준 지시문의 마지막 두 줄이 하는 일이 이거다. 되물음이 오는 동안은 내가 분석을 하고 있는 거고, 그 턴이 끝나야 나머지 셋이 돈다.
팀장에게 다시 쓰는 답
그 팀장에게 다시 답한다면 방법론 이름은 하나도 안 꺼낼 것 같다. 대신 채팅방에서 반쯤 하다 만 얘기를 제대로 하겠다. 우리 팀 개발 주기를 어디서 끊을 거냐를 먼저 정하고, 그 주기 안에 네 단계를 늘어놓고, 각 단계마다 무엇을 둘지를 하나씩 계획하는 것. 코딩 규칙은 어느 단계에 붙고, 설계 문서는 어느 단계의 산출물이고, CI는 어디서 돌고, 리뷰는 언제 들어가는지. 방법론은 남이 만든 완제품을 통째로 가져오는 거고, 이건 우리 단계에 우리 물건을 하나씩 놓는 일이다.
지난 8일 동안 배운 게 있어서 여기에 한 항목을 더 붙이고 싶다. 각 단계에 무엇을 둘지 옆에, 무엇이 통과하면 이 단계가 끝난 거냐를 같이 적는다.
내 저장소를 그렇게 놓아 봤다. 분석에는 증상 보고랑 원인 기록이 있고, 증상 수랑 원인 수를 따로 셌으면 통과다. 설계에는 문서 열한 개가 있고, 문서에 적은 가정이 코드 어디서 막히는지 짚을 수 있으면 통과인데, 동시 공격자 말고는 안 따져 봤다. 구현에는 코딩 규칙 200줄쯤이랑 검사기 23종이 있고 돌리면 다 통과한다. 근데 자동으로 도는 데가 없어서 내가 손으로 돌릴 때만 돈다. 테스트에는 아무것도 없다.
구현 쪽 구멍은 이렇게 놓고 나서야 보였다. 검사기를 23종까지 키워 놓고 자동으로 돌릴 데를 안 만들었다. .github 디렉터리가 없고, git 훅도 0개다. 내가 기억날 때 손으로 check_refs.py를 돌리는 게 전부다. 커밋 메시지에 "교차 참조 23종 OK"라고 적혀 있는 건 그날 내가 돌렸다는 뜻이지 매번 돈다는 뜻이 아니다.
첫날 이렇게 놓아 봤으면 CI 칸이 빈 걸 바로 봤을 거고, 검사기를 만들 때 같이 걸었을 거다. 나는 순서를 거꾸로 갔다. 사고가 나서 검사를 만들고, 또 사고가 나서 추가하고, 그게 스물세 개가 돼서야 표를 그렸다.
ADR 도 그 표 안에 들어갈 것 같다. 결정 기록은 설계 산출물처럼 보이지만 실제로는 나중에 "이거 왜 이렇게 됐지"를 물었을 때 대조할 수 있는 물건이다. 내가 채팅방에서 표준화 얘기를 하려다 ADR로 샌 게 아니라, 표준화를 물어보면 검증 얘기가 나오는 게 맞았던 거다. 그때는 그 연결을 문장으로 못 만들어서 꼬였다고 적었다.
그 채팅방에서 다른 분이 거들었던 말이 계속 생각난다. AI 조직은 사내에서 이해관계 충돌이 제일 많이 일어나는 곳이라 꽤 피곤할 거라고 했다. 그래서 더 검증이 답이라고 생각한다. 프로세스를 새로 들고 들어가는 팀장이 제일 약해지는 때는 "이건 이렇게 하는 게 맞습니다"라고 말해야 하는 순간이고, 개발 관행을 놓고는 상대가 연차로 밀고 들어올 수 있다. 그런데 통과 조건은 누구의 판단이 아니라 눈에 보이는 상태다. 스크립트가 빨간 줄을 뱉었느냐, F5를 눌러본 사람이 있느냐. 이건 연차로 반박이 안 된다.
그 표를 8일 늦게 그렸다. 그사이 문서 10만 자쯤이랑 파이썬 천사백 줄쯤이 쌓였고, 둘 다 필요했지만 순서가 거꾸로였다. 이 글 쓰면서 안 건데, 그 천사백 줄도 아무도 안 시키면 안 돈다. 다음 커밋에 할 일이 하나 생겼다.
댓글
댓글 쓰기