Feature Flag 롤아웃 체크리스트

도입

Feature Flag는 배포와 릴리즈를 분리할 수 있어 강력하지만, 운영 규칙 없이 사용하면 기술 부채를 빠르게 만든다. 특히 실험 플래그와 운영 플래그를 구분하지 않으면 만료되지 않는 분기 코드가 누적된다. 이 글은 플래그 생성부터 삭제까지 전체 라이프사이클을 체크리스트 형태로 정리한다.

Feature Flag 롤아웃 체크리스트 커버 — Wikimedia Commons 기반 무료 이미지

문제 정의

플래그 장애는 보통 코드가 아니라 운영 절차 부재에서 발생한다.

플래그 소유자와 만료일이 없어 누구도 정리하지 않는다.
대상 세그먼트 정의가 모호해 의도치 않은 사용자에게 기능이 노출된다.
롤백 조건이 정해지지 않아 지표가 악화돼도 비활성화가 늦다.

플래그는 설정값이 아니라 운영 객체다. 생성 시점에 목적, 대상, 만료, 롤백 기준을 함께 정의해야 안전하다.

핵심 개념

관점	설계 기준	검증 포인트
분류	실험/운영/권한 플래그 구분	만료되지 않은 실험 플래그 수
승격 조건	핵심 지표 기반 단계별 확대	전환율, 에러율 변화
롤백	자동 비활성화 임계치 설정	경고 후 조치 시간
정리	만료 플래그 삭제 PR 의무	분기 코드 감소율

효율적인 방식은 템플릿 자동화다. 플래그 생성 CLI가 소유자와 만료일 입력을 강제하면 누락을 크게 줄일 수 있다.

코드 예시 1: 플래그 메타데이터 타입

export type FeatureFlag = {
  key: string;
  owner: string;
  expiresAt: string;
  kind: "experiment" | "operational" | "permission";
  rollout: { percent: number; segment?: string };
  rollbackGuard: { errorRatePct: number; latencyP95Ms: number };
};

export const signupFlowV2: FeatureFlag = {
  key: "signup_flow_v2",
  owner: "growth-team",
  expiresAt: "2026-06-30",
  kind: "experiment",
  rollout: { percent: 10, segment: "new_users" },
  rollbackGuard: { errorRatePct: 1.5, latencyP95Ms: 700 },
};

코드 예시 2: 승격/롤백 자동화 스크립트

#!/usr/bin/env bash
set -euo pipefail

FLAG_KEY=$1
ERROR_RATE=$(./scripts/metrics/error-rate.sh "$FLAG_KEY")
P95=$(./scripts/metrics/p95.sh "$FLAG_KEY")

if (( $(echo "$ERROR_RATE > 1.5" | bc -l) )) || (( P95 > 700 )); then
  ./scripts/flags/disable.sh "$FLAG_KEY"
  echo "rollback triggered"
  exit 0
fi

./scripts/flags/promote.sh "$FLAG_KEY" --step 10

echo "rollout promoted"

아키텍처 흐름

Mermaid diagram rendering...

트레이드오프

플래그 절차가 늘면 초기 속도는 느려지지만 장애 반경을 제어하기 쉬워진다.
자동 롤백은 안전하지만 잘못된 임계치 설정 시 과도한 롤백을 유발할 수 있다.
만료 정책을 엄격히 하면 코드 건강성은 좋아지지만 팀 운영 부담이 증가한다.

정리

Feature Flag 운영의 본질은 통제 가능성이다. 생성, 확장, 종료 단계를 명시하고 자동화하면 플래그가 기술 부채가 아니라 안전한 릴리즈 도구로 작동한다.

이미지 출처

Cover: source link
License: Public domain / Author: Robert Markowitz
Note: Wikimedia Commons 무료 라이선스 이미지를 다운로드 후 1600px 기준 JPG로 최적화했습니다.

도입