ARCHITECTURE.md (2021): 프로젝트 구조 기술명세서

 (matklad.github.io)
1P by GN⁺ | ★ favorite | 댓글 1개
  • 10k~200k 줄 규모의 오픈소스 프로젝트는 README, CONTRIBUTING 옆에 ARCHITECTURE 문서를 두면 신규 기여자가 코드 구조를 파악하는 비용을 줄일 수 있음
  • 낯선 프로젝트에서는 패치 작성이 대략 2배 느려지는 것보다, 어디를 고쳐야 하는지 찾는 데 10배 더 걸리는 문제가 더 큼
  • 이 문서는 고수준 구조와 자주 바뀌지 않는 내용을 짧게 담고, 코드와 계속 동기화하기보다 1년에 몇 차례 점검하는 방식이 적합함
  • 핵심 구성은 문제의 조감도와 코드맵(codemap) 이며, 큰 모듈과 관계를 보여줘 “X를 담당하는 코드가 어디인가”에 답해야 함
  • 중요한 이름, 아키텍처 불변조건, 계층·시스템 경계, 횡단 관심사를 남기되 직접 링크보다 이름 검색을 유도하면 유지보수 부담이 줄어듦

ARCHITECTURE 문서가 줄이는 비용

  • 오픈소스 프로젝트에서 가끔 기여하는 사람과 코어 개발자의 가장 큰 차이는 프로젝트의 물리적 아키텍처를 아는지 여부임
  • 낯선 코드베이스에서는 파일을 임의 순서로 놓인 논리 조각처럼 순차적으로 읽게 됨
  • 이미 의미 있는 기여를 한 개발자는 머릿속에 코드 지도가 있어 필요한 위치로 바로 이동하고, 없으면 해당 코드를 옮길 수도 있음
  • ARCHITECTURE 파일은 이 간극을 낮은 비용으로 줄이는 수단임
  • 문서는 짧아야 함
    • 반복적으로 기여하는 사람이 모두 읽어야 하기 때문임
    • 짧을수록 미래 변경으로 무효화될 가능성이 낮음
  • ARCHITECTURE에는 자주 바뀌지 않을 내용을 담는 것이 기준임
    • 코드와 계속 동기화하려 하지 않음
    • 대신 1년에 몇 차례 다시 검토함

무엇을 담아야 하는가

  • 먼저 프로젝트가 해결하는 문제를 조감도 수준에서 정리함
  • 이어서 어느 정도 상세한 코드맵(codemap) 을 작성함
    • 큰 단위의 모듈과 서로의 관계를 설명함
    • “X를 하는 것은 어디에 있는가”에 답해야 함
    • “내가 보고 있는 이것은 무엇을 하는가”에도 답해야 함
  • 각 모듈의 내부 동작까지 깊게 들어가지는 않음
    • 그런 내용은 별도 문서나, 더 낫게는 인라인 문서로 옮김
    • 코드맵은 국가 지도이지 주별 지도책이 아님
  • 코드맵을 쓰는 과정에서 프로젝트 구조도 함께 점검할 수 있음
    • 코드맵에서 가까이 두고 싶은 것들이 tree . 실행 결과에서도 인접한지 확인할 수 있음
  • 중요한 파일, 모듈, 타입 이름은 명시함
    • 직접 링크는 시간이 지나며 깨질 수 있으므로 피함
    • 대신 이름으로 심벌 검색을 하도록 유도하면 유지보수 부담 없이 관련된 비슷한 이름의 항목도 발견할 수 있음
  • 아키텍처 불변조건은 명시적으로 적어야 함
    • 중요한 불변조건은 어떤 것이 “없다”는 형태로 나타나는 경우가 많음
    • 예로 웹 개발에서 모델 계층이 뷰에 의존하지 않는다는 사실은 코드만 읽어서는 알아내기 어려울 수 있음
  • 계층과 시스템 사이의 경계도 표시해야 함
    • 경계는 그 뒤에 있는 시스템 구현에 대한 정보를 암시함
    • 가능한 모든 구현까지 제약함
    • 좋은 경계는 코드에서 무작위로 찾기 어렵기 때문에 문서화가 유용함
  • 코드맵 뒤에는 횡단 관심사를 위한 별도 섹션을 추가함
  • 참고할 만한 예시는 rust-analyzer의 architecture.md에서 볼 수 있음

