팀 문서를 Git으로 옮긴 이유

팀 문서를 Git 저장소로 옮긴 이유를 한 줄로 줄이면 이렇다. 공용 기술 문서와 운영 지침을 한곳에 모으되, 사람이 아니라 AI도 안정적으로 읽고 참조할 수 있는 형태로 만들고 싶었기 때문이다. 사람끼리 읽고 공유하는 기준으로는 Confluence만으로도 충분한 경우가 많았다. 코드 블록 같은 요소는 문제가 없었다. 하지만 이 문서들을 AI가 지속적으로 읽고 활용하는 용도로 보면, 특히 다이어그램 쪽에서 한계가 분명했다.

문서를 Git으로 옮긴다는 결정은 단순히 저장 위치를 바꾸는 일이 아니었다. 공용 기술 문서를 코드처럼 관리하겠다는 선택에 가까웠다. 특히 우리가 먼저 옮긴 것은 회의록 같은 문서보다 오래 살아남아야 하는 기술 문서와 지침이었다. 운영 가이드, 아키텍처 설명, ADR, 온보딩용 기술 문서처럼 구조가 분명해야 하고 팀이 반복해서 참조해야 하며, AI가 읽을 때도 문맥을 잃지 않아야 하는 문서들이다.

물론 아직은 적응 기간에 가깝다. 무엇이 우리 팀에 가장 잘 맞는 정답인지는 확정하지 못했다. 다만 공용 기술 문서와 운영 지침을 Git 기반으로 관리하고, Markdown과 Mermaid, 그리고 AI가 읽기 좋은 문서 구조까지 함께 시도해 보는 것이 충분히 가치 있다고 판단했다.

즉, team-docs는 “문서를 Git에 보관하는 저장소”라기보다, 공용 기술 문서와 운영 지침을 Markdown과 Mermaid 중심으로 정리하고, AI와 사람이 함께 활용할 수 있게 만드는 저장소에 가까웠다.

왜 Confluence만으로는 부족했는가

Confluence는 회의록, 프로젝트 킥오프, 임시 공유 문서에는 강하다. 페이지를 빠르게 만들고 링크를 퍼뜨리기 쉽고, 비개발자도 접근하기 편하다. 문제는 엔지니어링 문서가 시간이 지나면 점점 “살아 있는 문서”가 되어야 한다는 점이다.

운영 가이드, ADR, 구조 설명, 온보딩 문서 같은 것은 한 번 써서 끝나는 문서가 아니다. 코드와 함께 진화하고, 변경 이력을 따라가야 하며, 리뷰를 받아야 한다. 이 지점에서 Confluence는 몇 가지 한계가 있었다.

Confluence는 사람 중심 협업 문서 도구로는 충분히 강했다. 프로젝트 문서, Jira와 연결된 업무 기록, 팀 위키 용도로는 잘 맞았다. 코드 블록도 지원하기 때문에 기술 문서 자체를 전혀 못 쓰는 도구는 아니었다. 다만 아키텍처나 기술 구조를 설명하는 문서에서는 다이어그램이 가장 애매했다.

다이어그램도 비슷했다. Confluence 안에서 Lucidchart 같은 도구로 그림을 넣는 것은 사람에게는 충분히 유용하다. 하지만 AI 입장에서는 그 결과가 바로 읽을 수 있는 텍스트 원본이 아니다. 문서 안의 매크로를 보고, 다시 연결된 다이어그램 문서를 찾고, 필요한 경우 export까지 거쳐야 구조를 해석할 수 있다. 이 과정은 사람에게는 자연스러워도 AI에게는 꽤 비효율적이다.

즉, Confluence는 “빨리 쓰기”에는 좋았지만, “오래 관리하기”와 “AI가 안정적으로 읽기”에는 점점 불리해졌다.

왜 공용 기술 문서 저장소가 필요했는가

팀 안에는 시간이 지나도 계속 다시 찾아보게 되는 문서들이 있다. 장애가 났을 때 보는 운영 가이드, 새로운 기능을 설계할 때 참고하는 아키텍처 문서, 왜 이런 결정을 했는지 남겨 두는 ADR, 새 팀원이 빠르게 구조를 이해하기 위한 온보딩 문서들이다.

