오늘날 IT 프로젝트에서 문서화 는 프로젝트의 성공과 효율성을 보장하는 필수적인 요소이지만, 여전히 많은 프로젝트에서 우선순위에서 밀리거나 제대로 관리되지 않는 경우가 많습니다. 특히 신규 프로젝트에 투입되었을 때 기존 코드와 기능을 빠르게 파악해야 하는 경우, 문서화의 부재는 프로젝트의 이해도를 떨어뜨려 심각한 문제로 다가옵니다. 저 역시 프로젝트 매니저로 첫 업무를 맡았을 때, 10명의 개발자와 방대한 코드베이스 사이 문서화가 거의 이루어지지 않은 프로젝트를 경험하게 되면서 이러한 문제를 뼈저리게 느꼈습니다. 이로 인해 프로젝트의 주요 기능을 파악하는 데만 한 달 이상이 소요되었고, 고객과 개발자들이 일일이 소통하며 문제 해결 방안을 찾는 반복적인 작업이 이어졌습니다.
이러한 문제는 단순히 한 팀의 경험이 아니라, 대규모 IT 기업 및 복잡한 프로젝트에서 흔히 발생하는 어려움입니다. 개발자들은 대개 코딩 자체에는 열정을 쏟지만, 코드 주석 작성이나 프로젝트 문서화 작업은 기피하는 경우가 많습니다. 더욱이 초기 문서화가 이루어지더라도, 프로젝트가 확장되거나 시간이 흐름에 따라 이를 최신 상태로 유지하는 일은 또 다른 도전과제로 남습니다.
이 글에서는 이처럼 빈번히 발생하는 문서화 문제를 해결하기 위해 Qodo (구 CodiumAI)와 Kotaemon과 같은 도구를 활용한 새로운 접근법을 제안합니다. 이 도구들이 제공하는 효과적인 문서화 방식이 어떻게 실무에서의 어려움을 완화하고, 프로젝트 효율성을 높이는지에 대해 데모를 통해 알아보겠습니다.
Qodo (구 CodiumAI) 이란 무엇인가요?
이 글을 작성하게 된 첫 번째 중요한 계기는 CodiumAI(현재 Qodo로 알려져 있지만, 여전히 이전 이름으로도 사용 가능)를 알게 된 것입니다. Qodo는 코드 품질을 개선하고 테스트를 자동화하는 플랫폼으로, 기존의 생성형 도구와는 다르게 코드 분석 및 테스트 작성에 특화되어 있습니다. 이를 통해 논리 오류, 성능 문제, 보안 취약점을 방지하는 데 큰 도움이 됩니다.
Qodo의 주요 장점 중 하나는 기존 코드를 바탕으로 단위 테스트와 통합 테스트를 자동 생성하는 기능으로, 아키텍처 개선 및 코드 유지 관리에 대한 권장사항을 제시해 대규모 팀과 조직에 특히 유용합니다. 또한 테스트 생성 외에도 애플리케이션 성능과 보안을 향상시키는 데 도움이 되는 권장 사항을 제공합니다. 70개 이상의 프로그래밍 언어를 지원하고, VS Code와 같은 인기 있는 IDE와 통합되며, 클라우드 및 로컬 환경 모두에서 작동하여 다양한 개발 및 엔터프라이즈 환경에 유연한 솔루션을 제공합니다.
이번 글에서 특히 중요한 것은 Qodo 가 제공하는 코드 주석 생성 기능입니다. 코드를 기반으로 주석을 자동으로 생성하고, 이후 Kotaemon을 통해 더욱 깊이 있는 정보를 받고 분석하는 과정을 보여드리도록 하겠습니다.
Kotaemon이란 무엇인가요?
최근 Github에서 발견한 새 프로젝트 Kotaemon은 문서 관리 및 데이터 분석을 위한 오픈 소스 도구입니다. Kotaemon은 RAG(검색 강화 생성, Retrieval-Augmented Generation) 방식을 사용하여 대용량 텍스트 데이터와의 상호작용을 최적화하는 것을 목표로 하고 있습니다. 아래는 Kotaemon의 주요 기능과 활용 가능성에 대한 자세한 설명입니다.
- 문서 작업 인터페이스
Kotaemon은 PDF와 같은 문서를 다운로드하고 볼 수 있는 Gradio 기반 인터페이스를 제공하며, 다양한 텍스트 형식을 처리할 수 있습니다. 이를 통해 대량의 정보 관리를 간소화하고, 문서 내 특정 데이터를 찾기 위해 질문을 직접 입력해 검색할 수 있습니다.
- 질문과 답변을 위한 RAG 파이프라인
RAG 파이프라인을 통해 다운로드한 데이터를 기반으로 응답을 생성하는 기능이 Kotaemon에 있습니다. 시스템은 문서에서 관련 텍스트 조각을 찾아내고, 언어 모델이 제공하는 데이터와 결합해 사용자 질문에 대한 답변을 생성합니다.
- 언어 모델 및 벡터 검색 지원
OpenAI나 Azure와 같은 로컬 및 클라우드 언어 모델을 사용할 수 있으며, 벡터 검색 기능을 제공하여 비정형 데이터 처리에 유리합니다. 이를 통해 유사한 텍스트 조각을 찾고, 의미적 유사성에 기반해 복잡한 질문에 답변할 수 있습니다.
- 다중 모드 데이터 처리
텍스트 파일 외에도 Kotaemon은 표와 이미지 작업을 지원하여 다양한 데이터 유형을 처리해야 하는 프로젝트에서 특히 유용합니다. 예를 들어 한 문서에서 텍스트와 표를 동시에 분석할 수 있어 여러 소스의 데이터를 효과적으로 결합할 수 있습니다.
- 인용 및 데이터 시각화
이 시스템은 데이터 인용 및 시각화 도구를 지원하며, NanoGraphRAG 기능을 통해 관련 결과를 그래프로 표시할 수 있습니다. 이는 복잡한 데이터를 제시하고, 서로 다른 소스 간의 관계를 분석하는 데 유용합니다.
설치 방법
Qodo 설치는 웹사이트에 접속하여 회원 가입 후, IDE에서 플러그인을 다운로드하고 로그인만 하면 됩니다. 복잡한 설정 없이 쉽게 사용할 수 있다는 점이 매우 만족스러웠습니다.
Kotaemon은 설치 및 초기 구성 방법이 몇 가지 있습니다. 가장 간단한 방법은 Hugging Face에서 해당 스페이스를 복사해 실행하는 것이며, 보다 고급 설정으로는 직접 인스턴스를 배포하는 방법도 있습니다. 여기서는 두 번째 방법에 대해 자세히 설명하겠습니다. 필요한 단계는 다음과 같습니다:
- 프로젝트의 GitHub 릴리스 섹션에서 최신 Kotaemon 릴리스의 .zip 아카이브를 다운로드합니다.
- 다운로드한 파일을 압축 해제합니다.
- /scripts 폴더에서 적합한 스크립트를 실행합니다. 저는 Linux에 설치할 예정이지만, macOS와 Windows에서도 설치할 수 있습니다.
- 설치가 완료되면 웹 버전을 사용할 수 있습니다.
- 저는 이미 배포된 Ollama 인스턴스를 보유하고 있으므로 로컬 LLM을 사용할 예정이지만, 원하는 경우 Cohere API나 OpenAI/Azure를 사용할 수도 있습니다.
사용 방법
1. Qodo
Qodo 는 코드의 테스트 생성, 설명, 개선 제안 및 문서화 기능을 통해 개발자가 효율적으로 코드를 분석하고 개선할 수 있도록 돕는 강력한 도구입니다. 코드의 특정 섹션을 선택하여 기능별로 테스트를 생성하거나 개선 사항을 확인할 수 있어, 복잡한 코드베이스에서 개별 요소의 품질을 손쉽게 높일 수 있습니다.
코드의 특정 섹션을 선택하고 /test 명령을 실행하면 해당 코드에 대한 테스트 생성 제안이 포함된 별도의 창이 표시됩니다. 이미 작성된 테스트 예시를 템플릿으로 지정하거나, 하나 이상의 테스트를 즉시 실행할 수 있으며, 코드 개선을 위한 권장 사항을 받을 수 있습니다. 또한 적합한 테스트를 선택하여 새로운 파일로 저장할 수 있습니다.
/explain 옵션을 사용하면 선택한 코드 섹션의 동작 방식에 대한 설명과 함께 잠재적인 변경 사항 목록이 표시됩니다.
다음으로, 코드 개선 기능을 살펴보겠습니다. React로 작성된 작은 컴포넌트를 선택하여 실행하면, 짧은 로딩 후 제안된 변경 사항을 확인하고 적용할 수 있습니다.
물론 제안된 변경 사항이 항상 정확하지는 않으나, 제 경험에 따르면 Qodo를 작은 코드 섹션(예: 독립적인 순수 함수)에 적용할 경우 유용한 제안을 얻을 수 있습니다. ‘/improve’ 명령어는 코드 개선 제안을 통해 미처 발견하지 못한 성능 개선 기회를 제시해 줍니다. 이 기능은 독립적인 순수 함수와 같은 작은 코드 섹션에 적용할 때 특히 효과적이며, 각 제안을 검토해 필요하다고 판단되는 항목을 선택적으로 적용할 수 있어 개선의 효율성을 극대화합니다. 또한 이 과정에서 자동으로 생성되는 docstring을 통해 코드 문서화가 가능해, 코드의 가독성과 유지 보수성을 한층 높여줍니다.
2. Kotaemon
다음으로는 Kotaemon이 어떻게 작동하는지 알아보기 위해 새 프로젝트의 요약 파일을 하나 업로드하고 그 내용을 분석해보겠습니다.
문서의 핵심 개념을 정확하게 포착한 답변을 생성했으며, 특히 인터페이스 오른쪽에 정보 출처를 강조 표시하는 기능이 돋보였습니다.
이번에는 코드가 포함된 파일을 다운로드 해보겠습니다. 복잡하게 생각하지 않고Kotaemon의 설치 스크립트를 가져와, 확장자를 .sh에서 .txt로 변경할 것입니다. (현재 Kotaemon은 일반 텍스트 형식만 지원합니다.)
결과는 만족스러웠습니다. 평소에 Bash 스크립트를 작성하는 일이 많지 않아 이러한 스크립트를 읽는 것이 가끔은 어렵게 느껴지는데, 텍스트 형식으로 변환된 형태로 보니 훨씬 쉽게 다가왔습니다. 마지막 예시로, Qodo에서 주석이 포함된 여러 파일을 선택해, 이들 파일에서 필요한 정보를 한 번에 검색해보려 합니다.
오래된 테스트 과제에서 몇 개의 파일을 가져와 “이 코드에 자세히 주석 달기” 명령을 사용한 후, Kotaemon에 업로드했습니다. 이제 Kotaemon이 이 코드에 대해 어떤 정보를 제공할 수 있는지 확인해보겠습니다.
Kotaemon은 코드의 기본 개념을 명확하고 체계적으로 설명해 주어, 코드의 구조와 핵심 내용을 쉽게 파악할 수 있게 했습니다. 특히 여러 파일을 문맥에 포함하여 함께 분석할 수 있다는 점은 매우 유용했습니다. 이는 복잡한 코드베이스에서 여러 모듈 간의 상호작용을 이해하고 오류를 탐지하거나 성능 개선점을 파악하는 데 큰 도움이 될 것입니다.
이번 데모는 Qodo와 Kotaemon의 실제 활용 가능성을 검토하고, 각 도구가 제공하는 기능의 강점을 확인하는 데 중점을 두었습니다. 두 도구는 코드 주석 작성, 파일 관리, FAQ 생성 등을 지원해 각각 유용성을 발휘하지만, 통합 사용에는 다소 한계가 있었습니다. 이러한 한계를 극복하려면 별도의 자동화 서비스(예를 들어 수동 주석 작성, 파일 업로드, FAQ 생성 파이프라인)를 구축하는 것이 효과적일 수 있습니다.
특히 Qodo와 Kotaemon은 대규모 코드베이스 및 문서 관리가 필요한 프로젝트에서 업무 효율성을 크게 향상시킬 잠재력을 지니고 있습니다. 향후 이 도구들이 더욱 발전한다면 개발팀과 문서 관리팀 간의 협업이 더욱 원활해지고, 기존 문서화 프로세스의 비효율성이 개선될 것으로 기대됩니다.
Qodo와 Kotaemon의 발전 가능성에 관심 있는 전문가들에게 유용한 통찰을 제공할 수 있기를 바라며, 끝까지 읽어 주셔서 감사합니다.