함께 보면 좋은 글 β

GN⁺   [-]
Hacker News 의견들

  • 이 아이디어가 좋고, 저장소 크기와 상관없이 아키텍처 설명은 README에도 들어갈 자리가 있다고 봄
    예를 들어 모든 독자가 작업 흐름을 보고 이해하는 게 중요하다고 생각해서, 메인 README에 일부러 Mermaid 시퀀스 다이어그램[1]을 넣었음[2]
    [1] https://mermaid.js.org/syntax/sequenceDiagram.html
    [2] https://github.com/hbcondo/revenut-app?tab=readme-ov-file#-w...

    • 자연어로 Mermaid 다이어그램을 만들어주는 도구가 있으면 꽤 멋질 듯함. 생각해볼 만함

  • 정말 좋은 조언처럼 들림
    실행 중인 시스템의 아키텍처를 시각화하는 도구가 더 좋아졌으면 함. 아직도 코드를 읽거나 Markdown 파일을 보는 게 최신 방식이라는 게 이상함. 운이 좋으면 Mermaid 다이어그램 정도는 있을 수 있음
    아키텍처가 스스로 실시간으로 드러났으면 좋겠음. 거시적 규모의 관측 가능성이 기본으로 내장되는 식이면 좋겠고, 모두가 컴퓨팅을 더 잘 이해하고 인류가 스스로를 증강하는 데도 도움이 될 것 같음

    • dep-tree 같은 시각화에 키워드 검색이나 LLM 벡터 검색을 붙이면 좋겠음. 질의하면 관련 파일과 클러스터가 강조되는 방식임

  • 임시 기여자가 많은 오픈소스 프로젝트에는 유지보수가 적은 모델로 좋아 보임. 전담 엔지니어가 있는 프로젝트라면 ADR도 고려할 만함
    ADR은 유지보수가 더 필요하지만 “왜 그렇게 했는지”와 “검토했던 대안”을 남기므로, 재설계할 때 매우 유용함
    참고: https://adr.github.io/

    • 여기서는 “대신”보다 “함께”가 더 맞는 표현 같음
      ARCHITECTURE.md는 현재 아키텍처 상태를 담고, ADR은 거기까지 오게 된 의사결정의 기록임. 둘 다 매우 유용함
    • 우리 회사에도 아키텍트들이 쓰는 쓸모없는 문서가 있는데, 대부분 이런 식임
      마이크로서비스, Kafka, Kubernetes: 현재 사용자는 4천 명인데 혹시 10억 명이 되면 어떡하냐는 이유
      GraphDB: SQL로 충분하지 않으면 어떡하냐는 이유
      ElasticSearch: 통계와 함께 전문 검색도 해야 하면 어떡하냐는 이유
      그런데 이런 문서 대부분은 결국 “재미있어서 새 아키텍처/기술을 써보고 싶다, FAANG 다니는 동료가 쓴다, 그 책을 읽었다, 이력서에 좋아 보인다”의 축약형임
      그들이 다음 큰 프로젝트 설계로 넘어가고 나면, 우리 팀은 팀원 수보다 많은 서비스와 위 DB·기술을 계속 동기화해야 함. 물론 이런 문제는 “큰 아키텍처 결정”을 내리는 것보다 훨씬 단순하다는 식임

  • 문득 든 생각인데, 써본 모든 IDE는 왼쪽에 프로젝트 폴더 구조를 표준 디렉터리 트리로 보여줌. 프로젝트를 의존성 그래프로 탐색하게 해주는 IDE가 있나?

    • 질문에 대한 직접 답은 아니지만, 결국 “파일 구조를 더 잘 시각화하고 싶다”는 뜻으로 보임
      목차식 표현은 잘 맞지 않는다고 봄. 요즘 코딩 작업 흐름에서는 터미널을 열고 그 안에서 ranger를 실행한 뒤, 좌우 디렉터리 구조를 탐색할 때 그 터미널로 탭 전환함. VSCode를 열고 분할 터미널에서 위쪽은 일반 터미널, 아래쪽은 Ranger를 실행하는 식임. Midnight Commander도 가능하고, 사실 TUI 파일 탐색기면 됨
      또 프로젝트의 architecture.md 파일에 코드 지도를 넣기 시작했음. tree -L 을 실행하면 Markdown에 넣기 좋은 파일 구조 트리 다이어그램을 원하는 깊이만큼 얻을 수 있음. 그 출력을 Markdown에 추가하고, 각 파일/폴더 뒤에 10단어 미만으로 용도를 설명하는 주석을 붙임
      Ranger - https://github.com/ranger/ranger
      Midnight Commander - https://midnight-commander.org/
    • 나도 정확히 같은 생각을 했음
      어떤 모습일지 두 가지 아이디어가 있음
      첫째, 심볼릭 링크를 써서 파일을 직교적으로 조직하는 여러 디렉터리 트리임. 일반적인 디렉터리 구조는 클라이언트/서버로 나뉘지만, 기능 기준으로 나누고 싶으면 어떨까? IDE가 훨씬 쉽게 만들어줄 수 있음
      둘째, 이 글의 방향처럼 IDE가 북마크를 만들고 그 사이를 오가며 사람들에게 코드를 설명하기 쉽게 해줬으면 함. 가끔 주석을 남기고 클릭하면 코드베이스의 다른 위치로 점프하고 싶음. 이런 것들을 이어 붙이면 코드베이스 전체에 걸쳐 작동 방식을 설명하는 서사를 엮을 수 있음
      이런 쪽으로 작업하는 사람이 있는지 궁금함
    • 실제로는 어떤 모습이 될까? 예를 들어 순환 의존성은 어떻게 처리할 수 있을까?
    • 아마 멀티트리를 원하는 것일 수도 있음

  • 여기서 저자가 말하는 내용을 일반 소프트웨어 프로젝트로 너무 확장하는 건 조심해야 한다고 봄
    맥락이 부족한 기여자가 많은 대형 오픈소스 프로젝트에서는 이런 문서를 유지할 가치가 큼. 하지만 작은 업무 프로젝트에서 개발자가 커밋한 문서는 결국 모두 유지보수되지 않는 상태가 되는 걸 봤음

    • 팀들과 몇 번 아키텍처 세션을 해봤는데 항상 가치가 있었음
      적어도 팀원들이 현재 아키텍처와 이상적인 아키텍처에 대해 서로 매우 다른 생각을 갖고 있다는 걸 알게 됨. 그것을 명시적으로 드러내는 것만으로도 문서를 만들 가치가 있음
      그리고 “문서는 유지보수되지 않는다”는 건 문서를 만들지 말아야 할 이유로 매우 약함. 어떤 문서든, 오래됐거나 미묘하게 틀린 문서라도 “문서 없음”보다는 낫기 때문임

  • 몇 년 전 큰 사이드 프로젝트 중 하나에서 비슷한 방식을 실험해봤음
    https://github.com/shipmight/shipmight/blob/master/src/ARCHI...
    각 파일 상단에는 저장소 안의 다른 ARCHITECTURE.md 파일로 가는 링크 트리를 뒀음. 예시는 다음과 같음: ARCHITECTURE.md <- 현재 위치, backend/ARCHITECTURE.md, backend/api/ARCHITECTURE.md, backend/cli/ARCHITECTURE.md, backend/ui/ARCHITECTURE.md, backend/utils/ARCHITECTURE.md, frontend/ARCHITECTURE.md, internal-charts/ARCHITECTURE.md

  • 짧을수록 미래의 변경으로 무효화될 가능성이 낮음. ARCHITECTURE의 핵심 경험칙은 자주 바뀌지 않을 내용만 적는 것임. 코드와 동기화하려고 하면 안 됨
    인터페이스는 바뀔 가능성이 더 낮고, 바꾸기도 더 어려움. 시스템을 모듈로 분해할 때 쓰는 기준에 관한 Parnas의 관점임
    코드베이스를 이해하기 어렵다는 데 동의함. “패턴” 이름 붙이기가 어느 정도 도움이 되긴 하지만, 결국 꽤 많이 읽어야 함
    GitHub에서는 파일별 커밋 메시지가 설명처럼 느껴질 때가 많음. 그게 더 유용할 수도 있을까?

  • 참여했던 모든 프로젝트에서 온보딩 때 아키텍처 다이어그램과 구성 요소에 대한 간단한 설명을 받았음
    그래서 오픈소스에서 이게 이렇게 흔하지 않다는 게 놀라움

    • “구성 요소 설명”이 바로 문제임. 누군가가 해줘야 하기 때문임
      오픈소스 프로젝트에는 직원의 첫 출근일이 없으니 이런 소개도 없음
      시간이 아주 많지 않다면 이런 설명은 별로 좋지 않음. 직원은 혼자 뭔가 해내기까지 몇 주가 걸릴 것으로 기대되지만, 보안 컨설턴트인 우리는 2주마다 완전히 새로운 설명을 듣게 됨. 문제는 이런 설명이 즉흥적이고 구조화되지 않았으며, 말하는 사람이 지식의 저주 때문에 관련 없는 세부사항을 많이 말한다는 것임
      아마 저장소에 새로 온 사람이 한 번 이것을 작성하고, 이후에는 유지보수만 하는 게 좋을 듯함. 차선은 아무나라도 즉흥적으로 매번 설명하는 대신, 무엇을 넣고 뺄지 1분 정도 생각한 뒤 적어두는 것임. 저자가 말했듯이 이 파일은 프로젝트의 고수준 아키텍처를 설명해야 하고 짧아야 함. 반복 기여자는 모두 읽어야 하며, 짧을수록 향후 변경으로 무효화될 가능성도 낮음

  • 늘 매우 유용한 실천이라고 느꼈음. 많은 프로젝트에는 변경 대부분이 일어나는 핵심 파일 몇 개, 또는 패키지/모듈 등이 있음
    새 기여자나 오랜만에 돌아온 기여자가 그것들을 빨리 익힐 수 있으면 프로젝트 시작 시간이 크게 줄어듦
    여러 직장에서 프로젝트에 아키텍처 파일을 추가해봤고 [0], [1] 반응이 좋았음. 완벽하진 않지만 없는 것보다는 나음
    [0]: https://github.com/zapier/zapier-platform/pull/324
    [1]: https://github.com/stripe/stripe-cli/blob/master/ARCHITECTUR...

    • GitHub에서 이런 걸 자동으로 볼 방법이 있나? 예를 들어 파일 변경 히트맵 같은 것

  • 예전에는 이런 작은 문서/다이어그램-as-code 표준들을 좋아했음
    README 주도 개발, ARCHITECTURE.md, ADR, arc42, C4 등임
    지금은 그냥 git 저장소의 /docs 폴더 안에 Obsidian 보관함을 넣음
    남의 표준을 쓰는 대신, Obsidian에서 개인 노트를 관리하듯 문서를 계속 정리하고 리팩터링함
    처음에는 GitHub의 GFM과 Obsidian 양쪽에서 동작하는 공통 Markdown 부분집합을 쓰고 싶었지만 포기했고, 이제는 Dataview 플러그인과 템플릿 같은 독자 기능을 포함해 Obsidian식 Markdown을 그대로 씀
    Mermaid와 LaTeX는 Obsidian에 내장되어 있고, PlantUML 플러그인도 있음. 시각적 그림/다이어그램에는 내장 Canvas, DrawIO, Excalidraw를 사용함

답변달기