개발 환경과 문화의 표준화 — 코드, 협업, 그리고 사람의 일하는 방식

1. 개발 환경의 목표 — '사람 없이도 일관된 결과'

REINDEERS의 개발 환경은 단 하나의 목표를 갖고 설계되었다. "사람이 없어도 코드 품질과 배포 결과가 동일해야 한다."

이를 위해 모든 개발 환경은 완전히 동일한 컨테이너 기반으로 세팅되었고, 환경 편차나 로컬 의존성 문제는 제거되었다. 개인의 환경은 존재하지 않으며, 모든 환경은 dev, staging, production 세 단계로 통합 관리된다.

이 목표가 생긴 배경이 있다. 팀이 네 번 교체되면서 매번 겪었던 문제가 "내 PC에서는 되는데 서버에서는 안 된다"였다. 운영체제 버전, 런타임 버전, 로컬에 설치된 라이브러리의 차이가 빌드 결과의 불일치를 만들어냈다. 특히 4개국(태국, 한국, 중국, 말레이시아)에 분산된 개발자들이 각자 다른 환경에서 작업하면 이 문제는 기하급수적으로 커진다. 컨테이너화된 개발 환경은 이 문제를 원천적으로 해결한다. 누가, 어디서 빌드하든 결과가 동일하다.

표준 개발 환경 구조

# Dockerfile (공용 개발환경)
FROM node:20-bullseye

RUN apt-get update && \
    apt-get install -y python3 python3-pip vim curl git && \
    pip install pre-commit flake8

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .

CMD ["npm", "run", "dev"]

모든 개발자는 동일한 컨테이너 이미지를 사용하며, 코드 수정 시 Drone의 pre-flight build가 자동 수행되어 린트, 테스트, 의존성 검증이 완료되어야만 PR이 생성된다.

2. Git 워크플로우 — 브랜치 전략과 커밋 규칙

Git 워크플로우는 팀 전체의 코드 품질을 결정짓는 기반이다. REINDEERS는 Git Flow를 기반으로 하되, 몇 가지 강화된 규칙을 적용한다.

