오늘만 무료

2026 AI 시대 팀 개발 운용 가이드

AI 코드 리뷰·개인정보 반출 규정·기술 부채 관리 국내 기업

Mar 19. 2026 brunch_membership's

이 장을 읽기 전에: Git의 기본(1장 1.4절)을 이해하고 있을 것.

좋은 팀은 개별 엔지니어가 특별히 뛰어나기 때문에 강한 것이 아니라, 같은 판단을 몇 번이고 재현할 수 있기 때문에 강하다. 브랜치 운용, 리뷰, 문서, 온보딩과 같은 평범한 구조가 개발 속도와 품질의 상한을 결정한다.

� 한국 시장 맥락: 국내 주요 IT 기업(카카오·네이버·토스·라인)은 GitHub를 코드 관리 표준으로 사용하며, GitHub Flow 또는 Trunk-Based Development를 중심으로 운용한다. 공공·금융·SI 환경은 SVN 또는 사내 GitLab을 사용하는 경우가 여전히 많다.

1. Git 브랜치 전략

이 섹션이 답하는 질문: 어떤 브랜치 운용을 선택해야 하는가. 어디까지 규칙을 늘려야 하는가.

왜 필요한가

팀 개발에서는 변경을 안전하게 통합하는 구조가 필요하다. 브랜치 전략이 애매하면 리뷰 누락, 충돌, 릴리스 사고가 늘어난다.

브랜치 전략 플로

실무에서의 원칙

브랜치는 단명으로 한다 (최대 1~2일)

PR은 작게 나눈다 (리뷰 가능한 크기: 400줄 이하 권장)

main에 직접 커밋은 원칙적으로 피한다

머지 조건을 CI와 리뷰로 명확하게 한다 (Protected Branch 설정)

장수명 브랜치에서 사양 차이를 쌓지 않는다

# GitHub Protected Branch 설정 예시 (.github/branch-protection.yml)

# 또는 GitHub Settings > Branches에서 직접 설정

protection_rules:

- pattern: "main"

required_status_checks:

- "CI: 린트 / 타입 / 테스트"

- "CI: 보안 스캔"

required_pull_request_reviews:

required_approving_review_count: 1

dismiss_stale_reviews: true

require_linear_history: true

allow_force_pushes: false

국내 커밋 메시지 컨벤션

# Conventional Commits — 국내 표준 (카카오·네이버·토스 공통)

feat(주문): 카카오페이 결제 연동 추가

fix(인증): 네이버 로그인 토큰 만료 처리 수정

docs(README): 로컬 개발 환경 설정 가이드 업데이트

refactor(서비스): 주문 서비스 레이어 분리

test(결제): 토스페이먼츠 결제 완료 E2E 테스트 추가

chore(deps): Spring Boot 3.3 → 3.4 업그레이드

⚠️ 막히면 GitHub Flow로 충분한 경우가 많다. 규칙을 늘리는 것은 기존 운용으로 명확하게 곤란해지고 나서도 좋다.

정리

브랜치 전략은 복잡성이 아니라, 통합 빈도와 릴리스의 쉬움으로 선택한다. 먼저 단명 브랜치와 작은 PR을 철저히 한다.

2. 코드 리뷰의 문화와 진행 방법

이 섹션이 답하는 질문: 리뷰를 형해화시키지 않고, 품질 향상으로 연결하려면 어떻게 하는가.

왜 필요한가

코드 리뷰의 목적은 승인 스탬프가 아니다. 버그의 조기 발견, 일관성 유지, 지식 공유가 주된 가치다.

리뷰에서 최소한 봐야 할 항목

사양대로 동작하는가

인증·인가나 입력 검증에 구멍이 없는가 (IDOR, SQL 인젝션)

실패 시의 동작이 정의되어 있는가

테스트가 정말로 의도를 검증하고 있는가

변경 후 운용에서 곤란하지 않은가

개인정보 처리 방식이 개인정보보호법에 맞는가 (로그 마스킹 등)

PR 리뷰 코멘트 수준 레이블

[nit] 작은 제안 (반영 여부 작성자 재량)

> 변수명이 더 명확하면 좋을 것 같아요: `items` → `orderItems`

[suggestion] 개선 제안 (반영 권장)

