입사한지 8개월이 지났습니다.

 

현재 속한 팀에 배정받은건 11월이니 3개월정도 지났네요. 아직 우리팀의 업무 흐름을 완벽하게 파악 못한 상태입니다..

 

이유를 들어보면

 

1. 팀에서 관리하는 컴포넌트가 많습니다.

각각이 별개의 컴포넌트가 아니고, 전체가 하나의 큰 시스템을 이루고 있습니다..(그렇다고 MSA는 또 아님...근데 몇 십개..)

팀 내에 꽤 오래 다니신 분도 아직도 파악 못한 컴포넌트가 있을 정도라고 하십니다.

 

2. 자체 인프라, 자체 플랫폼

네이버와 동일한 인프라시스템, 플랫폼을 공유합니다. 오픈소스도 직접적인 경로로 하는게 아닌 좀 말아서 제공하기때문에, 좀 더 찾아봐야 합니다.. 배포도 AWS를 사용하는게 아니라 IDC에서 배포하기 때문에 초기 러닝커브가 좀 있습니다..

 

물론, 위의 것들은 누군가가 일일히 가르쳐줘야 한다고 절대! 생각하지 않습니다. 제가 당연히 알아가야 하는것이라고 생각하고, 계속 노력중입니다.

팀에서 그래도 생태계를 파악할 수 있도록 다양한 이슈를 할당해 주시기 때문에 현재까지 처리해온 이슈들과 관련된 내용은 다 정리가 되어있습니다.

 

그치만 언제까지 알아가기만 할 수는 없겠죠...아무리 신입버프가 있다고 해도 팀에서는 쓸모있고 잘하는 사람이 필요할 것입니다.

이번주에 설계 문서와 각종 다이어그램에 대해 생각해보며 문서화의 중요성을 한 번 더 깨우쳤습니다.

 

현재도 이슈를 할당받고 이슈분석을 하는 과정에서, 이걸 수정하려면 어디를 봐야 하는지, 어떤 컴포넌트와 연관되어있고 어떤 영향이 가는지, 배포시 어떤 컴포넌트랑 어떻게 배포해야하는지,...등등을 파악하는게 가장 큰 병목입니다...이런 고민들에 비해 구현은 진짜 별거없는 경우도 많구요...(2줄 수정하면 되는거 파악하려고 하루 쓴 사람...)

 

그래서 제가 앞으로 하려는 것은.. 시퀀스 다이어그램, 컴포넌트 다이어그램, 스테이트 머신 다이어그램, 디플로이먼트 다이어그램, C4다이어그램을 그려보려고 합니다. 문서화를 잘 해놓고, 모두 살아있는 문서로 관리하여 다음에 들어오실 개발자분의 온보딩 과정에 도움이 되었으면 합니다.

 

살아있는 문서로 관리한다는 것.

"살아있는 문서"라고 했는데, 완벽한 문서를 만드는 게 아니라, 업데이트 가능한 문서를 만드는 것입니다. 이슈를 처리하면서 기존 다이어그램과 달라진 부분이 있으면 함께 수정하는 것. 그래서 별도의 문서 도구보다는 코드와 함께 버전 관리가 가능한 형태(Mermaid 등...)를 우선 고려하고 있습니다. 그림 파일로 관리하면 수정이 귀찮아서 결국 안 하게 되니까요.

 

80%짜리 문서가 0%짜리 문서보다 낫습니다. 그리고 80%짜리 문서를 꾸준히 업데이트하면 언젠가 95%가 됩니다. 100%는 애초에 불가능하다고 생각합니다.

 

 

그래서 뭘, 어떻게 할건데?

 

"다이어그램 그리는건,, 기본은 글쓰기가 중요하고, 그 글을 이해하기 좋은 도표를 고르는 형태가 되어야함." 

 

위 말을 듣고  다이어그램을 그리기 전에, 먼저 글로 정리해보는 과정을 거치려 합니다. "A 컴포넌트가 B에게 요청을 보내고, B는 C를 조회한 뒤 결과를 돌려준다" 이 한 문장을 쓸 수 있어야 시퀀스 다이어그램도 그릴 수 있다고 생각합니다. 글로 설명이 안 되는 건 다이어그램으로 그려도 안 됩니다. 그리고 글로 먼저 정리하면 "이걸 어떤 다이어그램으로 표현하는 게 적합한가?"도 자연스럽게 보일것이라고 생각합니다.

 

