생성형 AI 도구가 기술 문서 작성과 활용이라는 오래된 과제에 새로운 변화를 불러오고 있다. 핵심은 문서의 대상 독자와 목적을 명확히 이해하고, 그에 맞는 도구를 선택해 활용하는 것이다.
데브옵스팀은 기술 문서를 작성하고 활용하는 일에 복잡한 감정을 갖고 있다. 개발자는 문서화되지 않은 코드를 읽거나 유지보수하는 일을 싫어한다. 아키텍처 다이어그램은 멋진 이야기를 들려줄 수 있지만, 실제 구현된 구조와 비교하면 상당 부분이 ‘허구’에 가깝다. 심지어 사고, 요청, 변경관리를 다루는 IT 서비스 관리(IT service management, ITSM) 절차조차도 문서에 명시된 대로 지켜지는 경우는 드물다.
CIO, CTO 등 디지털 리더들은 문서화를 강조하지만, 프로젝트 예산에는 기술 문서 담당자가 포함되는 경우가 거의 없다. 애자일팀 역시 코드 수준의 주석이나 README 파일 같은 기본적인 문서 외에는 작성할 시간이 부족하다.
제품 책임자가 애자일 사용자 스토리를 통해 요구사항을 기록하더라도, 애플리케이션의 비즈니스 규칙, 사용자 여정 맵, 아키텍처, API, 표준 운영 절차(SOP)를 담은 문서는 대체로 불완전하거나 최신 상태가 아니다.
이전에 필자는 생성형 AI를 활용해 요구사항과 애자일 사용자 스토리를 작성하는 방법에 대해 다룬 적이 있다. 이번에는 한 단계 더 나아가 “개발자, 엔지니어, 아키텍트는 생성형 AI 도구를 어떻게 활용해 정확한 기술 문서를 작성하고 유지할 수 있을까?”라는 질문을 던진다.
데브옵스와 ITSM 문서화에 생성형 AI 활용하기
몇 년 전, 필자가 함께 일한 한 개발팀은 문서가 ‘무의미하다’고 단언했다. 이들은 명명 규칙을 따르고, 단위 테스트와 예외 처리가 잘 되어 있으며 코드 커버리지가 높은 ‘좋은 코드’ 자체가 최고의 문서라고 주장했다. 또한 새로운 기능 개발 시간을 줄이면서까지 기존 기능을 문서화하더라도, 다음 배포 시점에 코드가 바뀌면 문서가 금세 쓸모없어질 것이라고 말했다.
하지만 찬성하는 쪽의 시각은 다르다. 생성형 AI 도구를 활용하면 데브옵스팀이 코드 변경 및 배포 속도에 맞춰 문서를 자동으로 갱신할 수 있다는 것이다.
사용자 경험 분석 솔루션 업체 펜도(Pendo)의 CTO 에릭 트로안은 “생성형 AI는 소프트웨어 문서를 정적인 참고자료에서 제품 경험의 일부로 통합된 동적인 계층으로 바꾸고 있다”라며 “사용자 흐름을 포착하고 문맥에 맞는 가이드를 자동 생성함으로써 문서가 소프트웨어와 함께 실시간으로 진화해 마찰을 줄이고 사용자 효율성을 높이고 있다”라고 설명했다.
디지털 컨설팅 기업 브리지넥스트(Bridgenext)의 CTO 도미닉 프로피코는 “AI가 생성하는 지식은 머지않아 기존 문서를 완전히 대체할 것”이라고 내다봤다. 그는 “생성형 AI가 발전하면 수십 년간 리더들이 원하고 개발자들이 기피해온 문서 자체가 사라질 것이며, 대규모 언어 모델(LLM)은 질문이나 채팅, 프롬프트에 즉시 대응해 코드베이스, 산업 표준, 문서, 지원 티켓, 시스템 로그 등에서 필요한 정보를 실시간으로 생성하게 될 것”이라고 말했다.
미래의 형태가 어떻든, 이미 생성형 AI는 데브옵스팀이 문서화 요구사항을 더 효율적으로 충족하도록 돕고 있다. 또한 AI 에이전트와 다양한 생성형 AI 개발 도구가 확산되면서, 문서화에 투자해야 할 새로운 이유도 생겨나고 있다.
문서의 대상 독자 정의하기
문서화에 투자하기 전에 가장 먼저 해야 할 일은 대상 독자와 그들이 문서를 어떻게 활용할지를 명확히 정의하는 것이다. 이는 ‘충분히 좋은’ 문서와 ‘최신 상태’ 문서의 기준이 된다. 데브옵스팀이 고려해야 할 주요 독자층과 그들의 요구사항은 다음과 같다.
• 새로 합류한 개발자는 아키텍처, 데브옵스 필수 요구사항, 소프트웨어 개발 프로세스, 코드의 전반적 구조를 이해할 수 있는 문서를 필요로 한다. 이를 통해 빠르게 업무에 적응하고, 조직의 표준에 맞는 결과물을 낼 수 있다.
• 외부 개발팀은 API 문서, Git 저장소의 README 파일, 데이터 카탈로그 내 데이터 정의, 로그 파일 및 관측 관련 아티팩트에 대한 가이드를 검토하고자 한다.
• 아키텍트, 보안 전문가, 사이트 신뢰성 엔지니어(SRE)는 애플리케이션 현대화나 기술 부채 해소 방안을 제안할 때 문서를 필요로 한다. 또한 사고 대응 및 근본 원인 분석을 수행할 때도 관련 문서가 필수적이다.
• 데이터 과학자, 데이터 거버넌스 전문가, 데이터 엔지니어 등 데이터 파이프라인을 다루는 인력은 API와 애플리케이션이 생성한 데이터를 활용해 보고서, 데이터 시각화, 분석, AI 모델을 개발한다. 이들은 최신 데이터 카탈로그와 데이터 계보(lineage)를 참고해 데이터 기반 의사결정을 내린다.
• 제품 관리자, 제품 책임자, 변화 관리 리더, 주제 전문가(SME)는 “시스템이 어떻게 작동하는가”를 알고자 한다. 코드를 직접 살펴보는 것은 원하지 않지만, 릴리스 노트에 담긴 정보보다 더 구체적인 내용을 필요로 한다.
• ISO 27001, ISO 9001, SSDF, CMMI, SOC 2 등 규정 준수 표준의 감사 담당자는 반드시 검토해야 할 문서가 필요하다.
• 생성형 AI 코딩 어시스턴트와 AI 에이전트 또한 문서를 학습 데이터로 활용해 정확성과 적합성을 높인다.
생성형 AI 도구를 활용한 기술 문서 작성 방법
각기 다른 독자층은 서로 다른 문서 요구사항을 갖고 있다. 그렇다면 생성형 AI 도구를 어떻게 활용하면 이들의 다양한 필요를 충족할 수 있을까?
기능 작동 방식 문서화
컨설팅 업체 SADA의 CTO 마일스 워드는 “구글 클라우드의 API 문서는 코드로 작성돼 있으며, 수만 건에 달하는 API 문서를 최신 상태로 유지하는 유일한 방법은 자동화뿐이라는 사실을 증명했다”고 말했다. 그는 “우리 팀은 기술 문서를 노트북LM에 통합했고, 이제 나는 기능 간 상호작용의 세부 내용을 평이한 영어로 설명해주는 팟캐스트 형태로 받아볼 수 있다”며 “제미나이, 노트북LM, 마리너 같은 신기술 덕분에 기술 문서가 더 이상 부담이 아닌 자산이 되고 있다”고 설명했다.
기능이 어떻게 작동하는지를 문서화하기 위해 다음과 같은 항목을 작성하고 유지하는 것이 좋다.
• 요구사항과 사용자 관점이 포함된 기능 명세서
• 아키텍처, 의존성, 테스트, 보안, 설정, 배포를 포함한 간략한 기술 설계 문서
• 애자일 사용자 스토리 및 IT 서비스 관리(ITSM) 티켓 참조 링크
이와 같은 기능 수준 문서화에는 마이크로소프트 팀즈, 아틀라시안 컨플루언스, 구글 워크스페이스, 노션, 미디어위키(MediaWiki) 등의 도구가 유용하다.
API, 데이터 사전, 데이터 파이프라인 문서화
글로벌 기술 서비스 및 인재 솔루션 기업 테크시스템즈(TEKsystems)의 기술 현대화 담당 이사 아르만도 프랑코는 “생성형 AI가 문서를 사후 작업이 아닌 개발 과정의 자연스러운 산출물로 바꾸고 있다”며 “예를 들어 팀이 마이크로서비스를 구축할 때 AI가 자동으로 오픈API 명세를 생성·유지해 엔드포인트, 페이로드, 인증 방식을 정확히 반영한다”고 말했다. 이어 “데이터 팀의 경우 AI가 SQL 코드와 ETL 파이프라인에서 직접 데이터 라인리지 다이어그램과 데이터 카탈로그를 생성해 환경 간 일관성을 보장할 수 있다”고 덧붙였다.
데브옵스팀은 기술 문서의 주요 독자가 자신들이 아니라는 점을 명심해야 한다. 프로젝트에 새로 합류하거나 기존 개발팀의 업무를 이어받는 개발자, 그리고 API나 외부 연계 기능을 사용하는 외부 개발자가 핵심 독자층이다.
문서 유형별로 적합한 도구는 다음과 같다.
• 데이터 사전을 문서화하기에 가장 적합한 도구는 알레이션(Alation), 애틀랜(Atlan), 아타카마(Ataccama), AWS 글루 데이터 카탈로그, 애저 데이터 카탈로그, 콜리브라(Collibra), 데이터월드(Data.world), 어윈 데이터 카탈로그(Erwin Data Catalog), 구글 데이터플렉스 유니버설 카탈로그, 인포매티카 엔터프라이즈 데이터 카탈로그(, 세코다(Secoda) 등이다.
• 데이터 파이프라인이나 데이터 통합 플랫폼을 사용하는 데이터옵스팀은 시각적 설계 도구를 통해 데이터 흐름 및 라인리지 다이어그램을 제작할 수 있다.
• API 문서화에는 포스트맨(Postman), 리독클리(Redocly), 스웨거(Swagger), 스톱라이트(Stoplight) 등이 널리 활용된다.
런타임 및 표준 운영 절차(SOP) 문서화
클라우드 인프라 업체 벌트(Vultr)의 CMO 케빈 코크레인은 “전통적인 문서화 방식은 오늘날 AI 기반 클라우드 시스템의 실시간·동적 특성을 따라가지 못하고 있다”라며 “CTO들은 이제 생성형 AI 도구를 활용해 로그, 설정, 런타임 데이터를 기반으로 시스템과 함께 진화하는 ‘살아 있는 문서’를 만들고 있다”고 말했다. 그는 “이 접근법은 문서를 단순한 기록이 아닌 ‘연속성 도구’로 바꾸어, 팀 간 공통 맥락을 유지하고 단일 실패 지점을 줄이며 시스템 전반의 운영 단절을 방지한다”라고 설명했다.
데브옵스 모범 사례는 주로 워크플로, 도구, 설정에 집중하지만, 개발과 운영 간 인수인계 문서를 어떻게 구성할지는 팀의 재량에 맡겨진 경우가 많다. 이러한 공백을 메우기 위한 도구는 다음과 같다.
• 운영 지식베이스 및 표준 운영 절차 작성을 위한 도구: 아틀라시안 지라 서비스 매니저, 프레시서비스(Freshservice) 지식베이스, 서비스나우 지식관리, 젠데스크 가이드
• AI 기반 로그 분석 도구: 데이터독, 다이나트레이스, 로직모니터(LogicMonitor), 로그즈아이오(Logz.io), 뉴렐릭, 스플렁크, 수모로직
• 클라우드 인프라 시각화 도구: 클라우드크래프트(Cloudcraft), 하바(Hava), 루시드스케일(Lucidscale)
• 아키텍처, 시퀀스, 워크플로 다이어그램 도구: 드로우아이오(Draw.io), 피그마, 이레이저(Eraser), 루시드차트(Lucidchart), 미로(Miro), 비지오(Visio)
AI 에이전트를 위한 문서 제공
많은 코드 생성형 AI 에이전트가 코드베이스를 분석하지만, 점점 더 많은 도구들이 소프트웨어 문서를 함께 분석해 맥락을 보완하고 있다.
AI 코딩 에이전트 플랫폼 업체 젠코더(Zencoder)의 CEO 겸 설립자 앤드루 파일레프는 “모든 코드 변경이 문서화되면 AI는 코드가 ‘무엇을 하는가’뿐만 아니라 ‘왜 그렇게 작성됐는가’를 이해할 수 있다”라며 “이러한 맥락적 지식은 AI를 단순한 코딩 보조 도구에서 진정한 팀 구성원으로 발전시킨다”라고 말했다. 그는 또 “이전에는 개발자의 머릿속이나 슬랙 대화 속에 흩어져 있던 조직적 지식이 검색 가능하고 실행 가능한 지능형 자산으로 변하며, 모든 AI 상호작용의 품질을 향상시킨다”라고 설명했다.
데브옵스팀은 AI 코드 생성기에게 API 문서, 승인 기준이 포함된 사용자 스토리, 코딩 표준, 아키텍처 원칙, README 파일, 보안 코딩 가이드라인, 데이터 개인정보 보호 규정, 컴플라이언스 참조자료 등을 학습 데이터로 제공하는 방안을 고려해야 한다.
파일레프는 “LLM은 세부 문서가 있을 때 세 배 더 정확하게 작동한다”며 “이 방식을 도입한 팀들은 6개월 후 AI가 자체 코드베이스의 패턴과 규칙을 훨씬 더 효과적으로 이해하게 됐다고 보고했다”고 말했다.
레거시 애플리케이션 문서화
문서가 존재하지 않는 애플리케이션을 다루는 것도 생성형 AI의 주요 활용 사례 중 하나다. 특히 원래 개발자가 회사를 떠난 경우, 시스템의 작동 방식과 의도를 파악하기 어려운 상황이 자주 발생한다.
데브옵스 플랫폼 업체 코파도(Copado)의 COO 산제이 기드와니는 기존 시스템 문서화를 훨씬 수월하게 만들어주는 세 가지 핵심 AI 역량을 다음과 같이 설명했다.
• 생성형 AI는 방대한 양의 자료를 요약하는 데 뛰어나며, 기존 소스 코드를 읽고 그 의도를 간결하게 정리할 수 있다.
• 많은 비즈니스 애플리케이션 시스템이 설정 메타데이터에 의존하는데, 메타데이터 인식 기능을 갖춘 AI는 이러한 설정 정보를 분석하고 자동으로 문서화할 수 있다.
• AI는 데이터를 분석해 실제 사용 중인 프로세스를 파악하고, 각 단계의 소요 시간과 참여자의 역할까지 식별할 수 있다.
문서화되지 않은 시스템은 문제를 일으킬 가능성이 높고, 경우에 따라 컴플라이언스 위반으로 이어질 수 있다. 하지만 반대로 지나치게 장황한 문서를 작성하는 것도 또 다른 부담이 된다. 아무리 생성형 AI의 도움을 받더라도 장문 형태의 문서는 사람이 읽기 어렵고 유지 비용도 높다.
매우 효과적인 접근 방식은 ‘독자를 염두에 둔 적정 수준의 문서화’다. 모든 문서는 검토 대상자와, 해당 문서를 학습해 질의응답에 활용할 LLM을 위한 용도로 작성되어야 한다.
[email protected]
