시스템 아키텍처 다이어그램 작성 시 더 흔한 실수들

More common mistakes to avoid when creating system architecture diagrams

📅 2026-03-22 📰 Hacker News (Top) ⬆ 128

요약

시스템 아키텍처 다이어그램의 일반적인 7가지 오류를 설명한다. 리소스 이름 부재, 연결되지 않은 리소스, '마스터' 다이어그램 시도, 컨베이어 벨트 신드롬 등으로, 다중 관점으로 분해하고 정확한 상호작용을 표현할 것을 권장한다.

핵심 포인트

리소스는 타입만 아닌 실제 이름으로도 표시하여 각 리소스를 명확히 구별해야 한다.
모든 리소스는 다른 리소스와 연결되어야 하며, 한 다이어그램에 너무 많은 정보를 담지 말아야 한다.
행동 다이어그램에서 단순화로 인해 시스템의 실제 왕복 상호작용을 생략하면 심각한 오해를 초래한다.

왜 중요한가

명확하고 정확한 아키텍처 다이어그램은 팀 소통과 시스템 이해도를 크게 향상시키는 필수 도구입니다.

📄 전문 번역

아키텍처 다이어그램의 흔한 실수 7가지 (후편)

Billy Pilger · 2026년 3월 12일 · 읽기 시간 6분

시스템 아키텍처 다이어그램은 복잡한 시스템을 문서화하는 데 필수적인 도구입니다. 하지만 다이어그램의 작은 실수 하나가 관계자들에게 혼란과 좌절감을 줄 수 있죠. 피해야 할 일곱 가지 흔한 실수를 살펴보겠습니다.

(이전 글 "아키텍처 다이어그램의 흔한 실수 7가지"의 후속편입니다)

실수 #1: 리소스 이름 표기 누락

시스템 다이어그램에서 라벨이 없거나 부족한 리소스는 정말 흔한 문제입니다. AWS 다이어그램의 아이콘 아래 라벨을 보면:

> 이 다이어그램의 리소스들은 이름이 아닌 타입으로만 표기되어 있습니다. (출처: amazon.com)

각 리소스가 타입으로만 라벨 되어 있고 이름은 없네요. 타입 정보도 분명 중요하지만, 둘 중 하나만으로는 부족합니다:

타입은 리소스가 어떤 종류의 것인지 설명합니다. 데이터베이스 테이블이나 VM 인스턴스 같은 구체적인 것도 있고, 서비스처럼 추상적인 것도 있죠.
이름은 같은 타입의 다른 리소스들과 구별해줍니다. 잘 지어진 이름은 그 리소스의 역할이나 목적을 나타내기도 합니다.

공간이 충분하다면 이름과 타입 둘 다 표기하는 게 좋습니다. 가장 간단한 방법은 리소스 이름에 타입 접미사를 붙이는 거예요. 예를 들어 'Orders Table', 'Results Bucket' 같은 식이죠. 다이어그램에 아이콘이 있으면 타입은 자동으로 시각화되므로, 아이콘이 있을 때는 이름 라벨이 더욱 중요합니다.

실수 #2: 연결되지 않은 리소스

이건 단순하면서도 자주 보는 실수입니다. 다이어그램의 모든 리소스는 다른 리소스와 어떤 식으로든 연결되어 있어야 합니다.

> 오른쪽의 Amazon Route 53이 다른 모든 리소스와 연결되지 않았습니다. (출처: amazon.com)

위 다이어그램을 보면 Amazon Route 53이 고립되어 있어요. 이 리소스가 시스템에서 어떤 역할을 하는지 전혀 알 수 없습니다. 다이어그램의 목적 자체가 리소스 간의 관계를 보여주는 것인데, 이런 식으로 관계를 빠뜨리면 다이어그램의 존재 의미가 사라지죠.

이런 문제는 보통 다이어그램 작성자가 어떤 리소스가 시스템에 포함되어 있다는 건 알지만, 이를 깔끔하게 표현할 방법을 찾지 못할 때 생깁니다. 특히 한 개의 다이어그램에 너무 많은 정보를 담으려 할 때 발생합니다. (다음 실수 참조)

실수 #3: "마스터" 다이어그램 만들기

"마스터" 다이어그램은 시스템 전체를 한 번에 보여주려고 합니다. 모든 걸 한눈에 보고 싶다는 욕심에서 비롯된 건데, 거의 항상 실수가 됩니다.

> Ilograph의 서버리스 백엔드 아키텍처 (클릭하면 확대됩니다)

이 다이어그램은 Ilograph 백엔드 시스템의 마스터 다이어그램입니다. 런타임 의존성, DNS 설정, CDN 설정, 소스 코드, 배포 시 의존성 등이 모두 한 장에 담겨 있어요. 보시다시피 이렇게 많은 정보를 한 다이어그램에 집어넣으면 보는 사람이 압도당합니다.

해결책은 이런 다이어그램을 여러 개의 관점(perspective)으로 나누는 것입니다:

> 마스터 다이어그램은 여러 관점으로 분리할 수 있습니다.

대부분의 시스템은 이렇게 다이어그램을 나눌 만큼 충분히 복잡합니다. 각 관점은 자신만의 이야기를 일관성 있게 전달하면서도 다른 관점들과 간섭하지 않죠.

모델 기반 다이어그래밍 도구를 사용하면 여러 관점이 리소스를 명시적으로 공유하면서 연결 관계를 유지할 수 있습니다. 자세한 내용은 "Breaking Up the Master Diagram"을 참고하세요.

실수 #4: 컨베이어 벨트 증후군

지금까지 본 예제 다이어그램들은 모두 관계형 다이어그램(relational diagram)이었습니다. 리소스 간 관계를 보여주는 거죠. 하지만 또 다른 종류의 시스템 다이어그램이 있습니다. 바로 행동형 다이어그램(behavioral diagram)인데, 관계가 아닌 리소스 간의 구체적인 상호작용을 보여줍니다.

행동형 다이어그램은 구체적인 상호작용을 다루기 때문에 관계형 다이어그램보다 자세합니다. 그런데 다이어그램 작성자가 공간이나 시간 때문에 단순화하다가 왕복 통신이나 오케스트레이션 같은 현실적인 부분을 생략해버리는 경우가 있습니다. 이를 '컨베이어 벨트 증후군'이라고 부르는데, 그 결과는 시스템의 본질을 심각하게 왜곡한 다이어그램이 됩니다.

> 이 다이어그램은 시스템을 컨베이어 벨트처럼 표현합니다. (출처: amazon.com)

위 다이어그램(이 솔루션에서 출처)은 시스템을 조립 라인처럼 그렸습니다. 마치 각 리소스가 이전 리소스에서 입력을 받아 이를 가공한 후 다음 리소스로 전달하는 것처럼 보이네요.

물론 실제로 그런 시스템도 있습니다. 하지만 대부분의 경우 훨씬 복잡합니다. 이들 리소스 간에 (그리고 표시되지 않은 다른 리소스들과도) 훨씬 많은 왕복이 일어나거든요. 경험 많은 개발자는 이 다이어그램이 모든 걸 보여주지 않는다는 걸 직관적으로 이해할 테지만, 초보자는 크게 오해할 수밖에 없습니다.

해결책은 완전히 다른 종류의 다이어그램을 사용하는 것입니다. 바로 시퀀스 다이어그램(sequence diagram)인데요. 시퀀스 다이어그램은...

🔗 원문 보기 👍 유용해요