평문(Plain English)으로 다이어그램, 비용, 런북을 생성하는 클라우드 아키텍처 도구를 만들었습니다 — 그 방법을 소개합니다

평문(Plain English)으로 다이어그램, 비용, 런북(runbooks)을 생성하는 클라우드 아키텍처 도구를 만들었습니다 — 그 방법을 소개합니다

내가 계속 마주쳤던 문제

클라우드 시스템을 설계하기 위해 앉을 때마다, 나는 결국 다음과 같은 과정을 반복했습니다:

1. 아키텍처 드로잉 도구(architecture drawing tool)를 연다
2. EC2 노드를 추가한다
3. 생각한다: EC2의 SLA(Service Level Agreement)가 뭐였더라?
4. 새 탭을 연다 → AWS 문서
5. 생각한다: 잠깐, 이걸 Fargate로 바꿔야 하나?
6. 또 다른 탭을 연다
7. 생각한다: Lambda의 동시성 제한(concurrency limits)이 얼마지?
8. 또 다른 탭을 연다
9. 생각한다: 중간 규모(medium scale)일 때 비용이 얼마나 들까?
10. 또 다른 탭을 연다

답을 얻었을 때쯤이면, 내가 무엇을 설계하고 있었는지에 대한 흐름을 놓쳐버리곤 했습니다.
문서에 파묻혀 있는 동안 다이어그램에는 상자 3개와 화살표 2개만 덩그러니 남아 있었습니다.

그러고 나서 디자인 리뷰(design review)에서 다이어그램을 공유하면, 첫 번째 질문은 항상 이랬습니다:
"RDS Multi-AZ의 SLA가 무엇인가요?" 다시 탭을 열어야 했죠.

이 과정이 지겨워졌습니다. 그래서 Potato를 만들었습니다.

Potato란 무엇인가

라이브 데모(Live demo) →
GitHub →

Potato는 무료 오픈 소스 클라우드 아키텍처 스튜디오(Cloud Architecture Studio)로, 모든 노드가 평소라면 10개의 탭을 열어서 찾아야 했을 질문들에 대한 답을 이미 알고 있습니다.

캔버스 위의 서비스에 마우스를 올리면 다음과 같은 정보를 얻을 수 있습니다:

• 기능 (What it does) — 마케팅 문구가 아닌, 명확하고 간결한 한 문장
• SLA — 정확한 가동 시간 약정 (99.9%? 99.95%? 99.99%? 생각보다 훨씬 다양합니다)
• 제한 사항 (Hard limits) — Lambda의 15분 실행 제한, DynamoDB의 400KB 항목 제한, API Gateway의 10MB 페이로드 최대치 등
• 일반적인 운영 환경의 함정 (Common production pitfalls) — 단순한 'Hello World' 수준이 아니라, 규모가 커질 때 팀을 곤경에 빠뜨리는 실수들
• 사용 시점 (및 사용하지 말아야 할 시점)
• 월간 예상 비용 (Monthly cost estimates) — 서비스별 소규모 / 중규모 / 대규모 워크로드 분류 및 다이어그램 전체 합계

52개의 AWS, Azure, GCP 서비스 문서화 완료. 클릭 한 번으로 불러올 수 있는 12개의 운영 환경용 AWS 템플릿 (VPC + ECS Fargate, 서버리스 API, 멀티 리전 액티브-액티브(multi-region active-active), 데이터 파이프라인 등) 제공.

계정 불필요. 로그인 불필요. 구독 불필요. 네트워크 의존성 제로.

AI 워크플로우 — 실제 작동 방식

사람들이 가장 많이 질문하는 부분입니다.

"AI 가져오기 (AI Import)" 기능은 스스로 AI API를 호출하지 않습니다. 대신, 여러분이 이미 사용 중인 LLM(Claude, ChatGPT, Gemini 등 무엇이든)에 붙여넣을 수 있는 프롬프트(Prompt)를 제공합니다. LLM이 구조화된 JSON 블록을 반환하면, 여러분은 그 JSON을 Potato에 붙여넣기만 하면 됩니다. 그러면 다이어그램이 스스로 구축됩니다.

