Video: 아키텍처 그림, 문서 쉽게 만들기 | C4 · ADR · arc42
Channel: 코딩하는기술사
Duration: 6m 52s
Source: subtitle (auto, ko)
Transcript:
개발자 여러분들 아키텍처 문서와 잘 하고 계신가요? 자, 오늘은이 아키텍처를 문서로 표현하는 방법에 대해서 알려 드리겠습니다. 자, 당신이 만든 시스템 아키텍처 문서가 있나요? 아키텍처 문서의 현실입니다. 문서 자체가 없는 경우입니다. 개발자들 머릿속에는 있는데 문서는 없는 경우가 많습니다. 그리고 문서가 있어도 읽지 않는 문서가 많습니다. 왜냐하면 내용이 너무 단순하거나 아니면 너무 장황하거나. 또 그리고 현재 시스템하고 전혀 맞지 않는 오래된 문서. 우리 아키텍처 문서의 현실입니다. 자, AI 시대에는 아키텍처를 기록하는 것이 더 중요해졌습니다. 왜냐하면 AI로 구현 속도가 빨라질수록 시스템의 핵심 구조와 그리고 아키텍터적 결정에 근거를 아는 사람이 점점 줄어들기 때문입니다. 우리이 코드는 무엇을 만들었는지를 설명해 주지만 이게 왜 이렇게 만들어졌는지는 설명해 주지 않습니다. 나중에이 시스템을 파악하거나 유지보수하거나 확장해야 될 때 그 근거를 찾아볼 수 없는 것이죠. 자, 그런데 문서화가 어려운 이유가 무엇일까요?

첫 번째 무엇을 어떻게 어디에 작성해야 할지 막막합니다. 그리고 또 아키텍처 다이어그램은 또 어떻게 그려야 할지 그리고 어느 수준까지 자세히 그리거나 작성해야 될지 그리고 문서를 한번 만들었으면 어떻게 관리해야 할지 막막하고 정해진 정답이 없습니다. 그래서 문수화가 어렵습니다. 자 그런데 전문가는 항상 기준을 사용해야 된다고 제가 늘 강조드리고 있죠. 아키텍처를 문서할 때도 전문가는 본인의 네피셜로 작성하는 것이 아니라 공신력 있는 기준을 사용합니다. 그 기준을 오늘 세 개 알려 드리겠습니다. 첫 번째 아키텍처 그림을 어떻게 그려야 할지 참조할 수 있는 C4 모델입니다. 두 번째 아키텍처의 설계 결정의 근거를 효과적으로 남길 수 있는 ADR입니다. 세 번째 아키텍처 문서의 목차와 구조를 어떻게 잡아야 할지 막막할 때 참조할 수 있는 아크2입니다. 자, 먼저 아키텍처 그림을 그리는 방법입니다. 시포 모델을 잠주해서 우리 아키텍처를 표현할 수 있습니다. 모델에서는 아키텍처를 추상화 수준으로 이렇게 레벨을 나눠서 제일 추상화가 높은 수준에서 추상화가 낮은 즉 구체적인 다이어그램으로 이렇게 상세화시켜 나가라고 말하고 있습니다.

첫 번째 레벨은 컨텍스트 다이아그램, 두 번째는 컨테이너 다이아이그램, 세 번째는 컴퍼넌트 다이아그램,네 번째는 코드 다이아이그램입니다. 자, 10 모델의 공식 사이트에 보시면 마치이 지도처럼 추상화 수준이 높은 데부터 지도를 확장하면서 점점 상세한 지도가 나오는 것처럼 아키텍처 다이어그램을 추상한 수준을 나눠서 점점 상세하게 그릴 수 있도록 가이드하고 있습니다. 자, 시스템 컨텍스트 다이어그램 그리고 컨테이너 다이어그램 그리고 컴퍼넌트 다이아그램 그리고 코드 다이그램 작성 방법과 가이드를 이렇게 안내하고 있습니다. 자, 그런데 실전에서는이네 개의 다이그램을 모두 다 그걸 그려라고는 하지 않습니다. 대부분의 시스템에서는 컨텍스트 다이아이그램과 컨테이너 다이아그램 정도로 충분하다고 하고요. 컴포넌트 다이아그램하고 코드 다이아그램은 필요할 때만 작성하고 또 특히 이런 하위 레벨의 다이아그램은 손으로 직접 그리지 말고 어 아이디 같은이 자동화 툴를 통해서 자동으로 그리라고 합니다. 그렇게 해야지 코드의 변화를 따라갈 수 있기 때문입니다.

