기술 설계서 및 ADR 기록

기술 설계서는 소프트웨어, 시스템, 제품 또는 기능을 구축하기 전에 그 구현 방안을 상세히 기술한 문서이다. 이는 요구사항을 구체적인 설계와 아키텍처로 변환하는 과정의 산출물이며, 개발팀이 무엇을, 어떻게 만들어야 하는지에 대한 청사진 역할을 한다.

기술 설계서는 일반적으로 시스템의 구성 요소, 데이터 모델, API 명세, 데이터베이스 스키마, 기술 스택, 비기능적 요구사항(성능, 보안 등)에 대한 해결책, 그리고 주요 워크플로우나 알고리즘을 포함한다. 이 문서는 단순한 아이디어 수준을 넘어, 실제 구현에 필요한 충분한 세부 사항을 제공하여 개발자들이 일관되고 효율적으로 작업할 수 있는 기반을 마련한다.

기술 설계서의 핵심 개념은 미리 계획함으로써 발생할 수 있는 문제를 사전에 예방하고, 팀원 간의 이해를 일치시키며, 구현의 복잡성을 관리 가능한 단위로 분해하는 데 있다. 이는 특히 복잡한 시스템이나 여러 개발자가 참여하는 프로젝트에서 필수적인 도구로 작용한다.

기술 설계서의 주요 목적은 구현을 위한 구체적인 청사진을 제공하는 것이다. 이는 개발자가 시스템의 특정 컴포넌트나 기능을 어떻게 구축할지에 대한 명확한 지침을 포함한다. 설계서는 요구사항을 실제 코드로 변환하기 위한 중간 다리 역할을 하여, 구현 과정에서의 오해와 불일치를 최소화한다.

기술 설계서의 필요성은 여러 측면에서 나타난다. 첫째, 복잡한 로직이나 새로운 기술을 도입할 때, 사전에 검토된 설계는 기술적 위험을 낮추고 구현의 일관성을 보장한다. 둘째, 이는 팀 내 지식 공유와 온보딩을 촉진한다. 새로운 팀원이나 관련 부서는 설계서를 통해 시스템의 특정 부분을 빠르게 이해할 수 있다. 셋째, 미래의 유지보수와 개선 작업에 있어 설계 의도와 배경을 기록함으로써 문서화의 가치를 제공한다[1].

ADR은 소프트웨어 아키텍처 결정과 그 배경, 결과를 문서화하는 간결한 기록이다. 이는 특정 아키텍처 문제에 대한 결정이 어떻게, 그리고 왜 내려졌는지를 포착하는 것을 목표로 한다. 단순히 최종 선택된 해결책만을 기록하는 것이 아니라, 고려된 대안들, 각 대안의 장단점, 그리고 최종 결정에 이르게 된 논의 과정과 맥락을 포함한다.

ADR은 일반적으로 하나의 결정에 초점을 맞춘 독립적인 문서로 관리된다. 각 기록은 특정한 제목, 날짜, 상태(예: 제안됨, 수용됨, 폐기됨, 대체됨), 결정 문장, 결정의 맥락, 고려된 여러 대안, 그리고 결정으로 인해 예상되는 결과를 포함하는 구조를 따른다. 이 구조는 결정의 복잡성을 단순화하고 핵심 정보에 빠르게 접근할 수 있도록 돕는다.

이러한 기록의 핵심 가치는 시간이 지남에 따라 팀의 집단 지성과 의사 결정 역사를 보존하는 데 있다. 프로젝트가 진행되거나 팀 구성원이 변경될 때, ADR은 특정 기술적 선택의 근거를 명확히 설명함으로써 지식의 소실을 방지한다. 또한, 비슷한 문제가 다시 발생했을 때 과거의 결정을 재검토하거나 새로운 맥락에서 재평가하는 데 유용한 기준을 제공한다.