Claude, ChatGPT, Gemini 전반에 걸쳐 신뢰할 수 있고 파싱 가능한(parseable) JSON을 반환하도록 이 프롬프트를 만드는 과정은 프로젝트 전체에서 가장 많은 반복 작업이 필요했습니다. 핵심 교훈은 다음과 같습니다:

1. 스키마의 구체성(Schema specificity)이 자연어 지시보다 강력합니다.
JSON 스키마가 구체적일수록 환각(hallucination) 현상으로 인한 잘못된 필드가 줄어듭니다. 만약 "아키텍처를 나타내는 JSON 객체를 반환해줘"라고 말한다면, 매번 다른 결과가 나올 것입니다. 하지만 타입이 지정된 예시와 함께 정확한 형태를 제공한다면, 일관된 출력을 얻을 수 있습니다.

2. "Act as" 프레이밍은 아키텍처 결정의 품질을 변화시킵니다.
LLM에게 단순히 "이 시스템을 설계해줘"라고 요청하는 대신, 수석 솔루션 아키텍트 (Principal Solutions Architect)로서 행동하도록 요청하면 훨씬 더 나은 서비스 선택 결과를 얻을 수 있습니다. 예를 들어, 단일 인스턴스 대신 RDS Multi-AZ를 사용하고, NAT Gateway를 추가하며, 적절한 요소들을 프라이빗 서브넷 (private subnets)에 배치하게 됩니다.

3. LLM이 노드를 배치하게 하세요. 픽셀 단위로 완벽한 레이아웃을 요구하지 마세요.
JSON에는 x / y 좌표가 포함됩니다. 초기 버전에서는 LLM이 예쁜 레이아웃을 생성하도록 시도했습니다. 하지만 이는 결코 안정적으로 작동하지 않았습니다. 더 나은 접근 방식은 LLM으로부터 어떤 레이아웃이든 받아들인 다음, 자동 정렬 (auto-arrange)하거나 수동으로 드래그하는 것입니다. 중요한 것은 아키텍처 구조이지, 픽셀 위치가 아닙니다.

4. 붙여넣기 전이 아니라, 붙여넣은 후에 검증하세요.
프롬프트 중간에 JSON을 검증하려고 시도하는 대신, LLM이 반환하는 결과 그대로를 받아들인 후 가져오기 (import) 단계에서 검증하도록 했습니다. 알 수 없는 노드 유형은 일반적인 아이콘으로 대체됩니다. 누락된 필드는 기본값 (defaults)을 할당받습니다. 이를 통해 이 기능은 시스템이 중단되지 않으면서도 약간 불완전한 LLM 출력에 대해 관용적으로 대응할 수 있게 됩니다.

결과적으로: 평문 (plain English)으로 시스템을 설명하면, 약 15초 만에 20~40개의 노드가 포함된 연결된 다이어그램을 얻을 수 있습니다. 그런 다음 Play를 누르면 다이어그램이 단계별로 스스로 설명합니다.

향후 계획

추가하고 싶은 몇 가지 사항이 있습니다:

• Terraform / CDK 내보내기 (export) — 다이어그램으로부터 IaC 스텁 (stubs) 생성
• 더 많은 서비스 아이콘 — Kubernetes, Kafka, Snowflake, Databricks
• 차이 모드 (Diff mode) — 두 가지 아키텍처 버전을 시각적으로 비교
• 팀 공유 — 다이어그램 상태를 인코딩하는 가벼운 URL 기반 공유

GitHub에서 보기 →

직접 사용해 보신다면 여러분의 의견이 정말 궁금합니다. 특히 솔루션 아키텍트 (Solutions Architect)이시거나 DevOps 분야에서 근무하며 지식 베이스 (Knowledge Base)에 무엇이 부족한지에 대한 의견을 가지고 계신 분들이라면 더욱 그렇습니다.