아키텍처 변경 요청: C4 모델을 위한 Pull Request

지난달, 제가 자문하는 팀의 한 엔지니어가 아키텍처 다이어그램에서 핵심 서비스의 이름을 변경했습니다. 논의 없이. 검토 없이. 변경은 즉시 반영되었고, 세 팀이 다음 스탠드업에서 실제 서비스가 이름이 바뀐 건지 다이어그램만 바뀐 건지 혼란스러워했습니다. 바뀌지 않았습니다. 누군가가 레이블이 불명확하다고 생각하고 "수정"한 것이었습니다.

그 사건은 우리가 한동안 생각해온 것을 결정화했습니다. 코드에는 Pull Request가 있습니다. 인프라에는 plan/apply가 있습니다. 데이터베이스 스키마에는 마이그레이션이 있습니다. 하지만 아키텍처 다이어그램은? 편집 권한이 있는 누구나 언제든지 무엇이든 변경할 수 있고, 나머지 팀은... 결국에 알게 됩니다.

오늘 우리는 이것을 바꿉니다. 아키텍처 변경 요청은 C4 모델에 Pull Request 워크플로우를 가져옵니다.

작동 방식

개념은 의도적으로 익숙합니다. GitHub에서 Pull Request를 열어본 적이 있다면, 이미 어떻게 작동하는지 알고 있습니다.

변경 요청을 생성하는 것으로 시작합니다. 제목을 지정하고, 무엇을 제안하는지와 이유를 설명합니다. 그런 다음 변경을 추가합니다 — 새 시스템 생성, 기존 컨테이너 업데이트, 사용하지 않는 컴포넌트 삭제, 관계 수정. 각 변경은 특정 C4 요소에 대한 개별 작업입니다: 생성, 업데이트 또는 삭제.

변경 요청은 초안으로 시작됩니다. 준비될 때까지 계속 변경을 추가하고 다듬을 수 있습니다. 제안이 완료되면 검토를 위해 열기합니다.

팀원들은 프로젝트의 변경 요청 목록에서 열린 요청을 봅니다. 제안된 각 변경을 검토하고, 무엇이 생성, 수정 또는 제거되는지 정확히 볼 수 있습니다. 리뷰를 남깁니다: 승인, 변경 요청, 또는 코멘트. 필요한 승인 수가 충족되면 요청을 병합할 수 있습니다 — 모든 변경이 라이브 C4 모델에 하나의 원자적 작업으로 적용됩니다.

시각적 미리보기

JSON blob처럼 읽히는 diff 뷰는 원하지 않았습니다. 아키텍처는 시각적이며, 아키텍처 변경을 검토하는 것도 시각적이어야 합니다.

모든 변경 요청에는 다이어그램의 라이브 미리보기가 포함됩니다. 미리보기는 제안된 모든 변경이 오버레이된 현재 C4 모델을 렌더링합니다. 새 요소는 녹색 하이라이트로 나타납니다. 수정된 요소는 호박색 링을 얻습니다. 삭제된 요소는 빨간색 표시기를 보여줍니다. C4 레벨 — 시스템, 컨테이너, 컴포넌트, 코드 — 을 탐색하며 모든 깊이에서 제안의 전체 영향을 볼 수 있습니다.

이것은 라이브 다이어그램에 사용하는 것과 동일한 대화형 React Flow 캔버스이며, 동일한 드릴다운, 줌, 팬 기능이 있습니다. 유일한 차이점은 데이터입니다: 병합 후 아키텍처가 어떻게 보일지에 대한 계산된 프로젝션입니다.

검토 프로세스

검토는 간단한 모델을 따릅니다. 리뷰어는 다음을 할 수 있습니다:

• 승인 — "좋아 보입니다, 준비되면 병합하세요."
• 변경 요청 — "우려가 있습니다, 진행하기 전에 논의합시다."
• 코멘트 — "반대는 없지만, 여기 약간의 맥락이 있습니다."

각 리뷰에는 상세한 피드백을 위한 자유 텍스트 본문이 포함됩니다. 변경 요청은 프로젝트의 필수 임계값에 대한 승인 수를 추적합니다. 기본적으로 하나의 승인이 필요하지만 프로젝트별로 구성할 수 있습니다 — 가벼운 추적을 원하는 소규모 팀은 제로 승인, 공식적인 서명이 필요한 대규모 조직은 둘 또는 셋.

요청 전용 모드