시퀀스 다이어그램

"이 요청이 어디를 거쳐서 어디까지 가는거지??" 를 잘 표현하면 좋을것 같습니다. 구체적인 표현은 최대한 줄이고, 흐름 파악만 되면 시퀀스 다이어그램의 역할은 끝이라고 생각합니다.

주의할 점으로, 모든 분기와 예외를 다 그리지 않으려 합니다. 메인 플로우 하나, 대표적인 예외 플로우 하나. 이 정도면 충분하다고 생각합니다. 전부 다 담으려고 하면 다이어그램이 코드만큼 복잡해지고, 그러면 그냥 코드를 보는 게 낫습니다.

그래서 시퀀스 다이어그램만 보고도 이슈 분석시 어떤부분을 들여다 보면 되겠구나를 알아채기 쉽게 하는 것을 목표로 할 것입니다.

 

컴포넌트 다이어그램

"이걸 고치면 어디에 영향이 가지???" 가 잘 나타나면 좋을것 같습니다.

여기서 중요한 건 "방향"이라고 생각합니다. A → B 의존이 있다는 것만으로는 부족하고, "A가 B의 무엇을 왜 의존하는가"가 한 줄이라도 적혀있으면 나중에 영향도 분석할 때 훨씬 빨라지는 것을 목표로 합니다.

 

스테이트 머신 다이어그램

"이 상태에서 저 상태로 언제 넘어가는거지??"

복잡한 비즈니스더라도 상태 전이는 "정상 흐름"만 그리면 쉬운데, 진짜 삽질하게 되는 건 "이 상태에서 이 상태로는 갈 수 없다"는 제약조건입니다. 불가능한 전이도 문서에 명시하려 합니다.

 

디플로이먼트 다이어그램

"배포할때 무엇을 신경써야하지??"

CI/CD를 구축하지않고, CI까지만 구축한 후에 배포는 수동으로 하고있습니다. 그리고 컴포넌트별 배포 순서도 중요한 환경입니다.

수동 배포 환경이다보니, 배포 순서를 틀리면 장애로 이어질 수 있습니다. 단순히 구조만 그리는 것이 아니라 "A를 먼저 배포하고, B를 배포해야 한다. 순서가 바뀌면 X 문제가 발생한다" 수준의 주의사항도 함께 적으려 합니다.

 

C4 다이어그램

"전체 시스템이 어떻게 생겼지??"

C4는 레벨 구분이 핵심이라고 생각합니다. Level 1(System Context)에 클래스 이름이 들어가거나, Level 3(Component)에 인프라 정보가 섞이면 오히려 혼란스러워집니다. 각 레벨에서 "이 레벨의 독자는 누구인가?"를 먼저 정하고 그리려 합니다.

 

마무리

 

이 작업의 가장 큰 수혜자는 아마 미래의 저일 것입니다. 6개월 뒤의 제가 "이게 뭐였지?" 할 때, 지금의 제가 남겨둔 문서가 답을 줄 수 있으면 좋겠습니다. 그리고 그 다음 수혜자는, 다음에 이 팀에 합류하실 분이겠죠. 3개월 전의 제가 이런 게 있었으면 좋았을 것들을 만드는 겁니다.

시간이 얼마나 걸릴지는 솔직히 모르겠습니다. 하지만 이슈 하나 처리할 때마다 관련된 부분을 조금씩 문서화하면, 이슈를 처리하는 것 자체가 문서화 작업이 됩니다. 별도의 시간을 크게 내지 않아도 쌓이는 구조를 만들어보려 합니다. AI도 있기도 하고요...

 

 

 

참고할 링크

더보기

1. 시퀀스 다이어그램

2. 컴포넌트 다이어그램

3. 스테이트 머신 다이어그램

4. 디플로이먼트 다이어그램

5. C4 다이어그램

  • 공식 사이트 (Simon Brown): https://c4model.com/ — C4의 원저자가 직접 관리하는 공식 페이지. Level 1~4 정의, 예제, FAQ 전부 여기에 있음
  • C4 FAQ: https://c4model.com/faq — "C4는 프로세스가 아니라 표현 방법이다", arc42와의 호환 등 자주 하는 오해 정리

 

'TW' 카테고리의 다른 글

변경하기 좋고 확장성 좋은 코드는 누구를 위한것인가?  (3) 2026.02.06

+ Recent posts

티스토리툴바