AI에게 일을 맡겨보면 금방 알게 되는 게 있습니다. 문제는 참 잘 찾습니다. 데이터가 안 맞는다, 이 계산이 이상하다, 이 규칙은 여기서 깨진다 — 시키지 않아도 계속 나옵니다.
그런데 그다음이 문제였습니다. 찾아준 걸 제가 기억하지 못했습니다. 그날 대화창에서 한 번 읽고 넘어가면 끝입니다. 며칠 뒤 같은 문제가 다시 나오고, 그제야 "아 이거 전에 봤던 건데" 합니다.
그래서 표를 한 장 만들었습니다. 거창한 게 아니라 마크다운 표 하나입니다.
미리 밝혀두면, 이건 제가 혼자 혹은 아주 작은 규모로 파일 하나를 굴리며 얻은 방법입니다. 여러 사람이 동시에 쓰거나 감사·보안 요구가 큰 조직이라면 전용 이슈 트래커가 맞습니다.
규칙은 세 가지입니다
하나, 발견하면 그 자리에서 적습니다. 고칠 수 있을 때 적는 게 아니라, 못 고쳐도 적습니다. 제 경우 "나중에 고쳐야지"만 해둔 건 거의 안 고쳐졌습니다. 오히려 시간이 없을 때일수록 적어야 합니다. 한 줄이면 됩니다 — 뭘 봤고, 왜 문제인지.
둘, 지우지 않습니다. 상태만 바꿉니다. 해결되면 지우고 싶어지는데, 따로 이력을 남겨두지 않았다면 지우는 순간 왜 그렇게 고쳤는지도 같이 사라집니다. 반년 뒤 비슷한 문제가 오면 조사를 처음부터 반복하게 됩니다. 진행에서 종결로 바꾸고 그 아래에 근거를 붙여둡니다.
셋 — 이게 핵심입니다 — 정기 점검의 첫 줄을 "내 미결 목록 갱신"으로 박아둡니다. 제 경우 이게 없을 때 원장은 그냥 쌓이기만 했습니다. 적어둔 게 정해진 주기로 눈앞에 다시 나타나야 목록이 살아 있습니다.
제 원장에서는 이런 게 잡혔습니다
얼마 전 하루에 서른 건 넘게 훑어봤는데, 두 건은 이미 다 고쳐놓고 티켓만 열려 있었습니다. 일이 밀린 게 아니라 닫는 걸 잊은 겁니다. 목록만 보면 밀린 일처럼 보이는데 실제로는 아니었습니다.
반대 경우도 있었습니다. 적어둔 해결책이 틀렸습니다. "이렇게 고치면 된다"고 스스로 적어놓은 방법이었는데, 실행하기 전에 실제로 몇 줄이나 걸리는지 세어봤더니 천 줄이 넘었습니다. 그대로 밀어붙였으면 멀쩡한 기록을 무더기로 뒤집을 뻔했습니다. 세어보고 나서야 알았고, 그 숫자를 다시 그 자리에 적어뒀습니다. 다음 사람이 같은 판단을 반복하지 않도록.
"코드로 만들어 공개하라"는 말을 들었는데
깔 만한 코드가 별로 없습니다. 다 합쳐 사백 줄이 안 되고, 하는 일은 둘뿐입니다 — 번호표 뽑기, 그리고 표가 안 깨졌는지 세기.
대신 제가 실제로 겪고 먼저 막은 고장 두 가지를 알려드릴 수 있습니다.
창을 둘 이상 띄우면 번호가 겹칩니다. 각자 "제일 큰 번호 + 1"을 계산하니까요. 그런데 카운터를 하나 두는 것만으로는 끝나지 않습니다 — 두 창이 같은 값을 동시에 읽으면 결국 같은 번호를 가져갑니다. 그래서 저는 파일 잠금 안에서 읽고·올리고·저장하는 걸 한 번에 처리하게 했습니다. 번호가 겹치면 한 줄은 진행, 다른 줄은 종결이 되고 "그거 끝났어?"의 답이 어느 줄을 보느냐로 뒤집힙니다.
번호만 문제가 아닙니다. 두 창이 파일 전체를 동시에 저장하면 한쪽 줄이 통째로 사라집니다. 그래서 쓰기 자체를 한 번에 하나씩만 들어가게 막아뒀습니다.
표가 길수록 깨진 줄을 못 찾습니다. 표 칸 안에 구분 기호를 그냥 쓰면 칸이 밀리는데, 줄이 많으면 밀린 줄이 눈에 안 띕니다. 세어보니 열다섯 줄이 그렇게 깨져 있었고, 그중 하나가 하필 "표가 깨져도 아무도 못 잡는다"고 적어둔 줄 자신이었습니다. 그 줄은 미결 상태였는데 어떤 집계에도 안 잡히고 있었습니다.
그대로 쓰실 수 있게 옮겨둡니다
원리만 말씀드리면 막상 시작하기 어렵습니다. 제가 쓰는 규칙을 그대로 옮깁니다.
아래는 프로젝트 파일을 직접 읽고 쓸 수 있는 에이전트형 AI 도구를 전제로 한 템플릿입니다. 대화만 하는 AI에서는 동작하지 않습니다. 넣기 전에 ① 파일 쓰기 권한과 작업 경로 ② 파일이 없을 때 표 헤더까지 포함해 새로 만들 것 ③ 이 파일이 아무나 볼 수 없는 위치인지, 세 가지를 확인하십시오.
■ 미결 이슈 원장 문제를 발견하면 docs/issues.md 에 한 줄 추가한다. 표 머리: ID / 등록일 / 발견 / 소관 / 이슈 / 상태 / 비고 규칙
- 발견 즉시 등록한다. 고칠 수 없어도 적는다. "나중에"는 없다. 이슈 칸에는 무엇을 봤는지와 왜 문제인지를 쓴다. 실측한 숫자가 있으면 넣되, 민감한 값은 마스킹한다.
- 행을 삭제하지 않는다. 상태만 바꾼다 (open → closed). 종결할 때 비고에 "무엇을 어떻게 고쳤는지 + 그 근거"를 남긴다. 조치안이 틀린 것으로 밝혀져도 지우지 말고, 왜 틀렸는지를 덧붙인다. 예외 — 비밀정보·개인정보·오등록은 보안 정책에 따라 즉시 마스킹하거나 지우고, 허용되는 범위에서 처리 사유만 남긴다.
- AI 가 제기한 것은 확인 전까지 비고에 [미검증] 으로 적고 재현 방법이나 근거를 함께 남긴다. 확인되면 [확인] 으로 바꾸고, 틀린 것으로 밝혀지면 지우지 말고 반증 근거를 남긴다.
- 한 번에 한 작성자만 이 파일을 쓴다. 숫자 ID 가 필요하면 파일 잠금 안에서 카운터를 읽고·올리고·저장하는 것을 한 스크립트가 통째로 처리한다. 그런 장치가 없으면 ID 는 UUID 를 쓴다. UUID 는 번호 충돌만 막는다 — 동시 저장으로 줄이 사라지는 건 별개 문제다.
- 표 칸 안에 구분 기호를 쓸 때는 역슬래시로 이스케이프한다 (GitHub 계열 렌더러 기준). 등록·수정 뒤 실제 쓰는 렌더러에서 그 줄이 일곱 칸으로 파싱되는지 확인한다. 구분 기호 개수를 세는 방식은 이스케이프한 것도 같이 세므로 쓰지 않는다. 상태값은 셋만 쓴다 — open(진행) / waiting(외부·상대 대기) / closed(해결)
그리고 제 경우, 이게 없을 때는 위의 표가 그냥 쌓이기만 했습니다. 정기적으로 돌리는 점검·리포트가 있다면, 그 지시문의 맨 첫 줄에 이걸 넣으십시오.
[0] docs/issues.md 에서 내가 맡은 미결 이슈(open, waiting)를 확인·갱신한다. waiting 은 무엇을 기다리는지와 다음 확인일을 비고에 적는다. 새로 발견한 것은 등록한다. 행은 삭제하지 않는다. — 이것을 보고의 첫 항목으로 낸다.
한 가지만 짚어두면, 이 문구 자체가 점검을 예약해주지는 않습니다. 이미 정기적으로 돌고 있는 작업의 첫 항목으로 넣거나, 스케줄러에서 그 작업을 불러주셔야 합니다.
주기는 이슈가 급한 정도에 맞추시면 됩니다. 핵심은 적어둔 것이 정해진 주기로 눈앞에 다시 나타나게 만드는 겁니다.
순서를 거꾸로 하지 마십시오
제가 얻은 결론은, 먼저 필요한 게 도구보다 기록 습관이었다는 겁니다. 표는 마크다운 한 장이면 되고, 코드는 나중에 붙여도 됩니다. 저는 반대로 코드부터 만들어봤는데 — 도구만 남고 기록은 빠졌습니다.
혹시 AI에게 일을 맡기고 계시다면 한 가지만 여쭙겠습니다. AI가 어제 찾아준 문제, 지금 어디에 있습니까?
