CIAO - Code In Architecture Out - Automated Software Architecture Documentation with Large Language Models

1. 문제 정의 (Problem)

• 문서화 부재 및 불일치: 소프트웨어 아키텍처 문서화는 시스템 이해, 의사소통, 장기적 진화에 필수적이지만, 실제 산업 현장과 오픈소스 프로젝트에서는 문서가 없거나, 구식이거나, 구현 코드와 불일치하는 경우가 많습니다. 이로 인해 아키텍처 드리프트 (Architectural Drift) 와 기술 부채가 발생합니다.
• 기존 LLM 기술의 한계: 최근 LLM 기반 기술들은 코드에서 문서를 생성하는 데 사용되지만, 주로 API 설명, 코드 주석, 테스트 요약 등 국소적 (Local) 인 산출물에 집중합니다. 표준 (ISO/IEC/IEEE 42010 등) 에 부합하는 시스템 수준의 통합된 아키텍처 설명을 저장소 전체에서 직접 생성하는 접근법은 아직 충분히 탐구되지 않았습니다.

2. 방법론 (Methodology: CIAO)

CIAO 는 GitHub 저장소를 입력으로 받아 표준 기반의 아키텍처 문서를 출력하는 자동화 워크플로우입니다.

A. 표준 기반 템플릿 설계

문서 구조는 다음 세 가지 주요 표준과 모델을 기반으로 설계되었습니다:

1. ISO/IEC/IEEE 42010: 이해관계자의 관심사와 아키텍처 설명의 관계를 정의.
2. SEI Views & Beyond: 구조적, 행동적, 배포 관점의 분리.
3. C4 Model: 컨텍스트 (L1), 컨테이너 (L2), 컴포넌트 (L3), 코드 (L4) 의 4 단계 계층 구조.

생성되는 문서의 8 개 섹션:

1. System Overview: 시스템 목적, 범위, 주요 책임 요약.
2. Architectural Context: 외부 환경, 액터, API, 데이터 소스 (C4 Context).
3. Containers: 런타임 논리 조직, 애플리케이션 및 데이터 저장소 (C4 Container).
4. Components: 내부 논리 구조, 모듈, 패키지, 클래스 관계 (C4 Component).
5. Code-Level: 아키텍처 추상화와 구체적 구현 (소스 코드) 간의 매핑.
6. Cross-Cutting Concerns: 보안, 로깅, 설정 등 시스템 전반에 걸친 관심사.
7. Quality Attributes and Rationale: 성능, 유지보수성 등 품질 속성과 설계 결정의 근거.
8. Deployment: 배포 아티팩트 (Dockerfile 등), 실행 환경, 노드 관계.

B. CIAO 워크플로우

1. Repository Flattening: REPOMIX 도구를 사용하여 저장소의 소스 코드를 AI 가 처리하기 쉬운 단일 텍스트 파일로 변환합니다. (주석 제거, 비소스 파일 제외, 필수 설정 파일 유지).
2. Prompt Generation: 각 문서 섹션별로 고정된 글로벌 프롬프트와 섹션별 프롬프트를 생성하여 병렬로 준비합니다.
3. LLM-based Section Generation: 생성된 프롬프트를 LLM 에 입력하여 각 섹션의 내용을 생성합니다.
4. Documentation Assembly: 생성된 섹션들을 하나의 문서로 조립합니다.
5. Diagram Rendering: LLM 이 생성한 PlantUML 텍스트를 이미지로 렌더링하여 최종 문서에 삽입합니다.

C. 모델 선택 및 프롬프트 엔지니어링

• 모델 선택: GPT-5, Claude Sonnet 4.5, Gemini 2.5, Mistral Large 2 등을 비교 평가한 결과, GPT-5가 아키텍처 정확도, 용어 일관성, 할루시네이션 감소, 템플릿 준수 측면에서 가장 우수하여 기본 모델로 선정되었습니다.
• 프롬프트 전략: '세심한 소프트웨어 아키텍트 (Meticulous Software Architect)' 역할을 부여하고, 증거 기반 생성 (Evidence-grounded generation) 을 요구하며, 저장소에 없는 아키텍처 요소를 임의로 생성하지 않도록 지시하는 전략을 사용했습니다.

