아키텍처 의사결정 기록

페이지덱의 결제 화면을 고치던 태오가 요금 정보를 왜 이런 구조로 저장했는지 물었는데, 답할 수 있는 사람이 없었습니다. 그렇게 정한 사람은 이미 회사를 떠났고, 코드에는 무엇을 했는지만 남아 있었습니다.

코드는 결정의 결과만 보여 줍니다. 어떤 대안이 함께 올라왔는지, 그중 무엇을 왜 버렸는지, 그때 어떤 제약이 걸려 있었는지는 한 줄도 남지 않습니다. 이유를 모르는 구조 앞에서 팀은 둘 중 하나로 움직입니다. 무서워서 손대지 못한 채 그 위에 새 코드를 얹거나, 별 이유 없겠거니 하고 갈아엎었다가 원래의 이유였던 함정에 그대로 빠집니다. 후자가 더 비쌉니다. 페이지덱도 한 번 겪었습니다. 느려 보인다는 이유로 저장 구조를 바꿨다가, 두 달 뒤 기업 고객의 정산 자료가 어긋나면서 원래 구조가 그 정산을 맞추려고 만들어진 것이었다는 사실을 알았습니다.

회의에서 결론이 나지 않은 것도 아니었습니다. 문제는 남는 물건이 회의록뿐이라는 데 있었습니다. 회의록은 오간 말을 시간순으로 적은 글이라 결론이 어느 줄인지 찾아 읽어야 하고, 그 자리에 없던 사람에게는 앞뒤 사정이 빠진 채로 읽힙니다. 그래서 회의가 아니라 결정 하나를 단위로 삼고, 아무도 미루지 않을 만큼 짧은 형식을 정해 코드 바로 옆에 두자는 방식이 자리 잡았습니다.

한 장은 네 칸으로 적습니다. 어떤 상황이었는지, 무엇으로 정했는지, 그래서 무엇이 따라오는지, 지금 이 결정이 살아 있는지입니다.

1. 맥락 — 이 결정이 필요했던 사정을 적습니다. 무엇이 문제였고 어떤 제약이 걸려 있었는지까지 씁니다. 반년 뒤에 읽는 사람이 판단을 되짚으려면 결론보다 이 칸이 필요합니다.
2. 결정 — 무엇으로 정했는지 한두 문장으로 못 박습니다. 여기에 함께 검토한 대안과 그것을 버린 이유를 붙입니다. 버린 쪽을 적지 않으면 나중에 누군가 그 대안을 새 아이디어처럼 다시 들고 옵니다.
3. 결과 — 이 결정으로 무엇이 좋아지고 무엇이 나빠지는지 함께 적습니다. 좋은 점만 적힌 기록은 팔기 위한 글이지 기록이 아닙니다. 검색이 빨라지는 대신 저장 용량이 두 배로 든다면 그 두 배도 같은 칸에 들어갑니다.
4. 상태 — 이 결정이 지금도 유효한지 표시합니다. 제안됨, 채택됨, 폐기됨 정도로 씁니다. 폐기된 기록은 지우지 않고 상태만 바꾸는데, 무엇이 언제 왜 뒤집혔는지가 다음 사람에게는 결정 자체만큼 쓸모 있기 때문입니다.

앞에 제목과 날짜와 번호를 답니다. 번호는 순서대로 붙여 나중에 다른 기록에서 가리킬 때 씁니다. 페이지덱이 실시간 공동 편집을 붙일 때 남긴 007번 기록은 이렇게 생겼습니다. 맥락 칸에는 같은 문서를 두 명이 동시에 고치면 뒤에 저장한 쪽이 앞의 수정을 덮어쓴다는 문제가, 결정 칸에는 충돌을 자동으로 합쳐 주는 방식을 쓰기로 했다는 문장과 잠금 방식을 버린 이유가, 결과 칸에는 서버 비용이 늘고 오프라인 지원이 어려워진다는 대가가 들어갔습니다. 전체가 한 화면이었습니다.

