AI 기반 데브옵스 문서 자동화 - 소프트웨어 개발 위한 기술 문서 혁신

이 글은 IDG의 아티클을 전재하여 제공합니다.
[원문보기]

핵심 인사이트

• 시간 절약 및 효율성 증대: 생성형 AI를 활용하여 기술 문서 작성 시간을 획기적으로 단축하고, 개발자들이 핵심 업무에 집중할 수 있도록 지원합니다.
• 정확하고 최신 정보 유지: AI 기반 자동화는 문서의 일관성을 유지하고, 코드 변경 사항을 즉시 반영하여 항상 최신의 정확한 정보를 제공합니다. 오류 감소 및 유지보수 비용 절감 효과를 누릴 수 있습니다.
• 데브옵스 문화 강화: 자동화된 문서화 시스템은 개발, 운영, 보안 팀 간의 협업을 촉진하고, 지식 공유를 활성화하여 데브옵스 문화를 더욱 강화합니다. 투명하고 효율적인 협업 환경을 구축할 수 있습니다.

생성형 AI 도구는 ‘기술 문서 작성과 활용’이라는 오래된 과제에 새로운 변화를 불러오고 있습니다. 핵심은 문서의 대상 독자와 목적을 명확히 이해하고, 그에 맞는 도구를 선택해 활용하는 것입니다.

데브옵스팀은 기술 문서를 작성하고 활용하는 일에 복잡한 감정을 갖고 있습니다. 개발자는 문서화되지 않은 코드를 읽거나 유지보수하는 일을 싫어합니다. 아키텍처 다이어그램은 멋진 이야기를 들려줄 수 있지만, 실제 구현된 구조와 비교하면 상당 부분이 ‘허구’에 가깝습니다. 심지어 사고, 요청, 변경관리를 다루는 IT 서비스 관리(IT service management, ITSM) 절차조차도 문서에 명시된 대로 지켜지는 경우는 드뭅니다.

CIO, CTO 등 디지털 리더들은 문서화를 강조하지만, 프로젝트 예산에는 기술 문서 담당자가 포함되는 경우가 거의 없습니다. 애자일팀 역시 코드 수준의 주석이나 README 파일 같은 기본적인 문서 외에는 작성할 시간이 부족합니다.

제품 책임자가 애자일 사용자 스토리를 통해 요구사항을 기록하더라도, 애플리케이션의 비즈니스 규칙, 사용자 여정 맵, 아키텍처, API, 표준 운영 절차(SOP)를 담은 문서는 대체로 불완전하거나 최신 상태가 아닙니다.

필자는 이전에 생성형 AI를 활용해 요구사항과 애자일 사용자 스토리를 작성하는 방법에 대해 다룬 적이 있습니다. 이번에는 한 단계 더 나아가 “개발자, 엔지니어, 아키텍트는 생성형 AI 도구를 어떻게 활용해 정확한 기술 문서를 작성하고 유지할 수 있을까?”라는 질문을 던집니다.

데브옵스와 ITSM 문서화에 생성형 AI 활용하기

몇 년 전, 한 개발팀은 문서가 ‘무의미하다’고 단언했습니다. 이들은 명명 규칙을 따르고, 단위 테스트와 예외 처리가 잘 되어 있으며 코드 커버리지가 높은 ‘좋은 코드’ 자체가 최고의 문서라고 주장했습니다. 또한 새로운 기능 개발 시간을 줄이면서까지 기존 기능을 문서화하더라도, 다음 배포 시점에 코드가 바뀌면 문서가 금세 쓸모없어질 것이라고 했습니다.

하지만 찬성하는 쪽의 시각은 다릅니다. 생성형 AI 도구를 활용하면 데브옵스팀이 코드 변경 및 배포 속도에 맞춰 문서를 자동으로 갱신할 수 있다는 것입니다.

사용자 경험 분석 솔루션 업체 Pendo의 CTO Erik Troan은 “생성형 AI는 소프트웨어 문서를 정적인 참고자료에서 제품 경험의 일부로 통합된 동적인 계층으로 바꾸고 있다. 사용자 흐름을 포착하고 문맥에 맞는 가이드를 자동 생성함으로써 문서가 소프트웨어와 함께 실시간으로 진화해 마찰을 줄이고 사용자 효율성을 높이고 있다”고 설명했습니다.