> 이 부분은 Kotlin의 `let` 대신 `apply`가 더 적합해 보입니다.

[question] 의도 확인

> 여기서 null 체크가 필요하지 않은 이유가 있을까요?

[blocker] 머지 전 반드시 수정 필요

> 이 쿼리는 SQL 인젝션 취약점이 있어 반드시 수정이 필요합니다.

AI를 사용하는 경우의 주의점

AI에 의한 요약이나 리뷰 보조는 유효하지만, 최종 판단은 인간이 갖는다. 특히 다음은 자동 코멘트만으로 처리하지 않는다.

인가 로직

과금·결제 처리

데이터 삭제·비식별화

외부 공개 API

보안 설정

⚠️ LGTM만 반환하는 리뷰는, 안 하는 것과 대차가 없다. 변경을 읽은 흔적이 남는 리뷰를 수행한다.

정리

리뷰 품질은 PR 크기, 관점의 명확성, 응답 속도로 결정된다. AI는 보조에 사용하고, 인간은 책임 있는 판단에 집중한다.

3. 문서화

이 섹션이 답하는 질문: 무엇을 문서화하고, 어디까지 남겨야 하는가.

왜 필요한가

코드는 "무엇을 하고 있는가"는 보여줄 수 있어도, "왜 그렇게 했는가"는 남기기 어렵다. 배경이 남지 않으면, 같은 논의와 같은 실패를 반복한다.

최소한 필요한 문서

ADR의 최소 템플릿

# ADR-001: 결제 게이트웨이 선정

## 상태

채용

## 배경

국내 결제 연동에서 토스페이먼츠·카카오페이·NHN KCP 중 선택이 필요했다.

주요 고려 사항: 개발자 경험, 문서 품질, 수수료, 정산 주기.

## 결정

토스페이먼츠를 주 결제 수단으로 채택.

## 이유

- 공식 문서와 SDK 품질이 가장 우수함

- 카카오·네이버 간편결제를 단일 SDK로 통합 가능

- 개발자 커뮤니티 지원이 활발함

## 영향

- 장점: 개발 속도 향상, 통합 관리 용이

- 단점: 토스페이먼츠 단일 의존. 추후 NHN KCP 추가 시 별도 구현 필요

README에 최소한 넣어야 할 것

이 리포지토리가 무엇인가

기동 수순 (Docker Compose 또는 로컬 실행)

필요한 환경 변수 (.env.example 참조)

테스트 방법

자주 막히는 부분 (한국어 인코딩, 카카오·네이버 SDK 설정 등)

AI 시대에 문서의 가치가 올라가는 이유

AI 지원을 사용하면, 문서는 인간용뿐만 아니라 미래의 자신이나 AI에 대한 컨텍스트가 된다. 단, 문서가 오래되면 오유도의 원인이 되므로, 양보다 업데이트성을 우선한다.

정리

README와 ADR을 최소한으로 좋으니 남긴다. 쓰는 것보다, 코드 변경에 맞춰 업데이트되는 것이 더 중요하다.

4. 개발 프로세스의 선택 방법

이 섹션이 답하는 질문: 스크럼, 칸반 등을 어떻게 선택하고, 어떻게 가볍게 운용하는가.

판단의 기준

끼어들기가 많다면 칸반 방향

목표를 기간으로 나누고 싶다면 스크럼 방향

현실에서는 양쪽이 섞이므로, 처음부터 완벽한 형태를 목표로 하지 않는다

실무에서의 원칙

규칙은 적게 시작한다

병목을 가시화한다

회고(레트로)에서 1가지만 개선한다

프로세스를 지키는 것 자체를 목적으로 하지 않는다

� 국내 협업 도구: 토스·당근마켓·카카오엔터 등은 Jira + Confluence 또는 노션 + GitHub Issues 조합을 많이 사용한다. 두레이(Dooray!)·카카오워크는 일부 기업·공공기관에서 그룹웨어와 함께 사용된다.

정리

좋은 프로세스는 현장의 마찰을 줄인다. 팀에 맞지 않는 의식은 줄이고, 효과 있는 규칙만 남긴다.

5. 기술 부채 관리

이 섹션이 답하는 질문: "나중에 고친다"를 어떻게 방치하지 않고 다루는가.

왜 필요한가

