From code to diagrams: Agentic architecture documentation with Amazon Bedrock AgentCore

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Amazon Bedrock AgentCore 기반 에이전트가 .NET 코드 분석부터 아키텍처 다이어그램 생성·검증·게시까지 자동화하고, CI/CD 및 자연어 검색과 연결하는 운영 사례를 소개한다.

📌 핵심 요약

• 글로벌 금융 중개 기업은 전자 거래 플랫폼의 아키텍처 문서를 유지하기 위해 이 파이프라인을 2026년 1분기부터 운영 환경에서 사용하고 있다.
• AWS CodeCommit의 main 브랜치에 코드를 푸시하면 AWS CodePipeline과 AWS CodeBuild가 소스를 준비하고 Amazon Bedrock AgentCore에서 실행되는 Strands 에이전트를 호출한다.
• 에이전트는 .NET 코드를 분석해 클래스·시퀀스·상태·컴포넌트·활동 다이어그램을 Mermaid로 생성하고, 문법 검증과 오류 수정을 거쳐 SVG와 메타데이터를 Amazon S3에 게시한다.
• 원문은 반복 검증과 자기 수정을 적용한 방식의 신뢰도를 95%, 단일 API 호출 방식의 신뢰도를 65%로 제시하지만 측정 조건은 설명하지 않는다.
• Amazon Bedrock Knowledge Bases는 다이어그램 설명과 Mermaid 소스 등을 Amazon Titan Text Embeddings v2로 임베딩하고 Amazon S3 벡터 저장소에 저장해 의미 검색과 자연어 질의를 지원한다.

🧩 주요 포인트

1. CI/CD와 문서 생성의 연결 → 코드 변경에 맞춰 문서를 갱신해 수작업 부담과 문서 노후화 문제에 대응한다.
2. Mermaid 문법 검증과 자기 수정 → 생성 오류를 반복적으로 교정하지만, 제시된 신뢰도 수치만으로 아키텍처의 의미적 정확성까지 확인할 수는 없다.
3. 다이어그램 설명·소스의 검색 자산화 → Amazon Bedrock Knowledge Bases를 통해 개발자와 이해관계자가 구조와 흐름을 자연어로 탐색할 수 있다.

🧠 상세 정리

1. 코드 변화 속도를 따라가지 못하는 문서

원문은 코드가 빠르게 바뀌는 개발 환경에서 아키텍처 문서를 최신 상태로 유지하기 어렵다는 문제로 시작하며, 개발팀이 여러 시간을 들여 만든 다이어그램도 배포 후 몇 주 안에 실제 구조와 어긋날 수 있다고 설명한다. UML이나 Mermaid로 복잡한 코드베이스를 수작업으로 표현하는 부담은 규모가 커질수록 지속하기 어려워지고, 문서 갱신이 늦어지면 의사결정의 근거로서 신뢰성도 떨어진다. 팀원이 떠날 때 암묵적인 지식이 함께 사라지면 레거시 시스템을 새로 이해하기 위해 코드를 역분석해야 하므로 신규 개발자의 적응도 느려진다. 보안 검토와 감사에는 최신 다이어그램이 필요하며, 특히 마이크로서비스에서는 서비스 의존성과 메시지 흐름의 이해가 연쇄 장애 예방과 연결되기 때문에 문서 공백의 영향이 커진다.

2. 금융 중개 기업의 자동 문서화 사례

소개된 해결책은 .NET 코드베이스를 분석하고 아키텍처 다이어그램을 생성하는 자율 에이전트를 기존 지속적 통합·지속적 전달 흐름에 통합하는 방식이다. 작성자는 주요 금융시장에서 금융 중개 업무를 수행하는 글로벌 금융 서비스 기업과 이 접근법을 개발하고 검증했으며, 해당 기업의 전자 거래 플랫폼에서 2026년 1분기부터 운영 중이라고 밝힌다. Amazon Bedrock AgentCore는 에이전트 실행을 담당하고, AWS CodePipeline은 코드 변경부터 문서 게시까지의 작업을 연결하며, Amazon Bedrock Knowledge Bases는 생성된 문서의 의미 검색을 제공한다. 이 구성은 다이어그램을 생성하는 데서 끝나지 않고 설명과 메타데이터까지 검색 대상으로 연결해 현재 아키텍처를 살펴볼 수 있도록 설계되어 있다.

