AI 개발팀을 위한 '에러 매뉴얼' 만드는 법

혼자서 AI에게 개발을 맡기면 코드는 제 손보다 훨씬 빠르게 늘어납니다.

 

문제는 그 다음입니다. 어느 날 화면에 에러가 뜨면, 저도 AI도 어디부터 열어야 할지 모르는 상태가 됩니다.

 

그래서 저는 AI 코딩 에러 대응 문서화를 따로 설계했습니다. 사고가 났을 때 AI가 스스로 원인이 있을 만한 자리를 찾아가도록 만든 문서입니다. 지금은 프로젝트 다섯 개 중 네 개, 모듈 마흔 개 남짓이 이 방식으로 정리되어 있습니다.

 

전에 병합 전 품질 게이트를 다룬 글을 쓴 적이 있습니다. 그 글은 코드가 합쳐지기 전에 거르는 장치였고, 오늘 글은 이미 돌아가는 코드에서 사고가 난 뒤를 다룹니다. 시점이 정확히 반대편입니다.

 

사고가 났을 때, AI도 어디부터 봐야 할지 모릅니다

 

사람으로 이루어진 개발팀이라면 "그건 결제 쪽이니 담당자에게 물어보라"는 한마디가 나옵니다. AI에게는 그 한마디를 해 줄 동료가 없습니다.

 

에러 메시지 하나만 던져 주면 AI는 코드 전체를 뒤지기 시작합니다. 운이 좋으면 맞히고, 아니면 엉뚱한 파일을 고쳐 놓습니다.

 

그래서 저는 코드를 설명하는 문서보다 찾아가는 길을 설명하는 문서를 먼저 만들기로 했습니다.

 

첫 번째, 라우팅부터 정합니다

 

가장 먼저 문서로 못 박은 것은 "어디부터 볼지"의 순서였습니다.

 

단계	하는 일
1	에러가 발생한다
2	어느 프로젝트, 어느 모듈 소관인지 라우팅한다
3	그 모듈의 목차에서 의심 파일을 짚는다
4	뒤에 나올 8개 항목 중 알려진 함정·흔한 에러·응급 대응을 맞춰 본다 (1차 단계라 뒤 두 칸은 비어 있을 수 있다)

 

이 순서를 1차로 밟고, 그래도 안 잡히면 2차로 코드를 직접 읽힙니다. 거기서도 남으면 작업계획서와 결정 기록, 사양서에서 맥락을 찾습니다.

 

별것 아닌 것 같지만, 이 네 줄이 있고 없고에 따라 AI가 처음 여는 파일이 달라집니다.

 

두 번째, 무엇을 적을지 여덟 가지로 고정합니다

 

문서를 쓰다 보면 매번 "이번엔 뭘 적어야 하지"에서 막힙니다. 그래서 모듈마다 채울 항목을 여덟 개로 고정했습니다.

 

번호	항목	담는 내용
①	함수별 책임	이 함수가 무엇을 책임지는가
②	의존관계	무엇을 부르고, 무엇에게 불리는가
③	알려진 함정	여기서 자주 밟는 지뢰
④	디버깅 진입점	문제가 생기면 먼저 여는 자리
⑤	흔한 에러와 원인	증상별 원인 매칭
⑥	응급 대응 절차	지금 당장 뭘 하면 되는가
⑦	로그로 찾는 법	어떤 로그를 어떻게 보는가
⑧	재현 방법과 환경	어떤 설정값으로 어떻게 다시 일으켜 보는가

 

항목을 미리 정해 두면 문서 작성이 판단에서 채우기로 바뀝니다. 빈칸이 보이니 무엇이 없는지도 한눈에 드러납니다.

 

세 번째, 처음부터 다 채우지 않습니다

 

여덟 칸을 처음부터 다 채우려 하면, 벌어지지도 않은 사고를 상상해서 적게 됩니다. 그건 문서가 아니라 소설에 가깝습니다.

 

그래서 기준을 하나 두고 두 번에 나눠 채우기로 했습니다. 코드를 읽고 판단하면 알 수 있는 것은 지금 채우고, 실제로 한 번 굴려 봐야만 아는 것은 뒤로 미룹니다.

 

층	해당 항목	채우는 시점
구조층	①②③⑧ (여기에 ④ 일부)	개발하면서
실전층	⑤⑥⑦	실제 사고가 난 뒤에 한 줄씩 (단, ⑤는 코드로 읽히는 자리에 한해 미리 씨앗을 깝니다)

 

실전층은 완성을 목표로 하지 않습니다. 운영하는 내내 누적되고, 실제 연동과 실제 비용이 붙으면서 생기는 코드 변경까지 계속 흡수합니다. 그래서 이 문서는 동결하지 않습니다.

 

이 원칙은 언뜻 게으르게 보일 수 있습니다. 그런데 코드에서 근거를 짚을 수 없는 칸은, 미리 채워 넣어 봐야 정작 사고가 났을 때 기댈 수가 없습니다.

 

갱신 책임도 같이 정해 두었습니다. 실제 에러에 대응할 때마다 그 모듈의 ⑤⑥⑦에 한 줄씩 쌓고, 코드 변경을 병합할 때 ①②⑧을 함께 손봅니다.

 

네 번째, 코드가 답할 수 있는 건 적지 않습니다

 

문서를 만들다 보면 함수 시그니처와 데이터베이스 구조와 API 경로까지 다 적고 싶어집니다. 저는 이걸 의도적으로 뺐습니다.

 