기술 설계서의 주요 목적은 구현에 앞서 시스템의 청사진을 명확히 정의하는 데 있다. 이는 개발자 간의 공통된 이해를 형성하고, 요구사항을 구체적인 기술적 솔루션으로 전환하는 과정을 문서화한다. 또한, 프로젝트 초기에 설계 상의 결함이나 모순을 발견하여 수정 비용을 줄이고, 향후 유지보수 및 확장을 위한 참조 자료로 활용된다. 체계적인 설계 문서는 특히 복잡한 시스템이나 대규모 팀 프로젝트에서 커뮤니케이션 효율성을 극대화하는 필수 도구이다.

한편, ADR의 주요 목적은 특정 아키텍처 결정의 배경, 맥락, 그리고 결과를 기록하는 데 있다. 이는 단순히 '무엇'을 결정했는지보다 '왜' 그 결정을 내렸는지에 초점을 맞춘다. 따라서 시간이 지나거나 팀원이 변경되었을 때, 당시의 의사결정 과정을 재구성하고 이해하는 데 결정적인 역할을 한다. 또한 유사한 문제에 직면했을 때 과거의 결정을 참고하여 일관성을 유지하거나, 잘못된 결정을 반복하지 않도록 돕는다.

이 두 문서의 필요성은 지식의 지속성과 의사결정의 투명성에서 기인한다. 기술 설계서는 시스템의 정적 구조를, ADR은 그 구조를 이루는 동적 의사결정 과정을 보존한다. 이는 단기적인 개발 효율 향상뿐만 아니라, 장기적인 조직의 기술 부채 관리와 지식 공유 문화 구축에 기여한다. 문서화되지 않은 암묵적 지식에 의존하는 것은 프로젝트의 위험 요소가 될 수 있으며, 이러한 문서들은 그 위험을 체계적으로 완화한다.

기술 설계서의 작성 구조는 프로젝트의 규모와 복잡도에 따라 달라지지만, 일반적으로 다음의 핵심 구성 요소를 포함합니다.

* 개요 및 목적: 문서의 전반적인 목적과 설계가 다루는 범위를 명확히 정의합니다. 해결하려는 문제나 구현할 기능을 간략히 설명합니다.

* 시스템 아키텍처: 전체 시스템의 상위 수준 구조를 다이어그램(예: 컴포넌트 다이어그램, 시퀀스 다이어그램)과 함께 제시합니다. 주요 모듈, 컴포넌트, 그리고 이들 간의 상호작용과 데이터 흐름을 보여줍니다.

* 상세 설계: 핵심 컴포넌트나 알고리즘에 대한 구체적인 설계를 기술합니다. 인터페이스 정의, 데이터베이스 스키마, API 명세, 중요한 클래스나 함수의 의사코드 등을 포함할 수 있습니다.

* 비기능적 요구사항: 성능, 보안, 확장성, 가용성 등 시스템의 품질 속성에 대한 요구사항과 이를 충족하기 위한 설계 선택을 설명합니다.

* 대안 평가 및 결정 근거: 고려되었던 설계 대안들과 각 대안의 장단점, 최종 선택안을 결정한 이유를 기술합니다. 이는 ADR과 연결될 수 있습니다.

반면, ADR은 보다 표준화된 간결한 형식을 따르는 경우가 많습니다. 일반적인 ADR 템플릿은 다음과 같은 항목으로 구성됩니다.

* 제목: 결정 사항을 명확히 나타내는 간결한 제목(예: "ADR-001: 메시지 큐로서 RabbitMQ 채택").

* 상태: 제안됨(Proposed), 수락됨(Accepted), 폐기됨(Deprecated), 대체됨(Superseded) 등 결정의 현재 상태를 나타냅니다.

* 문맥: 결정을 필요로 하게 된 문제, 기술적 또는 비즈니스적 배경을 설명합니다.

* 결정: 내려진 아키텍처적 결정을 명확한 문장으로 기술합니다.

* 결정 이유: 해당 결정을 내리게 된 근거를 제시합니다. 다른 대안을 배제한 이유와 선택한 안의 이점을 포함합니다.

* 결과: 이 결정으로 인해 발생할 긍정적 및 부정적 결과(Consequences)를 나열합니다. 이는 팀이 미래에 발생할 수 있는 영향을 인지하는 데 도움을 줍니다.

