내 말을 그대로 적어 둔다

게임 소스에서 가장 많이 쓰는 주석 표시는 [사용자]다. 내가 요구했거나 결정한 것이라는 뜻인데, 표시만 하는 게 아니라 그때 한 말을 큰따옴표로 옮겨 둔다. 이런 모양이다.

처음엔 그냥 편해서 그렇게 했다. 요약해서 옮기려면 한 번 더 생각해야 하니까. 그런데 몇 달 쌓이고 보니 요약하지 않은 것이 이득이었다. 이유가 셋이다.

첫째, 말투에 판단 기준이 들어 있다

이걸 요약하면 "맡김 후 다음 부대로 자동 이동"이 된다. 요구는 남지만 근거가 사라진다. "이민족의 토목처럼"이라는 말에는 이미 있는 기능을 기준으로 삼자는 판단이 들어 있고, "일관성있을거 같은데"는 그 판단의 이유다.

나중에 비슷한 자리에서 결정할 때, 요약된 명세는 도움이 안 된다. "일관성"을 기준으로 삼았던 사람의 말은 도움이 된다.

둘째, 관찰의 구체성이 남는다

위의 "1개는 정찰가고 2개는 해안선 근처에서 가만히 있음"을 다시 보자. 요약하면 "정찰 맡김이 작동하지 않음"이 된다. 그런데 원문에는 부분 성공이라는 정보가 들어 있다.

하나는 갔고 둘은 멈췄다. 이건 "기능이 안 돈다"와 전혀 다른 진단이다. 전부 안 도는 것이면 연결이 안 된 것이고, 일부만 도는 것이면 조건 어딘가에서 갈린다는 뜻이다. 숫자 하나가 원인의 방향을 가리킨다.

요약은 이런 걸 반올림해 버린다. 그리고 반올림된 정보로는 며칠 뒤에 다시 디버깅을 시작해야 한다.

셋째, 나중에 누가 맞았는지 판정할 수 있다

이게 제일 뜻밖의 이득이었다. 원문이 남아 있으면 그 말이 맞았는지 틀렸는지를 나중에 채점할 수 있다.

확인해 보니 의심이 맞았다. 그래서 주석이 이렇게 이어진다.

[사용자] 주석 중에 "맞다."로 시작하는 것들이 꽤 있다. 내가 뭔가 이상하다고 했고, 확인해 보니 정말 그랬던 경우다.

이걸 적어 두는 게 왜 중요한가. 다음에 같은 종류의 의심이 들 때 그걸 무게 있게 다루게 된다. "숫자를 보면 맞는데 뭔가 이상하다" — 이 느낌이 과거에 여러 번 맞았다는 기록이 있으면, 그 느낌을 근거로 다시 재 볼 수 있다.

반대 경우도 값을 한다. 내가 잘못 짚었던 기록이 남아 있으면 같은 착각을 덜 한다.

한 마디가 도구가 되기도 한다

지나가듯 한 말인데, 이게 도구 하나가 됐다. 맞닿은 두 타일의 경계 픽셀 색을 견줘 "조화"를 점수로 매기는 프로그램이다. 나쁜 조합을 순위로 뽑아 준다.

추상적인 요구를 측정 가능한 것으로 번역한 셈이다. 이런 번역이 가능한 이유가 원문이 남아 있는 것과 관계가 있다. "조화롭게"라는 낱말이 그대로 있으니 "그러면 조화를 어떻게 재지?"라는 다음 질문이 나온다.

표시가 갈라진다

쌓이다 보니 [사용자] 하나로는 부족해져 뒤에 갈래를 붙이기 시작했다. 지금 이렇게 쓰고 있다.

갈래를 나눈 덕에 검색이 쓸모 있어졌다. 화면 관련 결함만 훑고 싶으면 [사용자·화면]을 찾으면 된다. 요구사항 목록을 따로 관리하지 않는데도 목록이 코드 안에 있는 셈이다.

시험에도 같은 표시가 붙는다

[사용자]는 시험 파일에도 253번 나온다. 어떤 시험이 어떤 요구에서 나왔는지가 적혀 있는 것이다.

그 시험은 지금 "한 턴이 몇 초 안에 끝나야 한다"를 지킨다. 왜 그 시험이 존재하는지가 첫 줄에 적혀 있으니, 나중에 그 시험이 깨질 때 무엇을 지키려던 것인지를 바로 안다.

설계 문서를 쓴 기능은 한 걸음 더 갔다. 시험 설명에 문서의 절 번호를 적어 뒀다. 코드에서 문서로, 문서에서 코드로 양쪽 다 찾아갈 수 있다.

AI와 일할 때 값을 하는 지점

이 습관이 사람과 일할 때보다 AI와 일할 때 훨씬 값을 한다. 세 가지 이유로.

1. 세션이 바뀌어도 의도가 안 사라진다

대화는 끝나면 없어진다. 다음 세션의 AI는 어제 무슨 얘기를 했는지 모른다. 그런데 코드를 읽으면 안다 — 왜 이 줄이 이렇게 되어 있는지가 그 옆에 적혀 있으니까. 맥락을 매번 다시 설명하지 않아도 된다.

2. "왜 이렇게 되어 있나"에 코드가 답한다

AI가 리팩터링을 제안할 때 가장 위험한 것은 이유가 있는 코드를 이유 없다고 보고 정리하는 것이다. 이상하게 생긴 코드에는 대개 사연이 있다.

그 사연이 옆에 적혀 있으면 그 제안이 안 나온다. 실제로 "예전엔 이렇게 했는데 이런 문제가 있었다"가 적혀 있는 자리는 건드리자는 말이 나오지 않는다.

3. 내가 말을 바꾼 것이 드러난다

이건 좀 부끄러운 쪽인데, 유용하다. 예전에 A로 하자고 했던 기록이 남아 있으면, 지금 B로 하자고 할 때 내가 방향을 바꿨다는 걸 스스로 안다. 바꾸는 게 문제가 아니라, 바꾼 걸 모르는 게 문제다.

실제로 이 기록 덕에 "그때는 이렇게 정했는데 지금은 상황이 달라졌다"를 명시적으로 적게 됐다. 그러면 다음에 또 헷갈리지 않는다.

단점도 있다

정직하게 적으면, 주석이 길다. 함수 하나에 설명이 스무 줄인 자리도 있다. 코드만 빠르게 훑고 싶을 때 방해가 된다.

그리고 낡는다. 코드를 고치면서 주석을 안 고치면 거짓말이 된다. 실제로 한 번 대청소를 했다 — 자료를 갈아 끼우면서 "예전 방식으로 그린다"고 적혀 있던 주석 열아홉 곳을 찾아 고쳤다. 찾아 고칠 수 있었던 건 그 주석들이 일정한 문구를 쓰고 있었기 때문이다.

그래도 남기는 편이 낫다고 본다. 긴 주석을 읽는 값은 몇 초고, 왜 그렇게 됐는지를 잃는 값은 몇 시간이다. 그 몇 시간을 이미 여러 번 치러 봤다.