디지털 컨설팅 기업 Bridgenext의 CTO Dominick은 “AI가 생성하는 지식은 머지않아 기존 문서를 완전히 대체할 것”이라고 내다봤습니다. Dominick은 “생성형 AI가 발전하면 수십 년간 리더들이 원하고 개발자들이 기피해온 문서 자체가 사라질 것이며, 대규모 언어 모델(LLM)은 질문이나 채팅, 프롬프트에 즉시 대응해 코드베이스, 산업 표준, 문서, 지원 티켓, 시스템 로그 등에서 필요한 정보를 실시간으로 생성하게 될 것”이라고 했습니다.

미래의 형태가 어떻든, 이미 생성형 AI는 데브옵스팀이 문서화 요구사항을 더 효율적으로 충족하도록 돕고 있습니다. 또한 AI 에이전트와 다양한 생성형 AI 개발 도구가 확산되면서, 문서화에 투자해야 할 새로운 이유도 생겨나고 있습니다.

문서의 대상 독자 정의하기

문서화에 투자하기 전 가장 먼저 해야 할 일은 대상 독자와 그들이 문서를 어떻게 활용할지를 명확히 정의하는 것입니다. 이는 ‘충분히 좋은’ 문서와 ‘최신 상태’ 문서의 기준이 됩니다. 데브옵스팀이 고려해야 할 주요 독자층과 그들의 요구사항은 다음과 같습니다.

• 새로 합류한 개발자는 아키텍처, 데브옵스 필수 요구사항, 소프트웨어 개발 프로세스, 코드의 전반적 구조를 이해할 수 있는 문서를 필요로 합니다. 이를 통해 빠르게 업무에 적응하고, 조직의 표준에 맞는 결과물을 낼 수 있습니다.
• 외부 개발팀은 API 문서, Git 저장소의 README 파일, 데이터 카탈로그 내 데이터 정의, 로그 파일 및 관측 관련 아티팩트에 대한 가이드를 검토하고자 합니다.
• 아키텍트, 보안 전문가, 사이트 신뢰성 엔지니어(SRE)는 애플리케이션 현대화나 기술 부채 해소 방안을 제안할 때 문서를 필요로 합니다. 또한 사고 대응 및 근본 원인 분석을 수행할 때도 관련 문서가 필수적입니다.
• 데이터 과학자, 데이터 거버넌스 전문가, 데이터 엔지니어 등 데이터 파이프라인을 다루는 인력은 API와 애플리케이션이 생성한 데이터를 활용해 보고서, 데이터 시각화, 분석, AI 모델을 개발합니다. 이들은 최신 데이터 카탈로그와 데이터 리니지(data lineage)를 참고해 데이터 기반 의사결정을 내립니다.
• 제품 관리자, 제품 책임자, 변화 관리 리더, 주제 전문가(SME)는 “시스템이 어떻게 작동하는가”를 알고자 합니다. 코드를 직접 살펴보는 것은 원하지 않지만, 릴리스 노트에 담긴 정보보다 더 구체적인 내용을 필요로 합니다.
• ISO 27001, ISO 9001, SSDF, CMMI, SOC 2 등 규정 준수 표준의 감사 담당자는 반드시 검토해야 할 문서가 필요합니다.
• 생성형 AI 코딩 어시스턴트와 AI 에이전트 또한 문서를 학습 데이터로 활용해 정확성과 적합성을 높입니다.

생성형 AI 도구를 활용한 기술 문서 작성 방법

각기 다른 독자층은 서로 다른 문서 요구사항을 갖고 있습니다. 그렇다면 생성형 AI 도구를 어떻게 활용하면 이들의 다양한 필요를 충족할 수 있을까요?

기능 작동 방식 문서화

