효과적인 소프트웨어 설계 문서 작성법

설계 문서는 구현 전에 어려운 문제와 중요한 결정을 검토하고, 팀원 및 협력 팀의 피드백을 모아 잘못된 구현에 시간을 낭비하지 않도록 돕는 도구임 문서에 담을 결정은 틀렸을 때의 비용으로 판단함. 언어나 저장소처럼 바꾸기 어려운 선택에 집중하고, 몇 시간 안에 수정할 수 있는 UI 세부사항에 검토 시간을 쓰지 않음 프로젝트의 복잡성과 위험이 클수록 문서의 가치가 높아짐. 다인 협업, 3개월 이상의 개발, 장기 운영, 모호한 요구사항 등이 판단 기준이며, 상황에 따라 문서를 작성하지 않는 것이 적절할 수도 있음 목적과 범위뿐 아니라 측정 가능한 SLO, 인터페이스, 의존성, 보안, 개인정보 보호, 운영 방식을 정리하되, 모든 문서에 모든 항목을 넣을 필요는 없음 미해결 쟁점과 결정 근거를 남겨 검토와 후속 판단을 지원함. 각 쟁점에는 선택지와 다음 행동을 적고, 해결 후에는 결정 요약과 기존 논의를 보존함 설계 문서의 역할과 작성 시점 좋은 설계 문서는 수년에 해당하는 개발 시간을 절약할 수 있으며, 해결할 어려운 문제를 명확히 하고 팀 간 설계 결정을 조율하는 데 도움이 됨 다음 조건 중 하나라도 해당하면 작성할 가치가 있을 가능성이 높고, 둘 이상이면 거의 확실히 가치가 있음 여러 사람이 구현 작업을 조율해야 함 전일제 개발 기준 3개월 이상 걸림 구현물을 프로덕션에서 수년간 운영함 팀 간 협업이 필요함 목표와 요구사항이 모호함 보안 결함이나 법적 위험처럼 설계 단계에서 예방할 수 있는 치명적 위험이 있음 투자 규모는 한 페이지부터 다섯 팀의 승인이 필요한 50페이지 문서까지 달라질 수 있음 적정 분량과 작성 시간은 팀의 목표, 위험, 마감, 문화에 달려 있으며, 보편적인 기준은 없음 때로는 설계 문서에 투자할 적정 시간이 0일 수도 있음 Little Moments 설계 문서는 실제 개발 중인 웹 앱을 위해 코드 작성 전에 만든 예시임 구현도 해당 설계를 따르고 있음 개인 취미 프로젝트로는 상세하지만, 여러 사람이 협업하는 업무용 프로젝트에 적합한 수준의 길이와 깊이를 갖춤 문서에 담을 결정: 잘못 선택했을 때의 비용 모든 세부사항을 명세하면 설계 단계에서 사실상 구현까지 하게 되므로, 오판의 비용을 기준으로 문서화 대상을 고름 웹 앱을 C++로 20만 줄 작성한 뒤 Ruby on Rails가 더 적합했음을 깨닫는 상황은 되돌리기 어려움 처음부터 다시 작성하는 접근의 문제가 있으며, 새 코드를 Rails로 작...