main        → 프로덕션 (자동 배포, 직접 커밋 금지)
develop     → 통합 테스트 환경
feature/*   → 기능 단위 브랜치
release/*   → 사전 배포 검증
hotfix/*    → 긴급 수정 (최소 1인 리뷰 필수)

커밋 메시지는 Conventional Commits 형식을 따른다. feat:, fix:, refactor:, docs:, test:, chore: 등의 접두어가 필수이며, 이 형식에 맞지 않는 커밋은 pre-commit hook에서 거부된다. 서명된 커밋만 허용하여 "누가 이 코드를 작성했는가"를 추적 가능하게 했다.

브랜치 네이밍도 규칙이 있다. feature/CELL-A/i18n-currency-selector처럼 셀 이름과 기능 설명이 포함되어야 한다. 이렇게 하면 브랜치 목록만 봐도 어떤 셀이 무슨 작업을 하고 있는지 파악할 수 있다. 4개국에 분산된 팀에서 이 가시성은 매우 중요하다.

3. 코드 리뷰 프로세스 — AI + 사람의 이중 검증

코드 리뷰는 두 단계로 진행된다. 1차는 AI 리뷰, 2차는 셀(Cell) 단위 검증이다. AI 리뷰는 구조적 오류, 보안 위험, 성능 병목을 탐지하고, 사람이 직접 보는 리뷰는 비즈니스 로직 검증에 집중한다.

AI 리뷰가 확인하는 항목은 다음과 같다.

보안 취약점: SQL 인젝션 가능성, 하드코딩된 시크릿, XSS 위험
코딩 컨벤션: 네이밍 규칙, 파일 크기 제한(800줄), 함수 크기 제한(50줄)
성능: N+1 쿼리 패턴, 불필요한 반복문 내 DB 호출
타입 안전성: 타입 정의 누락, any 타입 사용

사람 리뷰는 AI가 판단하기 어려운 영역에 집중한다. "이 환율 변환 로직이 태국 세관의 최신 규정에 부합하는가", "이 물류 상태 변경이 실제 해운사의 선적 프로세스와 일치하는가" 같은 도메인 특화 검증이다. 두 단계 모두 통과해야 Merge가 가능하며, AI 리뷰에서 CRITICAL 등급이 나오면 사람 리뷰 자체가 차단된다.

AI 코드 리뷰 자동화 (파이프라인 내)

kind: pipeline
type: docker
name: ai-review

trigger:
  event: [ pull_request ]

steps:
  - name: static-analysis
    commands:
      - run security scanner on ./src
      - run lint checks

  - name: ai-review
    commands:
      - analyze code style and security risk
      - post review comments to PR

AI 리뷰 결과는 Git PR에 자동 코멘트로 남는다. 리뷰어는 승인만 하면 되며, 모든 내용은 로그로 아카이브된다.

4. 네이밍 컨벤션 — 4개국이 같은 언어를 쓰는 방법

태국 개발자, 한국 개발자, 중국 개발자가 하나의 코드베이스에서 작업한다. 각자의 모국어가 다르기 때문에, 코드에서 사용하는 "이름"에 대한 합의가 필수적이다.

REINDEERS의 네이밍 규칙은 다음과 같다.

모든 변수, 함수, 파일명은 영어로 작성한다. 예외 없다.
비즈니스 도메인 용어는 용어집(glossary)에 정의된 영어 표현을 사용한다. 예: 견적서 = Quote, 구매주문서 = PO, 송장 = Invoice
약어는 용어집에 등록된 것만 허용한다. 임의 약어 금지.
컴포넌트 파일: PascalCase (QuoteDetail.vue)
유틸리티 파일: camelCase (formatCurrency.ts)
API 라우트: kebab-case (/api/purchase-orders)
DB 테이블/컬럼: snake_case (order_po, currency_code)

코드 리뷰에서 네이밍 규칙 위반은 자동 탐지되어 PR 코멘트로 남는다. 처음에는 번거롭게 느껴졌지만, 이 규칙 덕분에 태국 개발자가 작성한 코드를 한국 개발자가 즉시 이해할 수 있게 되었다. 코드가 곧 문서가 되려면, 이름이 명확해야 한다.

5. 타임존 관리 — 비동기 우선 원칙

태국(GMT+7), 한국(GMT+9), 중국(GMT+8), 말레이시아(GMT+8). 최대 2시간의 시차지만, 각국의 업무 패턴이 달라 실질적 겹침은 하루 4~5시간 정도다.

이 제약을 극복하기 위해 "비동기 우선(async-first)" 원칙을 채택했다.

실시간 회의: 주 1회, 30분 이내. 모든 국가가 업무 시간인 오전 10시(한국 기준)에 진행.
의사결정: PR 코멘트와 기술 문서를 통해 비동기적으로 진행. 24시간 내 응답 원칙.
긴급 상황: Telegram 알림 채널을 통해 즉시 공유. 장애 대응은 해당 시간대의 당번이 처리.
인터페이스 합의: MQ 이벤트 스키마와 API 명세를 먼저 정의하고, 구현은 각자의 시간대에서 독립 진행.

코드 리뷰도 비동기로 돌아간다. 한국 팀이 퇴근 전에 올린 PR을 태국 팀이 다음 날 아침에 리뷰하고, 그 피드백을 한국 팀이 오전에 확인하여 반영한다. 이 사이클이 매끄럽게 동작하려면 PR의 설명이 충분히 상세해야 한다. "왜 이 변경이 필요한가", "어떤 영향 범위가 있는가"를 PR 본문에 명확히 기술하는 것이 규칙이다.

6. 커뮤니케이션 도구 — 도구는 줄이고 자동화는 늘린다

REINDEERS는 Jira, Notion 같은 별도의 프로젝트 관리 도구를 사용하지 않는다. 도구가 많아지면 정보가 분산되고, "어디에 최신 정보가 있는가"를 찾는 것 자체가 업무가 된다.

대신 Git 저장소가 진실의 단일 원천(Single Source of Truth)이다. 코드, 문서, API 명세, 데이터 스키마(DBML), 배포 설정 모두가 Git에서 버전 관리된다. 작업 추적은 GitHub Issues와 PR로 처리하고, 실시간 알림은 Telegram으로 집중한다.

Telegram은 단순한 메신저가 아니라 모니터링 채널 역할을 한다. 배포 결과, 장애 알림, 환율 수집 실패, DTS 복제 지연 등 시스템에서 발생하는 모든 이상 징후가 Telegram으로 즉시 전달된다. 개발자는 Telegram 알림만 확인하면 시스템 상태를 파악할 수 있다.

7. 배포 문화 — '한 명이 아니라 시스템이 한다'

REINDEERS의 배포는 100% 자동화되어 있다. 코드 병합 → Drone 파이프라인 실행 → COS/CDN 배포 → 헬스체크 → Grafana 피드백의 완전 폐루프다. 배포 인가는 자동 검증이 통과된 브랜치만 허용된다.

배포 절차 개요

git push origin main
Drone CI → 빌드/테스트/배포
CDN 캐시 무효화
헬스체크 후 알림 채널에 리포트

수동 배포는 금지되어 있다. SSH로 서버에 접속하여 직접 배포하는 행위는 감사(audit) 로그에 기록되며, 해당 변경은 즉시 롤백된다. 이 규칙이 엄격한 이유는 수동 배포가 만드는 "재현 불가능한 상태" 때문이다. 파이프라인을 거치지 않은 배포는 어떤 버전이 서버에 올라가 있는지 추적할 수 없게 만든다.

8. 개발 문화의 6가지 원칙

REINDEERS의 개발 문화는 여섯 가지 원칙으로 정의된다.

No Manual Deploy — 수동 배포 금지. CI/CD만 사용.
No Silent Commit — 모든 커밋은 서명 필수.
No Local Config — 모든 환경변수는 KMS 기반 관리.
Always Observable — 모든 API와 함수는 모니터링 대상.
Data-Driven Change — 코드보다 데이터 우선.
AI-Assisted Everything — 반복은 모두 자동화.

이 원칙을 통해 개인 역량에 관계없이 동일한 품질의 결과가 유지된다. 원칙 3번 "No Local Config"는 특히 중요하다. 환경 변수를 로컬 .env 파일로 관리하면, 개발자마다 다른 설정값을 가지게 되고 "내 환경에서는 동작하는데 스테이징에서는 안 된다"는 문제가 반복된다. KMS 기반 관리는 모든 환경의 설정값이 중앙에서 일원화되어 환경 간 불일치를 원천적으로 방지한다.

9. 일관성 유지의 핵심 — 자동화된 품질 게이트

4개국에 분산된 팀이 동일한 품질 기준을 유지하는 것은 규칙만으로는 불가능하다. 규칙을 강제하는 자동화 장치가 필요하다.

Pre-commit hook: 커밋 메시지 형식 검증, 린트 자동 실행
CI 게이트: 테스트 통과, 커버리지 기준, 보안 스캔 통과 필수
PR 템플릿: 변경 사유, 영향 범위, 테스트 계획 필수 기재
AI 리뷰: 자동 코드 품질 분석 및 PR 코멘트
배포 후 헬스체크: 배포 완료 후 자동 검증, 실패 시 롤백

이 게이트들을 모두 통과한 코드만이 프로덕션에 도달한다. 사람이 "이번은 급하니까 건너뛰자"고 결정할 수 있는 여지를 시스템적으로 차단한다. 엄격해 보이지만, 이 구조 덕분에 배포 후 장애 발생률이 극적으로 낮아졌다.

10. 결론 — 개발환경이 곧 문화다

REINDEERS는 개발 환경, 프로세스, 문화가 모두 하나의 구조 안에 녹아 있다. "사람이 시스템을 운영한다"는 개념 대신 "시스템이 사람의 역할을 대체하고, 개발자는 구조를 설계한다"는 철학이 정착했다.

표준화의 진짜 가치는 "제약"이 아니라 "자유"에 있다. 환경 설정, 배포 절차, 코드 리뷰 같은 반복적인 의사결정에서 해방되면 개발자는 정말 중요한 일 — 아키텍처 설계, 도메인 로직 구현, 사용자 경험 개선 — 에 집중할 수 있다. 4개국에 걸친 팀이 하나의 플랫폼을 만들어가는 과정에서, 이 표준화가 없었다면 지금의 결과물은 불가능했을 것이다.

Blog

Search This Blog