자 다음으로이 아키텍처 설계 결정을 효과적으로 남기는 ADR 아키텍처 디시즌 레코드입니다. 자, 설계 결정을 이렇게 상태, 맥락, 결정, 결과 이런 식으로 문서를 남기도록 템플릿을 제공하고요. 예시를 보시면 왜 카프카를 결정했는지에 대한 결정 사항을 ADR 포맷으로 남길 수 있습니다. 자, 그리고이 아키텍처 문서의 목차와 구성 적 템플릿을 제공하는 아크 42입니다. 자, 아크 42에서는 총 12개의 아키텍처 목차를 제공합니다.이 이 목차에 맞춰서 어 시스템의 아키텍처 내용을 기술하도록 템플릿을 제공하는 거죠. 자, 공식 사이트에서 이렇게 설명을 하고 있고요. 자, 보시는 바와 같이 12개의 섹션에 대한 상세한 설명과 그리고 예시를 보여주고 있습니다. 자, 그런데이 12개를 다 작성해야 될까요? 그렇지 않습니다.이 아크2 FAQ에서도 이렇게 말하고 있습니다. 전체를 다 작성할 필요는 없고 해당 시스템의 특성과 어 이해 관계자의 어떤 상황을 보고 만들면 된다고 하고 있고요. 그렇지만 이렇게 다섯 개 정도는 최소 권장으로 하면 좋다 이렇게 권장하고 있습니다.

자이 세 개의 점조 모델의 관계입니다. 먼저 아크폴티 2는 아키텍처 문서의 목차와 템플릿 즉 무엇을 어디에 무슨 내용으로 남길지를 알려 주고요. 그리고 C 모델은 아키텍처 다이그램을 어떤 식으로 그려야 할지 가이드를 주고요. 그리고 ADR은 설계 결정을 어떤 식으로 남기면 효과적인지에 대한 구조를 안내하고 있습니다. 그래서이 세 개는 각각 대체하거나 경쟁하는 관계가 아니라 함께 조합해서 만들 수 있는 보완 관계에 있다고 할 수 있습니다. 자, 그런데이 세 개를 참조할 때 조심해야 될 사항입니다. 아크폴티 2에 12개 섹션을 다 채워야지라고 하는 것. 그리고 14 모델의 모든 레벨에 다이아그램을 다 그려야지. 그리고 ADR에 ADR 써서 어 성능 절차 제대로 밟아야지. 자, 이렇게 하는 것은이 세 개의 참조 모델을 잘못 이용하고 있는 것입니다. 문서와 방법론을 도입했는데 문서 작성 업무만 더 늘었다면 잘못 도입하는 뜻입니다. 자, 그래서 이렇게 시작하십시오. 첫 번째 C 모델로 일단 컨텍스트 다이그램을 한번 그려 보십시오.

그리고 오늘부터이 설계 결정을 ADR로 가볍게 한번 남겨 보십시오. 그리고 나서 아키텍처 문서를 정식으로 다 만들고자 할 때는 아크폴티 2의 12개 섹션에서 우리한테 필요한 섹션을이 공식 사이트의 아이디에 따라서 한번 작성해 보십시오. 자, 한꺼번에 도입할 필요는 전혀 없습니다. 우리 시스템에 맞는 우리 시스템을 잘 설명하는 최소한의 문서화가 필요한 거죠. 자, 그림은 14, 근거는 ADR, 구조는 아크폴티 2로 아키텍처를 문서화하십시오. 문서화를 잘한다는 건 문서를 복잡하고 화려하게 만드는 것이 아니라 필요한 정보만 유지 가능한 수준으로 남기는 것입니다. 자, 여기까지 보셨다면 아키텍트에 관심이 많으신 분이실 겁니다. 제 채널에 아키텍트 인사이트 멤버십이 있습니다. 여기에 오시면 아키텍처의 정통 이동과 그리고 들기에 관한 사항 그리고 오늘 말씀드린이 세 개 문소화를 어떤 식으로 할지 자세히 설명을 하고 있습니다. 자, 관심 있으신 분들은 멤버십에 참여하셔서 아키텍트로 같이 성장하시죠. 자, 수했습니다.