기술 설계서 작성 시에는 우선 문서의 독자를 명확히 정의해야 한다. 독자는 프로젝트 관리자, 개발자, 테스터, 또는 새로운 팀원 등이 될 수 있으며, 각 대상에 맞는 적절한 기술 수준과 상세도를 제공해야 한다. 또한 문서의 범위를 명확히 한정하여 너무 광범위하거나 지나치게 세부적인 내용으로 인해 핵심이 흐려지지 않도록 주의한다. 모든 기술적 결정은 그 배경과 절충점, 예상되는 영향(성능, 유지보수성, 확장성 등)을 함께 기술하여 의사 결정의 맥락을 남기는 것이 중요하다.

다음으로, 문서는 정적이지 않고 진화하는 산물로 간주해야 한다. 초기 설계가 구현 과정에서 변경될 수 있으므로, 설계서도 이에 맞춰 지속적으로 갱신되어야 한다. 이를 위해 버전 관리 시스템을 활용한 변경 이력 관리가 필수적이다. 마지막으로, 가능한 한 구체적이고 검증 가능한 내용을 포함시켜야 한다. 모호한 표현 대신 API 명세, 데이터 스키마, 플로우차트, 의사 결정 트리 등을 활용하여 명확성을 높인다.

ADR 작성 시 가장 중요한 고려사항은 각 기록이 하나의 특정한 아키텍처 결정과 그 이유에 집중하도록 하는 것이다. 따라서 제목은 결정 사항을 명확히 반영해야 하며, '상태'(제안/수락/폐기) 필드를 통해 결정의 현재 생애 주기를 추적할 수 있어야 한다. 결정의 동기와 문맥을 상세히 기술하여, 미래에 같은 문제를 마주한 사람이 당시의 제약 조건과 고려 사항을 이해할 수 있게 한다.

ADR은 다양한 대안과 그 각각의 장단점을 객관적으로 비교한 후, 최종 선택에 이르는 논리를 제시해야 한다. '결정된 사항' 뿐만 아니라 '검토되었지만 기각된 대안'과 그 이유를 기록하는 것이 문서의 가치를 높인다. 마지막으로, 모든 ADR은 검색과 참조가 쉽도록 일관된 형식과 저장 위치를 가져야 하며, 결정이 폐기되거나 변경될 때는 새 ADR을 작성하고 이전 기록과의 연결 관계를 명시해야 한다[2].

기술 설계서 작성 예시

다음은 사용자 인증 시스템을 구축하기 위한 간략한 기술 설계서 예시의 개요이다. 이 설계서는 REST API 기반의 마이크로서비스 환경에서 JWT를 활용한 인증 방식을 채택한 배경과 상세 구현 방안을 설명한다.

ADR 작성 예시

아래는 위 기술 설계 과정에서 내려진 하나의 구체적인 아키텍처 결정을 기록한 ADR 예시이다. 이 기록은 특정 결정의 문맥과 결과에 초점을 맞춘다.

기술 설계서의 작성 구조는 프로젝트의 규모와 복잡도에 따라 달라지지만, 일반적으로 다음의 핵심 구성 요소를 포함합니다.

작성 시에는 독자의 이해를 돕기 위해 다이어그램, 시퀀스 다이어그램, 상태 다이어그램 등을 적극 활용하는 것이 효과적입니다. 모든 구성 요소는 명확하고 검증 가능하도록 작성해야 하며, 특히 상세 설계 섹션에서는 구현 담당자가 코드를 작성하는 데 충분한 수준의 정보를 제공해야 합니다.

기술 설계서 작성 시에는 몇 가지 핵심 고려사항을 명심해야 한다. 첫째, 문서의 독자를 명확히 정의하는 것이다. 설계서는 프로젝트 매니저, 개발자, QA 엔지니어, 향후 유지보수 담당자 등 다양한 이해관계자를 대상으로 할 수 있다. 독자에 따라 필요한 기술적 세부 수준과 설명 방식이 달라지므로, 초반에 목표 독자층을 설정하고 그에 맞춰 작성하는 것이 중요하다.