더 나아가고 싶은 팀을 위해 프로젝트 설정에 요청 전용 모드를 추가했습니다. 활성화하면 C4 모델에 대한 직접 편집이 잠깁니다. 아키텍처를 수정하는 유일한 방법은 변경 요청을 통하는 것입니다.

이것은 다이어그램이 읽기 전용이 된다는 의미가 아닙니다. 여전히 탐색하고, ADR과 문서를 요소에 연결하고, 코멘트를 추가할 수 있습니다. 변경 요청 워크플로우를 거치지 않고는 요소를 이동, 이름 변경, 생성 또는 삭제할 수 없을 뿐입니다.

이것은 아키텍처 거버넌스가 중요한 조직을 위해 만들었습니다 — 규제 산업, 대규모 엔지니어링 팀, 공유 인프라를 관리하는 플랫폼 팀. 아키텍처는 모든 변경이 추적 가능하고 검토되는 통제된 산출물이 됩니다.

활동 추적

모든 변경 요청 라이프사이클 이벤트가 프로젝트의 활동 탭에 나타납니다. 요청이 열리거나, 닫히거나, 다시 열리거나, 병합되면 작성자, 타임스탬프, 요청 제목과 함께 이력 항목이 기록됩니다. 이것은 아키텍처가 어떻게 진화했는지의 타임라인을 제공합니다 — 오늘 어떻게 보이는지뿐만 아니라, 이를 형성한 제안과 결정의 순서도 알 수 있습니다.

ADR과 문서 링크와 결합하면 완전한 내러티브를 얻습니다: 무엇이 변했는지(변경 요청), 왜 변했는지(ADR), 어떻게 더 넓은 맥락에 맞는지(문서).

변경 구성

변경 빌더를 사용하면 요소별로 제안을 구성할 수 있습니다. 각 변경에 대해 다음을 지정합니다:

• 작업: 생성, 업데이트 또는 삭제
• 요소 유형: 시스템, 컨테이너, 컴포넌트, 코드 요소, 관계 또는 오버레이
• 요소 데이터: 요소의 전체 명세 — 이름, 설명, 기술, 유형, 직접 생성할 때 설정하는 모든 필드

업데이트의 경우, 시스템은 현재 상태와 제안된 상태를 모두 캡처하여 리뷰어가 정확히 무엇이 변하는지 볼 수 있습니다. 삭제의 경우, 기존 요소 데이터가 참조를 위해 요청에 보존됩니다.

작업을 자유롭게 혼합할 수 있습니다. 단일 변경 요청이 두 개의 새 컨테이너를 생성하고, 관계를 업데이트하고, 사용되지 않는 컴포넌트를 삭제할 수 있습니다. 병합 시 모든 변경이 함께 적용됩니다.

팀에게 의미하는 것

아키텍처 변경 요청은 관료주의를 추가하는 것이 아닙니다. 아키텍처 진화를 의도적으로 만드는 것입니다.

코드베이스에서 Pull Request는 단순한 관문이 아닙니다 — 커뮤니케이션 도구입니다. "여기 내가 제안하는 것이 있고, 이유가 있으며, 어떻게 생각하세요?"라고 말합니다. 지식 공유, 실수를 조기에 발견, 공유된 이해 구축을 위한 자연스러운 순간을 만듭니다.

아키텍처도 같은 대우를 받을 자격이 있습니다. 누군가가 새 서비스 추가를 제안할 때, 그것은 다이어그램에 나타나기 전에 나눌 가치가 있는 대화입니다. 누군가가 컴포넌트 계층 구조를 재구성하려 할 때, 팀은 새로운 현실이 되기 전에 전체 그림을 봐야 합니다.

변경 요청은 그 대화를, 구조화되고 추적 가능하게 만든 것입니다.

시작하기

아키텍처 변경 요청은 모든 팀 플랜에서 지금 사용할 수 있습니다. 아무 프로젝트로 이동하면 사이드바에서 "요청" 섹션을 찾을 수 있습니다. 첫 번째 요청을 만들고, 변경을 추가하고, 검토를 위해 열어보세요.

워크플로우를 강제하려면 프로젝트 설정에서 요청 전용 모드를 활성화하세요. 팀의 거버넌스 요구에 맞게 필요한 승인 수를 구성하세요.

아키텍처는 팀의 결정입니다. 이제 도구가 이를 명시적으로 만듭니다.

협업 아키텍처에 대해 더 알고 싶으신가요? C4 다이어그램에서의 실시간 협업에 대해 읽어보거나, 아키텍처 결정 기록이 모든 아키텍처 진화의 "왜"를 포착하여 변경 요청을 어떻게 보완하는지 알아보세요.