기술 부채는 제로로 만들 수 없지만, 보이지 않게 하면 위험하다. 부채 그 자체보다, "아무도 파악하지 않은 상태"가 문제다.

관리 방법

부채를 일람화한다 (Jira 에픽 또는 GitHub Issues 라벨 활용)

영향과 상환 비용을 견적한다

통상 개발 중에 조금씩 갚는다 (보이스카우트 규칙: 건드린 곳은 조금 더 좋게)

보안 부채만은 뒤로 미루지 않는다 (개인정보보호법·ISMS-P)

상환의 원칙

건드린 부분은 조금 좋게 하여 돌아온다

큰 부채는 작게 나누어 갚는다 (에픽 → 스토리)

신기능 개발과 완전히 분리하지 않는다

정리

부채 관리는 정신론이 아니라 재고 관리에 가깝다. 가시화하고, 우선순위를 붙이고, 지속적으로 줄인다.

6. 온보딩과 지식 공유

이 섹션이 답하는 질문: 새로운 멤버가 빠르게 전력이 되려면 무엇이 필요한가.

왜 필요한가

온보딩이 약하면 같은 질문이 반복되고, 리뷰 비용도 올라간다. 반대로 초기 도선이 갖춰져 있으면 새 멤버는 빠르게 안전하게 움직일 수 있다.

첫 1주일에 달성하고 싶은 것

개발 환경을 재현할 수 있다 (Docker Compose 또는 로컬 설정)

README를 읽고 기동할 수 있다

작은 PR을 1건 내어 머지까지 경험한다

시스템 구성과 주요 업무 용어를 설명받는다

카카오·네이버 소셜 로그인·결제 연동의 테스트 방법을 이해한다 (국내 서비스 특이사항)

신규 멤버 온보딩 체크리스트 예시

## 온보딩 체크리스트 (첫 1주)

### 환경 구축

- [ ] GitHub 계정에 org 초대 및 권한 부여

- [ ] .env 파일 설정 (팀 리드에게 요청)

- [ ] 로컬 개발 환경 기동 확인 (`make dev` 또는 `docker-compose up`)

- [ ] 테스트 실행 확인 (`npm test` / `./gradlew test`)

### 코드베이스 이해

- [ ] README 및 docs/adr/ 읽기

- [ ] 주요 도메인 코드 산책 (주문·결제·회원)

- [ ] 배포 파이프라인 확인 (GitHub Actions)

### 첫 PR

- [ ] 작은 버그 수정 또는 문서 업데이트 PR 제출

- [ ] 코드 리뷰 경험

- [ ] main 머지 완료

### 업무 맥락

- [ ] 서비스 아키텍처 다이어그램 설명 받기

- [ ] 인시던트 대응 절차 (Runbook) 위치 확인

- [ ] 슬랙/카카오워크 채널 참여

지식 공유에서 효과 있는 구조

AI 지원을 사용하는 신인 교육에서의 주의점

AI는 학습 보조가 되지만, 생성 결과를 읽지 않고 채용하는 버릇은 위험하다. 새 멤버에게는 다음을 명시한다.

AI의 제안은 반드시 읽고, 설명할 수 있는 상태로 한다

테스트를 통과했을 뿐 이해한 것으로는 하지 않는다

모르는 부분은 리뷰에서 질문한다 (AI보다 팀원에게 먼저 확인)

정리

온보딩에서는 환경 구축, 첫 PR, 업무 문맥의 이해를 빠르게 돌린다. 지식 공유는 선의에만 맡기지 않고, 구조로 만든다.

7. AI 시대의 팀 개발

이 섹션이 답하는 질문: AI를 사용하는 전제로, 팀의 규칙은 어떻게 바뀌어야 하는가.

AI가 늘리는 것은 구현 속도만이 아니다. 리뷰 양, 검증 부하, 정보 관리의 중요성도 늘어난다.

AI 이용 가이드라인 예시 (팀 내 규정)

## AI 코딩 도구 이용 가이드라인

### 사용 허가 범위

- ✅ 코드 자동 완성 (Copilot, Cursor)

- ✅ 테스트 케이스 초안 생성

- ✅ 주석·문서 작성 보조

- ✅ 리팩터링 제안

### 주의가 필요한 범위

- ⚠️ 인증·인가 로직 (반드시 인간 리뷰)