둘째, 명확성과 간결성을 유지하는 것이다. 불필요한 기술적 행어나 지나치게 추상적인 설명은 피해야 한다. 복잡한 아키텍처나 로직은 다이어그램, 순서도, 표 등을 활용하여 시각적으로 표현하는 것이 효과적이다. 모든 핵심 용어는 일관되게 사용하고, 필요한 경우 용어집을 제공하여 오해의 소지를 줄여야 한다.

셋째, 변경 가능성을 고려하는 것이다. 소프트웨어 설계는 요구사항 변화에 따라 진화한다. 따라서 설계서는 너무 구체적이고 경직되어 유연성을 잃어서는 안 된다. 대안으로 고려했던 옵션과 그 이유, 주요 결정의 근거를 함께 기록하면 향후 변경 시 참고 자료가 될 수 있다. 마지막으로, 문서 자체의 유지보수성을 고려해야 한다. 설계가 변경될 때 문서도 함께 업데이트할 수 있는 실용적인 구조와 프로세스를 마련하는 것이 장기적인 문서의 생명력을 보장한다.

기술 설계서 작성 예시

다음은 사용자 인증 시스템을 개선하기 위한 마이크로서비스 아키텍처의 API 게이트웨이 도입에 관한 기술 설계서의 간략한 예시이다. 이 설계서는 새로운 아키텍처 구성 요소의 도입을 제안하고 그 근거를 설명한다.

제목: 사용자 인증을 위한 중앙화된 API 게이트웨이 도입 설계서

1. 문제 정의: 현재 애플리케이션은 각 마이크로서비스가 독립적으로 사용자 인증과 권한 부여를 처리한다. 이로 인해 인증 로직의 중복, 보안 정책의 불일치, 그리고 새로운 서비스 개발 시마다 인증 모듈을 재구현해야 하는 비효율이 발생한다.

2. 제안된 해결책: API 게이트웨이 패턴을 적용하여 인증(Authentication)과 권한 부여(Authorization)를 중앙에서 처리하는 레이어를 구축한다. 모든 외부 요청은 먼저 게이트웨이를 통과하여 JWT 토큰을 검증받은 후, 적절한 서비스로 라우팅된다.

3. 기술 스택: 게이트웨이 구현체로는 NGINX와 Lua 스크립트를 사용한 커스텀 모듈 또는 Kong API Gateway를 검토한다. 인증 프로토콜은 OAuth 2.0과 JWT를 채택한다.

4. 예상 이점: 보안 정책의 일관성 유지, 서비스 개발 생산성 향상, 인증 관련 모니터링과 로깅의 중앙화가 주요 기대 효과이다.

5. 잠재적 위험 및 완화 방안: 게이트웨이가 단일 장애점(SPOF)이 될 수 있으므로, 활성-대기 또는 활성-활성 클러스터링 구성을 통해 가용성을 보장한다.

ADR 작성 예시

다음은 위 기술 설계서의 결정 사항 중 하나를 기록한 ADR의 예시이다. ADR은 특정한 아키텍처 결정과 그 맥락, 결과를 간결하게 기록한다.

제목: ADR 001 - API 게이트웨이 구현체로 오픈소스 Kong 채택

상태: 제안됨 (또는 수락됨)

배경: 사용자 인증 중앙화를 위한 API 게이트웨이 도입이 결정되었다. 구현체 후보로는 NGINX 기반 커스텀 개발, Spring Cloud Gateway, Kong API Gateway가 검토되었다.

결정: 오픈소스 API 게이트웨이인 Kong을 구현체로 채택한다.

근거:

* 플러그인 생태계: 인증(Authentication), 로깅, 속도 제한 등 필요한 기능을 공식 플러그인으로 제공하여 개발 기간을 단축한다.

* 확장성: NGINX 기반의 높은 성능과 Lua를 이용한 커스텀 플러그인 개발이 가능하다.

