혼자 일하는 개발자도 설계 문서를 써야 할까요?

커머스 기능 하나를 설계 문서 작성부터 구현까지 끝내보라는 과제를 받았습니다. 과제 설명을 읽자마자 든 생각은 좀 엉뚱했습니다. 설계 문서, 정말 꼭 써야 하나?

 

저희는 기획, 디자인, 개발을 한 팀에서 다 합니다. 고객 요청이 들어오면 내용을 구체화해서 기능을 확정하고, 곧바로 구현으로 넘어갑니다. 기능이 정해지면 저는 머릿속으로 반례를 몇 개 떠올려 보고, 이 기능을 어느 모듈이 책임져야 할지 대강 그림을 그린 다음 클로드와 대화를 시작합니다. 이 과정에는 설계 문서가 없습니다.

그래서 이런 생각이 들었습니다. 설계 문서의 가장 큰 목적은 층위가 분리된 두 집단, 예를 들면 기획과 개발 사이의 소통이 아닐까요? 그렇다면 기획하는 사람과 구현하는 사람이 같은 저희 팀에서 문서는 어떤 의미를 가질까요?

가정을 좀 더 극단으로 밀어 보겠습니다. 기획도 개발도 혼자 하는 사람이 있습니다. 소통할 상대가 없는 그는 여전히 설계 문서를 써야 할까요? 

설계와 설계 문서

생각을 풀다 보니 제가 처음부터 두 가지를 뭉뚱그리고 있었다는 걸 알았습니다. 설계와 설계 문서입니다.

설계란 뭘까요. 저는 이렇게 정의해 봤습니다. 불완전한 요구사항과 동작하는 코드 사이의 빈칸을 '결정'으로 채우는 일.

 

이렇게 놓고 보면 설계는 문서가 있든 없든 항상 일어납니다. 의식하고 정했는지, 코드를 짜다가 얼결에 정해졌는지가 다를 뿐입니다. 문서 없이 일해온 저희 팀도 설계를 안 한 게 아니었습니다. 설계는 했고, 적지 않았을 뿐입니다.

 

설계가 무엇인지 정의했습니다. 그렇다면 설계 문서란 단순히 설계의 결과물 일까요? 정의하기 전에 문서가 어떤 역할을 하는지 적어봤습니다.

1. 소통: 제가 처음 떠올린 바로 그 목적입니다.
2. 코드에 담기지 않는 맥락의 보존: 개념 모델을 어떻게 나눴는지 같은 상위 수준의 구조, 그리고 왜 이렇게 결정했고 무엇을 포기했는지 같은 트레이드오프가 여기에 속합니다.
3. 생각 정리: 문서를 쓰다 보면 머릿속에서는 매끄럽던 설계의 빈틈과 모순이 드러납니다.
4. AI에게 건넬 입력: 명확한 문서가 있으면 더 명확한 지시를 내릴 수 있습니다.

적어 놓고 보니 네 가지의 성격이 둘로 갈립니다.

1번과 2번은 결과물로서의 문서입니다. 다 쓰인 뒤에 누군가 읽음으로써 가치가 생깁니다.

3번과 4번은 도구로서의 문서입니다. 여기서 가치는 읽히는 데 있지 않고 쓰는 과정, 혹은 코드가 만들어지는 과정에 있습니다.

혼자 일하는 개발자에게 남는 것

이제 처음의 극단적인 가정으로 돌아가 하나씩 지워 보겠습니다. 혼자 일한다면 1번 소통은 해당되지 않습니다. 3번과 4번은 분명 쓸모가 있지만, 건물이 올라가면 철거하는 비계와 같습니다. 코드가 완성된 뒤에는 굳이 보존할 이유가 없습니다. 제 역할을 다한 것이니까요.

그러면 하나가 남습니다. 코드에 담기지 않는 맥락입니다. 코드는 설계의 가장 정확한 표현물입니다. 하지만 코드는 선택된 길만 보여 줍니다. 검토했다가 버린 대안, 그 대안을 버린 이유, 이 구조가 감수하고 있는 비용은 코드 어디에도 없습니다.

그래서 저는 설계 문서를 이렇게 정의하기로 했습니다. 설계를 표현한 것들 가운데 코드가 잃어버리는 쪽을 맡는 문서. 설계의 대부분은 코드가 이미 말해줍니다. 문서는 코드가 말해주지 못하는 나머지를 맡으면 됩니다.

처음 질문에 답하자면, 혼자 일해도 설계 문서는 필요합니다.

그래서, 무엇을 적어야 할까요

앞에서 설계는 결정의 연속이라고 했습니다. 변수 이름 하나, 함수 경계 하나도 결정입니다. 코드가 잃어버리는 결정을 전부 적겠다고 나서면 문서는 거의 무한히 길어집니다. 

 

결국 기록할 가치가 있는 결정을 골라내야 합니다. 나중에 뒤집기 어려운 결정, 코드만 봐서는 이유를 짐작할 수 없는 결정, 다른 선택지가 충분히 그럴듯했던 결정. 그런 것들을 알아보는 눈이 필요합니다.

 

어떤 결정을 적을지 고르려면, 내가 지금 어떤 결정들을 내리고 있는지부터 알아야 합니다. 얼결에 정해진 것들은 적을 후보에도 못 오릅니다. 기록할 결정을 잘 고르는 능력은 설계를 잘하는 능력과 꽤 많이 겹치는 것 같습니다.