설계 문서가 대체 뭘 위한 걸까요
코드를 쓰기 전에 문서부터 쓰라고 하면 귀찮게 느껴지죠. 저도 처음엔 그랬어요. 그런데 설계 문서(Design Document)가 뭐냐면, 단순히 '이렇게 만들 거예요'를 적어두는 기록이 아니에요. 코드를 한 줄도 쓰기 전에 내 계획의 허점을 다른 사람이 찾아내게 만드는 도구예요. 코드를 다 짜고 나서 '이 구조는 좀 아닌 것 같은데요'라는 리뷰를 받으면 몇 주가 날아가지만, 문서 단계에서 같은 지적을 받으면 몇 시간이면 고칠 수 있거든요.
Refactoring English라는 책의 한 챕터로 공개된 이 글은, 바로 이 관점에서 설계 문서를 어떻게 써야 하는지를 아주 실용적으로 풀어줘요. 글쓴이인 Michael Lynch는 구글에서 일하다가 독립한 개발자인데, 개발자를 위한 글쓰기에 대해 꾸준히 좋은 글을 써온 사람이에요.
가장 흔한 실수: 해결책부터 쓰기
많은 설계 문서가 이렇게 시작해요. 'Redis 캐시 레이어를 추가하고, 워커를 3개로 늘리고, 큐를 Kafka로 바꾼다.' 그런데 이걸 읽는 사람은 이런 생각이 들어요. '그래서 왜?'
문서의 첫 부분은 반드시 문제여야 해요. 지금 뭐가 안 되고 있는지, 그게 왜 문제인지, 누가 얼마나 아픈지. 예를 들어 '결제 API의 p99 응답 시간이 4초를 넘어서 결제 이탈률이 올라가고 있다'라고 시작하면, 읽는 사람이 해결책을 평가할 기준이 생기거든요. 문제가 명확하면 리뷰어가 '그 문제라면 Kafka까지 갈 필요 없이 이렇게 해도 되지 않아요?'라고 더 나은 대안을 제시할 수도 있어요. 문제를 안 적으면 그런 피드백 자체가 불가능해요.
목표와 비목표를 분명히
문제 다음에 오는 게 목표(Goals)와 비목표(Non-goals)예요. 비목표가 뭐냐면, '이번엔 일부러 안 하기로 한 것'이에요. 이게 정말 중요한데요, 리뷰어들이 '근데 이건 왜 안 해요?'라고 묻는 시간을 확 줄여주거든요. 예를 들어 '이번 설계에서 멀티 리전 장애 조치는 다루지 않는다. 별도 프로젝트로 진행 예정'이라고 한 줄만 적어두면, 리뷰 코멘트 열 개가 사라져요.
독자가 누구인지 정하세요
설계 문서는 소설이 아니에요. 읽는 사람이 정해져 있어요. 같은 팀 시니어 엔지니어인지, 옆 팀의 인프라 담당자인지, 아니면 기술을 잘 모르는 PM인지에 따라 써야 하는 내용이 완전히 달라져요. 팀 내부용 문서에 우리 팀이 매일 쓰는 서비스 설명을 세 문단씩 넣을 필요는 없고, 반대로 다른 팀에게 보여줄 문서라면 우리만 아는 약어를 그대로 쓰면 안 되죠.
글쓴이가 강조하는 팁 하나는, 리뷰어에게 무엇을 봐달라고 할지 명시하라는 거예요. '전체적으로 봐주세요'는 최악이에요. 대신 '3번 섹션의 데이터 모델과 5번 섹션의 마이그레이션 순서에 특히 의견을 부탁드려요'라고 쓰면, 리뷰어가 어디에 집중해야 하는지 알게 되고 피드백의 질이 확 올라가요.
대안을 솔직하게 비교하세요
좋은 설계 문서에는 '고려했지만 선택하지 않은 대안' 섹션이 꼭 있어요. 이게 왜 중요하냐면, 두 가지 효과가 있거든요. 첫째, 리뷰어가 '이건 생각해봤어요?'라고 물어볼 것들을 미리 답해줘요. 둘째, 내가 정말로 여러 선택지를 비교한 다음 결론을 냈다는 걸 보여줘서 신뢰가 생겨요.
다만 여기서 함정이 있어요. 대안을 일부러 약하게 써서 내 선택이 돋보이게 하는 거예요. 이러면 경험 많은 리뷰어는 바로 알아채고, 문서 전체의 신뢰도가 떨어져요. 각 대안의 장점을 솔직하게 적고, 그럼에도 왜 이걸 골랐는지 트레이드오프(어떤 걸 얻기 위해 어떤 걸 포기하는지)를 설명하는 게 훨씬 설득력 있어요.
짧게 쓰세요, 안 그러면 안 읽어요
문서가 길수록 꼼꼼해 보일 것 같지만, 현실은 반대예요. 스무 페이지짜리 설계 문서를 끝까지 읽고 의미 있는 피드백을 주는 사람은 거의 없어요. 대부분 앞부분만 훑고 '좋아 보이네요' 하고 승인 버튼을 누르죠. 그러면 문서를 쓴 목적 자체가 사라져요.
그래서 구현 세부사항을 과하게 적지 말라는 조언이 나와요. 함수 시그니처 하나하나, 테이블 컬럼 타입 하나하나까지 적으면 문서는 길어지고, 정작 중요한 구조적 결정은 묻혀버려요. 설계 문서는 결정이 필요한 것에 집중해야 해요. 나머지는 코드 리뷰에서 다루면 돼요.
또 하나, 문서를 '완성'하고 나서 공유하지 말라는 것도 중요해요. 설계 문서는 피드백을 받기 위한 건데, 이미 마음을 다 정한 뒤에 보여주면 '승인 도장 받기'가 돼버리거든요. 초안 상태에서 공유하고, 아직 못 정한 질문을 그대로 남겨두는 게 좋아요.
한국 개발자에게 주는 시사점
한국 개발 문화에서는 설계 문서를 쓰는 팀과 안 쓰는 팀의 차이가 정말 커요. 안 쓰는 팀은 보통 구두로 얘기하고 바로 코딩에 들어가는데, 3개월 뒤에 '왜 이렇게 만들었지?'를 아무도 기억 못 하는 상황이 생겨요. 설계 문서는 팀의 기억이기도 해요.
그리고 요즘은 AI 코딩 도구 시대잖아요. 좋은 설계 문서는 AI에게 주는 최고의 컨텍스트이기도 해요. 문제, 목표, 비목표, 선택한 구조와 이유가 명확한 문서를 Claude나 Copilot에게 주면 결과물의 품질이 완전히 달라져요. 설계 문서를 잘 쓰는 능력이 AI 시대에 오히려 더 중요해진 이유예요.
주니어라면 작은 기능부터 한 페이지짜리 설계 문서를 써보는 걸 추천해요. 문제 한 문단, 목표와 비목표, 접근 방법, 대안 하나 정도. 이 정도만 해도 시니어와 대화하는 방식이 달라져요.
마무리
한 줄로 정리하면, 설계 문서는 코드가 아니라 결정을 리뷰받기 위한 도구이고, 문제부터 시작해서 짧게 쓰는 게 핵심이에요. 여러분 팀은 설계 문서를 쓰고 있나요? 쓴다면 실제로 피드백이 오가는지, 아니면 형식적으로 승인만 받고 끝나는지 궁금하네요.
🔗 출처: Hacker News