AI 협업 환경 구축과 코드 자동화 시스템
1. AI 협업 환경 도입 배경
8월 초, 전체 개발 속도는 아키텍처 안정화와 함께 급격히 느려졌다. 다국어 코드베이스, 서비스 간 인터페이스 복잡도, 릴리즈 간 충돌 등으로 개발자가 직접 관리해야 할 영역이 지나치게 많았다. 단순 반복적인 테스트, 리뷰, 빌드 작업을 사람 대신 AI에게 맡기기로 했다.
목표는 다음과 같았다.
- AI가 코드 문맥을 이해하고 변경 사항을 요약 및 리뷰
- CI/CD 파이프라인과 직접 연동하여 코드 품질 평가
- Prompt Repository를 통한 코드 수정 자동화
- Telegram을 통한 빌드/배포 명령 및 상태 보고
핵심 원칙은 하나였다. AI는 코드를 생성하고 수정하지만, 최종 병합과 배포는 반드시 사람이 승인한다. 어떤 상황에서도 AI가 단독으로 프로덕션에 코드를 반영하는 일은 없도록 설계했다. 이 원칙은 이후 모든 자동화 시스템의 기본 전제가 되었다.
2. 환경 구성 — Cursor & Claude Code 기반 개발 체계
모든 개발 작업은 Cursor 에디터를 기본으로 통합했다. Cursor는 프로젝트의 디렉토리 구조와 문맥을 인식하여 Claude Code API와 연결된다. 개발자는 명령을 직접 내리지 않고, "의도(Prompt)"만 작성한다. 예를 들어 "상품 등록 API의 중복 검증 로직 최적화"라고 명시하면, Claude Code가 Git 브랜치를 생성하고 수정된 diff를 자동으로 커밋한다.
# Example of AI-generated commit
feat(product): optimize duplicate validation logic
- added Redis check before DB insert
- improved exception message consistency
- updated integration tests수정된 코드는 Drone CI가 자동으로 빌드하고, 테스트 결과를 Claude Code에 다시 전달한다. Claude는 테스트 로그를 분석해 실패 원인을 요약하고 제안 수정안을 생성한다. 성공률이 95% 이상일 경우만 main 브랜치로 병합된다.
GPT 계열 모델은 주로 문서 생성과 번역 검증에 활용되었다. 기술 문서의 초안 작성, API 문서의 다국어 변환, 코드 주석의 일관성 검증 등이 GPT가 담당하는 영역이었다. Claude가 코드 수정에 집중한다면, GPT는 코드 이외의 텍스트 품질을 관리하는 역할로 분리되었다.
3. Prompt Repository와 자동 리뷰 시스템
AI 협업의 핵심은 일관된 지시 체계였다.
우리는 "Prompt Repository"를 Git 내부에 별도로 구성했다.
각 기능 단위로 AI가 참조할 프롬프트 템플릿을 정의했다.
예를 들어 prompts/api_review.md에는 코드 리뷰 기준이 다음과 같이 명시되었다.
### API Review Rules
1. 모든 API는 3단계 검증 (입력 -> 검증 -> 응답)을 따라야 함
2. 로깅은 Cloud Function 호출 직전 최소 1회 기록
3. 예외는 200 OK 이외의 모든 응답 코드에서 명확한 메시지 반환
4. 함수당 최대 길이 80라인 이하
Claude Code는 코드 변경이 감지될 때마다 이 문서를 읽고 자동 리뷰를 수행한다.
오류나 규칙 위반이 감지되면 MQ를 통해 review.failed 이벤트를 발행한다.
Cloud Function은 이 이벤트를 받아 Telegram 알림을 전송한다.
Code Review Failed
File: api/product/create.py
Line: 42
Issue: Missing validation on product_name field
Suggested fix: add regex check before DB insert
개발자는 Telegram에서 /approve 명령으로 AI의 제안을 승인하거나 /reject로 무시할 수 있다.
승인된 제안은 자동으로 브랜치에 반영되어 재테스트가 수행된다.
4. AI가 생성한 코드의 Hallucination 방지
AI 코드 생성에서 가장 위험한 부분은 hallucination이다. 존재하지 않는 라이브러리를 import하거나, 없는 API 엔드포인트를 호출하거나, 실제 DB 스키마와 다른 컬럼명을 사용하는 경우가 대표적이다. 이런 문제는 컴파일 에러로 잡히기도 하지만, 런타임에서야 드러나는 경우가 더 많았다.
이를 방지하기 위해 세 가지 가드레일을 적용했다.
- 1단계: AI가 생성한 코드의 import 목록을 requirements.txt와 대조
- 2단계: 함수 호출 대상이 실제 코드베이스에 존재하는지 AST 분석으로 검증
- 3단계: DB 관련 코드는 실제 스키마 메타데이터와 컬럼명을 자동 대조
# Hallucination guard example
imports = extract_imports(generated_code)
for mod in imports:
if mod not in KNOWN_MODULES:
reject("Unknown module referenced: " + mod)
columns = extract_column_refs(generated_code)
for col in columns:
if col not in schema_metadata[table]:
reject("Column not found in schema: " + col)이 검증 파이프라인 도입 후, AI가 생성한 코드에서 발생하는 런타임 에러가 크게 감소했다. 특히 DB 관련 hallucination은 사전 차단율이 높아져 프로덕션 장애로 이어지는 케이스가 사라졌다.
5. AI 빌드 및 배포 자동화
Drone CI와 Claude Code는 서로 독립적으로 작동하지만, AI Ops-Agent가 이 둘을 연결했다. Ops-Agent는 빌드가 성공하면 Claude에게 로그를 전달하고, 실패 시 Claude가 자동으로 재시도할 수 있도록 Prompt Repository에서 "fix pipeline" 명령을 실행한다.
if build.status == "failed":
prompt = prompts.get("fix_pipeline")
suggestion = claude.analyze(build.logs, prompt)
if "retry" in suggestion:
publish("ci.retry", {"build_id": build.id})빌드 로그 분석 결과, 테스트 실패의 62%는 의존성 충돌이었다. Claude는 requirements.txt를 자동으로 업데이트하고 재빌드하도록 설정되었다. 모든 과정은 Telegram에서 실시간으로 확인 가능했다.
6. 테스트 코드 자동 생성과 커버리지 관리
AI 협업에서 가장 실질적인 효과를 보인 영역은 테스트 생성이었다. 기존에는 개발자가 기능 코드를 작성한 후 테스트를 별도로 작성했지만, Claude Code 도입 후에는 기능 코드와 테스트 코드가 동시에 생성된다. Claude는 함수의 입력/출력 타입, 예외 조건, 경계값을 분석하여 단위 테스트와 통합 테스트를 자동으로 생성한다.
# AI-generated test example
def test_create_order_duplicate_check():
"""동일 idempotency_key로 중복 주문 방지"""
result1 = create_order({"key": "abc123", "product": "SKU001"})
result2 = create_order({"key": "abc123", "product": "SKU001"})
assert result1["order_id"] == result2["order_id"]
assert get_order_count("abc123") == 1테스트 커버리지 기준은 80% 이상으로 설정되었으며, Claude가 생성한 테스트만으로 평균 84%의 커버리지가 달성되었다. 부족한 부분은 개발자가 수동으로 보완하되, AI가 어떤 영역이 미달인지 Telegram으로 리포트를 보내주기 때문에 우선순위를 빠르게 판단할 수 있었다.
7. 코드 품질 점수화 및 AI 학습 피드백
8월 중순 이후 AI가 생성한 코드가 사람보다 빠르지만, 품질 일관성 문제는 남아 있었다. 이를 해결하기 위해 "Code Quality Scoring" 시스템을 도입했다. Claude는 모든 커밋에 대해 가독성, 일관성, 테스트 커버리지, 예외 처리 항목을 점수화한다. 80점 미만 커밋은 Drone이 자동으로 main 병합을 차단했다.
{
"commit": "5f3a2b",
"readability": 0.91,
"consistency": 0.86,
"coverage": 0.73,
"exception_handling": 0.9,
"score": 85.0
}Claude는 점수가 낮은 부분을 학습 데이터로 반영하여 이후 수정안 품질을 향상시켰다. 평균 코드 품질 점수는 초기 78점에서 89점으로 향상되었다.
8. 기술 문서 자동 생성과 다국어 번역
코드 자동화와 함께 문서화 영역도 AI가 담당하게 되었다. 새로운 API가 추가되면 Claude가 OpenAPI 스펙 기반의 문서를 자동 생성하고, GPT가 이를 한국어, 영어, 태국어, 중국어로 번역한다. 번역된 문서는 Git에 자동 커밋되어 항상 최신 상태를 유지한다.
기술 용어의 번역 일관성을 위해 내부 Glossary를 운영한다. 예를 들어 "견적"은 영어로 "quotation", 태국어로 "ใบเสนอราคา"로 고정되어 있으며, AI가 다른 표현을 사용하면 자동으로 교정된다. 이 Glossary는 3,000개 이상의 B2B 무역 용어를 포함하고 있다.
9. AI와 개발자의 협업 방식
이 시점부터 사람은 '코드를 작성하는 주체'가 아니라 '의도를 전달하는 관리자'로 역할이 바뀌었다. 개발자는 하루 업무 시작 시 "오늘의 기능 계획"을 입력하면, AI는 자동으로 하위 태스크를 생성해 Git 이슈를 등록했다. AI가 생성한 코드 중 92%는 수동 수정 없이 배포되었다. 나머지 8%는 에러 핸들링이나 국가별 특수 규칙(예: 언어 구문 차이)에서 조정이 필요했다.
AI는 변경사항을 요약해 다음과 같이 보고했다.
*Daily Summary*
- Added new endpoint: /v1/order/confirm
- Updated Redis TTL policy to 12h
- Fixed concurrency bug in cache invalidation
- All tests passed (74/74)중요한 점은 AI의 모든 작업이 투명하게 기록된다는 것이다. 어떤 프롬프트로 어떤 코드가 생성되었는지, 어떤 리뷰 규칙이 적용되었는지, 어떤 테스트가 통과하고 실패했는지가 전부 MQ 이벤트 로그로 남는다. 사후 감사가 가능하고, 문제가 발생하면 AI의 판단 근거를 역추적할 수 있다.
10. 보안 및 접근 제어
AI가 Git push 권한을 갖는 것은 위험 요소였다.
실수로 중요 설정 파일을 수정하거나, 외부 API 키를 노출할 가능성이 있었다.
이를 방지하기 위해 AI 계정의 권한을 "Draft Commit"으로 제한했다.
모든 병합은 사람이 Telegram /merge 명령으로 승인해야만 진행된다.
보안 로그는 별도의 Cloud Function에서 감시된다. 예기치 않은 diff가 감지되면 Ops-Agent가 즉시 병합을 차단하고 Telegram으로 알림을 보냈다. 이 방식은 중국, 태국 등지의 외부 네트워크 환경에서도 안정적으로 작동했다.
특히 .env 파일, 인증서, API 키가 포함된 파일은 AI의 접근 대상에서 완전히 제외되었다.
AI가 이 파일들을 읽거나 수정하려는 시도 자체가 이벤트로 기록되고,
해당 세션이 즉시 종료되도록 설정했다.
11. 결론 및 현재 상태
AI 협업 환경이 완전히 정착한 이후, 코드 작성 속도는 기존 대비 2.4배, 리뷰 속도는 4배 향상되었다. 평균 커밋당 에러율은 7.2%에서 1.3%로 감소했다. 개발자는 설계와 결정에 집중할 수 있게 되었으며, AI는 일관된 규칙을 유지하며 지속적으로 코드 품질을 보정한다.
현재 전체 코드베이스의 68% 이상이 AI 자동 생성이며, 나머지는 특수 국가 로직, 보안 모듈 등 사람이 직접 검증이 필요한 영역이다. REINDEERS의 개발 체계는 "AI가 주도하고 사람이 승인하는 구조"로 완전히 전환되었다.
다만 여기서 "AI가 주도한다"는 것은 AI가 의사결정을 한다는 뜻이 아니다. AI는 사람이 정의한 규칙과 프롬프트에 따라 실행하는 도구이며, 모든 최종 판단은 사람의 승인을 거친다. 이 경계를 유지하는 것이 AI 협업 환경의 가장 중요한 원칙이다.