팀 기술 문서를 Git으로 관리한 이유

운영 가이드와 아키텍처 문서, 온보딩용 기술 문서를 Git 저장소에서 관리하기 시작했습니다. 자주 바뀌는 설명과 절차를 코드처럼 수정하고 검토하고 싶었고, AI 도구에도 같은 원본을 전달해 참조할 수 있게 하려는 목적이 있었습니다.

모든 문서를 한 번에 옮기지는 않았습니다. 회의록과 임시 공유는 Confluence에 남기고, 반복해서 읽고 유지해야 하는 기술 문서를 먼저 정리했습니다. 당시에는 이 방식에 적응하며 무엇이 팀에 맞는지 확인하는 단계였습니다.

다이어그램 원본과 문서 조회

Confluence에서 문장과 코드 블록을 읽는 것에는 큰 문제가 없었습니다. 반면 연결된 다이어그램 도구의 내용은 별도로 열거나 내보내야 하는 경우가 있었습니다. 사용하던 AI 조회 경로에서도 페이지 본문과 그림의 구조를 한 번에 전달하기 어려웠습니다.

Markdown과 Mermaid를 함께 두면 문장과 노드·연결 관계를 같은 저장소에서 다룰 수 있었습니다. AI가 이미지를 전혀 해석할 수 없어서가 아니라, 당시 도구에서 반복적으로 검색하고 전달하기 편한 원본 형식이 필요했던 것입니다.

변경 이력과 검토

절차나 구조가 바뀌면 문서를 수정하고 PR에서 함께 검토할 수 있었습니다. 문장의 변경과 다이어그램 수정이 diff에 보이고, 왜 바꿨는지 커밋이나 리뷰와 연결해 남길 수 있었습니다.

다만 저장소에 넣었다고 담당자가 자동으로 정해지거나 문서가 최신 상태로 유지되지는 않습니다. 누가 검토할지와 시스템 변경 시 어떤 문서를 함께 확인할지 정하는 일이 필요했습니다.

문서 유형과 탐색 순서

새로 들어온 사람이 읽을 설명과 장애 때 따라 할 절차를 구분하려고 했습니다. 아래는 문서 역할을 나누는 구성 예시입니다.

README.md           # 시작점과 주요 문서 링크
architecture/       # 시스템 구조와 데이터 흐름
runbooks/           # 운영 작업과 장애 대응 절차
onboarding/         # 접근 신청과 개발 환경 준비
adr/                # 결정 배경과 대안, 변경 이력

실제 폴더 이름보다 각 문서의 목적과 찾는 경로가 일정한 것이 중요했습니다. 운영 절차에는 대상 환경과 필요한 권한, 확인 방법이 있어야 했고, 설계 문서에는 현재 구조와 과거 결정을 구분해서 적을 필요가 있었습니다.

AI가 참조할 범위

파일 경로와 제목을 통해 필요한 내용을 찾고, Markdown과 Mermaid 원본을 함께 읽게 하는 방식으로 활용하려 했습니다. 전체 저장소를 매번 전달하기보다 관련 문서에서 시작해 필요한 참조를 따라갈 수 있도록 링크를 정리했습니다.

문서가 텍스트라는 이유만으로 답변이 정확해지는 것은 아닙니다. 오래된 내용이나 실제 운영과 다른 예시가 있으면 AI도 그 내용을 바탕으로 답할 수 있습니다. 문서의 적용 범위와 최근 확인 시점, 관련 코드가 함께 있어야 검토하기 편합니다.

Confluence와 Git의 연결

같은 내용을 양쪽에서 따로 수정하면 어느 쪽이 기준인지 다시 헷갈릴 수 있습니다. 기술 문서의 기준은 저장소에 두고, Confluence에서는 필요한 곳으로 연결하는 식으로 역할을 나누려 했습니다.

이 작업을 통해 운영 대응이나 온보딩 시간이 얼마나 줄었는지까지 측정한 것은 아닙니다. 팀이 쓰던 도구 안에서 기술 문서를 계속 수정하고, 사람과 AI가 같은 내용을 참조할 수 있는 방식을 시도한 기록입니다.