이런 문서들은 공통점이 있다.

• 특정 개인이 아니라 팀 전체가 함께 써야 한다
• 한 번 읽고 끝나는 것이 아니라 반복해서 참조된다
• 코드와 시스템이 바뀌면 문서도 같이 바뀌어야 한다

그래서 필요했던 것은 개인 메모 저장소가 아니라, 공용 기술 문서와 운영 지침을 팀 차원에서 같이 관리하는 기준 저장소였다.

Git으로 옮긴 것은 주로 어떤 문서였나

모든 문서를 한 번에 옮긴 것은 아니었다. 우선순위는 명확했다. 시간이 지나도 반복해서 참조되고, 구조화가 중요하고, 코드와 함께 바뀌어야 하는 기술 문서부터 옮겼다.

대표적으로는 아래 문서들이 잘 맞았다.

• 운영 가이드는 절차가 바뀔 때마다 diff와 리뷰 이력이 중요해서 Git 기반 관리와 잘 맞았다.
• 아키텍처 문서는 Mermaid, 코드 예시, 구조 설명을 함께 다뤄야 해서 Markdown 중심 문서 흐름이 특히 편했다.
• ADR은 어떤 결정을 왜 했는지 commit과 PR 맥락과 함께 남기기 좋았다.
• 온보딩용 기술 문서는 새 팀원이 반복해서 읽고 자주 갱신해야 하므로, 최신성을 유지하기 쉬운 방식이 필요했다.

반대로 회의록, 임시 공유 메모, 킥오프 문서는 여전히 위키 쪽이 더 잘 맞았다. 즉 team-docs는 모든 팀 문서를 모으는 저장소가 아니라, 계속 유지하고 재사용해야 하는 공용 기술 문서와 운영 지침을 위한 저장소였다.

Git으로 옮기면 무엇이 달라지는가

Git 저장소로 문서를 옮기면 가장 먼저 달라지는 것은 문서가 코드와 비슷한 생애주기를 갖게 된다는 점이다.

1. 변경은 commit으로 남는다
2. 검토는 PR로 이루어진다
3. diff를 통해 무엇이 바뀌었는지 바로 보인다
4. 문서도 ownership과 review 책임이 생긴다

이 흐름은 특히 운영 가이드나 아키텍처 문서에 잘 맞았다. 문서가 최신 코드와 같이 바뀌어야 할 때, “누가 언제 왜 바꿨는지”를 Git 히스토리에서 바로 볼 수 있기 때문이다.

Markdown과 Mermaid를 제대로 쓰고 싶었다

엔지니어링 문서에서 중요한 것은 보기 좋은 결과보다 수정 가능한 원본인 경우가 많다. Markdown은 문장, 표, 코드 블록을 가볍게 다루기 좋고, Mermaid는 시스템 흐름과 구조를 텍스트로 유지하게 해 준다.

이 조합이 좋았던 이유는 단순하다.

• 코드 리뷰와 같은 도구로 문서를 리뷰할 수 있다
• 다이어그램도 텍스트 diff로 바뀐 부분을 볼 수 있다
• IDE에서 문서와 코드를 함께 열어 두고 수정하기 쉽다

예를 들어 아키텍처 변경을 설명하는 문서가 있다면, 이미지 파일을 갈아끼우는 것보다 Mermaid 소스를 수정하는 편이 훨씬 관리하기 쉽다.

문서를 “렌더 결과”가 아니라 “텍스트 원본”으로 다루고 싶을수록 Git 쪽이 더 자연스러웠다.

여기서 Mermaid가 특히 중요했던 이유는 단순히 다이어그램을 예쁘게 그리기 위해서가 아니었다. 사람은 Confluence의 다이어그램 매크로나 Lucidchart 결과만 봐도 구조를 이해할 수 있다. 하지만 AI는 그 그림 뒤에 있는 시스템 경계와 연결 관계를 텍스트로 받아야 더 안정적으로 해석할 수 있다. 그래서 Mermaid는 부가 기능이 아니라, 애초에 AI 친화적인 기술 문서를 만들기 위한 핵심 형식에 가까웠다.

Mermaid는 이 점에서 유리했다.