3. 서비스별 역할과 코드 변경의 전달 경로

Amazon Bedrock AgentCore는 자율 문서화 에이전트를 위한 서버리스 실행 환경을 제공하며, 인프라를 직접 관리하지 않아도 에이전트 수명주기 관리와 자동 확장, 도구 오케스트레이션을 처리하도록 구성된다. AWS CodePipeline은 AWS CodeCommit의 main 브랜치에 대한 푸시를 계기로 전체 흐름을 시작하고, AWS CodeBuild는 의존성 설치와 에이전트 호출, 산출물 준비 같은 실행 단계를 맡는다. 구체적인 흐름에서는 AWS CodeBuild가 저장소에서 코드를 가져와 패키징한 뒤 Amazon S3의 소스 코드 버킷에 업로드하고, 호출에 필요한 정보를 준비해 AgentCore의 Strands 에이전트를 실행한다. 에이전트는 Amazon S3에서 소스를 가져오며, 생성된 SVG와 Mermaid 소스, JSON 설명 메타데이터는 별도의 아키텍처 다이어그램 버킷에 저장되어 이후 게시와 검색 수집의 입력이 된다.

4. 분석 대상의 우선순위와 구조 추출

코드 분석 단계는 모든 파일을 무차별적으로 처리하기보다 운영 코드를 우선하고 테스트 파일과 빌드 산출물, 자동 생성 코드를 제외해 처리 시간을 줄이고 다이어그램의 관련성을 높이는 방향으로 설명된다. 제시된 스캔 예시는 디렉터리를 순회하면서 bin, obj, packages, .git 폴더를 제외하고, 확장자가 .cs인 파일을 분석한 결과를 모은다. 분석 결과는 발견한 파일 수와 전체 요약, 개별 파일 분석을 담는 구조화된 데이터로 반환되며, 에이전트가 인터페이스와 추상 클래스, 구체 구현 및 의존성을 파악하는 근거가 된다. 다만 본문의 우선순위 설명과 달리 공개된 짧은 코드에는 테스트 파일이나 자동 생성 코드를 별도로 식별해 제외하는 조건이 나타나지 않아, 예시만으로 전체 제외 정책의 구현을 확인할 수는 없다.

5. AgentCore와 Strands를 통한 에이전트 실행

배포 예시는 BedrockAgentCoreApp으로 실행 진입점을 만들고, Amazon Bedrock의 모델을 사용하는 Strands 에이전트에 소스 가져오기와 코드 스캔, Mermaid 저장·검증, SVG 변환, 업로드 도구를 연결한다. 모델 식별자는 선택한 모델을 넣는 자리표시자로 제시되며, 예시 설정에는 미국 동부 리전과 온도 0.3, 최대 토큰 4096이 포함되므로 특정 모델을 운영 사례의 확정된 선택으로 볼 수는 없다. 진입점은 호출 데이터에서 소스 버킷과 객체 키, 프로젝트 이름 등을 읽고, 소스 수집부터 분석과 생성, 검증·변환, 업로드까지 수행하도록 지시하는 프롬프트를 구성한다. 에이전트는 응답을 비동기로 전달하면서 코드 분석 결과와 다이어그램 생성 상태에 따라 도구 사용을 결정하고, 검증 오류가 생기면 수정하는 방식으로 실행된다.

6. 다섯 단계의 반복 생성과 자기 수정

에이전트의 작업은 이해, 생성, 검증, 변환, 게시의 다섯 단계로 구성되며, 먼저 소스를 가져와 주요 컴포넌트와 인터페이스, 관계를 파악하는 것으로 시작한다. 이후 Amazon Bedrock에서 제공하는 기반 모델을 활용해 클래스·시퀀스·상태·컴포넌트·활동 다이어그램을 Mermaid 기반 표현으로 생성하고, 각 다이어그램의 문법을 검증한다. 오류가 발견되면 오류 메시지를 분석해 다이어그램을 다시 생성하며, 검증을 통과한 결과를 웹 브라우저에서 표시할 수 있는 SVG로 변환한 뒤 소스와 메타데이터를 함께 게시한다. 원문은 이 반복 방식의 신뢰도를 95%, 단일 API 호출의 신뢰도를 65%로 제시하고 자율적인 오류 교정을 이유로 들지만, 신뢰도의 정의나 표본 규모, 평가 조건은 제공하지 않는다.