* 운영 도구: 대시보드(Kong Manager)와 선언적 설정 관리 기능이 제공되어 운영 편의성이 높다.

* 커뮤니티: 활발한 오픈소스 커뮤니티와 기업 지원(Kong Inc.)을 모두 활용할 수 있다.

결과:

* 긍정적 결과: 빠른 프로토타이핑과 표준화된 플러그인을 통한 안정적인 운영이 기대된다.

* 부정적 결과: Kong의 특정 학습 곡선이 발생하며, Docker 또는 Kubernetes 환경에 대한 의존성이 생긴다. 또한, 고급 기능 사용 시 엔터프라이즈 라이선스 고려가 필요할 수 있다[4].

대안으로 고려된 옵션:

1. NGINX + Lua 커스텀 개발: 최대한의 유연성과 경량화를 제공하지만, 모든 기능을 직접 개발하고 유지보수해야 하는 부담이 있다.

2. Spring Cloud Gateway: 자바 및 스프링 부트 생태계와의 긴밀한 통합이 장점이지만, 본 프로젝트의 다언어(Polyglot) 마이크로서비스 환경에는 부적합하다고 판단되었다.

기술 설계서는 특정 기능, 모듈, 또는 시스템 컴포넌트의 구체적인 구현 방안을 상세히 기술하는 문서이다. 이는 인터페이스 정의, 데이터베이스 스키마, 알고리즘 흐름, API 명세, 클래스 다이어그램, 그리고 상세한 의사코드나 실제 코드 스니펫까지 포함할 수 있다. 주로 개발자가 코드를 작성하기 직전 또는 작성 중에 참조하는 실행 지침서 역할을 하며, 그 범위는 하나의 서비스, 특정 마이크로서비스, 또는 하나의 주요 기능에 국한되는 경우가 많다.

반면, ADR은 프로젝트 전반에 걸친 높은 수준의 아키텍처적 결정과 그 배경을 기록한다. ADR의 범위는 특정 기술 선택(예: 메시지 큐로 RabbitMQ 대신 Apache Kafka를 선택한 이유), 시스템 간의 상호작용 패턴, 주요 비기능 요구사항을 달성하기 위한 전략(예: 확장성, 보안) 등에 초점을 맞춘다. 세부적인 구현 방법보다는 '무엇을'과 '왜' 선택했는지에 대한 논리와 맥락을 문서화하는 것이 핵심이다.

이를 표로 비교하면 다음과 같다.

따라서, 기술 설계서는 구체적인 실행 계획도를 제공하는 반면, ADR은 프로젝트의 중요한 갈림길에서 내린 결정지도를 제공한다고 볼 수 있다. 이 둘은 상호 보완적이며, ADR에서 내려진 광범위한 결정이 개별 기술 설계서의 방향성을 제약하거나 안내하는 경우가 많다.

기술 설계서는 일반적으로 특정 기능, 모듈, 또는 시스템 컴포넌트를 구체적으로 구현하기 전에 작성됩니다. 주로 개발 단계의 초기, 즉 상세 설계 단계에서 작성되며, 구현을 위한 구체적인 로직, 데이터 흐름, 인터페이스 정의, 클래스 다이어그램, 시퀀스 다이어그램 등을 포함합니다. 그 목적은 개발자들이 일관된 이해를 바탕으로 코드를 작성할 수 있도록 명확한 청사진을 제공하고, 구현 과정에서의 오류와 불일치를 최소화하는 데 있습니다.

반면, ADR은 아키텍처나 기술 스택에 대한 중요한 결정이 내려진 직후에 작성됩니다. 결정의 논의 과정 중이나 결정 직후에 기록하는 것이 이상적입니다. ADR의 주요 목적은 특정 결정의 배경, 고려된 대안, 그리고 그 결정으로 인한 결과를 문서화하여 팀의 집단 지식을 보존하는 것입니다. 이는 시간이 지나도 "왜 그런 선택을 했는가"에 대한 맥락을 잃지 않도록 하며, 미래에 비슷한 문제를 다시 검토할 때 참고 자료로 활용됩니다.