• 사람이 읽기에도 충분히 직관적이다
• diff로 무엇이 바뀌었는지 볼 수 있다
• 코드처럼 텍스트 원본을 유지할 수 있다
• AI가 노드와 연결 관계를 더 직접적으로 읽을 수 있다

문서 저장소에서는 구조와 이름이 더 중요해진다

문서를 Git으로 옮겼다고 해서 자동으로 좋아지지는 않는다. 오히려 폴더 구조와 파일명 규칙이 없으면 저장소는 금방 커다란 잡동사니 폴더가 된다.

그래서 중요한 것은 저장소 자체보다 분류 원칙이었다.

이런 식의 구분이 있어야 문서가 쌓일수록 탐색성이 좋아진다. 그리고 이 구조는 사람뿐 아니라 AI에게도 중요하다.

AI가 읽고 참조하기 좋은 문서는 어떤 특징을 가지는가

AI 도구가 문서를 잘 참조하게 하려면, 문서가 단순히 많이 있는 것보다 일관된 구조와 이름을 가져야 한다. 이 점이 바로 우리가 문서를 Git으로 옮긴 핵심 이유 중 하나였고, Git 기반 문서는 이 요구에 Confluence보다 더 잘 맞았다.

이유는 몇 가지다.

• 파일 경로와 파일명이 고정돼 있어 검색 대상이 명확하다
• Markdown 구조가 일정해서 제목, 코드, 표를 해석하기 쉽다
• Mermaid와 코드 블록이 텍스트라서 내용 추출이 쉽다
• PR과 commit 이력으로 최신 변경 맥락을 함께 볼 수 있다

즉, Git 기반 문서는 사람이 읽기 쉬울 뿐 아니라, AI가 “무엇이 어떤 문서인지” 파악하기에도 더 적합하다. 특히 공용 기술 문서일수록 이 차이가 더 크게 난다. 운영 절차, 아키텍처 경계, 설정 예시, 코드 블록, Mermaid 흐름도가 한 문서 안에 함께 있고, 그것이 텍스트로 관리되기 때문이다.

여기서 중요한 건 문서를 “AI만을 위해” 쓴다는 뜻은 아니라는 점이다. 다만 이번 저장소는 애초에 AI가 참조하기 좋은 문서 구조를 중요한 목표로 두고 설계됐고, 그 결과 사람도 더 쉽게 재사용할 수 있는 형태가 됐다.

Confluence와 Git은 무엇을 각각 맡아야 할까

Git으로 문서를 옮겼다고 해서 Confluence를 버릴 필요는 없다. 오히려 두 도구의 역할을 분리하는 편이 더 낫다.

이 역할 분담이 정리되고 나니, Confluence는 더 가볍고 빠른 공유 도구가 됐고, Git 저장소는 오래 살아남아야 할 엔지니어링 지식의 기준점이 됐다.

문서 저장소를 만든 이유는 결국 유지 가능성 때문이다

팀 문서를 Git으로 옮긴 가장 큰 이유는 기술 유행을 따르기 위해서가 아니었다. Markdown, Mermaid, diff, PR 리뷰처럼 엔지니어가 익숙한 작업 방식 안에서 문서를 유지하고 싶었기 때문이다.

그리고 그 결과, 사람이 찾기 쉬운 문서가 만들어졌고, AI도 더 잘 참조할 수 있는 형태가 됐다.

결국 중요한 것은 도구 이름이 아니다. 문서가 시간이 지나도 업데이트될 수 있고, 구조가 유지되며, 누가 봐도 어디에 무엇이 있는지 찾을 수 있어야 한다. 지금은 공용 기술 문서와 운영 지침을 Git 기반으로 관리하고, Markdown과 Mermaid 중심으로 정리하는 방식이 가장 실용적이라고 보고 계속 시도해 보고 있다.

물론 이것이 최종 정답이라고 생각하지는 않는다. 앞으로 AI 도구가 바뀌고, 문서 작성 방식도 달라질 수 있다. 다만 적어도 지금 시점에서는, 사람이 읽기 좋으면서도 AI가 반복해서 참조하기 좋은 기술 문서를 만들기 위해 여러 방식을 실험해 보는 과정 자체가 충분히 가치 있다고 느끼고 있다.