3. 주요 기여 (Key Contributions)

1. 표준 지향 템플릿: ISO/IEC/IEEE 42010, SEI, C4 모델을 통합한 시스템 수준 아키텍처 문서화 템플릿 제안.
2. 구조화된 LLM 워크플로우: GitHub 저장소에서 직접 아키텍처 문서를 생성하는 자동화 프로세스 정의.
3. 오픈소스 프로토타입: 제안된 워크플로우를 구현하여 즉시 사용 가능한 문서를 생성하는 도구 공개.
4. 실증적 평가: 22 명의 개발자를 대상으로 한 평가 연구를 통해 생성된 문서의 가치, 이해도, 정확도 및 한계를 검증.

4. 연구 결과 (Results)

22 명의 개발자 (연구자 및 산업계 개발자) 가 자신이 기여한 저장소에 대해 생성된 문서를 평가한 결과입니다.

• RQ1 (가치): 개발자들은 생성된 문서를 시스템 구조 이해에 유용하게 여겼으며, 많은 경우 프로젝트에 통합할 가치가 있다고 평가했습니다. 특히 아키텍처 다이어그램, 코드 레벨 상세 정보, 컴포넌트 뷰가 가장 높이 평가되었습니다.
• RQ2 (이해도): 문서의 명확성, 조직화, 용어 사용, 상세도가 전반적으로 긍정적으로 평가되었습니다. 고수준 아키텍처 섹션 (Context, Containers) 이 특히 이해하기 쉬웠습니다.
• RQ3 (정확성): 코드 기반 섹션 (Components, Containers, Code-Level) 은 높은 정확도를 보였습니다. 반면, 시스템 개요 (System Overview), 아키텍처 컨텍스트, 사용 사례 다이어그램과 같은 고수준 해석이 필요한 부분은 오해나 누락이 발생할 수 있어 정확도가 다소 낮았습니다.
• RQ4 (한계): 가장 큰 문제는 다이어그램의 품질이었습니다. 다이어그램이 불완전하거나, 잘못된 관계를 보여주거나, 시각적으로 부자연스러운 경우가 많았습니다. 또한 **배포 뷰 (Deployment View)**의 명확성 부족과 일부 정보 누락이 지적되었습니다.
• RQ5 (비용 및 시간):
  • 시간: 문서 생성에 평균 약 3 분 소요.
  • 비용: API 사용료 기준 평균 **약 $1.19** (최대$2.48).
  • 수동 문서화에 비해 시간과 비용 효율성이 매우 뛰어납니다.

5. 의의 및 결론 (Significance & Conclusion)

• 실용성: CIAO 는 표준에 기반한 체계적인 접근법을 통해 LLM 이 단순한 코드 설명을 넘어 시스템 수준의 아키텍처 문서를 생성할 수 있음을 입증했습니다.
• 경제성: 매우 짧은 시간과 낮은 비용으로 아키텍처 문서를 재생성할 수 있어, 문서가 부재하거나 구식인 레거시 시스템의 아키텍처 복원 (Architecture Recovery) 에 효과적인 솔루션이 될 수 있습니다.
• 향후 과제: 생성된 문서의 다이어그램 품질 향상이 가장 시급한 개선 사항입니다. 이를 위해 정적/동적 분석 도구를 LLM 과 결합하거나, 인간이 개입하는 피드백 루프 (Human-in-the-loop) 를 도입하여 정확도를 높이는 연구가 필요하다고 결론지었습니다.

이 연구는 소프트웨어 아키텍처 문서화의 자동화 가능성을 보여주며, 특히 오픈소스 및 기업 내부 프로젝트에서 아키텍처 드리프트를 방지하고 팀 온보딩을 지원하는 데 큰 잠재력을 가지고 있습니다.