요약하면, 기술 설계서는 "어떻게(How) 구현할 것인가"에 초점을 맞춘 실행 지침서라면, ADR은 "왜(Why) 그런 아키텍처나 기술을 선택했는가"에 대한 결정의 역사와 논리를 기록한 문서입니다. 기술 설계서의 작성은 구현을 시작하기 위한 전제 조건인 반면, ADR 작성은 중요한 결정이 있을 때마다 지속적으로 이루어지는 과정입니다.

버전 관리 시스템을 활용하여 기술 설계서와 ADR 문서의 변경 이력을 체계적으로 추적하는 것이 중요하다. 일반적으로 Git과 같은 도구를 사용하며, 문서 파일을 코드와 동일한 저장소에서 관리하거나 별도의 문서 전용 저장소를 구성할 수 있다. 각 문서는 고유한 식별자(예: 문서 제목, 날짜, 버전 번호)를 부여하고, 모든 수정 사항은 커밋 메시지에 명확한 변경 이유를 포함하여 기록해야 한다. 이를 통해 특정 시점의 문서 상태를 쉽게 확인하고, 변경의 의도와 맥락을 이해할 수 있다.

문서화는 단순한 파일 보관을 넘어, 검색 가능하고 접근성이 높은 형태로 유지되어야 한다. 마크다운과 같은 가벼운 마크업 언어로 작성된 문서를 정적 사이트 생성기를 통해 HTML로 변환하여 내부 위키나 문서 포털에 게시하는 방법이 효과적이다. 이때 문서 간의 하이퍼링크를 적극 활용하여 관련된 설계서와 ADR, 실제 코드 또는 API 문서와의 연결성을 높이는 것이 좋다. 모든 문서는 최신 상태로 유지되어야 하며, 더 이상 유효하지 않은 문서는 명시적으로 폐기 상태로 표시하거나 아카이브 처리해야 한다.

버전 관리와 문서화 전략을 효과적으로 운영하기 위해서는 명확한 워크플로우가 필요하다. 예를 들어, 문서 생성 또는 주요 변경 시 풀 리퀘스트를 통해 팀원들의 검토를 받도록 프로세스를 정립할 수 있다. 아래 표는 문서 유형별 권장 관리 방안을 요약한 것이다.

팀 내에서 기술 설계서와 ADR을 효과적으로 활용하기 위해서는 체계적인 공유 및 검토 프로세스가 필수적이다. 일반적으로 이러한 문서는 단순히 작성하여 저장소에 보관하는 것을 넘어, 적극적인 논의와 합의를 거치는 과정을 통해 그 가치가 극대화된다.

일반적인 프로세스는 문서 초안 작성 → 팀 내 공유 및 논의 → 피드백 반영 및 승인 → 공식 기록 및 배포의 단계로 구성된다. 초안은 주로 담당 엔지니어나 아키텍트가 작성하며, 콘플루언스나 Git 저장소의 풀 리퀘스트와 같은 협업 도구를 통해 팀원들에게 공유된다. 이후 정기적인 기술 리뷰 회의나 비동기적 논의를 통해 설계의 타당성, 대안 고려사항, 잠재적 위험 요소 등에 대한 피드백을 수집한다. 특히 ADR의 경우, 제안된 아키텍처 결정에 대한 명시적인 동의 또는 거부 의사표시가 기록되는 것이 중요하다.

검토가 완료되고 최종 승인된 문서는 버전 관리 시스템에 통합되고, 팀의 지식 베이스에 등록된다. 이후 관련 프로젝트의 위키나 문서 포털에 링크되어 모든 이해관계자가 쉽게 접근할 수 있도록 한다. 이 과정에서 문서의 상태(예: 제안됨, 승인됨, 폐기됨)를 명시적으로 표시하는 것이 유용하다.

이러한 프로세스를 정립함으로써 지식의 실버화를 방지하고, 신규 팀원의 온보딩을 용이하게 하며, 향후 유사한 결정을 내릴 때 참고할 수 있는 귀중한 조직적 자산을 축적하게 된다.