컨설팅 업체 SADA의 CTO Miles Ward는 “구글 클라우드의 API 문서는 코드로 작성돼 있으며, 수만 건에 달하는 API 문서를 최신 상태로 유지하는 유일한 방법은 자동화뿐이라는 사실을 증명했다”고 했습니다. Ward는 “우리 팀은 기술 문서를 NotebookLM에 통합했고, 기능 간 상호작용의 세부 내용을 평이한 영어로 설명해주는 팟캐스트 형태로 받아볼 수 있다”며 “Gemini, NotebookLM, Mariner 같은 신기술 덕분에 기술 문서가 더 이상 부담이 아닌 자산이 되고 있다”고 설명했습니다.

기능이 어떻게 작동하는지를 문서화하기 위해 다음과 같은 항목을 작성하고 유지하는 것이 좋습니다.

• 요구사항과 사용자 관점이 포함된 기능 명세서
• 아키텍처, 의존성, 테스트, 보안, 설정, 배포를 포함한 간략한 기술 설계 문서
• 애자일 사용자 스토리 및 IT 서비스 관리(ITSM) 티켓 참조 링크

이와 같은 기능 수준 문서화에는 Microsoft Teams, Atlassian Confluence, Google Workspace, Notion, MediaWiki 등의 도구가 유용합니다.

API, 데이터 사전, 데이터 파이프라인 문서화

글로벌 기술 서비스 및 인재 솔루션 기업 TEKsystems의 기술 현대화 담당 이사 Armando Franco는 “생성형 AI가 문서를 사후 작업이 아닌 개발 과정의 자연스러운 산출물로 바꾸고 있다. 예를 들어 팀이 마이크로서비스를 구축할 때 AI가 자동으로 오픈API 명세를 생성·유지해 엔드포인트, 페이로드, 인증 방식을 정확히 반영한다”고 했습니다. 이어 “데이터 팀의 경우 AI가 SQL 코드와 ETL 파이프라인에서 직접 데이터 리니지 다이어그램과 데이터 카탈로그를 생성해 환경 간 일관성을 보장할 수 있다”고 덧붙였습니다.

데브옵스팀은 기술 문서의 주요 독자가 자신들이 아니라는 점을 명심해야 합니다. 프로젝트에 새로 합류하거나 기존 개발팀의 업무를 이어받는 개발자, 그리고 API나 외부 연계 기능을 사용하는 외부 개발자가 핵심 독자층입니다.

문서 유형별로 적합한 도구는 다음과 같습니다.

• 데이터 사전을 문서화하기에 가장 적합한 도구는 Alation, Atlan, Ataccama, AWS Glue Data Catalog, Azure Data Catalog, Collibra, Data.world, Erwin Data Catalog, Google Dataplex Universal Catalog, Informatica Enterprise Data Catalog, Secoda 등입니다.
• 데이터 파이프라인이나 데이터 통합 플랫폼을 사용하는 데이터옵스팀은 시각적 설계 도구를 통해 데이터 흐름 및 리니지 다이어그램을 제작할 수 있습니다.
• API 문서화에는 Postman, Redocly, Swagger, Stoplight 등이 활용되고 있습니다.

런타임 및 표준 운영 절차(SOP) 문서화

클라우드 인프라 업체 Vultr의 CMO Kevin Cochrane은 “전통적인 문서화 방식은 오늘날 AI 기반 클라우드 시스템의 실시간·동적 특성을 따라가지 못하고 있다. CTO들은 이제 생성형 AI 도구를 활용해 로그, 설정, 런타임 데이터를 기반으로 시스템과 함께 진화하는 ‘살아 있는 문서’를 만들고 있다”고 했습니다. “이 접근법은 문서를 단순한 기록이 아닌 ‘연속성 도구’로 바꾸어, 팀 간 공통 맥락을 유지하고 단일 실패 지점을 줄이며 시스템 전반의 운영 단절을 방지한다”고 설명했습니다.

데브옵스 모범 사례는 주로 워크플로, 도구, 설정에 집중하지만, 개발과 운영 간 인수인계 문서를 어떻게 구성할지는 팀의 재량에 맡겨진 경우가 많습니다. 이러한 공백을 메우기 위한 도구는 다음과 같습니다.

