본문으로 건너뛰기

문서 자동화 프로세스

개요​

이 문서는 Gemini CLI를 활용하여 SurfAI 프로젝트의 기술 문서를 자동화하는 프로세스에 대해 설명합니다. 이는 기술 문서화의 효율성을 높이고, 항상 최신 상태의 정확한 문서를 유지하며, 다양한 이해관계자들이 쉽게 접근하고 이해할 수 있도록 돕는 것을 목표로 합니다.

1. 문제 상황​

기존의 기술 문서화 과정에서 다음과 같은 문제점들이 식별되었습니다:

  1. 수동 작업의 번거로움: 사람이 일일이 기술 문서를 작성하는 것은 많은 시간과 노력이 필요합니다.
  2. 다이어그램/도표 구성의 어려움: 기술 문서에 필요한 다이어그램이나 도표를 구성하는 데에도 많은 시간과 노력이 소요됩니다.
  3. 다국어 지원의 필요성: 기술 문서를 소비하는 대상이 범국가적일 경우, 번역 작업까지 추가적인 노력이 필요합니다.
  4. 비개발자 접근성의 한계: 개발자가 사용하는 전문 용어 때문에 비개발자 팀원이 기술 문서를 이해하기 어렵습니다.
  5. 개발자의 비개발자 친화적 문서 작성의 어려움: 개발자가 비개발자 팀원을 위해 쉬운 언어로 문서를 작성하는 것은 지식의 범위와 수준 차이로 인해 어렵고 번거로운 일입니다.
  6. 비개발자의 기술 문서 작성의 어려움: 비개발자가 문서를 작성하는 것은 추가되거나 수정되는 모듈에 대한 전문 지식이 필요하기 때문에 역시 어려운 일입니다.

2. 제시된 해결책​

위 문제점들을 해결하기 위해 Gemini CLI를 활용한 다음과 같은 자동화 방안이 제시되었습니다:

  1. 자동 문서 반영: 개발자가 새로운 모듈을 추가하거나 수정한 뒤 main 브랜치에 merge할 때, Gemini CLI를 통해 관련 사항을 surfai-docs의 기술 문서에 적절히 반영합니다.
  2. 다이어그램/도표 자동 포함: 소프트웨어의 전체적인 아키텍처, 기술 스택, 데이터베이스 스키마 등에 대한 맥락을 Gemini CLI가 가지고 있다가 필요한 경우 문서에 적절한 다이어그램이나 도표(Mermaid 기반)를 자동으로 포함시킵니다.
  3. 다국어 문서 지원: Gemini CLI가 기술 문서를 작성한 후, 추가로 영어와 같은 필요 언어로 번역 작업을 이어서 진행하여 다국어 문서를 지원합니다.
  4. 비개발자 친화적 문서 생성: 번역 작업 후, 비개발자 팀원도 쉽게 읽을 수 있도록 기존 기술 문서를 더 쉬운 언어로 풀어쓴 문서를 Gemini CLI가 생성합니다.

3. 파생된 문제점 및 해결책​

제시된 해결책으로부터 다음과 같은 파생 문제점들이 발생할 수 있으며, 이에 대한 해결책도 함께 마련되었습니다:

  1. 접근성 문제: Gemini CLI가 코드와 함께 기술 문서를 다루도록 해야 하는데, 비개발자 팀원이 깃이나 코드에 직접 접근해서 문서를 다루기에는 접근성이 낮습니다.
    • 해결책: Docusaurus라는 Static Site Generator를 통해 생성된 기술 문서를 배포합니다. Docusaurus는 개발자 친화적인 기능과 마크다운 지원, 다국어 지원과 같은 장점이 있어 좋은 해결책입니다.
  2. 다이어그램 한계: 아키텍처 구조 등을 그리기 위한 다이어그램을 그리는 것은 순수 Gemini CLI만으로는 한계가 있습니다.
    • 해결책: Mermaid라는 텍스트 기반으로 다이어그램, 흐름도, 순서도 등을 생성할 수 있는 도구를 사용합니다. Gemini CLI로 하여금 프로젝트에 맞는 Mermaid text를 생성해달라고 요청하는 방식을 사용합니다.
  3. 일관성 부족: Gemini CLI가 번역 혹은 쉬운 언어로 풀어쓰는 작업에 대한 일관성이 부족할 수 있습니다.
    • 해결책: .gemini/GEMINI.md 파일 혹은 PRINCIPLES.md와 같은 컨텍스트 파일을 작성하여 Gemini CLI가 문서 생성에 참고할 수 있는 기준을 명확히 작성합니다.

4. Gemini CLI의 역할​

이 모든 프로세스의 핵심은 Gemini CLI입니다. Gemini CLI는 다음과 같은 역할을 수행합니다:

  • 문서 업데이트 트리거: 사용자로부터 "문서 추가: [내용]" 또는 "문서 수정: [내용]"과 같은 명시적인 지시가 있을 때 문서 업데이트를 시작합니다.
  • 변경점 파악: 사용자 지시를 바탕으로 변경 내용을 분석하고, 필요한 경우 코드베이스를 탐색하여 추가 정보를 수집합니다.
  • 적절한 문서 식별 및 수정: surfai-docs 내에서 변경 내용에 가장 적합한 문서를 스스로 식별하여 수정합니다. (사용자가 특정 문서를 지정하지 않음)
  • Pull Request 자동 생성: 문서 수정 완료 후, surfai-docs 레포지토리에 새로운 브랜치를 생성하고, 변경 사항을 커밋한 후, Pull Request를 자동으로 생성합니다. 이때 브랜치 이름, 커밋 메시지, PR 제목 및 본문은 Gemini CLI가 적절하게 구성합니다.

이러한 자동화 프로세스를 통해 SurfAI 프로젝트의 기술 문서화는 더욱 효율적이고 체계적으로 관리될 것입니다.