이 해커톤이 뭔지부터 짧게 적어둔다. K-디지털 트레이닝(KDT)은 고용노동부가 국민내일배움카드로 훈련비를 지원해서, 미래 노동시장을 이끌 디지털·신기술 인재를 키우는 사업이다. 그 안에서 훈련생·수료생들이 실제 팀 프로젝트로 실력을 겨루고 서비스 개발 경험을 쌓아보라고 매년 여는 게 이 해커톤이고, 올해로 8회째다(주최 고용노동부, 주관 한국기술교육대학교 직업능력심사평가원). 팀은 3~6명으로 구성해야 하는데, 우리 춘배는 김경민·김다애·최현준으로 저번 공모전과 같은 인원으로 참여했다.

전체 300여 팀 중 멘토링을 받으며 기획서를 다듬는 팀이 60팀으로 추려지고, 그중 본선에 진출하는 30팀이 최종 확정되는데, 이 30팀은 본선에 오르는 순간 수상이 보장된다. 대상(국무총리상, 지정과제 1팀)이 1,000만 원, 아이디어상(직업능력심사평가원 원장상)이 30만 원, 30팀 전체 상금 규모는 총 6,080만 원이다. 우리는 자유과제로 참가했으니, 우리 쪽에서 노려볼 수 있는 제일 높은 등급은 최우수상(고용노동부 장관상, 500만 원)이였다.

문제의식: 피해자는 자신이 피해자인 줄 모른다

준비를 시작하며 가장 먼저 마주한 게 이 기사였다. 2024년 AI 얼굴합성물 피해 접수는 1,384건으로 전년(423건) 대비 227.2% 급증했고, 피해자의 92.6%가 10~20대, 96.6%가 여성이었다(중앙디지털성범죄피해자지원센터). 더 눈에 밟혔던 건 피해 유형 1위가 실제 유포가 아니라 '유포 불안'(전체의 25.9%)이었다는 사실이다. 수많은 사람이 "내 얼굴도 어딘가에서 합성되고 있지 않을까"라는 불안 속에 살고 있는데, 정작 그걸 확인할 방법이 개인에게는 없었다.

법과 제도는 이미 준비돼 있었다. 2024년 10월 성폭력처벌법 개정으로 제작·유포는 7년 이하 징역, 소지·시청도 처벌 대상이 됐고, 2026년 1월 AI기본법 시행으로 AI 합성물에는 AI 생성 표시 의무가 생겼다. 그런데 이걸 개인이 실제로 작동시킬 수단이 없었다. 서울시 AI 삭제 시스템이나 Reality Defender 같은 솔루션도 있었지만 전부 기업·기관 전용(B2B)이었다. 이 공백을 메우자는 게 딥소각의 출발점이었다.

신청서부터 킥오프까지

7월 8일에 참가 신청서와 서약서에 서명하면서 팀이 공식적으로 꾸려졌다. 정식 오리엔테이션(킥오프)은 7월 22일이었고, 계획은 6주 간트 차트로 짰다 —> 1주차 준비·설계, 2주차 예선·기반 구축, 34주차 핵심 기능 개발, 56주차 통합·테스트.

기술스택을 확정하는 과정에서 공식 문서와 약관을 직접 검색해 확인하다가, 원 계획대로면 실행이 막히거나 약관 위반 소지가 있는 지점을 세 군데 발견했다.

1. Google Custom Search API 신규 발급이 이미 중단됐고, 2027-01-01 완전 종료가 예정돼 있었다. → 역이미지 검색을 Google Cloud Vision API로 교체했다.
2. 텔레그램 Bot Platform Developer ToS가 "AI/ML 모델 개발·학습을 위한 공개 채널·그룹 콘텐츠 스크래핑·하베스팅·집계"를 명시적으로 전면 금지하고 있었다. → 자동 순찰에서 텔레그램을 제외하고, 사용자 수동 제보로 MVP 범위를 좁혔다.
3. 방심위(KOCSC) 온라인 신고센터의 공개 제출 API 존재 여부를 재검색으로도 확인하지 못했다. "없다"를 적극적으로 증명할 수는 없었지만, 확인이 안 된 채로 "자동 접수"를 약속할 수는 없었다. → "신고서 자동 생성"까지만 자동화하고, 실제 접수(발송)는 사용자가 최종 클릭을 직접 하도록 설계를 확정했다.

숫자도 다시 검증했다. AI-Hub 승인 절차는 "자동승인 정책이 있다"는 기존 인식과 달리 휴대폰 본인인증 기반 승인이 공식 절차였고, SerpApi·g5.2xlarge 단가처럼 처음 잘못 알고 있던 수치들도 재검색으로 바로잡았다.

멘토링 세 번, 그리고 기획서가 바뀐 과정

멘토링 1 — 다섯 가지 질문

가장 먼저는 창업기획(예비·초기·도약 단계) 지원, ICT·AI·클라우드 25년 이상 경력에 모바일 앱 분야 15년 경력을 가진 멘토님께 사업성 관점의 피드백을 받았다. 직접 준비해간 질문은 다섯 가지였다.

1. [시장성] 이게 팔릴까요? 문제는 명확하고 관련 자료도 많은데, 실제 수요가 있을까요?
2. [기술] 기능적으로 덜어내거나 추가해야 할 부분이 있을까요?
3. [클라우드] 데이터셋(얼굴·각도·한국인 특화 등)이 워낙 많고 다양해서 로컬 작업이 힘들 것 같은데, 서버를 쓰는 방향으로 가야 할까요?
4. [기술] 지금은 이미지로만 딥페이크를 판별하는데, 영상까지 고려해야 할까요? 고려한다면 어떻게?
5. [기획·법적] 서비스 기획·운영 단계에서 법적으로 어디까지 고려해야 할까요?

"마켓이 너무 작다. 스케일업하는 방향성을 생각해보자." 지금 타깃(만 19~24세 여성 대학생)만으로는 시장이 좁아 보인다는 지적이었고, PSST 전략으로 기획서를 다시 짜보라는 조언도 받았다.

PSST이란? Problem(문제인식)·Solution(솔루션)·Scale-up(성장전략)·Team(팀 역량)의 앞글자를 딴 사업계획서 구조로, 중소벤처기업부 계열 창업지원사업(예비창업패키지 등)에서 표준 양식처럼 쓰인다고 한다. 심사관이 이 네 블록에 각각 배점을 매기는 평가 프레임이라, "마켓이 너무 작다"는 지적은 정확히 Scale-up 항목을 겨냥한 것이었다.

두괄식·개조식으로 쓰되 한 주제가 두 줄을 넘어가지 않게 하라는 것, MVP UI를 반드시 넣으라는 것, 그리고 5번 질문(법적 고려사항)에 대한 답으로는 오히려 "페르소나를 만들어보라"는 역질문을 받았다. 실제 사용자 한 명을 구체적으로 그려보면 법적으로 어디까지 고려해야 하는지가 자연스럽게 드러난다는 취지였다. 여기서 또 하나의 방향 전환이 나왔다 — "사전처리"라는 개념이다. 이미 유포된 피해에 대응하는 것도 중요하지만, 불안해하는 사람들에게 사전에 제공하는 서비스(지금의 딥백신·소각 지수 라인)를 더 키워보자는 제안이었다.

멘토링 2 — "기획서 첫 페이지는 유튜브 썸네일이다"

이경엽 멘토님께 받은 피드백은 냉정했다. 심사위원은 60개 팀을 봐야 하고, 팀당 510분, 10페이지짜리 기획서라면 페이지당 2030초밖에 못 본다는 것. 팀당 1시간씩만 들여도 총 60시간인데, 심사위원이 그만큼 시간을 내줄 리 없다는 계산이었다. (실제로는 더 짧게 기획서를 읽고 심사를 하는 경우가 많다라고 전달받았다) 심사위원의 인지부하를 줄이는 게 핵심이라는 말이 가장 기억에 남는다.

구체적으로 이런 걸 배웠다.

• 기획서도 논문처럼 두괄식으로 — Introduction(추진배경) → Related works(경쟁 서비스 비교) → Main approach(핵심 기술) → Conclusion(기대효과) 순서

• 문제는 숫자와 함께 강해진다 — "저출산이 문제다"가 아니라 "출산율 0.7명대"처럼, 출처 각주도 바로바로
• 경쟁 서비스는 표로 — O/X 기호로 한눈에, 매출·MAU 같은 지표까지 넣어서 "듣보잡 아니다"를 보여주기
• 기획서 형식(대주제 5개: 추진배경/개발목표및내용/주요특징및핵심기술/기대효과및활용방안/개발추진체계)은 규정이라 절대 못 바꾼다. 소제목만 자유

이 피드백을 받고 경쟁 서비스 비교표, 시장 규모(TAM/SAM/SOM), 비즈니스 모델을 다시 짰다. TAM/SAM/SOM은 시장 규모를 세 겹의 원으로 좁혀가며 보여주는 방식인데(전체 잠재 시장 → 실제 접근 가능한 시장 → 정해진 기간 안에 확보할 시장), 우리는 국내 중·고교·대학 6,008개교(약 1,442억 원)에서 초기 판매 대상 대학 329개교(약 79억 원), 3년 내 유료 전환 대학 35개교(ARR 0.721.2억 원)까지 이렇게 좁혀서 제시했다.

멘토링 3 — "김밥천국이 아니라 미슐랭 원스타 국밥집이 되어야 한다"

세 번째 멘토링은 기술력 파트(3번 섹션, 배점 30점)에 집중됐다. 핵심 한마디는 "3번 섹션에서는 개발하는 모든 기술을 나열하지 마라"였다. 기능 리스트는 2번 섹션에서 끝내고, 3번에서는 핵심 기능 하나를 깊게 파야 한다는 것.

기술력 점수를 얻는 방법에는 난이도별 단계가 있다는 조언도 나왔다.

• [불가능] 원천 기술보다 더 나은 걸 정량화하기 — 사실상 논문 수준

• [상] 기술 가설을 3단계로 나눠서, 단계마다 실행하고 한계를 극복하는 이터레이션을 보여주기 ← 우리가 택한 방식
• [중상] 가설 하나라도 세워서 달성하기
• [중] Baseline과 정량 비교
• [하] 최소한 "왜 이 기술을 선택했는지"라도 설명

그리고 계속 곱씹게 되는 한 문장이 나왔다. "한계를 적지 않는다는 건 한계를 모른다는 뜻일 수 있다." 완벽한 척하지 말고, 뭘 못했는지 정직하게 쓰고 어떻게 극복할지 방법론을 제시하는 게 오히려 가산점이라는 것이었다. 여기서 얼굴가드의 v1(ArcFace 단독) → v2(ArcFace + Cloud Vision API) → v3(한국인 데이터 파인튜닝) 3단계 실험 설계가 나왔다.

+ 추가로 받았던 피드백

"3장에서 예시·가이드 자체보다 살릴 수 있는 부분을 더 크게 채워야 한다"는 얘기와 함께, "왜 이 글에 이 이미지를 썼는지 잘 모르겠다, 안 읽힌다"는 지적을 받았다. 어떤 이미지를 말하는 건지 곱씹어보면서 몇 개는 급하게 다시 손봤다, 줄이는 것보다 지금 있는 글에 의미를 더 채워 넣는 게 낫겠다는 피드백을 수용했다.

세 번의 멘토링을 반영해 실제로 뜯어고친 것들

역이미지 검색과 벡터 대조의 역할을 재배치했다.

원래는 "역이미지 검색으로 후보 수집 → 얼굴 유사도 필터 → AI 합성 판별" 순서였는데, "얼굴 원본을 단말 밖으로 안 내보낸다"는 원칙과 충돌했다. 역이미지 검색은 이미지 자체를 입력해야 작동하기 때문이다. 그래서 등록된 얼굴 임베딩을 기준으로 Cloud Vision API가 넓게 후보를 물어오고, ArcFace가 그중에서 정밀하게 걸러내는 구조로 재배치했다.

증거 보관 방식도 통째로 바꿨다.

개정 성폭력처벌법은 허위영상물의 소지·시청·저장만으로도 처벌 대상으로 규정한다. 원래 설계(스크린샷·아카이브를 서버에 원본 그대로 보관)는 서비스 운영자인 우리 팀이 그 콘텐츠를 "소지"하는 셈이 될 수 있었다. 그래서 원본은 피해자 단말에 암호화 저장하고, 서버는 SHA-256 해시·URL·시각·TSA 토큰 같은 메타데이터만 보관하는 구조로 바꿨다.

알림망 설계도 손을 봤다.

처음엔 "그룹 내 피해 발생 시 익명으로 그룹 전체에 경보"였는데, 학교처럼 좁은 공동체에서는 경보가 왔다는 사실 자체가 "이 안에 피해자가 있다"는 정보를 노출시킬 수 있었다. 그래서 모든 그룹에 동일한 주기·문구로 나가는 "정기 점검 위장" 알림으로 바꾸고, 실제 경보 발송 여부는 피해자 본인의 명시적 동의를 거치도록 했다. 기관명도 놓치지 않았다 — 방심위(방송통신심의위원회)가 2025년 10월 조직 개편으로 "방송미디어통신심의위원회"로 이름이 바뀌어 있었는데, 기획서 전체의 표기를 일괄 수정했다.

비즈니스 모델 방향도 바뀌었다.

처음엔 개인 유료 구독을 중심으로 그렸는데, 멘토님 피드백은 "개인은 보안에 돈을 많이 쓰지 않는다"는 것이었다. 예방 기능에 매달 돈을 내라고 하기보다, 실제로 피해를 입었을 때 "지우게 해주세요"가 더 팔릴 거라는 조언이었다. 그래서 기술을 앞세우기보다 공익적인 측면(뉴스 기사 인용 등)을 강조하는 쪽으로 서술 방향을 바꿨고, 이게 나중에 대학·교육기관 대상 B2B2C 모델(학생은 무료로 보호받고, 대학이 「고등교육법」상 보호 의무 이행 도구로 도입)로 이어졌다.

추진배경도 수정

숫자는 잘 썼지만 직접적인 출처 표시가 안 된 부분이 있었고, 인용한 기사에서 강조할 부분엔 밑줄이나 박스를 쳐야 시선을 사로잡는다는 것, "하나의 숫자로 표현할 수 있는 임팩트"가 아직 없다는 것, 그리고 무엇보다 "기획안은 잘썻지만 아쉽다는"는 평이었다. 피해 사례를 좀 더 자극적이고 후킹되게 앞부분에 배치해야 한다는 지적을 받고, 기사 화면 캡처에 강조 표시를 넣고 그래프를 여는 순간 바로 심각성이 느껴지도록 앞부분을 다시 짰다.

경쟁 서비스 비교표에도 지적이 있었다. O/X 표만으로는 "이게 어떤 서비스인지" 감이 안 온다는 것 — 그래서 표 아래에 각 서비스가 뭘 하는 서비스인지 한두 문장씩 설명을 추가했다.

시스템 아키텍처

손그림에서 실제 구조도로 바뀌었다. 1차는 앱·백엔드·AI 판별 등 7단계를 아이콘으로 나열한 수준이었는데, 최종본은 React Native/FastAPI/AWS/GitHub Actions까지 실제 기술 스택 이름이 박힌 아키텍처 다이어그램으로 교체됐다.

돌아보면 줄글 위주였던 1차 기획서가 표·다이어그램·실측 그래프 중심으로 변경했다, "이미지:줄글 비율 1/3 정도"라는 멘토링 팁이 단순한 디자인 조언이 아니라 "근거를 눈에 보이게 만들어라"는 뜻인거라고 생각한다.

목표의 정당성을 숫자로

"목표의 정당성을 수치화하라, 프리토타이핑을 해보라"는 조언을 받고, 실제 설문(수요조사)을 직접 설계했다.

프리토타이핑(Pretotyping)이란? 프로토타이핑은 핵심 기능을 실제로 만들어본 뒤 고객 테스트로 "만들 수 있는가"를 확인하는 거고, 프리토타이핑은 그보다 앞선 단계 — 아직 아무것도 안 만든 채로 랜딩페이지나 설문만으로 "만들 만한 가치가 있는가"를 먼저 확인하는 거였다. 개발에 자원 쏟기 전에 니즈부터 검증하자는 취지라, 우리는 앱 만들기 전에 먼저 설문으로 프리토타이핑을 한 셈이다.

그냥 "우리 서비스 어때요?"가 아니라 흐름을 짰다.

• 해커톤 서비스 소개로 시작
• 연령대·성별
• 어떤 SNS 플랫폼을 쓰는지
• 본인 얼굴이 들어간 사진이 스토리·피드에 올라가 있는지, 공개인지 비공개인지
• (1번 추진배경에 쓴 기사를 인용해서) 딥페이크 범죄를 얼마나 자각하고 있는지, 어떤 대처를 하고 있는지
• 서비스를 소개한 뒤 반응을 묻는 질문 한두 개로 마무리

여기에 NPS 스코어도 같이 넣었다. "이 서비스를 주변에 추천할 의향이 얼마나 되나요?"를 010점으로 물어서 추천그룹(910점)에서 비추천그룹(0~6점)을 뺀 값인데, 0점 이상이면 괜찮은 수준이고 80점 이상이면 세계적 수준이라고 한다. 잠재적 피해자를 대상으로 "이런 상황이라면 어떨까요?"라는 가정을 세워 테스트해보자는 방향이었다.

설문조사 결과 가장 필요한 기능으로 증거보존(57.8%)·게시 전 보호(55.6%)·공개 웹 확인(44.4%)이 꼽혔고, 학교가 서비스를 제공한다면 이용하겠다는 긍정 응답이 77.8%였다. 다만 개인정보 유출 우려가 75.6%로 높게 나오고 NPS는 0점이 나온 것도 그대로 실었다 — 이 결과를 계기로 "원본 미저장·기기 내 처리"라는 설계 원칙을 다시 한번 검증 과제로 명시했다.

검증 안 된 수치는 절대 임의로 만들지 않는다

멘토링을 반영하면서 세운 원칙은 하나였다. v1·v2는 실측, v3는 계획으로 명확히 구분해서 쓰는 것이다. v1은 ArcFace 단독 판별(Celeb-DF-v2 baseline)이다. InsightFace의 사전학습 buffalo_l 가중치로 Celeb-real 영상 590개를 대상으로 동일인 검증 실험을 했다. 등록 영상 3개·영상당 5프레임 조건에서 평균 ROC-AUC 1.000, EER 0.000, TAR 1.000을 기록했지만, FAR이 목표치 0.001을 초과(0.00138)해서 이 임계값을 운영값으로 채택하지 않았다. ArcFace는 "주어진 두 얼굴을 비교"만 할 뿐 "비교할 후보를 스스로 찾지는 못한다"는 한계가 v2로 이어지는 이유가 됐다.

v2는 실제 서비스 파이프라인 실측(Cloud Vision API + ArcFace)이다. 실제로 만든 코드를 그대로 사용해서 진짜 API를 호출하고 진짜 얼굴 임베딩을 계산했다. 표준 테스트 이미지에서 후보 20건이 반환됐고, 이 20건을 ArcFace로 재측정한 결과 코사인 유사도 평균 0.981, 20건 모두 임계값(0.6)을 상회했다. 반면 팀원 실제 얼굴 사진으로 테스트했을 때는 무관한 SNS 프로필 1건이 유사도 0.62로 후보에 포함됐다가 오탐으로 정확히 걸러졌다.

이 코사인 유사도를 그냥 숫자로만 남기지 않고, 실제 알림 로직에 쓸 수 있게 3단계 기준으로 나눴다. 유사도 0.85 이상이면 즉각경보, 0.60~0.84는 확인요청, 0.60 미만은 로그기록으로만 남기는 식이다. 오탐 하나 걸러졌다고 끝내는 게 아니라 "그럼 실제 알림은 어느 선에서 울려야 하나"까지 정해둔 셈이다.

v3는 아직 안 한 것이다. 한국인 얼굴 데이터셋(K-FACE, AI-Hub 이용 승인 완료)으로 파인튜닝하는 실험은 아직 실행하지 않았다. 계획은 등록 이미지 3~5장을 기준으로 임베딩 상단 계층만 재학습하는 방식과 backbone 전체를 재학습하는 방식을 비교하고, 각도·조명·화질·압축 조건을 반영한 고정 검증셋에서 ROC-AUC·FAR·FRR과 임계값별 오탐 변화를 측정하는 것까지 세워뒀다. 다만 v1·v2 실측이 목표치에 못 미친 원인이 얼굴 검출·정렬 실패만으로 설명되지 않을 때 진행하기로 했고, 아직 시작 전이라 검증 전 수치는 기획서에도, 그래프에도 "(목표·예측, 미실행)"이라고 매번 명시했다.

그래프를 만들다가 실수도 하나 했다. v1(1.000)·v2(0.981)·v3 목표(0.90)를 한 줄로 이어서 그렸더니 마치 버전이 올라갈수록 성능이 떨어지는 것처럼 보였다. 세 값은 서로 다른 지표(TAR@FAR vs 원시 코사인 유사도 평균)를 측정한 것이고 조건도 점점 어려워지는 구조라, 애초에 하나의 축으로 비교하면 안 되는 값들이었다. 결국 v1·v2는 각자의 실측 그래프로 따로 보여주고, v3는 그래프 대신 "목표"라는 걸 명시한 표로 대체했다.

남은 시간, 사흘 동안 프로토타입 개발

멘토링을 다 반영하고 나서는 기획서만 다듬은 게 아니라 실제로 앱을 붙이는 작업도 병행했다. 레포 커밋 기록을 다시 보면, 조용하던 시기를 지나 8월 5일부터 7일까지 사흘 동안 화면·기능이 한꺼번에 붙였다. 모니터링 화면, 후보 검토 화면, 증거·신고서 초안 화면, 안전 업로드(딥백신 적용 전) 화면, 서버 스캐폴딩과 이미지 처리 API, 화면들을 실제 서버 API 호출로 전환하는 작업까지 — 사흘 만에 PR이 20개가 넘게 작업을 진행했다.

그 뒤로 실제 역이미지 검색(Cloud Vision) 연동, 후보 상세 화면, 신고서가 실제 선택한 후보 데이터를 반영하도록 연결하는 작업까지 이어지면서 얼굴 등록 → 온디바이스 임베딩 → 모니터링 → 후보 검토 → 신고서 초안까지 실제로 동작하는 프로토타입이 완성됐다.

출처: Deng et al., CVPR 2019 확장판, arXiv:1801.07698, Fig.1

ArcFace 논문(Deng et al., CVPR 2019 확장판)의 그림도 실제 논문 PDF에서 좌표를 잡아 직접 크롭해 인용했는데, 그 과정에서 실수도 하나 발견했다 — 처음에 넣었던 그림 하나가 사실 논문이 아니라 회사 블로그 이미지였다는 걸 뒤늦게 알아채고, 실제 arXiv PDF를 다시 받아 정확한 그림으로 교체했다.

출처: Deng et al., Fig.8 — 딥소각이 임베딩을 기기 밖으로 내보내지 않는 설계 근거로 인용

논문 Fig.8도 그냥 인용에서 끝내지 않았다. ArcFace 임베딩이 판별뿐 아니라 얼굴을 역으로 복원하는 데도 쓰일 수 있다는 내용인데, 이걸 "그래서 딥소각은 임베딩을 서버로 보내지 않고 기기에만 저장한다"는 프라이버시 설계 근거로 그대로 연결했다.

예선심사 결과 발표

자유과제 본선 진출팀 발표에 춘배는 없었다. 대신 자유과제 아이디어상 명단에 춘배 이름이 올라갔다. 본선 오프라인 해커톤에는 못 갔지만, 처음 계획했던 대로 검증한 건 검증했다고, 못한 건 못했다고 정직하게 쓴 기획서가 심사에서 나름의 평가를 받았다고 생각한다.

운영사무국 문자

여기서 끝은 아니고, 인정한 한계

기획서 4.3절에는 "단계별 확장 및 한계"라는 표를 따로 넣었다. 이번 해커톤 MVP에서는 딥백신의 100% 합성 차단이 불가능하고 비공개 채널은 자동 탐색이 안 된다는 걸 그대로 인정했고, 대신 공개 웹 탐지·사용자 제보·증거자료 생성까지의 E2E 흐름을 먼저 검증하는 걸 목표로 잡았다. 36개월 안에는 이미지 변형에 따른 성능 저하, 오탐·개인정보 반복사용 미검증 문제를 한국인 얼굴 임계값 보정과 대학 1개교 실증(MAU·NPS·API 원가 측정)으로 풀어보려 하고, 13년 뒤에는 미참여 플랫폼과 암호화 채널의 재유포까지 기기 내 해시·C2PA·플랫폼 협력·Safe Upload API로 확장하는 게 목표다. 지금 당장 다 못 푸는 문제를 숨기지 않고 표로 박아둔 게, 돌아보면 이 프로젝트에서 제일 잘한 선택 중 하나였다.

생각정리

신청서를 쓴 7월 8일부터 결과를 받아본 지금까지 한 달 반 가까이 프로젝트(기획안을 작성)를 진행하면서 가장 많이 배운 건, 기술적으로 멋있어 보이는 것과 실제로 검증한 것을 절대 섞어서는 안 된다는 것이었다.

처음에는 좋은 기술과 기능을 많이 담는 것이 좋은 기획서라고 생각했다. 하지만 프로젝트를 하나씩 검증해 나가면서 생각이 조금씩 달라졌다. 킥오프 전에 실제 사용할 데이터셋을 확인하고, 공식 문서와 약관을 다시 찾아보면서 기존 계획에서 실행할 수 없거나 위험한 부분을 발견했다. 역이미지 검색과 얼굴 임베딩의 역할도 다시 나눴고, 실제로 해보지 않은 파인튜닝은 결과를 만들어내는 대신 '아직 실행하지 않았다'고 명확하게 적었다. 서로 다른 조건에서 나온 수치를 하나의 그래프로 보여주었던 것도 다시 뜯어고쳤다.

돌아보면 이 과정에서 계속 확인했던 건 하나였다. 확인한 것과 계획인 것을 구분해서 전달하는 것. 무엇을 할 수 있는지를 보여주는 것도 중요하지만, 지금 내가 어디까지 확인했고 어디부터가 아직 가설인지를 정확하게 말하는 것이 더 중요하다는 걸 배웠다. 특히 "한계를 적지 않는다는 것은 한계를 모른다는 뜻일 수 있다"는 멘토님의 말을 프로젝트가 끝날 때까지 계속 생각하게 됐다.

결과적으로 본선에는 진출하지 못했고, 처음 계획했던 것처럼 개발을 계속 이어갈 당위성도 사라졌다. 아쉽지 않다면 거짓말이겠지만, 그렇다고 이 한 달 반이 결과만으로 판단할 수 있는 시간이었다고 생각하지는 않는다. 적어도 이번 프로젝트를 통해 완성도를 과시하는 것보다 내가 확인한 범위를 정확하게 보여주는 것이 더 설득력 있을 수 있다는 것을 직접 경험했다.

본선에는 올라가지 못했지만, 아이디어상으로 프로젝트의 가치를 인정받을 수 있었고 9월 4일 시상식에 참석하는 것으로 이번 프로젝트의 한 매듭을 지으려고 한다. 돌이켜보면 KT 에이블스쿨에서 좋은 사람들을 만나 4월부터 지금까지 함께 개인 프로젝트와 개인일정에서도 병행하면서 총 세 번의 공모전에 도전했다. 그 과정에서 결과를 떠나 함께 고민하고, 부족한 부분을 채워가며 성장할 수 있었다는 것 자체가 나에게는 큰 의미로 남았다. 특히 이번 공모전은 춘배팀으로 함께한 마지막 공모전이라 더욱 아쉽게 느껴진다. 한 팀원은 올해 복학을 하고, 또 다른 팀원과 나는 함께 취업을 준비하며 각자의 새로운 길을 가게 됐다. 이제는 모두 같은 프로젝트를 위해 밤늦게까지 이야기하고 공모전을 준비하던 것처럼 함께하기는 어려울 수도 있다. 그래도 마지막까지 셋이 함께 프로젝트를 완성했고, 본선 진출이라는 목표에는 닿지 못했지만 작게나마 수상이라는 결과를 남길 수 있어서 다행이라고 생각한다.

다애님, 현준님 고생하셨어요!

이번 프로젝트의 자세한 기획안과 관련 자료는 아래 Github에서 확인할 수 있습니다. DeepSogak Github

📂 기획안은 Github의 docs/ 디렉토리에 정리되어 있습니다.

발대식 후기를 쓴 지 한 달이 조금 넘었다. 그때는 "혼자서는 벅찰 것 같다"는 생각과 "좋은 리뷰를 받아 Organization Member가 되는 것"이라는 목표만 있었는데, 지금은 실제로 이슈를 등록하고 PR을 올리고 리뷰를 주고받으며 한 달을 보냈다. Challenges 기간 중반을 지나며 지금까지 한 내용을 정리하려고 한다.

나는 OpenStack & Kubernetes 운영 문서화 및 국제화 팀 소속으로, 크게 세 갈래로 기여를 이어왔다.

• infra-cloud-kr/openstack-kubernetes — 팀에서 직접 만들어가는 OpenStack-Helm 운영 문서
• kubernetes/website — 쿠버네티스 공식 문서 한글화
• k8s-kr/kubelingoassist — 한글화 작업을 돕는 VS Code 확장 프로그램

여기에 더해 OpenDev 코드리뷰 워크플로우도 실습 진행했다.

겹치지 않는 이슈 선정하기

처음 팀 파트를 나눌 때 네트워크 쪽에 인원이 몰렸다. 나도 처음엔 Gateway API 파트로 시작했는데, GitHub 이슈 현황을 전수 조사해보니 이미 여러 명이 관련 주제를 선점한 상태였다. 그래서 아직 아무도 손대지 않은 Octavia 로드밸런싱(networking/load-balancing.rst)으로 파트를 바꿔 이슈(#24)를 새로 등록했다.

이후 이미 병합되거나 열려있는 다른 분들의 PR(#36, #38)을 읽으며 이 프로젝트에서 통용되는 문서 스타일(list-table로 리소스 정리, code-block으로 아키텍처 다이어그램 그리기)을 파악했고, 그 스타일을 따라 로드밸런서·리스너·풀·멤버·헬스 모니터 개념과 amphora/OVN 드라이버 비교를 작성해 PR #40을 올렸다.

출처: OpenStack Octavia 공식 문서

내가 문서로 정리한 게 바로 이 그림 속 구조다 — 로드밸런서 요청이 들어오면 amphora(실제 트래픽을 처리하는 VM 또는 컨테이너)가 뜨고, 컨트롤러가 이걸 관리하는 흐름을 이해하고 나니 글을 쓰기가 훨씬 수월해졌다. PR을 올리기 전 sphinx-build -W(경고 0건)와 doc8 린트(에러 0건)를 직접 돌려보고 확인한 것도 이번에 새로 익힌 습관이다.

첫 쿠버네티스 PR

kubernetes/website에 PR을 올리기 전에, 쿠버네티스 조직에 처음 PR을 올려본 곳은 kubernetes-sigs/contributor-playground였다(MERGED). CLA 서명이 제대로 되는지, Prow 봇이 어떻게 반응하는지 연습하는 온보딩용 저장소인데, 여기서 리뷰어가 GitHub의 "Approve" 버튼이 아니라 /lgtm, /approve 같은 "텍스트 커맨드"로 리뷰 상태를 바꿀 수도 있구나.. 많은 프로젝트에서 사용하지만 사용해보지 못했던 부분이라 신기했던거 같다.

리뷰받고 나서야 보인 것들

kubernetes/website에서는 kubeadm 고가용성 토폴로지 가이드의 오래된 번역을 최신화하는 PR(#56648)을 올렸다. 리뷰를 받기 전엔 "자연스러운 한국어면 된다"고 생각했는데, 리뷰어분께 받은 피드백 7건을 하나씩 내 원문과 비교해보니 내가 놓친 게 눈에 보였다.

local을 무조건 '지역'으로 직역하면 오히려 원문 의미가 흐려질 수 있다는 것, 매끄럽게 읽히려고 슬쩍 생략한 단어가 사실은 한글화팀이 지키려는 "원문 구조 보존" 원칙을 깨는 일이라는 걸 이때 처음 체감했다. 리뷰가 끝난 뒤엔 "커밋을 하나로 스쿼시해달라"는 요청도 받았는데, 리뷰 중엔 커밋을 계속 쌓다가 승인 직전에만 정리한다는 팀 관례도 이렇게 실제로 겪으며 배운거같다.

반대로 내가 간단하게 리뷰어가 되어본 경험도 있었다. 다른 분의 번역 PR(#56678)을 원문과 문단 단위로 대조하다가, 문서 상단의 translator 링크에 있는 GitHub 계정명 오타(hongp vs hong-p)를 발견했다. 번역 자체는 정확했지만, 링크가 실제 번역자를 가리키는지까지 확인하지 않았다면 놓쳤을 문제였다. 리뷰를 받는 입장과 직접 리뷰하는 입장을 모두 경험하면서, 좋은 번역은 ‘자연스럽게 읽히는 번역’에서 끝나는 것이 아니라 원문의 의미와 구조, 문서의 세부 요소까지 보존하는 번역이라는 걸 알게 됐다.

번역을 좀더 간편하게 할 수 있게

kubelingoassist에 기여하면서는 조금 다른 종류의 배움이 있었다. 번역 문서에서 자주 흔들리는 표기(예: 프록시/프락시)를 실시간으로 잡아주는 기능을 직접 설계·구현했는데, 처음엔 실제 문서 541개를 스캔해서 더 많이 쓰인 표현을 그냥 추천하려고 했다. 그런데 "가비지 컬렉션"이 corpus에서 더 많이 쓰인다고 보고 이걸 추천하려던 순간, 공식 용어집을 확인해보니 정답은 "가비지 수집"이었다. 컬렉션+콜렉션을 다 합쳐도 수집의 사용 빈도에 한참 못 미쳤다. 데이터(빈도)만 보고 판단하면 완전히 틀릴 수 있다는 걸, 내가 만들던 도구에서 직접 겪으며 배웠다. 이 경험 덕분에 "공식 용어집이 있으면 그걸 최우선으로, 없을 때만 데이터를 참고한다"는 설계 원칙을 세울 수 있었고, 이 기능을 VS Code Extension Host 환경에서 70개 이상의 테스트로 검증한 뒤 이슈(#30)와 PR(#31)을 올렸다.

OpenDev(Gerrit)

우리 팀이 최종적으로 바라보는 목표는 openstack-helm처럼 실제 OpenStack 프로젝트에 기여하는 것인데, 이 프로젝트들은 GitHub가 아니라 OpenDev라는, OpenInfra Foundation이 직접 운영하는 별도의 코드 호스팅·리뷰 인프라 위에서 돌아간다. 그래서 본격적으로 문서 작업을 하기 전에, OpenDev가 제공하는 연습용 저장소인 opendev/sandbox에서 이 낯선 워크플로부터 먼저 익혀보기로 했다. 계정 하나로 시작하는 GitHub와 달리, OpenDev는 Ubuntu One 계정(login.ubuntu.com)으로 로그인한다 — 이 계정은 Gerrit뿐 아니라 Launchpad(버그 트래커), 번역 플랫폼, 심지어 OpenInfra 재단 행사 투표까지 재단 전체 활동에 두루 쓰이는 단일 계정이었다. 이후 SSH key를 새로 만들어 ~/.ssh/config에 review.opendev.org 호스트를 등록하고 Gerrit에 공개키를 올렸고, git-review라는 전용 CLI 도구를 설치한 뒤 git review -s를 실행하면 gerrit이라는 리모트가 자동으로 생성된다. 커밋 메시지에도 규칙이 있었다 — 요약은 50자, 본문은 72자를 넘기지 않는 관례, 그리고 DCO(Developer Certificate of Origin, "내가 이 코드를 직접 썼고 라이선스에 동의한다"는 서명)를 뜻하는 Signed-off-by 태그를 반드시 붙여야 한다는 정보를 얻었다. 이렇게 세팅을 마치고 git-review로 패치를 올리니 터미널에 이런 로그가 찍혔다.

가장 헷갈렸던 건 "커밋을 새로 쌓는 방식이 아니라는 것"이었다. GitHub PR은 커밋을 계속 추가해서 리뷰 이력을 쌓아가지만, Gerrit은 git commit --amend로 같은 Change-Id를 가진 패치셋을 계속 덮어써서 갱신한다. 커밋 메시지 안에 있는 Related-Bug(연결된 버그 번호), Change-Id(이 리뷰를 식별하는 고유 값, 리비전이 바뀌어도 유지됨), Signed-off-by(DCO 서명) 세 태그를 이해하자

리뷰 방식도 완전히 달랐다. -1/0/+1은 누구나 줄 수 있는 리뷰 점수이고, +2는 승인 권한이 있는 리뷰어만 줄 수 있다는 점수제다. 게다가 병합되려면 세 종류의 라벨이 전부 채워져야 한다 — 사람이 코드를 검토하는 Code-Review, Zuul이라는 CI가 빌드·테스트 결과를 보고 자동으로 매기는 Verified, 그리고 병합 준비가 됐는지를 나타내는 Workflow. 이 셋 중 하나라도 비어 있으면 자동 병합(gate) 대상에서 제외된다는 걸 실습을 통해서 배울 수 있었다.

같은 실습 세션에서 팀원한분이 올린 연습 패치를 내가 리뷰해줄 기회도 있었다. Please capitalize the first letter.라는 코멘트를 남기고 Code-Review +2, Workflow +1을 직접 눌러 승인까지 해봤는데, GitHub에서는 "Approve" 버튼 한 번이면 끝날 일이 Gerrit에서는 점수 하나하나를 채워나가는 과정이 재밌었다. 한국어 번역에 많이 기여하고 더 나아가 영어번역에도 기여 할 수 있을 수 있게 많이 배우고 opendev사이트를 자주 방문해야겠다.

같은 "코드 리뷰"라도 프로젝트마다 문화와 도구가 이렇게 다를 수 있고, 우리 팀이 목표로 하는 openstack-helm 기여도 결국 이 Gerrit 문법(Change-Id, 패치셋, 점수제 승인, Zuul 게이트)을 몸에 익힌 다음에야 제대로 시작할 수 있겠다는 걸 이번 sandbox 연습을 하며 실습 환경을 익힌거같다.

미팅 사진을 몇개 안남겨서..

정규 미팅이 끝난 뒤에도 디스코드에서 당일 밋업에서 다룬 내용 중 이해가 잘 되지 않았거나 궁금했던 부분을 자유롭게 질문할 수 있었다. 멘토님들께서 질문에 바로 답변해주셔서, 세션 내용을 다시 짚어보고 궁금했던 부분을 바로 해소할 수 있었던거 같다. (멘토님들 항상 감사드립니다..)

생각정리

한 달 전만 해도 “번역은 자연스럽게만 하면 된다”고 생각했다면, 지금은 원문을 최대한 지키는 것과 자연스럽게 표현하는 것 사이에서 근거를 가지고 판단하는 법을 조금씩 배우고 있다. 리뷰를 받으면서, 반대로 다른 사람의 리뷰를 해보면서, 그리고 내가 만든 도구가 스스로 틀린 답을 낼 뻔한 순간을 겪으면서 결국 같은 교훈을 여러 방향에서 확인한 것 같다. 근거 없이 그럴듯해 보이는 것을 그냥 믿지 말 것. KubeCon Japan 이야기를 들으며 느낀 것도 비슷했다. 인프라도 문서도 결국 지금 맞다고 믿는 것을 계속 의심하고 검증하면서 조금씩 더 나은 방향으로 갱신해가는 일이라는 생각이 들었다.

앞으로 load-balancing.rst(PR #40)와 kubelingoassist(PR #31)가 실제 리뷰를 받게 된다면 이번에 배운 내용을 바탕으로 꼼꼼하게 반영해서 최종적으로 병합까지 이어갈 수 있는 PR을 만들고 싶다. 지금까지 OpenDev에서는 Sandbox를 통해 연습하는 데 그쳤다면, 이제는 실제 OpenStack 프로젝트, 특히 openstack-helm에 Gerrit으로 직접 패치를 올려보려고 한다. 다른 분들의 PR도 더 적극적으로 리뷰하면서 문서의 정확성을 검증하는 눈을 계속 키워가고 싶고, KubeCon Japan에 후기를 들으며 언뜻 접했던 AI 인프라의 흐름도 조금씩 따라가며 부족한 부분을 학습 해보려고 한다. 지금 당장 내가 직접 다뤄야 할 영역은 아니더라도, 내가 다듬고 작성하는 문서가 어떤 기술적 흐름 위에 놓여 있는지는 알고 써야 한다고 생각하기 때문이다.

처음에는 막막하게 시작했지만 한 달 사이에 GitHub와 Gerrit을 오가며 이슈를 만들고, PR을 올리고, 리뷰를 주고받는 과정이 어느새 제법 익숙해졌다. 아직 배워야 할 것도 많고 부족한 부분도 많지만, 적어도 한 달 전의 나와 비교하면 조금은 달라진 것 같다. Challenges 기간에서 많이 배웠고, 이어질 Masters 기간에서도 지금처럼 하나씩 부딪히고 확인해가면서 꾸준히 나아가보려고 한다.

빅프로젝트 특강 중 「Claude 엔지니어가 알려주는 AI Agent 시대의 개발 방법론과 실전 데모」를 들으며 가장 인상 깊었던 부분은, 강의가 단순히 새로운 AI 기술을 소개하는 강의가 아닌 앞으로 개발자가 어떤 방식으로 일해야 하는지를 중심으로 이야기하는 강의였다는 것이다. 특강은 생성형 AI의 현재 수준, AI Agent의 핵심 기술, 실전 데모, 그리고 앞으로 개발자의 역할이라는 네 가지 흐름으로 진행되었다. 들어가며 강조한 3가지가 인상깊어 글 시작전에 보고 다시 들어가보자.

첫 번째는 ‘말’, 즉 언어에 대한 부분이었다. AI 에이전트, MCP, 컨텍스트 엔지니어링 같은 용어를 단순히 외우는 것이 아니라, 왜 이런 개념이 등장했는지 자신의 문장으로 설명할 수 있어야 한다는 이야기였다. 두 번째는 ‘눈’, 즉 감각이었다. 에이전트가 제대로 작동하고 있는 상황과 불필요하게 반복하거나 엉뚱한 방향으로 흐르는 상황을 구분할 수 있는 판단력이 중요하다고 했다. 마지막은 ‘손’, 즉 행동이었다. 거창한 계획보다 오늘 저녁부터 바로 시작할 수 있는 90일 로드맵과 포트폴리오를 만들어보는 등 실천/활용이 필요하다는 점을 강조하는 특강이였던거 같다.

글 들어가기전, 요약

1. AI Agent는 이제 "실험"이 아니라 "실행"의 영역에 들어왔고, 개발자의 일은 "만드는 것"에서 "정하고 검증하는 것"으로 무게중심이 옮겨가고 있다.
2. 그런데 "토큰과 생각(추론)을 어떻게 줄일까"는 강의가 던진 화두이다. 실제로 파고들어 보면 훨씬 많은 갈래의 판단이 필요했다, 이 글의 절반은 그 고민이다.
3. 내가 만들던 claude-code-use 프로젝트를 강의 프레임에 대입해보니, 아직 AI를 100%역량을 끌어올려 사용하지 못한다고 생각이 들었다. 좀더 발전시켜서 AI를 잘 활용하자.

특강에서 다룬 개념

지금 우리는 어디쯤 와 있나

핵심은 "누가 다음 행동을 결정하는가"가 단계마다 사람에게서 AI로 옮겨간다는 것이다.

지금은 실험의 해가 끝나고 실행의 해가 시작된 시점이라는 게 강의의 내용이였다. AI를 최소 한 개 업무에라도 도입한 조직이 이미 다수이고, 공개된 MCP 서버 수도 1년 반 사이 수십 배로 늘었다. 다만 완전 자율 에이전트 도입은 아직 소수에 그친다. 챗봇은 질문→답변으로 끝나지만, 에이전트는 목표→계획→도구 실행→결과 평가→반복이라는 루프를 스스로 돈다.

같은 LLM을 쓰는데 결과물이 다른 이유는, 그 주변에 뭘 붙였느냐의 차이다.

이미 무게중심이 옮겨간 공정들

설계·인프라·리뷰·문서 네 공정 모두 AI가 초안을 만들고, 사람은 그게 사업 맥락에 맞는지 최종 판단하는 쪽으로 역할이 옮겨가고 있다. 일이 줄어드는 게 아니다. 일의 무게중심이 "만드는 쪽"에서 "정하고 검증하는 쪽"으로 이동한다. 용어도 1년 반 사이 빠르게 바뀌어왔다.

• 프롬프트 엔지니어링 - >
  • 컨텍스트 엔지니어링 - >
    • 하네스 엔지니어링 - >
      • 루프 엔지니어링

이름은 계속 바뀌지만 아래층(왜 이 문제가 생기는가)은 겹쳐 쌓인다는 게 요지였다. 그래서 용어 자체보다 판단 기준을 배우는 게 낫다.

AI Agent를 이루는 것들

Augmented LLM 구조	컨텍스트 보정

AI Agent는 다음 네 가지가 루프를 도는 것으로 정의된다. 하나라도 빠지면 그냥 챗봇이다.

• LLM (두뇌) — 무엇을 할지 추론·판단
• Memory (기억) — 무슨 일이 있었는지 들고 다님
• Tool (손발) — 바깥 세상을 읽고 바꿈
• Planning (계획) — 목표를 단계로 쪼개고 다시 짬 LLM은 텍스트만 뱉고, 실제 실행은 런타임(우리 코드)이 담당한다. 그래서 위험한 도구일수록 권한을 좁게, 파일 접근은 특정 디렉터리로 스코프를 한정하는 게 기본 원칙으로 강조됐다.

컨텍스트는 무한하지 않다는 것도 핵심 메시지였다. 많이 넣을수록 똑똑해질 것 같지만 실제로는 반대로 갈 때가 많다(Context Rot, Lost in the Middle 같은 연구가 근거로 제시됐다). 그래서 나온 게 네 가지 전략이다.

이 네 전략은 뒤에 나오는 내 개인적인 고민(토큰과 생각을 어떻게 줄일 것인가)의 출발점이 됐다.

워크플로 vs 에이전트, 그리고 자율성 레벨

"AI에게 다 맡기자"는 대개 실패한다.

workflow(사람이 순서와 분기를 미리 정함, 예측 가능하지만 예외에 취약)와 agent(모델이 도구와 순서를 스스로 판단, 유연하지만 관측·평가가 필수) 사이에서 지금 이 작업에 얼마나 맡길지를 정하는 게 현실적인 답이다. 자율성 레벨을 제시해줬다.

• L0(사람이 전부)
• L1(AI 제안·사람 실행)
• L2(AI 초안·사람 리뷰)
• L3(AI 실행·사후 확인)
• L4(완전 자율)

  이 중 L2가 실무에서 가장 흔히 쓰이는 지점이라고 한다. L4를 목표로 삼기보다, 지금 작업에 맞는 레벨을 스스로 정하는 게 실무적이라는 메시지였다.

고민하자

강의는 비용 = 토큰 × 스텝 수라는 한 줄로 정리하고 넘어갔다. 그런데 이 문장을 실제로 내 작업에 적용하려고 하니, 훨씬 많은 갈래의 고민이 나왔다. 일곱 가지로 정리해본다.

1. 애초에 추론이 필요한 문제인가부터 의심한다

"생각 깊이를 작업마다 다르게 설정하라"는 조언 앞에 생략된 판단이 있다고 생각한다. 이 작업에 추론이 정말 필요한가? 라는 질문이다.

1.파일 하나 찾기, 오타 하나 고치기처럼 답이 명백한 작업에 깊은 추론 모델을 물리면 토큰만 태우고 결과는 똑같다. 2. 반대로 여러 파일에 걸친 설계 결정처럼 "틀린 가정을 되돌아봐야 하는" 작업에 빠른 모델을 쓰면 결과가 부정확해서 재작업(=스텝 수 증가)으로 이어진다.

effort를 잘못 낮추면 재시도 비용으로 되돌아온다. "싼 모델을 쓰는 것"과 "적절한 모델을 쓰는 것"은 다른 문제다.

2. 스텝 수를 줄이는 게 토큰을 줄이는 것보다 효과가 클 때가 많다

프롬프트 한 줄을 줄이는 건 토큰 단가에서 몇 % 절약이지만, 루프 한 번을 줄이는 건 그 루프 전체(탐색+실행+검증)의 토큰을 통째로 아끼는 것이다. 그래서 고민의 우선순위는 "무엇을 짧게 쓸까"보다 "어디서 다시 도는가"를 먼저 찾는 쪽이어야 한다. 이건 결국 초기 지시가 얼마나 명확한가의 문제로 돌아간다. 다음에 애매하게 시켜서 되묻는 루프가 생기면, 그 되묻는 루프 자체가 스텝 수다.

3. 컨텍스트를 "안 채우는 것"과 "채웠다가 비우는 것"은 다른 전략이다

Write·Select·Compress·Isolate를 다시 뜯어보면, 이 넷은 사실언제 비용을 지불하느냐의 타이밍이 다르다.

• Select(애초에 필요한 것만 넣기)는 가장 싸다. 비용을 아예 안 만든다. 하지만 "지금 뭐가 필요한지"를 미리 정확히 알아야 하는데, 탐색적인 작업에서는 이게 어렵다.
• Compress(줄이기)는 한 번 채운 다음 요약하는 비용이 추가로 든다. 요약 자체도 LLM 호출이라 토큰을 쓴다.
• Isolate(서브 에이전트 분리)는 겉으로는 메인 컨텍스트를 지키지만, 서브 에이전트가 쓰는 토큰까지 합치면 총량은 오히려 늘어난다. 간단한 작업에 서브 에이전트를 붙이면 분리 비용만 남는다.

결국 네 전략 중 뭘 쓸지는 지금 이 작업이 얼마나 오래, 얼마나 많은 파일에 걸쳐 진행될 것인가를 미리 가늠해야 고를 수 있는데, 이 가늠 자체가 또 하나의 판단 비용이라는 게 아이러니하다...

4. 캐싱은 설계에서부터 고려해야 나오는 절약이다

매 요청마다 같은 시스템 프롬프트·같은 CLAUDE.md를 새로 밀어 넣으면 캐시가 안 붙고 매번 전체 단가로 과금된다. 자주 안 바뀌는 것과 매번 바뀌는 것을 앞뒤로 명확히 분리해두면 앞부분이 캐시에 걸려 반복 비용이 크게 줄어든다. 프롬프트를 무엇을 넣을까로만 생각하면 안 나오고, 어떤 순서로, 얼마나 자주 바뀌는 덩어리로 나눌까까지 생각해야 나오는 절약이다.

5. 병렬로 돌릴 것과 순차로 돌릴 것을 가르는 기준

서브 에이전트를 여러 개 동시에 돌리면 시간은 줄지만 토큰 총량은 그대로거나 늘어난다. 반대로 순차로 돌리면 앞 단계 결과를 뒤 단계가 참고할 수 있어 재작업이 줄 수도 있지만 시간이 길어진다. 나는 여태 이걸 "빠르면 좋은 것"으로만 생각했지 비용 관점에서 저울질해본 적이 없었다.

• 독립적인 작업(탐색 여러 갈래) → 병렬이 이득
• 서로 의존하는 작업(설계→구현→검증)을 억지로 병렬화 → 나중에 합치는 비용이 더 든다

6. 검증 비용도 전체 비용에 포함해서 계산해야 한다

빠르고 싼 모델로 작업을 끝냈다고 해서 끝난 게 아니다. 결과가 틀렸는지 사람이 검토하는 시간, 틀렸을 때 다시 시키는 토큰까지 합쳐야 진짜 비용이다. 모델을 고를 때 이 답이 틀렸을 때 내가 알아챌 수 있는가까지 고민에 넣어야 한다. 알아채기 어려운 실수를 내는 모델을 싸다고 고르면, 검증 비용이 절약분을 다 잡아먹는다.

7. 정말 풀리지 않는 고민

이번 판단에 얼마나 생각을 태울까를 매번 사람이 정해야 하는가? effort를 작업마다 다르게 설정하라는 조언은 맞지만, 그 설정을 사람이 매번 판단해야 한다면 이것도 결국 사람의 인지 비용이다. 이상적으로는 에이전트가 이 작업은 되돌아볼 필요가 있어 보인다"는 걸 스스로 감지해서 effort를 올리는 게 맞을 텐데, 이걸 사람이 대신 정해주는 지금 단계와 에이전트가 스스로 정하는 다음 단계 사이에 아직 간극이 있다. 나는 지금 이 판단을 거의 느낌으로 하고 있는데, 이걸 규칙으로 정리해서 CLAUDE.md나 하네스 설정에 박아둘 수 있을지가 다음에 시도해볼 지점이다. 예를 들면 이런 식이다.

• 파일 3개 이상 걸치면 → 깊은 모델
• 테스트 실패가 2회 이상 반복되면 → effort 상향

특강을 듣고 정리하고 나니 확실해진 게 있다.

토큰을 줄인다는 하나의 목표를 넘어서 어디서 비용이 새는지를 계속 다시 찾아야 하는 것이 중요하다고 생각한다. 이 프레임(Write·Select·Compress·Isolate, effort 조절)은 도구 상자일 뿐이고, 지금 이 작업에 어떤 도구를 얼마나 꺼내 쓸지는 결국 매번 새로 판단해야 한다.

내가 이미 하고 있던 것과 겹쳐보기

이 강의를 들으면서 계속 떠오른 게, Claude CLI를 자주 사용하는 입장에서 내가 편하려고 만들고 있는 claude-code-use였다. 배운 개념에 내 프로젝트를 대입해보자

지금 레포에는 11개의 서브 에이전트(00-orchestrator부터 시작해서 planner, implementer, reviewer, tester.. 등등)와, 그 아래에서 실제로 돌아가는 CLI 도구 몇 개가 있다. claude-cost는 세션을 시작하기 전에 에이전트·모델별로 예상 비용을 계산해준다. claude-handoff는 세션이 끝날 때 작업 맥락을 파일로 저장해뒀다가 다음 세션 시작할 때 그대로 이어 붙일 수 있게 해준다. claude-remind는 TODO.md나 CLAUDE.md에 남겨둔 미완료 항목을 세션 시작 시점에 다시 띄워준다. (여러가지 있지만) 이 조합을 다시 보면, planner·reviewer·security-auditor는 애초에 읽기 전용 권한만 갖도록 정의해뒀다는 게 눈에 들어온다. 코드를 직접 고치는 건 implementer 하나뿐이고, 나머지는 보고 판단만 하게 만들어뒀다. 이건 "사람이 개입하는 지점을 설계했는가"라는 질문에는 이미 답이 되어 있는 부분이다.

반면 없는 것도 분명하다. GitHub·Figma·Notion MCP 서버는 이미 클라이언트로 연결해서 쓰고 있지만, 전부 남이 만들어둔 걸 가져다 쓰는 입장이다. claude-code-use 안에 있는 도구들은 전부 내가 터미널에서 직접 실행하는 CLI라서, 이 중 하나라도 내가 직접 MCP 서버로 만들어서 Claude가 스스로 판단해서 호출하게 만든 건 아직 없다. 그리고 claude-cost가 "이번 달에 재작업이 몇 번 있었다"는 숫자는 남기지만, 정작 그 재작업이 왜 일어났고 어떻게 고쳤는지를 사람이 읽을 수 있는 글로 남기는 도구는 없다. 강의를 듣고 개선할 부분을 생각해보자.

1. MCP 서버 지금 claude-code-use에 있는 도구들은 전부 내가 터미널에서 직접 실행하는 CLI다. claude-cost(비용 추정)나 claude-handoff(세션 기록 조회)처럼 이미 로직이 검증된 도구부터 MCP 서버로 한 번 감싸보려고 한다. 새로 뭔가를 만드는 것보다, 이미 잘 도는 로직을 다른 방식(AI가 스스로 호출하는 방식)으로 한 번 더 노출해보는 쪽이 첫 시도로는 덜 위험하다고 판단했다. 이렇게 하면 에이전트가 작업을 시작하기 전에 "이 작업 예상 비용이 얼마나 나올까"를 스스로 물어볼 수 있게 되는데, 이게 바로 위에서 정리한 첫 번째 고민(추론이 정말 필요한 작업인지 미리 판단하기)을 도구 차원에서 도와주는 셈이 된다.

2. 실패를 기록하는 습관. 지금은 재작업이 얼마나 자주 일어났는지 숫자(비율)만 남기고 있는데, 정작 "왜 헛돌았고 어떻게 고쳤는지"를 글로 남긴 적은 없었다. 다음부터는 재시도가 발생한 세션이 끝나면 무엇을 하려고 했는지, 왜 안 됐는지, 어떻게 고쳤는지, 다음엔 뭘 다르게 할 것인지를 짧게라도 파일로 남겨보려고 한다. 숫자는 "얼마나 자주 실패했는가"는 보여주지만 "왜 실패했는가"는 보여주지 못한다는 걸, 많이 겪고 블로그 또는 프로젝트에 남겨보려고 한다.

생각정리

나는 AI를 어떻게 써야 할까 AI는 이제 설계도대로 아주 잘 짓는 존재가 됐지만, 무엇을 지을지 정하는 건 여전히 사람의 일이다.

나에게 이게 구체적으로 의미하는 건 이렇다.

1. 자율성 레벨을 스스로 정한다, L4(완전 자율)를 목표로 삼지 않는다. L2(AI 초안·사람 리뷰)가 실무에서 가장 많이 쓰이는 지점이고, 내 프로젝트의 읽기 전용 에이전트들도 결국 이 L2를 코드로 강제한 것이다.

2. 컨텍스트를 RAM처럼 다룬다. 무한히 넣지 않는다. 필요할 때만 꺼내 쓰고, 작업 경계에서 비운다.

3. 포트폴리오는 성공이 아니라 실패와 경계로 완성된다. 다음 과제는 명확해졌다. MCP 서버 하나를 직접 만들고, 실패 케이스를 의도적으로 만들어서 그 실패를 어떻게 고쳤는지 기록하는 것 또는 AI를 많이 활용하며 부족한점에 대해 계속 끊임없이 고민하는것이다.

대학교 학부에서 GPT-3.5를 사용하며 AI가 하지 못하는 일을 사람이 메우는 것이 개발자의 역할이라고 생각했다. 하지만 AI는 1년, 6개월, 그리고 불과 1개월 단위로도 체감될 만큼 빠르게 발전하고 있다. 지금의 AI를 보며 '과연 주니어 개발자는 앞으로 어떤 경쟁력을 가져야 할까?'라는 고민이 들 정도였다. 그런데 이번 강의를 들으며 생각이 조금 달라졌다. AI가 점점 더 능숙한 장인이 되어갈수록, 사람은 더 이상 벽돌을 하나씩 쌓는 사람이 아니라 어떤 땅 위에 무엇을 지을지 결정하는 사람이어야 한다는 것이다. 방향을 정하고, AI가 이해할 수 있는 맥락을 설계하며, 완성된 결과를 검증하고 책임지는 역할이 더욱 중요해지고 있다. 결국 AI 시대의 개발자는 코드를 가장 많이 작성하는 사람이 아니라, 가장 좋은 문제를 정의하고, 가장 올바른 질문을 던지며, 가장 분명한 기준을 세울 수 있는 사람이 되어야 한다고 생각한다. 기술은 점점 더 빠르게 발전하겠지만, 무엇을 만들 것인지 결정하고 그 결과에 책임을 지는 일만큼은 여전히 사람의 몫이라는 사실은 변하지 않을 것이다.

+ TMI - 해커톤 예선에 붙었다. 가보자고~ @현준 @다애

참고

• 내 프로젝트: github.com/BcKmini/claude-code-use Anthropic — Building Effective AI Agents Anthropic — Effective Context Engineering for AI Agents Anthropic — Building Effective AI Agents Anthropic — Effective Context Engineering for AI Agents Anthropic — Building Effective AI Agents Anthropic — Building Effective AI Agents

오픈소스 컨트리뷰션 아카데미(OSSCA)는 참여자를 멘토·멘티로 묶어 실제 오픈소스 프로젝트에 기여하는 경험을 쌓게 해주는 프로그램이다. 2026년에는 11개 팀이 참여형 프로젝트로 운영됐고, 나는 그중 OpenStack&Kubernetes 운영 문서화 및 국제화 팀에 멘티로 합류하게 됐다. (작년에 Pytorch프로젝트에 참여해 기여했었는데 좋은 기회가 다시...)

발대식 진행

이번 발대식은 2026년 7월 11일 서울 강남 한국과학기술회관 국제회의장에서 진행되었으며, 참여형 멘토와 멘티, 사무국 등 약 300명이 함께한 행사였다. 행사는 OSSCA 프로그램 소개와 운영 일정 안내로 시작되었으며, 이후에는 프로젝트별 팀 소개와 팀별 자율 미팅이 진행되었다.

타임테이블

강연정리 : 오픈소스를 대하는 나

박수홍 삼성전자 오픈소스 그룹장 — 오픈소스는 생각보다 폐쇄적이다

가장 기억에 남는 메시지는 "오픈소스는 열려 있고 개방적이라고 생각하지만, 사실 생각보다 폐쇄적이다"라는 문장이었다. 기업 입장에서는 과거에 오픈소스를 부정적으로 바라보는 시선이 컸다고 한다. 내 코드와 기술을 외부에 공개한다는 것 자체가 리스크로 여겨졌기 때문이다. 그런데 시간이 지나면서 이 인식이 조금씩 바뀌었고, 지금은 오히려 오픈소스 참여가 기업 경쟁력의 핵심으로 여겨지는 흐름으로 왔다는 이야기였다.

다른 자리에서도 밝힌 적 있는 관점과 맞닿는 지점이 있었다. "오픈소스는 기업에서 보면 경쟁력의 핵심이고, 사업에서는 헤게모니를 위한 굉장히 중요한 전략"이라는 표현인데, 결국 기업이 오픈소스를 공개하는 이유가 순수한 선의가 아니라 각자의 사업 전략에 맞춰 계산된 선택이라는 뜻이다. 실제로 삼성전자는 SW의 70% 이상을 오픈소스로 활용하며 165개 프로젝트를 직접 공개하고 있고, ONAP 같은 프로젝트에서는 코드 기여 순위로 화웨이를 앞서기도 했는데, 이런 활동들도 결국 산업 표준을 주도하고 영향력을 확보하기 위한 전략적 포지셔닝의 성격이 크다고 생각한다.

발대식에서 나온 "오픈소스는 순결하지만은 않다"는 표현을 말씀하셨다. 오픈소스라고 해서 모든 게 순수한 선의와 이상으로만 돌아가는 게 아니라, 그 안에도 기업의 이해관계와 전략이 얽혀 있다는 것이다. 이 얘기를 들으면서 최근 몇 년간 업계에서 실제로 있었던 사례들이 떠올랐다. MongoDB(2018년), Elastic(2021년), Redis(2024년) 같은 오픈소스 데이터베이스 기업들이 잇따라 라이선스를 바꾼 일이 대표적이다. AWS 같은 대형 클라우드 벤더가 이들의 오픈소스 코드를 그대로 가져다 관리형 서비스로 팔면서도 코드 기여로는 거의 돌려주지 않자, 원저작 기업들이 코드 공개 자체를 제한하는 source-available 라이선스로 돌아선 것이다. 이 사례는 오픈소스가 늘 이상적인 협업 공동체로만 굴러가는 게 아니라, 누가 가치를 만들고 누가 그 가치를 가져가느냐를 둘러싼 현실적인 힘겨루기의 장이기도 하다는 걸 잘 보여준다.

정승록 AMD 수석 AI 소프트웨어 엔지니어 — GPU 성능 평가 현장에서 오픈소스를 대하는 법

정승록 엔지니어는 AMD에서 GPU performance evaluation(그래픽카드 성능 평가) 파트를 담당하고 있다고 소개했다. 실제로 benchmarking과 performance testing 업무를 주로 하신다고 했는데, AMD가 ROCm(Radeon Open Compute)이라는 오픈소스 GPU 컴퓨팅 스택을 공개하고 있고, 그 안에 rocHPL이나 hipBench 같은 벤치마킹 도구들도 오픈소스로 함께 제공한다는 걸 감안하면 실무와 맞닿아 있는 이야기로 느껴졌다. 강연에서는 AMD 자체 코드도 이미 오픈소스로 공개되어 있고, 이 외에도 해외 유수 기업들이 공개한 오픈소스 프로젝트가 정말 많다고 강조했다. 다만 기술적으로 핵심적인 코드 기여는 결국 그 프로젝트를 직접 만든 사람들이나 이미 이름이 알려진 기업들이 주도하는 경우가 많으니, 후배 개발자 입장에서는 그런 코드를 보면서 공부하고 직접 뜯어보면서 시야를 넓히는 게 중요하다고 조언했다. 여기에 AI를 적극적으로 잘 활용하라는 말도 덧붙였다. 강연 말미에는 본인이 요즘 재미있게 보고 있는 논문이나 분야를 언급하며, 관련된 오픈소스 프로젝트 몇 가지를 추천해주기도 했다.

저녁엔 오픈인프라 x 쿠버네티스 한국 사용자 모임 밋업도

같은 날 저녁에는 OSSCA 발대식과는 별개로 OpenInfra 한국 사용자 모임과 Kubernetes 한국 사용자 모임이 공동 주최하는 밋업이 있었다.

타임테이블

낮에 있었던 발대식 세션과 저녁 밋업의 세션이 그대로 이어져서 시간가는줄 모르고 집중해서 들었다. 뒤에서는 밋업에서 얻은 인사이트를 OpenStack, Kubernetes 순서로 정리해보려고 한다.

OpenStack — 탄생부터 운영 문서화까지

OpenStack 이전

2010년 이전, 클라우드라는 개념 자체는 이미 있었지만 선택지가 좋지 않았다. 한쪽에는 AWS처럼 완전히 폐쇄적인 API로 돌아가는 퍼블릭 클라우드가 있었고, 다른 한쪽에는 VMware 같은 값비싼 proprietary 가상화 스택이 있었다. 오픈소스 쪽에서 그나마 존재하던 대안이 Eucalyptus였는데, 이건 아예 AWS API와 호환되도록 설계된 프로젝트였다. 즉 자체 표준을 만드는 게 아니라 AWS 생태계 안에서 하이브리드 클라우드를 돌리기 위한 보조 도구에 가까웠다. 결국 기업 입장에서는 어느 쪽을 택하든 특정 벤더(AWS든 VMware든)의 API와 생태계에 종속될 수밖에 없는 구조였다.

OpenStack 탄생

이 벤더 종속 문제를 풀기 위해 2010년, 미국항공우주국(NASA)과 클라우드 호스팅 업체 Rackspace가 각자 개발하던 프로젝트를 합쳤다. NASA는 자체 클라우드 플랫폼인 Nebula를 개발 중이었는데 여기서 나온 컴퓨트 제어 코드가 나중에 Nova가 됐고, Rackspace는 자사의 오브젝트 스토리지 서비스인 Cloud Files를 오픈소스로 공개하면서 이게 Swift가 됐다. 두 프로젝트가 만나 2010년 7월 오스틴에서 첫 디자인 서밋을 열고, 같은 달 21일 OSCON에서 정식으로 발표된 게 OpenStack의 시작이다. 그해 10월 나온 첫 정식 릴리스("Austin")에는 Nova와 Swift, 딱 두 개 서비스만 들어 있었다. 컴퓨트(Nova)와 스토리지(Swift)라는 클라우드의 가장 기본적인 두 축에서 시작해서, 이후 네트워킹(Neutron), 블록 스토리지(Cinder) 같은 프로젝트가 붙으며 지금의 오픈스택 생태계로 확장된 것이다. 핵심은 벤더 종속을 끊자는 목적의식이었다. VMware 같은 프로프라이어터리 스택도, AWS 같은 폐쇄적 퍼블릭 클라우드 API도 아닌, 아무 벤더에도 종속되지 않는 완전한 오픈소스 표준을 만들겠다는 게 OpenStack의 존재 이유였다. (아주 흥미롭지요)

OpenStack 재단, 그리고 왜 처음엔 리눅스 재단에 안 갔는가

OpenStack이 처음 만들어질 때 리눅스 재단(Linux Foundation) 산하로 들어가는 방안도 검토됐다고 한다. 그런데 당시 리눅스 재단은 사실상 리눅스 커널 하나만 돌보는 조직에 가까웠고, 지금처럼 수백 개 프로젝트를 품는 "빅 텐트" 구조가 아니었다. 그래서 오픈스택은 2012년에 독립된 재단(OpenStack Foundation)을 따로 설립하는 길을 택했다. 이후 2020년에는 오픈스택 하나만이 아니라 여러 오픈 인프라 프로젝트를 아우르겠다는 뜻에서 이름을 OpenInfra Foundation으로 바꿨다.

그리고 2025년, 큰 사건이 하나 있었다. OpenInfra Foundation이 리눅스 재단에 정식으로 합류한 것이다. 독립 재단을 만들었던 2012년의 결정과는 정반대의 방향인데, 이번엔 AI 시대의 막대한 인프라 투자와 지정학적 변화 속에서 힘을 합치는 게 낫다는 판단이었다고 한다. 이 합류로 재미있는 구조가 완성됐다. 운영체제 표준(Linux), 클라우드 인프라 표준(OpenStack/OpenInfra), 컨테이너 표준(Kubernetes/CNCF)이 모두 같은 리눅스 재단이라는 우산 아래 들어오게 된 것이다. OpenInfra Foundation은 리눅스 재단 안에서도 독자적인 예산과 거버넌스, 회원 구조를 유지하는 "재단 안의 재단" 형태로 운영된다.

OpenStack I18n 팀이 하는 일

OpenStack I18n(Internationalization) 팀의 공식 가이드는 "국제화는 OpenStack을 유비쿼터스로 만드는 데 필수"라는 문장으로 시작한다. 소프트웨어 자체의 국제화 품질을 높이고, 고품질 번역을 관리하는 게 이 팀의 역할이다. 쿠버네티스처럼 SIG-Docs 산하에 Localization 서브프로젝트를 두는 구조가 아니라, OpenStack은 애초에 I18n 팀 자체가 독립된 프로젝트 팀으로 존재한다. 소통 창구는 메일링 리스트와 IRC #openstack-i18n 채널이다.

번역 플랫폼 : Zanata -> Weblate

OpenStack은 2015년 9월부터 Zanata라는 번역 플랫폼(translate.openstack.org)을 써왔다. 웹 브라우저만 있으면 원문과 번역문을 좌우로 나란히 놓고 작업할 수 있는 CAT(Computer-Aided Translation) 툴이다. 그런데 Zanata 프로젝트 자체가 2018년 9월 이후로는 활발한 개발이 멈춘 상태였고, 이 문제를 풀기 위해 2023년 OpenStack 기술위원회가 Weblate로의 이전을 공식 투자 과제로 올렸다. 2024~2025년 사이 I18n SIG가 이 마이그레이션을 우선순위로 진행 중이며, Gerrit/Zuul과의 연동 문제 등을 해결해가고 있다고 한다.

기여 절차 부분은 핸즈온 세션을 통해 직접 실습을 진행했기 때문에, 해당 내용은 다음 글에서 실습 과정과 함께 자세히 다루도록 하겠다.

Kubernetes — 탄생부터 운영 문서화까지

Kubernetes 이전

Kubernetes도 마찬가지로 갑자기 생겨난 것이 아니다. 컨테이너 자체를 널리 퍼뜨린 건 Docker였고, Docker가 뜨자 "이 수많은 컨테이너를 어떻게 관리할 것인가"라는 오케스트레이션 문제가 따라왔다. 이 문제를 풀겠다고 나선 후보가 여럿 있었는데, Docker 진영 자체가 내놓은 Docker Swarm과, 아파치 재단의 Mesos(+Marathon)가 대표적이었다. 쿠버네티스 자체는 구글이 내부적으로 써오던 Borg, 그리고 그 후속작 Omega의 경험을 이어받아 만든 세 번째 컨테이너 관리 시스템이다. 즉 구글은 이미 수년간 수십만 대 서버에서 컨테이너를 굴려본 경험이 있었고, 그 노하우를 외부에 공개 가능한 형태로 다시 설계한 게 Kubernetes였다. 2014년 오픈소스로 공개됐고, 2015년 구글이 이걸 갓 설립된 CNCF(Cloud Native Computing Foundation)에 기증했다.

Kubernetes란

Kubernetes는 구글이 만든 관리 시스템이다. 컨테이너가 제공하는 활용성을 누리면서도 복잡한 분산 시스템을 쉽게 배포하고 관리할 수 있도록 도와주는 컨테이너 오케스트레이션 시스템으로 정의된다. 애플리케이션 배포 방식이 Traditional Deployment(물리 서버) → Virtualized Deployment(VM) → Container Deployment로 진화해온 흐름의 마지막 단계에 있다.

참고

CNCF - Kubernetes의 관계 CNCF(Cloud Native Computing Foundation)는 2015년 설립된 Linux Foundation 산하 재단으로, 벤더 중립적으로 클라우드 네이티브 오픈소스 프로젝트를 육성한다. 같은 해인 2015년, 구글이 쿠버네티스를 CNCF에 기증했고 쿠버네티스는 CNCF 최초의 오픈소스 프로젝트이자 최초로 졸업(Graduated)한 프로젝트가 됐다.

Kubernetes 커뮤니티 그룹 구조

쿠버네티스 커뮤니티는 세 층위로 나뉜다.

• 위원회(Committees): 프로젝트에 대한 특정 권한을 위임받은 그룹. 행동 강령 위원회, 보안 대응 위원회, 운영 위원회 등이 있다.
• 특별 관심 그룹(SIGs): 프로젝트의 특정 영역을 담당하는 그룹. Architecture, Docs, Release, Testing, Node, Storage 등으로 나뉜다.
  • 하위 프로젝트(Subprojects): SIG 안에서 독립적으로 운영되는 조직. 내가 참여하는 SIG-Docs 안의 Localization과 Website가 여기 해당한다.
• 워킹 그룹(Working Groups): 여러 SIG에 걸쳐 특정 목표를 달성하기 위해 만들어진 임시 그룹.

SIG-Docs가 하는 일

SIG-Docs의 목적은 문서를 통해 쿠버네티스에 기여하며, 가능한 한 많은 사람이 쿠버네티스를 쉽게 사용하도록 돕는 것이다. kubernetes.io에 문서를 게시하고, 기능 문서화 표준을 제공하며, 핵심 API·아키텍처 문서화, 분기별 릴리스 문서 작성, 기여자 지침 제공, 공식 블로그 관리까지 담당한다.

Localization(L10n)이란

SIG-Docs의 하위 프로젝트인 Localization의 목표는 영문 공식 문서를 다양한 언어로 현지화하고, 그 과정을 표준화하는 공간을 제공하는 것이다. 단순히 "번역팀"이 아니라 공식 문서 유지보수 조직에 가깝다는 게 발대식에서 가장 인상 깊었던 설명이었다.

L10n의 역할을 정리하면:

• Localization은 단순 번역이 아니라 오픈소스 접근성을 높이는 기여다. 모든 사용자가 영어에 익숙한 건 아니고, 모국어 문서의 존재는 학습 장벽을 크게 낮춘다.
• 글로벌 커뮤니티 확장에 기여한다. 누구나 사용할 수 있는 프로젝트를 만드는 게 오픈소스 철학 중 하나이고, Localization은 지역 커뮤니티(예: 한글화팀) 활성화에도 기여한다.
• 항상 최신 정보를 유지해야 한다. 쿠버네티스 릴리즈 주기는 약 4개월이고, L10n팀은 새 기능·Deprecated 기능·변경 사항을 각 언어 문서에 반영한다. 각 현지화 팀마다 별도 가이드라인이 있다.

AI 시대, L10n은 어떻게 변화해야 하는가

발대식 자료에서 많은 생각이 들었었다. 예전에는 "기여자가 직접 번역 → PR 생성 → 다른 기여자가 리뷰 → 머지"가 표준 흐름이었는데, 지금은 "AI가 자동 번역해주면 되는 거 아니냐"는 질문이 자연스럽게 나온다. (글쓰는 화자도 Claude를 pro를 사용하며 하루 토큰량을 빡빡하게 다 쓰는 입장이기에..)

앞으로의 방향으로 제시된 흐름은 "한글화 가이드라인을 기반으로 한 AI 프롬프트로 초안 생성 → 기여자가 리뷰 → PR 생성 → 다른 AI 혹은 기여자가 리뷰 → 머지"였다. 완전 자동화도, 완전 수작업도 아닌 중간 지점을 계속 고민해야 하는 이슈로 남겨져 있었다.

실제로 용어집 등록 논의(GitHub issue #51885)를 보면, "Pod를 포드로 표기할지 팟으로 표기할지" 같은 세부 사항까지 커뮤니티가 활발하게 토론하며 표준을 정하고 있었다. 이렇게 정립된 용어는 쿠버네티스 관련 문서·강의·서적의 참고 기준이 된다는 설명을 들으니, 단순 번역 작업이 아니라 표준을 함께 만들어가는 일이라는 게 실감났다.

실제 기여 프로세스

1) 기여 준비

• CNCF 커뮤니티 행동 강령(Code of Conduct)을 숙지한다.
• CLA(Contributor License Agreement)에 서명한다. 기여자가 작성한 코드의 권리를 커뮤니티에 양도한다는 의미이며, PR 생성 시 자동으로 서명 여부가 확인된다. 서명이 안 되어 있으면 PR이 머지되지 않는다.
• 처음이라면 kubernetes-sigs/contributor-playground 저장소에서 연습해볼 수 있다. remote 디렉터리에 자신의 GitHub 아이디로 마크다운 파일을 만들어 PR을 올리면 CLA 서명 코멘트가 자동으로 달리고, 머지되면 메인테이너의 환영 메시지도 받을 수 있다.

2) 이슈 탐색 및 작성

• Kubernetes i18n Tracker(kfess.github.io/kubernetes-i18n-tracker)에서 언어별로 원문 대비 얼마나 뒤처졌는지(outdated) 확인할 수 있다.
• 번역이 필요한 문서를 찾으면 kubernetes/website 저장소에 이슈를 등록한다.

3) 한글화 작업 및 PR 작성

• 쿠버네티스 문서 한글화 가이드(kubernetes.io/ko/docs/contribute/localization_ko)를 따른다. 과거에는 별도 브랜치를 운영했지만 지금은 메인테이너·컨트리뷰터 모두 main 브랜치를 기준으로 작업한다.
• 한글화 모범 사례 문서도 참고하면 좋다. 기여 방식, 문체 및 표현, 원문 처리, 용어 네 가지 카테고리로 자주 반복되는 리뷰 사례가 정리돼 있다.
• 작업이 끝나면 PR을 올린다.

4) AI 사용에 대한 가이드라인 이 부분이 개인적으로 가장 중요하게 느껴졌다. kubernetes.dev의 AI Guidance 문서 핵심은 이렇다.

• AI를 이용한 PR 작성은 허용되지만, 모든 변경 사항은 작성자가 이해하고 책임져야 한다.
• AI를 사용했다면 PR 설명에 반드시 공개해야 한다.
• AI를 공동 작성자로 등록하거나 AI가 만든 커밋 메시지를 그대로 쓰는 건 금지된다.
• AI가 대부분 작성한 대규모 PR은 허용되지 않는다.
• PR 제출 전 반드시 직접 코드 리뷰와 테스트를 해야 한다.
• 리뷰어의 질문에는 AI가 아니라 작성자가 직접 답해야 하고, 변경 이유를 설명하지 못하면 PR이 종료될 수 있다.

참고

한국어 L10n 팀은 Slack kubernetes.slack.com의 #kubernetes-docs-ko 채널을 중심으로 소통한다. 2주 단위 목요일 밤 10시(KST)에 Zoom으로 정기 회의를 하고, 회의록은 Google Docs에 공개되어 있다. 팀 구성은 Lead 1명, Approver·Reviewer 각 여러 명, 그리고 활동 현행화가 필요한 Member 목록까지 투명하게 공개돼 있었다. 실제로 참여형 로컬라이제이션(ko) 프로젝트를 새로 발족하려는 신규 기여 문의가 Slack에 올라오는 것도 볼 수 있었는데, 커뮤니티 활발히 운영되기도 하고 나도 기여 할 수 있을까에 대한 막연한 두려움이 든다.. (글, 리뷰, Issue, PR등등 모두 영어여...)

생각정리

같은 "문서 현지화"라도 OpenStack과 Kubernetes의 워크플로는 꽤 다른점이 처음 보는 입장에서는 적응하기 어려웠다. OpenStack은 Zanata(→Weblate)라는 전용 번역 툴 안에서 원문·번역문을 대조하며 작업하는 번역 전용 워크플로였고, 기여자의 활동을 "번역 단어 수"로 정량화해 거버넌스 투표권(AC 지위)까지 연결했다. 반면 쿠버네티스는 GitHub 저장소에 PR을 올리고 리뷰를 받는, 개발자에게 익숙한 코드 기여 방식 그대로였고 AI 사용 가이드라인까지 별도 문서로 명문화돼 있었다. 먼저 이 프로세스를 적응하고 방법, 돌아가는 구조를 이해해야 하기에 공식문서들을 들여다 봐야지.. (기여하는 부분에 있어 문서화가 정말 잘 되어있어 보기 편하다)

발대식을 진행하며 팀원들과의 자기소개 시간이 있었는데, 실제 현업에서 일하시는 분들도 많았고 인턴하시는 분들, 학생분들도 있었다. 모두 Cloud/Infra 관심이 있고 오픈소스 기여하는 것에 관심이 있어서 이렇게 팀으로 모이게 되었으니, 멘토님이 밋업 때 강조해주신 대로 팀원들과 함께 많이 소통하고 리뷰하고 배워야겠다. 발대식을 시작으로 이제 프로젝트가 시작된다. 앞으로 멘토님들을 따라 OpenStack, Kubernetes를 사용하는 한국사람들에게 더 보기 좋고 편한 문서를 만들기 위해 기여하면서, 더 좋은 서비스가 뭐가 있을까, 가독성이 좋은 글이 무엇일까(단어에 대한 양식은 정해진 부분이 많지만)에 대해서 고민을 많이 할 것 같다. 중간에 놓지 말고 끝까지 집중해서 많은 것을 배우고 성장하자. (좋은 Review를 받아 기여해 Organization Member가 되는것이 현재 목표!)

참고 자료

OpenStack 문서 기여 관련 (한국어 자료)

• OpenStack I18n 가이드(한국어): https://docs.openstack.org/i18n/latest/ko_KR/
• I18n 가이드에 관하여(한국어): https://docs.openstack.org/i18n/latest/ko_KR/about.html
• OpenStack 한국어 번역팀 위키: https://wiki.openstack.org/wiki/I18nTeam/team/ko_KR
• OpenStack 한국어 번역 문서: https://docs.openstack.org/ko_KR/
• 번역자로 기여하기(Contributor Guide): https://docs.openstack.org/contributors/common/i18n.html
• 공식 OpenStack 번역자 되기: https://docs.openstack.org/i18n/latest/official_translator.html
• 전체 언어팀 목록: https://wiki.openstack.org/wiki/I18nTeam/team
• Weblate 이전 관련 TC 문서: https://governance.openstack.org/tc/reference/upstream-investment-opportunities/2023/translations-infrastructure.html

  쿠버네티스 문서 기여 관련

• 쿠버네티스 공식 문서: https://kubernetes.io/
• CNCF Landscape: https://landscape.cncf.io/
• 쿠버네티스 커뮤니티 그룹: https://www.kubernetes.dev/community/community-groups/
• SIG-Docs Charter: https://github.com/kubernetes/community/blob/main/sig-docs/charter.md
• Localization Subproject: https://github.com/kubernetes/community/tree/main/sig-docs/localization-subproject
• 쿠버네티스 문서 현지화 가이드: https://kubernetes.io/ko/docs/contribute/localization/
• 쿠버네티스 한글화 모범 사례: https://kubernetes.io/ko/docs/contribute/localization_ko_best_practice/
• AI Guidance: https://www.kubernetes.dev/docs/guide/pull-requests/#ai-guidance
• CLA 안내: https://github.com/kubernetes/community/blob/main/CLA.md
• Kubernetes i18n Tracker: https://kfess.github.io/kubernetes-i18n-tracker
• Contributor Playground: https://github.com/kubernetes-sigs/contributor-playground
• Kubernetes Slack: https://slack.k8s.io/ (#kubernetes-docs-ko)

2026년도 기후에너지환경부가 주최한 AX(AI Transformation) 아이디어 경진대회에 참가했다. 부문은 자유분석이 아니라 지정분석이었는데, 이 대회의 지정분석은 한 기관이 아니라 12개 공공기관이 각자 자기 실무 문제를 과제로 내놓는 방식이었다. 국립공원공단은 해안 해양쓰레기 유입 예측을, 한강홍수통제소는 AI 기반 하천 수위 예측과 디지털트윈을, 한국남동발전과 서부발전은 발전소 대기오염물질 배출 최적화를, 한국남부발전은 배출권 가격 예측을, 한국동서발전은 제주 SMP 예측을, 한국원자력환경공단은 처분시설 국지성 기상 예측을, 한국전력공사는 전기요금 과다발생 사전 예측을, 한국지역난방공사는 열사용 이상 탐지를, 한국환경공단과 환경산업기술원은 각각 공급망 분석과 생활화학제품 안전관리 진단을 내놓았다. 그리고 그중에 한국수자원공사가 낸 과제가 있었다.

조류경보 예측 AI 모델 개발 — 대청댐 수질·수문·기상 정보를 바탕으로 유해남조류 발생 및 경보 발령 시점을 예측하고, 녹조 발생 주요 영향 인자를 도출해 사전 시나리오 기반 의사결정 지원체계를 구축한다.

처음 과제 목록을 쭉 훑어볼 때는 이것저것 하고싶어서 고민이 많았다. 그래서 우리는 각자 하고 싶은 주제를 선택해 간단하게 기획서를 작성해 회의때 발표를 진행해서 더 많이 설득되고 좋은 주제에 투표해 많은 투표를 받은 주제를 선정하게 되었다. 그래서 우리 팀은 다애님이 조사해주셨던 수자원공사의 조류경보 과제를 골랐다. 수자원공사는 대청댐의 수질·수문 관측자료를 10개년치 그대로 지정과제 데이터로 제공해줬는데, 이걸 어떻게 가공하고 무엇과 엮어야 진짜 예측이 될지는 온전히 우리 몫이었다.

팀명은 춘배, 팀원은 나(김경민)를 포함해 최현준, 김다애(성현석님은 취업으로 인해 불참하게 되었다) 세 명이었다. 우리가 최종적으로 잡은 과제명은 다음과 같다.

대청댐 유해남조류 선제적 대응을 위한 자율형 의사결정 지원 시스템 구축

조사를 시작하며 확신이 생긴 이유

수자원공사 과제를 고르고 조사를 시작하면서, 이 주제를 선택하길 잘했다는 확신이 점점 커진 이유가 세 가지 있었다.

첫째, 매년 반복되는 사회적 이슈라는 점이다. 국립환경과학원이 조류경보제 지점을 9곳에서 13곳으로, 2030년까지 28곳으로 늘리겠다고 밝힌 걸 확인했다. 정부가 이미 이 문제에 예산과 정책 우선순위를 두고 있다는 신호였고, 우리 아이디어가 허공에 뜬 상상이 아니라 실제 정책 흐름 위에 올라탈 수 있다는 뜻이기도 했다.

둘째, 대청댐 자체의 상징성이다. 대청호는 1998년 팔당호·충주호·주암호와 함께 국내 조류경보제가 최초로 도입된 4개 호소 중 하나다. 조류경보제의 "원조"격인 곳에서, 제도가 확대되어온 20여 년 동안 실제로 무엇이 바뀌었는지 들여다볼 가치가 있다고 판단했다.

셋째, 조사를 하면 할수록 현행 제도의 구조적 한계가 명확하게 보였다는 점이다. 조류경보제 운영지침을 읽어보니 발령 기준 자체가 "2회 연속 유해남조류 세포수가 기준을 초과할 때"였다. 첫 번째 초과가 확인되고서도 두 번째 채수 결과가 나올 때까지 기다려야 하는 구조다. 대청호 문의 수역에서 2023년 8월 30일 경계 단계가 발령된 사례를 역추적해보니, 관측 이후 실제 공식 대응까지 이어지는 데 최소 한 번의 채수 간격만큼, 체감상 열흘 가까운 행정 지연이 있었다.

"이미 나온 결과를 처리하는 시스템은 이미 있다. 데이터도 충분하지만 발생하고 나서 대응하는 방식이다. 우리가 이걸 미리 예측하고 예방한다면 도움이 되지 않을까?"

이 질문 하나로 방향을 잡았다. 그리고 처음부터 이걸 "발령 이전 단계를 보완하는 시스템"으로 포지셔닝하기로 팀 내에서 얘기가 나왔다.

제공된 데이터를 진짜 쓸모 있게 만드는 과정

수자원공사가 준 것, 우리가 채워야 했던 것

지정과제 공고에는 수자원공사가 제공하는 데이터 항목이 명확히 적혀 있었다. 대청댐 수질정보(최근 10개년, 주 단위 — 지점명, 채수위치, 조사일, 수온, pH, DO, 투명도, 탁도, Chl-a, 발령단계, 유해남조류 세포수와 4종별 세포수)와 대청댐 운영 수문정보(최근 10개년 — 날짜, 댐수위, 일유입량, 일방류량), 그리고 기상청 자료로 "날씨, 일조시간 합계, 일강수량" 정도가 함께 제공됐다. 즉 우리가 맨땅에서 대청댐 데이터를 수소문한 게 아니라, 애초에 이 세 축이 지정과제의 재료로 주어져 있었다.

문제는 공고에 적힌 기상 항목이 "날씨, 일조시간 합계, 일강수량" 정도로 꽤 단출했다는 점이다. 녹조 발생 메커니즘을 제대로 설명하려면 기온, 풍속, 일사량, 지면온도 같은 변수가 더 필요했다. 그래서 이 부분만큼은 우리가 직접 채워 넣어야 했다. 기상자료개발포털(data.kma.go.kr)을 뒤지고, 금강홍수통제소 사이트도 참고하면서 다음 관측망을 추가로 확보했다.

• ASOS(종관기상관측): 국가 공식 기후 자료로서 대표성을 갖는다. 대청호 유역과 관련된 보은(226, 회남 상류), 대전(133, 문의·추동 중하류), 청주(131, 문의 북측) 지점을 골랐다.
• AWS(방재기상관측): 위험 기상을 실시간으로 감시하는 데 주목적이 있어 지역성이 강하다. 청남대(888), 장동(648), 세천(643), 옥천(605/604) 지점을 썼다.

이 두 관측망의 성격이 다르다는 걸 이해하는 데도 시간이 좀 걸렸다. ASOS는 국가 대표 통계용이라 신뢰도는 높지만 지점 수가 적고, AWS는 촘촘하게 깔려 있지만 방재 목적이라 관측 항목이 더 단순했다(AWS는 일 자료 기준으로 평균기온·일강수량·평균풍속 정도만 뽑을 수 있었고, ASOS에는 일사량과 지면온도까지 있었다).

시간별 자료의 컬럼 하나하나도 다 뜯어봤다. 기온·이슬점온도·지면온도·5cm/10cm/20cm/30cm 지중온도, 강수량·적설·습도·증기압, 풍속·풍향·현지기압·해면기압, 일조·일사·전운량·중하층운량·운형·최저운고·시정, 지면상태·현상번호까지.

남조류가 왜, 어떻게 자라는지부터 공부해야 했다

기상 변수를 고르기 전에 먼저 "남조류가 왜 대발생하는가"를 생물학적으로 이해해야 했다. 이 부분은 정말 논문과 많은 자료, 운영지침을 오가며 시간을 많이 썼다. 정리하면 4대 메커니즘으로 요약된다.

1. 온도 메커니즘: 남조류는 대표적인 고온성 생물이다. 기온이 수온을 결정하는 가장 큰 요인이고, 특히 25°C 이상 고온이 유지되는 기간이 핵심이다. 다만 물은 공기보다 늦게 데워지고 늦게 식기 때문에(수온 관성), 당일 기온보다 최근 7일간 누적된 기온과 지열이 더 정확한 신호였다.

2. 광합성 메커니즘: 조류는 광합성으로 증식하므로, 단순히 해가 떠 있던 시간(일조시간)보다 실제 수면에 도달한 태양 에너지 총량(일사량)이 훨씬 정확한 설명 변수였다.

3. 영양염류 유입 메커니즘: 비는 유역의 질소·인 같은 영양분을 댐으로 실어 나르는 '먹이 공급원'이다. 다만 폭우는 오히려 조류를 씻어내리는(세굴) 효과가 있어서, 강수량의 강도와 지속 시간을 함께 봐야 했다.

4. 수직 안정도(성층) 메커니즘: 풍속이 낮을수록(대략 2m/s 미만) 물이 위아래로 섞이지 않는 '성층 현상'이 생기고, 이때 부력을 조절할 수 있는 남조류가 표층으로 떠올라 대발생하기 좋은 환경이 된다.

여기서 더 들어가서, 종별로 특성이 다르다는 것도 알게 됐다. 이게 나중에 우리 프로젝트의 중요한 차별점이 됐다.

• Microcystis: 국내에서 가장 흔한 녹조 주범. 간 독소(Microcystin) 생성. 고온(25°C 이상)과 강한 햇빛을 좋아하고, 스스로 부력을 조절해 표층으로 떠오르는 능력이 탁월하다.
• Anabaena(Dolichospermum): 냄새 유발 물질을 만들고, 질소를 스스로 고정할 수 있어 질소가 부족해도 잘 자란다. 인 농도는 높은데 질소가 부족한 조건에서 우점 가능성이 커진다.
• Oscillatoria: 다른 종보다 낮은 온도와 적은 빛에서도 견딘다. 초여름·늦가을에도 나타날 수 있어, 수온이 완전히 오르지 않은 시기의 증가는 이 종이 원인일 가능성이 있다.
• Aphanizomenon: Microcystis가 힘을 못 쓰는 고온기가 아니라, 기온이 오르기 시작하는 초여름이나 찬바람이 부는 늦가을에 주로 번성한다. 계절성이 뚜렷해서 월(Month)이나 계절 변수가 중요한 힌트가 된다.

대청호는 다른 호수와 뭐가 다른가

대청호만의 특수성도 따로 파고들었다. 언뜻 "체류시간이 길면 녹조가 심하다"는 단순한 공식이 통할 것 같았지만, 실제로 찾아보니 그렇게 단순하지 않았다. 예를 들어 소양호는 체류시간이 긴데도 TSI(부영양화 지수) 기준으로 빈영양 호수로 분류된다는 신문 기사(중앙일보)를 발견했다. 즉 체류시간만으로는 설명이 안 되고, 질소·인 오염원의 유입량과 고온다습한 기후가 함께 맞물려야 한다는 걸 확인했다.

그리고 대청호 특유의 지형적 문제도 찾아냈다. 관련 논문(「대청호 상류유역의 오염원 현황과 수질관리 방안에 관한 연구: 안남천과 안내천을 중심으로」, 「소옥천 유역의 오염제어 대책에 따른 대청호 조류저감 효과 분석」)을 보면, 대청호는 본류보다 소옥천 같은 지류·만입부의 오염 기여도가 크다는 게 드러난다. 소옥천 유역 연구에서는 축산분뇨 에너지화와 표준시비량 적용이 가장 수질개선 효율이 높다는 시뮬레이션 결과(CE-QUAL-W2 모형)도 확인했다.

또한 대청호는 자연호가 아니라 길고 구불구불한 인공저수지라는 점도 중요했다. 이 구조 때문에 조류 발생이 계절 변수만으로 설명되지 않고, 방류 운영·체류시간 변화·지류 유입부의 국지적 오염에 크게 좌우된다는 사실을 알게 됐다. 그래서 우리는 자연호에서 쓰는 범용 모델을 그대로 가져오는 대신, 수리 변수(수위·방류량·유입량·체류시간)와 공간 분리(수역별 모델링)를 중심에 둔 대청호 전용 접근이 필요하다고 판단했다.

제공 데이터를 자동으로 갱신하는 파이프라인 만들기

수자원공사가 넘겨준 수질·수문 데이터는 정적인 엑셀 파일 형태였다. 이걸 한 번 받아서 끝내는 게 아니라, 같은 출처에서 최신 구간까지 자동으로 이어붙이고 재현 가능하게 관리하고 싶어서 공공데이터포털의 대청댐 수문 운영 정보 API부터 먼저 시도했다. 그리고 대청댐 수질정보·수문정보 공개 페이지를 직접 크롤링하는 쪽으로 방향을 틀었다.

개발자도구로 페이지의 고유 div-id를 확인하고, Selenium으로 연도별 구간을 순회하며 엑셀을 내려받는 자동화 스크립트(water_gate.py, water_quality.py)를 직접 짰다. 수문 데이터는 dam_select0, dam_select1 같은 select 엘리먼트를 자바스크립트로 조작해서 대청댐을 선택하고, 시작일·종료일을 넣은 뒤 fnObj.hydrExcelDown() 같은 페이지 내부 함수를 직접 호출하는 방식으로 다운로드를 자동화했다. 다운로드 중간에 예상치 못한 alert 창이 뜨는 경우도 있어서 재시도 로직도 넣어야 했다. 이렇게 만든 파이프라인 덕분에 수자원공사가 준 기준 데이터에, 우리가 직접 확보한 최신 기상 데이터를 결합해 하나의 최종 데이터셋으로 관리할 수 있었다.

결측치는 어떻게 처리했나

10개년 데이터를 통으로 쓰다 보니 결측 구간도 있었다. 2016년 1월부터 3월까지는 주요 수질 지표가 장기간 결측되어 있어서, 억지로 채우는 대신 그 구간 자체를 학습에서 제외했다. 일강수량(daily_rain)의 결측은 성격이 달랐는데, 관측소에서 비가 오지 않아 애초에 기록되지 않은 경우로 판단해서 일괄적으로 0으로 대체했다. 반면 평균·최저·최고기온과 평균풍속은 시계열 특성이 있는 변수라, 전후 날짜 값으로 선형보간(Linear Interpolation)해서 자연스러운 흐름을 유지했다. 이렇게 정리한 뒤 최종적으로 확보한 데이터 규모는 2016년 4월부터 2025년 12월까지, 6,304행 × 57컬럼, 결측치 0건, 중복 키 0건이었다.

불규칙한 채수 주기, 그리고 슬라이딩 윈도우

데이터를 다 모으고 나서도 진짜 문제는 그다음이었다. 수질 채수일이 월요일이었다가 목요일로 바뀌고, 주 1회였다가 2회로 늘어나는 식으로 불규칙했다. 처음엔 이게 그냥 현장 사정인 줄 알았는데, 나중에 「조류예측 및 수질관리협의회에 관한 규정」 제8조를 읽고서야 이유를 알았다. 조류예측 정보는 "주 2회(월요일과 목요일) 17시에 발표"하되, 유해남조류 세포수가 상수원구간 기준 10,000 세포/mL를 하루라도 초과하면 매 근무일마다 발표하도록 되어 있었다. 즉 우리를 힘들게 했던 불규칙성 자체가 이미 정책적으로 설계된 결과였던 것이다.

이 불규칙성을 다루기 위해 채택한 방법이 "이벤트 중심 샘플링(Event-based Sampling)"이다. 날짜(달력) 기준이 아니라 '채수 이벤트(정답지가 있는 날)'를 닻(Anchor)으로 삼고, 그 과거로 창문(Window)을 던져 데이터를 긁어오는 방식이다.

• 단기 윈도우(T-3일): 비 온 직후의 희석 효과, 급격한 폭염 같은 조류의 즉각적인 반응을 포착
• 장기 윈도우(T-7일~T-14일): 영양염류 축적, 물의 정체 상태 같은 댐의 기저 환경을 포착

이 방식의 핵심은, 채수 간격이 며칠이든 상관없이 모델은 항상 "결과가 나오기 직전 N일 동안 누적된 환경"이라는 일관된 패턴을 학습한다는 점이다. 그리고 학습할 때와 운영할 때의 논리가 다르다는 것도 중요한 설계 포인트였다. 학습 시에는 정답(실측 세포수)이 있는 채수일을 기준으로 과거 데이터를 묶어 공부하지만, 실제 운영 시에는 정답지가 없어도 된다. 매일매일 윈도우를 굴리며 예측을 수행할 수 있기 때문이다.

변수별 가공 방식도 성격에 따라 다르게 설계했다.

• 기온: 평균과 최대값을 함께 본다. 7일 평균기온이 전반적인 더위를, 3일 최고기온의 평균이 폭염 강도를 나타낸다.
• 일사량: 합계(누적)를 쓴다. 남조류 증식은 태양 에너지가 누적되어야 폭발하기 때문에 평균보다 합계가 생물학적으로 더 정확하다.
• 강수량: 합계와 특정 시점 값(Lag)을 함께 쓴다. 3일 누적강수량과 T-7일 단일 강수량을 따로 변수화했다.
• 풍속: 조건 만족 일수를 카운트한다. 풍속 자체의 평균은 의미가 희석되므로, "2m/s 이하가 며칠 지속되었는가"를 세는 방식이 훨씬 유의미했다.
• 수위·저수율: 절대값보다 변동폭(Delta)이 중요하다. 오늘 수위에서 7일 전 수위를 뺀 값으로 물이 차오르는지 빠지는지를 봤다.
• 유입량·방류량: 상호작용 변수로 만들었다. 체류시간(Retention Time) = 저수량 / 일평균 방류량. 이 값이 클수록 물이 오래 고여 있다는 뜻이고, 조류 예측에서 가장 강력한 변수 중 하나가 됐다.

수질 자료(채수 데이터)는 매일 있는 게 아니므로 윈도우로 묶을 수 없었다. 대신 "직전 채수일(T-1)의 상태"를 오늘(T)의 결과를 예측하는 힌트로 썼다. 탁도 증가율(T-2 대비 T-1의 탁도 급증)은 비가 와서 오염물이 들어왔다는 강력한 증거로 활용했고, pH도 흥미로운 변수였다. 낮에는 광합성이 활발해서 CO₂가 줄고 pH가 오르며, 밤에는 호흡 작용으로 반대가 된다. 이 동조 현상 때문에 pH 변화량 자체가 녹조 발생의 현재 증거로 쓰일 수 있었다.

정책 문서를 조문 단위로 읽다

발령기준	모니터링 프로세스

「조류예측 및 수질관리협의회에 관한 규정」을 조문 하나하나 짚어가며 우리 모델과 어떻게 연결되는지 정리했다.

• 제4조(조류예측 기간): "발표일로부터 7일간" → 우리 모델의 예측 시점(next_log_cells, 7일 후)을 정책 언어에 그대로 맞출 수 있는 근거였다.
• 제5조(조류예측 항목): 수온, 유해남조류세포수, 기타 필요사항 → 우리는 수온을 주요 입력 변수로, 유해남조류세포수를 회귀·분류 타깃으로 정확히 대응시켰다.
• 제6조(분석자료): 수치모델링 예측 결과, 기상·수질·유량·위성영상 등 관측자료 → 우리가 수질만 보지 않고 기상·댐 운영 데이터까지 통합한 이유가 여기 있었다.
• 제7조(조류예측구간): 금강은 대청호부터 금강 하구언까지 → 대청호가 이미 법정 예측구간에 포함되어 있다는 걸 확인.
• 제8조(조류예측 발표): 5월~10월 발표, 주 2회(월·목) 17시 발표 → 앞서 언급한 채수 불규칙성의 원인.
• 제10조(사후평가): 매년 1월 사후평가 실시 → 우리 프로젝트의 baseline 대비 성능 개선 검증 로직과 대응시켰다.
• 제15조(협의회 협의 사항): 단계별 대응조치, 관계기관 상호 의견조정, 비상연락체계 → 우리가 만든 "시나리오 기반 의사결정 지원 체계"가 실제로 연결될 수 있는 제도적 지점이었다.

「물환경보전법 시행령」도 함께 봤고, 2025년 정부 보도자료(「2025년 여름철 녹조 대응」)도 꼼꼼히 읽었다. 여기서 정부가 이미 영양염류 유입 최소화 → 녹조 신속 수거·제거 → 댐·보·하굿둑 연계 운영 → 취·정수 관리 강화라는 4단계 대응 체계를 갖추고 있다는 걸 확인했고, 우리 시나리오 설계를 이 4단계에 맞춰 재구성했다. 예를 들어 "산불 영향구간 38개소를 대상으로 pH·T-P 등 6개 항목을 집중 모니터링하고 측정주기를 월 1회에서 2회로 확대"한다는 문장에서, 정부가 이미 "사건 기반 수질 변화 흐름"(산불 → 강우 → 토사·영양염류 유입 → 수질 변화 → 녹조 위험)을 인식하고 있다는 것도 알게 됐다. 이건 우리의 강수 후 유입 시차 가설(H2)과 정확히 같은 논리 구조였다.

또한 AI 조류발생 예보가 이미 2024년 34개 지점에서 2025년 41개 지점으로 확대되고 있다는 사실도 찾아냈다. "기온·강수·일사량·수온을 분석해 일주일 후 조류발생을 예측"한다는 문장은, 우리가 하려는 것과 정확히 같은 방향이었다. 이 조사를 하면서 "우리가 완전히 새로운 걸 하는 게 아니라, 이미 진행 중인 정책 방향에 숟가락을 얹는 형태"라는 확신이 생겼고, 이게 오히려 발표에서 설득력을 높이는 포인트가 됐다.

무엇을 예측할지부터 정확히 정의하기

모델을 짜기 전에 의외로 오래 붙잡고 있던 질문이 "정확히 뭘 예측할 것인가"였다. 조류경보제의 행정 판단 기준은 결국 유해남조류 세포수이기 때문에, Chl-a나 수온 같은 간접 지표를 타깃으로 삼으면 모델이 아무리 정확해도 실제 의사결정과 바로 연결되지 않는다. 그래서 Microcystis·Anabaena·Oscillatoria·Aphanizomenon 4종의 세포수 합계, 즉 법정 경보 기준과 직접 맞닿아 있는 유해남조류_세포수를 최종 타깃으로 잡았다.

회귀 타깃은 현재 세포수가 아니라 next_log_cells, 즉 다음 채수 시점 세포수를 log10(cells + 1)로 변환한 값으로 정의했다. 현재 세포수를 맞히는 모델은 이미 관측된 상태를 재확인하는 수준에 그치지만, 우리 목적은 오늘까지의 정보로 다음 시점(약 7일 후)의 위험을 먼저 알려주는 것이었다. 로그 변환을 쓴 이유는 세포수가 평상시엔 낮다가 여름철 특정 시기에 수천~수만 단위로 튀는 치우친 분포를 갖기 때문인데, 이렇게 하면 0도 안전하게 처리하면서 급증 구간의 영향을 완화할 수 있고, 예측 후에는 다시 cells/mL 단위로 복원해 현장 기준과 비교할 수 있었다.

분류 타깃은 next_alert_binary, 다음 채수 시점 예측 세포수가 관심 기준인 1,000 cells/mL 이상인지를 나타내는 이진값으로 정의했다. 미발령·관심·경계·대발생 4단계를 한 번에 분류하는 다중분류 대신 이진분류로 좁힌 이유는, 경계·대발생 표본이 상대적으로 적어서 다중분류로 쪼개면 학습이 불안정해질 위험이 있었고, 무엇보다 실무에서 가장 먼저 필요한 질문이 "다음 채수 때 관심 이상으로 넘어갈 가능성이 있는가"였기 때문이다.

마지막으로 previous_exceeded(직전 채수가 기준을 넘었는지)를 예측 결과와 함께 보는 것도 중요한 설계였다. 조류경보제 자체가 한 번 넘었다고 바로 확정되는 게 아니라 2회 연속 초과를 발령 조건으로 삼기 때문에, 직전 실측이 기준을 넘었는지와 다음 시점 예측이 기준을 넘는지를 함께 봐야 operational_alert_candidate(운영상 발령 후보)를 제대로 판단할 수 있었다.

가설을 먼저 세우고, 데이터로 검증하기

이 모든 조사를 바탕으로 다섯 개의 검증 가능한 가설을 세웠다. 그냥 "녹조가 늘어날 것이다" 수준이 아니라, 조건과 수치를 구체적으로 명시했다.

각 가설을 실제 데이터에서 Risk Ratio와 Fisher's exact test로 검증했다. 결과를 표로 정리하면 다음과 같다.

H4가 통계적으로 유의하지 않게 나온 게 개인적으로 제일 흥미로웠다. "물이 고이면 녹조가 생긴다"는 직관은 워낙 당연해 보이는데, 막상 단독 요인으로는 유의성이 안 나왔다. 그래서 우리는 정체 조건을 독립 요인이 아니라 고수온·저풍속·종별 우점 변화와 결합될 때만 의미 있는 보조 신호로 재정의했다. 데이터가 우리 예상을 배신했을 때, 그걸 억지로 끼워 맞추지 않고 "Not Supported"로 정직하게 보고서에 적은 것 — 이게 이번 프로젝트에서 스스로 가장 뿌듯했던 부분이다.

모델링

이상치를 다루는 방식부터 다시 생각해야 했다

Before	After
일반적인 데이터 분석이라면 극단값은 노이즈로 취급해서 제거하는 게 맞다. 그런데 우리 문제는 정반대였다. 세포수가 만 단위, 십만 단위로 튀는 구간이야말로 경보가 필요한 바로 그 순간이다. 이상치를 지우면 모델이 정작 맞혀야 할 걸 놓치게 된다.

그래서 타깃부터 next_log_cells = log10(다음 시점 세포수 + 1)로 로그 변환해서 왜도가 심한 분포를 완화했다. 회귀 후보 모델에는 이상치에 강한 HuberRegressor를 포함시켰는데, 이건 튜닝 과정도 나름 길었다. 처음엔 기본 설정으로 RMSE 0.7070이 나왔는데, epsilon=2.5, alpha=0.0, max_iter=3000, tol=0.00001, scaler=robust로 파라미터를 조정하니 RMSE가 0.6695까지 떨어졌다. 이후 Stacking Ensemble에 HuberRegressor를 추가로 포함시키자 최종 RMSE가 0.6554까지 개선됐다.

강수량 관련 컬럼(daily_rain, rain_3d_sum, rain_7d_sum, rain_14d_sum)은 평상시엔 0에 수렴하다가 태풍·집중호우 시 극단적 이상치를 갖는 왜도 심한 분포였다. 이런 컬럼엔 중앙값과 사분위수 범위(IQR)를 쓰는 RobustScaler를 적용했고, 반대로 기온·바람·일사량처럼 물리적 상하한이 비교적 일정한 변수엔 MinMaxScaler를 적용해서 특정 변수의 단위 크기가 학습을 왜곡하지 않도록 했다.

최종 모델 구조

최종적으로는 LightGBM, XGBoost, RandomForest, HistGradientBoosting, CatBoost, HuberRegressor를 베이스 모델로 하고 RidgeCV를 메타 모델로 쌓은 Stacking Ensemble 구조를 채택했다. 트리 기반 모델은 비선형 조건과 변수 간 상호작용을 잘 잡아내고, HuberRegressor는 이상치에 강한 안정적 방향성을 제공하며, RidgeCV는 이 예측들을 다시 안정적인 선형 결합으로 정리해 과적합을 완화하는 역할을 맡았다.

분류 모델도 같은 논리로 여러 모델의 확률 예측(predict_proba)을 LogisticRegression이 최종 종합하는 StackingClassifier를 썼다. 여기서 Logistic Regression은 단순 분류기가 아니라, 여러 모델이 계산한 위험 확률을 운영 관점에서 최종 정리하는 의사결정 레이어 역할이었다.

분류 모델(RandomForest 기준)은 Accuracy 95.6%, Precision 90.7%, Recall 100.0%, F1 0.951이 나왔다. 검증 데이터 기준 실제 관심 기준 이상 사례 137건을 하나도 놓치지 않았다(False Negative = 0). Binomial test 기준 p-value는 1.81e-56으로, 이 결과가 우연히 다수 클래스를 찍어서 나온 게 아니라는 것도 확인했다.

지점별 예측 오차(MAE, log 스케일)도 따로 확인했는데, 추동 0.447, 회남 0.547, 문의 0.438로 회남이 상대적으로 오차가 컸다. 상류에 위치한 회남이 강우 직후 변동성이 가장 크기 때문으로 해석했다.

SHAP으로 설명 가능성 확보하기

모델 성능만큼 신경 쓴 게 "왜 위험하다고 판단했는지"를 설명하는 것이었다. XGBoost, LightGBM, CatBoost, RandomForest 계열은 SHAP 기반 해석과 잘 연결됐다. 예를 들어 "강우 증가 → 영양염류 유입 증가 → 체류시간 증가 및 수온 상승 → 남조류 증식 → 경보 위험 증가"라는 환경 흐름을 feature contribution 형태로 설명할 수 있도록 설계했다. 관리자가 "위험하다/아니다"만 보는 게 아니라, "왜 위험한지"와 "어떤 대응이 필요한지"까지 함께 이해할 수 있게 만드는 게 목표였다.

예상 밖의 발견들

모델을 다 만들고 나서 데이터를 다시 들여다보다가, 애초에 의도하지 않았던 인사이트 두 개를 발견했다.

1. 연속 초과 확률이 88.1%였다. 직전 채수에서 관심 기준(1,000 cells/mL)을 넘긴 지점은, 다음 채수에서도 88.1%(318/361건) 확률로 다시 기준을 넘겼다. 반대로 직전에 기준 미달이었던 경우 다음 시점 초과 확률은 3.5%(43/1215건)에 불과했다. 즉, 조류경보제의 "2회 연속 초과" 발령 기준 자체가, 이미 통계적으로 상당히 예측 가능한 흐름을 그대로 기다리는 구조라는 뜻이었다. 우리는 이걸 근거로 "첫 초과 시점을 단순 관찰값이 아니라 조기 경보 신호로 활용하자"는 제안을 만들었다.

2. 종별 기여도와 출현 빈도가 정반대였다. 전체 세포수 총량 기준으로는 Microcystis가 84.9%(4,117,642)를 차지해 압도적이었다. 그런데 출현 빈도로만 보면 Aphanizomenon이 73.3%(683건)로 오히려 더 자주 나타났다(총량 기여도는 7.0%에 불과했는데도). Microcystis는 65.1%(607건) 빈도로 두 번째였다. 이건 "유해남조류 4종을 합산 관리하는" 현행 방식이 종별 생태 특성 차이를 가려버릴 수 있다는 뜻이었다. 우리는 이걸 "법정 기준의 4종 합산 관리는 유지하되, 예측 모델이 7일 후 예상한 우점종의 생태적 특성에 맞춰 현장 대응 시나리오를 다각화해야 한다"는 제안으로 연결했다.

시나리오 설계: 예측을 현장 언어로 바꾸기

예측값 하나만 던져주면 현장 담당자는 다시 매뉴얼, 채수 기준, 수문 상태, 기상 조건을 따로 확인해야 한다. 그래서 시나리오를 예측값과 현장 대응을 잇는 번역기로 설계했다. 기준은 네 가지 축이었다.

1. 행정 경보 기준: 관심(1,000)·경계(10,000)·조류대발생(1,000,000) 기준에 직접 연결되는 "관심 발령 후보", "경계 발령 후보", "조류대발생 감시"
2. 발생 메커니즘: 앞서 정리한 4대 메커니즘에 대응하는 "수온 20도 이상 계절 감시", "고온·고일사 성장 촉진", "강우 이후 영양염류 유입", "수체 정체·성층 위험"
3. 공간 전파 구조: 회남의 선행 위험이 다른 수역에 영향을 줄 수 있다는 H3 가설을 반영한 "회남 선행 전파 관찰"
4. 운영 단계: 아직 발령 후보는 아니지만 접근 중인 "관심 기준 접근", 하향 추세인 "하향·해제 관찰", 위험 신호가 없는 "일반 안정"

전체 기간에 대해 시나리오를 생성해보니 일반 안정이 823행으로 가장 많았고, 관심 발령 후보 271행, 관심 기준 접근 142행, 수온 20도 이상 계절 감시 71행, 경계 발령 후보 63행, 회남 선행 전파 관찰 8행 순이었다. 각 시나리오에는 실제 대응 초안도 함께 붙였는데, 예를 들어 "경계 발령 후보"에는 "주 2회 이상 채수 체계, 정수처리 강화, 취수 수심 조정, 물순환설비 가동, 조류 제거 장비 준비 여부를 우선 확인"이라는 식으로 정부 자료(2025년 녹조 대응 보도자료, 조류제거물질 사용지침)에 나온 실제 대응 수단을 그대로 연결했다.

LLM 에이전트까지 고민했던 이유

사실 이 프로젝트 초반 아이디어 회의에서는 더 큰 그림을 그리고 있었다. 출발점은 "기존 방식의 한계"에 대한 문제의식이었다. AI가 "7일 뒤 추동 수역 세포수 15,000cells/mL 예상"이라는 숫자만 던져주면, 실무자는 다시 매뉴얼을 찾아보고 현재 방류량을 확인한 뒤 직접 대응 방안을 고민해야 한다. 지금도 대응 체계가 완전히 자동화되지 못해서 과거 자료와 육안 확인에 의존하는 부분이 많다고 판단했다. 그래서 우리는 "AI가 수치 예측뿐 아니라 원인을 스스로 해석하고, 구체적인 관리 지시서까지 자동 생성하면 어떨까"라는 질문을 던졌다. 단순히 "예측하는 모델"이 아니라, 예측 결과를 스스로 해석하고 관리 지시서까지 자동 생성하는 자율형 에이전트를 만들면 어떨까 하는 논의였다.

정량 예측(회귀/분류) → SHAP 기반 원인 해석 → LLM이 이걸 자연어 관리 지시서로 변환하는 파이프라인이었다. 실제 최종 산출물에는 llm_publisher.py라는 스크립트로 이 개념을 일부 구현해뒀다. 예측 결과와 시나리오를 LLM 프롬프트 형태로 정리해서 payload, prompt, 샘플 CSV를 자동 생성하는 기능이다. 시간 관계상 이 부분을 완전히 실전 수준까지 다듬지는 못했지만, "AI가 판단 근거까지 설명하는 구조"를 지향했다는 점에서 팀 내부적으로는 의미 있는 시도였다고 생각한다.

B/C 분석: 숫자로 설득하기

기술적으로 그럴듯한 모델이라도, 결국 공공기관 담당자를 설득하려면 "그래서 이게 얼마나 이득인가"를 숫자로 보여줘야 했다. 「정수장 조류 대응 가이드라인」 63페이지에 나온 공식 비용 산정 기준을 그대로 가져왔다.

• 실시간 자동분석시스템 비용: 약 1.5억 원/10년 (구입비 5천만원 + 운영비 1억원/10년)
• 분말활성탄 절감액: 정수용량 1,000,000㎥/일 × 20mg/L × 90일 × 1,500천원/톤 × 20% 절감 = 약 5.4억 원/년
• 오존 처리비 절감액: 1,000,000㎥/일 × 2.5원/㎥ × 90일 × 20% 절감 = 약 0.45억 원/년

여기에 예측 기반 조기대응(사전 탐지 18건 × 평균 4일 × 1일당 대응가치 50만원 = 3,600만원), 미탐 감소(6건 × 건당 500만원 = 3,000만원)를 편익에 더하고, 늘어난 오경보 비용(4건 × 건당 80만원 = -320만원)을 차감해서 최종 계산을 했다.

B/C = 총편익 64.78억 원 / 총비용 3.5억 원 ≈ 18.51

1원을 투입하면 약 18.51원의 편익이 발생할 수 있는 구조라는 계산이 나왔다. 다만 이건 확정된 실측 결과가 아니라 "이런 방식으로 정량화할 수 있다"는 프레임을 제시한 것일 뿐이라는 점을 보고서에 분명히 명시했다. 실제 대청댐 운영자료 없이 부풀린 숫자로 포장하고 싶지 않았고, 최종 B/C는 관계기관의 조류예찰·정수처리·방제장비·경보 단계별 운영비 자료를 연계해 재산정해야 한다는 단서를 달았다.

리스크도 먼저 고민했다

AI 예측이 잘못 쓰이면 오히려 해가 될 수 있다는 것도 처음부터 인지하고 있었다. 그래서 세 가지 리스크 관리 방안을 별도로 정리했다.

1. 오해 방지: 예측 결과가 공식 경보나 수돗물 안전성 문제로 오해되지 않도록, 외부 안내 시에는 예측 위험도·실제 관측값·공식 경보 단계를 명확히 구분해서 제공한다.
2. 권한 분리: 조류경보 발령과 행정 조치 권한은 기존 조류경보제 운영 절차에 그대로 유지한다. AI는 자동 발령이나 자동 조치를 하지 않고, 사전 예찰과 대응 준비를 보조하는 도구로 역할을 제한한다.
3. 편향성 관리: 전체 정확도만 보면 특정 수역의 미탐이나 계절별 오경보를 놓칠 수 있어서, 지점별 재현율 편차·계절별 오경보율·경보 단계별 미탐률을 따로 점검한다.

발표, 그리고 본선까지

서류 심사를 통과하고 본선 발표 기회를 얻었다. 발표는 여섯 파트로 구성했다.

1. 문제 정의 — 녹조 대응은 왜 AI 예측 단계로 진입해야 하는가
2. 분석 목표와 핵심 가설(H1~H5)
3. 데이터 융합과 Feature 설계
4. AX 예측 모델링 프레임워크
5. 검증 결과와 대응 시나리오
6. 정책 활용성과 운영 리스크 관리

발표 자료 첫 장에 넣은 문제의식은 "경보보다 빠른 준비"였고, 마지막 장에 넣은 문장은 이거였다.

"AI가 경보를 대신 내리는 것이 아니라, 공공기관이 더 빠르고 근거 있게 준비하도록 돕는 것입니다."

우리 스스로도 이 예측 시스템이 만능이 아니라는 걸 인지하고 있고, 그 안에서 실질적으로 기여할 수 있는 지점이 어디인지를 명확히 하고 싶었다. 결과적으로 본선까지는 올라갔지만 최종 수상에는 들지 못했다. 다른 팀들의 결과물과 심사 흐름을 지켜보면서 아쉬운 지점도 있었지만, 그것과 별개로 이 프로젝트를 준비하며 배운 것들은 확실히 남았다.

본선 질의응답에서 배울점

"그래서 수질 자체와 녹조 발생의 상관관계는 어떻게 확인했나요?"

이 질문에는 제대로 답하지 못했다. 우리가 준비한 건 유해남조류 세포수를 타깃으로 놓고 기상·수문 조건(수온, 강수량, 유입량·방류량, 체류시간 proxy)과의 관계를 Risk Ratio와 Fisher's exact test로 검증한 가설들뿐이었다. 정작 심사위원이 물은 건 그 이전 단계, 즉 pH·DO·탁도·Chl-a 같은 수질 지표들 자체가 서로 어떻게 얽혀 있고, 그게 녹조 발생과 어떤 상관관계를 갖는지였다. 이 부분은 따로 분석해둔 자료가 없었다. 수질 항목 간의 관계를 정량적으로 파고든 근거도 준비되어 있지 않았다. 돌이켜보면 남조류 발생 메커니즘 공부에 밀려 정작 우리가 제공받은 수질 데이터 자체를 상관행렬이나 다중공선성 관점에서 제대로 들여다보지 않았던 게 원인이지 않을까 생각한다.

"회남·추동·문의는 위치도, 특성도 다른데, 그 차이를 모델이 정말 반영하고 있나요?"

이 질문에는 그나마 자신 있게 답할 수 있었다. 회남은 상류 유입부라 강수·유입량에 민감하고, 추동은 취수탑이 있는 정체 수역이라 수온·일조량에 민감하며, 문의는 댐 본체 근처라 방류량에 민감하다는 지점별 특성을 설명했다. 그리고 이걸 그냥 설명으로 끝낸 게 아니라 loc_encoded(지점 코드), loc_flow_order(흐름 순서), hoenam_pressure_for_downstream(회남 지점이 기준을 초과했을 때 하류 수역에 주는 압력 신호) 같은 파생 변수로 실제 모델에 반영했다는 것, 그리고 H3(수역 간 선행 신호) 가설이 Risk Ratio 7.16배로 가장 강하게 지지됐다는 결과까지 근거로 제시했다. 다만 심사위원 한 분이 "그러면 회남에서 감지된 신호가 정확히 며칠 뒤에 추동·문의에 도달하는지 지연 시간까지 정량적으로 특정했느냐"고 물었을 때는 ...할 말이 없었다. 우리는 "선행 신호가 있었던 기간"을 뭉뚱그려 정의했을 뿐, 회남에서 문의까지 물리적으로 며칠이 걸리는지 유속 기반으로 계산한 값은 없었다.

"지점이 세 곳인데 모델은 왜 하나인가요? 시계열 특성이 지점마다 다를 텐데요."

사실 초기 아이디어 회의 때는 회남·추동·문의를 완전히 독립된 세 개의 모델로 학습시키는 방안도 논의했었다. 지점마다 오염 발생 메커니즘 자체가 다르니, 하나의 모델에 지점을 욱여넣기보다 지점별로 가중치와 피처 중요도가 다른 세 개를 따로 학습시키는 게 이론적으로는 더 맞는 방향성이었다고 지금은 생각이든다. 그런데 실제로는 각 지점당 확보되는 채수 샘플 수가 전체 데이터를 3분의 1로 쪼개면 급격히 줄어드는 문제가 있었고, 결국 시간과 데이터 규모의 한계 속에서 loc_encoded와 지점 관련 파생 변수를 넣은 단일 통합 모델로 방향을 틀었다. 심사위원은 정확히 이 지점을 짚었다. "그럼 세 지점을 하나로 합쳐서 학습시켰을 때, 각 지점 고유의 계절적 패턴이나 자기상관 구조가 서로 다른데 단일 모델이 그 차이를 온전히 학습했다고 확신할 수 있느냐"는 질문이었다. 변명같지만.. 정확한 공공데이터가 없었는데..

돌아보며

결과는 본선 진출, 최종 수상은 못 했지만 많은것을 얻게해준 공모전이였다.

이번 대회를 준비하면서 가장 크게 느낀 건, 좋은 AI 프로젝트는 모델 성능이 전부가 아니라는 것이다. 우리 팀이 가장 많은 시간을 쓴 곳은 사실 모델을 하이퍼파라미터 튜닝하는 것이 아니라, 조류경보제 운영 매뉴얼과 관련 법령을 조문 단위로 읽으며 도메인 지식을 쌓고, 남조류 생물학 논문을 찾아 메커니즘을 이해하고, 대청호가 다른 호수와 어떻게 다른지 비교 연구를 뒤지는 과정이었다. AI 모델은 이 모든 조사의 결과물을 검증하는 단계에 불과하다.

특히 가설을 세우고 통계적으로 검증하는 단계가 가장 값졌다. H4처럼 예상과 다르게 기각에 가까운 결과가 나왔을 때, 그걸 억지로 끼워 맞추지 않고 "보조 신호"로 정직하게 재정의한 게 오히려 신뢰도를 높이는 방향이었다고 생각한다.

열두 개의 지정과제 중에서 굳이 수자원공사의 조류경보 문제를 고른 것도 돌이켜보면 잘한 선택이었다. 수자원공사가 대청댐 수질·수문 데이터를 10개년치나 통째로 있어 데이터적인 면에서는 수훨했고 그걸가지고 "왜 이 시기에 녹조가 늘어나는가"로 바꾸는 건 논문을 찾고, 기상 데이터를 보태고, 법령을 뒤지는 우리 몫이었다. 대청호 하나를 정말 깊게 파고드는 과정에서 법령 조문, 정부 보도자료, 국내외 논문까지 — 리서치의 폭과 깊이 모두에서 이전에 해본 어떤 프로젝트보다 재밌게 공부한 느낌이든다.

수상까지 이어지지는 못했지만, 다애님과 현준님과 함께 프로젝트를 준비한 시간 자체가 너무너무 값진 경험이였다. 일주일에 2~3회씩 꾸준히 회의를 진행하고, 새벽까지 함께 개발하고 자신이 찾은분을 공유하고, 프로젝트 이야기는 물론 사소한 일상 이야기까지 나누면서 자연스럽게 팀워크를 쌓을 수 있었다. 공모전을 준비하는 과정에서 힘든 순간도 있었지만, 돌이켜보면 좋은 경험으로 남은 기억이 훨씬 많다. 이후에도 우리 춘배팀은 여기서 멈추지 않았다. 함께 제4회 문화체육관광 인공지능·데이터 활용 공모전 개발 부문에도 도전했고 오늘일자로 결과가 나왔다. 기대만큼 만족스럽지는 않았지만, 이를 계기로 앞으로도 9월에 있을 해커톤을 함께하기로 했다. 무엇보다 공모전의 성과를 떠나 서로 배우고 성장할 수 있는 좋은 사람들을 만났다는 점이 이번 경험에서 가장 큰 의미였다고 생각한다.

고생하셨습니다 @다애,현준

참고 자료

프로젝트가 궁금하다면 -> GitHub

법령·정책

• 「조류예측 및 수질관리협의회에 관한 규정」
• 「물환경보전법 시행령」
• 「정수장 조류 대응 가이드라인」(국립환경과학원, 2017)
• 「조류제거물질 사용지침」
• 기후에너지환경부, 「관계부처 협업으로 여름철 녹조발생에 체계적 대응」 보도자료
• 기후에너지환경부, 「2025년 여름철 녹조 대응」 보도자료 (야적퇴비 관리, AI 조류발생 예보 지점 확대 34→41개 등)
• 대한민국 정책브리핑, 「녹조 수질검사·정보공개 전면 개편」(2025)
• 금강청, 「대청호 문의 수역 조류경보 관심 단계 발령」 보도자료

  데이터

• 한국수자원공사 대청댐 운영 수문정보, 수질·조류 관측자료
• 기상청 종관기상관측(ASOS) / 방재기상관측(AWS) Open API
• 공공데이터포털(data.go.kr)

  논문

• Liu et al., 2011, The effects of temperature and nutrient ratios on Microcystis blooms in Lake Taihu, China
• De Nobel et al., 1997, Competition for phosphorus between Anabaena and Aphanizomenon
• Van Liere & Mur, 1980, Occurrence of Oscillatoria agardhii
• Recknagel et al., 2025, Early warning of harmful cyanobacteria blooms based on high frequency in situ monitoring and intelligible machine learning modelling: The case study of Lake Müggelsee (Germany)
• 「대청호 상류유역의 오염원 현황과 수질관리 방안에 관한 연구: 안남천과 안내천을 중심으로」
• 「소옥천 유역의 오염제어 대책에 따른 대청호 조류저감 효과 분석」

11주차는 동원예비군 훈련에 참여하면서 미니 프로젝트를 진행하지 못해 곧바로 12주차 학습을 진행하게 되었다. 원래는 이전에 프론트엔드로 구현했던 프로젝트를 Spring을 활용하여 데이터베이스와 연동하고, json-server 기반의 임시 백엔드를 실제 서버 환경으로 대체하는 내용을 다룰 예정이었다. 하지만 일정상 해당 프로젝트를 진행하지 못했기 때문에 이번 글에서는 프로젝트 대신 학습한 내용을 정리하고자 한다. 이번 글은 클라우드 환경에서 자주 사용되는 핵심 서비스와 k8s, 그리고 AWS 기반 CI/CD 파이프라인을 중심으로 정리한 학습 기록이다.

다루는 범위:

• AWS 인프라: EC2, S3, EBS, VPC, ELB, Auto Scaling, Route53, CloudFront
• AWS 데이터베이스: RDS, Aurora, DynamoDB, ElastiCache
• AWS 보안·네트워크: IAM, Organizations, VPN, Direct Connect
• 컨테이너: Docker, VM vs Container, MSA
• Kubernetes: 클러스터 구성, Pod/RS/Deployment/Service/Ingress/HPA, ConfigMap/Secret, Volume
• CI/CD on AWS: CodePipeline, CodeBuild, CodeDeploy, 배포 전략 7가지
• 고가용성·DR: ELB+Auto Scaling, Route53 Failover, 재해복구 전략

1. 클라우드의 등장 배경과 AWS 글로벌 인프라

1.1 왜 클라우드가 필요했나?

예전 On-Premise 방식을 생각해보자. 서비스를 운영하려면 서버를 직접 구매해야 했다. 서버는 최대 트래픽 기준으로 사야 했기 때문에, 평소에는 비싼 장비가 놀고 있었다. 반대로 예상치 못한 트래픽 폭증이 오면 서버가 터졌다.

클라우드의 핵심 이점은 세 가지로 요약된다.

• 민첩성: 새 기능/서비스를 빠르게 출시할 수 있음
• 비용 최적화: 사용한 만큼만 지불, 불필요한 서버 유지 비용 없음
• 보안 취약성 최소화: AWS가 물리적 인프라 보안을 직접 담당

1.2 AWS vs Azure 비교

1.3 AWS 글로벌 인프라 — 리전, 가용 영역, 엣지

AWS 글로벌 인프라는 리전 → 가용 영역 → 엣지 로케이션의 3단계 계층 구조로 구성된다.

리전 (Region)
├── 가용 영역 AZ-1 (데이터 센터 × n)
├── 가용 영역 AZ-2 (데이터 센터 × n)
└── 가용 영역 AZ-3 (데이터 센터 × n)

엣지 로케이션 (전 세계 수백 곳)
Local Zone (대도시 근처 mini 리전)

리전(Region)

• AWS가 전 세계에서 데이터 센터를 클러스터링하는 물리적 위치
• 각 리전은 완전히 독립적 — 서울 리전 장애가 도쿄 리전에 영향 없음
• 서울 리전 코드: ap-northeast-2

리전 선택 시 4가지 고려사항:

1. 거버넌스: 금융, 의료 데이터는 국내 데이터센터에 보관해야 하는 법적 요건이 있음
2. 지연 시간: 사용자와 가까울수록 응답이 빠름
3. 서비스 가용성: 모든 AWS 서비스가 모든 리전에 출시되지 않음
4. 비용: 리전마다 EC2 요금이 다름

가용 영역(AZ, Availability Zone)

• 리전 내에서 서로 격리된 물리적 데이터 센터 그룹
• 화재, 정전, 자연재해로부터 독립 운영
• AZ끼리는 고속 프라이빗 전용 링크로 연결됨
• 한 AZ가 다운돼도 다른 AZ가 서비스 지속 → 고가용성(HA)의 핵심

엣지 로케이션

• 전 세계 주요 도시에 배치된 캐싱 거점 (200개 이상)
• CloudFront(CDN), Route53에서 사용
• 사용자 가장 가까운 곳에서 콘텐츠를 서빙해 지연 시간을 최소화

Local Zone

• 리전을 사용자 근처로 확장한 소형 인프라
• 실시간 게임, 라이브 스트리밍, AR/VR 같은 지연 시간에 민감한 워크로드용

2. 클라우드 네이티브 — DevOps와 CI/CD

2.1 Cloud Native란?

클라우드 네이티브는 단순히 "클라우드에서 실행한다"는 의미가 아니다. 처음부터 클라우드 환경을 최대한 활용할 수 있게 설계·개발·운영하는 방법론이다.

기존 앱을 클라우드에 그냥 옮기는 건 Lift & Shift(이전·재호스팅). 클라우드 네이티브의 핵심 요소 4가지:

2.2 DevOps — 개발팀과 운영팀의 벽을 허물다

DevOps 이전의 전통적인 개발 환경에는 구조적인 충돌이 있었다.

이 구조적 갈등으로 배포 주기가 길어지고, 장애 발생 시 책임 소재가 불분명해진다. DevOps는 자동화와 협업 문화를 통해 이 문제를 해결한다.

2.3 CI/CD — 자동화된 배포 파이프라인

Code → Build → Test → Release → Deploy → Monitor
  ↑                                             |
  └──────────── 피드백 루프 ────────────────────┘

CI (Continuous Integration, 지속적 통합)

• 코드 변경 사항을 주기적으로(매일 또는 여러 번) 빈번하게 merge
• merge 시 자동으로 빌드와 테스트 실행
• 통합 문제를 조기에 발견

CD (Continuous Delivery/Deployment, 지속적 배포)

• 테스트를 통과한 코드를 자동으로 스테이징 또는 운영 환경에 배포
• Continuous Delivery: 운영 배포 전 수동 승인 포함
• Continuous Deployment: 완전 자동화, 승인 없이 즉시 배포

CI/CD 도구 예시: Jenkins, GitLab CI/CD, GitHub Actions, AWS CodePipeline, ArgoCD

CI/CD 도입 효과: 배포 주기 단축, 버그 조기 발견, 팀 생산성 향상, 릴리즈 위험 감소

3. 클라우드 서비스 모델 — IaaS, PaaS, SaaS

온프레미스 (모두 직접 관리)
  Networking / Storage / Server / OS / Middleware / Runtime / Application

IaaS (OS부터 직접 관리)
  CSP 제공: Networking / Storage / Server
  직접 관리: OS / Middleware / Runtime / Application

PaaS (애플리케이션만 관리)
  CSP 제공: Networking / Storage / Server / OS / Middleware / Runtime
  직접 관리: Application

SaaS (관리 없음, 사용만)
  CSP 제공: 전부

AWS 컴퓨팅 서비스 출시 연표:

• 2006년: EC2 — 가상화 기반 IaaS (AWS 최초 서비스)
• 2014년: ECS — 컨테이너 오케스트레이션 (re:Invent 2014)
• 2014년: Lambda — 서버리스 Function-as-a-Service (re:Invent 2014)
• 2016년: Lightsail — 단순화된 VPS 서비스
• 2017년: Fargate — 서버리스 컨테이너 실행 (re:Invent 2017)
• 2018년: EKS — 관리형 Kubernetes (re:Invent 2017 발표, 2018 GA)

4. AWS EC2 — 클라우드의 가상 서버

4.1 EC2란?

EC2(Elastic Compute Cloud)는 AWS의 핵심 컴퓨팅 서비스다. 클라우드에서 안전하고 크기 조정 가능한 컴퓨팅 용량을 제공한다. 트래픽 변화에 따라 수초 만에 인스턴스를 추가하거나 제거할 수 있다.

4.2 EC2 인스턴스 생성 시 결정사항

4.3 AMI (Amazon Machine Image)

AMI는 EC2 인스턴스의 템플릿이다. 한 번 설정한 환경을 AMI로 저장해두면, 동일한 환경을 여러 인스턴스로 즉시 복제할 수 있다.

AMI 구성요소:

• 루트 볼륨 템플릿: OS, 앱 서버, 애플리케이션
• 시작 권한: 어느 AWS 계정이 이 AMI로 인스턴스를 시작할 수 있는지
• 블록 디바이스 매핑: 인스턴스 시작 시 어떤 볼륨을 연결할지

AMI를 얻는 방법:

1. AWS 제공 AMI: Ubuntu, Amazon Linux, Windows Server 등 공식 이미지
2. AWS Marketplace: 상용 소프트웨어가 사전 설치된 이미지
3. 직접 생성: 기존 인스턴스에서 커스텀 AMI 생성

AMI의 장점: 반복 가능(Repeatable), 재사용 가능(Reusable), 복구 가능(Recoverable)

4.4 인스턴스 유형 이름 읽기

인스턴스 유형 이름은 규칙이 있다.

c  7  g  n  .  2xlarge
│  │  │  │     └─── 인스턴스 크기
│  │  │  └──────── 옵션 (n = 네트워크 최적화)
│  │  └─────────── 프로세서 (g = AWS Graviton ARM)
│  └────────────── 세대 (숫자 높을수록 최신)
└───────────────── 인스턴스 패밀리

인스턴스 패밀리 상세:

최신 세대 인스턴스를 쓰는 게 유리하다 — 이전 세대 대비 성능 향상, 비용 절감, 더 나은 확장성.

4.5 테넌시와 배치 그룹

테넌시(Tenancy) — EC2가 어느 물리 서버에서 실행되는지 결정

배치 그룹(Placement Group)

4.6 사용자 데이터 (User Data)

인스턴스가 최초로 시작될 때 루트 권한으로 자동 실행되는 스크립트다. Kubernetes 설치, 웹서버 초기화 등에 활용한다.

#!/bin/bash
# Ubuntu 예시: 인스턴스 시작 시 Nginx 자동 설치
apt update -y
apt install -y nginx
systemctl start nginx
systemctl enable nginx

4.7 EC2 구매 옵션 — 비용 최적화

실전 조합 전략: 온디맨드(베이스) + Savings Plans(예측 가능한 부분) + Spot(내결함성 워크로드)

4.8 서버리스 컴퓨팅 — AWS Lambda

서버를 프로비저닝·관리할 필요 없이 코드만 올리면 이벤트 발생 시 자동 실행된다.

이벤트 소스 (S3 업로드, API Gateway 요청, DynamoDB 변경 등)
    ↓
Lambda 함수 실행 (코드)
    ↓ (선택적)
응답 반환

Lambda 특징:

• 지원 런타임: Python, Node.js, Java, Go, Ruby, C# 등
• 최대 실행 시간: 15분
• 최대 메모리: 10GB
• 요금: 요청 수 + 실행 시간 기준 (밀리초 단위)

Lambda 활용 예시:

• API Gateway + Lambda = 서버리스 REST API
• S3 업로드 이벤트 + Lambda = 이미지 리사이징 자동화
• CloudWatch 스케줄 + Lambda = 주기적 배치 작업

5. Amazon S3 — 객체 스토리지

5.1 S3 개념과 구조

Amazon S3(Simple Storage Service)는 무제한 용량의 객체 스토리지 서비스다. 파일 시스템이 아닌 Key-Value 방식으로 데이터를 저장한다.

버킷(Bucket): 최상위 컨테이너. 이름은 전 세계에서 유일해야 함.
└── 객체(Object): 실제 데이터
    ├── Key   : 객체의 전체 경로 (예: images/2024/photo.jpg)
    ├── Value : 파일 데이터 (최대 5TB)
    └── Metadata: Content-Type, ETag, 사용자 정의 태그 등

S3 주요 특성:

S3 URL 형식:

https://버킷이름.s3.리전코드.amazonaws.com/키이름
https://my-app.s3.ap-northeast-2.amazonaws.com/images/profile.jpg

5.2 S3 스토리지 클래스

데이터 접근 빈도에 따라 최적의 클래스를 선택해 비용을 절감한다.

5.3 S3 버전 관리 (Versioning)

버전 관리 활성화 시 같은 Key에 파일을 덮어써도 이전 버전이 모두 보존된다.

버전 관리 비활성: 업로드 → 덮어쓰기 → 이전 파일 영구 삭제

버전 관리 활성:
  photo.jpg 업로드   → ID: ver-001
  photo.jpg 재업로드 → ID: ver-002  (ver-001 유지)
  삭제 요청          → 삭제 마커(Delete Marker) 추가, 실제 파일 보존
  특정 버전 삭제     → 해당 ID만 삭제, 나머지 유지

• CodePipeline S3 소스 트리거에 버전 관리 활성화 필수
• 각 버전마다 별도 과금

5.4 수명 주기 정책 (Lifecycle Policy)

시간 경과에 따라 데이터를 자동으로 더 저렴한 클래스로 전환하거나 삭제한다.

업로드 → S3 Standard
    ↓ 30일 후 자동 전환
S3 Standard-IA
    ↓ 60일 후 자동 전환
S3 Glacier Flexible Retrieval
    ↓ 270일 후
자동 삭제

5.5 주요 기능

정적 웹사이트 호스팅: HTML, CSS, JS 파일을 S3에서 직접 서빙. 별도 웹 서버 불필요.

Presigned URL: 프라이빗 버킷 객체에 대한 시간 제한 접근 URL 생성.

import boto3
s3 = boto3.client('s3')
url = s3.generate_presigned_url(
    'get_object',
    Params={'Bucket': 'my-bucket', 'Key': 'report.pdf'},
    ExpiresIn=3600  # 1시간 유효
)

S3 Transfer Acceleration: CloudFront 엣지 로케이션 경유로 업로드 속도 최적화. 지리적으로 먼 클라이언트에서 대용량 업로드 시 유용.

교차 리전 복제 (CRR): 다른 리전 버킷에 객체를 자동 복제. DR, 지연 시간 감소, 데이터 주권 준수 목적.

6. Amazon EBS — EC2 블록 스토리지

6.1 EBS 개념

EBS(Elastic Block Store)는 EC2 인스턴스에 연결하는 네트워크 기반 블록 스토리지다.

EC2 인스턴스 ←── 네트워크 ──→ EBS 볼륨 (독립적으로 존재)

EBS 특성:

• 독립적 생존: EC2가 종료돼도 볼륨은 유지됨 (Delete on Termination 설정에 따라)
• AZ 범위: 동일 AZ 내 EC2에만 연결 가능
• 스냅샷: S3에 증분 백업. 다른 AZ/리전으로 복사해 활용 가능
• 기본 연결: 하나의 EBS는 하나의 EC2에만 연결 (io1/io2 Multi-Attach는 예외)

6.2 EBS 볼륨 타입

gp3 vs gp2: gp3는 용량과 IOPS/처리량을 각각 독립적으로 설정 가능. 동일 성능 대비 gp3가 최대 20% 저렴하며 AWS 권장 타입.

6.3 EBS 스냅샷

스냅샷은 EBS 볼륨의 특정 시점 백업. S3에 저장되며 증분(Incremental) 방식으로 변경된 블록만 저장한다.

첫 번째 스냅샷: 전체 볼륨 저장
두 번째 스냅샷: 첫 번째 이후 변경 블록만 저장
세 번째 스냅샷: 두 번째 이후 변경 블록만 저장
(각 스냅샷은 독립적으로 복원 가능)

활용:

• 볼륨을 다른 AZ로 이동: 스냅샷 생성 → 대상 AZ에서 볼륨 복원
• 다른 리전 복사: 스냅샷 복사(Copy) → 복사된 스냅샷으로 볼륨 생성
• AMI 생성의 기반: EC2 인스턴스 상태를 AMI로 저장 시 EBS 스냅샷이 함께 생성

7. AWS 데이터베이스 서비스

7.1 관계형 vs 비관계형 — 어떤 DB를 선택할까?

7.2 Amazon RDS — 관리형 관계형 데이터베이스

RDS는 MySQL, PostgreSQL, Oracle, SQL Server, MariaDB, IBM Db2를 관리형으로 제공한다. 설치·패치·백업·복제·모니터링을 AWS가 담당한다.

관리형 서비스의 장점:

Multi-AZ 배포 — 고가용성

가용 영역 1                가용 영역 2
┌──────────────────┐      ┌──────────────────┐
│  프라이머리 DB   │      │  대기 DB (Standby) │
│  (읽기/쓰기)     │←───→│  (평상시 미사용)   │
└──────────────────┘  동기식   └──────────────────┘
       ↑                복제
    장애 발생
       ↓
  대기 DB 자동 승격
  (수분 내 복구)

• 프라이머리 DB에서 대기 DB로 동기식 복제
• 프라이머리 장애 시 → 대기 DB가 자동으로 프라이머리로 승격
• 애플리케이션은 같은 DNS 엔드포인트를 계속 사용 → 코드 변경 불필요
• 대기 DB는 읽기에 사용되지 않음 (순수 대기 목적)

읽기 전용 복제본 — 읽기 성능 향상

프라이머리 DB
(읽기/쓰기)
     │
     └── 비동기 복제
          ↓
  읽기 전용 복제본 #1  ← 리포트, 통계 쿼리
  읽기 전용 복제본 #2  ← 분석 작업
  읽기 전용 복제본 #3  ← 다른 리전 (교차 리전 복제)

• RDS당 최대 5개, Aurora는 최대 15개 읽기 전용 복제본
• 비동기 복제 — 프라이머리와 약간의 지연(lag) 존재
• Multi-AZ + 읽기 복제본을 동시에 사용 가능

7.3 Amazon Aurora — 클라우드 전용 고성능 DB

Aurora는 AWS가 처음부터 클라우드용으로 설계한 관계형 DB다. MySQL과 PostgreSQL과 호환된다.

Aurora가 특별한 이유:

Aurora DB 클러스터 구조:

클러스터 엔드포인트 (읽기/쓰기)
    │
프라이머리 인스턴스 (읽기/쓰기)
    │
    ├── Aurora 복제본 1 (읽기 전용, AZ-1)
    ├── Aurora 복제본 2 (읽기 전용, AZ-2)
    └── Aurora 복제본 3 (읽기 전용, AZ-3)

클러스터 볼륨 (3개 AZ × 2 = 6개 복사본, 자동 복구)

7.4 Amazon DynamoDB — 완전 관리형 NoSQL

서버 관리가 전혀 필요 없는 완전 관리형 키-값/문서 NoSQL 데이터베이스다.

DynamoDB 기본 구조:

테이블: Gamers
┌──────────────┬──────────────┬───────┬────────┬──────────┐
│  GamerTag    │  GameID      │ Level │ Score  │ TopScore │
│ (파티션 키)  │ (정렬 키)   │       │        │          │
├──────────────┼──────────────┼───────┼────────┼──────────┤
│ "Hammer57"   │ "PuzzleGame" │  21   │  4050  │  483610  │
│ "FluffyDuffy"│ "MysteryGame"│   5   │  1123  │   10863  │
└──────────────┴──────────────┴───────┴────────┴──────────┘

• 파티션 키(Partition Key): 데이터 분산의 기준. 고르게 분산될수록 성능이 좋음
• 정렬 키(Sort Key): 선택적. 파티션 키 + 정렬 키 = 복합 기본 키
• 속성: 나머지 데이터. 행마다 다른 속성을 가질 수 있음 (스키마 유연성)

용량 모드:

• RCU (읽기 용량 단위): 최대 4KB 항목 1회 읽기
• WCU (쓰기 용량 단위): 최대 1KB 항목 1회 쓰기

읽기 일관성:

7.5 캐싱 전략 — ElastiCache

DB에 반복적으로 같은 쿼리를 날리는 건 낭비다. 자주 읽히는 데이터를 메모리에 캐싱해두면 응답 시간을 대폭 단축할 수 있다.

ElastiCache는 Redis와 Memcached를 관리형으로 제공한다.

어떤 데이터를 캐싱해야 할까?

• 쿼리가 느리고 비용이 많이 드는 데이터
• 자주 읽히지만 자주 바뀌지 않는 데이터 (상품 목록, 사용자 프로필 등)

캐싱 전략 1 — Lazy Loading (지연 로딩)

1. 요청 → 캐시 확인
2. 캐시 HIT → 즉시 반환 (빠름)
   캐시 MISS → DB 조회 → 캐시에 저장 → 반환 (느림, but 다음엔 빠름)

장점: 캐시에는 실제로 요청된 데이터만 저장됨 단점: 첫 번째 요청은 항상 느림 (Cache Miss)

캐싱 전략 2 — Write-Through (쓰기 시 동기화)

쓰기 요청
    → DB에 저장
    → 캐시에도 즉시 저장

장점: 캐시 데이터가 항상 최신 단점: 모든 쓰기 작업에서 캐시도 업데이트 (오버헤드)

캐시 만료 — TTL (Time To Live)

# Redis 예시: 1시간 후 자동 만료
cache.set("user:123", user_data, ex=3600)

캐시 메모리가 가득 차면 제거 정책(Eviction Policy) 적용:

• LRU (Least Recently Used): 가장 오래 사용되지 않은 데이터 제거
• LFU (Least Frequently Used): 사용 빈도가 가장 낮은 데이터 제거
• TTL 기반: TTL이 가장 짧은 데이터 제거

8. AWS 네트워크 — VPC 완전 이해

8.1 VPC (Virtual Private Cloud)

VPC는 AWS 클라우드 안에 사용자가 직접 정의하는 격리된 가상 네트워크다. 단일 AWS 리전에 연결된다.

VPC 특징:

• 워크로드를 논리적으로 격리
• 리소스에 사용자 정의 액세스 제어와 보안 설정 적용
• 기본 VPC가 이미 리전마다 생성되어 있음

8.2 IP 주소와 CIDR

CIDR(Classless Inter-Domain Routing) — IP 주소 범위를 지정하는 표기법

10.22.0.0/16
│         └── 앞 16비트를 네트워크 주소로 예약
└──────────── IPv4 주소

범위: 10.22.0.0 ~ 10.22.255.255 (65,536개 IP)

AWS는 각 서브넷에서 5개의 IP를 예약한다 (네트워크 주소, VPC 라우터, DNS, 미래 사용, 브로드캐스트).

8.3 서브넷 — 퍼블릭과 프라이빗

서브넷은 VPC CIDR 블록의 하위 집합이다. 각 서브넷은 하나의 가용 영역에 속한다.

VPC: 172.31.0.0/16 (서울 리전)
├── AZ-1 (ap-northeast-2a)
│   ├── 퍼블릭 서브넷: 172.31.0.0/20   ← 웹 서버, ALB
│   └── 프라이빗 서브넷: 172.31.32.0/20 ← 앱 서버, DB
└── AZ-2 (ap-northeast-2b)
    ├── 퍼블릭 서브넷: 172.31.16.0/20
    └── 프라이빗 서브넷: 172.31.48.0/20

퍼블릭 서브넷: 인터넷에서 직접 접근 가능 → 웹 서버, Load Balancer 프라이빗 서브넷: 인터넷에서 직접 접근 불가 → 앱 서버, 데이터베이스

8.4 인터넷 게이트웨이 (IGW)

인터넷 게이트웨이는 VPC와 인터넷 사이의 관문이다. 퍼블릭 서브넷의 인스턴스가 인터넷과 통신하려면 반드시 필요하다.

IGW 역할:

1. VPC 리소스와 인터넷 간의 통신 허용
2. NAT(Network Address Translation) 수행 — 프라이빗 IP ↔ 퍼블릭 IP 변환

퍼블릭 서브넷 조건 (세 가지 모두 필요):

1. VPC에 IGW 연결
2. 라우팅 테이블에 0.0.0.0/0 → IGW 경로 추가
3. 인스턴스에 퍼블릭 IP 할당

8.5 라우팅 테이블

라우팅 테이블은 네트워크 트래픽 경로를 결정하는 규칙 집합이다.

퍼블릭 서브넷 라우팅 테이블:

Destination      Target
172.31.0.0/16    local          ← VPC 내부 통신
0.0.0.0/0        igw-xxxxx      ← 모든 외부 트래픽 → IGW로

프라이빗 서브넷 라우팅 테이블 (기본):

Destination      Target
172.31.0.0/16    local          ← VPC 내부 통신만 가능

프라이빗 서브넷 라우팅 테이블 (NAT 추가 시):

Destination      Target
172.31.0.0/16    local
0.0.0.0/0        nat-xxxxx      ← 외부 트래픽 → NAT GW로

8.6 NAT 게이트웨이

프라이빗 서브넷의 인스턴스가 인터넷에 아웃바운드(나가는) 통신이 필요할 때 사용한다 (소프트웨어 업데이트, 외부 API 호출 등). 단, 인바운드(들어오는) 직접 접속은 차단된다.

프라이빗 인스턴스 (172.31.32.75)
    │ 소스 IP: 172.31.32.75
    ▼
NAT 게이트웨이 (퍼블릭 서브넷에 위치)
    │ 소스 IP를 탄력적 IP(203.0.133.15)로 변환
    ▼
인터넷 게이트웨이
    │
    ▼
인터넷

NAT GW는 반드시 퍼블릭 서브넷에 위치하고, 탄력적 IP(EIP)를 부여해야 한다.

탄력적 IP(Elastic IP): 인스턴스를 재시작해도 변하지 않는 고정 공인 IP.

8.7 보안 그룹 vs 네트워크 ACL

AWS에는 두 가지 방화벽 계층이 있다.

트래픽 흐름:

인터넷
  ↓
NACL 인바운드 규칙 (서브넷 경계에서 1차 필터링)
  ↓
보안 그룹 인바운드 규칙 (인스턴스 바로 앞에서 2차 필터링)
  ↓
EC2 인스턴스
  ↓
보안 그룹 아웃바운드 규칙
  ↓
NACL 아웃바운드 규칙 (Stateless라서 명시적으로 설정 필요)
  ↓
인터넷

보안 그룹 실전 설정 예시:

웹 서버 보안 그룹 인바운드:
- HTTPS 443 / 0.0.0.0/0   ← 모든 곳에서 HTTPS 허용
- HTTP 80  / 0.0.0.0/0    ← 모든 곳에서 HTTP 허용
- SSH 22   / 내 IP만       ← 관리자 접속만 허용

앱 서버 보안 그룹 인바운드:
- TCP 8080 / 웹 서버 보안 그룹 ID  ← 웹 서버에서만 접근 허용

DB 서버 보안 그룹 인바운드:
- TCP 3306 / 앱 서버 보안 그룹 ID  ← 앱 서버에서만 MySQL 접근 허용

이렇게 보안 그룹을 서로 참조하면 IP 대신 리소스 단위로 접근을 제어할 수 있다.

9. ELB — Elastic Load Balancer

9.1 로드 밸런서 개념

ELB(Elastic Load Balancer)는 들어오는 트래픽을 여러 대상(EC2, 컨테이너, Lambda 등)에 자동 분산시키는 완전 관리형 서비스다.

클라이언트 요청
    ↓
ELB (단일 진입점 — DNS 이름 고정)
    ↓ 트래픽 분산 (라운드 로빈, 최소 연결 등)
┌───────┬───────┬───────┐
│ EC2-1 │ EC2-2 │ EC2-3 │
└───────┴───────┴───────┘

ELB 제공 기능:

• 헬스 체크: 비정상 대상을 자동으로 라우팅에서 제외 (설정한 간격마다 HTTP/TCP 확인)
• 고가용성: 여러 AZ에 걸쳐 자동 분산 (Cross-Zone Load Balancing)
• SSL/TLS 종료: ELB에서 인증서 처리, EC2는 HTTP만 처리하면 됨
• 고정 세션(Sticky Session): 동일 클라이언트를 동일 대상으로 지속 라우팅

9.2 ELB 유형 4가지

9.3 ALB — Application Load Balancer

L7 레벨에서 동작하므로 URL 경로, 호스트 헤더, HTTP 메서드 등으로 트래픽을 세밀하게 분기할 수 있다.

ALB 리스너 (HTTPS:443)
    │
    ├── 규칙 1: Host = api.example.com       → Target Group A (API 서버)
    ├── 규칙 2: Path = /images/*              → Target Group B (이미지 서버)
    ├── 규칙 3: Path = /admin/* + IP 조건    → Target Group C (관리 서버)
    └── 기본 규칙                             → Target Group D (웹 서버)

Target Group: ALB가 트래픽을 전달할 대상들의 집합

• 대상 유형: EC2 인스턴스, IP 주소, Lambda 함수, 다른 ALB
• Target Group 단위로 헬스 체크, 포트, 프로토콜 설정
• 하나의 ALB로 여러 MSA 서비스 라우팅 → 로드밸런서 비용 절감

9.4 NLB — Network Load Balancer

L4(TCP/UDP) 레벨 동작. 초당 수백만 요청을 밀리초 수준 지연으로 처리.

NLB 선택 기준:

• 극도로 낮은 지연 시간이 필요한 실시간 서비스 (게임, 금융 트랜잭션)
• HTTP가 아닌 TCP/UDP 프로토콜 직접 처리
• 고정 IP 주소 필요 (NLB는 AZ마다 고정 IP 제공, ALB는 IP가 변함)
• AWS PrivateLink 기반 서비스 노출

10. EC2 Auto Scaling

10.1 Auto Scaling 개념

Auto Scaling은 애플리케이션 부하에 따라 EC2 인스턴스 수를 자동으로 조절하는 서비스다. 수평 확장(Scale Out/In)을 자동화한다.

트래픽 급증 → CPU 70% 초과 감지 → 인스턴스 추가 (Scale Out)
트래픽 감소 → CPU 30% 미만 유지 → 인스턴스 제거 (Scale In)

Auto Scaling Group(ASG) 핵심 설정값:

10.2 Auto Scaling 정책 4가지

① 목표 추적 조정 (Target Tracking) — 권장 지정 지표를 목표값으로 자동 유지. 설정이 가장 간단하고 효과적이다.

설정: "ALB RequestCountPerTarget = 1000"
→ 대상당 요청이 1000을 초과 → 인스턴스 자동 추가
→ 요청이 감소 → 인스턴스 자동 제거

사용 가능 지표: CPUUtilization, ALBRequestCountPerTarget, NetworkIn/Out

② 단계 조정 (Step Scaling) 지표 수치 구간별로 단계적으로 다른 크기 조정.

CPU 60~70% → +1개
CPU 70~85% → +3개
CPU 85% 이상 → +5개

③ 단순 조정 (Simple Scaling) CloudWatch 알람 하나에 고정 수량 조정. (현재는 Step Scaling으로 대체 추세)

④ 예약 조정 (Scheduled Scaling) 특정 시간대에 미리 용량 조정.

매일 오전 08:00 → 인스턴스 10개 (업무 시작 대비)
매일 자정 00:00 → 인스턴스 2개 (야간 최소 운영)

10.3 ELB + Auto Scaling 통합 동작

인터넷
  ↓
ALB (헬스 체크, 트래픽 분산)
  ↓
Auto Scaling Group
  ├── EC2 인스턴스 1  ← ASG가 ALB Target Group에 자동 등록
  ├── EC2 인스턴스 2
  └── EC2 인스턴스 3  (부하 증가 시 자동 추가)

• 신규 인스턴스 기동 → ALB Target Group에 자동 등록 → 헬스 체크 통과 후 트래픽 수신
• 인스턴스 제거 전 Connection Draining(기존 요청 처리 완료) 후 제거
• 헬스 체크 실패 인스턴스 → ASG가 자동 종료 후 새 인스턴스 교체

11. Route53 + CloudFront

11.1 Amazon Route53 — DNS 서비스

Route53은 AWS의 완전 관리형 DNS(Domain Name System) 서비스다.

사용자: "www.example.com" 입력
    ↓
Route53 DNS 조회
    ↓
IP 주소 반환 (예: 52.95.110.1)
    ↓
해당 IP로 실제 연결

Route53 3가지 기능:

1. 도메인 등록: Route53에서 직접 도메인 구매 가능
2. DNS 레코드 관리: A, AAAA, CNAME, MX, TXT, NS, SOA 레코드 관리
3. 트래픽 라우팅 + 헬스 체크: 엔드포인트 상태를 모니터링해 자동 장애 전환

11.2 Route53 라우팅 정책 6가지

① 단순 라우팅 (Simple)

• 도메인 → 단일 IP 반환
• 헬스 체크 불가, 레코드 하나에 여러 IP 등록 시 무작위 반환

② 가중치 기반 라우팅 (Weighted)

api.example.com
  ├── 서울 ALB (가중치 70) → 전체 트래픽의 70%
  └── 도쿄 ALB (가중치 30) → 전체 트래픽의 30%

카나리 배포(신버전에 일부 트래픽 먼저 전송), 부하 분산에 활용.

③ 지연 시간 기반 라우팅 (Latency) 사용자와 각 AWS 리전 간 네트워크 지연 시간을 측정해 가장 빠른 리전의 엔드포인트를 반환. 글로벌 서비스에서 사용자 경험 최적화에 사용.

④ 장애 조치 라우팅 (Failover)

Primary: 서울 리전 ALB  ← 헬스 체크 정상 시 100% 트래픽
    ↓ 헬스 체크 실패
Secondary: 도쿄 리전 ALB  ← 자동 전환 (Active-Passive DR)

⑤ 지리 위치 라우팅 (Geolocation) 클라이언트의 물리적 위치(국가, 대륙)를 기반으로 라우팅.

한국 → 서울 리전 엔드포인트
미국 → us-east-1 엔드포인트
EU → eu-west-1 엔드포인트
기타 → 기본 레코드

데이터 주권, 콘텐츠 현지화, GDPR 준수 등에 활용.

⑥ 다중값 응답 (Multivalue Answer) 최대 8개의 정상 레코드를 무작위로 반환. 헬스 체크와 연동 가능. ELB 대체용이 아닌 클라이언트 측 단순 분산 보조 수단.

11.3 Amazon CloudFront — CDN

CloudFront는 AWS의 콘텐츠 전송 네트워크(CDN) 서비스다. 전 세계 450개 이상의 엣지 로케이션에서 콘텐츠를 캐싱해 지연 시간을 줄인다.

오리진 서버 (S3 / ALB / EC2 / API Gateway)
    ↑ 캐시 MISS 시에만 요청 (오리진 부하 감소)
CloudFront 배포 (Distribution)
    ↑ 캐시 HIT 시 엣지에서 즉시 반환
엣지 로케이션 (사용자와 가장 가까운 곳)
    ↑
사용자

CloudFront 주요 개념:

CloudFront + S3 정적 웹사이트 구성:

사용자 → CloudFront (HTTPS 자동 적용, 전 세계 엣지 캐싱)
              ↑ 캐시 MISS 시만
         S3 버킷 (OAC로 접근, 버킷 자체는 프라이빗 유지)

캐시 정책 예시:

Behavior 1: /api/*      → ALB 오리진, TTL=0 (캐시 없음, 항상 오리진 요청)
Behavior 2: /static/*   → S3 오리진, TTL=86400 (1일 캐시)
Behavior 3: *.jpg, *.png → S3 오리진, TTL=604800 (7일 캐시)
기본           → ALB 오리진, TTL=0

12. 하이브리드 네트워크 — VPN vs Direct Connect

12.1 클라우드 배포 모델 4가지

실제 기업들이 가장 많이 쓰는 패턴: Hybrid Cloud — 기존 온프레미스 인프라를 단번에 클라우드로 옮기기 어렵기 때문.

12.2 AWS Site-to-Site VPN

회사 데이터 센터(온프레미스)와 AWS VPC를 인터넷을 통해 암호화 터널로 연결한다.

기업 데이터 센터
└── 고객 게이트웨이 디바이스 (VPN 장비)
         ↕ 암호화 터널 2개 (이중화)
└── 가상 프라이빗 게이트웨이 (AWS 측)
         └── VPC

특징:

• 최대 속도: 1.25Gbps
• 구성이 빠름 (수 시간 ~ 수 일)
• 비활성 시 요금 없음
• 데이터가 퍼블릭 인터넷을 경유 (암호화됨)
• 정적(Static) 또는 동적(BGP) 라우팅 지원

12.3 AWS Direct Connect

데이터 센터에서 AWS까지 전용 광 케이블로 직접 연결한다.

기업 데이터 센터
    → Direct Connect 파트너 시설 (코로케이션)
        → AWS 전용 회선
            → 가상 프라이빗 게이트웨이
                → VPC

특징:

• 속도: 50Mbps(Hosted Connection 최소) ~ 100Gbps(Dedicated Connection 최대)
• 낮은 지연 시간, 일관된 네트워크 성능 (인터넷 혼잡 없음)
• 데이터 기본 암호화 없음 (VPN 레이어 별도 추가 가능)
• 특수 계약 필요, 설치에 수 주 ~ 수 개월 소요
• 연결이 비활성 상태여도 포트 시간 비용 발생

VPN vs Direct Connect 언제 쓸까?

13. AWS IAM — 보안과 권한 관리

13.1 루트 사용자의 위험성

AWS 계정을 생성하면 루트 사용자가 만들어진다. 루트 사용자는 모든 AWS 서비스에 대한 전체 접근 권한을 가진다. 이 계정이 탈취되면 전체 인프라가 위험하다.

루트 사용자로 해야 할 일:

1. 결제 정보 관리
2. 초기 IAM 관리자 계정 생성
3. AWS 계정 해지

그 외 모든 일상 작업은 IAM 사용자로 해야 한다.

13.2 IAM 핵심 구성 요소

IAM 사용자 (User)

• 사람이나 애플리케이션을 대표하는 엔터티
• 고유한 자격 증명 (비밀번호, 액세스 키) 보유
• 콘솔 접근 또는 프로그래밍 방식 접근 설정 가능

IAM 그룹 (Group)

• IAM 사용자들의 집합
• 그룹에 정책을 연결하면 모든 구성원에게 일괄 적용
• 신규 팀원 온보딩 시 그룹에 추가하기만 하면 됨

그룹: Developers
├── 정책: AmazonEC2FullAccess
├── 정책: AmazonS3ReadOnly
│
├── 사용자: Alice
├── 사용자: Bob
└── 사용자: Charlie  ← 이 세 명 모두 위 정책 적용됨

IAM 역할 (Role)

• 임시 자격 증명을 사용하여 특정 권한을 위임
• 사람이 아닌 서비스나 다른 계정에 권한 부여 시 사용
• EC2 인스턴스, Lambda, ECS 태스크 등이 역할을 수임

예시: EC2 인스턴스가 S3에 파일을 업로드해야 할 때
→ EC2에 "S3 쓰기 권한" 역할을 부여
→ EC2가 역할을 수임 → 임시 자격 증명 발급 → S3 접근
→ 장기 자격 증명(액세스 키)을 코드에 하드코딩할 필요 없음

IAM 정책 (Policy)

• JSON 형식으로 권한을 정의하는 문서
• 사용자, 그룹, 역할에 연결

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:StartInstances",
        "ec2:StopInstances"
      ],
      "Resource": "arn:aws:ec2:*:*:instance/*",
      "Condition": {
        "StringEquals": {
          "ec2:ResourceTag/Owner": "${aws:username}"
        }
      }
    }
  ]
}

정책 요소:

• Effect: Allow 또는 Deny
• Action: 허용/거부할 작업 (예: ec2:StartInstances)
• Resource: 대상 리소스 ARN (특정 EC2 또는 * 전체)
• Condition: 선택적 조건 (IP, 태그, MFA 등)

정책 유형:

13.3 역할 수임 (Assume Role) 작동 방식

1. IAM 사용자/서비스 → STS에 역할 수임 요청
2. AWS STS → 임시 보안 자격 증명 반환
           (Access Key + Secret Key + Session Token, 유효시간 제한)
3. 임시 자격 증명으로 → AWS 리소스 접근

역할은 한 번 수임하면 일시적으로만 유효하다. 장기 자격 증명 노출 위험이 없다.

13.4 AWS Organizations — 다중 계정 관리

대기업이나 성장하는 스타트업은 계정을 여러 개로 분리해 운영한다. 이유:

• 팀별·환경별(개발/스테이징/운영) 청구 분리
• 보안 경계 강화 (한 계정의 오류가 다른 계정에 영향 없음)
• 규정 준수 요구사항

Organizations를 쓰면 이 계정들을 계층 구조(OU)로 관리하고, 통합 결제도 가능하다.

관리 계정 (Root)
└── OU: 개발
│   ├── 계정: dev-frontend
│   └── 계정: dev-backend
└── OU: 스테이징
│   └── 계정: staging
└── OU: 운영
    ├── 계정: prod-kr
    └── 계정: prod-us

SCP(서비스 제어 정책) — OU 또는 계정 수준의 최대 권한 제한

예시: 운영 OU에 SCP 적용
SCP: "EC2, S3, RDS만 허용"
→ 이 OU 안의 계정들은 아무리 IAM 정책을 넓게 줘도 허용된 서비스만 사용 가능

IAM 정책과 SCP의 교집합만 실제로 허용된다.

14. VM vs Container vs MSA

14.1 세 가지 실행 환경 비교

Bare Metal Server: 물리 서버를 통째로 하나의 OS가 사용

Virtual Machine (VM): 하이퍼바이저가 물리 서버를 논리적으로 분할, 각 VM이 독자적인 OS 보유

Container: 호스트 OS의 커널을 공유하되 프로세스 격리, 애플리케이션과 의존성만 패키징

Bare Metal          Virtual Machine        Container
┌──────────┐       ┌──┐ ┌──┐ ┌──┐       ┌──┐ ┌──┐ ┌──┐
│    App   │       │A1│ │A2│ │A3│       │A1│ │A2│ │A3│
├──────────┤       │OS│ │OS│ │OS│       │Lib│ │Lib│ │Lib│
│    OS    │       └──┘ └──┘ └──┘       └──┘ └──┘ └──┘
├──────────┤       ┌──────────────┐      ┌──────────────┐
│ Hardware │       │  Hypervisor  │      │Container Engine│
└──────────┘       ├──────────────┤      ├──────────────┤
                   │   Hardware   │      │     Host OS   │
                   └──────────────┘      ├──────────────┤
                                         │   Hardware   │
                                         └──────────────┘

상세 비교표:

상황별 선택 가이드:

14.2 Container의 핵심 특성

컨테이너는 애플리케이션과 그 실행에 필요한 모든 요소(코드, 런타임, 라이브러리, 설정)를 하나로 패키징한 경량 실행 환경이다.

4가지 핵심 특성:

14.3 MSA (Micro Service Architecture)

Monolithic(모놀리식): 모든 기능이 하나의 배포 단위에 묶임

문제점:

• 작은 수정도 전체 재배포
• 한 기능의 장애가 전체 시스템에 영향
• 특정 기능만 스케일 아웃 불가 (전체를 스케일 아웃해야 함)
• 기술 스택 통일 강제

MSA: 기능별로 독립적인 서비스로 분리

Monolithic 주문 앱                   MSA 주문 앱
┌─────────────────────┐             
│ 주문 UI             │             [주문 UI]  ─────────────────────┐
│ 주문 기록            │     →                                       │
│ 인벤토리             │             ALB (Application Load Balancer) │
│ 이메일 발송          │               │                             │
│ 영업 기록            │         ┌────┴──┬──────┬──────┐           │
└─────────────────────┘         │       │      │      │           │
                             [주문]  [인벤]  [이메] [영업]         │
                              서비스   토리   일     기록           │
                                    서비스  서비스  서비스          │

각 서비스:

• 독립적으로 배포 가능
• 독립적으로 확장 가능 (주문이 몰리면 주문 서비스만 스케일 아웃)
• 서비스별 장애 격리 (이메일 서비스가 죽어도 주문은 처리됨)
• 서비스별 기술 스택 자유 (Python AI 서비스 + Java 주문 서비스 혼용 가능)

컨테이너 + MSA + Kubernetes = 현대 클라우드 아키텍처의 핵심

15. Kubernetes — 컨테이너 오케스트레이션

컨테이너가 늘어나면 직접 관리가 한계에 부딪힌다. "이 컨테이너가 죽었는데?", "트래픽이 몰리는데 더 띄워야 하는데?", "서버 A가 꽉 찼는데 서버 B에는 올려도 되나?" — 이 모든 걸 자동화해주는 것이 Kubernetes(쿠버네티스, k8s)다.

15.1 Kubernetes 아키텍처

Control Plane (마스터 노드) — 클러스터 전체를 관리·감독

Worker Node — 실제 컨테이너가 실행되는 곳

15.2 Kubernetes 클러스터 구축 실습

실습에서는 AWS EC2 인스턴스 3개로 클러스터를 구성했다:

• Master Node: t3.medium (2vCPU, 4GB RAM) × 1
• Worker Node: t3.small × 2

최소 요건: 2GB 이상 RAM, 2개 이상 CPU, swap 비활성화

설치 전체 흐름:

# ① 모든 노드: 스왑 비활성화 (k8s 필수 사전 조건)
sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

# ② 모든 노드: 커널 모듈 로드
sudo tee /etc/modules-load.d/containerd.conf <<EOF
overlay
br_netfilter
EOF
sudo modprobe overlay
sudo modprobe br_netfilter

# ③ 모든 노드: 커널 파라미터 설정 (Pod 간 네트워크 통신)
sudo tee /etc/sysctl.d/kubernetes.conf <<EOF
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
EOF
sudo sysctl --system

# ④ 모든 노드: containerd 설치
sudo apt install -y containerd.io
containerd config default | sudo tee /etc/containerd/config.toml >/dev/null 2>&1
sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml
sudo systemctl restart containerd
sudo systemctl enable containerd

# ⑤ 모든 노드: Kubernetes 구성 요소 설치
sudo apt install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl  # 자동 업그레이드 방지

# ⑥ 마스터 노드에서만: 클러스터 초기화
sudo kubeadm init

# ⑦ 마스터 노드: kubeconfig 설정
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

# ⑧ 마스터 노드: 네트워크 플러그인 설치 (Calico)
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27.2/manifests/calico.yaml

# ⑨ 워커 노드에서: 클러스터에 조인
sudo kubeadm join 172.31.x.x:6443 --token <토큰> \
    --discovery-token-ca-cert-hash sha256:<해시>

# ⑩ 마스터 노드: 전체 노드 상태 확인
kubectl get nodes

왜 swap을 비활성화해야 할까?
Kubernetes는 메모리 관리를 직접 한다. swap이 활성화되어 있으면 k8s가 실제 메모리 사용량을 정확히 파악하기 어렵고, 스케줄링 결정이 부정확해진다.

왜 네트워크 플러그인이 필요할까?
k8s 자체는 Pod 간 통신 방법을 명세(CNI)만 정의한다. 실제 구현은 Calico, Flannel, Weave 등의 플러그인이 담당한다.

15.3 Pod — 가장 작은 배포 단위

Pod는 Kubernetes에서 배포 가능한 가장 작은 단위다. 하나 이상의 컨테이너가 같은 네트워크와 스토리지를 공유하며 하나의 단위로 실행된다.

# po/pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: pod-test2
spec:
  containers:
  - name: test-nginx-container
    image: nginx:latest
    ports:
    - containerPort: 80
      protocol: TCP

자주 쓰는 Pod 관련 명령어:

# Pod 생성 (명령어 방식)
kubectl run nginx-pod --image=nginx --port=80

# Pod 생성 (YAML 방식)
kubectl apply -f po/pod.yaml

# Pod 목록 확인
kubectl get pods
kubectl get pods -o wide   # IP, 배치된 노드도 표시

# Pod 상세 정보 (이벤트, 컨테이너 상태 등)
kubectl describe pods pod-test2

# Pod 내부 접속
kubectl exec -it pod-test2 -- bash

# Pod에 명령어 전달
kubectl exec pod-test2 -- env

# 로그 확인
kubectl logs pod-test2
kubectl logs -f pod-test2   # 실시간 로그 스트리밍

# Pod 삭제
kubectl delete pod pod-test2
kubectl delete -f po/pod.yaml

Pod의 한계: Pod를 직접 만들면, Pod가 죽었을 때 아무도 되살려주지 않는다. 이걸 해결하는 것이 ReplicaSet이다.

15.4 ReplicaSet — Pod를 N개 유지

ReplicaSet은 "이 Pod를 항상 N개 유지해줘" 라고 선언하는 리소스다.

# rs/rs-nginx.yaml
apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: replicaset-nginx
spec:
  replicas: 3                    # 항상 3개 유지
  selector:
    matchLabels:
      app: test-nginx-pods-label # 이 레이블의 Pod를 관리
  template:
    metadata:
      name: test-nginx-pod
      labels:
        app: test-nginx-pods-label
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80

ReplicaSet 동작 원리:

# 현재 3개의 Pod가 실행 중
kubectl get pods --show-labels

# Pod 하나를 수동 삭제하면?
kubectl delete pod replicaset-nginx-xxxxx

# 즉시 새 Pod가 생성됨!
kubectl get pods   # 여전히 3개

ReplicaSet이 Pod를 인식하는 방법: selector.matchLabels에 정의된 레이블을 가진 Pod가 관리 대상.

• 레이블이 맞는 Pod가 N개보다 적으면 → 새 Pod 생성
• 레이블이 맞는 Pod가 N개보다 많으면 → 초과 Pod 삭제
• Pod의 레이블을 수동으로 제거하면 → ReplicaSet 관리에서 벗어남 (고아 Pod)

15.5 Deployment — 버전 관리까지 되는 업그레이드

실제 서비스에서는 ReplicaSet을 직접 다루지 않는다. Deployment를 사용한다.

Deployment = ReplicaSet 관리 + 롤링 업데이트 + 롤백

# deploy/deploy-nginx.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: test-nginx-deploy
spec:
  replicas: 3
  selector:
    matchLabels:
      app: test-nginx
  template:
    metadata:
      labels:
        app: test-nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.10     # 현재 버전
        ports:
        - containerPort: 80

# Deployment 생성
kubectl apply -f deploy/deploy-nginx.yaml

# 생성된 Deployment, ReplicaSet, Pod 확인
kubectl get deployment
kubectl get replicasets,pods

# 이미지 버전 업데이트 → 롤링 업데이트 자동 실행
kubectl set image deploy test-nginx-deploy nginx=nginx:1.19

# 롤링 업데이트 진행 상황 실시간 확인
kubectl rollout status deployment test-nginx-deploy

# ReplicaSet 2개가 존재 (이전 버전 + 새 버전)
kubectl get replicasets

# 롤아웃 히스토리 확인
kubectl rollout history deployment test-nginx-deploy

# 이전 버전으로 롤백 (1번 revision으로)
kubectl rollout undo deploy test-nginx-deploy --to-revision=1

롤링 업데이트 동작 방식:

1. 새 버전의 ReplicaSet 생성
2. 새 ReplicaSet의 Pod를 1개씩 증가
3. 이전 ReplicaSet의 Pod를 1개씩 감소
4. 완전히 전환될 때까지 반복
5. 이전 ReplicaSet은 Pod 0개로 유지 (롤백 대비)

Deployment를 삭제하면 → 하위 ReplicaSet과 Pod도 모두 삭제됨.

15.6 Service — 고정된 네트워크 진입점

Pod는 동적으로 생성/삭제되어 IP가 매번 변한다. Service는 Pod들에 대한 고정된 DNS 이름과 IP를 제공한다.

Service (고정 IP/DNS)
    ↓ 트래픽 분산
Pod-1 (172.17.0.4)
Pod-2 (172.17.0.5)
Pod-3 (172.17.0.6)

Pod가 재생성되어 IP가 바뀌어도 Service를 통해 접근하면 문제없다.

Service 타입 3가지:

① ClusterIP (기본값) — 클러스터 내부 전용

# svc/svc-clusterip.yaml
apiVersion: v1
kind: Service
metadata:
  name: svc-clusterip
spec:
  ports:
  - name: web-port
    port: 8080        # Service가 노출하는 포트
    targetPort: 80    # Pod의 실제 포트
  selector:
    app: webserver    # 이 레이블의 Pod에 트래픽 전달
  type: ClusterIP

클러스터 내부에서만 접근 가능. 서비스 이름으로 DNS 조회 가능:

curl svc-clusterip:8080

② NodePort — 노드 IP로 외부 접근

# svc/svc-nodeport.yaml
apiVersion: v1
kind: Service
metadata:
  name: svc-nodeport
spec:
  ports:
  - name: web-port
    port: 8080
    targetPort: 80
    # nodePort: 30080   # 생략 시 30000-32767 범위에서 자동 할당
  selector:
    app: webserver
  type: NodePort

# 노드의 IP로 외부에서 접근
curl <노드 Internal IP>:<NodePort>

모든 노드에서 같은 NodePort로 접근 가능.

③ LoadBalancer — 퍼블릭 IP 자동 할당 (클라우드용)

# svc/svc-lb.yaml
apiVersion: v1
kind: Service
metadata:
  name: svc-lb
spec:
  ports:
  - name: web-port
    port: 80
    targetPort: 80
  selector:
    app: webserver
  type: LoadBalancer

AWS EKS, GKE, AKS 등 클라우드 환경에서 사용 시 클라우드 로드밸런서를 자동으로 프로비저닝한다.

서비스 타입 비교:

15.7 Ingress — HTTP/HTTPS 경로 기반 라우팅

Service의 LoadBalancer 타입은 서비스마다 별도 로드밸런서를 생성해 비용이 많이 든다. Ingress는 하나의 진입점에서 URL 경로나 호스트 이름을 기준으로 여러 서비스에 라우팅한다.

클라이언트
    ↓
Ingress (하나의 외부 IP / 로드밸런서)
    ├── /api/users   → users-service:80
    ├── /api/orders  → orders-service:80
    └── /            → frontend-service:80

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /api/users
        pathType: Prefix
        backend:
          service:
            name: users-service
            port:
              number: 80
      - path: /api/orders
        pathType: Prefix
        backend:
          service:
            name: orders-service
            port:
              number: 80

Ingress가 동작하려면 Ingress Controller가 클러스터에 설치되어야 한다.

kubectl get ingress
kubectl describe ingress app-ingress

15.8 HPA — Horizontal Pod Autoscaler

HPA는 CPU 사용률 또는 커스텀 지표를 기준으로 Pod 수를 자동으로 조절한다. Kubernetes 워크로드에 대한 수평 자동 확장이다.

부하 증가 → Pod CPU 80% 초과
    ↓
HPA 감지 (15초 간격 평가)
    ↓
Deployment replicas 3 → 6 자동 조정
    ↓
부하 분산, CPU 하락
    ↓
CPU 50% 안정 → 일정 시간 후 replicas 다시 축소

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: test-nginx-deploy
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50   # CPU 50% 목표

HPA가 동작하려면 Pod에 resources.requests 설정이 필수다:

resources:
  requests:
    cpu: "100m"      # 0.1 vCPU
    memory: "128Mi"
  limits:
    cpu: "500m"
    memory: "256Mi"

# HPA 생성 (명령어 방식)
kubectl autoscale deployment test-nginx-deploy --cpu-percent=50 --min=2 --max=10

# HPA 상태 확인
kubectl get hpa

# 상세 정보 (스케일 이벤트 확인)
kubectl describe hpa nginx-hpa

HPA vs EC2 Auto Scaling 비교:

15.9 Namespace — 클러스터 내 논리적 격리

Namespace는 하나의 클러스터를 여러 가상 클러스터로 분리하는 방법이다.

# ns/prod-ns.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: production

# 기본 namespace의 Pod
kubectl get pods                           # default namespace
kubectl get pods --namespace kube-system   # 시스템 컴포넌트

# namespace 생성 후 리소스 배포
kubectl apply -f prod-ns.yaml
kubectl apply -f deploy-svc-ns.yaml
kubectl get po,svc -n production

# 같은 namespace 서비스 접근
curl svc-clusterip-ns:8080

# 다른 namespace 서비스 접근 (FQDN: 서비스명.네임스페이스.svc)
curl svc-clusterip-ns.production.svc:8080

# namespace 삭제 → 안의 모든 리소스 삭제됨
kubectl delete namespace production

활용 예시:

• development, staging, production 환경 분리
• 팀별 격리 (team-a, team-b)
• 시스템 컴포넌트 분리 (kube-system)

15.10 ConfigMap과 Secret — 설정 분리

컨테이너 이미지에 설정값을 하드코딩하면 환경마다 이미지를 새로 빌드해야 한다. ConfigMap으로 설정을 분리하면 이미지 변경 없이 설정만 바꿀 수 있다.

ConfigMap 생성:

# 명령어로 생성
kubectl create configmap log-level-configmap --from-literal LOG_LEVEL=DEBUG
kubectl create configmap start-k8s --from-literal k8s=kubernetes --from-literal container=docker

# 파일로 생성 (설정 파일 전체를 ConfigMap으로)
echo "Hello, Kubernetes" | sudo tee index.html
kubectl create configmap index-file --from-file index.html

# ConfigMap 조회
kubectl get configmap
kubectl describe configmap log-level-configmap
kubectl get configmap log-level-configmap -o yaml

ConfigMap을 Pod에 주입하는 방법:

방법 1 — 환경 변수로 전달:

# 전체 ConfigMap을 환경 변수로
spec:
  containers:
  - name: my-container
    image: busybox
    args: ['tail', '-f', '/dev/null']
    envFrom:
    - configMapRef:
        name: log-level-configmap  # ConfigMap 전체를 env로
    - configMapRef:
        name: start-k8s

# 특정 키만 골라서 환경 변수로
spec:
  containers:
  - name: my-container
    env:
    - name: LOG_LEVEL
      valueFrom:
        configMapKeyRef:
          name: log-level-configmap
          key: LOG_LEVEL

방법 2 — 볼륨으로 파일 마운트:

spec:
  containers:
  - name: nginx
    volumeMounts:
    - name: config-vol
      mountPath: /etc/config
  volumes:
  - name: config-vol
    configMap:
      name: start-k8s

ConfigMap의 각 key-value가 파일 이름과 내용으로 마운트된다.

Secret — 민감 정보 보관:

# 비밀번호 저장
kubectl create secret generic my-password --from-literal password=dkagh123.

# 파일로 생성
echo mypassword | sudo tee pw1 > /dev/null
kubectl create secret generic our-password --from-file pw1

# Secret 확인 (값은 Base64 인코딩)
kubectl get secrets my-password -o yaml

# Base64 디코딩으로 실제 값 확인
echo <base64값> | base64 -d

Secret은 ConfigMap과 동일하게 환경 변수 또는 볼륨으로 Pod에 주입한다.

Docker private registry 인증 정보도 Secret으로 관리:

kubectl create secret docker-registry registry-auth \
  --docker-username=myuser \
  --docker-password=mypassword \
  --docker-server=registry.example.com

15.11 Volume — 데이터 영속성

컨테이너가 죽으면 컨테이너 내부 데이터는 사라진다. Volume을 사용하면 데이터를 영속적으로 저장할 수 있다.

emptyDir — 임시 공유 볼륨

Pod가 실행되는 동안만 존재하는 임시 디렉터리. 같은 Pod의 여러 컨테이너가 데이터를 공유할 때 사용.

# content-creator 컨테이너에서 파일 생성
kubectl exec -it emptydir-pod -c content-creator -- sh
echo "hello, k8s" > /data/test.html
exit

# apache-webserver 컨테이너에서 같은 파일 확인
kubectl exec -it emptydir-pod --container apache-webserver -- cat htdocs/test.html
# 출력: hello, k8s

hostPath — 노드 파일시스템 마운트

호스트 노드의 특정 디렉터리를 Pod에 마운트. 로그 수집, 노드 파일 접근 등에 사용.

주의: Pod가 다른 노드에 스케줄되면 데이터가 보이지 않을 수 있음.

PV/PVC — 클러스터 수준 영구 스토리지

관리자(Admin)                사용자(Developer)
     │                              │
     ▼                              ▼
PV 생성 (실제 스토리지 선언)   PVC 생성 (스토리지 요청)
                                     │
                               PV와 자동 바인딩
                                     │
                                  Pod에서 사용

# PV 정의 (관리자가 스토리지 선언)
apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv
spec:
  capacity:
    storage: 1G
  accessModes:
  - ReadWriteOnce      # 단일 노드 읽기/쓰기
  hostPath:
    path: /pv          # 실제 저장 경로

# PVC 정의 (사용자가 스토리지 요청)
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1G      # 조건에 맞는 PV가 자동 바인딩

# PV, PVC, Pod 생성 후 상태 확인
kubectl get pv,pvc,po

# Pod 내부에서 파일 생성
kubectl exec -it persistentvolume --container container -- /bin/bash
cd /mount1
echo "hello pv" >> test.txt
exit

# Pod를 삭제해도 PV의 데이터는 유지됨
kubectl delete pod persistentvolume

accessModes 종류:

16. AWS CI/CD — 코드 커밋부터 자동 배포까지

16.1 AWS CI/CD 서비스 구성

[소스 (S3 / GitHub)]
    ↓ 변경 감지 (CodePipeline이 트리거)
[CodeBuild] ← buildspec.yml
    ↓ 빌드 아티팩트 (dist/, .jar 등)
[CodeDeploy] ← appspec.yml
    ↓
[EC2 / S3 / ECS / Lambda]

16.2 Lab 10 — AWS CodePipeline 기본 (S3 → S3 배포)

가장 단순한 파이프라인: Source S3 버킷에 파일을 올리면 → Prod S3 버킷(정적 웹사이트)에 자동 배포.

구성 요소:

• Source 버킷: user-source-website — 버전 관리 활성화 (트리거에 필요)
• Prod 버킷: user-prod-website — 정적 웹사이트 호스팅 활성화, 퍼블릭 액세스 허용

파이프라인 설정 핵심:

• 소스 공급자: Amazon S3
• 배포 공급자: Amazon S3
• "배포하기 전에 파일 압축 풀기" 체크
• 표준 ACL: public-read (정적 웹사이트 공개 접근용)

파이프라인 동작 흐름:

Source 버킷에 test-website.zip 업로드
    → CodePipeline 자동 감지 (S3 버전 변경 이벤트)
        → Deploy: Prod 버킷에 압축 풀어 배포
            → 웹사이트 자동 업데이트

파일 압축 시 주의사항:

✗ 잘못된 방법: test-website 폴더를 통째로 압축
  → 압축 해제 시 또 폴더가 생겨 경로 오류

✓ 올바른 방법: 폴더 안으로 들어가 index.html, error.html 파일 선택 후 압축
  → 압축 파일 최상위에 바로 index.html이 있어야 함

16.3 Lab 11 — GitHub 저장소를 소스로 활용

소스를 S3 대신 GitHub으로 변경하면 git push만으로 파이프라인이 자동 실행된다.

GitHub 설정:

1. Repository 생성 (Private)
2. Personal Access Token 생성 (scopes: repo)
3. AWS CodePipeline에서 GitHub App 연결

로컬 → GitHub → CodePipeline 흐름:

# 처음 연결
git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/<계정>/test-website-repo.git
git branch -M main
git push -u origin main

# 이후 변경사항 → 파이프라인 자동 트리거
git commit -a -m "v2.0 update"
git push origin main

GitHub 웹 UI에서 파일을 직접 편집하고 커밋해도 파이프라인이 트리거된다.

GitHub App 연결 vs Personal Access Token:

• GitHub App: 더 안전하고 세밀한 권한 관리 가능 (권장)
• Personal Access Token: 간편하지만 관리 주의 필요

16.4 Lab 12 — AWS CodeBuild로 빌드 자동화

Angular 같은 프레임워크는 소스 코드를 바로 배포할 수 없다. 빌드 과정이 필요하다. buildspec.yml 파일로 빌드 방법을 정의한다.

buildspec.yml 구조:

version: 0.2

phases:
  install:                      # 빌드 환경 설정
    runtime-versions:
      nodejs: 20                # Node.js 20 사용
    commands:
      - npm install -g @angular/cli@17  # Angular CLI 전역 설치

  pre_build:                    # 빌드 전 준비
    commands:
      - npm install             # 프로젝트 의존성 설치

  build:                        # 실제 빌드
    commands:
      - ng build -c production  # 프로덕션 빌드
      - echo "Build completed."
    finally:                    # 성공/실패 무관 항상 실행
      - echo This is the finally block execution!

artifacts:                      # 배포할 결과물
  base-directory: dist/my-angular-project
  files:
    - '**/*'                    # 빌드 결과물 전체

buildspec.yml 위치: 프로젝트 루트에 있어야 CodeBuild가 자동으로 찾음

phases 종류:

파이프라인 구성:

[GitHub]
    ↓ push 이벤트
[Source 단계: GitHub 소스 체크아웃]
    ↓
[Build 단계: CodeBuild]
    buildspec.yml 실행:
    1. Node.js 20 설치
    2. npm install
    3. ng build -c production
    ↓ dist/ 아티팩트
[Deploy 단계: S3]
    ↓
[정적 웹사이트 배포]

첫 빌드 시 buildspec.yml이 없으면 Build 단계에서 실패한다. 로그를 확인해 실패 원인을 파악하고, 파일을 추가해 다시 push하면 된다.

16.5 Lab 13 — AWS CodeDeploy로 EC2 인스턴스에 배포

S3가 아닌 EC2 인스턴스에 빌드 결과물을 배포할 때는 CodeDeploy를 사용한다.

appspec.yml — 배포 명세서:

version: 0.0
os: linux

files:
  - source: dist/my-angular-project    # 빌드 아티팩트의 경로
    destination: /var/www/my-angular-project  # EC2에 복사할 경로

permissions:
  - object: /var/www/my-angular-project
    pattern: '**'
    mode: '0755'       # 실행 권한
    owner: root
    group: root
    type:
      - file
      - directory

hooks:
  ApplicationStart:
    - location: deploy-scripts/application-start-hook.sh
      timeout: 300     # 300초 제한

배포 훅(Hooks) — 배포 생명주기:

ApplicationStop          ← 현재 실행 중인 앱 종료
BeforeInstall            ← 파일 복사 전 준비 (의존성 설치 등)
AfterInstall             ← 파일 복사 후 설정 (설정 파일 적용 등)
ApplicationStart   ←────  현재 실습에서 사용
ValidateService          ← 배포 성공 검증 (헬스 체크 등)

각 훅에 셸 스크립트를 연결해 세밀한 배포 제어가 가능하다.

CodeDeploy 작동 요건:

• EC2 인스턴스에 CodeDeploy Agent 설치
• EC2 인스턴스에 IAM 역할 부여 (S3 아티팩트 접근 권한)
• CodeDeploy 서비스에도 IAM 서비스 역할 필요

전체 Lab 12+13 파이프라인 흐름:

GitHub push
    ↓
CodePipeline 트리거
    ↓
[Source] GitHub에서 소스 체크아웃
    ↓
[Build] CodeBuild + buildspec.yml
    → npm install → ng build → S3에 빌드 아티팩트 저장
    ↓
[Deploy] CodeDeploy + appspec.yml
    → S3에서 아티팩트 다운로드
    → 배포 훅 실행 (ApplicationStop → BeforeInstall → AfterInstall → ApplicationStart)
    → EC2 /var/www/my-angular-project/ 에 파일 배포
    ↓
[서비스 정상 확인]

17. 소프트웨어 배포 전략

새 버전을 어떻게 기존 운영 환경에 반영할지 결정하는 방법론이다. 다운타임, 롤백 속도, 비용, 위험도 측면에서 각각 다른 트레이드오프를 가진다.

17.1 In-Place 배포 (Rolling 배포)

기존 인스턴스를 교체 없이 순차적으로 새 버전을 덮어쓴다.

배포 전:   [v1][v1][v1][v1]
배포 중:   [v2][v1][v1][v1]  ← v1, v2 혼재
           [v2][v2][v1][v1]
배포 완료: [v2][v2][v2][v2]

동시 배포 비율 제어(MinimumHealthyHosts 설정):

• AllAtOnce: 전체 동시 배포 (가장 빠름, 다운타임 위험)
• HalfAtATime: 절반씩 배포
• OneAtATime: 1개씩 배포 (가장 안전, 가장 느림)

17.2 Blue/Green 배포

현재 운영 환경(Blue)과 동일한 새 환경(Green)을 별도로 구성한 뒤 트래픽을 한 번에 전환한다.

Blue (현재):  [v1][v1][v1][v1]  ← 전환 전 100% 트래픽
Green (신버전): [v2][v2][v2][v2]  ← 검증 완료 대기

ALB 전환:  Blue 100% → Green 100%  (순간 전환, 다운타임 없음)
롤백:      Green → Blue 즉시 재전환

CodeDeploy Blue/Green 설정 포인트:

• Green 환경 구성: ASG에서 자동 프로비저닝 또는 수동 지정
• 트래픽 재라우팅: 즉시 또는 N분 대기 후 자동 전환
• Blue 환경 처리: 전환 성공 후 N분 뒤 자동 종료

17.3 Canary 배포

신버전을 전체 트래픽의 일부(소수)에만 먼저 노출해 이상 여부를 확인하고 점진적으로 확대한다.

1단계 (Canary):   [v2][v1][v1][v1][v1][v1][v1][v1][v1][v1]
                  ↑ 10% 트래픽 → v2 (모니터링)
2단계 (확대):     v2 비율 50%
3단계 (완료):     v2 100%

AWS CodeDeploy 사전 정의 Canary 설정:

Lambda, ECS에서 주로 활용됨.

17.4 Linear 배포 (점진적 배포)

일정 시간 간격으로 동일한 비율씩 신버전 트래픽을 단계적으로 증가시킨다.

0분:  v2 → 10%
10분: v2 → 20%
20분: v2 → 30%
...
90분: v2 → 100%

Canary와 차이: Canary는 "소량 먼저 → 한 번에 나머지", Linear는 "균등하게 점진 증가".

AWS CodeDeploy 사전 정의 Linear 설정:

17.5 A/B Testing 배포

동일 기능의 두 버전을 서로 다른 사용자 그룹에 동시에 노출해 비즈니스 지표(전환율, 클릭률 등)를 비교한다.

사용자 그룹 A (50%) → 버전 A (기존 UI)  전환율: 3.2%
사용자 그룹 B (50%) → 버전 B (새 UI)   전환율: 4.7% ← 더 높음
→ 버전 B를 전체 배포 결정

Canary와 차이: Canary는 기술적 안정성 검증, A/B Testing은 사용자 행동 기반 비즈니스 최적화.

AWS 구현 방법:

• ALB 가중치 라우팅 + 헤더/쿠키 기반 Target Group 분리
• CloudFront + Lambda@Edge: 요청 헤더 기반 오리진 분기
• AWS AppConfig: 기능 플래그(Feature Flag)로 특정 사용자에게만 기능 활성화

17.6 Recreate 배포 (All-at-Once)

기존 버전을 모두 종료한 뒤 새 버전을 전체 배포. 다운타임 발생.

[v1][v1][v1] → 전체 종료 → (다운타임) → [v2][v2][v2]

적합한 경우: 개발/스테이징 환경, DB 스키마 변경으로 v1/v2 혼재가 불가능한 상황.

17.7 Shadow 배포 (트래픽 미러링)

실제 프로덕션 트래픽을 신버전에 복사(미러링)해서 응답은 사용자에게 보내지 않고 신버전의 동작만 검증한다.

사용자 요청
    ├── v1 (운영) → 실제 응답 사용자에게 반환
    └── v2 (Shadow) → 요청만 전달, 응답은 버림 (사용자 영향 없음)

v2 모니터링:
- 응답 시간 비교
- 에러 발생 여부
- 데이터 처리 정확성

AWS 구현: ALB 미러링 규칙, Istio/AWS App Mesh 트래픽 미러링 기능 활용.

17.8 배포 전략 종합 비교

AWS CodeDeploy 대상별 지원 배포 방식:

18. 서비스 안정성 — 고가용성과 무중단 배포

18.1 고가용성 3-Tier 아키텍처

실제 프로덕션 환경의 기본 아키텍처:

인터넷
    ↓
Route53 (DNS, 장애 조치 라우팅)
    ↓
CloudFront (CDN, 정적 콘텐츠 캐싱)
    ↓
Elastic Load Balancer (ELB)
    ↓ ↓
┌────────────────────────────────────────┐
│         퍼블릭 서브넷                  │
│  [웹/앱 서버 Auto Scaling Group]       │
│  AZ-1: EC2 × 2                        │
│  AZ-2: EC2 × 2                        │
└────────────────────────────────────────┘
    ↓ ↓
┌────────────────────────────────────────┐
│         프라이빗 서브넷                │
│  [RDS Multi-AZ]                        │
│  AZ-1: Primary DB + Read Replica      │
│  AZ-2: Standby DB + Read Replica      │
└────────────────────────────────────────┘

각 컴포넌트 역할:

• Route53: DNS 기반 장애 조치. 헬스 체크 실패 시 다른 리전으로 트래픽 전환
• CloudFront: 정적 콘텐츠(이미지, JS, CSS)를 엣지 로케이션에서 서빙
• ELB: 여러 EC2 인스턴스로 트래픽 분산, 헬스 체크로 비정상 인스턴스 제외
• Auto Scaling: CPU/메모리 지표에 따라 EC2 인스턴스 수 자동 조절
• RDS Multi-AZ: 프라이머리 장애 시 스탠바이로 자동 전환

18.2 DR(재해 복구) 전략 — RPO와 RTO

RPO (Recovery Point Objective): 장애 발생 시 얼마나 최근 데이터까지 복구할 수 있는가 → 데이터 백업 주기를 결정

RTO (Recovery Time Objective): 장애 발생 시 얼마나 빨리 서비스를 복구해야 하는가 → 복구 전략의 비용을 결정

재해 발생 시각
    │
    │←─── RPO ───→│
    │              │
    │    마지막     │
    │    백업 시점  │
                   │
                   │←──── RTO ─────→│
                                     │
                               서비스 복구

4가지 DR 전략 비교:

전략 상세 설명:

① 백업 및 복원

프로덕션 환경
    → 주기적 스냅샷 (S3, EBS, RDS Snapshot)
        → 장애 발생
            → CloudFormation으로 인프라 재구축
                → 백업에서 데이터 복원

적합한 경우: 비용 최우선, 중요도 낮은 시스템

② 파일럿 라이트

평상시:
    DR 리전: DB만 소규모 운영 (프라이머리와 복제)

장애 시:
    DR 리전: 앱 서버, 로드밸런서 신속 가동
    Route53으로 트래픽 전환

적합한 경우: 데이터는 중요하지만 앱 서버는 빠르게 재구축 가능한 경우

③ 웜 스탠바이

평상시:
    DR 리전: 모든 계층이 축소 규모로 상시 운영
    (웹 × 1, 앱 × 1, DB Standby)

장애 시:
    Auto Scaling으로 전체 용량으로 확장
    Route53으로 트래픽 전환

적합한 경우: 빠른 복구가 필요하지만 완전 Active/Active 비용을 감당하기 어려운 경우

④ 멀티 사이트 Active/Active

평상시:
    리전 A: 전체 용량으로 서비스 중
    리전 B: 전체 용량으로 서비스 중 (트래픽 분산)
    두 리전 간 Aurora Global Database로 실시간 복제

장애 시:
    Global Accelerator가 자동으로 정상 리전으로 100% 전환
    RTO: 거의 0 (실시간)

적합한 경우: 금융, 의료, 글로벌 서비스 — 다운타임이 허용되지 않는 경우

전체 아키텍처 흐름 요약

코드 커밋부터 사용자 요청 처리까지의 전체 흐름:

개발자 git push
    ↓
CodePipeline 트리거 (GitHub 웹훅 / S3 버전 변경)
    ↓
[Source] 소스 체크아웃
    ↓
[Build] CodeBuild + buildspec.yml
    → 의존성 설치 → 빌드 → 단위 테스트 → 빌드 아티팩트 S3 저장
    ↓
[Deploy] CodeDeploy + appspec.yml
    → 배포 전략 선택 (Blue/Green / Canary / Rolling 등)
    → 헬스 체크 통과 후 트래픽 전환
    ↓
Route53 (DNS, 장애 조치 라우팅)
    ↓
CloudFront (CDN — 정적 콘텐츠 엣지 캐싱, HTTPS)
    ↓
ALB (L7 로드 밸런싱, Target Group 헬스 체크)
    ├── /api/* → EC2 Auto Scaling Group 또는 EKS/ECS
    └── /      → S3 정적 웹사이트
    ↓
애플리케이션 레이어 (EC2 / Kubernetes Pod / ECS Task)
    ↓
데이터 레이어
    ├── Aurora / RDS (관계형 DB, Multi-AZ 고가용성)
    ├── ElastiCache Redis (캐싱 — Lazy Loading / Write-Through)
    └── DynamoDB (NoSQL — 세션, 실시간 이벤트)

서비스 계층별 AWS 서비스 매핑:

생각 정리

인프라 관점에서 보면 VPC가 네트워크 경계를 정의하고, ELB와 Auto Scaling이 트래픽 변화에 대응하며, RDS Multi-AZ와 DR 전략이 데이터 가용성을 보장한다. 그 위에 컨테이너와 Kubernetes를 올리면 배포 단위가 인스턴스에서 Pod로 내려오고, CI/CD 파이프라인이 이 전체 흐름을 자동화한다. 배포 전략을 깊게 들여다보면서 특히 인상적이었던 부분은, "새 버전을 올린다"는 행위 하나에도 다운타임 허용 여부, 롤백 속도, 비용, 버전 혼재 가능성을 모두 고려해 전략을 선택한다는 점이다. Blue/Green은 즉각적인 롤백이 가능한 대신 인프라 비용이 두 배가 되고, Canary는 리스크를 최소화하는 대신 운영 복잡도가 올라간다. 어떤 전략이 무조건 옳은 게 아니라, 서비스의 특성과 팀의 상황에 맞게 선택하는 것이 핵심이다. 클라우드는 가용성·확장성·보안·비용 최적화를 동시에 설계한다는 것을 실습을 진행하며 그리고 다음 프로젝트를 진행하며 많이 배운거같다.

참고 자료

AWS 공식 문서

• EC2 / EC2 Auto Scaling
• Amazon S3 / Amazon EBS
• VPC
• ALB / NLB
• Route53 / CloudFront
• IAM / AWS Organizations
• RDS / Aurora / DynamoDB / ElastiCache
• Direct Connect / Site-to-Site VPN
• ECR
• CodePipeline / CodeBuild buildspec / CodeDeploy appspec
• CodeDeploy 배포 구성
• AWS CLI 레퍼런스

Kubernetes 공식 문서

• Pod / ReplicaSet / Deployment
• Service / Ingress
• HorizontalPodAutoscaler
• ConfigMap / Secret
• PersistentVolume
• kubeadm / Calico CNI
• Nginx Ingress Controller

참고 아티클

• GeeksforGeeks — Kubernetes Architecture
• GeeksforGeeks — AWS IAM
• GeeksforGeeks — RDS Read Replicas vs Multi-AZ
• GeeksforGeeks — Container vs VM
• GeeksforGeeks — AWS EC2 Instance Types
• GeeksforGeeks — AWS CI/CD Pipeline

2026 AX 아이디어 경진대회 서류 심사를 통과하여 본선 발표 대상자로 선정되었다. 이번 대회에서는 아이디어 기획 부문 9팀, 제품·서비스 부문 8팀, 자유분석 부문 9팀, 지정분석 부문 8팀 등 총 34개 팀이 본선에 진출하였다. 우리 팀은 지정분석 부문에 선정되어 8개 팀과 함께 발표를 진행하고 평가 받게 되었다. 발표 준비와 함께 제4회 문화체육관광 인공지능·데이터 활용 공모전도 병행하고 있었고, 해당 프로젝트를 Unity로 개발하다 보니 블로그 작성이 조금 늦어지게 되었다. 여기에 더해 코딩 테스트 공부와 다른 프로젝트들도 함께 진행하고 있어 생각보다 여유가 없었다. 그래도 그동안 경험한 내용들을 기록으로 남기는 것은 중요하다고 생각하기 때문에, 늦었지만 다시 블로그 작성을 시작해보려고 한다. 잠시 멈춰 있었던 만큼 앞으로는 학습 과정과 프로젝트 진행 내용, 공모전 준비 과정 등을 꾸준히 정리해 나갈 예정이다. (공모전 수상 및 다른 이슈가 있다면 다 정리해서 한번에 올려야지..) 다시 하나씩 기록해 보자.

1. Spring Boot

1.1 Spring -> Spring Boot

Spring은 Java 엔터프라이즈 개발의 표준 프레임워크다. 그런데 초기 Spring은 XML 설정 파일, 의존성 버전 충돌, 외부 Tomcat 설치까지 시작 전에 할 일이 너무 많았다. Spring Boot는 그 불편함을 해소하기 위해 만들어진 확장판이다.

Spring Boot = Spring + 자동 설정 + 내장 서버 + Starter 의존성. Spring을 "사람이 쓸 수 있게" 만든 것이다.

1.2 IoC Container와 Bean

Spring의 핵심 개념이다. IoC(Inversion of Control, 제어의 역전)은 객체 생성과 관리를 개발자가 아닌 Spring Container가 대신 담당하는 것이다.

// IoC 없이 — 개발자가 직접 생성·연결
BookRepository repo = new BookRepository();
BookService service = new BookService(repo);

// Spring IoC — Container가 생성하고 주입해준다
@Service
public class BookService {
    private final BookRepository bookRepository; // Spring이 알아서 넣어준다
}

Spring Container가 관리하는 객체를 Bean이라고 부른다. @ComponentScan이 패키지를 스캔해서 아래 어노테이션이 붙은 클래스를 자동으로 Bean으로 등록한다.

@SpringBootApplication 안에 @ComponentScan이 포함되어 있다. 그래서 같은 패키지 하위의 모든 @Service, @Repository 등이 자동으로 등록된다.

1.3 프로젝트 구조

Spring Initializr (start.spring.io)로 생성하면 기본 구조가 잡힌다.

bookapp/
├── src/
│   ├── main/
│   │   ├── java/com/aivle/bookapp/
│   │   │   ├── BookappApplication.java   ← 진입점
│   │   │   ├── controller/               ← HTTP 요청 처리
│   │   │   ├── domain/                   ← 엔티티 (테이블 대응)
│   │   │   ├── repository/               ← DB 접근
│   │   │   ├── service/                  ← 비즈니스 로직
│   │   │   └── exception/                ← 예외 처리
│   │   └── resources/
│   │       └── application.yaml          ← 설정 파일
│   └── test/
└── build.gradle                          ← 의존성 관리

이 구조가 Layered Architecture(계층형 아키텍처)다. 요청이 Controller → Service → Repository 순서로 흘러내려간다. 각 레이어가 자기 역할만 하도록 분리되어 있다.

1.4 application.yaml 설정

server:
  port: 8080

spring:
  datasource:
    driver-class-name: org.h2.Driver
    url: jdbc:h2:mem:bookdb
    username: sa
    password: 1234
  h2:
    console:
      enabled: true
      path: /h2-console
  jpa:
    hibernate:
      ddl-auto: create   # 앱 시작 시 테이블 자동 생성
    show-sql: true       # 실행되는 SQL을 콘솔에 출력

H2는 인메모리 데이터베이스다. 앱을 끄면 데이터가 사라지지만, MySQL 설치 없이 바로 쓸 수 있어서 개발·학습 단계에서 유용하게 사용된다. /h2-console에서 브라우저로 DB를 직접 확인할 수 있다.

ddl-auto 옵션은 환경에 따라 달리 설정해야 한다. 잘못 설정하면 운영 DB 테이블이 날아갈 수 있다.

운영 환경에서는 반드시 none으로 설정한다. create를 운영에 쓰면 서버 재시작 때마다 모든 데이터가 삭제된다.

2. 첫 번째 API — @RestController

2.1 @SpringBootApplication

@SpringBootApplication
public class BookappApplication {
    public static void main(String[] args) {
        SpringApplication.run(BookappApplication.class, args);
    }
}

@SpringBootApplication은 세 어노테이션의 합성이다.

강의에서는 @Bean CommandLineRunner로 앱 시작 시 초기 데이터를 DB에 넣는 방법을 학습했다.

@Bean
CommandLineRunner init(BookRepository bookRepository) {
    return args -> {
        Book b1 = new Book();
        b1.setTitle("자바의 정석");
        b1.setAuthor("남궁성");
        bookRepository.save(b1);

        Book b2 = new Book();
        b2.setTitle("Spring 입문");
        b2.setAuthor("임한울");
        bookRepository.save(b2);
    };
}

CommandLineRunner는 앱 구동이 완료된 직후 한 번 실행된다. 테스트 데이터 세팅이나 초기화 작업에 쓴다.

2.2 @RestController와 URL 매핑

@RestController
public class HelloController {

    @GetMapping("/hello/{name}")
    public String hello(@PathVariable String name) {
        return "Hello, " + name + "!";
    }

    @GetMapping("/greet")
    public String greet(@RequestParam(defaultValue = "en") String lang) {
        if (lang.equals("ko")) {
            return "안녕하세요";
        }
        return "Hello";
    }
}

// @RequestBody 사용 예
@PostMapping("/books")
public ResponseEntity<Book> createBook(@RequestBody Book book) {
    // {"title": "Spring 입문", "author": "임한울"} → Book 객체로 변환
    Book saved = bookService.create(book);
    return ResponseEntity.status(HttpStatus.CREATED).body(saved);
}

@PathVariable은 리소스 식별에, @RequestParam은 필터·옵션 설정에, @RequestBody는 POST/PATCH 요청의 본문 수신에 쓴다.

2.3 하드코딩 → DB 연결로의 진화

강의 초반에는 Book을 직접 생성해 반환하게 진행했다.

// 처음 — 하드코딩
@GetMapping("/books/1")
public Book getBook() {
    return new Book(1L, "Spring Boot 입문", "임한울");
}

실제 서비스에서 데이터는 DB에서 꺼내야 한다.

3. 데이터베이스 연결 — JPA와 H2

3.1 JPA란?

JPA(Java Persistence API)는 Java 객체를 관계형 DB 테이블과 매핑해주는 표준 인터페이스다.

구현체는 Hibernate이고, Spring Boot는 Hibernate를 기본으로 사용한다.

Java 객체 (Book)  ←→  JPA / Hibernate  ←→  DB 테이블 (book)

SQL을 직접 쓰는 대신 Java 코드로 DB를 다룰 수 있게 해준다.

3.2 @Entity — 클래스와 테이블 매핑

@Entity
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class Book {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 200)
    @NotBlank
    private String title;

    @Column(nullable = false)
    @NotBlank
    private String author;
}

클래스 이름이 테이블 이름, 필드가 컬럼이 된다. Book 클래스 → book 테이블 자동 생성.

3.3 JpaRepository — CRUD 자동 제공

public interface BookRepository extends JpaRepository<Book, Long> {
    // 인터페이스 선언만 해도 구현체를 Spring이 자동으로 만들어준다
}

코드가 없어도 아래 메서드들이 즉시 사용 가능하다.

3.4 Dirty Checking (변경 감지)

JPA의 Spring에서 좋은 기능 중 하나다. @Transactional 안에서 엔티티를 조회하고 필드 값만 바꾸면, 트랜잭션이 끝날 때 JPA가 변경을 감지해서 자동으로 UPDATE 쿼리를 날린다.

@Transactional
public Book update(Long id, Book book) {
    Book existing = findById(id);           // DB에서 조회 → 영속성 컨텍스트에 등록
    if (book.getTitle() != null) {
        existing.setTitle(book.getTitle()); // 값만 변경
    }
    if (book.getAuthor() != null) {
        existing.setAuthor(book.getAuthor());
    }
    return bookRepository.save(existing);   // save 없이도 트랜잭션 종료 시 자동 UPDATE
}

save()를 명시적으로 호출하지 않아도 트랜잭션 커밋 시점에 변경된 필드만 UPDATE된다. 이게 Dirty Checking이다.

4. Query Method — SQL 없이 쿼리 만들기

4.1 메서드 이름으로 쿼리 자동 생성

Spring Data JPA의 핵심 기능이다. 메서드 이름 규칙만 따르면 SQL을 한 줄도 쓰지 않아도 쿼리가 자동 생성된다.

public interface BookRepository extends JpaRepository<Book, Long> {
    List<Book> findByTitle(String title);                         // WHERE title = ?
    List<Book> findByAuthor(String author);                       // WHERE author = ?
    List<Book> findByTitleContaining(String keyword);             // WHERE title LIKE '%?%'
    List<Book> findByTitleAndAuthor(String title, String author); // WHERE title = ? AND author = ?
}

주요 키워드 목록:

findByTitleContaining("Spring")만 선언하면 WHERE title LIKE '%Spring%'이 자동 생성된다. 메서드 이름이 곧 SQL이다.

4.2 Stream API와의 결합

Java 강의에서 배운 Stream이 여기서 사용된다.

// 특정 저자의 모든 책 제목만 추출
public List<String> authorGetTitle(String author) {
    List<Book> books = bookRepository.findByAuthor(author);
    return books.stream()
                .map(book -> book.getTitle())
                .toList();
}

5. Service 레이어 분리

5.1 왜 Service가 필요한가?

강의 중반까지는 Controller가 Repository를 직접 사용했다.

// Controller가 Repository를 직접 사용하는 방식
@RestController
@RequiredArgsConstructor
public class BookController {
    private final BookRepository bookRepository;

    @GetMapping("/books/{id}")
    public Book getBook(@PathVariable Long id) {
        return bookRepository.findById(id)
                .orElseThrow(() -> new RuntimeException("Book not found: " + id));
    }
}

로직이 단순할 때는 괜찮지만, 검증·예외 처리·복잡한 비즈니스 로직이 늘어나면 Controller가 비대해진다. Service 레이어를 분리하면 각 레이어의 책임이 명확해진다.

Controller — HTTP 요청/응답 형식 담당 (어떤 요청인지)
Service    — 비즈니스 로직 담당 (어떻게 처리할지)
Repository — DB 접근 담당 (어디서 꺼낼지)

5.2 의존성 주입(DI) 3가지 방식

Spring에서 Bean을 주입하는 방법은 세 가지다.

// 1. 필드 주입 — 코드가 짧지만 테스트하기 어렵고 Spring 권장 안 함
@Autowired
private BookRepository bookRepository;

// 2. Setter 주입 — 선택적 의존성에 사용 (잘 안 씀)
@Autowired
public void setBookRepository(BookRepository bookRepository) {
    this.bookRepository = bookRepository;
}

// 3. 생성자 주입 (권장) — 불변성 보장, 테스트 용이, 순환 의존성 감지
private final BookRepository bookRepository;

public BookService(BookRepository bookRepository) {
    this.bookRepository = bookRepository;
}

실제로는 @RequiredArgsConstructor로 생성자 주입을 자동화한다.

@Service
@RequiredArgsConstructor           // final 필드를 받는 생성자를 Lombok이 자동 생성
public class BookService {
    private final BookRepository bookRepository; // 생성자 주입이 자동으로 이루어짐
}

Spring 공식 권장 방식은 생성자 주입이다. final로 선언하면 주입 후 변경 불가(불변성), 테스트 시 Mock 객체를 직접 넣을 수 있다(테스트 용이성).

5.3 @Service와 @Transactional

@Service
@RequiredArgsConstructor
public class BookService {
    private final BookRepository bookRepository;

    @Transactional(readOnly = true)
    public Book findById(Long id) {
        return bookRepository.findById(id)
                .orElseThrow(() -> new BookNotFoundException(id));
    }

    @Transactional
    public Book create(Book book) {
        return bookRepository.save(book);
    }

    @Transactional
    public Book update(Long id, Book book) {
        Book existing = findById(id);
        if (book.getTitle() != null) existing.setTitle(book.getTitle());
        if (book.getAuthor() != null) existing.setAuthor(book.getAuthor());
        return bookRepository.save(existing);
    }

    @Transactional
    public void deleteBook(Long id) {
        if (!bookRepository.existsById(id)) {
            throw new BookNotFoundException(id);
        }
        bookRepository.deleteById(id);
    }
}

@Transactional은 하나의 작업이 전부 성공하거나, 실패하면 전부 롤백됨을 보장한다. DB의 ACID 원칙 중 Atomicity(원자성)을 코드 레벨에서 보장하는 것이다.

Java 강의에서 배운 DI 패턴이 여기서 그대로 나온다. BookService는 BookRepository 인터페이스에 의존하고, Spring이 구현체를 주입해준다.

6. 예외처리 — @RestControllerAdvice

6.1 사용자 정의 예외

public class BookNotFoundException extends RuntimeException {
    public BookNotFoundException(Long id) {
        super("Book not found: id=" + id);
    }
}

Java 강의의 PaymentFailedException과 구조가 동일하다. RuntimeException("Book not found")보다 BookNotFoundException이 훨씬 명확하다.

RuntimeException을 상속하면 throws 선언 없이 사용할 수 있다. Spring Boot는 체크 예외보다 언체크 예외(RuntimeException)를 권장한다.

6.2 @RestControllerAdvice — 전역 예외 처리기

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BookNotFoundException.class)
    public ResponseEntity<Map<String, String>> handleNotFound(BookNotFoundException e) {
        Map<String, String> body = Map.of(
            "error", "Book not found",
            "message", e.getMessage()
        );
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(body);
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidation(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldError().getDefaultMessage();
        Map<String, String> body = Map.of("error", "Validation failed", "message", msg);
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(body);
    }
}

@RestControllerAdvice는 모든 Controller의 예외를 한 곳에서 잡아서 처리한다. 각 Controller마다 try-catch를 쓰는 대신, 이 클래스 하나가 전역 예외 처리기 역할을 한다.

Controller마다 try-catch를 뿌리는 대신 한 곳에서 일괄 처리한다. AOP(관점 지향 프로그래밍)의 개념이 여기서 적용된다.

7. Lombok과 Validation

7.1 Lombok — 반복 코드 제거

Lombok은 컴파일 시점에 어노테이션을 읽어서 코드를 자동 생성해주는 라이브러리다.

// Lombok 없이 — 매번 직접 작성
public class Book {
    private String title;
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }
    public Book() {}
    public Book(Long id, String title, String author) { ... }
}

// Lombok 있으면 — 어노테이션으로 끝
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class Book { ... }

@RequiredArgsConstructor는 Service, Controller에서 생성자 주입 자동화에 쓴다.

7.2 @Builder — 가독성 높은 객체 생성

필드가 많은 객체를 생성할 때 생성자 인자 순서를 외우는 것보다 훨씬 가독성이 좋다.

@Builder
@Getter
public class Book {
    private Long id;
    private String title;
    private String author;
}

// 생성자 방식 — 인자 순서를 외워야 함
Book book = new Book(null, "Spring 입문", "임한울");

// Builder 방식 — 어떤 값인지 명확
Book book = Book.builder()
    .title("Spring 입문")
    .author("임한울")
    .build();

7.3 @Valid와 Bean Validation

// Book 엔티티에 검증 조건 선언
@NotBlank
private String title;

@NotBlank
private String author;

// Controller에서 @Valid로 검증 적용
@PostMapping("/books")
public ResponseEntity<Book> createBook(@Valid @RequestBody Book book) {
    Book saved = bookService.create(book);
    return ResponseEntity.status(HttpStatus.CREATED).body(saved);
}

@Valid가 붙으면 요청 본문을 역직렬화할 때 제약 조건을 검사한다. 검증 실패 시 MethodArgumentNotValidException이 발생하고, GlobalExceptionHandler가 400 Bad Request로 처리한다.

자주 쓰는 Bean Validation 어노테이션:

검증 로직을 Controller 안에 if문으로 직접 쓰는 대신, 어노테이션으로 선언하고 전역 핸들러로 처리하는 패턴이다. 코드가 훨씬 깔끔해진다.

8. 페이징과 정렬

8.1 PageRequest

대용량 데이터를 한 번에 내려주면 성능이 나쁘다. 페이징으로 나눠서 전달한다.

@Transactional(readOnly = true)
public Page<Book> getPage(int page, int size, String sortBy) {
    Sort sort = Sort.by(sortBy).ascending();   // 오름차순
    // Sort sort = Sort.by(sortBy).descending(); // 내림차순
    Pageable pageable = PageRequest.of(page, size, sort);
    return bookRepository.findAll(pageable);
}

@GetMapping("/books/page")
public Page<Book> getPage(
    @RequestParam int page,
    @RequestParam int size,
    @RequestParam String sortBy
) {
    return bookService.getPage(page, size, sortBy);
}

GET /books/page?page=0&size=10&sortBy=title을 호출하면 제목순 정렬로 첫 10개를 반환한다.

8.2 Page 응답 구조

Page<Book> 응답에는 데이터뿐 아니라 메타데이터도 함께 담긴다.

{
  "content": [ { "id": 1, "title": "자바의 정석", "author": "남궁성" }, ... ],
  "totalElements": 5,    // 전체 데이터 수
  "totalPages": 1,       // 전체 페이지 수
  "number": 0,           // 현재 페이지 번호 (0-based)
  "size": 10,            // 페이지 크기
  "first": true,         // 첫 페이지 여부
  "last": true           // 마지막 페이지 여부
}

프론트엔드에서 "다음 페이지" 버튼 표시 여부를 last 필드로 판단할 수 있다.

9. CRUD 완성 — HTTP 메서드 매핑

9.1 REST API 설계 원칙

@GetMapping("/books/{id}")       // 단건 조회
@GetMapping("/books")            // 전체 조회
@PostMapping("/books")           // 생성
@PatchMapping("/books/{id}")     // 부분 수정
@DeleteMapping("/books/{id}")    // 삭제

PUT vs PATCH 차이: PUT은 전체 교체(보내지 않은 필드는 null로 덮어씀), PATCH는 보낸 필드만 수정한다. 강의 실습에서 @PatchMapping을 쓴 이유가 이것이다.

9.2 ResponseEntity — 상태 코드 직접 지정

ResponseEntity를 쓰면 HTTP 상태 코드, 헤더, 바디를 직접 제어할 수 있다.

@PostMapping("/books")
public ResponseEntity<Book> createBook(@Valid @RequestBody Book book) {
    Book saved = bookService.create(book);
    return ResponseEntity.status(HttpStatus.CREATED).body(saved); // 201 + body
}

@DeleteMapping("/books/{id}")
public ResponseEntity<Void> deleteBook(@PathVariable Long id) {
    bookService.deleteBook(id);
    return ResponseEntity.noContent().build(); // 204 + 빈 body
}

@GetMapping("/books/{id}")
public ResponseEntity<Book> getBook(@PathVariable Long id) {
    Book book = bookService.findById(id);
    return ResponseEntity.ok(book); // 200 + body (축약형)
}

10. Spring Boot의 핵심 흐름 정리

강의를 통해 하나의 HTTP 요청이 어떻게 처리되는지 전체 흐름을 정리하자.

[클라이언트] POST /books {"title": "Spring 입문", "author": "임한울"}
     ↓
[DispatcherServlet] 요청을 적절한 Controller로 라우팅
     ↓
[BookController] @Valid로 입력값 검증 → BookService.create() 호출
     ↓
[BookService] @Transactional 시작 → bookRepository.save() 호출
     ↓
[BookRepository] JpaRepository → Hibernate → SQL 실행
     ↓
[DB] INSERT INTO book (title, author) VALUES (?, ?)
     ↓
[응답] 201 Created + 저장된 Book JSON

예외가 발생하면:

[BookService] BookNotFoundException 발생
     ↓
[GlobalExceptionHandler] @ExceptionHandler가 잡아서 처리
     ↓
[응답] 404 Not Found + {"error": "Book not found", "message": "..."}

생각정리

Spring을 앞으로 자주 사용할지는 아직 모르겠다. 최근에는 목적에 따라 다양한 서버 기술들이 사용되고 있기 때문이다. Python 기반 또는 간단한 프로젝트에서는 FastAPI나 Flask를 사용하는 경우가 많고, JavaScript 생태계에서는 Node.js와 Express, NestJS를 활용하는 사례도 많다. 또한 AI 서비스를 개발할 때는 모델 추론 서버를 FastAPI로 구축하는 경우가 흔하며, 게임이나 소규모 프로젝트에서는 Firebase나 Supabase 같은 BaaS 서비스를 활용하여 별도의 서버 개발 없이 기능을 구현하기도 한다. AWS Lambda와 같은 서버리스 환경을 사용하면 서버를 직접 운영하지 않고도 백엔드 기능을 제공할 수 있다.

그럼에도 이번 Spring 학습은 단순히 특정 프레임워크를 배우는 것 이상의 의미가 있었다. 어떤 기술 스택을 선택하더라도 서버 애플리케이션은 의존성 관리, 계층 분리, 예외 처리, 데이터 접근과 같은 공통적인 문제를 해결해야 한다. Spring은 이러한 문제들을 체계적으로 다루는 방법을 제공했고, Java 수업에서 배웠던 객체지향 설계 원칙들이 실제 프로젝트에서 어떻게 활용되는지를 이해할 수 있게 해주었다.

특히 Java 강의에서 학습했던 내용들이 Spring에서 자연스럽게 연결된다는 점과 실제 다음 미니프로젝트에서 연결해 사용할 수 있다는점이 좋았다. (예비군 참여로 인해 프로젝트에 기여한점은 없었다.) 인터페이스를 활용한 다형성은 의존성 주입(DI) 구조로 이어졌고, 사용자 정의 예외는 서비스 계층의 예외 처리 방식으로 확장되었다.

그중에서도 가장 생각해보고 고민한 부분은 생성자 주입 방식이었다. Java 수업에서는 객체를 직접 생성하거나 의존성을 전달하는 코드를 작성했지만, Spring에서는 @RequiredArgsConstructor와 final 키워드만으로 의존성 주입이 자동으로 이루어졌다. 덕분에 객체 간 결합도를 낮추면서도 코드를 더욱 간결하게 유지할 수 있었다.

학습 과정에서 가장 어려웠던 점은 레이어를 분리하는 기준을 이해하는 것이었다. Controller, Service, Repository 구조 자체는 이해할 수 있었지만 어떤 로직을 어느 계층에 배치해야 하는지 판단하는 것이 쉽지 않았다. 하지만 "HTTP 요청과 응답 처리는 Controller, 비즈니스 로직은 Service, 데이터 접근은 Repository"라는 기준을 세워야 각 계층의 역할이 명확하게 보인다고 생각한다. 이후에는 코드를 작성할 때도 책임을 분리하여 설계할 수 있었다.

JPA의 Dirty Checking 역시 처음에는 매우 신기한 기능으로 느껴졌다. 데이터를 수정한 뒤 save()를 호출하지 않았는데도 데이터베이스의 값이 변경되는 이유를 이해하지 못했지만, 영속성 컨텍스트가 엔티티의 상태를 추적하고 트랜잭션 종료 시점에 변경 사항을 자동으로 반영한다는 원리를 학습하면서 동작 과정을 이해할 수 있었다. 내부적으로 어떤 방식으로 넘어가는 후에 글을 찾아보며 공부해보자. 10-2글을 마무리한다.

출처/참고

• Spring Boot 공식 문서
• Spring Data JPA — 공식 레퍼런스
• Spring Data JPA — Query Methods
• Spring Framework — IoC Container
• Spring Framework — @Transactional
• Lombok 공식 문서
• Jakarta Bean Validation
• H2 Database 공식 문서
• Spring MVC — @RestControllerAdvice
• GeeksforGeeks — Spring Boot Architecture
• 실습 코드 (GitHub)

미니 프로젝트를 마친 후에는 프론트엔드와 백엔드를 연동하기 위해 Spring 학습할 예정이다. Spring은 Java를 기반으로 동작하는 프레임워크이기 때문에, Spring을 제대로 이해하기 위해서는 먼저 Java의 기본 문법과 객체지향 프로그래밍 개념을 익혀야 했다. 따라서 Java를 선수 학습한 뒤 Spring을 공부하는 순서로 학습을 진행했다. 이후에는 학습한 내용을 바탕으로 05 미니 프로젝트를 진행하며 실제로 프론트엔드와 백엔드를 연결해 볼 예정이다. 이번 주 정리에서는 학습한 내용이 많아 두 편으로 나누어 작성하려 한다. 이번 글(10주차-1)에서는 Java 학습 내용을 정리하고, 다음 글에서는 Spring(10주차-2) 학습 내용을 다룰 예정이다. 그럼 먼저 Java 학습 내용을 간단히 살펴보자. (IntelliJ IDEA 사용해 진행)

1. Java 언어의 기초

1.1 왜 Java인가?

수업 첫날부터 강사님이 짚어준 부분이다. 국내 백엔드 채용 시장에서 Java/Spring 비율은 약 70~80%다. 전자정부 프레임워크도 Spring 기반이고, 카카오·네이버·배달의민족 등 주요 IT 기업의 백엔드 기술 스택 대부분이 Java + Spring Boot 조합이다.

Python은 AI/ML에 강하지만 대규모 트래픽에서는 Java가 안정적. Java는 타입 안정성 덕분에 컴파일 시점에서 버그를 잡을 수 있다.

1.2 JDK / JRE / JVM 이해하기

Java의 핵심 특징은 WORA(Write Once, Run Anywhere)다. 한 번 작성하면 OS에 상관없이 어디서든 실행된다. 이게 가능한 이유가 JVM이다.

개발자 코드 (.java)
       ↓  javac 컴파일
   바이트코드 (.class)
       ↓  JVM이 각 OS 맞춤형 기계어로 번역
   Windows / Mac / Linux 에서 실행

1.3 변수와 자료형

Java는 정적 타입 언어다. 변수를 선언할 때 타입을 명시해야 한다. Python처럼 x = 10이 아니라 int x = 10;이다.

중요한 포인트가 하나 있는데, String은 기본 자료형이 아닌 참조 자료형(Reference Type)이다. 때문에 비교할 때 ==이 아니라 반드시 equals()를 써야 한다.

String a = new String("홍길동");
String b = new String("홍길동");

System.out.println(a == b);       // false → 주소를 비교
System.out.println(a.equals(b));  // true  → 실제 내용을 비교

String은 자주 쓰는 메서드들이 많다.

String name = "Alice";
System.out.println(name.length());          // 5
System.out.println(name.contains("li"));    // true
System.out.println(name.toUpperCase());     // ALICE
System.out.println(name.equals("Alice"));   // true
System.out.println(name.equals("alice"));   // false — 대소문자 구분

형변환(Casting)도 함께 학습했다.

• 작은 타입 → 큰 타입: 자동 변환 (int → double)
• 큰 타입 → 작은 타입: 명시적 변환 필요 ((int) 3.14 → 3, 소수점 버려짐)
• String ↔ 숫자: Integer.parseInt("123"), String.valueOf(123)

int x = 10;
double y = x;                      // 자동 변환: 10.0
int z = (int) 3.14;                // 명시적 변환: 3 (소수점 버려짐)
int n = Integer.parseInt("123");   // String → int: 123
String s = String.valueOf(123);    // int → String: "123"

1.4 Scanner로 사용자 입력 받기

Scanner는 java.util 패키지에 있어서 import가 필요하다.

import java.util.Scanner;

Scanner scanner = new Scanner(System.in);
int age = scanner.nextInt();          // 정수 입력
double height = scanner.nextDouble(); // 실수 입력
String line = scanner.nextLine();     // 한 줄 전체 (공백 포함)
String word = scanner.next();         // 단어 하나 (공백 제외)

scanner.close(); // 사용 후 반드시 닫기

nextInt() 이후 nextLine()을 쓰면 버퍼에 남아있는 \n 때문에 입력이 건너뛰어지는 문제가 생긴다. 실습하다가 직접 겪어봤다.

1.5 연산자

전위 vs 후위 증감 연산자:

int a = 5;
int b = ++a;  // a를 먼저 증가시키고 대입 → a=6, b=6

int c = 5;
int d = c++;  // 먼저 대입하고 나서 증가 → c=6, d=5

단락 평가(Short-circuit):

false && (10 / 0 > 5)  // 앞이 false면 뒤는 실행 안 됨 → 오류 발생 안 함
true  || (10 / 0 > 5)  // 앞이 true면 뒤는 실행 안 됨  → 오류 발생 안 함

불필요한 계산을 생략해서 성능을 높이고, 오류도 방지한다.

int year = 2024;
boolean isLeapYear = (year % 4 == 0 && year % 100 != 0) || (year % 400 == 0);
System.out.println(year + "년은 " + (isLeapYear ? "윤년" : "평년")); // 2024년은 윤년

2. 흐름 제어

2.1 조건문 — if와 switch-case

if ~ else if ~ else와 switch ~ case 두 가지 패턴을 다뤘다.

int age = 19;
if (age >= 18) {
    System.out.println("성인");
} else {
    System.out.println("미성년자");
}

// else-if: 연령대 분류
if (age < 13) {
    System.out.println("어린이");
} else if (age < 19) {
    System.out.println("청소년");
} else {
    System.out.println("성인");
}

switch는 하나의 변수를 여러 값과 비교할 때 가독성이 좋다. break를 빠뜨리면 아래 case로 계속 흘러내리는 fall-through 현상이 생기는데, 의도적으로 활용하면 여러 case를 묶을 수 있다.

switch (month) {
    case 3: case 4: case 5:
        System.out.println("봄"); // 3, 4, 5 모두 여기서 처리
        break;
    case 6: case 7: case 8:
        System.out.println("여름");
        break;
    default:
        System.out.println("잘못된 입력");
}

2.2 반복문 — for, while, do-while

세 가지 반복문을 모두 학습했다.

• for: 반복 횟수를 미리 아는 경우
• while: 조건이 참인 동안, 횟수가 불확실한 경우
• do-while: 최소 한 번은 무조건 실행하고 싶을 때

break와 continue의 차이:

for (int i = 0; i <= 10; i++) {
    if (i == 5) break;     // 반복문 즉시 종료
    if (i == 3) continue;  // 이번 회차만 건너뜀, 반복은 계속
    System.out.println(i);
}

int sum = 0;
for (int i = 1; i <= 100; i++) {
    sum += i;
}
System.out.println("합계: " + sum); // 5050

// while: 9가 입력될 때까지 계속 받기
Scanner scanner = new Scanner(System.in);
int input = 0;
while (input != 9) {
    System.out.print("숫자 입력 (9 = 종료): ");
    input = scanner.nextInt();
}

// continue로 짝수만 더하기
int evenSum = 0;
for (int i = 1; i <= 10; i++) {
    if (i % 2 != 0) continue; // 홀수는 건너뜀
    evenSum += i;
}
System.out.println("짝수 합계: " + evenSum); // 30

2.3 배열

배열은 크기가 고정이다. 선언할 때 크기를 정해야 하고, 반복문과 함께 쓰는 게 기본이다.

int[] scores = new int[5];

for (int i = 0; i < scores.length; i++) {
    scores[i] = scanner.nextInt();
}

int[] scores = {80, 90, 70, 60, 85};
int total = 0;

for (int i = 0; i < scores.length; i++) {
    total += scores[i];
}
double average = (double) total / scores.length;
System.out.println("평균: " + average); // 77.0

scores.length로 크기를 구할 수 있다. 배열은 크기가 고정이라 나중에 배울 ArrayList의 동적 크기 조절이 왜 필요한지 자연스럽게 이해됐다.

3. 메서드와 재사용성

3.1 메서드란?

특정 코드를 모아서 이름을 붙인 집합. 다른 언어의 '함수'와 유사하다. 반복되는 코드를 한 곳에 두고 이름으로 호출할 수 있어 가독성과 유지보수성이 올라간다.

// 반환값이 있는 메서드
public static int add(int a, int b) {
    return a + b;
}

// 반환값이 없는 메서드
public static void printResult(int result) {
    System.out.println("결과: " + result);
}

public static int sub(int a, int b) { return a - b; }
public static int mul(int a, int b) { return a * b; }
public static int div(int a, int b) { return a / b; }

System.out.println(add(17, 5)); // 22
System.out.println(sub(17, 5)); // 12
System.out.println(mul(17, 5)); // 85
System.out.println(div(17, 5)); // 3

3.2 메서드 오버로딩 (Overloading)

같은 이름, 다른 매개변수로 여러 메서드를 정의하는 것. 컴파일러가 호출 시 인자 타입을 보고 어떤 메서드를 쓸지 결정한다.

public static int add(int a, int b) { return a + b; }
public static double add(double a, double b) { return a + b; }

add(10, 20);      // int 버전 호출
add(3.14, 2.71);  // double 버전 호출

매개변수 개수가 달라도 오버로딩이 성립한다.

public static int max(int a, int b) { return a > b ? a : b; }
public static int max(int a, int b, int c) { return max(max(a, b), c); }
public static double max(double a, double b) { return a > b ? a : b; }

max(3, 7);        // int 2개 → 7
max(1, 5, 3);     // int 3개 → 5
max(3.14, 2.71);  // double 2개 → 3.14

반환값만 다르고 매개변수가 같으면 오버로딩이 성립하지 않는다. 이게 처음에 헷갈렸다.

4. 객체지향 프로그래밍 (OOP)

4.1 클래스와 객체

클래스 (Car.java)     ← 설계도, 자료형 역할, 1개
       ↓  new
객체 (avante, sonata) ← 실체, 여러 개 생성 가능

4.2 접근제한자 (Access Modifier)

필드와 메서드에 누가 접근할 수 있는지를 제어하는 키워드다. 4가지가 있다.

이 강의에서 중점적으로 다룬 건 public과 private 두 가지다. protected는 상속 파트에서 다시 등장한다.

4.3 캡슐화 (Encapsulation)

필드를 private으로 막고 Getter/Setter를 통해서만 접근하게 하는 패턴. 단순히 접근을 막는 게 목적이 아니라, 객체가 자기 데이터를 스스로 보호하는 게 핵심이다. Setter 안에서 유효성 검사를 넣을 수 있다.

public void setMaxSpeed(int maxSpeed) {
    if (maxSpeed < 0 || maxSpeed > 300) {
        System.out.println("잘못된 속도");
        return;
    }
    this.maxSpeed = maxSpeed;
}

Setter 안에 검증 로직이 있으니, 외부에서는 잘못된 값을 넣어도 객체 내부 상태가 오염되지 않는다.

public void setKorean(int korean) {
    if (korean < 0 || korean > 100) {
        System.out.println("점수는 0 ~ 100 사이여야 합니다.");
        return;
    }
    this.korean = korean;
}

student.setKorean(150); // "점수는 0 ~ 100 사이여야 합니다." 출력, 값 반영 안 됨
student.setKorean(85);  // 정상 저장

4.4 생성자 (Constructor)

객체 생성 시점에 필드를 한 번에 초기화하는 특별한 메서드다. 반환 타입이 없고 클래스 이름과 동일하다.

// 매번 setter를 따로 호출하던 것을
Car a = new Car();
a.setColor("Red");
a.setMaxSpeed(120);

// 생성자 하나로 해결
Car a = new Car("Red", 120, 3);

this 키워드는 "이 객체 자신"을 가리킨다. 매개변수 이름과 필드 이름이 같을 때 구분하는 데 쓴다.

public Car(String color, int maxSpeed) {
    this.color = color;       // this.color → 필드, color → 매개변수
    this.maxSpeed = maxSpeed;
}

생성자도 오버로딩이 된다. 매개변수 개수나 타입이 다르면 여러 생성자를 정의할 수 있다.

public Car() {                          // 기본 생성자 — 기본값으로 초기화
    this.color = "White";
    this.maxSpeed = 100;
}

public Car(String color, int maxSpeed) { // 매개변수 생성자 — 값을 받아 초기화
    this.color = color;
    this.maxSpeed = maxSpeed;
}

4.5 static 키워드

• static 필드: 모든 객체가 공유하는 하나의 값 (ex. 생성된 객체 수 카운터)
• static 메서드: 객체 없이 클래스명으로 바로 호출

// 우리가 매일 쓰던 이것들이 전부 static
Integer.parseInt("123");
String.valueOf(100);
Math.max(3, 5);

static 필드는 여러 객체가 공유해야 하는 값을 저장할 때 유용하다.

public class Car {
    private static int count = 0;  // 모든 인스턴스가 공유하는 하나의 변수

    public Car(String color, int maxSpeed) {
        this.color = color;
        this.maxSpeed = maxSpeed;
        count++;                   // 객체가 만들어질 때마다 증가
    }

    public static int getCount() { // 객체 없이 클래스명으로 바로 호출
        return count;
    }
}

Car a = new Car("Red", 200);
Car b = new Car("Blue", 150);
System.out.println(Car.getCount()); // 2

4.6 상속 (Inheritance)

공통 코드를 부모 클래스에 한 번만 작성하고, 자식 클래스들이 가져다 쓰는 구조다.

Vehicle (부모)
  ├── color, maxSpeed, start(), stop()
  │
  ├── Car (자식)   : + trunk, openTrunk()
  └── Truck (자식) : + loadCapacity, loadCargo()

자식 클래스에서 extends로 상속을 선언한다.

super 키워드: this가 "이 객체 자신"을 가리키듯, super는 "부모 객체"를 가리킨다. 자식 생성자에서 부모 생성자를 호출할 때 첫 줄에서 반드시 사용한다.

public class Car extends Vehicle {
    private int trunk;

    public Car(String color, int maxSpeed, int trunk) {
        super(color, maxSpeed); // 부모 생성자 호출 — 반드시 첫 줄
        this.trunk = trunk;
    }
}

protected 접근제한자: 부모 클래스의 필드를 private으로 선언하면 자식 클래스에서도 직접 접근이 불가능하다. protected로 선언하면 자식 클래스에서는 직접 접근이 가능하면서, 외부 클래스에서는 막힌다.

public class Vehicle {
    protected String color;   // 자식 클래스에서 직접 접근 가능
    private int maxSpeed;     // 자식 클래스에서도 직접 접근 불가
}

public class Car extends Vehicle {
    public void show() {
        System.out.println(color);     // OK — protected
        System.out.println(maxSpeed);  // 컴파일 에러 — private
    }
}

4.7 메서드 오버라이딩 vs 오버로딩

표로 정리!

// 오버라이딩: @Override 어노테이션으로 명시
@Override
public void move() {
    System.out.println("도로를 달린다"); // 부모의 "이동한다"를 재정의
}

4.8 다형성 (Polymorphism)

부모 타입 변수에 자식 객체를 담을 수 있다(업캐스팅). 같은 메서드 호출이 실제 객체에 따라 다르게 동작한다.

Vehicle[] vehicles = {
    new Car("Red", 200, 500),
    new Truck("White", 100, 5000),
    new Car("Black", 180, 400)
};

for (Vehicle v : vehicles) {
    v.move(); // Car면 "도로를 달린다", Truck이면 "화물을 싣고 달린다"
}

새 자식 클래스가 추가되어도 for 문 코드는 수정 불필요. 유지보수성과 확장성의 핵심이다.

instanceof + 다운캐스팅: 업캐스팅된 변수로는 자식 고유의 메서드를 호출할 수 없다. 실제 타입을 확인한 뒤 자식 타입으로 명시적으로 변환(다운캐스팅)해야 한다.

Vehicle v = new Car("Red", 200, 500);

v.move();        // OK — Vehicle에 있는 메서드
v.openTrunk();   // 컴파일 에러 — Vehicle에는 없음

// instanceof로 실제 타입 확인 후 다운캐스팅
if (v instanceof Car) {
    Car c = (Car) v;   // 다운캐스팅
    c.openTrunk();     // OK
}

배열에서 자식별로 다른 처리가 필요할 때 자주 쓰이는 패턴이다.

for (Vehicle v : vehicles) {
    v.move();  // 공통 동작
    if (v instanceof Car) {
        ((Car) v).openTrunk();
    } else if (v instanceof Truck) {
        ((Truck) v).loadCargo();
    }
}

5. 인터페이스와 설계 패턴

5.1 인터페이스란?

Java는 단일 상속만 지원한다. 그런데 한 객체가 여러 "역할"을 동시에 가져야 하는 경우가 많다. Car는 "탈것"이면서 동시에 "팔 수 있는 상품"이기도 하다.

상속 (extends)        → "이런 종류의 것이다" (한 개만 가능)
인터페이스 (implements) → "이런 일을 할 수 있다" (여러 개 가능)

public class Car extends Vehicle implements Sellable, Insurable {
    // 종류는 Vehicle 하나
    // 역할은 Sellable + Insurable 둘 다
}

인터페이스는 메서드 시그니처만 정의하고 구현하지 않는다. 구현체(클래스)가 implements로 받아 실제 동작을 채워 넣는다.

5.2 의존성 주입(DI) 패턴

강한 결합의 문제:

// OrderService 안에 KakaoPay를 직접 생성하면
// 결제 수단을 바꾸려면 OrderService 코드를 직접 수정해야 함
private KakaoPay payment = new KakaoPay();

인터페이스 기반 느슨한 결합:

public class OrderService {
    private final PaymentMethod payment; // 인터페이스 타입

    public OrderService(PaymentMethod payment) {
        this.payment = payment; // 외부에서 주입
    }
}

// 구현체를 자유롭게 교체 가능, OrderService 코드 수정 0
new OrderService(new KakaoPay());
new OrderService(new NaverPay());
new OrderService(new CreditCard());

Spring Boot의 @Autowired가 이 "외부에서 주입"하는 과정을 자동으로 해준다. 지금 손으로 하는 걸 Spring이 대신해주는 것이다.

이 개념을 이해하고 Spring때 사용하자

6. 예외처리

6.1 런타임 에러를 우아하게 처리하기

컴파일 에러는 IDE가 미리 잡아주지만, 런타임 에러는 실행 중에 갑자기 터진다.

try {
    int num = Integer.parseInt("abc"); // 여기서 예외 발생
    System.out.println("성공: " + num); // 실행 안 됨

} catch (NumberFormatException e) {
    System.out.println("실패: " + e.getMessage()); // 여기로 이동

} finally {
    System.out.println("항상 실행"); // 예외 여부와 무관하게 항상
}

6.2 다중 catch

try 블록에서 여러 종류의 예외가 발생할 수 있을 때 catch를 여러 개 작성한다. 순서가 중요한데, 자식 예외를 부모 예외보다 먼저 작성해야 한다. 부모가 먼저 오면 자식 예외까지 모두 잡아버려 아래 catch가 실행될 일이 없어진다.

try {
    int idx = Integer.parseInt(idxInput);   // NumberFormatException 가능
    int num = data[idx];                    // ArrayIndexOutOfBoundsException 가능

} catch (NumberFormatException e) {
    System.out.println("숫자 변환 실패");

} catch (ArrayIndexOutOfBoundsException e) {
    System.out.println("배열 범위 초과");

} catch (Exception e) {         // 부모 예외는 가장 마지막에
    System.out.println("기타 예외");
}

6.3 throw vs throws

헷갈리기 쉬운 두 키워드다.

// throw — 조건에 맞으면 예외를 직접 발생
public void setMaxSpeed(int maxSpeed) {
    if (maxSpeed < 0) {
        throw new IllegalArgumentException("음수 불가: " + maxSpeed);
    }
    this.maxSpeed = maxSpeed;
}

// throws — 체크 예외를 호출자에게 위임 (RuntimeException은 생략 가능)
public void readFile(String path) throws IOException {
    // 파일 읽기 코드
}

Spring Boot는 RuntimeException 위주라 throws 선언을 거의 쓰지 않는다. 메서드 시그니처가 깔끔하게 유지된다.

6.4 체크 예외 vs 언체크 예외

Spring Boot는 언체크 예외를 선호한다. 비즈니스 로직 코드가 try-catch로 도배되는 걸 방지할 수 있어서다.

6.5 사용자 정의 예외

RuntimeException을 상속해서 의미 있는 이름의 예외를 직접 만든다.

public class PaymentFailedException extends RuntimeException {
    public PaymentFailedException(String reason) {
        super("결제 실패: " + reason);
    }
}

IllegalArgumentException 대신 PaymentFailedException을 쓰면 예외 이름만 봐도 어떤 상황인지 즉시 파악된다. Spring Boot의 UserNotFoundException, OrderNotFoundException 같은 패턴이 전부 이것이다.

7. 컬렉션과 람다

7.1 배열의 한계와 List

배열은 크기가 고정이다. List는 크기가 동적으로 늘어나고 편리한 메서드를 제공한다.

List<String> names = new ArrayList<>();
names.add("홍길동");
names.add("이영희");

names.get(0);            // 조회
names.size();            // 크기
names.remove(0);         // 삭제
names.contains("이영희"); // 포함 여부

7.2 Map — 키-값 쌍으로 저장

Map<String, Integer> scores = new HashMap<>();
scores.put("홍길동", 85);
scores.get("홍길동"); // 85

for (Map.Entry<String, Integer> entry : scores.entrySet()) {
    System.out.println(entry.getKey() + ": " + entry.getValue());
}

List vs Map 선택 기준:

• 순서가 중요하고 인덱스로 접근 → List
• 이름표(키)로 빠르게 찾고 싶음 → Map

7.3 람다 표현식

메서드를 한 줄로 표현하는 문법이다.

// 전통적인 for + if 방식
List<Integer> highScores = new ArrayList<>();
for (int score : scores) {
    if (score >= 70) highScores.add(score);
}

// 람다 + Stream 방식
List<Integer> highScores = scores.stream()
    .filter(score -> score >= 70)
    .collect(Collectors.toList());

7.4 Stream API

컬렉션 데이터를 흐름처럼 처리하는 API다. 3단계 파이프라인으로 동작한다.

stream()          → 컬렉션을 스트림으로 변환
↓
.filter(조건)      → 조건 맞는 것만 통과
.map(변환)         → 각 원소를 다른 형태로 변환
↓
.collect(...)     → List 등으로 수집

// 70점 이상만 필터링하고, 각 점수를 등급 문자열로 변환
List<String> grades = scores.stream()
    .filter(score -> score >= 70)
    .map(score -> score + "점 (Pass)")
    .collect(Collectors.toList());

7.5 Optional — null을 안전하게 다루기

Optional<Integer> first = list.stream().findFirst();

first.ifPresent(n -> System.out.println("첫 원소: " + n)); // 값이 있을 때만
int n = first.orElse(0);                                    // 없으면 기본값
int n = first.orElseThrow(() -> new RuntimeException("없음")); // 없으면 예외

null 체크를 흩뿌리는 대신 Optional로 감싸면, "값이 없을 수도 있다"는 사실이 타입에 드러난다. Spring Data JPA의 findById()가 Optional<T>를 반환하는 이유가 바로 이것이다.

// 지금 배운 것들이 Spring Boot 서비스 코드로 그대로 이어진다
public List<UserDto> findActiveUsers() {
    return userRepository.findAll()
        .stream()
        .filter(u -> u.isActive())
        .map(u -> new UserDto(u.getName()))
        .collect(Collectors.toList());
}

public User findById(Long id) {
    return userRepository.findById(id)
        .orElseThrow(() -> new UserNotFoundException(id)); // 6장 사용자 정의 예외
}

생각정리

학부 과정에서 Java와 Spring을 모두 접해본 경험이 있었기 때문에 이번 학습에서 완전히 새로운 내용을 배우는 느낌은 아니었다. 오히려 예전에 배웠던 개념들을 다시 정리하고, Spring Boot를 사용하기 전에 필요한 Java 기초를 복습하는 시간에 가까웠다. 특히 객체지향 프로그래밍 파트는 예전에도 여러 번 공부했지만, 다시 학습하면서 클래스, 상속, 다형성, 인터페이스가 각각 왜 필요한지 조금 더 명확하게 이해할 수 있었다. 학부 시절에는 문법을 외우는 데 집중했다면, 이번에는 실제 프로젝트를 진행한다는 목적이 있어서 각 개념이 어떤 문제를 해결하기 위해 존재하는지 생각하며 학습하게 되었다. 가장 인상 깊었던 부분은 인터페이스와 의존성 주입 개념이었다. Spring을 사용할 때는 @Service, @Repository, @Autowired 등을 자연스럽게 사용했지만, 이번에는 그 동작 원리가 되는 구조를 Java 코드만으로 직접 구현해보며 다시 정리할 수 있었다. 덕분에 Spring이 단순히 편리한 프레임워크가 아니라 객체지향 설계 원칙을 기반으로 여러 기능을 자동화해주는 도구구나.. 알고 잘 사용하자 라는 느낌을 받은거 같다. 컬렉션, 람다, Stream API, Optional과 같은 기능들은 실제 백엔드 개발 과정에서 자주 사용되는 만큼 활용 방법을 다시 들으며 찾아보고 공부하게 되었다. 특히 Stream API는 데이터를 가공하는 코드를 간결하게 작성할 수 있어 앞으로 진행할 프로젝트에서도 적극적으로 활용할 수 있을 것 같다. 다음 주(11주차)에는 Spring Boot 학습을 통해 이번에 정리한 객체지향 개념과 설계 방식을 생각해보자. (예비군 훈련이 6/8 ~ 6/11이라 참여는 불가능할거 같지만.. 후에 따로 작업해보자) 10주차-1을 마무리한다.

참고/출처

• JVM이란
• class란 + Method
• 오버리이딩 vs 오버로딩
• 다형성 이해하기_java
• java예외처리
• 의존성주입
• IntelliJ IDEA 공식 문서
• Java 공식 문서 (Oracle)
• 점프 투 자바

실습 Code

04미니프로젝트가 끝났다. 지금까지의 프로젝트들(01,02,03)은 AI 쪽 로직이 중심이었다. Multi-Agent, LangGraph, RAG 파이프라인 같은 프로젝트였다. 이번 프로젝트에서는 프론트엔드 개발 전체를 진행했다. React, OpenAI API 연동, 이미지 처리, 컴포넌트 설계, 그리고 팀 코드 병합까지. 이번 회고록엔 "왜 이 프로젝트가 필요한가"라는 배경부터, 실제로 내가 고민하고 결정하고 부딪혔던 기술적인 내용들까지 최대한 상세하게 남겨보려 한다.

12조의 프로젝트가 궁금하다면?

프로젝트 배경 — 왜 이걸 만들어야 하나

책 표지, 그게 그렇게 중요한가?

프로젝트를 시작할 때 강사님이 던진 질문이 있었다.

"책 표지 디자인이 왜 중요할까요?"

처음엔 그냥 예쁘면 되는 거 아닌가 하고 시작하려고 했다. 비슷한 서비스를 개발하고 여러 사이트를 방문하고 내가 조사한 책 표지에 실제 수치를 보고 나서 생각이 바뀌었다. 표지 디자인은 CTR(Click Through Rate, 클릭률), 구매 전환율, SNS 공유율에 직접적인 영향을 준다. 독자는 내용보다 표지를 먼저 본다. 첫인상이 구매를 결정한다.

텍스트 기반 콘텐츠(책 내용)
        ↓
    표지 디자인
"장르와 메시지를 시각적으로 전달"
        ↓
    독자(User)
"끌리는 표지일수록 클릭하고 싶다"
        ↓
CTR · 구매 전환율 · SNS 공유율 증가

그런데 현실적으로 개인 작가나 소규모 창작자가 전문 디자이너에게 표지를 맡기기는 어렵다. 비용도 비용이지만, 수정 피드백을 주고받는 과정도 길다. 감성적인 의도를 언어로 전달하는 것 자체가 어렵기도 하다.

서비스 컨셉 — "걷기가 서재"

이번 프로젝트의 도메인은 "걷기가 서재" 라는 가상의 국내 최대 독서 플랫폼이다. 그 안에 있는 "작가의 산책" 서비스를 구현하는 것이 목표였다.

누구나 작가가 되어 자유롭게 글을 집필하고 공개할 수 있는 창작 플랫폼. 단, 기존 플랫폼과 달리 AI 표지 제작을 지원한다.

이야기가 그대로 표지에 닿도록. 작가의 감성을 AI가 시각화해준다는 컨셉이었다. 텍스트 기반 콘텐츠를 입력하면 AI가 거기에 어울리는 표지를 자동으로 만들어주는 것이다. 이 맥락을 이해하고 나서야 단순한 CRUD 앱이 아닌, 왜 이 기능이 의미 있는지 납득이 됐다. 개발하는 내내 이 목적의식이 있었기 때문에 UI 결정을 팀원들과의 소통하는데 있어 하나하나에 더 신중해질 수 있었던 것 같다.

프로젝트 개요

기술 스택

백엔드는 따로 없다. json-server가 db.json을 읽어서 GET/POST/PATCH/DELETE REST API를 자동으로 제공해주는 구조다. 추후 백엔드 미니프로젝트에서 이 자리를 Spring Boot로 교체할 예정이다.

전체 데이터 흐름은 아래와 같다.

브라우저(React)
  │
  ├── GET/POST/PATCH/DELETE ──▶ json-server(localhost:3000) ──▶ db.json
  │
  └── POST + prompt ──────────▶ OpenAI GPT Image 2
                      ◀── b64_json 응답 ──────────────────────
                        ↓
              React 내부에서 b64_json → Data URL 변환
                        ↓
      PATCH books/:id(coverImageUrl) ──▶ json-server

내 역할

총 8명 팀이었고, 나는 전체적인 UI 개발을 담당했다. 구체적으로는:

• 프로토타입 UI 설계 및 구현 (전체 라우팅 구조)
• OpenAI LLM 호출 연결 코드 전체 설계 및 구현
• CSS 기본 틀 + 후에 만들어놓은 CSS를 받아 수정
• 팀원들이 개발한 코드를 직접 병합 (PR 없이 - main에 올려놓고 했어야지..)
• 1개 프롬프트 입력 → 3개 이미지 생성 처리 설계
• 검색바, 리스트 필터링, 정렬 디테일 관리
• json-server 예외처리 전반

구현 세부사항

1. 프로토타입 UI 설계 — 팀이 시작할 수 있는 기반 만들기

제일 먼저 한 건 팀이 개발을 시작할 수 있는 공통 기반을 만드는 것이었다. 각자가 맡은 파트를 개발하려면 라우팅 구조와 공통 레이아웃이 먼저 잡혀있어야 한다. 이 부분이 없으면 팀원들이 각자 만든 컴포넌트를 나중에 합칠 때 충돌이 훨씬 커진다.

App.jsx에 React Router 기반 라우팅을 잡았다.

function App() {
  return (
    <BrowserRouter>
      <Header />
      <Box component="main" sx={{ pt: "64px" }}>
        <Routes>
          <Route path="/"                       element={<Home />} />
          <Route path="/books"                  element={<BookListRoute />} />
          <Route path="/books/new"              element={<BookFormRoute />} />
          <Route path="/books/:id"              element={<BookDetailRoute />} />
          <Route path="/books/:id/edit"         element={<BookEditRoute />} />
          <Route path="/books/:id/cover-editor" element={<BookCoverEditor />} />
        </Routes>
      </Box>
    </BrowserRouter>
  )
}

각 Route 컴포넌트(BookListRoute, BookDetailRoute 등)는 useNavigate와 useParams를 내부에서 처리하고, 실제 페이지 컴포넌트에는 네비게이션 콜백만 prop으로 내려주는 구조로 설계했다.

// 라우팅 로직을 래퍼에서 처리 → 페이지 컴포넌트는 라우터 의존성 없음
function BookDetailRoute() {
  const navigate = useNavigate()
  const { id } = useParams()
  return (
    <BookDetail
      id={id}
      onBack={() => navigate('/books')}
      onEdit={() => navigate(`/books/${id}/edit`)}
      onEditCover={() => navigate(`/books/${id}/cover-editor`)}
      onDeleted={() => navigate('/books')}
    />
  )
}

이 패턴의 장점은 BookDetail 컴포넌트 자체가 react-router-dom에 의존하지 않는다는 것이다. 나중에 라우팅 구조가 바뀌어도 페이지 컴포넌트를 건드릴 필요가 없다.

MUI <Box component="main" sx={{ pt: "64px" }}> 로 고정 헤더(AppBar) 높이만큼 콘텐츠 영역을 밀어주는 방식도 여기서 잡았다. 이게 없으면 헤더 뒤에 첫 번째 콘텐츠가 숨어버린다.

2. 도서 목록 페이지 — 필터링과 정렬 설계

도서 목록에서 기대한 기능들은 생각보다 많았다.

• 장르별 사이드바 필터
• 즐겨찾기 탭
• 제목/저자 실시간 검색
• 등록순/제목순/가격순 정렬
• 그리드/리스트 뷰 전환

이 모든 걸 하나의 컴포넌트에서 처리해야 했다. 상태 설계부터 시작했다.

const [books, setBooks] = useState([])          // 전체 데이터 (서버에서 한 번만 fetch)
const [genre, setGenre] = useState('ALL')        // 장르 필터
const [query, setQuery] = useState('')           // 검색어
const [view, setView] = useState('grid')         // 뷰 모드
const [favoriteIds, setFavoriteIds] = useState(() => readFavoriteIds())  // 즐겨찾기
const [sortBy, setSortBy] = useState('register') // 정렬 기준

books는 최초 fetch 이후 서버 재요청 없이 클라이언트에서 모든 필터링/정렬을 처리한다. json-server가 쿼리 파라미터를 지원하긴 하지만, 검색어가 바뀔 때마다 API를 치는 건 비효율적이다. 전체를 한 번 받아서 useMemo로 파생 상태를 계산하는 방식이 더 낫다.

// 필터링: 장르 + 즐겨찾기 + 검색어
const filtered = useMemo(() => {
  const lowerQuery = query.toLowerCase()
  return books.filter((book) => {
    const genreOk =
      genre === 'ALL' ||
      (genre === 'FAVORITES'
        ? favoriteIds.has(String(book.id))
        : book.genre === genre)
    const queryOk =
      !query ||
      book.title?.toLowerCase().includes(lowerQuery) ||
      book.author?.toLowerCase().includes(lowerQuery)
    return genreOk && queryOk
  })
}, [books, genre, favoriteIds, query])

// 정렬: filtered 결과 위에서
const sorted = useMemo(() => {
  const arr = [...filtered]
  if (sortBy === 'title')
    return arr.sort((a, b) => a.title?.localeCompare(b.title || '', 'ko'))
  if (sortBy === 'price')
    return arr.sort((a, b) => (a.price || 0) - (b.price || 0))
  // 기본: 등록순 (최신 순)
  return arr.sort(
    (a, b) => toTime(b.createdAt) - toTime(a.createdAt) || Number(b.id) - Number(a.id)
  )
}, [filtered, sortBy])

filtered와 sorted를 useMemo 두 단계로 분리한 이유가 있다. 필터링은 books, genre, query에 의존하고, 정렬은 filtered, sortBy에만 의존한다. 한 덩어리로 합치면 sortBy만 바뀌어도 필터링 로직이 다시 실행된다. 분리하면 각각 필요한 시점에만 재계산된다.

즐겨찾기 탭 — localStorage 동기화 문제

즐겨찾기는 localStorage에 저장한다. 문제는 탭이 여러 개 열려있을 때 A탭에서 즐겨찾기를 추가하면 B탭에는 반영이 안 된다는 것이다.

useEffect(() => {
  const refresh = () => setFavoriteIds(readFavoriteIds())
  window.addEventListener('focus', refresh)       // 탭 포커스 복귀 시
  window.addEventListener('storage', refresh)     // 다른 탭에서 storage 변경 시
  window.addEventListener('bookFavoriteChange', refresh)  // 커스텀 이벤트
  return () => {
    window.removeEventListener('focus', refresh)
    window.removeEventListener('storage', refresh)
    window.removeEventListener('bookFavoriteChange', refresh)
  }
}, [])

세 가지 이벤트를 구독했다.

• focus : 다른 탭에서 돌아왔을 때 최신 상태로 갱신
• storage : 같은 브라우저 다른 탭에서 localStorage 변경 감지
• bookFavoriteChange : 같은 탭 내에서 즐겨찾기 토글 시 dispatchEvent로 알림

이 세 가지를 다 처리하지 않으면 어느 한 경우에서 즐겨찾기가 화면에 즉시 반영되지 않는 버그가 생긴다.

3. Main 페이지 — 검색바와 도서 랭킹 캐러셀

Main 페이지는 구조가 단순해 보이지만, 안에 들어있는 설계 결정들이 꽤 많다. SearchBar와 BookSection 두 컴포넌트로 구성됐고, 둘 다 내가 전담으로 만들었다.

SearchBar — 상태를 URL에 넘기는 이유

검색어를 입력하고 엔터를 누르면 도서 목록 페이지로 이동한다. 단순해 보이지만 구현 방식에서 한 번 고민했다.

const handleSearch = () => {
  if (query.trim()) {
    navigate(`/books?search=${encodeURIComponent(query)}`)
  }
}

검색어를 컴포넌트 상태로 넘기지 않고, URL 쿼리 파라미터로 넘긴다. 이렇게 하면 두 가지 이점이 있다.

첫째, 검색 결과 URL이 공유 가능해진다. /books?search=해리포터 를 그대로 누군가에게 주면 같은 결과를 볼 수 있다.

둘째, 도서 목록 페이지에서 useSearchParams로 읽으면 SearchBar가 어디 있든 상관없이 검색어를 받을 수 있다. 컴포넌트 간 props 연결이나 전역 상태가 필요 없다.

// BookListPage에서 URL 파라미터 수신
const [searchParams] = useSearchParams()
const [query, setQuery] = useState(searchParams.get('search') || '')

useEffect(() => {
  setQuery(searchParams.get('search') || '')
}, [searchParams])

Header에도 같은 검색바가 있는데, 거기서도 동일하게 URL로 넘기니까 도서 목록 페이지가 알아서 처리한다. encodeURIComponent로 한글 검색어가 URL에서 깨지지 않도록 처리한 것도 이 부분이다.

BookSection — 캐러셀과 탭 설계

도서 랭킹과 신작 탭을 제공하는 캐러셀 슬라이더다.

데이터는 이렇게 가공한다.

// 랭킹: 조회수 높은 순 최대 60권
const rankingBooks = [...data]
  .sort((a, b) => (b.viewCount || 0) - (a.viewCount || 0))
  .slice(0, 60)

// 신작: 최근 1개월 이내 출간, 최신 순
const now = new Date()
const oneMonthAgo = new Date()
oneMonthAgo.setMonth(now.getMonth() - 1)

const newBooks = [...data]
  .filter((book) => {
    if (!book.pubDate) return false
    const pubDate = new Date(book.pubDate)
    return pubDate >= oneMonthAgo && pubDate <= now
  })
  .sort((a, b) => new Date(b.pubDate) - new Date(a.pubDate))
  .slice(0, 60)

원본 배열을 건드리지 않도록 [...data] 스프레드로 복사한 뒤 정렬했다. 정렬은 원본을 변경하기 때문에 이걸 빠뜨리면 data가 조용히 바뀐다.

슬라이더는 CSS transform 방식으로 구현했다. 라이브러리 없이.

<div
  className={styles.cardList}
  style={{ transform: `translateX(calc(-${currentIndex} * (25% + 6px)))` }}
>
  {currentBooks.map((book) => (...))}
</div>

-${currentIndex} * (25% + 6px) — 카드 4개가 한 화면에 보이니 각 카드 너비가 25%고, 여기에 카드 간 gap(6px)을 더해서 정확히 한 칸씩 이동한다. 탭 전환 시 currentIndex를 0으로 리셋하는 것도 중요하다.

useEffect(() => {
  setCurrentIndex(0)
}, [activeTab])

이게 없으면 랭킹 탭에서 5번째 카드를 보다가 신작 탭으로 전환했을 때 신작이 5번째부터 시작한다. 사용자 입장에선 당황스러운 경험이다. 커버 이미지가 없는 책은 fallback으로 처리했다.

src={book.coverImageUrl || `https://picsum.photos/seed/${book.id}/200/300`}

picsum.photos에 seed로 책 id를 넘기면 항상 같은 책에 같은 랜덤 이미지가 나온다. AI 표지 생성 전까지 빈 박스 대신 그럴듯한 이미지를 보여줄 수 있어서 UI가 훨씬 자연스러워 보인다. 키보드 접근성도 챙겼다.

onKeyDown={(e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault()
    onBookClick?.(book)
  }
}}

마우스 없이 탭으로 이동해서 Enter/Space로 클릭할 수 있도록. 사소하지만 role="button" + tabIndex={0} + onKeyDown 세트가 없으면 키보드 사용자는 카드를 클릭할 수 없다.

4. Detail 페이지 — 가장 많은 설계 결정이 들어간 컴포넌트

BookDetail은 이번 프로젝트에서 코드량이 가장 많은 컴포넌트다(486줄). 그만큼 설계에서 고민한 것도 많았다.

인라인 스타일 선택 — CSS Module을 안 쓴 이유

다른 컴포넌트들은 CSS Module(.module.css)을 쓰는데, BookDetail은 인라인 스타일 객체를 썼다.

const s = {
  page: { minHeight: 'calc(100vh - 64px)', background: '#eeece6' },
  topbar: { background: '#fff', borderBottom: '0.5px solid rgba(0,0,0,0.12)', ... },
  hero: { background: '#fff', borderRadius: 14, display: 'grid', gridTemplateColumns: '260px minmax(0, 1fr)', ... },
  // ...
}

선택한 이유가 있다. 이 컴포넌트는 coverColor처럼 런타임에 동적으로 결정되는 스타일이 있다. 장르에 따라 표지 배경색이 달라진다.

// 함수형 스타일 — 인자에 따라 다른 스타일 반환
coverBox: (bg) => ({
  height: 360,
  background: bg,   // 장르별 색상이 런타임에 주입
  display: 'flex',
  ...
}),
favoriteBtn: (active) => ({
  background: active ? '#fff7e8' : '#fff',
  border: `0.5px solid ${active ? '#f59e0b' : 'rgba(0,0,0,0.18)'}`,
  color: active ? '#f59e0b' : '#9b9b95',
  ...
}),

CSS Module에서 이걸 하려면 클래스를 조건부로 바꾸거나 CSS 변수를 써야 한다. 인라인 스타일로 함수형으로 처리하면 상태에 따라 스타일이 직접 바뀐다는 게 코드에서 명확하게 보인다.

<div style={s.coverBox(coverColor.bg)}>
<button style={s.favoriteBtn(favorite)}>

coverColor는 useMemo로 계산한다.

const coverColor = useMemo(() => getCoverColor(book?.genre), [book?.genre])

book?.genre가 바뀔 때만 재계산된다. 옵셔널 체이닝(?.)으로 book이 null인 초기 로딩 상태에서도 에러 없이 처리된다.

조회수 업데이트 — 300ms 딜레이를 넣은 이유

상세 페이지에 들어오면 조회수가 1 증가한다. 구현이 생각보다 까다로웠다.

const res = await fetch(`${API}/${id}`)
const data = await res.json()
const currentViews = Number(data.viewCount || 0)
const nextViews = currentViews + 1

setBook(data)
setViews(nextViews)  // UI는 즉시 +1 반영

// 실제 PATCH는 300ms 후에
setTimeout(() => {
  fetch(`${API}/${id}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ viewCount: nextViews }),
  }).catch((e) => {
    console.warn('조회수 백그라운드 동기화 락 상태 우회 처리:', e)
  })
}, 300)

왜 바로 PATCH를 치지 않고 300ms를 기다리나?

json-server는 동시에 여러 요청이 들어오면 파일 락(lock)이 걸린다. GET 요청으로 데이터를 받아오는 것과 동시에 PATCH를 날리면 락 충돌이 생기는 경우가 있었다. 300ms를 기다렸다가 GET이 완전히 끝난 뒤 PATCH를 날리는 방식으로 이 문제를 우회했다.

UI는 setViews(nextViews)로 즉시 갱신해두니 사용자는 딜레이를 느끼지 못한다. 서버 동기화는 백그라운드에서 일어난다. 실패해도 console.warn으로 로그만 남기고 에러를 전파하지 않는다 — 조회수 업데이트 실패가 사용자 경험을 방해해선 안 된다고 판단했다.

삭제 확인 모달 — 브라우저 confirm을 안 쓴 이유

삭제 버튼을 누르면 브라우저 기본 confirm 대화상자 대신, 직접 만든 모달이 뜬다.

const [showDeleteModal, setShowDeleteModal] = useState(false)

{showDeleteModal && (
  <div style={s.overlay}>
    <div style={s.modal}>
      <div style={s.modalTitle}>도서를 삭제할까요?</div>
      <div style={s.modalDesc}>
        <strong>{book.title}</strong> 정보가 목록에서 삭제됩니다.
        <br />이 작업은 되돌릴 수 없습니다.
      </div>
      <div style={s.modalActions}>
        <button style={s.cancelBtn} onClick={() => setShowDeleteModal(false)}>취소</button>
        <button style={s.dangerBtn} onClick={handleDelete}>삭제하기</button>
      </div>
    </div>
  </div>
)}

window.confirm()은 브라우저마다 생김새가 다르고, 앱 스타일과 전혀 어울리지 않는다. 커스텀 모달을 쓰면 메시지에 책 제목을 강조(<strong>)해서 "어떤 책을 삭제하는지" 명확하게 보여줄 수 있다. 모달 overlay는 position: fixed, inset: 0으로 화면 전체를 덮고, z-index: 100으로 다른 요소 위에 올라간다.

즐겨찾기 — localStorage와 커스텀 이벤트 연동

즐겨찾기 상태는 localStorage에 저장하고, 변경 시 커스텀 이벤트를 발행한다.

useEffect(() => {
  localStorage.setItem(`bookFavorite:${id}`, String(favorite))
  window.dispatchEvent(new Event('bookFavoriteChange'))
}, [favorite, id])

dispatchEvent로 bookFavoriteChange 이벤트를 발행하면, 도서 목록 페이지에서 이 이벤트를 구독하고 있다가 즐겨찾기 탭을 즉시 갱신한다. BookDetail과 BookListPage가 직접 연결되지 않아도 이벤트를 통해 상태가 동기화된다.

메타 정보 그리드

출판사, 출판일, 가격, 페이지, ISBN, 조회수 6가지 메타 정보를 배열로 관리하고 map으로 렌더링한다.

const meta = [
  { icon: 'ti-building',      label: '출판사', value: book.publisher || '-' },
  { icon: 'ti-calendar',      label: '출판일', value: book.pubDate ? fmtDate(book.pubDate) : '-' },
  { icon: 'ti-currency-won',  label: '가격',   value: formatWon(book.price) },
  { icon: 'ti-book-2',        label: '페이지', value: book.pages ? `${book.pages.toLocaleString()}쪽` : '-' },
  { icon: 'ti-barcode',       label: 'ISBN',   value: book.isbn || '-' },
  { icon: 'ti-eye',           label: '조회수', value: `${views.toLocaleString()}회` },
]

하드코딩으로 6개 블록을 나열하는 것보다 이 방식이 나중에 항목을 추가/제거하기 훨씬 편하다. formatWon으로 가격에 원화 포맷을 적용하고, 값이 없으면 전부 -로 fallback 처리했다.

5. BookCoverEditor — 이번 프로젝트에서 내가 가장 공들인 컴포넌트

AI 표지 생성 에디터다. 사용자가 스타일 옵션을 태그로 고르고, 자유 프롬프트를 입력하면 표지 후보 3장이 나온다. 마음에 드는 걸 선택해서 저장하는 흐름이다.

상태 설계

const [dbBookInfo, setDbBookInfo] = useState({
  title: '', author: '', originalContent: '',
})
const [userPrompt, setUserPrompt] = useState('')
const [selectedOptions, setSelectedOptions] = useState({
  style: 'miki', background: 'beige', lighting: 'daylight', typography: 'serif',
})
const [apiConfig, setApiConfig] = useState({
  model: 'gpt-image-2', quality: 'Medium',
})
const [generatedImages, setGeneratedImages] = useState([null, null, null])
const [isGenerating, setIsGenerating] = useState(false)
const [selectedImageIndex, setSelectedImageIndex] = useState(null)

generatedImages를 [null, null, null]로 초기화한 게 포인트다. 슬롯이 항상 3개 존재하고, 생성 전에는 null, 생성 중에는 로딩 스피너, 완료 후에는 이미지를 보여주는 방식이다. 배열 인덱스로 슬롯을 관리하니 UI에서 3개를 일관되게 렌더링하기 쉬웠다.

{[0, 1, 2].map((index) => (
  <div
    key={index}
    className={`${styles.imageSlot} ${selectedImageIndex === index ? styles.activeSlot : ''}`}
    onClick={() => generatedImages[index] && setSelectedImageIndex(index)}
  >
    {isGenerating ? (
      <div className={styles.loadingSpinner}>생성 중...</div>
    ) : generatedImages[index] ? (
      <img src={generatedImages[index]} alt={`표지 후보 ${index + 1}`} />
    ) : (
      <span className={styles.slotText}>Preview {index + 1}</span>
    )}
  </div>
))}

isGenerating 하나로 3개 슬롯을 동시에 제어한다. 생성 버튼을 누르는 순간 setGeneratedImages([null, null, null])로 초기화하고 setIsGenerating(true)로 전환해서 모든 슬롯이 동시에 로딩 상태로 바뀐다.

모델 선택과 퀄리티 제약

모델은 3가지를 지원하도록 만들었다.

const handleModelChange = (modelName) => {
  setApiConfig({
    model: modelName,
    quality: modelName === 'dall-e-3' ? 'High' : prev.quality
  })
}

DALL-E 3는 퀄리티 옵션이 High만 지원한다. 모델 변경 시 자동으로 강제 설정하고, 퀄리티 선택 UI에서도 Low/Medium을 누르면 경고 알림이 뜨도록 처리했다.

onClick={() => {
  if (apiConfig.model === 'dall-e-3' && qualityLevel !== 'High') {
    alert('DALL-E 3 모델은 High 퀄리티만 선택 가능합니다.')
    return
  }
  setApiConfig({ ...apiConfig, quality: qualityLevel })
}}

사소해 보이지만, 이런 제약 처리가 없으면 사용자가 DALL-E 3 + Low 조합을 선택한 채로 API를 쏘고 400 에러를 마주친다. 실제로 처음엔 빠뜨렸다가 테스트 중에 터졌다.

6. OpenAI API 연동 — 기본 흐름 이해

API 호출 자체는 간단하다.

export async function generateBookCover(apiKey, prompt) {
  if (!apiKey) throw new Error('API Key가 없습니다.')

  const response = await fetch('https://api.openai.com/v1/images/generations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey.trim()}`
    },
    body: JSON.stringify({
      model: 'gpt-image-2',
      prompt: prompt,
      size: '1024x1536',  // 세로형 책 표지 비율
      output_format: 'png',
      n: 1
    })
  })

  if (!response.ok) {
    throw new Error(`OpenAI 요청 실패 (Status: ${response.status})`)
  }

  const data = await response.json()
  const b64Json = data.data?.[0]?.b64_json

  if (!b64Json) throw new Error('이미지 데이터를 찾지 못했습니다.')

  return `data:image/png;base64,${b64Json}`
}

OpenAI가 응답으로 주는 건 base64 인코딩된 PNG 문자열(b64_json)이다. 이걸 data:image/png;base64,... 형태의 Data URL로 변환하면 <img src>에 바로 쓸 수 있다.

data.data?.[0]?.b64_json 이 옵셔널 체이닝이 없으면 응답 구조가 조금이라도 달라질 때 앱 전체가 크래시된다. 실제로 처음에 빠뜨렸다가 에러를 마주쳤다. 외부 API 응답은 항상 방어적으로 접근하는 게 맞다.

7. 1 프롬프트 → 3 이미지 — 핵심 설계 고민

미션 명세는 "AI 표지 생성 버튼 클릭 → 이미지 1개 생성"이었다. 그런데 내가 생각하기엔 표지 하나만 나오면 사용자가 선택권이 없다. 같은 도서 내용으로 스타일이 다른 3가지 샘플을 동시에 보여줘야 실제로 유용하다고 판단했다.

gpt-image-2는 n: 3 파라미터를 지원하지 않는다. n: 1만 된다. 그래서 요청을 3번 병렬로 보내는 방식으로 처리했다.

const handleGenerate = async () => {
  // ...유효성 검사...

  setIsGenerating(true)
  setSelectedImageIndex(null)
  setGeneratedImages([null, null, null])  // 슬롯 초기화

  // 도서 정보 + 사용자 자유 프롬프트를 합쳐서 subject 구성
  const combinedInfo = {
    title: dbBookInfo.title,
    author: dbBookInfo.author,
    content: `[Book Story]: ${dbBookInfo.originalContent} / [User Design Request]: ${userPrompt}`
  }

  const finalPrompt = buildStructuredPrompt(combinedInfo, selectedOptions)

  // 3개 동시 요청
  const generatePromises = [
    generateBookCover(apiKey, finalPrompt),
    generateBookCover(apiKey, finalPrompt),
    generateBookCover(apiKey, finalPrompt),
  ]

  const newImages = await Promise.all(generatePromises)
  setGeneratedImages(newImages)
}

Promise.all을 쓰면 3개 요청이 동시에 날아가서 순차 요청(3배 시간)보다 훨씬 빠르게 결과를 받을 수 있다. 사용자는 3개 이미지를 나란히 보고 마음에 드는 걸 선택해서 저장한다.

한 가지 추가로 고민한 부분은 content 조합 방식이다.

content: `[Book Story]: ${dbBookInfo.originalContent} / [User Design Request]: ${userPrompt}`

db에 저장된 도서 내용과 사용자가 직접 입력한 프롬프트를 분리해서 합쳤다. 그냥 이어 붙이면 모델이 어느 게 더 중요한 지시인지 헷갈릴 수 있다. 레이블을 붙여서 두 정보의 성격이 다름을 명시적으로 알렸더니 결과물이 더 의도에 가깝게 나왔다.

8. 프롬프트 엔지니어링 — 단순 텍스트 전달은 쓰레기를 만든다

이 부분이 이번 프로젝트에서 가장 실험이 많았던 부분이다. 처음에는 이렇게 프롬프트를 구성하려고 혼자 생각했었다. (따로 프로젝트 진행중 테스트 진행)

"A book cover for a book titled '별빛 아래의 서점'. 
Content: 작은 마을 서점의 1년을 담은 에세이."

결과가 처참했다. 글자가 이상하게 들어가거나, 내가 원하는 느낌에 책 표지 이미지가 나왔다. 여러 번 재생성해도 품질이 들쑥날쑥했다. GPT Image 2 모델이 "텍스트 렌더링 성능이 개선됐다"고 하지만, 그냥 자연어로 넘기면 모델이 어디에 집중해야 할지 헤맨다는 걸 체감했다. 그렇기에 OPENAI를 사용한 이미지 만드는 깃허브를 참고해 조원에 태정님이 프롬프트를 구조화해서 모델에게 명확한 지시를 줄 수 있는 6섹션 구조를 만들었다.

[STYLE]
Oil Painting Classic (visible heavy brushstrokes, rich impasto texture,
deep color palette, classic chiaroscuro lighting, canvas texture)

[SUBJECT]
A professional book cover design.
Main theme concept: [Book Story]: 작은 마을 서점의 1년을 담은 에세이 / 
[User Design Request]: 따뜻하고 고요한 느낌으로.
Title: "별빛 아래의 서점". Author: "홍길동".

[BACKGROUND]
Lush Nature background (soft-focus forest with dappled sunlight, natural textures)

[LIGHTING]
Warm Golden Hour (rich golden tones, long soft shadows, warm highlights)

[TYPOGRAPHY]
Serif Classic Typography layout
(book title written in elegant Serif typeface at top-center in large letters)

[TECHNICAL]
85mm portrait lens at f/1.8, razor-sharp focus, cinematic background bokeh.

[NEGATIVE]
low quality, blurry, distorted text, garbled letters, misspelled text, watermark.

각 섹션이 하는 역할이 다르다.

• [STYLE] — 전체적인 화풍, 렌더링 방식
• [SUBJECT] — 표지의 주제, 도서 정보
• [BACKGROUND] — 배경 분위기
• [LIGHTING] — 조명 설정
• [TYPOGRAPHY] — 제목 텍스트 처리 방식
• [TECHNICAL] — 사진 품질 관련 고정값 (렌즈/포커스/보케)
• [NEGATIVE] — 제거할 요소 명시

[NEGATIVE] 섹션이 생각보다 중요했다. 이걸 추가하고 나서 글자 깨짐이나 워터마크 같은 품질 문제가 눈에 띄게 줄었다. 각 옵션에는 영어 프롬프트 프리셋이 연결돼 있고, 사용자는 한국어 태그만 선택하면 된다.

export const STYLE_PRESETS = {
  '수채화':    'Line Art (clean lines, delicate watercolor bleeding effects, minimalist aesthetic...)',
  '3D애니메이션': '3D Animated style (vibrant colors, expressive characters, soft volumetric lighting...)',
  '유화':      'Oil Painting Classic (visible heavy brushstrokes, rich impasto texture...)',
  '미니멀리즘': 'Modern Minimalism (bold geometric shapes, flat design elements, high contrast...)',
  '빈티지':    'vintage pulp fiction (gritty textures, bold halftone patterns, dramatic chiaroscuro...)',
  '일러스트':  'Warm Anime Illustration style (soft pastel colors, whimsical character design...)',
}

이렇게 태그→영어 프리셋으로 매핑하는 방식을 택한 이유는 두 가지다. 첫째, 사용자에게 복잡한 영어 프롬프트를 직접 입력하게 하면 진입 장벽이 너무 높다. 둘째, 검증된 프리셋을 쓰면 결과물 품질이 더 일관적이다. 자유 프롬프트는 [User Design Request]에 입력을 받도록 설계해 사용자가 원하는 이미지를 만들 수 있게 했다.

9. 이미지 압축 — 예상 못했던 병목

Data URL은 생각보다 훨씬 크다. 실제로 OpenAI에서 받은 원본 Data URL 하나가 1~2MB 가까이 됐다. 이걸 그대로 json-server에 PATCH로 저장하면 db.json 파일이 순식간에 수십 MB가 된다. 로딩이 느려지고 심하면 json-server가 불안정해진다. 그래서 Canvas API를 활용한 이미지 압축 함수를 직접 만들었다.

export async function compressImageDataUrl(dataUrl, maxBytes = 75000) {
  if (!dataUrl?.startsWith('data:image/')) return dataUrl || ''
  if (dataUrl.length <= maxBytes) return dataUrl  // 이미 충분히 작으면 패스

  const image = await new Promise((resolve, reject) => {
    const img = new Image()
    img.onload = () => resolve(img)
    img.onerror = () => reject(new Error('이미지를 압축할 수 없습니다.'))
    img.src = dataUrl
  })

  const canvas = document.createElement('canvas')
  const ctx = canvas.getContext('2d')
  const aspect = image.height / image.width || 1.5  // 비율 유지

  const widths = [360, 320, 280, 240, 200, 180]
  const qualities = [0.72, 0.62, 0.52, 0.42, 0.34]

  for (const width of widths) {
    canvas.width = width
    canvas.height = Math.round(width * aspect)
    ctx.clearRect(0, 0, canvas.width, canvas.height)
    ctx.drawImage(image, 0, 0, canvas.width, canvas.height)

    for (const quality of qualities) {
      const compressed = canvas.toDataURL('image/jpeg', quality)
      if (compressed.length <= maxBytes) return compressed
    }
  }

  return canvas.toDataURL('image/jpeg', 0.28)  // 최후 수단
}

핵심 로직은 이렇다.

1. 이미 목표 크기(75KB) 이하면 바로 반환
2. Canvas로 이미지 그리기 → toDataURL('image/jpeg', quality)로 압축
3. 너비 360px부터 180px까지 단계적으로 줄이면서, 각 너비에서 품질도 0.72부터 0.34까지 낮춤
4. 목표 크기 이하가 되는 첫 조합을 반환
5. 모두 실패하면 quality: 0.28로 강제 반환

PNG(원본) → JPEG(압축)로 포맷도 바뀐다. 표지 미리보기용으로는 충분한 품질이 나왔고, 저장 용량은 원본 대비 95% 이상 줄었다. aspect ratio를 image.height / image.width || 1.5 로 계산하는 이유도 있다. 이미지 로딩이 실패하거나 width가 0인 경우 나누기 0이 되는데, || 1.5로 fallback해서 책 표지 기본 비율(세로형)을 유지하도록 했다.

10. 예외처리 — 사용자에게 무슨 일이 일어났는지 알려줘야 한다

OpenAI API를 다루면서 예외처리가 생각보다 많이 필요하다는 걸 깨달았다. 처리하지 않으면 화면이 그냥 멈추거나 흰 화면이 뜬다. 사용자 입장에서 가장 당황스러운 경험이다.

API Key 관련

if (!apiKey) throw new Error('API Key가 없습니다.')
// → .env 파일에 VITE_OPENAI_API_KEY 설정 필요 안내

HTTP 응답 실패

if (!response.ok) {
  throw new Error(`OpenAI 요청 실패 (Status: ${response.status})`)
  // 401 → API Key 오류
  // 429 → Rate Limit 초과
  // 500 → OpenAI 서버 오류
}

응답 데이터 누락

const b64Json = data.data?.[0]?.b64_json
if (!b64Json) throw new Error('이미지 데이터를 찾지 못했습니다.')

이미지 압축 실패

img.onerror = () => reject(new Error('이미지를 압축할 수 없습니다.'))
// → 압축 실패 시 원본 반환으로 fallback

저장 실패

if (response.ok) {
  alert('표지가 성공적으로 수정되었습니다!')
  navigate(-1)
} else {
  throw new Error('저장 실패')
}

try-catch 안에서 에러를 잡고 alert로 사용자에게 알리는 방식이다. 실제 서비스라면 toast 알림이나 에러 상태 UI로 더 세련되게 처리하겠지만, 프로젝트 범위 안에서는 이 정도로 충분하다고 판단했다.

11. 코드 병합 — 가장 힘든 작업이었다

팀에서 PR을 제대로 진행하지 못했다. 각자 로컬에서 개발한 코드를 파일로 공유하는 방식이었는데, 이걸 내가 직접 하나씩 합쳤다. (처음 개발 진행시 틀을 잡지 못하고 시작하게 크다.. 나의 잘못이라고 생각한다.) 병합하면서 실제로 마주친 문제들:

• 변수명 충돌 한 쪽은 book, 다른 쪽은 bookData, 또 다른 쪽은 currentBook. 어느 게 맞는지 기준이 없어서 일일이 읽어가며 통일했다.
• 상태 관리 불일치 A는 useState로 직접 관리, B는 props로 내려받는 구조가 혼용됐다. 데이터 흐름이 섞이면 어디서 상태를 갱신해야 하는지 판단하기 어렵다.
• API 호출 방식 혼재 fetch를 컴포넌트 안에서 직접 쓴 곳, 별도 함수로 분리한 곳이 섞였다. 에러 처리 방식도 다 달랐다.
• CSS 클래스 중복 같은 클래스명인데 스타일이 다른 경우가 있었다. CSS Module을 쓴 곳과 일반 클래스를 쓴 곳이 혼재했다.

이걸 하나하나 읽으면서 충돌 없이 합치고, 라우팅 흐름이 끊기지 않는지 확인하면서 전체 앱이 돌아가게 만드는 과정이 생각보다 훨씬 오래 걸렸다. 검색바 동작 방식(useMemo + 클라이언트 사이드 필터링), 리스트 카드 클릭 → 상세 전환 흐름, 등록/수정 폼의 상태 초기화 타이밍 같은 디테일도 이 과정에서 직접 정리했다.

생각정리

이번 04miniproject를 진행하며 어려웠던 점, 느낀점, 다음계획(프로젝트가 끝난후 따로 진행하고 있다)에 대해 정리해보자구..

어려웠던 점

b64_json이란?

OpenAI 응답에서 이미지가 URL이 아니라 base64 문자열로 온다는건 알았지만 dn.json에서는 큰 용량을 처리하는데에 한계가 있었다. 응답 JSON을 콘솔에 찍어봤더니 data[0].b64_json 에 엄청 긴 문자열이 들어있었다. db.json 서버를 사용할떄는 data:image/png;base64,...로 변환해야 <img src>에 쓸 수 있다는 것도 직접 해보고 나서야 자연스럽게 이해됐다.

Promise.all에서 하나가 Rate Limit에 걸리면?

3개 이미지 동시 생성에서 Promise.all을 쓰면 하나라도 실패하면 전체가 reject된다. Rate Limit(429)이 걸릴 때 이 문제가 생겼다. 3개 요청 중 1개만 실패해도 나머지 2개 결과가 다 날아간다. 나중에 Promise.allSettled로 바꿔서 실패한 것만 null 처리하는 방식을 검토했다. 이렇게 하면 2개는 성공, 1개는 null 슬롯으로 보여줄 수 있다.

이미지가 json-server에 저장은 됐는데 목록에 안 보임

PATCH 요청이 성공했는데 도서 목록으로 돌아오면 표지가 안 나왔다. 원인은 books 상태가 최초 fetch 이후 갱신이 안 된 것이었다. navigate(-1) 로 뒤로 가면 컴포넌트가 언마운트/리마운트되는데, 이때 useEffect의 fetch가 다시 실행돼야 한다. 의존성 배열을 확인하고 재fetch 트리거를 명시적으로 추가해서 해결했다.

Data URL이 너무 커서 json-server가 느려짐

앞서 언급한 이미지 압축 문제다. 처음엔 원본 Data URL을 그대로 저장했더니 db.json이 수십 MB가 됐고, json-server의 응답 속도가 눈에 띄게 느려졌다. 압축 함수를 만들고 나서 해결됐다.

느낀 점

UI 개발은 그리는 게 아니라 설계하는 것이다

이번 전까지 UI 개발은 "화면을 예쁘게 만드는 것"이라고 생각했다. 실제로 해보니 완전히 달랐다. 라우팅 설계, 컴포넌트 인터페이스 정의, 상태 흐름 설계, API 연동, 예외처리, 사용자 피드백 처리까지 전부 UI 개발의 영역이었다. 화면을 만드는 건 그 중 일부일 뿐이다. 가장 먼저 해야 할 것이 "어떻게 생겼는가"가 아니라 "데이터가 어떻게 흐르는가"라는 걸 이번에 확실히 배웠다.

"1 프롬프트 → 3 이미지"는 기술 문제가 아니라 UX 문제였다

교안에서 요구한 건 이미지 1개였다. 그걸 3개로 늘린 건 기술적 도전이 아니라 "사용자가 실제로 이걸 어떻게 쓸까" 를 생각한 우리조의 토론 결과였다. 표지를 딱 하나만 주면 선택의 여지가 없다. 마음에 안 들면 재생성 버튼을 계속 누르게 된다. 처음부터 3가지를 주면 그 중 하나는 마음에 들 가능성이 높다. API 비용은 3배 들지만 사용자 경험은 훨씬 낫다. 기능 구현보다 사용 맥락을 먼저 생각하는 습관이 이번에 좀 생긴 것 같다.

프롬프트 엔지니어링은 확실히 기술이다

"좋은 표지 그려줘" 와 [STYLE] Oil Painting Classic... [NEGATIVE] low quality, blurry... 는 결과물이 완전히 다르다. 언어를 구조화해서 모델이 집중할 지점을 명확하게 만드는 것, 제거할 요소를 NEGATIVE로 명시하는 것 — 이게 다 기술이다. 이전 프로젝트들에서 Multi-Agent나 LangGraph를 다뤘을 때도 프롬프트가 중요했지만, 이미지 생성에서는 그 차이가 훨씬 직관적으로 느껴졌다.

협업은 처음부터 규칙이 있어야 한다

이번 프로젝트에서 제일 힘든 작업이 코드 병합이었다. 사람마다 코딩 스타일이 다르고 변수명도 다르다. PR도 없이 파일로 코드를 주고받으면 충돌이 생길 수밖에 없다. 다음에는 처음부터 브랜치 전략, PR 규칙, 컨벤션(변수명, 컴포넌트 구조) 을 팀 안에서 먼저 합의하고 시작해야겠다. 이걸 나중에 맞추려고 하면 이미 늦다는 걸 뼈저리게 느꼈다. 아이러니하게도, 병합 작업 덕분에 팀 전체 코드를 가장 잘 아는 사람이 됐다. 모든 파일을 다 읽었으니까. 나쁘지 않은걸까..?

다음 목표 (후에 Spring도 연결 예정이니)

• Git 협업 플로우 제대로 경험하기 — 브랜치 전략, PR, 코드 리뷰
• React 상태 관리 깊이 파기 — React Query로 서버 상태와 클라이언트 상태 분리
• 실제 백엔드 연결 — json-server → Spring Boot 교체 (백엔드 미니프로젝트 예정)
• Promise.allSettled 패턴 — 일부 실패해도 나머지 결과는 보여주기

3일이라는 짧은 기간 동안 진행한 프로젝트였기에, 더 많은 시간을 투자했다면 더욱 완성도 높은 결과물을 만들 수 있었을 것이다. 하지만 제한된 시간 속에서도 모든 조원이 각자의 역할에 최선을 다해 주었기에 의미 있는 결과물을 만들어낼 수 있었다고 생각한다. 이번 프로젝트는 단순히 결과물을 완성하는 것에서 끝나지 않고, 프로젝트가 끝난 이후에도 더 공부하고 배워야 할 점들과 부족했던 부분을 채울 수 있는 프로젝트였다. 9주차 프로젝트를 마무리한다.

12조 파이팅!

목차

• 들어가며
• 1. VS Code 세팅부터 HTML/CSS 뼈대 잡기
  • Semantic Tag를 활용한 문서 구조화
  • CSS Flexbox로 유연하고 깔끔한 레이아웃 구성
• 2. JavaScript / React 컴포넌트 설계
  • JavaScript 심화: 배열 내장 함수
• 3. React 입문 및 컴포넌트(Component) 분리
  • Vite React 프로젝트 생성
  • Props를 통한 단방향 데이터 흐름 제어
• 4. React State 관리와 CRUD 구현
  • useState와 이벤트 핸들링
  • 폼(Form) 제어와 조건부 렌더링
  • 불변성을 유지하는 Create / Delete 로직 구현
• 5. 비동기 처리와 API 연동
  • useEffect와 컴포넌트 생명주기 제어
  • Axios를 활용한 REST API 연동 (비동기 처리)
• 6. 생각정리

Raact 학습_ko

VS Code 세팅부터 HTML/CSS 뼈대 잡기

4일간의 프론트엔드 강의를 진행했다. 1일차에 목표는 React를 활용한 동적인 SPA(Single Page Application)를 구축하는것이다.

Semantic Tag를 활용한 문서 구조화

본격적으로 게시판을 제작하며 가장 강조된 부분은 어떻게 하면 문서의 구조를 의미론적으로 명확하게 짤 수 있을까? 였다. 단순히 화면의 구역을 나누기 위해 무의미한 <div> 태그만을 남발하지 않고, 철저하게 Semantic Tag를 활용에 대해 학습했다. 시맨틱 태그를 사용하면 검색 엔진 최적화에 유리하다.

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8">
  <title>미니 게시판 프로젝트</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <header class="board-header">
    <h1>미니 게시판</h1>
    <nav>
      <button class="btn-create">새 글 작성</button>
    </nav>
  </header>

  <main class="board-container">
    <section class="post-list-section">

      <article class="post-item">
        <h2 class="post-title">프론트엔드 회고입니다.</h2>
        <div class="post-meta">
          <span class="author">작성자: 김경민</span>
          <span class="date">2026-05-15</span>
        </div>
      </article>

      <article class="post-item">
        <h2 class="post-title">시맨틱 태그와 VS Code 세팅</h2>
        <div class="post-meta">
          <span class="author">작성자: 이순신</span>
          <span class="date">2026-05-15</span>
        </div>
      </article>

    </section>
  </main>
</body>
</html> 

이렇게 명확하게 나누어진 구조는 당장 코드를 읽기 편하게 해줄 뿐만 아니라, React를 학습할 때 header 영역은 Header 컴포넌트로, article영역은 PostItem 컴포넌트로 분리하는데 도움이 된다.

CSS Flexbox로 유연하고 깔끔한 레이아웃 구성

간단하게 CSS를 통해 시각적인 레이아웃을 잡았다. 게시판 UI를 화면에 보기 좋게 배치하기 익힌 기술은 CSS Flexbox였다. 요소들을 가로로 배치하기 위해 복잡하게 위치를 계산하거나 화면이 깨지는 현상을 걱정할 필요 없이, Flexbox를 사용하면 1차원(가로 또는 세로) 레이아웃을 매우 직관적으로 제어할 수 있다. VS Code의 화면을 반으로 분할하여 왼쪽에는 HTML을, 오른쪽에는 CSS를 띄워두고 게시판의 디자인을 입혀나갔다. 부모 컨테이너에 display: flex를 선언하고, 주축(Main Axis)과 교차축(Cross Axis)을 정렬하는 코드를 작성했다.

* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

.board-header {
  display: flex;
  justify-content: space-between; 
  align-items: center; 
  padding: 20px 40px;
  background-color: #2c3e50;
  color: white;
}

.board-container {
  display: flex;
  flex-direction: column; /* 세로 방향으로 자식 요소 배치 */
  gap: 20px; /* 요소들 사이의 일정한 간격 유지 */
  padding: 40px;
  max-width: 800px;
  margin: 0 auto; /* 화면 중앙 정렬 */
}

.post-item {
  display: flex;
  flex-direction: column;
  gap: 10px;
  padding: 20px;
  background-color: #f8f9fa;
  border: 1px solid #dee2e6;
  border-radius: 8px;
}

.post-meta {
  display: flex;
  justify-content: flex-start;
  gap: 15px;
  font-size: 0.9rem;
  color: #6c757d;
}

특히 justify-content: space-between을 통해 헤더의 제목과 버튼을 손쉽게 양 끝으로 밀어내고, gap 속성을 사용해 margin 겹침 현상에 대한 고민 없이 요소 간의 여백을 일정하게 주입하는 과정이 편리했다. 브라우저 창 크기를 이리저리 줄였다 늘여도 레이아웃이 유연하게 변경되는 Flexbox를 잘 이용하자

JavaScript / React 컴포넌트 설계

만들어놓은 HTML/CSS에 웹 페이지에 데이터를 다루고 사용자와 상호작용하는 Modern JavaScript의 핵심 문법을 배우고 React를 학습했다.

JavaScript - 배열 내장 함수 (map, filter, reduce)

게시판 프로젝트를 진행하면서 가장 많이 다루게 될 데이터 형태는 결국 '게시글 객체들이 담긴 배열(Array)'이다. 서버로부터 여러 개의 게시글 데이터를 받아와 화면에 뿌려주고, 특정 글을 삭제하거나 검색해야 하기 때문이다. 이를 위해 기존의 지루한 for 루프를 벗어나, ES6+의 강력한 배열 내장 함수들을 학습했다.

불변성을 지키면서 원본 배열을 훼손하지 않고 새로운 배열을 반환하는 이 함수들은 추후 React의 상태 관리 로직에서 핵심적인 역할을 한다.

• map(): 배열의 모든 요소를 순회하며 내가 원하는 형태(주로 HTML/JSX UI 요소)로 가공하여 새로운 배열을 만들어낸다. 게시글 목록을 렌더링할 때 필수적이다.
• filter(): 조건에 맞는 요소들만 걸러내어 새로운 배열을 만든다. 게시글 삭제 기능이나 검색 기능을 구현할 때 주로 사용된다.
• reduce(): 배열의 모든 값을 하나로 누적하여 병합한다. 총 게시글 수 계산이나 복잡한 데이터 포맷팅에 유용하다.

const posts = [
  { id: 1, title: '프론트엔드 1일차 회고', author: '김경민' },
  { id: 2, title: 'React 너무 재밌네요', author: '김민' },
  { id: 3, title: 'JavaScript 배열 함수 정리', author: '경민' }
];

const postTitles = posts.map(post => `제목: ${post.title}`);
console.log(postTitles); 
// ["제목: 프론트엔드 1일차 회고", "제목: React 너무 재밌네요", "제목: JavaScript 배열 함수 정리"]

const filteredPosts = posts.filter(post => post.id !== 2);
console.log(filteredPosts); // id가 1, 3인 객체만 남은 새 배열 반환

출처/참고 https://developer.mozilla.org/ko/docs/Web/JavaScript/Reference/Global_Objects/Array https://adjh54.tistory.com/66

React 입문 및 컴포넌트(Component) 분리

들어가기전 VS Code 터미널에서 create-react-app 또는 Vite를 통해 기본 React 환경을 세팅하고 갑시다.

Vite React 프로젝트 생성

전체 명령어

npm create vite@latest
cd my-app
npm install
npm run dev

실행 결과

React의 가장 큰 장점 중 하나는 위에서 만들었던 '통짜 HTML' 문서를 레고 블록과 같은 Component 단위로 잘게 쪼개어 재사용할 수 있다는 것이다. 유지보수의 효율성을 극대화하기 위해, 나는 게시판 UI를 크게 Header, PostList(게시글 목록), PostItem(개별 게시글)이라는 독립적인 함수형 컴포넌트로 분리했다. 이렇게 컴포넌트를 분리하면 각 파일이 맡은 역할이 명확해져 코드를 읽고 수정하기가 훨씬 수월해진다.

Props를 통한 단방향 데이터 흐름 제어

컴포넌트를 여러 개로 분리하고 나면 필연적으로 "데이터를 어떻게 주고받을 것인가?"라는 문제에 부딪힌다. React는 부모 컴포넌트에서 자식 컴포넌트로만 데이터가 흐르는 단방향 데이터 바인딩 원칙을 가진다. 이때 전달되는 데이터의 매개체가 바로 Props다. 앞서 배운 map() 함수와 React의 Props 개념을 결합하여, 최상위 컴포넌트(App.js)가 가진 배열 데이터를 하위 컴포넌트(PostItem)까지 안전하게 전달하여 화면에 그리는 로직을 구현했다.

// 1. 개별 게시글을 담당하는 자식 컴포넌트 (PostItem.jsx)
// 부모로부터 post 객체를 Props로 전달받아 화면에 렌더링한다.
const PostItem = ({ post }) => {
  return (
    <article className="post-item">
      <h2 className="post-title">{post.title}</h2>
      <div className="post-meta">
        <span className="author">작성자: {post.author}</span>
      </div>
    </article>
  );
};

export default PostItem;


// 2. 게시글 목록을 렌더링하는 부모 컴포넌트 (PostList.jsx)
// 서버에서 받아왔다고 가정한 데이터 배열을 map으로 순회하며 자식에게 Props로 넘겨준다.
import PostItem from './PostItem';

const PostList = () => {
  const dummyData = [
    { id: 1, title: '프론트엔드 1일차 회고', author: '김경민' },
    { id: 2, title: 'React 입문기', author: '김민' }
  ];

  return (
    <section className="post-list-section">
      {/* 배열의 map 함수를 이용해 컴포넌트를 반복 생성 */}
      {dummyData.map((post) => (
        // 컴포넌트 반복 시 고유한 key 값을 반드시 부여해야 함
        <PostItem key={post.id} post={post} /> 
      ))}
    </section>
  );
};

export default PostList;

출처/참고 https://yhuj79.github.io/Vue/241230/ https://dkkim2318.tistory.com/161

React State 관리와 CRUD 구현

단순히 정해진 데이터를 보여주는 것이 아닌, 사용자가 직접 글을 작성하고 삭제할 수 있는 동적인 CRUD(Create, Read, Update, Delete) 게시판을 프론트엔드 단에서 완벽하게 제어하는 실습을 가졌다.

useState와 이벤트 핸들링

React에서 가장 중요하고 혁신적인 개념을 꼽으라면 State 관리일 것이다. 일반적인 JavaScript 변수는 값이 바뀌어도 화면이 스스로 업데이트되지 않지만, React의 useState Hook을 통해 생성된 상태는 값이 변경될 때마다 컴포넌트를 자동으로 다시 렌더링하게 만든다. 사용자가 입력창에 글씨를 타이핑하거나 버튼을 클릭하는 등의 행동을 Event라고 한다. 나는 onChange와 onClick 같은 이벤트 핸들러를 통해 사용자의 동작을 감지하고, 그 결과를 useState의 상태 변경 함수(setState)에 전달하여 화면이 즉각적으로 갱신되도록 로직을 짰다.

폼(Form) 제어와 조건부 렌더링

게시판의 핵심인 '글 작성' 기능을 만들기 위해 입력 폼을 제어하는 방법을 익혔다. React에서는 사용자의 입력값을 DOM 자체에 맡겨두는 것이 아니라, React의 State를 '신뢰 가능한 단일 출처'로 삼는 제어 컴포넌 패턴을 권장한다.

입력 필드의 value 속성을 State와 연결하여 폼을 완벽하게 제어했고, 사용자가 빈 값을 제출하려 할 때 제출을 막고 경고창을 띄우는 간단한 유효성 검사도 추가했다. 또한, 상태 값에 따라 화면의 UI가 다르게 보이도록 하는 조건부 렌더링 개념도 도입했다. 예를 들어, 게시글 배열의 길이가 0일 때는 "작성된 게시글이 없습니다"라는 안내 문구를 보여주고, 게시글이 존재할 때만 목록 컴포넌트를 렌더링하도록 삼항 연산자를 적극 활용했다.

불변성을 유지하는 Create / Delete 로직 구현

가장 많은 고민을 했던 부분은 상태로 관리되는 배열에 새로운 데이터를 추가하고 삭제하는 로직이었다. React에서는 상태를 변경할 때 반드시 불변성을 지켜야 한다. 기존 배열을 직접 수정해버리는 push()나 splice() 같은 메서드는 사용할 수 없었다.

• Create (추가): 전개 연산자(...)를 사용하여 기존 배열의 요소들을 새로운 배열에 흩뿌리듯 복사한 뒤, 그 뒤에 새로운 게시글 객체를 덧붙여 새로운 배열을 반환하도록 했다.
• Delete (삭제): 특정 게시글의 삭제 버튼을 누르면, 해당 게시글의 고유 id를 인자로 전달받아 filter() 함수를 돌렸다. 즉, 삭제하려는 id와 일치하지 않는 게시글들만 남긴 '새로운 배열'로 상태를 통째로 교체하는 방식이다.

이러한 불변성 유지 로직을 실제 코드로 구현한 모습은 다음과 같다.

import React, { useState } from 'react';
import PostList from './PostList'; // 2일차에 만든 목록 컴포넌트 불러오기

const BoardApp = () => {
  // 게시글 목록 상태 관리
  const [posts, setPosts] = useState([
    { id: 1, title: '리액트 상태 관리 학습', author: '김경민' }
  ]);

  // 폼 입력창 상태 관리
  const [inputValue, setInputValue] = useState('');

  // Create: 폼 제출 시 새로운 게시글 추가
  const handleSubmit = (e) => {
    e.preventDefault(); // 브라우저의 기본 새로고침 동작 방지

    // 유효성 검사: 빈 문자열 제출 방지
    if (inputValue.trim() === '') {
      alert('내용을 입력해주세요.');
      return;
    }

    const newPost = {
      id: Date.now(), // 고유한 식별자를 위해 현재 시간의 타임스탬프 활용
      title: inputValue,
      author: '익명'
    };

    // 기존 배열을 건드리지 않고(불변성 유지) 새 데이터가 추가된 새 배열로 상태 변경
    setPosts([...posts, newPost]);

    // 글 작성이 완료되면 입력창 초기화
    setInputValue(''); 
  };

  // Delete: 특정 게시글 삭제
  const handleDelete = (idToRemove) => {
    // filter를 이용해 삭제 대상 id와 일치하지 않는 요소만 걸러내어 새 배열 생성
    const filteredPosts = posts.filter(post => post.id !== idToRemove);
    setPosts(filteredPosts);
  };

  return (
    <div className="board-container">
      <h2>새 글 작성</h2>
      {/* 폼 제출 이벤트 핸들링 */}
      <form onSubmit={handleSubmit}>
        <input 
          type="text"
          value={inputValue}
          onChange={(e) => setInputValue(e.target.value)}
          placeholder="게시글 제목을 입력하세요"
        />
        <button type="submit">등록</button>
      </form>

      <hr />

      {/* 조건부 렌더링: 게시글 유무에 따라 다른 UI 노출 */}
      {posts.length === 0 ? (
        <p className="empty-message">아직 작성된 게시글이 없습니다.</p>
      ) : (
        <PostList posts={posts} onDelete={handleDelete} />
      )}
    </div>
  );
};

export default BoardApp;

출처/참고 https://ko.react.dev/reference/react/useState https://ko.react.dev/learn/conditional-rendering

비동기 처리와 API 연동

지금까지 완성한 게시판은 화면 단에서 CRUD가 완벽하게 작동했지만, 브라우저를 새로고침하는 순간 모든 데이터가 날아가는 치명적인 한계가 있었다. 데이터가 메모리(State)에만 존재하기 때문이다. 실제 백엔드 서버(REST API)와 연결하여 영구적으로 데이터를 읽고 쓰는 웹 애플리케이션을 만든다.

useEffect와 컴포넌트 생명주기 제어

서버에서 데이터를 가져오려면 언제 요청을 보내야 할까? 단순히 컴포넌트 함수 내부에 요청 코드를 작성하면, 상태가 변경되어 렌더링이 일어날 때마다 무한히 서버에 요청을 보내는 대참사가 발생한다. 이러한 부수 효과(Side Effect)를 통제하기 위해 React의 useEffect 훅을 학습했다. useEffect는 컴포넌트가 화면에 처음 나타날 때(Mount), 사라질 때(Unmount), 특정 상태가 변경될 때(Update) 등 컴포넌트의 생명주기에 맞춰 특정 코드를 실행할 수 있게 해준다. 두 번째 인자인 의존성 배열을 비워두면 [], 오직 처음 화면이 렌더링될 때 딱 한 번만 서버에 데이터를 요청하도록 안전하게 제어할 수 있다.

Axios를 활용한 REST API 연동 (비동기 처리)

서버와 통신하기 위해 자바스크립트 내장 fetch 대신, 실무에서 표준처럼 쓰이는 Axios 라이브러리를 도입했다. 데이터를 가져오는 데는 필연적으로 네트워크 지연(시간)이 발생하므로, 코드의 흐름이 멈추지 않도록 비동기 처리(async/await) 개념을 확인하자.

서버의 API 명세에 맞추어 HTTP 메서드를 매핑

• GET: 서버에서 전체 게시글 목록 받아오기
• POST: 내가 작성한 새 글을 서버에 저장하기
• DELETE: 특정 id의 게시글을 서버에서 삭제하기

이러한 비동기 통신 로직을 기존 코드에 붙여보자

import React, { useState, useEffect } from 'react';
import axios from 'axios';
import PostList from './PostList';

const ApiBoardApp = () => {
  const [posts, setPosts] = useState([]);
  const [inputValue, setInputValue] = useState('');

  // 1. Read (GET): 컴포넌트가 마운트될 때 딱 한 번 서버에서 데이터 로드
  useEffect(() => {
    const fetchPosts = async () => {
      try {
        const response = await axios.get('[https://api.example.com/posts](https://api.example.com/posts)');
        setPosts(response.data); // 서버에서 받은 데이터로 상태 초기화
      } catch (error) {
        console.error('데이터를 불러오는데 실패했습니다.', error);
      }
    };
    fetchPosts();
  }, []);

  // 2. Create (POST): 서버에 새 게시글 데이터 전송
  const handleAddPost = async (e) => {
    e.preventDefault();
    if (!inputValue.trim()) return;

    try {
      // 서버에 데이터 저장 요청
      const response = await axios.post('[https://api.example.com/posts](https://api.example.com/posts)', { 
        title: inputValue 
      });
      // 서버에서 응답받은 새 객체(DB에서 생성된 id 포함)를 상태에 추가
      setPosts([...posts, response.data]);
      setInputValue('');
    } catch (error) {
      console.error('게시글 작성에 실패했습니다.', error);
    }
  };

  // 3. Delete (DELETE): 서버에 특정 게시글 삭제 요청
  const handleDeletePost = async (id) => {
    try {
      await axios.delete(`https://api.example.com/posts/${id}`);
      // 서버 삭제 성공 시, 프론트엔드 상태에서도 제거
      setPosts(posts.filter(post => post.id !== id));
    } catch (error) {
      console.error('게시글 삭제에 실패했습니다.', error);
    }
  };

  return (
    <div className="board-container">
      <h2>API 연동 미니 게시판</h2>
      <form onSubmit={handleAddPost}>
        <input 
          value={inputValue} 
          onChange={(e) => setInputValue(e.target.value)} 
          placeholder="새 글을 입력하세요" 
        />
        <button type="submit">작성</button>
      </form>
      <hr />
      <PostList posts={posts} onDelete={handleDeletePost} />
    </div>
  );
};

export default ApiBoardApp;

출처/참고 https://ko.react.dev/learn/lifecycle-of-reactive-effects https://velog.io/@sukong/REACT-%EB%A6%AC%EC%95%A1%ED%8A%B8%EC%9D%98-%EC%83%9D%EB%AA%85%EC%A3%BC%EA%B8%B0%EC%99%80-useEffect-Hook

생각정리

React를 배우며 가장 뼈저리게 느낀 핵심은 단연 '상태기반의 UI 제어'와 '불변성 유지'의 중요성이다. 과거 바닐라 자바스크립트로 개발할 때는 이벤트가 발생할 때마다 일일이 DOM 요소를 찾아내서 직접 멱살을 잡고 수정해야 했다. 하지만 React는 이 귀찮은 과정을 거치지 않는다. 우리는 데이터만 신경 쓰면 된다 -> (상태를 변경하면 React가 알아서 변경점을 감지하고 화면을 업데이트) 여기에 더해 화면을 독립적인 Component 단위로 잘게 쪼개는 설계 방식은 코드의 재사용성을 엄청나게 끌어올려 주었다. 컴포넌트 분리를 통해 각 UI가 맡은 역할이 명확해지니, 코드가 아무리 길어져도 어디를 고쳐야 할지 한눈에 파악된다. 유지보수하기 좋은 코드란 무엇인지 제대로 배운 기분이다. (에러나는 부분에 터미널로 자세하게 나오니 이렇게 친절할수가..) 하나에 불편한점이라고 생각한다면 React는 상태가 곧 화면이 되기 때문에, 결국 '이 상태를 어디서 어떻게 관리할 것인가'가 애플리케이션의 성능과 구조를 좌우하는 핵심이 된다고 생각한다. 무분별하게 상태를 변경했다가는 불필요한 Re-rendering이 폭발적으로 발생하기 때문이다. 편리해진 만큼, 상태 설계를 더 꼼꼼하게 작성하는 습관을 가지자. 8주차를 마무리한다.

Gitprivate

이번 글에서는 01에이블데이를 보냈던 기록을 남겨보려고 한다. (에이블데이 진행 직후, 기억나는 내용들을 급하게 임시 저장 형태로 작성하고 이후 내용을 다시 정리해 업로드해 늦게 업로드가 되었다.. 참고로 썸네일은 코딩테스트 후 나의 모습과 비슷해 보여서 선정했다...) 이번 01 에이블데이는 Step1이 끝난 시점에 진행되었다. 오전에는 코딩테스트를 치르고, 오후에는 자소서 특강과 함께 각 반별 랜선 회식 시간을 가졌다. 약 한 달이 넘는 시간 동안 세 번의 미니 프로젝트와 공모전도 제출하고 코딩테스트 문제를 풀며 달려왔고, 어느새 하나의 단계가 마무리되었다. 이번 회고록에서는 오전에 진행했던 코딩테스트문제에 대해 집중해 나의 기억을 더듬어 작성해보겠다.

코딩테스트

문제는 총 3문제로, 제한 시간은 2시간이었다. 문제 내용은 유출이 금지되어 있기 때문에 구체적으로 다루지는 못하지만, 이번 글에서는 문제를 풀며 느꼈던 점과 접근 방식, 그리고 아쉬웠던 부분들에 대해 이야기해보려고 한다. (이번 코딩테스트는 파이썬을 선택해 진행했다.)

1번 : 2차원 배열 시뮬레이션과 차원 축소

1번 문제에서는 주어진 조건에 따라 2차원 배열의 크기를 점진적으로 줄여나가는 전형적인 구현 및 시뮬레이션 문제였다.

Main : 배열 시뮬레이션과 풀링

이 문제의 핵심은 2차원 배열의 행과 열 길이를 비교하여 분기를 나누고, 인접한 원소들을 특정 기준(최댓값 또는 최솟값)으로 압축하는 것이다. 이는 컴퓨터 비전이나 딥러닝에서 이미지의 차원을 축소하고 주요 특징을 추출할 때 사용하는 풀링 연산, 그중에서도 특정 축을 기준으로 값을 줄여나가는 과정과 매우 유사하다.

가장 대표적인 예로 맥스 풀링이 있다. 지정된 윈도우 크기(예: 1x2 또는 2x2) 내에서 가장 큰 값만 남기고 나머지는 버리는 방식이다.

개념 / 파이썬을 활용한 1차원 풀링

## 예시 
# 특정 축(가로 또는 세로)을 기준으로 인접한 두 값을 압축(Sum Pooling)하는 예시

def axis_based_pooling(arr, axis):
    row_len = len(arr)
    col_len = len(arr[0])

    if axis == 'horizontal': 
        # row을 순회하며 인덱스를 2칸씩 건너뛰어 압축
        return [[row[j] + row[j+1] for j in range(0, col_len, 2)] for row in arr]
    elif axis == 'vertical': 
        # col을 고정하고 행 인덱스를 2칸씩 건너뛰어 압축
        return [[arr[i][j] + arr[i+1][j] for j in range(col_len)] for i in range(0, row_len, 2)]

sample_matrix = [
    [1, 2, 3, 4],
    [5, 6, 7, 8]
]

# 1. 가로축 기준 압축 결과 (열의 개수가 절반으로 줄어듦)
# [[1+2, 3+4], [5+6, 7+8]] => [[3, 7], [11, 15]]
print(axis_based_pooling(sample_matrix, 'horizontal'))

# 2. 세로축 기준 압축 결과 (행의 개수가 절반으로 줄어듦)
# [[1+5, 2+6, 3+7, 4+8]] => [[6, 8, 10, 12]]
print(axis_based_pooling(sample_matrix, 'vertical'))

이번 테스트 문제는 이러한 차원 축소의 개념을 2차원 배열의 가로, 세로 비율에 따라 유동적으로(가로 방향 축소 또는 세로 방향 축소) 적용하는 것이 핵심이였다고 생각한다.

나의 접근법

문제를 해결하기 위해 나는 파이썬의 기능인 List Comprehension을 적극 활용했다. 지정된 횟수만큼 반복문을 수행하되, 루프 시작 지점에서 현재 배열의 열과 행 길이를 측정했다. 만약 배열이 더 이상 줄어들 수 없는 1x1 크기가 되었다면, 불필요한 반복 연산을 막기 위해 즉시 탈출하도록 예외 처리를 두었다.

가로가 세로보다 크거나 같을 때 행(row) 단위로 순회하며, 인덱스를 2칸씩 건너뛰며 인접한 열의 원소들을 비교해 최댓값을 추출했다. 세로가 길 때 -> 열 단위로 인덱스를 고정한 채, 인접한 행의 원소들을 비교해 최솟값을 추출하도록 구현했다.

코드 분석

리스트 컴프리헨션을 사용하여 2중 배열의 구조 변경을 단 한 줄의 코드로 처리했고, 변수 상태가 꼬일 여지를 차단했다. 특히 range(0, length, 2) 방식으로 인덱스를 제어한 것은 배열의 길이가 항상 짝수(혹은 2의 거듭제곱 꼴)로 떨어지는 제약 조건 내에서 인덱스 초과(Index Out of Bounds) 오류를 방지하는 좋은 접근이였다고 생각한다. 다만, 최적화 관점에서 내 코드를 분석해 볼 필요는 있다. 현재 방식은 매 반복 단계마다 arr = [...] 형태로 완전히 새로운 2차원 리스트를 메모리에 반복해서 동적 할당하고 있다. 파이썬 내부적으로 이전 배열은 가비지 컬렉터가 처리해주겠지만, 만약 입력 배열의 초기 크기가 어마어마하게 크고 변환 횟수가 많았다면 잦은 메모리 할당과 해제로 인해 오버헤드가 발생했을 것이다. 만약 메모리 제한이 극단적으로 빡빡한 환경이었다면, 새로운 배열을 생성하는 대신 원본 배열은 그대로 둔 채 접근해야 하는 인덱스의 범위(투 포인터 등)만 절반씩 좁혀가는 In-place 덮어쓰기 방식을 고민해야 했을 것이다. 하지만 주어진 코딩테스트의 제한 사항과 시간 복잡도 내에서는, 개발 시간 단축과 버그 방지를 위해 직관적인 배열 재생성 로직을 선택한 것이 훌륭한 트레이드오프였다고 생각한다.

2번 : 다중 라운드 상태 추적과 엣지 케이스

2번 문제는 시간이 흐름에 따라 변화하는 객체들의 상태를 추적하고, 규칙 위반 여부를 검증하는 시뮬레이션 문제였다.

Main : 상태 머신과 이력 관리

이 문제의 핵심은 여러 주체가 매 라운드마다 특정 대상과 상호작용을 시도할 때, '현재의 선택'이 '과거의 이력(직전 상태)'에 의해 제약받는다는 점이다. 이와 유사한 로직을 자주 접할 수 있다. 예를 들어, 사용자가 비밀번호를 변경할 때 '최근 3번 이내에 사용한 비밀번호는 사용할 수 없다'는 제약을 걸거나, 스케줄링 시스템에서 '이틀 연속 동일한 근무자와 짝을 이룰 수 없다'는 조건을 검증하는 로직이 이에 해당한다.

개념 / 파이썬을 활용한 과거 이력 기반 유효성 검사

문제 유출을 피하기 위해, 이와 본질적으로 동일한 구조를 가진 연속 파트너 지목 제한 로직을 간단한 파이썬 코드로 구현했다.

## 예시

def check_rule_violations(current_choices, last_partners):
    violations = 0
    valid_matches = {}

    for person, target in current_choices.items():
        # 규칙 1: 자기 자신을 지목할 수 없음
        if person == target:
            violations += 1
            continue
        # 규칙 2: 직전 라운드에서 짝이었던 사람을 다시 지목할 수 없음
        if last_partners.get(person) == target:
            violations += 1
            continue
        # 서로 지목하여 매칭이 성사된 경우를 확인 
        if current_choices.get(target) == person:
            valid_matches[person] = target

    return violations, valid_matches

# 1라운드 결과 (A-B 매칭)
history = {'A': 'B', 'B': 'A', 'C': None}

# 2라운드 선택 (A가 직전 파트너인 B를 또 지목하여 위반 발생)
round_2_choices = {'A': 'B', 'B': 'C', 'C': 'B'}

errors, new_history = check_rule_violations(round_2_choices, history)
print(f"위반 횟수: {errors}") # 결과: 위반 횟수 1

이 문제는 위 예시처럼 각 라운드의 선택을 순회하며 조건을 확인하고, 다음 라운드 검증을 위해 history를 정확히 갱신해 주는 것이 목표였다.

나의 접근법

나는 이 문제를 해결하기 위해 파이썬의 Dictionary를 활용하여 각 주체의 상태를 관리했다. last_partner라는 딕셔너리를 초기화하여 이전 라운드의 결과를 저장할 공간을 만들었다. 각 라운드마다 반복문을 돌며, 현재 지목한 target이 자기 자신이거나 직전 파트너(last_partner[me])인지 검사하여 위반 횟수를 누적했다. 서로 지목하여 조건이 맞는 경우에만 next_partner 딕셔너리에 매칭 결과를 임시 저장하고, 라운드가 끝날 때 last_partner를 next_partner로 덮어씌워 상태를 갱신했다.

코드 분석

기본적인 로직의 뼈대는 맞았지만, 결과적으로 100점 코드 결과가 나오지 못한 이유는 행위와 결과 상태의 분리가 완벽하지 않았고, 이로 인해 연쇄적인 엣지 케이스를 놓쳤기 때문이라고 생각한다. 복기해 보면 내 코드에는 문제가 있었다. 나는 서로를 올바르게 지목했을 때만(curr_choices.get(target) == me) next_partner에 기록을 남겼다. 그런데 만약 다대다 관계에서 누군가 한 명이라도 규칙을 어겼다면 어떻게 될까? A와 B가 서로를 지목했지만 A가 과거 이력 규칙을 어겨서 무효가 되었다면, A를 지목했던 B의 상태는 '매칭 실패'로 처리되어 다음 라운드에 반영되어야 한다. 즉, 특정 주체의 규칙 위반이 얽혀있는 다른 주체들에게 미치는 '연쇄 작용'을 제대로 끊어내지 못했다. 복잡한 엇갈림 속에서 매칭이 실패했음에도 불구하고, 과거의 엉뚱한 데이터를 참조하게 되어 특정 테스트 케이스에서 위반 횟수가 누락되거나 과다 측정된 것이다.

향후 개선 방향

• 상태 전이도 분리: '현재 선택 확인' -> '위반자 색출 및 필터링' -> '유효한 선택자들 간의 매칭 성사 확인' -> '결과 상태 갱신'이라는 단계를 명확한 함수나 블록으로 쪼개어 결합도를 낮춰야 한다.

• 테스트 주도 접근: 코딩을 시작하기 전에, 문제 지문에 나오지 않은 최악의 엇갈림 상황을 종이에 손으로 그려가며 상태표가 어떻게 변해야 하는지 먼저 검증해야겠다.

공부합시다 --- 출처/참고 https://kr.linkedin.com/pulse/state-machine-design-pattern-concepts-examples-python-sajad-rahimi?tl=ko https://cloudjini.tistory.com/entry/%F0%9F%93%8C-%EC%BD%94%EB%94%A9%ED%85%8C%EC%8A%A4%ED%8A%B8-%ED%85%8C%EC%8A%A4%ED%8A%B8%EC%BC%80%EC%9D%B4%EC%8A%A4-%EC%A0%9C%EB%8C%80%EB%A1%9C-%EC%9D%B4%ED%95%B4%ED%95%98%EA%B3%A0-%EA%B0%80%EC%9E%90 https://blog.naver.com/kmh03214/221685090465 https://wikidocs.net/blog/@jaehong/12397/

3번 : 이진 트리의 구조적 한계와 Bottom-Up 최적화

이진 트리의 성질을 다루는 문제였는데, 직관적인 탐색(Top-Down) 로직 함정에 낚였다... '우선순위(삭제 최소화 > 추가 최소화)'라는 제약 조건이 알고리즘의 방향성을 어떻게 완전히 뒤집어야 하는지 깨닫게 해준 좋은 문제였던거같다.

Main : 이진 트리의 종속성과 Bottom-Up 용량 전파

이 문제의 본질은 일반적인 그래프 탐색이 아니라, 이진 트리가 가지는 수학적 용량의 종속성을 해결하는 것이다. 이진 트리에서 부모 노드 1개는 최대 2개의 자식 노드만 가질 수 있다. 이를 역으로 생각하면, 특정 레벨(L)에 N개의 노드가 존재하려면, 그 바로 위 레벨(L-1)에는 최소한 $\lceil N/2 \rceil$개의 부모 노드가 반드시 존재해야 한다는 뜻이다.

개념 / 파이썬을 활용한 하위 종속성 해결 (Bottom-Up)

문제 유출을 방지하기 위해, 이진 트리 구조에서 하위 레벨의 노드들을 유지하기 위해 각 상위 레벨에서 최소 몇 개의 노드가 필요한지 역산하는 핵심 개념을 파이썬 코드로 구현했다.

import math

# 각 레벨(깊이)별 최소 필요 노드 수를 바텀업으로 계산하는 예시
def calculate_minimum_required_nodes(node_counts):
    max_level = len(node_counts) - 1
    required = [0] * (max_level + 1)
    required[max_level] = node_counts[max_level]

    # 가장 아래 레벨부터 루트를 향해 Bottom-Up으로 순회
    for L in range(max_level - 1, 0, -1):
        # 하위 레벨(L+1)의 노드들을 모두 수용하기 위해 필요한 최소 부모 수
        min_needed = math.ceil(required[L+1] / 2)
        # 실제 존재하는 노드 수와 비교하여, 더 큰 값을 현재 레벨의 필요량으로 확정
        required[L] = max(node_counts[L], min_needed)

    return required

sample_levels = [0, 1, 0, 4] # 인덱스가 레벨, 값은 해당 레벨의 노드 수
# 레벨 3에 4개의 노드가 있다면, 레벨 2에는 최소 2개의 노드가 필요하다.
# 결과: [0, 1, 2, 4] -> 빈 레벨이었던 레벨 2에 최소 2개가 필요함이 전파됨
print(calculate_minimum_required_nodes(sample_levels))

이처럼 하위 레벨의 데이터가 상위 레벨의 최소 조건을 강제하는 로직이 이 문제의 핵심 키였다.

나의 접근법

나는 주어진 노드들의 레벨 분포를 카운팅한 뒤, 루트(레벨 1)부터 시작하여 아래로 내려가는 탑다운(Top-Down) 방식으로 접근했다. 빈 레벨이 나타나면 노드를 1개 추가(added += 1)하여 연결을 유지했다. 현재 레벨의 노드 수 곱하기 2(current_node * 2)를 다음 레벨의 최대 허용치로 설정했다.다음 레벨의 노드 수가 허용치를 초과하면, 그 초과분만큼을 삭제(removed += excess)했다. 언뜻 보면 문제의 조건(빈 레벨 금지, 부모 당 자식 최대 2개)을 모두 지킨 것 같지만, 여기서 1순위, 노드 삭제를 최소한으로 할 것'이라는 가장 중요한 조건을 위배하는 실수를 저질러 버렸다..

• 무엇이 문제였을까? 가정해보자. 레벨 2에는 노드가 0개이고, 레벨 3에는 노드가 4개 존재한다.

나의 탑다운 로직: 레벨 2가 비었으므로 노드를 1개만 추가한다. 그러면 레벨 3의 최대 허용치는 2개(1*2)가 된다. 결국 레벨 3에 있던 4개의 노드 중 2개를 강제로 삭제해야 한다. (결과: 추가 1, 삭제 2)

정답 로직: 레벨 3의 노드 4개를 '삭제 없이' 살리기 위해 역산해보면, 레벨 2에는 최소 2개의 노드가 필요하다. 따라서 레벨 2에 노드를 2개 추가하면 레벨 3에서는 아무것도 삭제하지 않아도 된다. (결과: 추가 2, 삭제 0)

문제의 1순위 조건은 삭제의 최소화로 기억한다. 나의 코드는 상위 레벨에서 노드를 최소한(1개)으로 추가하려다가 극심한 병목을 만들어버렸고, 그 결과 하위 레벨에서 대량의 노드가 삭제되는 문제가 발생했다.

향후 개선 방향

• 데이터가 위에서 아래로 흐르는지, 아니면 밑바닥의 조건이 위를 강제하는지 코딩 전에 확실히 설계해야 한다. 최소 삭제가 목표라면, 지켜야 할 대상(가장 많은 노드가 포진된 하위 레벨)부터 거꾸로 올라가며 필요 인프라(부모 노드)를 구축하는 것이 맞다.

• 그리디(Greedy) 알고리즘의, 특정 시점(빈 레벨)에서 당장 최적이라고 생각한 선택(1개만 추가)이 전체의 최적해를 망칠 수 있음을 항상 경계해야 한다.

공부합시다 --- 참고/출처 https://wing-beat.tistory.com/130 https://cdragon.tistory.com/entry/%EC%9E%90%EB%A3%8C%EA%B5%AC%EC%A1%B0%EC%99%80-%EC%95%8C%EA%B3%A0%EB%A6%AC%EC%A6%98-Greedy-Algorithms https://as-ps.tistory.com/78 https://velog.io/@yoon_0/%EC%9E%90%EB%A3%8C%EA%B5%AC%EC%A1%B0-%EC%95%8C%EA%B3%A0%EB%A6%AC%EC%A6%98-%EC%9D%B8%EB%8D%B1%EC%8A%A4-%ED%8A%B8%EB%A6%AC-Top-Down-%EB%B0%A9%EC%8B%9D%EA%B3%BC-Bottom-Up-%EB%B0%A9%EC%8B%9D

자기소개서 특강

기업이 포트폴리오를 통해 확인하고자 하는 것은 지원자가 몇 개의 언어와 프레임워크를 아는지가 아니라, 실제 실무에 투입되었을 때 마주할 비즈니스 문제를 어떻게 해결할 것인가에 대한 능력이었다. 특강을 통해 배운 포트폴리오 작성의 핵심 원리와 흐름을 내 관점에서 정리해본다.

1. 포트폴리오의 진짜 목적은? -> 재사용 가능한 역량 증명

가장 크게 와닿았던 핵심 개념은 포트폴리오는 시험 점수처럼 나의 스펙을 나열하는 곳이 아니라는 점이다. 기업은 '적합하지 않은 인재를 채용할 두려움'을 강하게 가지고 있다. 따라서 우리는 포트폴리오를 통해 재사용 가능한 역량을 보여주어야 한다. 재사용 가능한 역량이란, 과거의 프로젝트에서 어떤 비즈니스 요구사항(Why)을 바탕으로 어떤 제약사항 속에서 문제를 정의(What)하고, 어떤 트레이드오프(How)를 거쳐 최종 구현을 해냈는지를 논리적으로 설명할 수 있는 능력이다. 이를 증명하면 채용 담당자는 "이 지원자는 우리 회사에 와서도 비슷한 방식으로 문제를 잘 해결하겠구나"라고 판단하게 된다.

2. 기업 문제 중심의 포트폴리오 설계

내 프로젝트를 무작정 포장하기 전에, 지원하고자 하는 기업이 현재 어떤 문제를 겪고 있는지부터 파악해야 한다. 이를 위한 가장 좋은 방법은 채용 공고(JD) 분석과 기업에서 제공하는 기술 블로그 분석이다. 적어도 10개 이상의 채용 공고를 분석하여 해당 직무의 핵심 과제, 성과 지표, 필수 경험, 그리고 요구되는 기본기를 도출해야 한다. 또한 타겟 기업의 기술 블로그를 읽으며 현업 개발자들이 어떤 제약 상황 속에서 어떤 아키텍처를 선택했고, 왜 그런 결정을 내렸는지(트레이드오프)에 대한 고민을 내 포트폴리오에 자연스럽게 녹여내야 한다.

3. 프로젝트 경험 구조화 (어떻게 작성할 것인가)

프로젝트를 소개할 때는 단순히 "무엇을 만들었다"가 아니라 철저히 문제 해결 중심으로 구조화해야 한다.

• 기술 스택 선정의 이유 가장 많이 하는 실수가 사용한 툴을 아이콘으로 줄줄이 나열만 하는 것이다. 면접관이 궁금한 것은 어떤 기술을 썼는지가 아니라 왜 하필 그 기술을 선택했는지다. 예를 들어 단순한 데이터 처리에 무거운 프레임워크를 썼다면 오버엔지니어링으로 보일 수 있다. 현재 프로젝트의 상황, 팀원의 숙련도, 성능상의 이점 등 명확한 도입 목적과 트레이드오프 판단 근거를 적어야 한다.

• 핵심 기능과 문제 해결 과정 기능을 설명할 때는 반드시 문제 → 영향 → 해결 결과의 흐름을 따라야 한다. 특히 많은 사람들이 누락하는 것이 영향 부분이다. 내가 마주한 에러나 병목 현상이 '비즈니스나 사용자 경험에 어떤 치명적인 영향을 미칠 수 있었는지'를 명시해야 내가 비즈니스를 이해하고 코드를 짜는 개발자임을 어필할 수 있다.

• 성능 개선과 회고 개선 전후의 지표를 수치화(예: 응답시간 3초 → 1초로 66% 개선)하여 보여주는 것이 중요하다. 프로젝트가 끝난 후에는 한계를 분석하고, "운영 안정성 측면에서 이러한 부분이 부족했기에 향후에는 이 아키텍처를 도입해 실시간 안정성을 높이겠다"는 식의 향후 개선 방향을 적어야 지속적으로 성장하는 인재임을 증명할 수 있다.

4. 포트폴리오 작성 도구와 검토 전략

결국 내 포트폴리오를 읽는 사람은 실무 관리자이거나 최종 결정권자다. 이들은 단순한 코딩 스킬을 넘어 시스템을 확장하고 운영할 수 있는 안정성을 본다.

• Notion 활용: 정보가 한눈에 들어오도록 3단 위계(표지 → 프로젝트 목록 DB → 개별 상세)로 구성하고, Toggle이나 Callout을 활용해 핵심만 노출시켜 가독성을 극대화해야 한다.
• GitHub 활용: README는 한 편의 훌륭한 기술 보고서가 되어야 한다. 아키텍처 다이어그램 한 장이 코드 백 줄보다 낫다. 의미 단위의 커밋 컨벤션과 CI/CD 구축 흔적으로 코드 품질과 협업 능력을 증명해야 한다.

5. 포트폴리오 작성의 비교

특강에서 제시된 사례들을 비교해보면, 합격하는 포트폴리오와 탈락하는 포트폴리오의 차이가 명확하게 드러난다.

정리해보자면

결국 좋은 포트폴리오란

"나는 주어진 스펙대로만 코딩하는 단순 구현자가 아니라, 비즈니스의 제약사항을 이해하고 최적의 기술적 타협점(트레이드오프)을 찾아내어 시스템을 개선할 수 있는 문제 해결사입니다." 라는 메시지를 던지는 매체다. 이번 특강을 바탕으로 내 과거 프로젝트들을 단순히 '무엇을 만들었나'가 아닌 '어떤 문제를 어떻게 해결했나'의 관점에서 전면 재작성해 이력서를 정리해보자!

랜선회식

반에서 간단하게 에이블기간동안 한 핵심단어 퀴즈 맞추기 및 단원 정리를 진행 (레크레이션 시간이랄까..)

그림보고 키워드 맞추기

정답 실패..

단체 컷

선물 감사합니다 111

선물 감사합니다 222

모든 9기 에이블러님들 고생하셨습니다 -_-

이번 주차에서는 LLM을 활용한 마지막 03 MiniProject를 진행하고, AIVLE DAY를 보내며 코딩테스트와 자소서 특강 강의를 진행했다. 이번 글(7주차-1)에서는 먼저 프로젝트 진행 내용을 정리하고, 다음 글(7주차-2)에서 코딩테스트 리뷰와 강의를 통해 느끼고 배워간 점들을 함께 정리해보려고 한다. 이번 프로젝트 역시 01, 02 MiniProject 때와는 또 다른 팀원들과 함께하게 되어 설레는 마음으로 시작했다. 주제는 상품 리뷰 분석 Agent 서비스 구축이었다.

프로젝트의 배경은 다음과 같다.

• 멤버십 쇼핑라운지 데이터분석팀은 AI 기반 감성 분석 프로젝트를 통해 리뷰 데이터를 구조화하고, 각 속성별 감성 정보를 추출하여 입점 업체에 제공함으로써 제품 기획, 마케팅, 고객 응대 등 비즈니스 전반에 실질적인 인사이트를 제공하는 서비스 체계를 구축하고자 했다.
• 단기적으로는 리뷰 분석 자동화를 목표로 하고, 중장기적으로는 리뷰 기반 상품 추천, 자동 요약, VOC 클러스터링 등 고도화된 서비스로 확장하기 위한 첫 단계로 프로젝트가 기획되었다.
• 최종적으로는 프로젝트의 성공을 바탕으로 전체 입점 업체까지 서비스를 확산하는 것을 목표로 하고 있었다.

이번 프로젝트 역시 이전 프로젝트들과 비슷하게 기본적인 틀은 제공되었지만, 각 팀이 회의를 통해 방향성을 구체화하고 어떤 부분에 집중해 서비스를 고도화할 것인지 결정하는 과정이 핵심이었다고 생각한다. 같은 주제를 바탕으로 하더라도 어떤 사용자 경험에 초점을 맞추고, 어떤 기능을 강화하느냐에 따라 서비스의 색깔이 완전히 달라지기 떄문이다. 특히 이번에는 Streamlit을 활용한 시각화와 LangSmith 기반의 실행 과정 모니터링 및 추적 기능까지 적용하면서, 이전 프로젝트보다 결과물을 더욱 직관적이고 완성도 있게 보여줄 수 있을 것이라는 기대가 컸다. 이러한 과정 속에서 우리 조가 어떤 방향으로 프로젝트를 진행했는지 소개해보려고 한다.

ABSA 알고 있나요?

본격적인 시스템 구현에 앞서, 이번 프로젝트의 핵심 방법론인 속성 기반 감성 분석(ABSA: Aspect-Based Sentiment Analysis)에 대해 먼저 짚고 넘어가고자 한다. 우리 서비스가 실제 비즈니스 환경에서 입점 업체들에게 '실질적인 액션 아이템'을 제시하기 위해서는 일반적인 감성 분석만으로는 괜찮을까?라는 생각이 들고 이는 강의에서 언급된 내용이기도 하지만 자세하게 다루지 않았기에 ABSA 개념에 대해 조사했다.

속성 기반 감성 분석(ABSA)이란?

단순히 전체 리뷰를 '긍정' 혹은 '부정'으로만 분류하는 기존의 감성 분석과 달리, 리뷰 내에 포함된 '구체적인 속성(Aspect, 예: 가격, 향, 성분 등)'과 그에 대응하는 '감성(Sentiment)'을 쌍으로 매칭하여 세밀하게 추출하는 자연어 처리 기법이다.

예를 들어, "가격은 저렴해서 좋은데, 향이 너무 강해서 아쉬워요."라는 리뷰가 있다면 일반적인 감성 분석은 문장 전체의 극성을 모호하게 판단하겠지만, ABSA는 다음과 같이 데이터를 구조화하여 명확한 의미를 도출해낸다.

속성 1: 가격 → 감성: 긍정(1) 속성 2: 향 → 감성: 부정(0)

왜 이번 프로젝트의 핵심이었나? 이번 프로젝트의 목표는 단순히 "고객들이 이 제품을 좋아한다/싫어한다"라는 단편적인 피드백을 전달하는 것이 아니었다고 생각한다. 입점 업체가 고객의 소리(우레에겐 리뷰)를 기반으로 제품을 개선하고 마케팅 전략을 수정할 수 있도록, "제품의 어느 부분(가격, 제형, 성분, 디자인, 배송 등)에서 만족하고, 또 어느 부분에서 구체적인 불만을 느끼는지"를 파악하는 것이 프로젝트의 핵심 과제라고 생각한다. 이러한 정성적 데이터를 정량화된 JSON 포맷으로 변환하는 ABSA 체계를 구축함으로써, 우리는 다량의 리뷰 데이터 속에서 특정 속성의 만족도 추이를 통계적으로 추출할 수 있었다. 결과적으로 이 ABSA 기법은 우리 팀의 멀티 에이전트 시스템에서 에이전트들이 문제를 인지하고 각 전문가 노드로 업무를 할당하는 판단의 기준이 되는 중요한 로직으로서 기능하게 되었다.

ABSA란? 참고 https://abluesnake.tistory.com/173 https://www.ibm.com/kr-ko/think/topics/sentiment-analysis https://www.elastic.co/kr/what-is/sentiment-analysis https://www.sciencedirect.com/science/article/abs/pii/S0950705121009059 (논문 궁금하면)

주제 : 상품 리뷰를 구조화된 감성 데이터로 변환하는 Multi - Agent AI 분석 시스템

기본 시스템 구조

전체 시스템은 LangGraph를 기반으로 설계되었으며, Supervisor, Analyzer, Critic이라는 핵심 에이전트들이 상호작용하며 리뷰 데이터를 반복적으로 분석하고 검증하는 구조로 이루어져 있다.

• 작업 분배 및 흐름 제어 (Supervisor Node): 워크플로우의 중심에서 전체 프로세스를 조율한다. 리뷰 데이터가 들어오면 먼저 Analyzer에게 분석을 지시하고, 이후 결과에 따라 Critic으로 검증을 넘기거나, 혹은 검증이 완료되면 워크플로우를 종료시키는 조건부 분기역할을 수행함

• 리뷰 데이터 1차 분석 (Analyzer Node): 사용자의 원시 리뷰 텍스트가 입력되면, 제시된 후보 속성 중 리뷰에 언급된 항목을 추출한다. 해당 속성에 대한 만족(1)과 불만족(0) 여부를 판별한다.

• 결과 검증 및 피드백 (Critic Node): Analyzer가 내놓은 분석 결과의 품질을 꼼꼼히 검토한다. 추출된 속성이나 감정 라벨링 등에 오류가 없는지 평가하고, 재작성이 필요한 경우 구체적인 피드백(예: 범위 오류, 근거 부족 등)과 함께 Analyzer가 다시 분석하도록 유도한다.

우리가 생각한 고도화 방법

1. 리뷰분석 Agent의 평점 산정 기준

• 고객이 입력한 별점이 있는 경우 -> 입력된 별점 숫자가 0보다 크면 그 숫자를 그대로 사용
• 별점이 누락되었거나 0점인 경우 -> Agent가 리뷰 원문의 직접 분석해 1점부터 5점 사이로 알아서 별점을 책정하도록 설계 (매우 만족은 5점, 만족은 4점, 보통 3점, 불만족 2점, 매우 불만족 1점)

2. 정성데이터의 정량화 (텍스트 리뷰를 수치 데이터로 변환)

• 속성(Aspect) 추출 -> 우리조는 data.csv를 미리 화장품 리뷰에 나올 법한 후보 속성 리스트(예: 가격, 향, 보습 등 50여 개)를 세팅해두고, 리뷰에서 실제로 언급된 속성 키워드를 추출
• 긍정/부정(Label) 매칭: 추출해 낸 각 속성에 대한 만족도를 판별해서, 만족/긍정은 '1', 불만족/부정은 '0'으로 라벨링을 진행
• 데이터 매칭: 결과적으로 추출된 속성 리스트와 0 또는 1로 이루어진 라벨(label) 리스트를 1:1로 정확하게 매칭했으며, 정성적인 텍스트를 JSON 데이터 형식으로 변환

3. 시스템의 우선순위 판단 기준

분석 결과에서 '불만족(0)'으로 나온 속성들을 해결하기 위해 분야별 전문가 에이전트에게 업무를 할당했다. 이때 처리 우선순위를 잡았다. (화장품 특성상 제품의 핵심 기능과 가격이 최우선이라고 판단) 그래서 매칭된 에이전트 리스트에 performance_llm(효능/성분 개선 전문가)이나 Texture_llm(제형/사용감/자극 개선 전문가)이 포함되어 있다면, 무조건 리스트의 최우선 순위에 오도록 정렬 규칙을 세웠다.

예외 처리(불만족이 없는 경우) 만약 라벨 리스트에 불만족(0)이 하나도 없는 '완전 만족' 리뷰라면? 이때는 전반적인 감사 및 고객 관리를 위해 Service_llm(배송/고객 경험 관리 전문가)을 출력하도록 예외 처리도 진행

4. 복합 불만에 대응하는 유연한 배열 반환 구조

Router Agent가 반환하는 결과값은 단일 문자열이 아니라 배열 형태의 데이터이다. 예를 들어 고객이 "크림 성분은 좋은데 뚜껑이 안 열려서 화가나요"라고 리뷰를 남겼다면? Router Agent는 이 복합적인 불만을 캐치하여 ["performance_node", "design_node"] 형태의 리스트를 반환한다. 이를 받은 LangGraph 시스템은 두 개의 전문가 노드를 모두 활성화시켜 각자의 관점에서 개선안을 작성하도록 만든다. 딱 필요한 전문가 노드만 선택적으로 깨워서 일하게 만드는 매우 효율적이게 구축했다.

5. JSON 파싱 에러에 대비한 Fallback

LLM이 결과를 뱉을 때 가끔 포맷을 무시해서 JSON 형식이 깨지는 경우가 있다. 우리는 실제 서비스 투입을 가정하고 이런 에러 상황까지 완벽하게 대비했다.

• Router Agent 코드 내에 파싱을 처리하는 try-except json.JSONDecodeError 구문을 적용
• 만약 LLM의 출력 에러로 인해 JSON 디코딩에 실패하더라도, 시스템이 에러를 뿜으며 다운되지 않고 안전하게 기본값인 ["Service_llm"]으로 향하도록 방어 로직을 구축

Batch처리 (동기 vs 비동기)

1. 기존의 방식동기식 처리 (Synchronous)

먼저, 시스템은 DB에 새롭게 쌓인 '미처리 리뷰(아직 분석되지 않아 aspect IS NULL인 상태)'들을 한꺼번에 불러와 분석을 시작한다. 초기에는 extract_review_elements라는 동기식(Sync) 함수로 진행했다. 동작 방식은 단순 -> 파이썬의 기본 for문을 돌면서, 첫 번째 리뷰를 Agent(app.invoke())에 던지고 답변이 올 때까지 가만히 기다렸다. 첫 번째 리뷰 분석이 완전히 끝나면, 그제야 두 번째 리뷰가 진행되었다.

# 기존 방식: 하나씩 순서대로 처리 (동기)
def extract_review_elements(clean_reviews):
    result = []

    for review in clean_reviews:
        print("-리뷰 분석 시작합니다.-")
        initial_state = {
            "input_review": review,
            "score": 0,
            "aspect_list": ['가격', '보습', '제형', '디자인', '배송', ...], # 생략
            "max_num": 3,
            "current_num": 0,
            "messages": []
        }


        final_state = app.invoke(initial_state) 

        result.append({
            "aspect": final_state["result"]["aspect"],
            "label": final_state["result"]["label"],
            "score": final_state["result"]["score"]
        })

    return result

문제점: LLM 기반 에이전트는 단점이 있다. 바로 네트워크 I/O 대기 시간(API 응답을 기다리는 시간)이 길다. 앞선 리뷰의 분석이 끝날 때까지 CPU가 아무 일도 하지 않고 놀고 있으니, 처리 속도가 턱없이 느릴 수밖에 없었다.

2. 개선한 비동기식 처리 (Asynchronous)

답답한 처리 속도를 해결하기 위해, 저희 조는 파이썬의 asyncio 라이브러리를 활용하여 시스템을 수정했다. 새롭게 extract_review_elements_async라는 비동기(Async) 함수를 도입다. 이제는 for문을 돌면서 무작정 기다리지 않고 비동기 호출(app.ainvoke())을 통해 여러 개의 리뷰 분석 요청을 동시에 병렬로 API에 던져준다.

import asyncio

async def extract_review_elements_async(clean_reviews, concurrency=6):
    # API 호출 제한 방지: 한 번에 최대 6개의 일꾼(Concurrency)만 일하도록 설정
    semaphore = asyncio.Semaphore(concurrency)

    async def analyze_one(review):
        async with semaphore: 
            initial_state = {
                "input_review": review,
                "score": 0,
                "aspect_list": ['가격', '보습', '제형', '디자인', '배송', ...],
                "max_num": 3,
                "current_num": 0,
                "messages": []
            }

            # 핵심 포인트! ainvoke()를 사용해 비동기적으로 API 호출
            # 응답을 기다리는 동안 다른 리뷰 분석을 동시에 진행.
            final_state = await app.ainvoke(initial_state) 

            return {
                "aspect": final_state["result"]["aspect"],
                "label": final_state["result"]["label"],
                "score": final_state["result"]["score"],
            }

    # 수많은 리뷰 요청을 한꺼번에 모아서(gather) 동시 실행!
    results = await asyncio.gather(*[analyze_one(r) for r in clean_reviews])
    return results

# 배치 실행 트리거 함수
async def start_batch_async():
    # DB에서 미처리 리뷰 불러오기 등 초기화 과정 생략
    ...
    # 비동기 함수 호출
    analyzed_results = await extract_review_elements_async(None_analyze_reviews, 6) 

    # DB 업데이트 
    update_db(None_analyze_reviews, analyzed_results)

3. 트러블슈팅 및 결과: 5.52배 성능 향상

동기 방식에서 비동기 방식으로 파이프라인을 완전히 리팩토링한 결과는 성공적이였다. 우선, API 응답을 하염없이 기다리게 만들었던 원흉인 app.invoke()를 비동기 호출 메서드인 app.ainvoke()로 전면 교체하고 파이썬의 asyncio.gather를 활용해 수많은 미처리 리뷰 데이터를 개별적으로 보내지 않고 한 번에 묶어 쏘아 올리는 병렬 구조로 변경했다. 이렇게 설계하니 기존 동기 방식에서 아무것도 하지 못하고 버려지던 '응답 대기 시간'들을 완벽하게 겹쳐서(Overlap) 사용할 수 있게 되었고, 병목 현상을 해결 할 수 있었다.

Rate Limit 방어

무작정 수천, 수만개 등의 리뷰 요청을 동시에 던지면 어떻게 될까? 십중팔구 LLM API 서버에서 'Rate Limit' 에러를 뿜어내며 전체 시스템이 다운될것이다. 저희 조는 이 치명적인 문제를 방지하기 위해 asyncio.Semaphore(6)를 도입했다. 동시에 일하는 워커의 개수를 최대 6개로 제한하여, API 서버에 과부하를 주지 않으면서도 시스템이 낼 수 있는 최대의 효율을 뽑아내는 안정적인 타협점을 찾았다.

그 결과, 한 번의 API 에러나 멈춤 없이 시스템이 아주 안정적으로 돌아갔다. 동일한 수량의 리뷰 데이터를 배치 처리하는 데 걸리는 전체 시간이 획기적으로 줄어들었으며, 최종적으로 기존 대비 약 5.52배라는 성능을 향상시켰다.

LangSmith 모니터링

우리 조의 역할을 분담하는 과정에서 나는 LangSmith 파트를 맡게 되었다. 이에 따라 이번 화장품 리뷰 분석 AI 에이전트 프로젝트에서는 LangSmith 기반의 모니터링 시스템 구축에 검증하고 조사했다.

1. Trace Tree 시각화를 통한 동적 라우팅 및 병렬 처리 검증

코드로 설계한 LangGraph 아키텍처가 실제 트래픽 환경에서 어떻게 동작하는지 LangSmith의 Trace Tree를 통해 가장 먼저 확인했다.

• 동적 라우팅(Dynamic Routing) 확인: 로그를 보면 START 노드에서 시작된 리뷰 데이터가 가장 먼저 router_node로 진입하고 라우터는 리뷰의 불만족 속성을 파악하여 어떤 전문가 에이전트를 호출할지 결정하는 역할을 수행한다.

• Send API 기반의 병렬 실행 증명: 트리의 하단부를 보면 저희 조 아키텍처의 핵심인 '병렬 처리'가 완벽하게 기록되어 있다. router_node 이후 add_conditional_edges와 Send API를 통해 performance_node(성분/효능), design_node(패키징), service_node(CS) 등의 여러 전문가 노드가 직렬이 아닌 동시에(병렬로) 분기되어 실행되는 흐름을 시각적으로 확인할 수 있었습니다. 이는 비동기 처리가 의도대로 작동하여 전체 처리 시간을 획기적으로 단축시키고 있음을 보여준다.

2. 노드별 I/O 심층 추적을 통한 프롬프트 디버깅 및 제어

단일 실행 기록(Run)의 세부 내역으로 들어가면, 각 전문가 에이전트에게 LLM모델이 어떤 입력을 받고 어떤 출력을 반환하는지 정확히 추적이 가능하다.

Router Node의 매칭 정확도 검증

router_node의 상세 로그를 통해, 50여 개의 화장품 속성(aspect)과 불만족(label=0) 데이터가 어떻게 파싱되는지 확인했다. 예를 들어 '보습' 불만은 performance_node로, '포장' 불만은 design_node로 정확히 분류하여 ["performance_node", "design_node"] 형태의 리스트를 반환하는 것을 디버깅했습니다. 파싱 에러 발생 시 Fallback으로 ["service_node"]가 정상 호출되는 예외 처리 로직도 이 화면을 통해 검증을 진행했다.

전문가 Node(Expert Agents)의 도메인 특화 추론 확인

특정 전문가 노드(예: design_node 또는 texture_node)의 내부 추론 로그다. 모델이 프롬프트 지시사항에 따라 자신의 담당 영역이 아닌 불만(예: 디자이너 노드에 입력된 배송 불만)은 철저히 무시하고, 오직 자신의 도메인에 맞춰 "- 속성: ... - 원인 분석: ... - 개선 방안: ..." 형태의 규격화된 텍스트로 해결책을 제시하고 있음을 확인했습니다. 이를 통해 모델의 환각 현상을 통제하고 전문성을 극대화한다.

Aggregator Node의 최종 데이터 병합

개별적으로 실행된 전문가 에이전트들의 result_list가 최종적으로 aggregator_node에 모여 데이터 소실 없이 하나의 [종합 제품 개선 제안서] 텍스트 포맷으로 완벽하게 병합되는 마지막 단계를 확인했다.

3. 대시보드 지표 분석과 토큰/비용 최적화

LangSmith의 대시보드 지표는 시스템의 부하 상태를 정량적으로 파악하고 아키텍처를 개선하는 결정적인 근거가 된다. 병렬로 수많은 에이전트가 동시에 LLM(OPEN_API) API를 호출하는 구조이다 보니, 토큰 사용량과 Rate Limit 관리의 중요성이 매우 컸다. Metrics 탭의 Latency 차트와 Token Usage 리스트를 상시 모니터링하여, 여러 전문가를 동시에 깨우는 병렬 라우팅 구조가 동기식 순차 처리 방식보다 지연 시간방어에 훨씬 유리함을 지표 추이로 입증했다.

결과 시각화 (Streamlit)

생각정리

이번 3차 Mini Project는 단순히 LLM을 호출해 결과를 출력하는 것이아닌, 실제 서비스 환경에서 AI 시스템을 어떻게 안정적으로 운영하고 관리할 것인가에 대해 생각해볼 수 있는 프로젝트이지 않을까? 라는 생각이 든다.

리뷰 분석이라는 하나의 기능 뒤에도, 우리가 고도화 과정에서 다뤘던 Rate Limit 대응, JSON 파싱 오류 처리, 병렬 처리 구조 설계, 응답 지연 시간(Latency) 개선, 토큰 비용 최적화 등 생각보다 훨씬 많은 시스템적 문제들이 존재했다. 또한 다른 조들의 발표를 들으며 같은 주제를 가지고도 팀마다 전혀 다른 방향으로 프로젝트를 발전시킨 점이 인상 깊었다. 어떤 조는 LangSmith를 활용한 모니터링과 분석 체계에 더욱 집중해 AI 파이프라인의 흐름과 안정성을 강조했고, 또 다른 조는 리뷰 데이터를 활용한 실제 서비스 아이디어를 구체적으로 제시하기도 했다. 반면 사용자 관점에서 리뷰를 어떻게 더 직관적으로 받아들이고 활용할 수 있을지에 집중해 UX 측면을 강화한 조도 있었다. 단순히 모델 성능만이 중요한 것이 아니라, 어떤 문제를 정의하고 어떤 사용자 경험을 제공할 것인지에 따라 같은 AI 기술도 완전히 다른 결과물로 이어질 수 있다는 점에 시야가 넓어진거같다..

이번 프로젝트에서 내가 맡았던 LangSmith 기반 모니터링 파트에서는 반복적인 로그를 보는 것이 아닌, LangGraph 기반 멀티 에이전트 구조가 실제로 어떤 흐름으로 동작하는지 Trace 단위로 분석하고 검증하는 경험을 할 수 있었다. 각 Agent가 어떤 입력을 받고 어떤 판단을 내리는지, 병렬 라우팅이 실제로 의도한 대로 수행되는지, 그리고 특정 프롬프트가 왜 잘못된 결과를 만드는지까지 시각적으로 추적하며 디버깅할 수 있었고, 이를 통해 AI 시스템의 신뢰성과 제어 가능성을 크게 높일 수 있었다. 또한 프로젝트를 진행하면서 좋은 프롬프트 하나로 모든 문제가 해결되지는 않는다는 점도 크게 느꼈다. 실제로 Trace 로그를 분석해보면 모델의 성능 부족보다는 프롬프트의 모호함, 예외 처리 부족, 출력 포맷 불일치 같은 시스템 설계 영역의 문제가 더 자주 발생했다. 이를 해결하기 위해 Few-shot 예시를 반복적으로 수정하고, Fallback 로직과 검증 규칙을 추가하며 프롬프트 엔지니어링을 더 수정하고 발전해나갔다. 더 개선할점이 있고 발전할점도 있지만 짧은 기간동안 조원들과 토의하고 이뤄낸 결과이기에 이번 03Miniproject결과물은 만족한다.

좋은 팀원들과 함께 수없이 테스트하고, 실패하고, 개선해 나가며 완성했던 만큼 개인적으 정말 많이 배우고 성장할 수 있었던 프로젝트였다. 7주차-1을 마무리한다.

12조 조원분들 고생하셨습니다!

Github Private

최근 AX 공모전 제출 준비로 인해 블로그 활동이 조금 뜸해졌다. 문서화 작업에 예상보다 많은 시간이 들어가면서, GitHub PR 정리부터 노션 문서화, 보고서 작성까지 꽤 많은 에너지를 쏟게 된 것 같다. 그래도 그만큼 열심히 준비한 만큼 좋은 결과가 있기를 바라고 있다. 관심 있다면 프로젝트도 한번 구경해 보세요 :) 그 사이 03차 미니프로젝트와 에이블 데이(코딩 테스트 3문제 및 특별 강의)도 진행했는데, 이것들도 천천히 기록해 보려고 한다. 우선은 6주 차에 학습했던 LLMOps 개념부터 다시 정리하며 복습해보려 한다.

1. LLMOps 개념/필요성

최근 챗GPT나 Claude 같은 거대 언어 모델(LLM)을 활용한 서비스가 쏟아지고 있다. 나 역시 간단한 프롬프트 엔지니어링만으로도 그럴듯한 챗봇이나 자동화 스크립트를 만들어본 경험이 있다. (최근 뜻깊게 보고 있는 Claude.md 포함)이번 강의를 들으며, 단순히 API를 호출해 답변을 얻어내는 '데모 수준의 장난감'과 실제 비즈니스 환경에서 신뢰하고 사용할 수 있는 '상용 AI 시스템' 사이에는 거대한 벽이 존재한다는 것을 깨달았다. 그 벽을 넘기 위해 알아야 하는 개념이 바로 LLMOps(Large Language Model Operations) 다. 'LLMOps의 개념과 필요성'에 대해 내가 이해하고 정리한 내용을 다루어 보려고 한다.

1.1 LLMOps란 무엇이며, 기존 MLOps와 어떻게 다른가?

소프트웨어 개발에 관심이 있다면 데브옵스(DevOps)나 머신러닝 옵스(MLOps)라는 단어를 들어보았을 것이다. LLMOps는 쉽게 말해 LLM 기반의 애플리케이션을 개발, 배포, 유지보수하는 전체 생애주기를 관리하는 방법론이다. 처음에는 LLMOps가 기존의 MLOps와 비슷한 것이 아닐까 생각했다. 하지만 둘은 초점을 맞추는 영역 자체가 완전히 달랐다.

• MLOps의 핵심 (데이터와 모델의 학습): 기존의 인공지능 프로젝트는 우리가 직접 양질의 데이터를 수집하고, 정제하여, 모델을 학습시키고 정확도를 높이는 데 집중했다. 즉, '어떻게 하면 똑똑한 모델을 만들 것인가'가 주된 과제였다.
• LLMOps의 핵심 (시스템 통합과 통제): 반면 LLMOps 환경에서는 이미 오픈AI나 구글이 천문학적인 비용을 들여 학습시켜 놓은 초거대 모델을 가져다 쓴다. 모델 자체를 뜯어고치거나 재학습시키는 파인튜닝(Fine-tuning)보다는, 이 똑똑하지만 통제하기 힘든 모델을 '어떻게 우리 비즈니스 로직에 맞게 오케스트레이션하고 제어할 것인가' 에 집중한다.

프롬프트를 어떻게 버저닝(Versioning)하여 관리할 것인지, 모델이 외부 API나 도구(Tool)를 사용할 때 발생하는 오류를 어떻게 복구할 것인지, 복잡한 체인(Chain)의 흐름을 어떻게 시각화할 것인지가 LLMOps의 최대 관심사다.

1.2. 왜 LLMOps가 필수적인가?

전통적인 소프트웨어 프로그래밍은 명확하다. A라는 입력값을 주면 정해진 로직을 거쳐 반드시 B라는 출력값이 나온다. 하지만 LLM은 기본적으로 다음에 올 단어를 확률적으로 예측하는 모델이다. 이러한 태생적 특징 때문에 상용 서비스를 구축할 때 치명적인 3가지 리스크가 발생하게 되며, 이를 제어하기 위해 LLMOps가 필요하다.

1) 비결정론적 출력 (Non-deterministic Output)

가장 개발자를 괴롭히는 요소다. LLM은 동일한 프롬프트를 입력해도 어제 다르고 오늘 다른 답변을 내놓을 수 있다. 소프트웨어를 개발할 때는 코드가 정상적으로 작동하는지 확인하기 위해 단위 테스트를 작성한다. 하지만 LLM의 결과물은 매번 텍스트의 형태나 문맥이 미세하게 바뀌기 때문에 전통적인 방식의 테스트 코드(assert output == "정확한 텍스트")를 작성하는 것이 불가능하다. 이러한 비결정성 때문에 시스템이 예기치 못한 에러를 뱉었을 때 버그를 재현하기가 극도로 어려우며, 출력 결과의 포맷(예: JSON 형식으로만 응답해달라는 요청)이 깨지는 현상이 빈번하게 발생한다.

2) 기하급수적인 비용(Cost)과 지연 시간(Latency)

API를 통해 LLM을 사용할 때는 입력과 출력에 사용된 토큰의 수량만큼 요금이 부과된다. 단순한 1회성 질문과 답변이라면 큰 문제가 되지 않지만, 에이전트시스템으로 넘어가면 이야기가 달라진다. 최근의 AI 시스템은 문제를 스스로 계획하고, 검색하고, 코드를 실행하고, 결과를 스스로 검토하여 틀리면 다시 처음으로 돌아가는 루프 구조를 가진다. 만약 모델이 방향을 잘못 잡아 무한 루프에 빠지게 된다면, 에이전트는 계속해서 이전까지의 대화 기록을 통째로 짊어지고 모델을 호출하게 된다. 이는 순식간에 막대한 API 과금으로 이어질 수 있다. 또한, 하나의 최종 답변을 만들기 위해 모델을 내부적으로 5~10번씩 호출하게 되면, 사용자가 화면 앞에서 응답을 기다리는 지연 시간이 수십 초 단위로 길어져 서비스의 사용자 경험을 심각하게 훼손하게 된다.

3) 환각(Hallucination)의 연쇄 작용

LLM이 사실이 아닌 내용을 그럴듯하게 지어내는 환각 현상은 널리 알려져 있다. 하지만 멀티 에이전트(Multi-Agent) 시스템에서는 이 환각이 훨씬 더 무서운 결과를 초래한다. 예를 들어, 계약서를 분석하는 에이전트 파이프라인이 있다고 가정해 보자. 첫 번째 정보 추출 에이전트가 존재하지 않는 위약금 조항을 환각으로 만들어냈다. 만약 이 결과가 필터링 없이 두 번째 요약 에이전트, 세 번째 메일 발송 에이전트로 그대로 전달된다면 어떻게 될까? 단순한 오답 하나가 눈덩이처럼 불어나 기업의 법적 책임 문제나 심각한 비즈니스 리스크로 직결될 수 있다.

1.3. '잘 작동하는 AI' -> '통제 가능한 AI'

앞서 말한 리스크들을 완벽하게 0으로 만드는 것은 현재의 LLM 기술로는 불가능에 가깝다. 그렇다면 어떻게 접근해야 할까? 강의에 핵심 메시지는 바로 '통제 가능성' 을 확보하는 것이었다. 성공적으로 작동할 때의 데모 영상은 누구나 화려하게 만들 수 있다. 하지만 진정한 엔지니어링은 실패했을 때 발견된다.

• 가시성과 투명성: 시스템 내부에서 에이전트들이 어떤 프롬프트를 주고받았고, 어떤 도구를 사용했으며, 어느 지점에서 시간이 가장 오래 걸렸는지 한눈에 추적할 수 있어야 한다.
• 상태 추적과 재현성: 에러가 발생했다면, 그 에러가 발생하기 직전의 데이터 상태로 돌아가 디버깅을 하고 재실행할 수 있는 구조가 필요하다.
• 안전장치(개입 가능성): AI가 중요한 의사결정을 내리기 직전, 혹은 특정 비용 한도에 도달했을 때 프로세스를 멈추고 인간이 직접 개입하여 승인하거나 수정할 수 있는 연결 고리를 만들어 두어야 한다. 결국 LLMOps의 첫걸음은 "AI 모델을 그냥 믿고 맡겨두면 알아서 잘하겠지"라는 환상을 버리는 것에서 시작한다. AI는 매우 유능한 인턴이지만, 그 인턴이 사고를 치지 않도록 업무 프로세스를 잘게 쪼개고, 결재 라인을 만들고, 업무 지시서를 명확히 문서화하며, 중간 보고를 받도록 시스템을 설계하는 과정이 반드시 필요하다. 이러한 통제 가능한 아키텍처를 만들기 위해 어떠한 방식의 설계 절차를 거치고, 어떤 문서들을 작성해야하는지 알아보자.

참고/출처 https://tech.ktcloud.com/entry/2026-01-ktcloud-mlops-llmops-%EC%9A%B4%EC%98%81%EC%B2%B4%EA%B3%84-%EC%A0%84%ED%99%98 (많이 배웁니다..) https://www.databricks.com/blog/what-is-llmops https://solutionshub.epam.com/blog/post/aiops https://www.redhat.com/ko/topics/ai/llmops

2. AI Agent 시스템 설계 절차와 5대 핵심 문서화 전략

강의를 들으며 내 기존 개발 방식을 다시 돌아보게 되었다. 나는 그동안 아이디어가 떠오르면 전체적인 흐름을 먼저 머릿속에 그리고, 이를 여러 섹션으로 나눈 뒤 어떻게 개발하고 연결할지 구상하며 부분적으로 기능을 붙여나가는 식으로 개발을 진행해 왔다. 일반적인 애플리케이션이나 단순한 스크립트를 짤 때는 이 방식이 꽤 유용했다. 하지만 데모 수준을 넘어선 LLM 기반의 멀티 에이전트 시스템을 구축할 때 이런 머릿속 구상이나 점진적인 기능 추가 방식은 한계가 명확했다. 에이전트가 두세 개만 넘어가도 서로 어떤 데이터를 주고받는지, 예외 상황에서 흐름이 어떻게 꼬이는지 정확히 추적하고 통제하기가 불가능해지기 때문이다. 성공적인 AI Agent 시스템을 위해서는 코딩 전에 완벽한 문서화 형태의 설계가 선행되어야 한다. 이번 글에서는 내가 학습한 에이전트 시스템 설계의 5단계 흐름과, 5개 설계 문서에 대해 정리해 보았다.

2.1. AI Agent 시스템 설계 5단계 흐름

개발자가 가장 저지르기 쉬운 실수는 '문제'보다 'AI 모델'을 먼저 생각하는 것이다. LLMOps 관점에서는 철저하게 비즈니스 문제 해결을 위한 소프트웨어 공학적 설계 절차를 따른다.

• 문제 정의 (Problem): 우리가 현재 어떤 비즈니스적 어려움을 겪고 있으며, 기존 시스템의 한계는 무엇인지 명확히 한다.
• 목표 정의 (Goal): AI 시스템을 도입해서 얻고자 하는 최종 결과물과 성공을 측정할 수 있는 평가 지표를 수립한다.
• 시나리오 정의 (Scenario): 사용자가 시스템에 어떻게 접근하고, 어떤 입력을 주며, 최종적으로 어떤 형태의 출력을 받게 되는지 Use Case 기반의 서비스 흐름을 그린다.
• 구조 설계 (Architecture Design): 요구사항을 해결하기 위해 어떤 역할을 가진 에이전트들이 필요한지 쪼개고, 이들이 어떻게 상호작용할지 전체적인 워크플로우 초안을 그린다.
• 상세 설계 (Detailed Design): 본격적인 구현 직전, 각 에이전트의 구체적인 입력/출력값, 프롬프트 내용, 데이터의 상태 구조를 상세 문서로 명세화한다.

이 중에서 시스템의 안정성과 직결되는 가장 중요한 작업이 바로 마지막 5단계인 '상세 설계'다.

2.2. 통제를 위한 5대 핵심 설계 문서

강의에서 제공된 설계 문서 양식들을 직접 뜯어보면서, 시스템을 톱니바퀴처럼 맞물려 돌아가게 만드는 요소가 무엇인지 파악할 수 있었다. 프로젝트를 진행할떄 아래의 5가지 문서를 통해 에이전트를 완벽하게 제어하는것이 목표다.

1) Agent 역할 정의서 (Agent Role Definition)

각 에이전트에게 명확한 자아와 책임 범위를 부여하는 문서다. 하나의 에이전트가 너무 많은 일을 하면 환각이 발생할 확률이 급격히 높아지므로 역할을 철저히 분리해야 한다.

• 목적 및 역할: 예를 들어 Planner Agent는 계획만 세우고, Executor Agent는 계획에 따라 계약서에서 정보만 추출하며, Critic Agent는 결과물의 품질만 평가하도록 쪼갠다.
• 입력과 출력: 해당 에이전트가 실행되기 위해 필요한 필수 데이터(Input)와 다음 노드로 넘겨줄 결과 데이터(Output)를 명시한다.
• 제약 조건 및 실패 리스크: 문서에 없는 내용은 절대 추측하지 말 것, 실행 로직을 포함하지 말 것 같은 엄격한 규칙과, 이 에이전트가 실패했을 때 전체 워크플로우에 미치는 파급력을 기록한다.

2) Workflow 명세서 (Workflow Specification)

역할이 부여된 에이전트들이 어떤 순서로 동작하는지 전체적인 실행 뼈대를 정의한다. 시작 단계에서 어떤 데이터가 입력되는지, 그리고 Planner에서 Executor, Critic, Supervisor를 거쳐 종료에 이르는 각 단계마다 데이터가 어떻게 가공되고 전달되는지를 한눈에 볼 수 있도록 도식화 및 문서화한다. 이 문서가 있어야만 무한 루프에 빠지는 설계적 결함을 사전에 방지할 수 있다.

3) State 정의서 (State Specification)

개인적으로 멀티 에이전트 시스템에서 가장 중요하다고 느낀 부분이다. 에이전트 시스템은 'State(상태)'라는 전역 객체를 메모리처럼 서로 공유하며 작업을 진행한다.

• 변수 및 데이터 타입 정의: 전체 과정을 기록할 messages, 사용자의 최초 요구사항인 user_request, 에이전트 간 주고받을 extracted_info나 summary 등 상태에 담길 모든 변수를 정의한다.
• 업데이트 방식 (Reducer vs Overwrite): 특정 변수에 새로운 값이 들어왔을 때, 이전 값을 지우고 덮어쓸 것인지(Overwrite), 아니면 기존 배열에 값을 계속 누적하여 추가할 것인지(Reducer)를 설계한다. 예를 들어 대화 기록인 messages는 누적되어야 하고, 현재 실행 단계를 나타내는 current_step_index는 다음 숫자로 덮어써져야 한다. 이 규칙이 어긋나면 시스템은 과거의 기억을 잃거나 불필요한 데이터 폭탄을 안고 실행을 반복하게 된다.

4) Decision Policy (의사결정 정책서)

분기점(라우팅)에서 어떤 조건일 때 어떤 에이전트를 실행할지, 언제 반복을 종료할지 명확한 수학적/논리적 조건식으로 정의한 문서다.

• 실행 및 평가 제어: 계획된 단계가 남아있으면 다음 Executor를 실행하고, 모든 단계가 끝났으면 Critic을 호출하여 평가를 받게 한다.
• 재실행 및 강제 종료 정책: Critic의 평가 결과가 거절일 때 무조건 다시 실행하는 것이 아니라, 현재 반복 횟수가 최대 허용 횟수 미만일 때만 Planner로 돌아가 재계획을 수행한다. 만약 제한 횟수에 도달했다면 비용 폭증을 막기 위해 현재까지의 결과만 반환하고 강제로 종료하도록 조건을 촘촘하게 설정한다.

5) Prompt 명세서 (Prompt Specification)

개발자가 코딩할 때 변수명을 정하듯, LLM에게 전달할 프롬프트의 골격을 문서로 고정한다.

• 페르소나와 지침: 에이전트가 맡은 역할에 몰입할 수 있도록 구체적인 전문가 페르소나를 부여하고, 수행해야 할 과업을 간결하고 명확하게 지시한다.
• 엄격한 출력 형식(Formatting): 비결정론적 특성을 통제하기 위해 응답 형식을 매우 엄격하게 제한한다. 예를 들어 Planner는 반드시 파이썬 리스트 형태로만 응답하도록 강제하고, 다른 부연 설명은 일절 금지한다. 이러한 출력 포맷을 사전에 문서로 확정해야만 코드로 파싱할 때 발생하는 오류를 막을 수 있다.

이 5가지 문서를 꼼꼼히 작성하는 과정이 처음에는 꽤나 번거롭고 시간이 오래 걸리는 작업처럼 느껴졌다. 부분적으로 기능을 떼어 붙여가며 코딩하던 나의 익숙한 방식과는 다소 거리가 있었기 때문이다. 하지만 복잡도를 높여가며 테스트를 해보니, 이 설계 문서들이야말로 개발 시간을 줄여주고 시스템을 내 장악하는데 큰 영향을 준다. 기능이 얽혀서 버그가 났을 때 어디를 고쳐야 할지, 어떤 상태 값이 잘못되었는지 문서에 이미 답이 다 적혀 있기 때문이다.

참고/출처 https://wikidocs.net/blog/@jaehong/9475/ https://www.youtube.com/watch?v=UCV3lAo0fhQ https://lobehub.com/skills/openclaw-skills-naver-search (이런것도 있구나)

3. 역할 기반 설계와 워크플로우를 지휘하는 Supervisor 패턴

구체적으로 에이전트들의 역할을 어떻게 분리하고 이들의 실행 흐름을 어떻게 중앙에서 강력하게 통제하는지 그 아키텍처의 핵심인 역할 기반 설계(Role-based Design)와 Supervisor 패턴에 대해 복습해보려고한다.

3.1. 머릿속의 섹션 구상을 에이전트의 역할 분리로 구체화하기

나는 위에서 한번 언급 했듯 평소에 새로운 아이디어가 떠오르면 전체적인 흐름을 먼저 머릿속에 그려둔 뒤, 이를 여러 섹션으로 나눈다. 그리고 각 섹션별로 어떻게 개발하고 연결해야 할지 틀을 잡은 다음, 부분적으로 기능을 하나씩 붙여가며 살을 붙이는 방식으로 개발을 진행해 왔다. 이러한 탑다운(Top-down) 방식의 접근과 점진적인 기능 결합은 일반적인 애플리케이션 개발에서 코드를 깔끔하게 유지하는 데 큰 도움이 되었다. 강의를 들으며 놀라웠던 점은, 내가 평소에 하던 이 개발 습관이 LLMOps에서 복잡한 문제를 해결하기 위해 사용하는 역할 기반 설계의 철학과 정확히 맞물려 있다는 사실이었다. 거대하고 모호한 비즈니스 문제를 하나의 프롬프트로 해결하려 하지 않고, 전체 흐름을 논리적인 섹션으로 쪼갠 뒤 그 섹션마다 전담 전문가(에이전트)를 배치하여 부분적인 기능을 독립적으로 수행하게 만드는 것이다. 다만 결정적인 차이점이 있었다. 일반적인 소프트웨어에서는 내가 나눈 섹션들이 정해진 로직에 따라 완벽하게 맞물려 돌아가지만, LLM 환경에서는 각 섹션을 담당하는 주체가 비결정론적인 인공지능이라는 점이다. 따라서 머릿속 구상에만 의존해 대강 기능을 붙여 나가면 에이전트들이 서로 엉뚱한 데이터를 주고받으며 전체 파이프라인이 쉽게 무너진다. 이를 방지하기 위해 전문가 에이전트들의 역할을 수학적으로 명확히 분리하고, 이들을 유기적으로 연결하는 고도화된 아키텍처 패턴이 필요하다.

3.2. Planner, Executor, Critic의 전문가 삼각 편대

역할 기반 설계에서 가장 널리 쓰이면서도 강력한 구조는 복잡한 과업을 Planner(기획자), Executor(수행자), Critic(검토자) 이라는 세 가지 축으로 분리하는 것이다. 하나의 AI에게 "문서를 분석하고 요약해서 검증까지 끝내라"고 하면 과부하가 걸려 환각을 일으키기 쉽지만, 역할을 쪼개면 각 단계에서 모델이 집중해야 할 컨텍스트의 크기가 줄어들어 품질이 극대화된다.

1) Planner Agent: 전략과 계획 수립의 사령탑

Planner는 사용자의 최초 요구사항과 분석해야 할 원문 데이터를 입력받아, 직접 문제를 해결하는 대신 문제를 해결하기 위한 '단계별 실행 계획(Plan)'을 수립하는 역할을 한다.

• 동작 원리: 사용자가 아무리 복잡하거나 모호한 요청을 하더라도, Planner는 자신이 사용할 수 있는 도구나 하위 에이전트들의 목록을 고려하여 최적의 실행 순서를 정의한다. 예를 들어 프롬프트 명세서에 정의된 규칙에 따라 반드시 파이썬 리스트 형태(["executor1", "executor2"])로만 실행 계획을 출력하도록 강력히 통제된다. 부연 설명이나 변명을 일절 배제함으로써 후속 코드가 결과를 안정적으로 파싱할 수 있게 만든다.
• 재계획(Replanning) 기능: Planner의 진짜 가치는 실패했을 때 드러난다. 뒤에서 설명할 Critic에 의해 결과물이 거절(REJECTED)되면, Planner는 단순하게 이전 계획을 반복하는 것이 아니라 State에 누적된 Critic의 구체적인 거절 사유(Critique reason)를 읽어 들인다. "어느 지점의 정보 추출이 부실했다"는 피드백을 바탕으로 계획을 전면 수정하거나 새로운 단계를 추가하는 재계획을 수행한다.

2) Executor Agent: 철저하게 지침에 따르는 유닛

Executor는 Planner가 수립한 계획의 단위를 하나씩 넘겨받아 실제 데이터 가공 및 분석을 수행하는 에이전트다. 프로젝트의 특성에 따라 여러 개의 Executor를 독립적으로 배치할 수 있다. 이번 계약서 분석 워크플로우 예시에서는 두 가지 Executor로 세분화되었다.

• Executor1 (정보 추출 전문가): 계약서 원문과 사용자 요청을 비교하여 계약 당사자, 계약 기간, 계약 금액 및 사용자가 별도로 요구한 특약 사항 등의 핵심 정보만 항목형으로 깔끔하게 추출한다. 프롬프트 지침에 "문서에 없는 내용은 절대로 유추하거나 추측하지 말 것"이라는 제약 조건을 엄격하게 고정하여 환각 발생을 차단한다. 작업을 마치면 추출된 정보를 State에 기록하고, 현재 진행 단계를 나타내는 인덱스(current_step_index)를 1 증가시킨 뒤 제어권을 넘긴다.
• Executor2 (요약 전문가): 원문 문서와 Executor1이 앞서 추출해 둔 핵심 정보를 동시에 입력받아 전체 내용을 명확하게 요약하는 실무를 담당한다. 추출된 정보를 레퍼런스로 삼기 때문에 완전히 엉뚱한 내용으로 요약할 위험이 현저히 줄어든다. 지침에 따라 3문장 이내의 bullet-point 형식 등 일관된 포맷으로 결과물(summary)을 작성하여 State를 업데이트한다.

3) Critic Agent: 타협 없는 품질 검증관

Critic은 앞선 Executor들이 만들어낸 최종 결과물(extracted_info, summary)이 사용자의 최초 요구사항을 완벽하게 충족하는지 제3자의 시선에서 냉정하게 평가하는 에이전트다.

• 평가와 사유의 명시: Critic은 새로운 정보를 창출해서는 안 되며, 오직 검증만 수행해야 한다. 결과가 합격점이라면 승인(critique_decision = "APPROVED")을 내리고 워크플로우를 종료 단계로 이끈다. 만약 지침이 누락되었거나 품질이 떨어진다면 과감하게 거절(critique_decision = "REJECTED") 판정을 내린다. 이때 가장 중요한 것은 단순히 거절하는 것에 그치지 않고, Planner가 계획을 보정할 수 있도록 구체적인 불합격 사유(critique_reason)를 논리적 문장으로 기록하여 State에 남겨야 한다는 점이다.

3.3. 왜 Supervisor 패턴인가? 중앙 집권식 흐름 통제의 힘

Planner, Executor, Critic을 각각 잘 만드는 것보다 훨씬 더 중요한 과제는 이 에이전트들을 어떻게 연결할 것인가이다. 에이전트 시스템을 처음 개발할 때 흔히 하는 실수는 에이전트가 직접 다음 행동을 결정하게 만드는 것이다. 예를 들어 Executor1이 끝나면 스스로 판단해서 Executor2를 호출하고, Critic이 끝나면 Critic 내부 로직 안에서 판단해 Planner로 직접 데이터를 던지는 방식이다. 이런 구조는 내가 평소 하던 대로 섹션을 나눠 기능을 붙여나갈 때 자칫 발생하기 쉬운 끈끈한 결합 상태를 유발한다. 에이전트가 많아질수록 화살표가 사방으로 얽히며 코드가 스파게티처럼 꼬이고, 예외 처리가 불가능해진다. 이 문제를 해결하는 아키텍처가 바로 Supervisor 패턴이다. 모든 하위 에이전트들은 서로의 존재를 알 필요가 없다. 이들은 오직 전역 상태(State)에서 자신에게 필요한 입력값만 가져와 작업을 수행하고, 결과물만 다시 State에 던진 뒤 실행을 종료한다. 그리고 에이전트들의 다음 실행 노드를 결정하고 라우팅하는 모든 제어권은 중앙의 Supervisor가 전담한다.

Supervisor 패턴이 제공하는 통제력의 이점은 명확하다.

1) 제어 로직과 실행 로직의 완전한 분리

Critic 에이전트는 품질 평가만 담당할 뿐, 시스템의 흐름을 바꾸는 라우팅 코드를 내포하지 않는다. Critic이 내린 판정 결과(critique_decision)가 State에 저장되면, 규칙 기반으로 설계된 Supervisor가 Decision Policy(의사결정 정책서)에 맞춰 물리적인 조건 분기를 실행한다. AI의 모호한 판단에 시스템 흐름 제어를 맡기지 않고, 개발자가 작성한 명확한 소스코드 라인 위에서 흐름을 제어하기 때문에 시스템 가시성이 극대화된다.

2) 비용 방어를 위한 루프 통제 (max_iterations)

비결정론적인 LLM 특성상 Planner와 Critic 사이에 갇혀 무한히 수정을 반복하는 루프가 발생할 수 있다. 이는 상용 서비스에서 심각한 API 비용 폭증의 원인이 된다. Supervisor는 중앙에서 반복 횟수(iteration)라는 상태 값을 직접 카운트하고 관리한다. Critic이 아무리 거절 판정을 내렸더라도, Supervisor 단에서 사전에 설정된 최대 허용 횟수(max_iterations)에 도달했다고 판단하면 재계획을 차단하고 현재까지의 결과물만 들고 프로세스를 강제 종료(END) 시킬 수 있는 강력한 브레이크 역할을 수행한다.

3.4. 통제 가능한 아키텍처가 주는 확신

아이디어를 섹션별로 분리하고 부분적인 기능을 결합해 나가던 나의 개발 방식이, Supervisor라는 명확한 조정자와 상태 중심의 통제 구조를 만나면서 비로소 상용 수준의 AI 에이전트 아키텍처로 완성될 수 있음을 배웠다. 각 에이전트의 독립성을 보장하고 중앙에서 규칙 기반으로 흐름을 장악하는 이 아키텍처는 시스템이 복잡해질수록 진가를 발휘할 것이라고 생각이 들었다. 이러한 대규모 시스템 통제 기법을 깊이 있게 학습하면서, 자연스럽게 내가 프로젝트를 진행하면서 관심 있게 바라보던 구체적인 엔지니어링 도메인에 이 아키텍처를 대입해 보게 되었다. 특히 수많은 회로와 커넥터, 배선 지침이 복잡하게 얽혀 있어 엄격한 규칙과 품질 검증이 필수적인 하네스 엔지니어링 분야가 떠올랐다. 방대한 하네스 설계 표준 문서를 분석하고, 사양에 맞춰 회로 배치를 계획하며, 설계 결함을 검증하는 일련의 과정을 오늘 배운 Planner, Executor, Critic 삼각 편대와 Supervisor 패턴으로 구조화한다면 대단히 강력한 자동화 시스템을 만들 수 있겠다는 생각이 들었다.

참고/출처 https://medium.com/@servifyspheresolutions/planner-executor-critic-engineering-reliable-ai-agents-4eed3b5ddb54 https://dl-pkw.tistory.com/entry/8-2-%EC%97%AD%ED%95%A0-%EB%B6%84%EB%A6%AC-Planner-Worker-Critic https://breyta.ai/blog/ai-agent-architecture-patterns

4. 시스템의 안전장치를 확보하는 인간 개입(Human-In-The-Loop) 설계

구조적으로 완벽해 보이는 에이전트 아키텍처를 설계하고 나면, 모든 것을 AI에게 맡겨두고 알아서 완벽하게 처리해 주기를 기대하게 된다. 하지만 LLM의 본질적인 한계인 환각과 비결정성을 완벽하게 제거할 수 없는 한, 100% 완전 자동화는 비즈니스 환경에서는 폭탄과 같다. 특히 금융 거래, 법률 계약서 검토, 혹은 내가 관심을 두고 있는 하네스 엔지니어링의 배선 설계 사양 검증처럼 작은 오류 하나가 막대한 자산 손실이나 안전사고로 직결되는 고위험 도메인에서는 더욱 그렇다. 이러한 문제를 해결하기 위해 시스템 내부의 가장 강력한 방어선이자 통제 장치로서 사람을 워크플로우에 명시적으로 포함하는 HITL(Human-In-The-Loop) 설계에 대해 깊이 있게 학습했다.

4.1. 완전 자동화의 환상과 HITL의 본질

처음 에이전트 시스템을 접했을 때는 인간의 개입이 없는 완전한 자동화만이 정답이라고 생각했다. 사람이 일일이 확인해야 한다면 인공지능을 도입하는 의미가 퇴색되는 것이 아닌가 하는 의문이 들었기 때문이다. 하지만 상용 수준의 LLMOps를 구축할 때 HITL은 자동화의 실패를 의미하는 것이 아니라, 오히려 시스템의 신뢰성을 완성하는 컴포넌트임을 배웠다. 비즈니스 프로세스에서 AI는 매우 빠르고 효율적으로 방대한 데이터를 처리하는 유능한 일꾼이지만, 최종적인 법적 책임이나 안전성에 대한 담보는 오직 인간만이 할 수 있다. 따라서 HITL은 시스템의 실행 과정 중에 사람이 검토하고 승인하거나 수정할 수 있는 연결 고리를 의도적으로 배치하는 설계 기법이다. 이를 통해 AI가 가진 한계를 인간의 판단력으로 보완하며, 동시에 인간이 모든 과정을 처음부터 끝까지 수작업으로 처리하던 비효율을 획기적으로 줄이는 균형점을 찾을 수 있다.

4.2. 사전 통제(Proactive Control) 계층으로서의 HITL

인간의 개입을 설계할 때 가장 주의해야 할 점은 문제의 발생 시점이다. 많은 개발자가 저지르는 실수는 시스템이 예측하지 못한 에러를 뱉으며 멈추거나, 이미 잘못된 결과물이 고객에게 발송된 이후에야 사람이 개입하는 사후 조치(Reactive) 방식으로 시스템을 만드는 것이다. LLMOps에서 다루는 HITL은 철저하게 사전 통제(Proactive Control) 계층으로 설계되어야 한다.

• Reactive (사후 조치): 에이전트가 환각 기반의 잘못된 분석 결과를 담아 이메일을 발송한 뒤, 고객의 항의를 받고 관리자가 로그를 보며 수동으로 수습하는 방식이다. 이미 비즈니스적 신뢰가 무너진 상태이므로 시스템으로서 가치가 떨어진다.
• Proactive (사전 통제): 에이전트가 분석 결과를 완성하더라도 즉시 발송 노드로 진입하지 못하도록 워크플로우 중간에 의도적인 '대기 상태(Pause)' 노드를 설계한다. 관리자가 해당 결과를 화면에서 검토하고 승인 버튼을 누르기 전까지는 다음 프로세스로 절대 진행되지 않도록 기술적 안전장치를 걸어두는 방식이다. 이러한 사전 통제 구조를 통해 AI가 무한 루프에 빠져 API 비용을 날리거나, 치명적인 결함이 외부로 노출되는 리스크를 완벽하게 차단할 수 있다.

4.3. Supervisor 패턴 내에서의 HITL 구현 원칙

인간 개입을 시스템에 녹여낼 때, 아무렇게나 사람을 호출하도록 코드를 짜면 아키텍처가 순식간에 붕괴된다. 강의를 통해 배운 Supervisor 패턴 기반의 HITL 구현에는 두 가지 철저한 엔지니어링 원칙이 존재했다.

1) 하위 Worker 에이전트는 절대로 사람을 직접 호출하지 않는다

만약 정보 추출을 담당하는 Executor1이나 요약을 담당하는 Executor2가 작업을 하다가 "이 부분은 모호하니 사람이 확인해 주세요"라고 직접 인간 개입 노드로 흐름을 넘기게 되면, 전체 워크플로우의 제어권이 사방으로 분산된다. 에이전트가 늘어날수록 어떤 노드에서 사람을 호출했는지 추적하기 어려워지며, 중앙의 의사결정 정책이 무력화된다. 따라서 Worker 에이전트들은 오직 자신이 맡은 기능만 수행하고 결과물과 상태를 공유 객체(State)에 기록한 뒤 종료되어야 한다. 상태를 읽은 중앙의 Supervisor만이 현재 에이전트의 수행 결과나 카운트된 리스크 점수를 기반으로 HITL 노드(human_review)를 트리거할 수 있어야 한다. 제어권을 중앙 집권식으로 유지해야만 일관된 운영 정책을 적용할 수 있다.

2) 인간을 비결정론적인 외부 노드로 취급한다

시스템 아키텍처 관점에서 볼 때, 인간은 일반적인 파이썬 함수처럼 즉각적인 응답을 주는 존재가 아니다. 검토하는 데 수 분에서 수 시간이 걸릴 수도 있고, 한 사람의 인건비가 소요되므로 비용도 높다. 또한 사람마다 판단 기준이 조금씩 다를 수 있으므로 비결정론적인 특성을 지닌다. 즉, 시스템 입장에서는 인간 역시 LLM 모델이나 외부의 거대한 검색 API를 호출하는 것과 다름없는 '외부 도구 혹은 독립된 노드'로 취급해야 한다. 그래프 상에 인간 개입 노드를 명시적으로 배치하고, 사람이 응답을 줄 때까지 상태를 안전하게 보존하며 대기할 수 있는 구조가 뒷받침되어야 상용 서비스 환경에서 시스템이 멈추지 않고 매끄럽게 구동될 수 있다.

4.4. 인간 개입 이후의 사후 흐름 처리

인간 개입 노드가 트리거되어 관리자가 에이전트의 중간 결과물을 검토한 후, 내릴 수 있는 의사결정의 유형은 명확하게 구조화되어야 한다. 시스템은 사람이 입력한 피드백에 따라 이후의 워크플로우 흐름을 크게 세 가지 분기로 나누어 처리하도록 설계한다.

1) APPROVE (승인)

에이전트가 수행한 정보 추출이나 요약의 품질이 완벽하다고 판단하여 승인하는 경우다. 이 조건이 만족되면 Supervisor는 해당 상태를 확인하고 프로세스를 성공적으로 종료하거나, 실제 메일 발송이나 데이터베이스 반영과 같은 다음 후속 노드로 흐름을 이어가게 만든다.

2) ABORT (중단)

에이전트가 도저히 해결할 수 없는 잘못된 방향으로 계획을 세웠거나, 분석 대상 문서 자체가 훼손되어 있어서 더 이상 프로세스를 진행하는 것이 의미가 없다고 판단하는 경우다. 이 경우 추가적인 API 비용 낭비를 막기 위해 전체 워크플로우를 즉시 강제 종료 시키고 시스템을 초기화한다.

3) REVISE (수정 및 재계획)

결과물에 일부 누락이나 오류가 있어 보정이 필요한 경우다. 이때 인간은 단순히 거절 버튼만 누르는 것이 아니라, 무엇이 잘못되었는지 구체적인 가이드라인이나 지침을 텍스트 형태의 피드백으로 작성하여 공유 상태에 저장한다.

Supervisor는 이 REVISE 신호와 함께 저장된 피드백을 확인하면, 시스템의 제어권을 다시 맨 앞단의 Planner Agent로 돌려보낸다. Planner는 사용자의 최초 요청뿐만 아니라, 방금 전 인간이 남긴 구체적인 피드백(human_feedback)까지 컨텍스트로 함께 입력받는다. "인간 검토자가 이 지점의 수치 오류를 지적했으니, 이를 반영하여 실행 계획을 수정하자"라며 계획을 전면 보정하는 재계획을 수행하게 된다. 인간과 AI가 협력하는 유기적인 피드백 루프가 완성되는 지점이다.

4.5. 인간과 AI의 협업 체계가 주는 안정감

HITL 설계를 배우면서 AI 에이전트 시스템을 대하는 시야가 넓어졌다. 모든 것을 인공지능이 완벽하게 처리하도록 프롬프트를 깎는 데 시간을 허비하는 것보다, 중요한 길목에 사람이 검토할 수 있는 안전장치를 아키텍처적으로 배치하는 것이 훨씬 현명하고 강력한 통제 방법이라는 것을 배웠다. HITL 설계를 직접 프로젝트에도 사용해보자고..

참고/출처 https://macgence.com/blog/hitl-human-in-the-loop/ https://wikidocs.net/316360 https://www.ibm.com/kr-ko/think/topics/human-in-the-loop

5. 시점 관리와 실행 관측

5.1. 시점 관리

에이전트 시스템이 구동될 때 가장 곤란한 상황은, 총 10단계로 이루어진 복잡한 파이프라인에서 8번째 단계에 치명적인 오류가 발생했을 때다. 일반적인 스크립트라면 처음부터 다시 실행하면 되지만, 토큰당 과금이 이루어지고 결과가 매번 달라지는 LLM 환경에서는 처음부터 재실행하는 것이 비용 낭비이자 또 다른 오류를 낳을 수 있다. 이를 해결하기 위해 프레임워크 내부에 존재하는 것이 바로 전역 상태의 변화 과정을 매 노드마다 사진 찍듯 저장해 두는 스냅샷(Snapshot) 기능이다.

1) MemorySaver와 체크포인트 이력 추적

그래프 컴파일 단계에서 MemorySaver와 같은 체크포인터를 연결해 두면, 에이전트가 한 노드를 통과할 때마다 당시의 모든 변수 상태(messages, extracted_info, current_step_index 등)가 고유한 ID(checkpoint_id)와 함께 저장된다. 문제가 발생했을 때 개발자는 graph.get_state_history() 메서드를 호출하여 시간 역순으로 상태 변화 이력을 모두 꺼내볼 수 있다. "아, Executor2가 요약을 수행할 때 extracted_info 값이 이미 빈 문자열로 넘어왔구나" 하는 식으로 에러의 근본 원인이 발생한 정확한 노드와 시점을 특정할 수 있게 된다.

2) 타임 트래블 (Time Travel)과 부분 재실행

스냅샷의 진정한 가치는 단순히 기록을 보는 것을 넘어, 과거의 특정 시점으로 시스템의 상태를 되돌려 거기서부터 다시 실행하는 타임 트래블에 있다. 에러가 발생하기 직전의 정상적인 checkpoint_id를 찾아 설정(Config) 객체에 담아 그래프를 호출(graph.invoke(None, config))하면, 시스템은 처음부터 API를 호출하지 않고 과거의 상태를 그대로 이어받아 실패한 노드부터 재실행을 시작한다. 프롬프트를 일부 수정하거나 버그를 고친 뒤 곧바로 해당 시점부터 테스트해 볼 수 있어, 디버깅 시간과 API 비용을 획기적으로 절약할 수 있다.

5.2. 실행 관측

상태 데이터가 '무엇'이 변했는지 알려준다면, 실행 관측은 시스템이 '어떻게' 실행되었고 자원을 '얼마나' 소모했는지 알려주는 모니터링 체계다. LangSmith 같은 전문 관측 플랫폼을 연동하여 시스템의 성능을 계측한다.

1) Run Tree와 Waterfall 시각화

코드에 환경 변수 단 한 줄(LANGSMITH_TRACING=true)만 추가하면, 런타임에 발생하는 모든 LLM 호출, 도구사용, 에이전트 라우팅 내역이 중앙 서버로 전송된다. 플랫폼 대시보드에서는 이 복잡한 실행 과정을 트리 구조와 시간 축 기반의 Waterfall 차트로 시각화하여 보여준다. 어떤 에이전트가 다른 에이전트를 호출했는지, 그 과정에서 주고받은 프롬프트의 원문은 무엇인지 블랙박스 같았던 내부가 투명하게 드러난다.

2) 지연 시간(Latency) 및 비용(Cost) 병목 진단

Waterfall 뷰를 보면 전체 응답 시간이 30초 걸렸을 때, 어느 노드에서 가장 오랜 시간(예: 25초)이 정체되었는지 한눈에 파악할 수 있다. 특정 검색 도구의 API 지연인지, 특정 프롬프트가 너무 길어서 LLM 응답이 늦어지는 것인지 병목 구간을 정확히 진단 가능하다. 또한 각 단계별로 입력 토큰과 출력 토큰이 얼마나 소모되었고, 이것이 실제 달러($) 비용으로 얼마인지 실시간으로 계산되어 나타난다. 불필요하게 토큰을 많이 소모하는 프롬프트를 최적화하는 기준점이 된다.

찰고/출처 https://oidea.tistory.com/entry/AI-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8-%EC%9B%8C%ED%81%AC%ED%94%8C%EB%A1%9C-%EC%9A%B4%EC%98%81-%EB%A1%9C%EA%B7%B8-%ED%8F%89%EA%B0%80-%EA%B4%80%EC%B8%A1%EC%84%B1%EC%9D%84-%EC%84%A4%EA%B3%84%ED%95%98%EB%8A%94-%EB%B2%95 https://smith.langchain.com/ https://sudormrf.run/2024/08/17/langsmith_review/ https://wikidocs.net/250954

생각정리

그동안의 나는 AI API를 호출해 원하는 결과물을 빠르게 만들어내는 과정 자체에 만족해왔던 것 같다. 프롬프트를 조금 더 정교하게 다듬고, 모델을 연결해 자동화를 구성하며 “AI로 이런 것도 가능하구나”를 체감했다면, 이번 LLMOps 학습을 통해서는 완전히 다른 관점을 배우게 되었다. 이제는 단순히 모델의 성능을 보는것이 아닌, 비결정론적인 AI를 어떻게 로직 안에서 안정적으로 묶고 통제할 것인가를 고민하는, 조금은 시스템 아키텍트에 가까운 시야를 가지게 된 느낌이다. 글을 정리하면서 가장 크게 와닿았던 문장은 결국 이것이었다.

“진정한 AI 엔지니어링은 완벽한 AI를 만드는 것이 아니라, 불완전한 AI를 안전하게 제어하는 시스템을 만드는 것이다.”

처음에는 왜 이렇게까지 복잡하게 설계해야 하는지 이해하지 못했다. Agent 역할 정의서, Workflow 명세서, State 정의서, Decision Policy, Prompt 명세서까지 이어지는 5대 설계 문서는 단순히 개발 속도를 늦추는 귀찮은 작업처럼 느껴졌고, Planner-Executor-Critic 구조나 Supervisor 패턴 역시 “굳이 이렇게까지 역할을 잘게 나눠야 하나?” 싶은 생각이 들었다. 하지만 직접 멀티 에이전트 흐름을 구성하고 Trace를 따라가 보니, 이런 구조들이 단순한 형식이 아니라 통제 불가능한 LLM을 상용 수준의 신뢰성을 가진 시스템으로 바꾸기 위한 엔지니어링 장치라는 사실을 배운거같다.

특히 LangSmith 기반의 실행 관측을 경험하면서 시야가 크게 넓어졌다. 예전에는 에이전트가 실패하면 단순히 “모델이 이상하게 답했네” 정도로 넘어갔지만, 이제는 어떤 노드에서 프롬프트가 비대해졌는지, 어느 시점에서 토큰 사용량이 급증했는지, 어떤 에이전트가 잘못된 상태를 전달했는지를 Waterfall 형태로 추적하며 병목과 오류를 분석할 수 있게 되었다. Planner가 잘못된 실행 계획을 세운 순간부터, Executor가 불완전한 정보를 추출하고, Critic이 왜 특정 결과를 Reject 했는지까지 전부 Trace 상에서 이어지는 흐름으로 확인할 수 있었다. LLM 시스템을 더 이상 “감과 반복”으로 디버깅하는 것이 아니라, 로그와 상태 기반으로 분석하는 소프트웨어 엔지니어링의 영역으로 다루게 된 것이다.

또 하나 인상 깊었던 부분은 Snapshot과 Time Travel 기반의 상태 복구였다. 기존에는 에이전트 시스템이 중간에 실패하면 처음부터 다시 실행하는 경우가 많았지만, 이제는 특정 checkpoint 시점으로 되돌아가 실패한 노드만 재실행하며 디버깅할 수 있다는 점이 굉장히 강력하게 느껴졌다. 특히 토큰 비용이 곧 운영 비용으로 이어지는 LLM 환경에서는 단순한 편의 기능이 아니라, 실제 서비스 운영을 위한 안전장치에 가깝다고 생각했다. 이러한 경험들을 하면서 자연스럽게 내가 관심있던 하네스 엔지니어링(Harness Engineering) 분야와 연결 지어 보게 되었다. 최근 AI 분야에서 말하는 하네스 엔지니어링은 단순히 더 뛰어난 LLM 모델을 만드는 기술이 아니다. 오히려 비결정론적인 AI가 실제 업무 환경 안에서 안정적으로 동작할 수 있도록, 주변의 시스템과 실행 환경, 제약 조건, 평가 체계를 설계하는 엔지니어링에 가깝다.

즉, 프롬프트 하나를 잘 작성하는 수준을 넘어:

어떤 컨텍스트(Context)를 제공할 것인지, 어떤 도구(Tool)를 어디까지 사용할 수 있게 허용할 것인지, 어떤 조건에서 실행을 중단하거나 재시도할 것인지, 결과를 어떤 방식으로 검증(Evaluation)할 것인지, 문제가 발생했을 때 어떻게 추적(Trace)하고 복구할 것인지

까지 전부 포함하여, AI가 “통제 가능한 상태” 안에서 동작하도록 만드는 것이다.

강의를 들으며 배운 LLMOps의 구조들이 하네스 엔지니어링의 맞닿아 있다. 처음에는 단순히 복잡해 보였던 Planner-Executor-Critic 구조, Supervisor 패턴, HITL, State 관리, Snapshot 기반 복구, Trace 관측 같은 요소들이 사실은 모두 AI를 안전하게 통제하기 위한 장치였던 것이다. 특히 LangSmith 기반의 Trace 관측은 내가 생각하던 하네스 엔지니어링의 핵심과 굉장히 잘 연결되었다. 기존에는 에이전트가 잘못된 결과를 생성하면 단순히 “모델 성능이 아쉽다” 정도로 받아들였지만, 이제는

어떤 프롬프트에서 토큰이 과도하게 사용되었는지, 어떤 Agent가 잘못된 상태(State)를 전달했는지, 어느 시점에서 Decision Policy가 잘못된 분기를 탔는지, 어떤 이유로 Critic이 Reject 판정을 내렸는지

를 Trace 기반으로 전부 추적할 수 있게 되었다. 결국 중요한 것은 “AI가 얼마나 똑똑한가”가 아니라, AI가 실수하더라도 시스템 전체는 무너지지 않도록 만드는 구조를 설계하는 것이라고 느꼈다. 앞으로는 단순히 모델 성능이나 프롬프트 최적화만 바라보는 것이 아니라, AI가 실제 서비스 환경 안에서 안정적으로 동작할 수 있도록

실행 환경을 구조화하고, 제약 조건을 설계하고, 평가 루프를 만들고, 상태를 추적하며, 인간 개입(HITL)을 연결하는

이러한 하네스 엔지니어링 관점의 AI 시스템 설계를 더 깊이 있게 공부해보고 싶다. 아직은 배워야 할 것도 많고, 직접 구현해보며 부딪혀야 할 문제들도 많다. 하지만 이번 학습을 통해 단순히 “AI를 잘 사용하는 개발자”도 좋지만, AI를 안전하게 통제하고 운영할 수 있는 시스템을 설계하는 사람에 방향성을 조금이나마 잡게 된 것 같다. 6주차 정리를 마무리한다.

기술에 발전이 무섭습니다.. 새로 나오는 기능, 서비스, 모델들 잘 활용하고 찍먹 해봅시다.

Github Private

이번 글에서는 2차 미니 프로젝트로 진행한 AI 강사 Agent 구축 과정에 대해 정리해보려고 한다. PPT에 내용을 슬라이드별로 데이터를 분석하고 이를 음성 및 영상과 연결하여 하나의 완성된 강의 콘텐츠를 만들어내는 에이전트를 개발하는 것이 이번 프로젝트의 핵심이었다. 나는 이 과정에서 각 기능을 담당하는 노드들을 설계하고 이들을 연결하는 그래프 관리자 역할을 맡았다.

1. 프로젝트의 핵심 흐름

이번 프로젝트의 목표는 영상 제작 시간을 단축하고 품질을 균일화하여 강의 자료 학습의 효율성을 극대화하는 것이었다. 우리 조는 단순히 텍스트를 읽어주는 기능을 넘어, 교안의 전체 맥락을 이해하고 학습을 돕는 부가 콘텐츠(퀴즈, 만화 등)까지 생성하는 에이전트를 설계했다.

전체 워크플로우는 다음과 같은 구조로 진행된다.

• PPT 정보 분해: 슬라이드별로 제목, 본문, 이미지, 표를 추출하여 데이터화한다.
• 강의 요약 및 맥락 정의: 모든 슬라이드를 처리하기 전, 전체 내용을 훑어 강의의 대주제와 흐름을 정의한다. 이는 나중에 페이지별 대본을 쓸 때 일관성을 유지하는 기준이 된다.
• 콘텐츠 제작 루프: 각 슬라이드별로 외부 검색을 통해 내용을 보충하고, 스크립트와 퀴즈를 생성하며 음성(TTS) 및 영상 클립을 만든다.
• 최종 합성: 생성된 만화, 아웃트로, 슬라이드 영상들을 하나로 합치고 자막을 입혀 최종 결과물을 완성한다.

2. 핵심 노드 구성 및 역할

우리 조가 설계한 그래프의 각 노드는 독립적인 기능을 수행하면서도 State를 통해 긴밀하게 데이터를 주고받는다. 코드 로직을 바탕으로 정리한 주요 노드의 역할은 다음과 같다.

• parse_all: 프로젝트의 시작점으로, PPTX 파일에서 텍스트, 표, 이미지 등을 완벽하게 추출한다.
• gen_overall_script: 추출된 모든 정보를 토대로 강의 전체의 초안 스크립트를 작성한다.
• search_index: 슬라이드 제목을 키워드로 외부 검색을 수행한다. 교안에 담긴 내용 외에도 최신 정보나 보충 설명이 필요한 부분을 채워줌으로써 에이전트의 지식울 확장한다.
• gen_content & gen_script: 검색 결과와 교안 내용을 결합하여 페이지별 핵심 내용을 구성하고, 이를 바탕으로 실제 강사가 강의하는 듯한 자연스러운 대본을 작성한다. 이때 앞서 만든 overall_script를 참조하여 전체적인 톤앤매너를 유지한다.
• gen_quiz: 작성된 스크립트를 바탕으로 학습자의 이해를 돕는 퀴즈를 생성한다.
• gen_comic & gen_outro: 강의 요약본을 바탕으로 4컷 만화를 생성하고 아웃트로 영상을 만든다.
• tts & gen_video: OpenAI의 TTS 엔진을 활용해 대본을 음성으로 변환하고, 슬라이드 이미지와 결합하여 개별 비디오 클립을 생성한다.
• update_index & node_check_finish: 조건부 엣지의 핵심이다. 모든 슬라이드가 처리될 때까지 인덱스를 업데이트하며 루프를 제어하고, 모든 작업이 완료되면 최종 영상 합성을 위한 단계로 흐름을 넘긴다.
• concat_videos & gen_subtitles_video: 흩어져 있던 영상 클립들과 만화 영상을 하나로 통합하고, Whisper 모델을 사용하여 자동 자막을 입히며 프로세스를 종료한다.

3. 설계한 그래프 구조 및 핵심 코드

그래프 관리자 역할을 맡고 내가 신경 쓴 부분은 비동기적인 작업 분기와 루프 제어의 정확성이었다. 아래는 LangGraph를 활용해 구축한 우리 조의 에이전트 구조이다.

from langgraph.graph import StateGraph, END

# 그래프 구축
w = StateGraph(State)

# 노드 추가
w.add_node("parse_all", node_parse_all)
w.add_node("gen_overall_script", node_gen_overall_script)
w.add_node('gen_comic', node_gen_comic)
w.add_node("gen_outro", node_gen_outro)
w.add_node("search_index", node_search_index)
w.add_node("gen_content", node_gen_content)
w.add_node("gen_script", node_gen_script)
w.add_node("tts", node_tts)
w.add_node("gen_video", node_gen_video)
w.add_node("update_index", node_update_slide_index)
w.add_node("concat_videos", node_concat_videos)
w.add_node("gen_quiz", node_gen_quiz)
w.add_node("gen_subtitles_video", node_gen_subtitles_video)

# 엣지 및 흐름 설계
w.set_entry_point("parse_all")
w.add_edge("parse_all", "gen_overall_script")

# 분기 1: 만화 및 아웃트로 생성
w.add_edge("gen_overall_script", "gen_comic")
w.add_edge("gen_comic", "gen_outro")
w.add_edge("gen_outro", "concat_videos")

# 분기 2: 슬라이드별 콘텐츠 제작 루프
w.add_edge("gen_overall_script", "search_index")
w.add_edge("search_index", "gen_content")
w.add_edge("gen_content", "gen_script")
w.add_edge("gen_script", "tts")
w.add_edge("gen_script", "gen_quiz")
w.add_edge("gen_quiz", "gen_script")
w.add_edge("tts", "gen_video")
w.add_edge("gen_video", "update_index")

# 조건부 분기: 모든 슬라이드 완료 여부 체크
w.add_conditional_edges(
    "update_index",
    node_check_finish,
    {
        "continue": "search_index",
        "end": "concat_videos"
    }
)

w.add_edge("concat_videos", "gen_subtitles_video")
w.add_edge("gen_subtitles_video", END)

app = w.compile()

4. 프로젝트를 통해 배운 점

이번 프로젝트는 단순히 기술적인 구현보다는 에이전트 시스템을 설계하고 협업하는 경험을 한거같다. 첫째로, 상태(State) 관리의 중요성을 깨달았다. LangGraph 내에서 데이터가 노드 사이를 흐를 때, 어떤 형식으로 저장되고 업데이트되는지 명확히 정의하지 않으면 전체 워크플로우가 꼬이기 쉽다. 특히 여러 팀원이 만든 노드를 통합할 때 공통된 데이터 규격을 유지하는 인터페이스 설계 능력이 필수적임을 느꼇다. 둘째로, 맥락(Context) 유지의 힘이다. 초기 모델에서는 슬라이드별로 대본을 따로 쓰다 보니 내용이 겹치거나 말투가 달라지는 문제가 있었다. 이를 해결하기 위해 Summary Context를 공유하도록 설계함으로써 전체 영상의 일관성을 확보할 수 있었다. 마지막으로, 협업의 가치이다. 팀원들이 각자의 노드에 역할을 맡아 개발을 진행해 만든 노드들을 최적의 경로로 엮어냈을 때, 혼자서라면 진행하기 힘들었던 부분들도 완성되는 과정에서 큰 보람을 느꼈다.

생각하기

마감시간 전까지 프로젝트를 무사히 제출하고, 다른 조들의 최종 발표를 들으며 참 많은 생각이 들었다. 프로젝트 초기 기획 단계부터 '이 에이전트를 누가, 어떻게 사용할 것인가'에 대한 타겟 유저를 명확히 정의하고 출발한 팀들도 있었고, 퀴즈나 만화 같은 보편적인 기능을 넘어 노드 자체에 참신한 아이디어를 녹여낸 팀들도 보였다. 우리 조의 경우 R&R을 나누고 각자 맡은 기능 구현에 몰두하느라, 프로젝트의 본질적인 주제나 기획의 방향성에 대해 깊게 토론할 시간이 부족했다. 서로 의견을 나누며 전체적인 그림을 다듬기보다 각자의 역할에만 집중했던 것 같아 결과물에 아쉽다.. 아쉬운점도 남지만 오히려 시스템을 설계해 보면서, 아키텍처 관점에서 시스템을 더 고도화하고 싶은 생각이 들었다. 이번 경험을 발판 삼아 앞으로 다음 두 가지 주제를 더 깊이 파고들어 보려 한다.

1. State 최적화 및 메모리 관리

현재 구조는 추출된 텍스트, 요약본, 그리고 파일 경로들이 모두 하나의 State 딕셔너리에 담겨 노드 사이를 이동한다. 작은 규모의 프로젝트에서는 당장 문제가 없지만, 처리해야 할 슬라이드가 많아지거나 데이터의 크기가 커지면 메모리 효율성이 크게 떨어질 수밖에 없다. (우리는 3p 슬라이드만 실험을 했기때문에 후에 진행 해봐야겠다.) 이를 해결하기 위해 매번 전체 데이터를 복사해서 넘기는 대신, 필요한 정보만 선별하여 전달하는 방식을 고민해야 한다. 더 나아가 메타데이터(ID) 식별자만 State에 남기고, 실제 무거운 데이터는 외부 DB와 연동하여 필요할 때만 불러오는 효율적인 구조를 설계해봐야겠다.

2. RAG 고도화

현재 우리 에이전트는 부족한 내용을 채우기 위해 단순한 웹 검색 노드(TavilySearch)를 활용하고 있다. 하지만 타겟 사용자가 명확하게 정해진 교육용 에이전트로 거듭나려면 이를 넘어 벡터 데이터베이스를 활용해야 한다. 사내 문서나 전공 서적, 특정 도메인의 전문 지식을 청크 단위로 벡터화하여 저장해 두고, 스크립트를 작성할 때 이를 정확하게 검색해오는 고급 RAG 파이프라인으로 발전시키고 싶다. (공모전에서 사용할 수 있다면 해봐야겠다.)

02miniproject, 2번째 미니로젝트 회고록을 마무리한다.

협업은 언제나 재밌다.

이번 글에서는 멀티 Agent와 2차 미니 프로젝트를 진행하며 느낀 점에 대해 이야기해보려고 한다. 4주차와 마찬가지로 Agent 관련 내용의 범위가 방대하다.. 그렇기에 이번에도 내용을 두 편으로 나누어 작성하려고 한다. 먼저 5주차-1에서는 Multi-Agent에 대해 다루고, 5주차-2 회고록에서는 미니 프로젝트 후기와 함께 프로젝트를 진행하며 배운 점/나아간 점들을 정리해보려 한다. 특히 이번 02 Mini Project에서는 강사님께서 다양한 실습 자료를 제공해주셨고, 01 Mini Project와 함께했던 팀원들을 떠나 새로운 팀원들과 함께 프로젝트를 진행하게 되었다. 새로운 팀원들과 협업하며 느꼈던 점, 함께 공부하고 고민했던 부분을 기록하려고 한다. 먼저 Multi-Agent내용 복습을 해보자

1.상태(State) 설계

지난 4주차에서는 단일 에이전트(Single Agent)의 기초와 RAG를 통한 지식 확장을 학습했다. 하지만 현실의 문제는 단일 에이전트가 처리하기에는 너무 복잡하거나, 여러 단계의 전문적인 지식을 동시에 요구하는 경우가 많다. 이번 글에서는 이러한 한계를 극복하기 위한 Multi-Agent 시스템의 필요성과, 상태(State) 설계에 대해 복습 진행!

1.1. Single Agent의 한계와 Multi-Agent의 등장

하나의 에이전트가 모든 일을 처리하는 방식은 마치 한 명의 박사님/교수님(?)이 기획, 디자인, 코딩, 테스트를 모두 혼자 하는 것과 같다. 초기에는 효율적일 수 있지만, 프로젝트가 커지면 다음과 같은 문제가 발생할 수 있다.

• 복잡도 증가: 에이전트에게 주어지는 프롬프트와 도구가 너무 많아지면 모델이 집중력을 잃고 엉뚱한 결과를 내놓을 확률이 높음
• 컨텍스트 윈도우의 압박: 대화가 길어질수록 모든 이력을 하나의 에이전트가 들고 있기에는 토큰 비용이 급증하고 핵심 정보를 놓치기 쉬움
• 전문성 부족: 특정 분야(예: 코드 분석 vs 데이터 시각화)에 특화된 프롬프트를 하나로 섞으면 성능이 저하

이러한 문제를 해결하기 위해 Multi-Agent 방식을 사용. 이는 각기 다른 역할(Role)과 전문 도구를 가진 여러 에이전트가 협업하여 복잡한 목표를 달성하는 구조다.

1.2. Multi-Agent의 핵심 이점

Multi-Agent 시스템으로 전환한다면?

• 관심사 분리 (Separation of Concerns): 각 에이전트는 자신에게 할당된 작은 문제에만 집중하므로 정확도가 상승
• 유연한 확장성: 새로운 기능이 필요할 때 전체 시스템을 수정하는 대신, 특정 역할을 수행하는 에이전트 하나/여러개를 추가하면 됨
• 디버깅 용이성: 문제가 발생했을 때 어떤 단계, 어떤 에이전트에서 오류가 났는지 추적하기 쉬움

1.3. 상태(State) 설계

Multi-Agent 시스템에서 가장 중요한 것은 "에이전트들이 정보를 어떻게 주고받는가?"이다. LangGraph에서는 이를 State(상태) 객체를 통해 해결

상태는 에이전트들 사이를 흐르는 '공유 메모리' 단순히 메시지 이력을 쌓는 것을 넘어, 시스템이 필요로 하는 특정 데이터(예: 분석 결과, 사용자 정보, 현재 단계 등)를 구조화하여 정의한다.

효과적인 State 설계 전략

1. 공통 스키마 정의: 모든 에이전트가 이해할 수 있는 메시지 리스트(Annotated[list, add_messages])를 기본으로 포함
2. 전용 필드 활용: 루프를 돌거나 특정 조건을 판단할 때 필요한 플래그 변수나, 중간 결과물을 저장할 필드를 추가
3. 독립성 유지: 각 에이전트는 전체 State 중 자신이 필요한 부분만 읽고, 작업이 끝나면 업데이트가 필요한 부분만 반환하여 상태를 갱신

참고/출처 https://www.hanbit.co.kr/channel/view.html?cmscode=CMS8333330411 https://cloud.google.com/discover/what-is-a-multi-agent-system?hl=ko https://wikidocs.net/331297

2. Router 패턴

2.1. Router 패턴이란?

사용자의 요청이나 현재 상태를 분석해서, 가장 적합한 에이전트에게 작업을 할당하는 아키텍처 패턴이다. (콜센터의 ARS 안내원 같은 역할)

2.2. Router 패턴의 작동 방식

단순히 질문에 바로 대답하는 것이 아니라, "이 질문은 어떤 전문가가 처리하는 게 제일 좋을까?"를 먼저 고민(분류)하는 것이 핵심이다.

• 의도 파악 (Intent Classification): Router 역할을 맡은 LLM이 사용자의 입력값을 읽고 핵심 의도를 분류함
• 분기 처리 (Routing): 분류된 결과(예: 코드 질문, 디자인 질문, 일반 질문)에 따라 특정 에이전트로 작업 흐름을 넘김
• 전문가 처리: 작업을 전달받은 전문 에이전트가 자신의 특화된 프롬프트와 도구(Tool)를 사용해 정확한 답변을 생성

2.3. LangGraph에서의 구현 포인트

LangGraph로 Router 패턴을 구현할 때 핵심은 조건부 엣지(Conditional Edge)다.

1. 라우터(Router) 함수/노드 생성: 현재 State(상태)를 읽어보고 조건에 따라 "Coder_Agent", "Reviewer_Agent" 등의 문자열(결과값)을 뱉어내는 판단 로직을 작성한다.
2. 분기점(Routing) 설정: add_conditional_edges를 사용해 라우터 노드의 판단 결과와 실제 이동할 다음 노드들을 매핑(Mapping)하여 연결해준다.

출처/참고 https://wikidocs.net/318951 https://wikidocs.net/322453 https://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/agentic-ai-patterns/workflow-for-routing.html

3. Supervisor 패턴

3.1. Supervisor 패턴이란?

단어 뜻 그대로 중앙 통제자 역할을 하는 에이전트를 하나 두고, 이 관리자가 여러 에이전트들을 지휘하는 아키텍처다. 어떤 작업을 누가 먼저 할지, 그 다음엔 누구에게 넘길지, 작업이 충분히 완료되었는지(종료할지)를 중앙에서 지속적으로 판단하고 통제한다.

3.2. Router 패턴과의 결정적 차이점

- Router (접수처): "이 질문은 코드 관련이니까 Coder_Agent한테 가!" -> (한 번 분기하면 끝. 단방향)
- Supervisor (프로젝트 매니저): "Search_Agent야, 자료 먼저 찾아와. (결과 확인 후) Planner_Agent야, 찾은 자료 바탕으로 계획서 써봐. (결과 확인 후) 음, 완벽하군. 이제 FINISH!" -> (중앙에서 지속적인 피드백과 반복/루프 통제)

3.3. 작동 방식

강의에서 다룬 '여행 계획 에이전트'를 떠올려 보자. 사용자가 *"부산 2박 3일 가족 여행 코스 짜줘"*라고 요청했을 때 시스템은 다음과 같이 움직인다.

1. 지시: Supervisor가 요청을 분석하고, 먼저 명소 정보가 필요하다고 판단하여 Search_Agent(검색 담당)에게 지시를 내림.
2. 작업 및 보고: Search_Agent가 부산 명소 10곳을 찾아 State(공유 메모리)에 저장하고 Supervisor에게 보고.
3. 다음 지시: Supervisor가 검색된 내용을 확인한 뒤, 이번에는 Planner_Agent(일정 담당)에게 "이 장소들을 모아서 2박 3일 일정을 작성해"라고 지시.
4. 검토 및 종료: 일정이 완성되면 Supervisor가 최종 검토 후 FINISH 상태를 선언하고 사용자에게 결과물 제공.

3.4. LangGraph에서의 구현 포인트

Supervisor 패턴을 구현할 때의 핵심은 '관리자 전용 프롬프트'와 '상태(State)를 통한 대화 기록 공유'다.

1. 팀장(Supervisor) 프롬프트 세팅: "너는 여러 에이전트(Search, Planner 등)를 관리하는 매니저야. 현재 대화 내역(State)을 읽고, 다음으로 어떤 에이전트가 나서야 할지 텍스트로 내뱉어. 만약 사용자 요청이 모두 해결되었다면 'FINISH'를 출력해."라고 명확히 역할을 부여해야 한다.
2. 동적 라우팅 연결: Supervisor 노드의 결과값(다음 작업자 이름 or FINISH)에 따라 그래프의 흐름이 해당 에이전트 노드나 종료(End)로 향하도록 Conditional Edge를 촘촘하게 연결해 준다.

참고/출처 https://wikidocs.net/270690 https://ohyeah12.tistory.com/24 https://github.com/braincrew-lab/langgraph-v1-tutorial

4. Network 패턴

4.1. Network 패턴이란?

Network 패턴은 중앙에 관리자를 두지 않고, 각 에이전트들이 알아서 판단하여 다른 에이전트에게 주도권을 직접 넘겨주는 아키텍처다.

4.2. Network 패턴의 작동 방식

강의에서 다룬 고객센터(CS) 봇에 대해 작동방식을 생각해보자, 예시로 사용자가 *"앱 설치도 안 되고, 결제도 이상해요. 취소해 주세요!"*라고 복합적인 불만을 접수한다.

1. 초기 대응: Main Agent가 불만을 접수하고, 기술적인 문제라고 판단해 Tech_Agent(기술 지원)에게 바통(Handoff)을 넘김.
2. 기술 지원의 판단: Tech_Agent가 앱 설치 문제를 안내함. 그런데 텍스트를 읽어보니 '결제 취소' 요청도 있음. "결제 취소 권한은 나한테 없는데?"라고 스스로 판단.
3. 직접 토스(Handoff): Tech_Agent가 중앙 관리자를 거치지 않고, 알아서 Refund_Agent(환불 지원) 부서로 작업을 바로 넘김.
4. 마무리: Refund_Agent가 결제 취소 절차를 진행하고 사용자에게 답변 제공.

구현 포인트: 에이전트가 다른 에이전트를 호출할 수 있는 도구(Tool)를 가지게 만들어서, 특정 조건이 되면 마치 함수를 실행하듯 다른 에이전트를 호출하도록 프롬프트와 그래프를 구성하는 것이 핵심이다.

참고/출처 https://rudaks.tistory.com/entry/langgraph-Multi-agent-Network https://wikidocs.net/322453

생각정리

이번 추가 과제인 'AI 면접관 Agent 시스템' 실습을 진행하면서 "정말 재밌다, 앞으로 더 깊게 파보고 싶다"라는 생각이 강하게 들었던 시간이었다. 단순히 남의 코드를 따라 치지 않고 직접 아키텍처를 비교하고 상태(State)의 흐름을 파악하면서 개념을 명확하게 나의 것으로 만들었다는 점에서 의미가 크다. 이전까지 나에게 언어 모델은 그저 ‘질문하면 정답을 빠르게 내주는 도구’ 정도에 불과했다. 프롬프트를 얼마나 구체적이고 세세하게 작성하느냐에 따라 결과물이 달라지는, 단순한 입력과 출력의 관계라고만 생각했다. 하지만 이번에 LangGraph를 활용해 Multi-Agent 시스템을 직접 구축해보면서, 언어 모델은 단순한 도구 그 이상이라는 것을 느끼게 된 것 같다. 이력서에서 약점을 찾아내는 Agent, 그 약점을 파고들어 날카로운 면접 질문을 던지는 Agent, 그리고 지원자의 대답을 듣고 다시 꼬리질문을 할지 다음 주제로 넘어갈지 판단하는 Agent까지. 내가 직접 정의한 규칙과 공유 메모리 위에서 여러 특화된 AI들이 데이터를 주고받는 방식이 재밌었다. 결국 앞으로의 AI 개발 생태계에서 가장 중요한 역량은 '어떤 모델의 API를 가져다 쓰느냐'가 아니라, "우리가 풀고자 하는 복잡한 문제를 어떻게 잘게 쪼개어 각 Agent에게 역할을 부여하고, 이들을 어떻게 효율적으로 협업시킬 것인가?"를 설계하는 사람이 성공하지 않을까..? 라는 생각이 든다. 이번 주차의 배움을 발판 삼아, 앞으로는 그저 만들어진 AI 도구를 소비하는 개발자가 아니라, 여러 AI Agent들을 이용해 나만의 강력한 자동화 파이프라인을 구축해내는 여러 경험을 쌓고 싶다. 다음에 하는 미니프로젝트 또는 내가 시간을 내서 토이프로젝트로 만들거나 과거에 만들었던 챗봇 시스템을 수정하면서 여러 경험들을 해보려고 한다. 5주차 공부를 마무리한다.

와... 너 정말, 핵심을 찔렀어.

이번 글에서는 지난 글에 이어, 현재 진행 중인 공모전과 코딩 테스트 스터디에 대해 이야기해보려고 한다. 처음 스터디를 시작할 때는 생각보다 모집이 활발해서 여러 선택지 사이에서 고민이 많았다. 코딩 테스트 스터디(자바/파이썬), 공모전 스터디, 교육 내용을 복습하는 스터디, 정기적으로 카페에서 모여 공부하는 오프라인 스터디 등 다양한 형태가 있었기 때문이다. 이 중에서도 나는 우리 반에서 모집 중인 스터디에 참여하면, 이후 미니 프로젝트나 본 프로젝트를 진행할 때 자연스럽게 팀을 구성하거나 협업하기에 더 좋지 않을까? 라는 생각이였다. 그래서 최종적으로 우리 반에서 진행하는 공모전 스터디와 자바 스터디에 참여하게 되었다.

공모전 스터디

공모전스터디 모임에는 총 8명이 함께하게되었는데 4/4로 쪼개 각 팀원들끼리 상의해 원하는 공모전에 참여하는 형식으로 진행하게 되었다. (팀장 회의는 매주 수요일 18:00~)

우리 조에서는 이번에 2026 AX 아이디어 경진대회에 참여하기로 했다. 생각보다 많은 시상을 이루기도 하며 주제가 다른 공모전에 비해 자유롭게 선정할 수 있다는 점이 컸다. 그리고 우리 팀원 (다애님, 현석님, 현준님) 모두가 개발을 한 경험이 있기 때문에 제품/서비스 에이전트 개발을 나가면 이번에 에이전트를 배우면서 좀 더 발전시킬 수 있다고 생각했었다.

그렇게 처음 시작을 했는데 경진대회 홈페이지를 찾아보니 개발제출물이 모두 앱으로 해야했네? .. (앱개발 경험은 모두가 많지 않았기에..)

이후 활용단계가 아닌 분석 단계로 방향을 바꾸어 지정 과제 분석부터 시작하게 되었다. 우리 스터디는 매주 적게는 2회, 많게는 4회까지 모이며 각자 맡은 파트와 공부한 내용을 공유하고 있다. 그렇게 우리가 이번에 시작하게된 공모전 주제는

데이터 지정 과제(한국수자원공사) - 조류경보 예측 AI 모델 개발!

총 12개의 지정 과제가 있었지만, 각자 관심있는 데이터나 주제를 맡아 조사하고 발표했다. 그중 다애님이 관심 있게 살펴보고 제안한 한국수자원공사의 과제를 선택해 진행하게 되었다. 대청댐, 유해조류, 활용해야 할 데이터 등 전반적인 도메인 지식이 부족한 상태였기 때문에, 각자 조사할 내용을 나누어 학습한 뒤 회의 시간에 화면 공유를 통해 발표하는 방식으로 진행하고 있다. (자연스럽게 토론도 이어지다 보니 매 회의가 1시간 20분을 훌쩍 넘기곤 하는데.. 정상 이겠죠?) 학교 외에서 다른 사람들과 프로젝트를 진행해본 경험이 많지 않아 처음에는 걱정도 있었지만, 다애님과 현준님은 1차 미니 프로젝트를 함께했던 팀원이라 오프라인에서 이미 안면을 익혀 조금(?) 친해진 상태였고, 현석님은 코딩 테스트 스터디를 함께하고 있어 이번 공모전을 계기로 더 많은 이야기를 나누며 가까워질 수 있을 것 같았다. 우리가 진행하는 방식은 비교적 체계적이다. 자료 공유와 간단한 회의록 작성, 일정 관리를 위해 노션을 활용하고 있으며, 주관기관에서 제시한 지정 과제를 기반으로 데이터 전처리와 모델 개발을 진행해야 하기 때문에 깃허브 저장소도 별도로 만들어 협업하고 있다. (간단한 질문, 궁금한 내용은 카톡 or Teams 활용!)

공모전을 제출하고 후에 글을 한번에 정리해 공모전에 대해 A~Z까지 다뤄보려고한다.

춘배 1

춘배 2

춘배 3

Github

인사말

열렬한 회의중 111

열렬한 회의중 222

이번 공모전을 시작으로 우리가 교육이 끝나는 9월전까지 많은 공모전을 도전하고 많이 함께 이것저것 만들어 볼 수 있을거 같다. 우리 팀원들에게 항상 감사드립니다.

다루는 내용이 궁금하다면? 노션 링크 깃허브 링크

코딩테스트 스터디

코딩 테스트를 준비하는 스터디 모임에서는 자바/파이썬 모집 글이 있었지만 나는 자바 스터디 모임을 진행했다. 우선 나에게 배경지식에 자바는 학교 전공수업에서 배우고 프로젝트를 간단하게 1개 사용해 본 적 이외에는 잘 사용하지 않았었다. 파이썬에 경우에는 백준/프로그래머스 사이트 등에서 코딩 테스트 문제를 대학교 때 간간히 풀어서 어느 정도 알고 있어 자바로 코테를 진행하면서 도전해 보려고 했다. (알고리즘, 문제풀이 구현 방식은 어느 정도 기억? 하고 있다고 생각해서 클래스와 객체를 활용한 문제 해결 방식을 풀면서 익혀보려고 했다)

Python - Baekjoon Online Judge

기본적으로 카톡방이 있지만 현재는 활발하게 자신의 코드를 공유하지는 않고 코딩마스터스를 이용해 일마다 10문제씩 풀고 구글docs를 이용해 각자 자신이 푼 코드와 상대방에 코드를 공유하는 방식이다. (따로 회의는 진행하지 않았다.) 그렇기에 개인이 집중해서 문제를 풀면서 역량을 늘리는것이기에 스터디모임에 역할이 없다고 생각하지만 문제는 하루에 하나씩은 풀자는 생각으로 문제를 풀고 있다. 파이팅해자고..

백준사이트 서비스 종료.... 믿기지 않습니다.. 아직 취업 못했는데..

생각정리

이번에는 따로 글로 정리하진 않았지만, 5/6반에서 모집한 기자단에 지원했고 운 좋게 선정되었다. 교육을 시작하면서부터, 나도 부트 캠프를 진행하게 된다면 배운 내용이나 그때의 생각들을 꾸준히 다시 블로그로 돌아와 남겨보자는 마음을 가지고 있었다. 이 과정이 끝난 이후에도 기록을 다시 꺼내보면서 나에게도 도움이 되고 내 글을 방문하게 된다면 방문 한 이에게도 도움이 되지 않을까 하는 생각이 들었고, 그 명분과 약간의 책임감으로 계속 써 내려간다면 쉬지 않고 앞으로 나아갈 수 있을 것 같았다. 예전에 대학교에서 만난 친해진 선배가 있었다. 폴더별로 txt 파일을 만들어 매일 기록을 남기던 분이었는데, 그때 이런 이야기를 해주셨다. “배운 내용은 결국 다 까먹는다. 천재가 아닌 이상 계속 다시 보게 된다. 시험 기간에도 보고, 그 이후에도 보게 된다. 그리고 교수님의 지식은 내 지식이 아니니까, 반드시 내 말로 정리해봐야 한다.” 그 말을 들으면서, 단순히 하루동안 배운 내용을 나의 머리에 꾸역 넣는것과 공부를 진행하면서 기록까지 꾸준히 남기는 건 또 다른 영역이라는 생각이 들었다. 그런데 막상 조금씩이라도 기록을 시작해보면, 그게 어느 순간 습관이 되고 결국 나를 성장시키는 시간이 되는 것 같다. 지금은 나도 후배들에게 비슷한 이야기를 해줄 수 있게 된 것 같다. 2024년부터 Velog, GitHub, Notion, Obsidian 등에 사소한 것까지 기록해왔다. 연구실, 전공에서 배운 내용, 진행했던 프로젝트/막혔던 부분과 왜 찾았는지/해결했는지, 프로젝트에서 맡았던 역할, 느낀 점, 서비스 프로젝트 이후 배포나 유지보수 과정에서 겪은 어려움, 그리고 학생회나 소모임, 대회활동 같은 일상적인 경험들까지. 그렇게 쌓인 1일, 1주일, 1달, 1년의 기록들이 필요할 때마다 다시 꺼내볼 수 있는 자료가 되었고, 단순한 검색보다 훨씬 오래 기억에 남는 공부가 되는 것 같다. 아직 나는 글을 재미있고 유익하게 잘 쓰는 편은 아니지만, 쓰다 보니 자연스럽게 다른 사람의 글도 더 찾아보게 되고, 남이 읽기 편한 글, 좋은 글을 쓰기 위한 자료나 책에도 관심이 생긴다. 이것도 하나의 취미라고 할 수 있을까, 4주차 회고록을 마무리한다.

나만의 루틴을 탄탄히 만들자, 미루지 말자.

이번 주차는 크게 4주차-1(교육 정리)과 4주차-2(스터디 모임 회고록)에 대해 작성해 보려고 한다. 4주차에서는 AI Agent와 워크플로우 설계 대해 학습을 진행했다. 내용이 광범위하고 다음 주차, 프로젝트를 진행하기 위해서는 크게 복습을 한번 진행하는 것이 중요하다고 생각했기 때문에 주차를 나눠서 글을 작성하려고 한다. 4주차-2에서는 따로 스터디를 진행 중인 공모전/코딩테스트 스터디 모임에 대해 좀 더 이야기를 나눠보려고 한다. 이제 Agent에 내용에 관해 정리해 보자

1. AI Agent와 워크플로우 설계

들어가기 전 AI Agent는

• 모델 정의 (LLM 선택 및 프롬프트 엔지니어링)
• 지식 기반 구축 (RAG 및 벡터 데이터베이스 설정)
• 도구 정의 (외부 API, 웹 검색, 코드 실행 등 Tool 연동)
• 워크플로우 설계 (Planning, Reasoning, Reflection 구조화)
• 실행 및 모니터링 (실시간 대응 및 데이터 관리) 위 AI Agent 구축 사이클을 기억하자

이번 과정에서는 생성형 AI를 단순히 호출하고 답변을 얻는 것을 넘어서, 언어 모델이 스스로 의사를 결정하고 도구를 사용하여 문제를 해결하는 AI Agent를 구축하는 방법을 배우게 되었다. 특히 LangChain과 LangGraph 프레임워크를 활용하여 복잡한 워크플로우를 설계하는 것이 주된 목표다.

1.1 LLM 활용 방식과 LangChain의 역할

대규모 언어 모델(LLM)을 우리의 데이터에 맞게 활용하는 방법은 크게 세 가지로 나눌 수 있다. 첫째는 모델을 그대로 사용하는 것이고, 둘째는 나의 데이터를 추가로 학습시키는 파인튜닝(Fine-Tuning), 그리고 셋째는 외부 지식을 검색하여 프롬프트에 포함시키는 RAG(Retrieval-Augmented Generation) 방식이다. 파인튜닝은 연산 자원과 훈련 시간, 과적합 등의 한계가 존재하기 때문에 최근에는 RAG 기반의 접근이 매우 중요해지고 있다.

이러한 LLM 기반 애플리케이션을 쉽게 개발하도록 돕는 프레임워크가 바로 LangChain이다. LangChain은 대규모 언어 모델을 활용하여 다양한 컴포넌트들을 체인(Chain)으로 연결해 복잡한 작업을 자동화하도록 돕는다. 주요 구성 요소로는 모델(LLM), 프롬프트, 인덱스(벡터 DB 등), 메모리, 체인, 그리고 에이전트와 도구가 있다.

1.2. 메시지 구성과 프롬프트 엔지니어링

LangChain에서 모델에 입력값을 전달할 때는 단순한 문자열이 아닌, 명확한 역할을 부여한 메시지 객체를 사용한다.

메시지의 종류

• SystemMessage: AI에게 지침이나 역할, 성격을 지정하는 메시지다.
• HumanMessage: 사용자의 질문이나 요청을 담는 메시지다.
• AIMessage: AI가 반환한 응답을 나타낸다.

메시지를 구성할 때는 튜플 방식과 객체 방식을 모두 사용할 수 있다.

이러한 메시지들을 구조화하여 다중 메시지 기반의 흐름을 만드는 것이 ChatPromptTemplate이다. 프롬프트를 설계할 때는 역할(Role), 맥락과 목적(Context & Goal), 답변 형식(Format)을 명확하게 명시하는 프롬프트 엔지니어링이 필수적이다.

1.3. 모델의 답변 무작위성 제어

LLM은 내부적으로 다음 단어가 등장할 확률을 계산하여 텍스트를 생성한다. 이 생성 과정의 다양성과 무작위성을 제어하기 위해 몇 가지 중요한 파라미터를 조절할 수 있다.

• Temperature: 확률 분포 자체를 조절한다. 0에 가까울수록 가장 확률이 높은 단어만 선택하여 일관되고 논리적인 답변을 생성하며, 1 이상으로 높아질수록 낮은 확률의 단어도 선택할 가능성이 생겨 창의적인 답변을 도출한다.
• Top_k: 확률이 가장 높은 상위 K개의 단어만 다음 단어의 후보로 제한하는 방식이다.
• Top_p: 단어들의 누적 확률이 p 이상이 되는 최소 집합을 후보로 삼는다. 예를 들어 0.9로 설정하면, 상위 확률 단어들을 더해 총합이 90%가 되는 순간까지만 후보군에 포함시킨다.

1.4. 파이프라인 구성과 출력 결과 구조화

LangChain의 진정한 강력함은 컴포넌트들을 연결하는 LCEL(LangChain Expression Language)에서 나온다. 파이프(|) 연산자를 사용하여 데이터가 흐르는 직관적인 파이프라인을 구축할 수 있다.

# LCEL을 이용한 체인 구성 예시
chain = prompt | llm | parser
response = chain.invoke({"user_input": "추천 도서 알려줘"})

여기서 마지막에 연결된 parser는 Output Parser(출력 파서)를 의미한다. LLM은 기본적으로 단순한 문자열 텍스트를 반환하지만, 실제 애플리케이션 개발에서는 리스트나 JSON과 같이 구조화된 데이터가 필요한 경우가 많다.

이때 PydanticOutputParser를 활용하면 매우 편리하다. 파이썬의 Pydantic 라이브러리를 통해 우리가 원하는 데이터 스키마(예: 책 제목, 저자, 출판년도)를 명확히 정의하고, 모델이 해당 구조에 맞게 응답하도록 프롬프트 지침을 주입할 수 있다. 또한 반환된 데이터의 타입이 맞는지 자동으로 검증까지 수행해주어 출력의 안정성을 크게 높여준다.

참고/출처 https://docs.langchain.com/ https://brunch.co.kr/@ywkim36/147 https://www.samsungsds.com/kr/insights/what-is-langchain.html https://aws.amazon.com/ko/what-is/langchain/ https://pangguinland.tistory.com/318

2.RAG 기반 파이프라인 구축

대규모 언어 모델(LLM)은 자신이 학습하지 않은 최신 정보나 내부 비공개 문서에 대해서는 알지 못하며, 잘못된 정보를 사실처럼 말하는 할루시네이션(Hallucination) 문제가 발생하기 쉽다. LLM의 한계를 극복하기 위해 외부 지식을 검색하여 답변의 근거로 활용하는 RAG(Retrieval-Augmented Generation) 기술과 그 파이프라인 구축 과정을 정리!

2.1. RAG 개념의 이해

RAG는 쉽게 말해 '검색(Retrieval)'과 '생성(Generation)'을 결합한 기술이다. 사용자가 질문을 던지면 LLM이 바로 답변을 생성하는 것이 아니라, 먼저 준비된 지식 데이터베이스(Vector DB)에서 질문과 관련된 문서(Context)를 검색하여 찾아낸다. 그런 다음 검색된 문서의 내용을 프롬프트에 포함시켜 LLM에게 전달하고, LLM은 주어진 문맥만을 바탕으로 정확한 답변을 생성하게 된다.

이러한 시스템을 구축하기 위해서는 문서를 컴퓨터가 이해하고 검색할 수 있는 형태로 변환하여 저장하는 Vector DB 구축 과정이 선행되어야 한다.

2.2. Vector DB 구축 절차

Vector DB를 만드는 과정은 크게 4가지 단계(Load -> Split -> Embed -> Store)로 이루어진다.

(1) 데이터 불러오기 (Load)

가장 먼저 할 일은 다양한 포맷의 파일로부터 텍스트를 추출하는 것이다. LangChain에서는 Loader라는 도구를 제공하며, 파일 형식에 따라 알맞은 로더를 사용한다. 일반적인 텍스트 파일은 TextLoader, PDF 파일은 PyMuPDFLoader, CSV 파일은 CSVLoader를 사용하여 문서를 읽어 들인다. 로드된 데이터는 텍스트 내용(page_content)과 메타데이터(metadata)를 포함하는 Document 객체 형태로 변환된다.

(2) 텍스트 분할 (Split)

문서를 로드했다고 해서 그대로 LLM에 던져줄 수는 없다. LLM이 한 번에 처리할 수 있는 입력 토큰 수에 제한이 있기 때문이다. 따라서 긴 문서를 의미 있는 작은 단위인 청크(Chunk)로 나누는 작업이 필요한데, 이를 텍스트 분할이라고 한다.

텍스트를 나눌 때는 단순히 글자 수로만 자르면 문맥이 끊어질 수 있으므로, 문단이나 문장 단위를 고려하고 청크 간에 내용이 일부 겹치도록 설정하는 것이 중요하다. LangChain의 CharacterTextSplitter를 사용하면 최대 글자 수(chunk_size)와 겹치는 글자 수(chunk_overlap)를 지정하여 문서를 분할할 수 있다. 적절한 청크 크기(보통 300~800자)와 오버랩을 설정하는 것이 RAG의 검색 품질을 좌우하는 핵심 요소 중 하나다.

(3) 텍스트 벡터화 (Embed)

분할된 텍스트 청크들은 텍스트 자체로는 수학적 검색이 불가능하므로, 이를 숫자로 이루어진 벡터(Vector)로 변환해야 한다. 이 과정을 임베딩(Embedding)이라고 하며, 텍스트의 의미적 정보를 다차원 공간의 좌표로 매핑하는 것이다. OpenAI의 text-embedding-3-small과 같은 모델을 주로 사용하며, 의미가 유사한 텍스트일수록 벡터 공간 상에서 서로 가까운 위치에 놓이게 된다.

(4) 벡터 저장소에 저장 (Store)

마지막으로 임베딩된 벡터 데이터들을 효율적으로 저장하고 검색할 수 있는 데이터베이스에 보관한다. 이를 Vector Store라고 부른다.

2.3. 유사도 검색 원리

Vector DB에 문서가 저장되었다면, 이제 사용자의 질문을 임베딩하여 DB에 저장된 문서 벡터들과 비교할 수 있다. 이때 주로 사용되는 수학적 기준이 코사인 유사도(Cosine Similarity)다.

코사인 유사도는 두 벡터가 이루는 각도를 계산하여 텍스트 간의 의미적 유사성을 측정한다. 값이 1에 가까울수록 문맥적 의미가 매우 유사함을 뜻하며, 0이면 관계가 없고, -1이면 반대 의미를 가짐을 나타낸다. 시스템은 질문 벡터와 코사인 유사도가 가장 높은 상위 K개의 문서를 추출하여 응답의 근거로 사용한다.

2.4. RAG 파이프라인(Chain) 구성

지식 DB 준비가 끝났다면, 사용자의 질문을 받아 검색하고 답변을 생성하는 전체 파이프라인을 LCEL 문법으로 엮어주어야 한다.

1단계: Retriever 선언 Vector DB를 검색기(Retriever)로 변환한다. .as_retriever() 함수를 사용하며, 코사인 유사도를 기준으로 상위 몇 개(k)의 문서를 가져올지 설정한다.

2단계: RAG 전용 프롬프트 정의 LLM이 외부 지식을 활용해 답변하도록 역할을 고정하고, 제공된 문맥(Context) 내에서만 답하도록 프롬프트를 설계한다. 특히 "제공된 문맥에 답이 없다면 모른다고 답변하고 억지로 지어내지 마라"는 조건을 명시하여 할루시네이션을 방지한다.

3단계: LCEL 체인 연결 입력된 질문이 Retriever를 통과해 관련 문서(Context)를 찾아오고, 이 문맥과 원본 질문이 프롬프트 템플릿에 삽입된 후 LLM을 거쳐 최종 답변이 나오는 체인을 구성한다.

# 문서 객체 리스트를 하나의 문자열로 결합하는 포맷 함수
def format_docs(docs):
    return "\n\n".join(doc.page_content for doc in docs)

# LCEL 기반 RAG 파이프라인 구성
rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | llm
)

# 챗봇 실행
response = rag_chain.invoke("가장 심각한 사이버 보안 위험이 뭐야?")

2.5. RAG 성능 최적화 고려 사항

RAG 파이프라인이 제대로 동작하더라도 검색 품질이나 생성 결과가 아쉬울 수 있다. 이를 개선하기 위해 다음과 같은 요소들을 튜닝해야 한다.

• 청크 전략: 문서의 특성에 맞춰 chunk_size와 chunk_overlap을 조정한다. 청크가 너무 작으면 문맥이 잘리고, 너무 크면 여러 주제가 섞여 유사도 검색 성능이 떨어진다.

• 검색 개수(k): LLM의 입력 토큰 한계를 넘지 않는 선에서 충분한 문맥을 제공하기 위해 최적의 k값을 찾는다 (보통 3~5개).

• 프롬프트 고도화: 출력의 제약(길이, 형식 등)을 프롬프트에 구체적으로 명시할수록 응답의 일관성이 향상된다.

참고/출처 https://m.blog.naver.com/rainbow-brain/224072340830 https://kr.linkedin.com/pulse/unlocking-power-rag-pipelines-enhancing-ai-real-time-data-zaveri--lmzif?tl=ko https://m.blog.naver.com/rainbow-brain/224040868079

3. AI Agent - LangGraph

모델이 단순히 주어진 질문에 대답하는 것을 넘어서, 주어진 목표를 달성하기 위해 스스로 계획을 세우고 도구를 활용하며 문제를 해결하도록 만들 수는 없을까? 능동적인 문제 해결 시스템인 AI Agent의 개념과, 이 에이전트의 복잡한 작업 흐름을 통제하기 위한 LangGraph의 정리!

3.1. AI Agent란 무엇인가?

AI Agent는 스스로 의사를 결정하며, 도구를 사용하여 목표를 달성하는 시스템이다. 단순한 텍스트 생성을 넘어, 다단계 추론과 외부 도구 호출 능력을 결합한 것이 특징이다. 즉, 언어 모델(LLM)에 손과 발, 그리고 기억력을 달아주어 하나의 독립적인 작업자로 만드는 과정이라고 이해할 수 있다.

AI Agent는 크게 네 가지 핵심 요소로 구성된다.

• 첫째, 시스템이 최종적으로 해결해야 할 목표(Goal)다.
• 둘째, 이 목표를 달성하기 위해 계획을 세우고 판단을 내리는 두뇌 역할의 추론 엔진(Reasoning Engine)이며 주로 GPT 같은 LLM이 담당한다.
• 셋째, 웹 검색, 계산기, 사내 API 등 에이전트가 호출하여 사용할 수 있는 외부 기능인 도구(Toolset)다.
• 넷째, 이전의 대화나 수집한 정보, 현재의 진행 상황을 저장하고 추적하는 공간인 메모리와 상태(Memory/State)다.

3.2. 워크플로우 제어를 위한 LangGraph

이러한 Agent 시스템을 구축하기 위한 프레임워크로는 여러 가지가 있지만, 복잡한 다단계 프로세스를 개발자가 원하는 대로 세밀하게 제어하기 위해 LangGraph를 활용한다. LangGraph는 에이전트의 작업 흐름을 그래프(Graph) 구조로 설계할 수 있게 해준다.

LangGraph를 구성하는 핵심 요소는 다음과 같다.

• State (상태): 그래프 전체를 관통하며 현재 상태 값을 저장하고 전달하는 역할을 한다. 에이전트가 통과하는 각 단계마다 정보가 누적되며, 파이썬의 TypedDict를 사용하여 어떤 데이터가 들어갈지 딕셔너리 형태로 명확히 구조를 정의한다.
• Node (노드): 특정 작업이나 판단을 수행하는 실제 단위다. 파이썬 함수로 구현되며, 상태(State)를 입력으로 받아 특정 작업을 수행한 후 업데이트된 상태를 반환한다.
• Edge (엣지): 노드와 노드를 연결하는 선으로, 작업의 흐름을 정의한다. 한 노드의 작업이 완료된 후 다음으로 이동할 노드를 지정한다.
• Conditional Edge (조건부 엣지): 단순한 순차적 이동이 아니라, 특정 조건이나 상태 값에 따라 노드 간의 분기 처리를 수행할 때 사용한다.

3.3. 에이전트 워크플로우의 세 가지 기본 패턴

상태와 노드, 엣지를 조합하면 다양한 형태의 워크플로우를 설계할 수 있다. (세 가지 그래프 구조를 학습)

(1) 단순 그래프 (Simple Graph)

입력, 처리, 출력으로 이어지는 단순한 파이프라인 형태다. 가장 기본적인 구조로, 시작점(START)에서 출발해 정의된 노드들을 차례대로 거친 후 종료점(END)에 도달한다.

(2) 라우팅 (Routing)

사용자의 입력이나 특정 조건에 따라 서로 다른 경로를 선택하여 실행 흐름을 제어하는 구조다. 이때 조건부 엣지(Conditional Edge)가 핵심적인 역할을 한다.

강의에서는 입력된 숫자가 짝수인지 홀수인지 판별하여 각각 다른 노드를 실행하는 예제를 다루었다. 짝수/홀수 판별 함수를 먼저 만들고, 이를 조건부 엣지에 연결하여 흐름을 동적으로 분기시키는 방식이다.

# 조건 분기를 결정하는 라우터 함수
def parity_condition(state: State):
    return "even" if state["number"] % 2 == 0 else "odd"

# 조건부 엣지 추가 (check_parity 노드 실행 후 분기)
builder.add_conditional_edges(
    "check_parity", 
    parity_condition,
    {"even": "even_node", "odd": "odd_node"}
)

(3) 반추 (Reflection)

에이전트가 스스로의 추론 과정이나 결과물을 돌아보고 피드백을 생성하여, 결과가 만족스러울 때까지 반복 작업을 수행하는 메커니즘이다. 그래프 상에서 특정 노드에서 종료로 가지 않고 다시 이전 노드로 돌아가는 루프(Loop)를 형성하여 구현한다.

예를 들어, 문서를 요약하는 노드를 거친 후 결과의 만족도를 평가한다. 평가 결과가 '만족'이면 시스템을 종료하지만, '불만족'이면 다시 생각해보기(반추) 노드를 거쳐 원래의 요약 노드로 되돌아간다. 이러한 순환 구조를 통해 에이전트는 한 번에 완벽한 답을 내지 못하더라도, 점진적으로 결과물의 품질을 향상시킬 수 있다.

참고/출처 https://wikidocs.net/268610 https://cobusgreyling.medium.com/whats-your-definition-of-an-ai-agent-edb7d5e1c760 https://www.langchain.com/langgraph

4. AI Agent와 Tool 활용

도구(Tool) 활용법과, 과거의 대화를 기억하며 도구를 능동적으로 사용하는 실질적인 챗봇 에이전트 구축 과정을 정리!

4.1. AI Agent와 Tool의 역할

일반적인 대규모 언어 모델은 사용자의 입력을 받아 단순히 텍스트 응답을 생성한다. 하지만 실제 업무에서는 실시간 웹 검색이 필요하거나, 정확한 수학 계산을 해야 하거나, 사내 데이터베이스를 조회해야 하는 등 외부 시스템과의 상호작용이 필수적이다.

이러한 외부 기능들을 에이전트가 사용할 수 있도록 묶어놓은 것을 Tool(도구)이라고 부른다. 모델은 사용자의 질문을 분석한 뒤, 스스로 판단하여 필요한 시점에 적절한 도구를 호출(Tool Call)하고 그 결과를 바탕으로 최종 응답을 만들어낸다.

도구는 크게 두 가지로 나뉜다.

• Custom Tool: 우리가 필요에 따라 파이썬 함수로 직접 정의하고 만든 도구다.
• 외부 도구: 검색 엔진(Tavily 등), 날씨 API 등 외부 업체에서 미리 만들어 제공하는 도구다.

4.2. 메모리를 가진 대화형 챗봇 만들기 (State 관리)

도구를 사용하는 복잡한 에이전트를 만들기 전, 먼저 에이전트가 과거의 대화를 기억하게 만들어야 한다. LangGraph에서는 이를 State를 통해 관리한다.

단순히 텍스트 하나만 주고받는 것이 아니라, 대화 기록 전체를 리스트 형태로 State에 담아 관리해야 문맥이 유지된다. 이때 매번 기존 리스트를 덮어쓰는 것이 아니라 새로운 메시지를 계속 누적해서 추가(Append)해야 하는데, LangGraph는 이를 아주 쉽게 구현할 수 있도록 add_messages라는 기능을 제공한다.

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages

# 대화 이력을 자동으로 누적해서 관리하는 State 구조
class State(TypedDict):
    messages: Annotated[list, add_messages]

이렇게 Annotated와 add_messages를 활용해 State를 정의하면, 새로운 메시지가 반환될 때마다 프레임워크가 알아서 기존 메시지 목록의 맨 뒤에 새 메시지를 추가해 준다. 이를 통해 모델은 항상 전체 대화 히스토리를 보며 자연스러운 맥락을 이어갈 수 있다.

4.3. Custom Tool 만들기 및 모델에 연결하기

에이전트에게 쥐어줄 도구를 만드는 방법은 매우 간단하다. 일반적인 파이썬 함수를 작성한 뒤, 그 위에 @tool 데코레이터만 붙여주면 LangChain이 인식할 수 있는 도구로 변환된다. 이때 함수 내부의 매개변수 타입과 독스트링을 명확히 적어주는 것이 중요한데, 모델이 이 설명을 읽고 언제 어떻게 이 도구를 써야 할지 결정하기 때문이다.

from langchain_core.tools import tool

# 계산기 도구 정의
@tool
def calculator_tool(expression: str) -> str:
    """수학 수식을 입력받아 계산 결과를 반환합니다."""
    return str(eval(expression))

# 1. 사용할 도구들을 리스트로 묶기
tools = [calculator_tool]

# 2. LLM에 도구 목록 연결 (Binding)
llm_with_tools = llm.bind_tools(tools)

가장 핵심적인 부분은 만든 도구들을 리스트로 묶어 LLM에 바인딩하는 것이다. 이 과정을 거쳐야만 LLM이 자신에게 어떤 무기들이 주어졌는지 인지하고, 필요할 때 함수 실행을 요청할 수 있다.

4.4. Tool을 사용하는 Agent 워크플로우 구성

이제 모델과 도구를 LangGraph의 노드와 엣지로 엮어 실제 에이전트의 워크플로우를 구성할 차례다. 도구를 사용하는 에이전트의 흐름은 대체로 다음과 같은 순환 구조를 가진다.

사용자 입력: 사용자가 질문을 던진다.

모델 판단 (call_model 노드): LLM이 질문을 분석한다. 만약 도구 사용이 필요 없다면 바로 최종 답변을 생성하고 종료(END)한다.

도구 호출 요청: 도구가 필요하다고 판단되면, LLM은 응답 텍스트 대신 "이 도구를 이런 매개변수로 실행해줘"라는 Tool Call 명령을 내뱉는다.

조건부 분기: 조건부 엣지가 모델의 응답을 확인하여 Tool Call이 포함되어 있다면 흐름을 도구 실행 노드로 보낸다.

도구 실행 (tools 노드): ToolNode가 실제 파이썬 함수를 실행하고 그 결과값을 State의 messages에 추가한다.

결과 피드백: 흐름은 다시 모델 판단 노드(call_model)로 돌아간다. LLM은 방금 실행된 도구의 결과값을 확인하고, 이를 바탕으로 최종 답변을 정리하여 사용자에게 전달한다.

이러한 과정을 통해 에이전트는 한 번에 답을 내기 어려운 복잡한 문제도 스스로 도구를 여러 번 호출해가며 해결책을 찾기

생각정리

Agent에 대한 공부는 처음이 아니었지만, 이번에는 이전보다 훨씬 깊이 있게 개념을 탐색하고 정리할 수 있었던 시간이었다. 단순히 겉핥기식으로 이해하는 것이 아니라, 직접 검색하고 구조를 파악하면서 개념을 보다 명확하게 이해할 수 있었다는 점에서 의미가 크다. 과거에는 Agent를 학습할 때 GitHub에서 스타가 많은 레포지토리를 중심으로 글을 읽고, 코드를 클론하여 실행해보는 방식에 집중했었다. 또한 실제 프로젝트에 Agent가 필요한지, 필요하다면 어떻게 적용할 수 있을지에 대한 고민보다는 구현 자체에 초점을 맞췄던 것 같다. 일종의 ‘바이브 코딩’에 가까운 접근이었다. 하지만 이번 학습을 통해 Agent의 전체적인 구조와 동작 방식, 그리고 실제로 어떻게 활용해야 하는지에 대해 한 단계 더 깊이 이해할 수 있었다. 단순히 사용하는 것을 넘어서, 어떤 상황에서 적절하게 적용할 수 있는지를 고민하게 되었다는 점이 가장 큰 변화다. 최근에는 다양한 Agent들이 등장하고 있고, 나 역시 GitHub Copilot, Cursor, Codex, Claw-Code 등 여러 도구의 도움을 많이 받고 있다. 이러한 흐름 속에서 Agent를 단순한 도구로 사용하는 것을 넘어, 나에게 가장 잘 맞는 형태로 어떻게 활용할 수 있을지 고민하는 것이 중요하다고 느꼈다. 이번 학습은 단순한 개념 이해를 넘어서, 앞으로 내가 진행할 프로젝트에 Agent를 왜 필요할지, 어떻게 활용하면 좋을지, 왜 화두가 되고 모두가 편리하게 사용하는지에 관한 생각을 하게했던거 같다. 4주차 공부를 마무리한다.

결국 차이를 만드는 것은 도구가 아니라, 그것을 바라보는 관점이다

Github-Private

이번주차는 크게 처음으로 미니프로젝트조가 생겨 조원들7명과 함께 미니프로젝트 및 아이데이션을 준비하게 되었다. 에이블 스쿨에서는 오프라인으로 에이블러들과 프로젝트를 진행 할 수 있게 강의실을 예약해서 이용할 수 있는데 수도권인 경우 KT 전농지점과 KT 판교빌딩 2곳이 있다. 나는 집에서 가기편한곳인 전농교육장을 예약해 방문했다.

01-MiniProject

전농교육장

나포함 조원 6명이 전농교육장에 방문해 함께 프로젝트를 진행했다.. 다른 사진을 하나도 안찍었네.. 우리가 한 프로젝트를 간단하게 봐보자

데이터 분포도 일부 확인

모델 학습

처음은 개인이 지정된 csv를 불러와 데이터 분석/전처리부터 시작해 직접 모델을 만들고 평가로 진행했다. 그 후 조원들과 개인이 작성한 코드에 대한 리뷰를 진행하는 시간이 충분히 주어져 조원들과 모델에 loss 값을 낮추기 위해 어떤 점을 보완하고 추가했으면 좋겠다는 의견을 많이 나눠서 좋았다. (랜덤이지만 처음 미니 프로젝트 조원들을 너무 잘 만난 거 같다) 우리조에서 나온 리뷰를 나열하자면

• 과적합에 대한 문제점이 무엇일까
• Class에 가중치를 둬 학습해보기
• EarlyStopping/ModelCheckpoint를 활용
• Dense를 깊게/얇게 조정하면서 시도하기
• Dropout/Learning rate/Batch_size등 값 조절하기
• 새로운데이터와 기존데이터에 새롭게(기존 모델구조와 같게)모델 학습 vs 새로운데이터와 기존모델을 불러와 재학습에 대한 리뷰
• code를 쓰면서 왜 사용하고 어떻게 표현해야하는지

들을 진행하고 하나의 코드로 통일해 미션을 끝냈다. (1번째 미니프로젝트가 끝나고 퇴근시간인 2호선, 1호선을 타고 집으로 가면서 죽을뻔했네)

아이데이션

아이데이션이라는 단어를 들어봤는데 이게 머였지..? 검색해 보자

아이데이션(Ideation)은 광고, 기획, 디자인 분야에서 새로운 아이디어를 생성(Generating), 발전(Developing), 커뮤니케이션(Communicating)하는 전 과정을 뜻하는 핵심적인 창의적 프로세스

01-미니 프로젝트를 진행한 조원들과 함께 진행하게 되었다. 정부가 운영하고 있는 나라장터나 최근 이슈가 되는 기업, 정부 관련된 뉴스를 조사해 각자 아이디어를 내고 토론하는 자리였다. (B2B, B2C에 대해 생각하기!) 조원들과 토론하면서 각자 자신이 정한 아이디어에 대해 "이 서비스를 만들어야 하는 이유", "서비스를 기업/정부에 제시한다면 설득력이 있을까?"를 고민하게 하고 요구사항을 맞춰야 한다고 생각했다. 그렇게 작성을 진행했었는데 감사하게도 내가 조사한 과제명이 뽑혀 내 아이디어를 가지고 어떻게 더 발전할 수 있을지에 대해 토론하고 결과물을 내는 시간이었다. (결과물을 제출하기 전에 피드백을 받고 수정할 수 있는 시간이 있어서 좀 더 퀄리티 있는 결과물을 제출할 수 있었던 거 같다.)

생각정리

에이블 스쿨에 입교해 처음으로 팀원들이 생긴 귀중한 시간이었던 거 같고 개인/팀원으로써 코드/리뷰 와 서비스 개발에 필요한 아이디어(?) 마음가짐 등을 배울 수 있었던 자리여서 좋은 시간이었던 거 같다. 아쉬운점이라면 원하던 결과물을 만들기에는 시간이 조금 부족했던 점과 팀원들과 많이 소통을 못 해본 것이 아쉽다. 누구나 그렇다고 생각하지만 처음 대면한 사람을 만나고 대화를 한다는 것은 쉽지 않은 거 같다. 우리반에서는 OT-자기소개 시간에 MBTI를 말하는 시간이 있었는데 내 기억상 90% 이상이 I인 것으로 기억한다. (컴퓨터 만지는 사람이 보통 그런가..?) 그래도 오랜만에 팀프로젝트를 진행하며 좋은 감점을 느꼇다. 활동을 하면서 대학교에서 과대표나 멘토 멘티를 하면서 느꼈던 "상대방이 모르는 부분에 대해 알려주고 이해한 상대방이 만족을 느꼈을 때에 대한 행복"울 느꼈던 거 같다. 이 감정을 느끼는 방식은 남들과 조금 다를 수 있지만, 나에게는 지금까지 꾸준히 공부할 수 있게 만든 원동력 중 하나이며, 팀원에게 한마디 더 건넬 수 있는 자신감의 근원이기도 하다. (먼저 다가가야 상대방도 마음을 열것이다..!) 프로젝트를 짧게 진행해 이번 조원들과의 만남이 아쉽지만 다른 프로젝트와 활동을 하면서 같이 성장하고 싶은 마음이 드는 하루라고 생각하며 3주 차를 마무리한다.

내일은 없다.

Github-Private

ML에 대해 2일 동안 DL에 대해 1일 학습을 진행했다. 기간이 짧은 기간 동안 중요한내용을 빠르게 학습하고 바로 실습(코드)으로 진행해 개인이 문제를 해결하기보다 라이브러리 및 함수에 대해 익숙해지고 학습한 모델이 어떤구조와 어떤 흐름으로 이어가는지에 대한 전체적인 이해를 배운 거 같다. 정리해보자

1. 머신러닝 (Machine Learning)

들어가기전 머신러닝은

• 문제 정의
• 데이터 준비(데이터 전처리)
• 모델링(알고리즘 적용)
• 평가
• 성능 최적화(튜닝) 위 사이클을 꼭 기억하기

1-1. 데이터 전처리

알고리즘에 데이터를 넣기 전, 모델이 데이터를 잘 이해할 수 있도록 가공하는 필수 단계

• 결측치 처리: 비어있는 데이터(NaN)를 평균, 중앙값 등으로 채우거나 행 자체를 삭제한다.
• 가변수화 (One-Hot Encoding): 머신러닝 모델은 문자를 이해하지 못하므로, 범주형 데이터(예: 성별, 혈액형)를 0과 1로 이루어진 변수로 변환해 주어야 한다.
• 스케일링 (Scaling): 변수마다 값의 범위가 다르면(예: 나이는 1080, 연봉은 300010000) 단위가 큰 변수에 모델이 가중치를 과도하게 둘 수 있다. 따라서 모든 변수의 범위를 0~1 사이로 맞추는 정규화(MinMaxScaler)나 평균 0, 표준편차 1로 맞추는 표준화(StandardScaler)를 진행한다. 거리 기반 알고리즘(KNN 등)에서는 필수적이다.

1-2. 문제의 정의와 주요 알고리즘: 회귀(Regression) vs 분류(Classification)

목표 변수(Target)의 형태에 따라 접근 방식과 알고리즘을 선택하자!

출처/참고 : https://www.geeksforgeeks.org/machine-learning/ml-classification-vs-regression/

[회귀 모델링 (Regression)]

• 목표(Target): 연속적인 '숫자'를 예측하는 문제 (예: 집값 예측, 주가 예측, 매출액 예측). 실제 값과 예측값의 '오차(Error)'를 최소화하는 것이 핵심이다.
• 선형 회귀 (Linear Regression): 데이터의 경향성을 가장 잘 설명하는 하나의 최적의 직선(y = wx + b)을 긋는 방식. 빠르고 해석이 쉽지만 복잡한 패턴을 잡기는 어렵다.
• K-최근접 이웃 회귀 (KNN Regressor): 예측하려는 데이터와 가장 가까운 K개의 이웃 데이터를 찾아, 그 이웃들의 타겟 값 평균을 계산하여 예측한다.

[분류 모델링 (Classification)]

• 목표(Target): 데이터가 속할 '범주(Class)'를 예측하는 문제 (예: 스팸 메일 여부, 질병 유무). 정확하게 경계선을 그어 범주를 나누는 것이 핵심이다.
• 로지스틱 회귀 (Logistic Regression): 이름은 회귀이지만 분류에 사용된다. 시그모이드 함수를 통해 특정 클래스에 속할 확률(0~1)을 계산하여 0.5를 기준으로 분류한다.
• 의사결정나무 (Decision Tree): 스무고개처럼 조건(예: 나이가 30 이상인가? Yes/No)을 분기하여 데이터를 분류한다. 사람이 직관적으로 이해하기 좋고 설명력이 뛰어나다.
• 랜덤 포레스트 (Random Forest): 수많은 의사결정나무를 만들고, 각 나무의 예측 결과를 취합(투표)하여 최종 결과를 내는 앙상블(Ensemble) 기법이다. 단일 모델보다 성능이 훨씬 뛰어나며 과적합을 방지하는 효과가 있다.

1-3. 모델 성능 평가 (Evaluation)

학습된 모델이 처음 보는 데이터(Test Data)에 대해 얼마나 잘 작동하는지 객관적으로 평가

분류 모델 평가 지표 (Classification Metrics)

출처/참고 : https://glassboxmedicine.com/2019/02/17/measuring-performance-the-confusion-matrix/

[분류 평가지표와 오차행렬(Confusion Matrix)] 분류 문제는 오차행렬(TP, TN, FP, FN)을 기반으로 평가한다.

• Accuracy (정확도): 전체 예측 중 맞춘 비율. 데이터 불균형(예: 정상 99개, 불량 1개) 시 무조건 정상이라고만 찍어도 99%가 나오므로 신뢰하기 어렵다.
• Precision (정밀도): 모델이 'Positive'라고 예측한 것 중 실제 'Positive'인 비율. (예: 스팸으로 걸러낸 메일 중 진짜 스팸인 비율. 일반 메일을 스팸으로 걸러버리면 안 될 때 중요).
• Recall (재현율): 실제 'Positive'인 것 중 모델이 'Positive'로 찾아낸 비율. (예: 실제 암 환자 중 모델이 암이라고 예측한 비율. 병원 진단 모델처럼 실제 환자를 놓치면 안 될 때 가장 중요).
• F1-Score: 정밀도와 재현율의 조화 평균으로, 데이터가 불균형할 때 모델의 성능을 가장 객관적으로 대변한다.

1-4. 교차 검증(Cross Validation)과 모델 성능 튜닝(Hyperparameter Tuning)

개발자가 알고리즘에 직접 설정해 주어야 하는 '하이퍼파라미터'에 따라 성능이 극명하게 달라지므로, 이를 최적화하는 과정이 필요하다.

• K-Fold 교차 검증: 훈련 데이터를 통째로 한 번만 학습하는 것이 아니라, 데이터를 K개의 폴드(조각)로 나누어 K번 반복 학습 및 평가를 진행한다. 특정 데이터 셋에만 맞춰지는 것을 방지하고 모델의 평균적인 성능을 신뢰성 있게 평가할 수 있다.

• Grid Search (그리드 서치): 지정한 파라미터 값들의 '모든 경우의 수'를 다 조합해서 학습해 보고 가장 최고 성능(best_score_)을 내는 조합(best_params_)을 찾는 방법. 탐색 공간이 넓어지면 시간이 늘어난다.
• Random Search (랜덤 서치): 파라미터의 범위만 지정해 주고, 그 안에서 랜덤하게 조합을 뽑아 지정된 횟수(n_iter)만큼만 테스트하는 방법. 그리드 서치보다 시간은 훨씬 절약되면서도 꽤 괜찮은 최적의 값을 빠르게 찾아낸다.

출처/참고 https://ethen8181.github.io/machine-learning/model_selection/model_selection.html https://datarian.io/blog/grid-search-random-search https://blog.naver.com/hsj2864/222215638480 https://scikit-learn.org/stable/modules/cross_validation.html https://www.ibm.com/think/topics/fine-tuning

2. 딥러닝 (Deep Learning)

들어가기 전 딥러닝은

• 데이터 준비 (데이터 전처리 및 스케일링 필수)
• 구조 설계 (레이어, 노드, 활성화 함수 구성)
• 모델 컴파일 (손실 함수 및 옵티마이저 설정)
• 모델 학습 (Epoch 반복을 통한 가중치 업데이트)
• 성능 최적화 (Early Stopping, Dropout 등으로 과적합 방지)
• 평가 위 딥러닝 고유의 모델링 사이클을 꼭 기억하기!

머신러닝의 알고리즘 중 '인공신경망(ANN)'을 여러 개의 은닉층(Hidden Layer)으로 깊게(Deep) 쌓아 올린 것이 딥러닝이다.

2-1.작동 원리

출처/참고 https://starcell.github.io/ai/dl-basic/

신경망은 Input Layer(입력층), Hidden Layer(은닉층), Output Layer(출력층)로 구성

• 가중치(Weight)와 편향(Bias): 각 노드(뉴런)는 입력값에 가중치를 곱하고 편향을 더한다. 학습이란 이 가중치와 편향의 최적값을 찾아가는 과정이다.
• 역전파(Backpropagation): 출력층에서 예측값과 실제값의 오차를 구한 뒤, 이 오차를 최소화하는 방향으로 출력층에서부터 입력층으로 거꾸로 돌아가며 가중치를 업데이트(미분 활용)한다.

2-2. 활성화 함수(Activation)와 손실 함수(Loss) 설정

딥러닝은 층과 층 사이에 '활성화 함수'를 넣어 비선형성을 추가한다. 이것이 없으면 아무리 층을 깊게 쌓아도 결국 단순한 선형 회귀 모형과 다를 바가 없어진다. 은닉층에서는 주로 'relu'를 사용하여 딥러닝의 고질적 문제인 기울기 소실(Vanishing Gradient)을 방지한다.

문제 유형에 따른 출력층 설계

• 회귀 (연속된 숫자 예측):
  • 출력 노드 수: 1개
  • 활성화 함수: 없음 (또는 linear)
  • 손실 함수(Loss): mse (Mean Squared Error)
• 이진 분류 (O/X, 생존/사망 등 두 개 중 하나 분류):
  • 출력 노드 수: 1개
  • 활성화 함수: sigmoid (출력값을 0~1 사이의 확률로 변환)
  • 손실 함수(Loss): binary_crossentropy
• 다중 분류 (여러 클래스 중 선택):
  • 출력 노드 수: 분류하려는 클래스의 개수 (예: 개/고양이/새 분류면 3)
  • 활성화 함수: softmax (각 클래스에 속할 확률을 모두 더하면 1이 되도록 변환)
  • 손실 함수(Loss): categorical_crossentropy (원핫인코딩 된 경우) 또는 sparse_categorical_crossentropy (정수형 라벨인 경우)

2-4. 학습 방법론과 성능 최적화 (과적합 방지 기법)

딥러닝 모델은 파라미터가 수십만~수천만 개에 달하기 때문에, 훈련 데이터에만 완벽히 맞춰져 새로운 데이터에 취약해지는 '과적합(Overfitting)'에 빠지기 매우 쉽다. 모델의 복잡도를 제어하는 것이 핵심이다.

• 주요 학습 파라미터:

  • Epoch (에포크): 전체 데이터를 몇 번 반복해서 학습할 것인가. 에포크가 너무 적으면 과소적합, 너무 많으면 과적합이 발생한다.
  • Learning Rate (학습률): 가중치를 업데이트할 때 오차의 최소점을 향해 한 번에 얼마나 크게 이동할 것인가를 결정한다. 너무 크면 최적점을 지나쳐 발산하고, 너무 작으면 학습이 지나치게 느려지거나 지역 최적점(Local Minimum)에 갇힌다.

• 과적합 방지 및 최적화 기법:

  • Early Stopping: 모델이 학습하면서 검증 데이터의 오차(val_loss)가 더 이상 감소하지 않고 반등하기 시작하면, 설정해 둔 Epoch가 남아있더라도 학습을 강제로 조기 종료시킨다. patience 옵션으로 오차가 줄지 않아도 몇 번의 에포크를 더 기다려볼지 결정할 수 있다. 과적합으로 넘어가기 전 최적의 타이밍에 학습을 멈추는 필수 콜백 함수다.
  • ModelCheckpoint: Early Stopping과 함께 자주 쓰이며, 학습 과정 중 지정한 지표(예: val_loss)가 가장 좋았던 순간의 최적의 가중치를 파일로 자동으로 저장해 둔다.
  • Dropout: 은닉층의 노드 중 일부 비율(예: 20~50%)을 무작위로 비활성화한 채로 학습하는 방법이다. 매 에포크마다 끊어지는 노드가 달라지므로 모델이 특정 노드의 가중치에만 과도하게 의존하는 것을 막아준다. 이는 일종의 앙상블 효과를 내어 새로운 데이터에 대한 일반화(Generalization) 성능을 비약적으로 높여준다.
  • Regularization: L1 규제, L2 규제 등을 통해 가중치 값이 비정상적으로 커지는 것을 수학적으로 억제하여 모델의 복잡도를 낮추는 기법이다.

출처/참고 https://facerain.github.io/improve-dl-performance/ https://pub.towardsai.net/keras-earlystopping-callback-to-train-the-neural-networks-perfectly-2a3f865148f7 https://kh-kim.github.io/nlp_with_deep_learning_blog/docs/1-14-regularizations/04-dropout/ https://www.geeksforgeeks.org/machine-learning/regularization-in-machine-learning/

생각정리

대학원 면접 보러 갔을 당시 내가 고민하다가 생각한 주제인 Why Multi-class Classification Needs Softmax를 발표하는 장면이 주마등처럼 스쳐가는 수업이었던 거 같다... 수업내용에서는 Multi-class를 크게 다루지 않았지만 학부 연구생때 연구실에 처음 들어가 교수님이 읽으라고 지시해주신 딥러닝 모델들도 생각나게 되는 수업이었던 거 같다.

• ImageNet Classification with Deep Convolutional Neural Networks(AlexNet)
• Deep Residual Learning for Image Recognition
• Densely Connected Convolutional Networks
• Very Deep Convolutional Networks for Large-Scale Image Recognition

구조를 이해하고 최적화기법에 하나하나에 수식을 보는 것이 아닌 전체 흐름 구조 복습 및 실질적인 AICE-associate를 준비하기 앞서 코드를 직접 작성해 보고 구현해 보는 것이 목적이었다고 생각한다. 기간이 너무 짧다 보니(2일/2일) 비전공자/전공자에게 모든 것을 이해시키는 것은 정말 불가능하다고 생각했었기 때문이다. 하나의 내용으로만 2주 내내 수업해도 모자라지 않은 내용이었다고 생각한다. 실습과 복습을 진행하면서 수업 시간에 내용에서 강사님께서 설명해 주신 부분이 맞나?라고 생각했던 부분을 다시 찾아 보면서 이해할 수 있었던 좋은 시간이었다고 생각한다. 배웠던 내용이 오래 기억되고 나의 지식으로 온전히 다 받아들일 수 있게 "반복 학습하자!" 생각을 하며 2주차를 마무리한다.

교수님(대학교 지도교수님)의 말씀 중 : 내가 배운 내용을 정말 이해하고 있는지 의문이 들 때가 있어, 그럴 때는 그 내용을 다른 이에게 설명하고, 상대방에게 설명할 수 있다면 비로소 그것이 내 것이 된 지식일 거야

Github-Private

회고록은 자고로 1주일을 마무리며 쓰는 게 제일 효과적이라고 생각했다.. 그렇게 생각했지만.. 미루고 미루다 보니 4주 차가 끝나는 시점에 블로그로 기록을 남기게 되었다. 아주 부끄럽지만 지금부터라도 수업이 끝난 주 주말에 1주일에 회고록을 담아 내가 생각하고 배웠던 내용을 생생히 담아보려고 한다.

1주차

자기소개/인사말

간단하게 입교식 및 AIVLE-EDU 사용법에 대해 매니저님께서 설명해 주셨다. 수업내용과 자료는 AIVLE-EDU사이트에서 다운로드해 활용하고 Teams를 이용해 5,6반 에의 블러 팀원들과 매니저님과 소통할 수 있게 되었다. 1주 차에서는 깃허브 사용법과 Colab-Python 데이터 전처리를 간단하게 배웠다. 복습을 해보자 (깃 README.md에 정리된 내용)

Pandas DataFrame 데이터 처리

1. 데이터프레임 인스턴스 생성 및 데이터 로드

데이터 분석의 초기 공정은 다양한 소스의 원천 데이터를 Pandas의 핵심 객체인 Series 또는 DataFrame으로 적재(Loading)하는 과정이다.

데이터프레임의 직접 정의

import pandas as pd

# 데이터 본체(data), 행 식별자(index), 열 명칭(columns)을 명시하여 객체를 생성함
df = pd.DataFrame(data=data_source, index=idx_list, columns=col_list)

외부 데이터셋 가독 (CSV)

# index_col: 특정 열을 데이터프레임의 인덱스로 지정함
# header: 열 이름이 포함된 행의 번호를 지정하며, 부재 시 None으로 설정함
df = pd.read_csv("path/to/data.csv", index_col='Date')

2. 데이터 탐색 및 기술통계 (Exploration & Descriptive Statistics)

데이터의 물리적 구조, 자료형, 분포 및 결측치 현황을 파악함으로써 이후 전처리 전략의 기초를 수립하는 정찰 단계이다. 구조 및 메타데이터 참조

• df.head(n) / df.tail(n) : 데이터셋의 상위 및 하위 표본을 추출

• df.shape : 데이터프레임의 차원(행과 열의 개수)을 확인함

• df.info() : 인덱스 구성, 각 열의 자료형(dtypes) 및 비결측치(Non-Null) 개수 등 전체 요약을 출력함

• df.columns / df.index : 열 명칭 및 행 인덱스 정보를 참조함

• df.values : 내부 데이터를 Numpy 다차원 배열 형태로 반환함

통계적 특성 및 분포 파악

• df.describe() : 수치형 데이터에 대한 주요 기술통계량(평균, 표준편차, 사분위수 등)을 요약함

• df['col'].value_counts() : 범주형 데이터의 각 항목별 출현 빈도를 산출함

• df['col'].unique() / nunique() : 고유값의 목록 및 고유값의 총 개수를 확인함

• df['col'].mode() : 데이터셋 내 최빈값을 산출함

• df.sum(), df.mean(), df.median(), df.std() : 산술 합계, 평균, 중앙값, 표준편차 등 통계 함수를 적용함

3. 데이터 조회 및 필터링 (Selection & Filtering)

특정 분석 목적에 부합하는 서브셋(Subset)을 추출하기 위한 다양한 인덱싱 기법을 포함한다. 데이터 인덱싱 및 정렬

차원 선택

- df['col'] : 단일 열 추출 시 Series 객체가 반환됨

- df[['col1', 'col2']] : 다중 열 추출 시 리스트를 사용하여 DataFrame 형태를 유지함

조건부 조회 및 위치 기반 조회

- df.loc[row_condition, col_name] : 레이블 기반 조회 방식으로, 불리언 인덱싱(Boolean Indexing)을 통한 조건부 필터링에 최적화됨

- df.iloc[row_idx, col_idx] : 정수 위치 기반 조회 방식으로, 행과 열의 물리적 순서에 따라 데이터를 추출함

- df.isin([list]) : 특정 열의 값이 주어진 리스트 내에 포함되는지 여부를 판단하여 필터링함

정렬 프로토콜

- df.sort_values(by=['col1', 'col2'], ascending=[True, False]) : 복수의 열을 기준으로 정렬 방식을 개별 적용할 수 있음

4. 데이터프레임 구조의 변형 (Structural Modification)

열(Column) 및 행(Row) 관리

식별자 변경: df.rename(columns={'old': 'new'}, inplace=True)를 통해 특정 열의 명칭을 수정한 후 원본 객체에 직접 반영함

열의 추가 및 삽입:

- df['new_col'] = values : 데이터프레임의 최우측에 새로운 열을 추가함

- df.insert(pos, 'name', values) : 지정된 위치(pos)에 특정 열을 삽입하여 구조를 정밀하게 제어함

제거 프로세스:

- df.drop(list, axis=1, inplace=True) : 명시된 열 리스트를 제거함 (열 삭제 시 axis=1 설정 필수)

- df.pop('col') : 특정 열을 반환함과 동시에 원본 데이터프레임에서 영구히 삭제함

인덱스 재설정: df.reset_index(drop=True, inplace=True)는 기존 인덱스를 제거하고 연속적인 정수 인덱스로 초기화하는 공정으로, 데이터 결합 후 인덱스 정합성 확보를 위해 수행함

5. 데이터 가공 및 변환 (Transformation & Mapping)

데이터의 유효성을 확보하고 분석에 용이한 형태로 값을 변환하는 과정이다.

- replace() : 스칼라 값을 탐색하여 지정된 값으로 정밀하게 치환함

- map() : 딕셔너리 또는 함수를 매개로 Series의 개별 요소를 일대일 대응 변환함 (범주형 데이터 인코딩 시 유용함)

- pd.cut() : 수치형 연속 변수를 지정된 경계값에 따라 범주형 데이터로 이산화(Discretization)함

6. 결측치 관리 (Handling Missing Values)

데이터의 완전성을 저해하는 결측값(NaN)에 대한 체계적인 처리 방안을 명시한다.

• 현황 파악: df.isna().sum() 또는 df.isnull().sum()을 통해 열 단위 결측치 발생 빈도를 집계함

• 제거 전략: df.dropna(subset=['col'], axis=0, inplace=True)를 실행하여 특정 핵심 변수에 결측이 존재하는 레코드를 제외함

• 보간 및 대체: df.fillna(value) 또는 전방/후방 보간법(method='ffill'|'bfill')을 적용하여 결측값을 통계적 추정치로 대체함

7. 데이터 집계 및 그룹 연산 (Aggregation & Grouping)

특정 기준 열을 중심으로 데이터를 그룹화하여 고차원적 통계 정보를 추출하는 방법론이다. Groupby 연산

분할(Split)-적용(Apply)-결합(Combine) 패러다임을 통해 그룹별 분석을 수행함.

# 범주별 타겟 열에 대해 다중 통계량(합계, 평균 등)을 동시에 산출함
df.groupby('Category', as_index=True)['Target'].agg(['sum', 'mean'])

8. 데이터프레임 병합 및 연결 (Merging & Concatenation)

다양한 출처에서 기인한 데이터를 단일 데이터프레임으로 통합하는 고도화된 결합 기법이다. 물리적 연결 (Concat)

- axis=0 : 수직 방향 연결을 수행하며, 인덱스 중복 여부를 고려하여 reset_index를 병행할 것을 권장함

- axis=1 : 수평 방향 연결을 수행하며, 조인 방식(join='inner'|'outer')에 따라 데이터 유지 범위가 결정됨

논리적 병합 (Merge)

관계형 데이터베이스의 Join 연산과 유사하게 공통된 키(Key) 컬럼을 기준으로 데이터를 병합함.

- how='inner' : 양측 데이터프레임에 공통으로 존재하는 키값만을 추출함

- how='left' / 'right' : 좌측 또는 우측 데이터프레임을 기준으로 데이터를 유지하며, 대응값이 없는 경우 NaN으로 처리함

- how='outer' : 모든 데이터를 보존하는 완전 외부 조인을 수행함

생각정리

깃허브를 배우는 수업에서 VScode-Git-graph 이용법에 대해 배웠던 점이 인상 깊었다. 항상 터미널로 작업하던 입장으로써 눈으로 직관적으로 brnach들을 볼 수 있다는 점 그리고 간단하게 클릭으로 Checkout, Merge, Rebase, Reset, Revert 등을 적용할 수 있다는 점이다. 유용하게 프로젝트를 진행할 때 사용할 거 같았다. (코드 리뷰할 때도 편할 거 같았다)

데이터 전처리 코드를 수없이 봐왔던거 같다(캐글, 자격증 준비, 전공) 이번 1주차에서는 기본적인 내용으로 짧고 빠르게 많은 함수에 사용법을 알아가는 시간이었던 거 같다. 수업 시간이 09~18시까지 온라인으로 이어지다 보니 아침에 일어나 적응하는 시간이 아직 익숙해지지 않았던 거 같다. 날마다 체크인과 체크아웃 시간에 자기소개 시간을 가지며 같은 반 에이블러님들이 어떤 목표로 부트 캠프에 참여하게 된 걸 알게 되어 좋았던 거 같다. (같은 목표를 바라보는 에이블러님들이 많았던 거 같다) 자기소개 이외에 교육을 진행하는 동안 미래의 나에게 전하는 시간이 있었는데 (코딩테스트 업그레이드, 공모전 수상, 개근하기 등등)그 말을 이룰 수 있도록 열심히 임해 후회 없는 시간들을 보냈으면 좋겠다고 생각하며 1주 차를 마무리한다.

강사님의 말씀 중 "하루살이라고 생각하고 오늘 하루의 최선을 다하세요!"

Github-Private