카카오클라우드 - 클라우드 개발자 교육 17주차 후기

공식적 프로젝트 진행기간이다. 

 

먼저 이전에 진행했던 프로젝트들의 경험으로 설계문서를 작성했다.

WBS(244건)

 

요구사항 정의서 (198건)

 테이블 정의서등

총 13개의 설계문서가 나왔다. 

초안에 비해 많이 보강되었지만 아직 설계 미스와, 부족한 부분이 많아 프로젝트를 진행하며 더 늘어날 것 같다.

 

먼저 기존에 조금씩 개발하던 agent 프로젝트의 패기지 구조를 잡았다.

 

1. Agent 패키지 구조 확정 (src/monglepick/):                                                                                                                     
  ├── api/              # API 레이어 (SSE/sync/upload 엔드포인트)
  ├── agents/           # LangGraph 에이전트 (Chat 13노드 + 추천 7노드)                                                                                         
  ├── chains/           # LLM 체인 (의도분류, 감정분석, 선호추출 등)                                                                                            
  ├── rag/              # 하이브리드 검색 (Qdrant + ES + Neo4j → RRF)                                                                                           
  ├── data_pipeline/    # 데이터 수집/정제/임베딩/적재                                                                                                          
  ├── db/               # DB 클라이언트 (5개 DB 싱글턴)                                                                                                         
  └── utils/            # 유틸리티

 

2. Git 저장소 손상 복구                                                                                                                                          
   
  monglepick-agent 로컬 저장소에서 error: bad tree object HEAD가 발생하여 기본 git 명령이 모두 실패하는 문제가 발생했습니다. 

iCloud 로 등록한 폴더에 프로젝트를 넣었더니 맥미니와 맥북의 싱크가 안맞거나, 파일이 깨지는 등의 이슈엿던거 같습니다. 문제를 확인하고 해결하다보니 

원인 분석:                                                                                                                                                    
  - HEAD 커밋이 참조하는 tree 객체가 누락
  - .git/objects 내 여러 tree/blob 객체가 손상                                                                                                                  
  - git mktree, git reset --hard 시 mmap failed: Operation timed out 에러 (디스크 I/O 이슈 추정)
                                                                                                                                                                
  해결 과정:                                                                                                                                                    
  1. 손상된 저장소를 monglepick-agent-corrupted로 백업                                                                                                          
  2. GitHub에서 새로 git clone 수행                                                                                                                             
  3. .env, .venv 등 로컬 설정 파일을 백업에서 복원

 

이런 결과 가 나왔는데 ai가 많은 도움을 주어 복구했습니다. 그리고 결론은 icloud동기화로 인해 꼬였던 문제 였습니다.

 

3. Git 브랜치 전략 확립 & PR 테스트
                                                                                                                                                                
  Client 레포지토리에서 첫 번째 PR(Pull Request #1)을 머지하며 팀의 Git Flow 워크플로우를 검증했습니다.                                                         
                                                                                                                                                                
  main          ← 운영 배포 (직접 push 금지)                                                                                                                    
    └─ develop  ← 개발 통합 (직접 push 금지)                                                                                                                    
         └─ feature/xxx  ← 기능 개발 (develop 기반 분기)                                                                                                        
                                                                                                                                                                
  팀원(이민수)도 Client 레포에서 테스트 커밋을 수행하며, PR 기반 협업 흐름이 정상 작동하는지 함께 확인했습니다.   

https://github.com/monglepick/monglepick-backend/blob/main/docs/팀원_Git_가이드.md

monglepick-backend/docs/팀원_Git_가이드.md at main · monglepick/monglepick-backend

이렇게 가이드를 만들고 조직레포에 rule과 hook을 등록해 직접적인 push merge 등등을 제한 했습니다.

 

4. gitaction 설정

CI/CD 파이프라인 구축 (4개 서비스)                                                                                                                         
                  
  GitHub Actions 기반으로 각 서비스의 스테이징 CI/CD를 설정했습니다.                                                                                            
             
  │ Backend   │ Gradle 빌드 + H2 테스트 DB + Docker 이미지 빌드   │ H2 테스트 DB 설정 추가 필요                  │

  │ Agent     │ uv sync + ruff lint + pytest + Docker 이미지 빌드 │ --no-frozen 옵션 비호환, ruff 실패→경고 전환 │                                              
                                        
  │ Client    │ npm install + build + Docker 이미지 빌드          │ self-hosted 러너 배포 설정                                                       
  │ Recommend │ 기본 빌드 + Docker 이미지 빌드                  '

 

스테이징 서버는 교육 업체에서 대여해준 m1 맥북에어에 설정해놓고 테스트 또한 등록해 파이프라인을 구축했습니다.

맥북에는 self-host runner를 통해 깃의 변경사항을 감지하고 자동배포 파이프라인을 실행합니다.

 

 

 1주차 요약
                                                                                                                                                                

  │   날짜    │                         핵심 작업                          │ 커밋 수 │                                                                          
 
  │ 3/9 (일)  │ 4개 서비스 초기 스캐폴딩, GitHub 레포 생성                 │ 5       │
  
  │ 3/10 (월) │ Git 저장소 복구, 브랜치 전략 수립, PR 테스트               │ 5       │                                                                          
                                                       
  │ 3/12 (수) │ CI/CD 파이프라인 4개 구축, 폴더 구조 리팩토링, 임베딩 검증 │ 12      │                                                                          
                                                                
  │ 3/13 (목) │ DDL 정합성 통합, 개발문서 기반 스키마 확장                 │ 4       │
                                                            
  │ 합계      │                                                            │ 26 커밋 │
 

  1. 4개 서비스 레포지토리 생성 및 초기 구조 확립 — 팀원 4명이 바로 개발에 착수할 수 있는 기반 마련련                                                             
  2. GitHub Actions 기반 CI/CD 파이프라인 — 4개 서비스 모두 자동 빌드/테스트/배포 환경 구축
  3. 도메인 기반 아키텍처 적용 — Backend(도메인 기반), Client(Feature-Sliced Design)로 팀원별 독립 작업 가능                                                    
  4. DB 스키마 단일 진실 원본 확립 — 멀티 서비스 간 데이터 정합성 보장                                                                                          
  5. 임베딩 파이프라인 검증 완료 — 308개 테스트 통과, 재적재 준비 완료     

 

 

 

 

—————————————————————————— 
본 후기는 [카카오엔터프라이즈x스나이퍼팩토리] 카카오클라우드로 배우는 AIaaS 마스터 클래스 3기(B-log) 리뷰로 작성 되었습니다.