이런 항목은 검색 한 번이면 값이 그대로 튀어나옵니다. AI에게 찾아보라고 시키면 몇 초면 끝납니다. 그런데 문서에 또 적어 두면 코드가 바뀔 때마다 두 곳을 고쳐야 하고, 언젠가 반드시 한쪽이 낡습니다.

 

그래서 이 문서가 담당하는 것은 코드가 답하지 못하는 영역, 즉 운영하며 얻은 경험과 대응 절차입니다.

 

같은 이유로 규모를 적는 방식에도 선을 그었습니다. 파일 줄 수는 어느 모듈을 먼저 깊게 파야 할지 가늠하는 스냅샷으로만 남기고, 검색하면 바로 나오는 메서드나 함수 개수는 문서에 박지 않습니다.

 

한 가지 더 있습니다. 실험용으로 만들어 둔 코드 경로는 운영 파이프라인이 호출하지 않으므로, 에러 라우팅 후보에서 아예 제외한다고 문서에 명시해 두었습니다. AI가 엉뚱한 곳을 뒤지는 시간을 줄이는 장치입니다.

 

다섯 번째, 사고가 몰릴 곳부터 먼저 깊게

 

모든 모듈을 같은 깊이로 채우지는 않습니다.

 

상태가 단계별로 넘어가는 지점이나 비동기 처리의 경계처럼, 사고가 몰릴 것으로 예상되는 자리를 먼저 지목해 그곳만 깊게 팠습니다.

 

실제로 그렇게 먼저 판 한 곳에는 지금 다섯 줄이 들어가 있습니다. 코드를 읽으면서 "여기서는 이런 식으로 터진다"를 미리 뽑아 둔 씨앗 목록입니다.

 

그중 네 줄을 옮겨 보면 이런 모양입니다.

 

증상	원인
409 Conflict, 확정 요청이 거부됨	이전 단계가 끝나지 않은 상태에서 확정을 호출
404 Not Found	상태 레코드가 아직 만들어지지 않음
작업이 실패 응답으로 돌아옴	필요한 데이터 재조회에 실패(예외를 던지지 않고 결과값으로 반환)
작업 요청은 보냈는데 실행이 안 됨	작업 지시를 대신 받아 두는 중간 서버(메시지 브로커)가 연결되지 않았거나, 그 지시를 꺼내 처리할 프로세스가 떠 있지 않거나, 실행 방식 설정이 어긋남

 

다섯 줄 모두 코드에서 근거를 짚어 적었기 때문에, 증상과 원인이 특정 파일까지 이어집니다. 근거 없이 머릿속에서 지어낸 목록과는 쓸모가 다릅니다.

 

여기서 한 걸음 더 나간 응급 대응과 로그 항목은, 실제로 한 번 겪어야 채워집니다.

 

시행착오 하나, 같은 문서를 두 곳에 뒀습니다

 

처음 이 문서를 만들 때 실수가 하나 있었습니다.

 

코드 저장소 안에도 경로를 안내하는 문서가 하나 있었고, 운영 문서 쪽에도 비슷한 성격의 것이 따로 자라고 있었습니다. 성격이 같은 정보가 두 군데로 나뉘면, 정작 급할 때 어느 쪽이 맞는지부터 헷갈립니다.

 

결국 코드 저장소 쪽 문서를 운영 문서 쪽으로 흡수해 하나로 합쳤습니다. 그 뒤로는 같은 성격의 문서를 두 곳에서 각각 키우지 않기로 했습니다.

 

지금은 절반만 채워져 있습니다

 

정직하게 현재 상태를 적어 둡니다.

 

구조층은 네 프로젝트의 모듈에 1차 골격까지 들어차 있지만, 실전층에 해당하는 ⑤⑥⑦은 대부분의 모듈에서 아직 "미기재"로 남아 있습니다. 앞서 말한, 사고가 몰릴 것으로 본 한 곳의 '흔한 에러' 칸에만 코드에서 뽑은 씨앗이 들어가 있습니다.

 

이 빈칸은 밀린 숙제라기보다 원칙이 눈에 보이는 상태에 가깝습니다. 코드를 읽어 판단할 수 있는 것은 미리 채우고, 겪어야만 아는 것은 뒤로 미룬다는 그 원칙 말입니다. 채워진 칸과 빈칸이 나란히 있는 모습 자체가 이 문서가 살아 있다는 신호이기도 합니다.

 

혹시 비슷한 문서를 만들어 보실 생각이라면, 아래 순서로 시작해 보시길 권합니다.

 

• 에러가 났을 때 어느 프로젝트, 어느 모듈로 갈지 라우팅 순서를 먼저 적었는가
• 모듈마다 채울 항목을 미리 고정했는가 (많아도 열 개 안쪽)
• 코드를 읽고 판단해 지금 적을 수 있는 항목과, 겪어야만 채워지는 항목을 나눠 두었는가
• 검색하면 값이 그대로 나오는 정보를 문서에 중복해 적고 있지는 않은가
• 사고가 몰릴 것 같은 지점을 한 곳 이상 지목했는가
• 같은 성격의 문서가 두 군데에서 각각 자라고 있지는 않은가
• 에러를 한 번 처리할 때마다 문서에 한 줄 남기는 습관이 있는가

 

AI에게 개발을 맡긴다는 건 코드를 대신 짜 준다는 뜻만은 아니었습니다. 사고가 났을 때 어디부터 보라고 알려 줄 문서를 제가 대신 써 둬야 한다는 뜻이기도 했습니다.

 

그 문서는 사고가 한 번 날 때마다 한 줄씩 늘어납니다.