신규 기능을 메인 브랜치에 넣고도 사용자에게 바로 켜지 않으려면, 배포와 공개를 분리하는 스위치가 필요합니다. 기능 플래그(Feature Flag, Feature Toggle)는 그 스위치입니다. 코드는 이미 프로덕션에 있고, 켜짐 비율·대상 사용자·긴급 끄기만 운영에서 바꿉니다.
아래는 도입 전 판단부터 네이밍·점진 공개·킬스위치·측정·정리까지 약 40항목 체크리스트입니다. 사례 중심 도입기는 언리시 피처 플래그 6주 사례를, 배포 전 공통 게이트는 프로덕션 배포 체크리스트를 같이 보세요.
플래그가 없으면 “금요일 핫픽스”와 “전체 롤백” 사이에 중간 카드가 없습니다. 반대로 모든 한 줄 수정에 플래그를 붙이면 플래그 자체가 제품 설정 시스템이 되어 관리 비용이 커집니다. 먼저 표로 갈라 보세요.
| 상황 | 플래그 권장 | 대안 |
|---|
| UI·API 계약이 바뀌는 사용자 노출 기능 | 필수에 가깝다 | 장시간 피처 브랜치(충돌 비용↑) |
| 결제·권한·데이터 삭제 경로 | 필수 + 이중 확인 | 스테이징만으로는 부족 |
| A/B·점진 공개(1%→10%→100%) | 필수 | 서버 전체 배포 비율만으로는 사용자 단위 제어 어려움 |
| 순수 버그픽스·오타·내부 리팩터 | 보통 불필요 | 일반 PR + 빠른 롤백 |
| 스키마 파괴 마이그레이션만 | 플래그만으로 부족 | 확장-수축 마이그레이션 + 호환 기간 |
마틴 파울러의 기능 토글 글은 플래그를 릴리스 토글·실험 토글·옵스 토글·권한 토글로 나눕니다. 타입이 다르면 수명·소유·기본값 정책도 달라집니다. 같은 “on/off”라도 실험용 7일 토글과 엔터프라이즈 권한 토글을 한 바구니 관리하면 사고가 납니다.
도구(언리시·런치다크리·플립퍼·홈그로운)보다 타입 합의가 먼저입니다. 타입 없이 키만 늘어나면 6개월 뒤 “이게 왜 아직 있지?” 목록만 남습니다.
오픈피처(OpenFeature)는 벤더 SDK를 추상화하는 표준 API입니다. 팀이 나중에 언리시에서 다른 제공자로 옮겨도 앱 코드의 평가 인터페이스를 유지하려는 경우 후보입니다. 도입 초기 단일 도구로 충분하면 굳이 추상화 레이어를 먼저 깔 필요는 없습니다.
키 이름만 보고 “누가, 왜, 언제까지”를 알 수 없으면 정리 단계에서 막힙니다. 슬랙에 “checkout_v2 꺼도 되나요?”가 반복되면 네이밍 규칙이 실패한 겁니다.
같은 키라도 브라우저에서 평가하면 사용자가 우회할 수 있고, 서버에서만 평가하면 정적 페이지·CDN 캐시와 충돌할 수 있습니다. 보안·캐시·일관성을 한 번에 점검하세요.
롤아웃은 “켜기 버튼”이 아니라 관측 가능한 단계입니다. 비율만 올리고 지표·로그·온콜 합의가 없으면 장애를 천천히 키우는 장치가 됩니다.
비율 해시는 보통 userId 기준 sticky가 필요합니다. 새로고침할 때마다 집단이 바뀌면 실험이 깨지고, 지원 팀도 재현을 못 합니다. 익명 트래픽만 있는 랜딩이면 세션·쿠키 정책을 개인정보 고지와 맞춰 두세요.
플래그 키는 로그·트레이스·제품 이벤트에 같이 남아야 “어느 변형에서 터졌는지”를 10분 안에 좁힙니다. 구조화 로그 필드는 구조화 로깅 체크리스트와 키 이름을 맞추는 편이 좋습니다.
코드 리뷰에서 플래그를 “나중에 지우면 되지”로 넘기면 기술 부채가 쌓입니다. 코드 리뷰 체크리스트에 아래 항목을 한 블록으로 끼워 넣으세요.
플래그 성공의 마지막 단계는 삭제입니다. 100% on이 된 릴리스 토글을 코드에 남기면 분기가 영구 부채가 됩니다. 주간 또는 스프린트 단위로 “만료 임박” 목록을 돌리세요.
소팀은 Postgres/Redis + 관리 UI로도 시작합니다. 트래픽·감사·다변량·스트림이 필요해지면 언리시·런치다크리·클라우드비·플래그스미스 등 관리형을 봅니다. 선택 기준만 체크하세요.
| 항목 | 직접 구현 | 관리형·오픈소스 플랫폼 |
|---|
| 초기 비용 | 낮음 | 구독·호스팅 |
| 감사·RBAC·SSO | 직접 구현 부담 | 대체로 기본 제공 |
| 스트리밍·엣지 지연 | 설계 난이도 높음 | SDK·엣지 연동 문서화 |
| 벤더 잠금 | 없음 | OpenFeature 등으로 완화 가능 |
| 적합한 규모 | 소팀·소수 키 | 다팀·실험·규정 요구 |
언리시 도입 과정의 팀 변화는 피처 플래그 6주 사례에 정리되어 있습니다. 이 글의 체크리스트는 도구와 무관하게 PR·롤아웃·정리에 공통으로 붙일 수 있습니다.
실무에서 막히지 않게 순서를 한 줄로 고정합니다.
- 판정 — 표의 “권장” 행인지 확인. 아니면 일반 PR.
- 타입·키·만료 — 메타 필수 필드 채운 뒤 콘솔/코드에 키 생성(기본 off).
- 분기 구현 — 서버 게이트 우선, 테스트 on/off, PR 템플릿 체크.
- 스테이징 토글 — 폴백 UX·로그 필드·대시보드 확인.
- 프로덕션 배포 — 코드 배포(아직 off) → 내부 → 소비율 → 승급.
- 관측 — 단계마다 에러·지연·가드레일. 이상 시 킬스위치.
- 정리 — 100% 안정 후 분기 제거·키 삭제·문서 갱신.
의존성 봇 PR처럼 “자동으로 켜지는” 변경과 플래그 롤아웃을 같은 주에 겹치면 원인 분리가 어렵습니다. 대규모 의존성 흡수 주는 의존성 업데이트 체크리스트 일정과 롤아웃 주를 어긋나게 배치하세요.
기능 플래그와 환경 변수(FEATURE_X=true)는 무엇이 다른가요?
환경 변수 스위치는 배포·재시작 단위로 바뀌는 경우가 많고, 사용자 비율·세그먼트·감사 로그가 약합니다. 기능 플래그 플랫폼은 런타임 변경, 점진 공개, 컨텍스트 기반 타기팅, 변경 이력을 전제로 합니다. 정말 전역 on/off 하나면 env로도 되지만, 1% 롤아웃이 필요하면 플래그 쪽이 맞습니다.
플래그 없이 장기 피처 브랜치만 쓰면 안 되나요?
가능은 합니다. 다만 메인이 매일 움직이면 머지 충돌·통합 지연·“큰 날 배포” 리스크가 커집니다. 플래그는 작은 단위로 메인에 합류시키고 공개만 늦추는 타협입니다. 브랜치 수명이 길수록 리뷰·CI 비용도 같이 올라갑니다.
클라이언트 SDK만으로 결제 기능을 막아도 되나요?
안 됩니다. UI 숨김은 우회 가능합니다. 결제·권한·데이터 변경 API는 서버에서 동일 정책으로 거절해야 합니다. 클라이언트 플래그는 경험 최적화용, 서버 플래그는 안전장치용으로 역할을 나누세요.
100% 켠 뒤에도 플래그 키를 남겨 두어도 되나요?
짧은 관찰 기간은 괜찮습니다. 그 이후에도 분기를 남기면 읽기 비용·테스트 행렬·실수 on/off가 쌓입니다. 릴리스 토글은 코드 고정 후 키 삭제를 기본 규칙으로 두는 편이 안전합니다. 권한·옵스 토글만 장기 키로 분류하세요.
소규모 사이드 프로젝트에도 관리형 플래그가 필요한가요?
필수는 아닙니다. 사용자 수가 적고 배포가 자유로우면 env·간단 설정 테이블로 시작할 수 있습니다. 다만 “일부 사용자만 베타”가 반복되고 지원 문의가 생기면 그때 플랫폼을 검토해도 늦지 않습니다. 먼저 이 글의 네이밍·기본값·정리 규칙만 지켜도 부채가 줄어듭니다.
OpenFeature를 처음부터 도입해야 하나요?
단일 도구·소수 서비스면 네이티브 SDK로 충분합니다. 여러 언어·여러 팀이 같은 평가 모델을 쓰거나 벤더 이전을 염두에 둘 때 OpenFeature가 이득입니다. 추상화 레이어 자체가 비용이므로, 실제 이전·다중 백엔드 계획이 있을 때 도입하는 편이 낫습니다.