기록은 결정을 내린 사람이 직접 씁니다. 대안을 왜 버렸는지는 그것을 고른 사람 머릿속에만 있어서, 옆에서 지켜본 사람이 대신 쓰면 결론만 남고 판단이 빠집니다. 페이지덱에서는 결정이 끝난 회의의 마지막 15분을 이 일에 씁니다. 나중에 쓰겠다고 미루면 영영 쓰지 않게 되고, 일주일만 지나도 그때 무엇이 걸렸는지가 흐려집니다.

읽는 사람은 셋입니다. 반년 뒤에 그 코드를 고치는 사람, 새로 들어와 구조를 익히는 사람, 그리고 자기가 왜 그렇게 정했는지 잊어버린 본인입니다. 셋 다 결정을 되돌릴지 말지를 판단하려고 이 글을 폅니다. 그래서 기록이 답해야 하는 질문은 하나로 좁혀집니다. 이 결정을 지금 뒤집어도 되는가.

두는 자리도 형식의 일부입니다. 문서 도구가 아니라 코드와 같은 저장소 안에 텍스트 파일로 둡니다. 코드를 고치는 사람이 코드를 보다가 바로 옆에서 이유를 찾을 수 있어야 하기 때문입니다. 자리가 같으니 확인 절차도 같아집니다. 새 기록은 코드와 함께 올려 코드 리뷰를 거치는데, 동료가 읽고 맥락 칸이 부족하다고 짚으면 그 자리에서 채웁니다.

"이거 왜 이렇게 돼 있어요? 기록 있나요?"

코드만 봐서는 판단이 안 서니 결정 당시의 사정을 찾자는 말입니다.

"결정은 났으니까 기록 한 장 남기고 닫을게요."

논의를 더 끌지 않고 결론과 버린 대안만 추려 남기겠다는 뜻입니다.

"그 기록 상태가 폐기로 바뀌었어요. 012번을 보세요."

예전 결정이 이미 뒤집혔으니 지금 유효한 쪽을 대신 읽으라는 안내입니다.

페이지덱에서 태오가 검색 기능을 다른 저장 방식으로 옮기자고 제안한 날, 지현이 2년 전 기록을 찾아 왔습니다. 그때도 같은 제안이 올라왔고, 기업 고객의 자료 보관 요건 때문에 접었다는 내용이 맥락 칸에 적혀 있었습니다. 태오는 그 요건이 지금도 유효한지 수아에게 확인했고, 계약이 바뀌어 더는 걸리지 않는다는 답을 듣고 나서 제안을 다시 올렸습니다.

기록이 결정을 막지는 않았습니다. 논의의 출발점을 바꿨을 뿐입니다. 기록이 없었다면 그날의 대화는 이 방식이 좋은지 나쁜지에서 시작했겠지만, 기록이 있었기에 2년 전에 걸렸던 조건이 지금도 걸리는지에서 시작했습니다.

설계 문서의 요약본으로 여기는 경우가 가장 흔합니다. 둘 다 시스템 구조를 다루니 자연스러운 오해입니다. 그런데 단위가 다릅니다. 설계 문서는 시스템 전체가 지금 어떤 모습인지를 그리고 구조가 바뀔 때마다 갱신됩니다. 기록은 결정 하나와 그때의 사정을 담고 한 번 쓰면 손대지 않습니다. 이 둘을 섞으면 기록이 설계 문서를 따라 길어지고, 길어진 형식은 아무도 쓰지 않아 반년 만에 조용히 사라집니다.

결정이 뒤집히면 기록을 고쳐야 한다고 생각하는 것도 잦습니다. 지금과 다른 내용이 남아 있는 게 어색해 보이니 그렇습니다. 하지만 고치지 않고 상태만 폐기로 바꾼 뒤 새 기록을 씁니다. 새 기록의 맥락 칸에 예전 기록 번호를 적어 두면 무엇이 언제 왜 뒤집혔는지가 함께 읽힙니다. 덮어써 버리면 그 이력이 통째로 사라지고, 1년 뒤 누군가 처음 버려진 대안을 새 제안처럼 다시 들고 옵니다.