• 운영 지식베이스 및 표준 운영 절차 작성을 위한 도구: Atlassian Jira Service Manager, Freshservice Knowledge Base, ServiceNow Knowledge Management, Zendesk Guide
• AI 기반 로그 분석 도구: Datadog, Dynatrace, LogicMonitor, Logz.io, New Relic, Splunk, Sumo Logic
• 클라우드 인프라 시각화 도구: Cloudcraft, Hava, Lucidscale
• 아키텍처, 시퀀스, 워크플로 다이어그램 도구: Draw.io, Figma, Eraser, Lucidchart, Miro, Visio

AI 에이전트를 위한 문서 제공

많은 코드 생성형 AI 에이전트가 코드베이스를 분석하지만, 점점 더 많은 도구들이 소프트웨어 문서를 함께 분석해 맥락을 보완하고 있습니다.

AI 코딩 에이전트 플랫폼 업체 Zencoder의 CEO 겸 설립자 Andrew Filev는 “모든 코드 변경이 문서화되면 AI는 코드가 ‘무엇을 하는가’뿐만 아니라 ‘왜 그렇게 작성됐는가’를 이해할 수 있다”며 “이러한 맥락적 지식은 AI를 단순한 코딩 보조 도구에서 진정한 팀 구성원으로 발전시킨다”고 했습니다. “이전에는 개발자의 머릿속이나 슬랙 대화 속에 흩어져 있던 조직적 지식이 검색 가능하고 실행 가능한 지능형 자산으로 변하며, 모든 AI 상호작용의 품질을 향상시킨다”고 설명했습니다.

데브옵스팀은 AI 코드 생성기에게 API 문서, 승인 기준이 포함된 사용자 스토리, 코딩 표준, 아키텍처 원칙, README 파일, 보안 코딩 가이드라인, 데이터 개인정보 보호 규정, 컴플라이언스 참조자료 등을 학습 데이터로 제공하는 방안을 고려해야 합니다.

Filev는 “LLM은 세부 문서가 있을 때 세 배 더 정확하게 작동한다. 이 방식을 도입한 팀들은 6개월 후 AI가 자체 코드베이스의 패턴과 규칙을 훨씬 더 효과적으로 이해하게 됐다고 보고했다”고 했습니다.

레거시 애플리케이션 문서화

문서가 존재하지 않는 애플리케이션을 다루는 것도 생성형 AI의 주요 활용 사례 중 하나입니다. 특히 원래 개발자가 회사를 떠난 경우, 시스템의 작동 방식과 의도를 파악하기 어려운 상황이 자주 발생합니다.

데브옵스 플랫폼 업체 Copado의 COO Sanjay Gidwani는 기존 시스템 문서화를 훨씬 수월하게 만들어주는 세 가지 핵심 AI 역량을 다음과 같이 설명했습니다.

• 생성형 AI는 방대한 양의 자료를 요약하는 데 뛰어나며, 기존 소스 코드를 읽고 그 의도를 간결하게 정리할 수 있습니다.
• 많은 비즈니스 애플리케이션 시스템이 설정 메타데이터에 의존하는데, 메타데이터 인식 기능을 갖춘 AI는 이러한 설정 정보를 분석하고 자동으로 문서화할 수 있습니다.
• AI는 데이터를 분석해 실제 사용 중인 프로세스를 파악하고, 각 단계의 소요 시간과 참여자의 역할까지 식별할 수 있습니다.

문서화되지 않은 시스템은 문제를 일으킬 가능성이 높고, 경우에 따라 컴플라이언스 위반으로 이어질 수 있습니다. 하지만 반대로 지나치게 장황한 문서를 작성하는 것도 또 다른 부담이 됩니다. 아무리 생성형 AI의 도움을 받더라도 장문 형태의 문서는 사람이 읽기 어렵고 유지 비용도 높습니다.

매우 효과적인 접근 방식은 ‘독자를 염두에 둔 적정 수준의 문서화’입니다. 모든 문서는 검토 대상자와, 해당 문서를 학습해 질의응답에 활용할 LLM을 위한 용도로 작성되어야 합니다.

FAQ

▶   해당 콘텐츠는 저작권법에 의하여 보호받는 저작물로 기고자에게 저작권이 있습니다.
▶   해당 콘텐츠는 사전 동의 없이 2차 가공 및 영리적인 이용을 금하고 있습니다.