7. 생성된 다이어그램의 의미 검색

Amazon Bedrock Knowledge Bases는 Amazon S3의 아키텍처 다이어그램 버킷에서 생성된 문서 자료를 수집해 검색과 설명 제공에 활용하며, 다이어그램 메타데이터와 Mermaid 소스, 설명이 주요 대상이다. 수집 과정에서는 Amazon Titan Text Embeddings v2로 벡터 임베딩을 만들고, 다이어그램 설명과 Mermaid 소스를 의미 있는 단위로 나누는 청킹을 적용한 뒤 결과를 Amazon S3 벡터 저장소에 보관한다. 이 구조는 전체 아키텍처 문서를 대상으로 의미 검색과 검색 증강 생성을 지원하므로, 사용자는 자연어로 관련 다이어그램과 맥락 설명을 찾을 수 있다. 원문은 재연결 활동 흐름이 어떻게 구성되는지 묻거나 인프라 컴포넌트의 클래스 다이어그램을 나열해 달라고 요청하는 예를 통해 개발자와 이해관계자의 탐색 방식을 보여준다.

8. 파이프라인 통합 예시와 제공 범위

마지막 부분은 AWS CodePipeline이 코드 커밋에서 문서 게시와 지식 기반 수집까지 연결한다는 설명에 이어, AWS CodeBuild에서 사용할 빌드 명세 예시를 제시한다. 환경 변수에는 소스와 문서, 벡터 저장소의 버킷 이름뿐 아니라 에이전트 식별자, 프로젝트 이름, 지식 기반과 데이터 소스 식별자, 실행 리전이 포함되어 각 구성요소를 연결하는 입력을 보여준다. 설치 단계에는 파이썬 3.11 실행 환경과 boto3 및 awscli 설치가 나타나지만, 제공된 원문은 사전 빌드 단계의 소스 패키징 주석 뒤 명령이 시작되는 부분에서 끊긴다. 따라서 전체 서비스 흐름과 에이전트의 처리 단계는 파악할 수 있으나, 이 자료만으로 뒤에 이어질 빌드 명령이나 배포·수집 호출의 완전한 구현을 확인할 수는 없다.

🧾 핵심 주장 / 시사점

• 문서 생성을 코드 변경 흐름에 통합하는 것이 핵심이며, 문서 노후화에 대응하는 수단은 생성 기능과 CI/CD 연결의 결합이다.
• 반복 검증은 생성 결과를 교정하는 장치이지만, Mermaid 문법 통과와 실제 코드 구조의 정확한 표현은 구분해 평가할 필요가 있다.
• 설명과 Mermaid 소스를 함께 검색 대상으로 삼으면 다이어그램이 단순한 이미지에서 구조와 흐름을 탐색하는 문서 자산으로 확장된다.

✅ 액션 아이템

• 2026년 1분기부터 운영 중인 사례를 바탕으로 .NET 코드 분석과 CI/CD 문서 생성 연결의 적용 가능성 검토.
• 신뢰도 95%와 65%의 측정 조건 및 Mermaid 문법 검증과 아키텍처의 의미적 정확성 간 평가 범위 확인.
• Amazon Bedrock Knowledge Bases를 통한 다이어그램 설명·소스의 자연어 탐색 활용 가능성 검토.

❓ 열린 질문

• 신뢰도 95%와 65%는 어떤 측정 조건과 성공 기준에 따라 산출되었는가?
• Mermaid 문법 검증과 별개로 생성된 다이어그램의 아키텍처 의미적 정확성은 어떻게 확인하는가?
• 2026년 1분기부터 운영한 CI/CD 문서 생성 연결은 수작업 부담과 문서 노후화를 얼마나 줄였는가?