Kiro CLI Sync Agent - 개발 동기화 자동화 시스템

❌ 문제 상황

개발이 복잡해지면서 모델/DB/API/View 간 sync가 안 맞음
새 AI 세션마다 전체 구조를 다시 설명해야 함
수동으로 파일 찾아서 확인하는 비효율
컨텍스트 토큰 낭비

✅ 해결 방법

1시간마다 자동으로 전체 구조 추출
DB 스키마, API 엔드포인트, 프론트엔드 타입 자동 생성
동기화 검증 및 이슈 자동 탐지
통합 컨텍스트 문서 자동 생성 (AI용)

🏗️ 시스템 아키텍처

~/Documents/PromptLibrary/
├── .kiro/sync-agent/              # Kiro CLI 통합
│   ├── agent.py                  # 백그라운드 데몬 (1시간마다 실행)
│   ├── config.yaml               # 프로젝트별 설정
│   ├── agent.pid                 # 프로세스 ID
│   └── agent.log                 # 실행 로그
│
├── .sync-agent/generators/       # 생성기 모듈
│   ├── schema_generator.py       # DB 스키마 추출
│   ├── api_generator.py          # API 엔드포인트 추출
│   ├── frontend_generator.py     # 프론트엔드 타입 추출
│   ├── validator.py              # 동기화 검증
│   └── dev_context.py            # 통합 컨텍스트 생성
│
└── giftcall/docs/                # 자동 생성 파일
    ├── schema-map.json           # DB 스키마 구조
    ├── api-spec.json             # API 엔드포인트 목록
    ├── SYNC_REPORT.md            # 동기화 검증 리포트
    └── DEV_CONTEXT.md            # 통합 개발 컨텍스트 ⭐

✨ 주요 기능

📊 DB 스키마 추출

SQLAlchemy 모델에서 자동으로 테이블 구조, 컬럼 타입, 관계 추출

🔌 API 엔드포인트 추출

FastAPI 라우터에서 모든 엔드포인트 (GET, POST, PUT, DELETE) 자동 스캔

🎨 프론트엔드 타입 생성

Vue.js 서비스 파일에서 API 호출 패턴 추출 및 TypeScript 타입 생성

✅ 동기화 검증

모델/API/프론트엔드 간 불일치 자동 탐지 및 리포트 생성

📝 통합 컨텍스트

모든 정보를 하나의 마크다운 파일로 통합하여 AI가 쉽게 이해

⏰ 자동 실행

백그라운드 데몬으로 1시간마다 자동 실행 (설정 변경 가능)

📈 실제 결과

GiftCall 프로젝트 적용 결과

✅ 6개 모델 자동 추출 (User, Store, GiftOrder, GiftRecipient, RecipientMessage, RecipientChangeLog)
✅ 47개 API 엔드포인트 자동 스캔 (auth, gift_orders, recipients, stores, users, messages)
✅ 동기화 검증: 이슈 없음
✅ 통합 컨텍스트: 5.7KB (AI가 한 번에 파악 가능)

🚀 사용법

1. 자동 실행 (권장)

# 터미널 열 때마다 자동 시작 (zshrc에 추가됨)
# 또는 kiro-cli 실행 시 자동 시작
        

2. 수동 제어

# 상태 확인
python3 ~/Documents/PromptLibrary/.kiro/sync-agent/agent.py status

# 즉시 실행 (기다리지 않고 바로 업데이트)
python3 ~/Documents/PromptLibrary/.kiro/sync-agent/agent.py run

# 시작
python3 ~/Documents/PromptLibrary/.kiro/sync-agent/agent.py start

# 중지
python3 ~/Documents/PromptLibrary/.kiro/sync-agent/agent.py stop

# 로그 확인
tail -f ~/Documents/PromptLibrary/.kiro/sync-agent/agent.log
        

3. AI 세션 시작 시

# 이 파일을 컨텍스트로 제공
cat ~/Documents/PromptLibrary/giftcall/docs/DEV_CONTEXT.md
        

💡 팁: 같은 PC에서 여러 kiro-cli 세션을 실행해도 에이전트는 하나만 실행되며, 모든 세션이 동일한 파일을 공유합니다. 1시간마다 자동 업데이트되므로 항상 최신 정보를 유지할 수 있습니다.

⚙️ 설정

실행 주기 변경

# ~/.kiro/sync-agent/config.yaml
interval_minutes: 60  # 1시간 → 원하는 분으로 변경
        

새 프로젝트 추가

projects:
  - name: giftcall
    enabled: true
    generators:
      - schema_map
      - api_spec
      - frontend_types
      - sync_validator
      - dev_context
  
  - name: new-project
    path: ~/Documents/PromptLibrary/new-project
    enabled: true
    generators:
      - schema_map
      - api_spec
        

📊 효과 비교

Before (문제)

❌ 새 세션마다 전체 구조 설명 필요
❌ 모델/API/프론트엔드 불일치 발견 어려움
❌ 수동으로 파일 찾아서 확인
❌ 컨텍스트 토큰 낭비

After (해결)

✅ DEV_CONTEXT.md 하나로 전체 파악
✅ 1시간마다 자동 검증 및 업데이트
✅ 동기화 이슈 자동 탐지
✅ 효율적인 컨텍스트 관리

🛠️ 기술 스택

Python 3.13

백그라운드 데몬 및 생성기 구현

SQLAlchemy

DB 모델 introspection

정규표현식

API 엔드포인트 및 프론트엔드 패턴 추출

YAML

프로젝트별 설정 관리

🔮 향후 개선 계획

OpenAPI 스펙 자동 생성 (/openapi.json 활용)
TypeScript 타입 자동 생성 (openapi-typescript)
프론트엔드 API 호출 검증 (미사용 엔드포인트 탐지)
Slack/Discord 알림 (동기화 이슈 발생 시)
웹 대시보드 (실시간 상태 모니터링)

💼 실제 사례: GiftCall 프로젝트

배경

이마트 명절 선물세트 배송 업무 지원 시스템 개발 중, FastAPI 백엔드 + Vue.js 프론트엔드 + PostgreSQL DB의 복잡한 구조로 인해 새로운 AI 세션마다 전체 구조를 설명하는 데 많은 시간이 소요되었습니다.

적용 결과

개발 시간 단축: 새 세션 시작 시 5분 → 30초
동기화 이슈 조기 발견: 1시간마다 자동 검증
문서화 자동화: 수동 문서 작성 불필요
팀 협업 개선: 여러 개발자가 동일한 컨텍스트 공유

🤝 이 시스템을 공유하는 이유

이 시스템은 완벽하지 않습니다. 하지만 실제 개발 현장에서 겪은 문제를 해결하기 위해 만들어졌고, 비슷한 상황에 있는 다른 개발자들에게 도움이 될 수 있다고 생각했습니다.

개선 제안이나 피드백은 언제나 환영합니다. 함께 더 나은 도구를 만들어가면 좋겠습니다.

적용 가능한 상황

풀스택 개발 프로젝트 (백엔드 + 프론트엔드)
AI 어시스턴트를 활용한 개발
여러 개발자가 협업하는 프로젝트
복잡한 데이터 모델을 가진 시스템

📚 참고 자료

📄 라이선스

이 시스템은 MIT 라이선스로 공개됩니다. 자유롭게 사용, 수정, 배포할 수 있습니다.

👤 작성자

최은봉 (이마트 SAC팀) - 2025년 12월 26일

🤖 Kiro CLI Sync Agent