- ⚠️ 결제·과금 처리 (토스페이먼츠·카카오페이 API)

- ⚠️ 개인정보 처리 로직 (PIPA 대응)

- ⚠️ 외부 공개 API 설계

### 금지 사항

- ❌ 고객 개인정보를 외부 AI 서비스에 전송

- ❌ 미공개 영업 기밀·소스코드를 외부 AI에 입력

- ❌ AI 생성 코드를 테스트 없이 그대로 본번 배포

- ❌ AI 생성 코드임을 PR에서 숨기기

팀에 필요한 공통 인식

AI는 보조자이며, 책임 주체가 아니다

빠르게 쓰는 것보다, 빠르게 안전하게 고칠 수 있는 것이 중요하다

생성물은 "초안"으로 취급한다

문서와 테스트의 가치는 오히려 올라간다

⚠️ AI 도입에서 처음에 정비해야 할 것은 도구의 비교표가 아니라, "어떤 정보를 보내도 되는가", "누가 최종 승인하는가", "무엇을 반드시 검증하는가"의 3가지다.

정리

AI 시대의 팀 개발에서 중요한 것은 속도 그 자체가 아니라, 속도를 안전하게 다루는 운용이다. 도구 선정보다 먼저, 책임, 정보 관리, 검증의 규칙을 결정한다.

8. 국내 팀 개발 실무 특이사항

이 섹션은 원문에 없는 내용으로, 한국 개발 현장에 맞게 보완한 내용이다.

국내 주요 기업 개발 문화 참고

협업 도구 스택 패턴

## 국내 스타트업 표준 협업 스택

### 코드 관리

- GitHub (코드 호스팅 + PR 리뷰 + GitHub Actions CI)

### 이슈·프로젝트 관리

- Jira + Confluence (중간 규모 이상)

- GitHub Issues + Notion (스타트업)

- Linear (빠른 이슈 관리)

### 커뮤니케이션

- 슬랙 (국내 스타트업 표준)

- 카카오워크 (카카오 계열 및 일부 중소기업)

- 두레이(Dooray!) (NHN 계열 및 일부 기업)

- Microsoft Teams (공공·금융·대기업)

### 문서화

- Notion (스타트업 표준)

- Confluence + Jira (중견 이상)

- GitHub Wiki / docs/ 폴더 (개발 문서)

야근·워크라이프 밸런스와 개발 프로세스

## 지속 가능한 팀 개발을 위한 프로세스 원칙

- 릴리스 배포는 업무 시간 내에 (야간·주말 긴급 배포 최소화)

- 인시던트 온콜 체제를 명확히 하고 보상 규정 마련

- 스프린트 오버타임은 기술 부채의 신호로 인식

- 회고에서 프로세스 개선 사항을 백로그에 등록

## 국내 법정 의무 준수

- 근로기준법: 연장 근로 한도 (주 12시간) 준수

- 중대재해처벌법: IT 분야 적용 범위 확인

- 개인정보보호법: 개발 과정에서 개인정보 처리 절차 준수

✅ 이 장의 체크리스트

자신의 팀에 맞는 브랜치 전략을 설명할 수 있는가?

리뷰에서 최소한 봐야 할 관점을 공유할 수 있는가?

README, ADR, 운용 수순서의 역할을 설명할 수 있는가?

프로세스를 목적화하지 않고, 개선 대상으로 다룰 수 있는가?

기술 부채를 가시화하여 우선순위를 매길 수 있는가?

온보딩에서 첫 1주일에 무엇을 달성해야 하는지 설명할 수 있는가?

AI 이용 시의 책임 분계, 정보 관리, 검증 규칙을 정하고 있는가?

고객 개인정보를 외부 AI 서비스에 전송할 때의 주의사항을 설명할 수 있는가?

Conventional Commits 컨벤션을 팀에서 표준화하는 이유를 설명할 수 있는가?

⚠️ 편집 노트: 본 문서는 지속적으로 보완 중입니다. 국내 기업 기술 블로그의 개발 문화 사례(토스·카카오·네이버), GitHub Actions Protected Branch 최신 설정, AI 코딩 도구 가이드라인 변화는 각 공식 문서와 기술 블로그를 통해 최신 정보를 확인하세요.