"엔지니어의 역할이 코드를 작성하는 사람에서, AI가 안전하게 코드를 작성할 수 있는 환경을 설계하는 사람으로 바뀐다."

충격적인 숫자들

2026년 2월, OpenAI가 내부 실험 결과를 공개했다.

• 엔지니어 3→7명
• 5개월 동안 100만 줄 코드 생산
• 수동으로 작성한 코드: 0줄
• PR 약 1,500개 머지
• 엔지니어당 하루 3.5개 PR

가장 놀라운 건, 팀원이 늘어날수록 속도가 빨라졌다는 것이다. 소프트웨어 공학의 고전 법칙인 브룩스의 법칙("지연되는 프로젝트에 인력을 추가하면 더 늦어진다")을 정면으로 반박한 결과다. 에이전트 간에는 커뮤니케이션 오버헤드가 없기 때문이다.

OpenAI는 이 방법론에 Harness Engineering(하네스 엔지니어링)이라는 이름을 붙였다.

Harness Engineering이 뭔데?

"하네스"는 원래 말(馬)에 씌우는 장비다. 강력하지만 예측 불가능한 동물의 힘을 방향 있게 쓰기 위한 도구 — 고삐, 안장, 울타리.

AI 에이전트에 대입하면:

정의: 아키텍처 제약, 피드백 루프, 관측성, 문서 시스템, 자동 품질 관리를 포함하는 구조화된 환경을 구축하여 AI 코딩 에이전트가 프로덕션 수준에서 안정적으로 작동하게 하는 학문.

프롬프트 → 컨텍스트 → 하네스: 3단계 진화

┌──────────────────────────────────────┐
│      Harness Engineering (하네스)      │  시스템이 무엇을 막고, 측정하고, 고치는가?
│  ┌──────────────────────────────────┐ │
│  │    Context Engineering (컨텍스트)   │ │  에이전트가 무엇을 보는가?
│  │  ┌──────────────────────────────┐ │ │
│  │  │   Prompt Engineering (프롬프트) │ │ │  지시문을 어떻게 쓰는가?
│  │  └──────────────────────────────┘ │ │
│  └──────────────────────────────────┘ │
└──────────────────────────────────────┘

• 프롬프트 엔지니어링: "이렇게 해줘" — 단발성 지시 최적화
• 컨텍스트 엔지니어링: "이것들을 참고해서 해줘" — 도구, RAG, 메모리, 스키마 설계
• 하네스 엔지니어링: "이 울타리 안에서, 이 피드백을 받으며, 이 품질 기준으로 해줘" — 제약 + 관측 + 자동 교정

핵심 차이를 한 마디로:

컨텍스트는 에이전트가 "무엇을 아는가"를 다루고, 하네스는 "무엇이 잘못될 수 있고 어떻게 막는가"를 다룬다.

OpenAI가 정의한 세 가지 기둥

1. Context Engineering — 에이전트의 눈

"에이전트가 볼 수 없는 것은 존재하지 않는다."

Slack에만 있는 결정, Google Docs에만 있는 설계 문서는 에이전트에게 없는 것이나 마찬가지다.

실천법:

• AGENTS.md는 백과사전이 아니라 목차 (~100줄)
• 실제 지식은 docs/ 디렉토리에 구조화
• ExecPlan(실행 계획서) 작성 — 초보자도 구현 가능한 수준의 자족적 설계 문서
• ExecPlan이 잘 작성되면 에이전트가 7시간 이상 무인 작업 가능

프로젝트/
├── AGENTS.md          ← 100줄짜리 목차
├── docs/
│   ├── architecture.md
│   ├── conventions.md
│   ├── gotchas.md     ← 자주 틀리는 것들
│   └── plans/
│       └── feature-x.md  ← ExecPlan

2. Architectural Constraints — 보이지 않는 울타리

"기계적으로 강제할 수 없으면, 에이전트는 반드시 벗어난다."

OpenAI는 6계층 의존성 아키텍처를 강제했다:

Types → Config → Repo → Service → Runtime → UI
          (의존성 방향: 오직 왼→오른쪽만 허용)

• 커스텀 린터가 위반을 감지하면 빌드 즉시 실패
• 이 린터 자체도 Codex 에이전트가 작성했다
• 에러 메시지가 단순 경고가 아니라 교육적 해결법을 포함 — "매 실패 메시지가 다음 시도의 컨텍스트가 된다"

3. Garbage Collection — AI 쓰레기 청소부

코드가 100만 줄이 되면, 문서는 빠르게 낡는다. 처음엔 매주 금요일에 사람이 "AI slop"을 정리했지만, 확장이 안 됐다.

해결책: 백그라운드 에이전트를 돌렸다.

• 낡은 문서 감지 → 자동 정리 PR 생성
• 아키텍처 위반 탐지 → 자동 리팩토링 PR
• 품질 기준 위반 → 자동 수정

"인간의 취향을 한 번 캡처하고, 지속적으로 강제한다."

Vibe Coding vs. Harness Engineering

요즘 "바이브 코딩"이라는 말을 많이 듣는다. 대충 말하면 AI가 알아서 코드를 짜주는 것. 재미있고 빠르다. 하지만 프로덕션에서는?

2025년 8월, 18명의 CTO를 대상으로 한 설문에서 16명이 AI 생성 코드로 인한 프로덕션 장애를 경험했다고 답했다.

가장 생산적인 패턴은 둘의 결합이다: 하네스로 울타리를 치고, 그 안에서 바이브하게 코딩한다.

그리고 숫자가 증명한다. Can.ac 벤치마크에서 하네스만 바꿨을 뿐인데, 모델 가중치는 건드리지 않고:

• Grok Code Fast 1: 6.7% → 68.3% 성공률
• GPT-4 Turbo: 26% → 59% 성공률

모델보다 하네스가 더 큰 성능 변수라는 뜻이다.

핵심 원칙 5가지

OpenAI의 100만 줄 실험에서 추출한 원칙들:

1. 에이전트가 볼 수 없는 것은 존재하지 않는다

모든 결정을 마크다운, 스키마, ExecPlan으로 레포에 기록한다. Slack 대화? Google Docs? 에이전트에겐 존재하지 않는 것이다.

2. "왜 실패했지?"가 아니라 "어떤 능력이 부족한가?"

에이전트 실패 = 디버깅 대상이 아니라 설계 입력. 실패할 때마다 하네스에 도구/규칙/문서를 추가한다.

3. 문서보다 기계적 강제

사람이 "이렇게 해주세요"라고 써놓는 것보다, 린터가 "이건 안 됩니다"라고 빌드를 실패시키는 게 100배 효과적이다.

4. 에이전트에게 눈을 줘라

Chrome DevTools Protocol로 실제 UI를 보게 하고, 로그/메트릭으로 성능을 확인하게 한다.

5. 매뉴얼이 아니라 지도

100줄짜리 조감도. 아키텍처 경계만 명확히. 압도적인 세부사항은 오히려 해롭다.

여기까지가 개념이다. 이제 직접 해본 이야기를 하겠다.

실전 적용: Flutter 앱과 Next.js 웹에 같은 하네스를 씌우다

프로젝트 소개

나는 사이드 프로젝트로 반려동물 건강 기록 서비스를 만들고 있다. 두 개의 코드베이스가 하나의 서비스를 이룬다.

• PetLog App (Flutter + Supabase): 보호자가 매일 쓰는 앱. 건강 기록, 접종 일정, 사료 관리
• PetLog Web (Next.js + Supabase): 수의사/관리자용 대시보드. 통계 시각화, 환자 이력 조회

같은 Supabase DB를 바라보는 두 코드베이스:

  [Flutter App]  ──→  Supabase  ←──  [Next.js Web]
   (데이터 생산)        (DB)         (데이터 소비)

기술 스택이 완전히 다르다. 하나는 Dart, 하나는 TypeScript. 하지만 하네스의 구조는 동일하게 적용할 수 있었다.

Before: 문서는 있었는데 왜 안 됐나

두 프로젝트 모두 CLAUDE.md와 docs/는 이미 있었다. 아키텍처 규칙도, Golden Principles도 정의해뒀다.

# 기존 CLAUDE.md (발췌)
## Golden Principles
1. Clean Architecture 3레이어 준수: domain/ → data/ → presentation/
2. 상태관리는 Riverpod provider만
3. Feature 간 직접 import 금지 — core/를 통해서만 공유

꽤 괜찮아 보인다. 문제는 이걸 가지고 "기능 만들어줘"라고 하면 에이전트가:

1. 문서를 읽긴 하는데, 설계 없이 바로 코딩 시작
2. 중간에 아키텍처 위반해서 삽질 → 롤백
3. 끝나고 나서야 "아, 이거 주의사항이었는데" 하고 깨달음
4. 다음 세션에선 같은 실수 반복

원인은 명확했다. 문서는 있었지만, "문서를 언제, 어떤 순서로, 어떻게 써야 하는지"를 정의하지 않았던 것이다.

규칙은 있는데 절차가 없었다. 마치 교통법규는 있는데 신호등이 없는 교차로 같았다.

After: 4단계 워크플로우 프로토콜

CLAUDE.md에 에이전트의 행동 절차를 추가했다:

## 🔒 에이전트 워크플로우 프로토콜

### Phase 1: 분석 (자동)
→ 의도 파악, 코드베이스 탐색, docs/ 전체 읽기

### Phase 2: 설계 (자동 → 사용자 승인)
→ ExecPlan 작성 → 사용자에게 보여주고 승인 요청
→ ⚠️ 승인 없이 구현 시작 금지

### Phase 3: 구현 (단계별 체크포인트)
→ 매 단계마다 린트 + 빌드 + 테스트 확인 후 커밋

### Phase 4: 검증 보고
→ 완료 기준 체크 + 최종 요약

핵심 발견: 프로토콜은 동일하고, 체크포인트만 스택별로 다르다.

프로토콜이라는 울타리는 같지만, 울타리 안의 도구는 각 스택에 맞게 교체한 것이다. 아키텍처 규칙도 마찬가지다:

[Flutter App]                    [Next.js Web]
domain/ → data/ → presentation/  types/ → lib/ → components/ → app/
(역방향 import 금지)              (역방향 import 금지)

표현은 다르지만, "의존성은 한 방향으로만 흐른다"는 원칙은 동일하다.

실전 시나리오: "알림 기능 만들어줘"

이 한 마디를 입력하면 이제 이런 일이 벌어진다.

Phase 1: 분석 (자동 — 나는 기다리기만)

[에이전트]
  CLAUDE.md 읽기 → 워크플로우 프로토콜 인식 ✓
  docs/ARCHITECTURE.md → Clean Architecture 3-layer 확인 ✓
  docs/CONVENTIONS.md → Riverpod + Freezed 패턴 확인 ✓
  docs/gotchas.md → "domain에 Supabase import 금지" 확인 ✓
  기존 features/ 패턴 분석 → notification/ 모듈 구조 설계 ✓

Phase 2: 설계 → 내 승인

📋 ExecPlan을 작성했습니다.

목적: 접종 일정 D-3, D-1, 당일 푸시 알림 자동 발송
범위: FCM 기반 로컬 스케줄링 + Supabase Edge Function 트리거

영향 분석:
| 파일                                    | 변경   |
|-----------------------------------------|--------|
| lib/features/notification/domain/       | 신규   |
| lib/features/notification/data/         | 신규   |
| lib/features/notification/presentation/ | 신규   |
| supabase/functions/schedule-notify/     | 신규   |

아키텍처 결정:
- domain에 Supabase import 없음 (gotcha 준수)
- FCM 토큰 관리는 data 레이어에서만

구현 4단계:
1단계: Domain 모델 + Repository 인터페이스
2단계: Data 레이어 (Supabase + FCM 구현체)
3단계: Presentation (알림 설정 화면)
4단계: Edge Function + 통합 테스트

이대로 진행할까요?

나: "좋아, 근데 알림 시간 커스텀도 추가해줘"

에이전트가 ExecPlan 수정 → 재확인 → 승인 후 구현 시작.

Phase 3: 단계별 자동 구현

━━━ 1단계: Domain 모델 ━━━
flutter analyze ✅ → flutter test ✅ → 커밋 💾

━━━ 2단계: Data 레이어 ━━━
flutter analyze ✅ → check_architecture.sh ✅ → 커밋 💾

━━━ 3단계: Presentation ━━━
flutter analyze ❌ → "presentation에서 Supabase 직접 import 감지"
🔧 자동 수정 → data 레이어 경유로 변경
📝 gotchas.md 업데이트: "NotificationSettingsPage에서 SupabaseClient 직접 사용 금지"
flutter analyze ✅ → 커밋 💾

━━━ 4단계: Edge Function + 테스트 ━━━
flutter test ✅ (전체 통과) → 커밋 💾

3단계에서 에이전트가 아키텍처를 위반했지만, check_architecture.sh가 즉시 잡았고, 에이전트가 스스로 수정한 뒤 gotchas.md에 기록까지 했다. 다음 세션에선 같은 실수를 하지 않는다.

Phase 4: 검증 보고

📊 구현 완료

완료 기준 체크:
✅ 접종 D-3, D-1, 당일 알림 스케줄링
✅ 알림 시간 커스텀 (오전 9시 / 오후 12시 / 오후 6시)
✅ FCM 토큰 갱신 로직
✅ 전체 테스트 통과
✅ check_architecture.sh 통과

새로 발견된 사항:
📝 gotchas.md에 1건 추가

커밋 4개 생성, 각 단계별 롤백 가능합니다.

내가 한 일: 한 줄 요청 + "좋아" 1번 + 방향 조정 1번. 에이전트의 자율 행동: 코드 분석, ExecPlan 설계, 4단계 구현, 아키텍처 위반 자동 수정, gotchas 기록, 검증 보고.

같은 기능을 Next.js 웹에 추가할 때도 같은 프로토콜이 작동한다. 체크포인트만 flutter analyze → npm run lint로 바뀔 뿐이다.

gotchas.md — 하네스의 성장 엔진

하네스를 세팅하는 건 시작일 뿐이다. 진짜 가치는 사용할수록 gotchas가 쌓인다는 것이다.

1주차:  3건 → 에이전트가 자주 삽질
2주차:  8건 → 삽질 절반으로 감소
3주차: 12건 → 거의 한 번에 통과
1개월: 15건 → 에이전트가 나보다 규칙을 잘 지킴

실제 기록 예시:

## Flutter
### domain에 Supabase import 금지
- domain/ 레이어에서 Supabase 패키지 직접 import하면 아키텍처 위반
- ✅ data/ 레이어에서만 Supabase 접근

### Riverpod provider 추가 후 코드 생성 필수
- provider 추가/수정 후 반드시 build_runner 실행

## Next.js
### "use client" 누락
- 클라이언트 훅 사용하는 컴포넌트에 선언 필수

### any 타입 금지
- 모든 데이터는 types/api.ts에 타입 정의 후 사용

체감 변화

한계와 비판도 있다

모든 것이 장밋빛은 아니다.

검증 부재 문제 — Martin Fowler 사이트의 Birgitta Böckeler가 지적: OpenAI 글에는 "시스템이 실제로 올바르게 작동하는지 검증하는 방법"에 대한 논의가 없다.

레트로핏 문제 — 성공 사례 대부분이 그린필드 프로젝트다. 10년 된 레거시에 하네스를 적용하는 건 완전히 다른 문제다.

초기 투자 비용 — OpenAI의 하네스를 구축하는 데 5개월이 걸렸다.

과잉 엔지니어링 위험 — 하네스에 너무 많은 로직을 넣으면 모델 업데이트 시 깨진다. Manus는 6개월 동안 5번 리팩토링했다.

배운 것들

1. 규칙보다 절차가 중요하다

Golden Principles를 아무리 잘 써놔도, "언제 읽고, 어떤 순서로 적용하고, 위반하면 어떻게 하는지"를 정의하지 않으면 에이전트는 규칙을 무시한다.

규칙 = 교통법규. 프로토콜 = 신호등.

2. 프로토콜은 한 번 만들면 어디든 복붙

CLAUDE.md = 프로젝트 고유 정보 + 범용 워크플로우 프로토콜
             (프로젝트마다 다름)   (모든 프로젝트에 동일)

Flutter든 Next.js든 Spring Boot든 Swift든, "분석 → 설계 → 승인 → 구현 → 검증"은 변하지 않는다.

3. 승인 단계는 과잉이 아니라 시간 절약

승인 없이 바로 구현했다가 방향이 틀리면 전부 롤백해야 한다. 30초짜리 "좋아, 진행해"가 30분짜리 삽질을 막아준다.

4. 에이전트 실패 = 하네스 설계 입력

에이전트가 실수하면 "왜 실패했지?"가 아니라 "어떤 규칙이 빠져있지?"를 묻는다.

하네스는 쓸수록 강해진다. 에이전트의 모든 실수가 미래의 성공을 만드는 재료가 된다.

당장 시작하는 법

복잡하게 생각할 것 없다. 지금 작업 중인 프로젝트의 CLAUDE.md(또는 AGENTS.md)에 이것만 추가하면 된다:

## 🔒 워크플로우 프로토콜

모든 기능 구현 요청 시:
1. 분석: 관련 코드/문서 탐색 (자동)
2. 설계: 계획 작성 → 사용자 승인 (승인 없이 구현 시작 금지)
3. 구현: 단계별 빌드+테스트 확인 후 커밋
4. 검증: 완료 기준 체크 + 결과 보고

이 8줄이 에이전트의 행동을 근본적으로 바꾼다.

그리고 빈 파일 하나:

# gotchas.md
> 에이전트가 실패할 때마다 여기에 기록한다.

이 파일은 지금은 비어있지만, 한 달 뒤에는 당신의 가장 가치 있는 엔지니어링 자산이 될 것이다.

마무리: 패러다임이 바뀌었다

하네스 엔지니어링의 본질은 이것이다:

병목은 환경이었다. 에이전트에게 코드를 짤 능력이 부족했던 게 아니라, 구조와 도구와 피드백과 명확한 제약이 부족했던 것이다.

우리는 지금 "코드를 잘 짜는 사람"에서 "코드가 안전하게 생성되는 환경을 설계하는 사람" 으로의 전환점에 서 있다.

프롬프트를 잘 쓰는 것보다, 컨텍스트를 잘 설계하는 것보다, 결국 하네스를 얼마나 견고하게 짓느냐가 개발자의 경쟁력이 되는 시대. 이미 시작됐다.

참고 자료

• Harness engineering: leveraging Codex in an agent-first world | OpenAI
• Unlocking the Codex harness | OpenAI
• Unrolling the Codex agent loop | OpenAI
• Harness Engineering | Martin Fowler
• OpenAI Introduces Harness Engineering | InfoQ
• The Harness Problem (benchmarks) | Can.ac
• 5 Harness Engineering Principles | Tony Lee
• Harness Engineering: The Moat Isn't Code Anymore | TechWithDarin
• Harness Engineering Is Not Context Engineering | mtrajan

"엔지니어의 역할이 코드를 작성하는 사람에서, AI가 안전하게 코드를 작성할 수 있는 환경을 설계하는 사람으로 바뀐다."

충격적인 숫자들

2026년 2월, OpenAI가 내부 실험 결과를 공개했다.

• 엔지니어 3→7명
• 5개월 동안 100만 줄 코드 생산
• 수동으로 작성한 코드: 0줄
• PR 약 1,500개 머지
• 엔지니어당 하루 3.5개 PR

가장 놀라운 건, 팀원이 늘어날수록 속도가 빨라졌다는 것이다. 소프트웨어 공학의 고전 법칙인 브룩스의 법칙("지연되는 프로젝트에 인력을 추가하면 더 늦어진다")을 정면으로 반박한 결과다. 에이전트 간에는 커뮤니케이션 오버헤드가 없기 때문이다.

OpenAI는 이 방법론에 Harness Engineering(하네스 엔지니어링)이라는 이름을 붙였다.

Harness Engineering이 뭔데?

"하네스"는 원래 말(馬)에 씌우는 장비다. 강력하지만 예측 불가능한 동물의 힘을 방향 있게 쓰기 위한 도구 — 고삐, 안장, 울타리.

AI 에이전트에 대입하면:

정의: 아키텍처 제약, 피드백 루프, 관측성, 문서 시스템, 자동 품질 관리를 포함하는 구조화된 환경을 구축하여 AI 코딩 에이전트가 프로덕션 수준에서 안정적으로 작동하게 하는 학문.

프롬프트 → 컨텍스트 → 하네스: 3단계 진화

지금까지 AI 코딩의 발전은 이런 계층 구조를 따라왔다.

┌──────────────────────────────────────┐
│      Harness Engineering (하네스)      │  시스템이 무엇을 막고, 측정하고, 고치는가?
│  ┌──────────────────────────────────┐ │
│  │    Context Engineering (컨텍스트)   │ │  에이전트가 무엇을 보는가?
│  │  ┌──────────────────────────────┐ │ │
│  │  │   Prompt Engineering (프롬프트) │ │ │  지시문을 어떻게 쓰는가?
│  │  └──────────────────────────────┘ │ │
│  └──────────────────────────────────┘ │
└──────────────────────────────────────┘

• 프롬프트 엔지니어링: "이렇게 해줘" — 단발성 지시 최적화
• 컨텍스트 엔지니어링: "이것들을 참고해서 해줘" — 도구, RAG, 메모리, 스키마 설계
• 하네스 엔지니어링: "이 울타리 안에서, 이 피드백을 받으며, 이 품질 기준으로 해줘" — 제약 + 관측 + 자동 교정

핵심 차이를 한 마디로:

컨텍스트는 에이전트가 "무엇을 아는가"를 다루고, 하네스는 "무엇이 잘못될 수 있고 어떻게 막는가"를 다룬다.

OpenAI가 정의한 세 가지 기둥

1. Context Engineering — 에이전트의 눈

"에이전트가 볼 수 없는 것은 존재하지 않는다."

OpenAI 팀이 가장 먼저 깨달은 것: Slack에만 있는 결정, Google Docs에만 있는 설계 문서는 에이전트에게 없는 것이나 마찬가지다.

실천법:

• AGENTS.md는 백과사전이 아니라 목차 (~100줄)
• 실제 지식은 docs/ 디렉토리에 구조화
• ExecPlan(실행 계획서) 작성 — 초보자도 구현 가능한 수준의 자족적 설계 문서
• ExecPlan이 잘 작성되면 에이전트가 7시간 이상 무인 작업 가능

프로젝트/
├── AGENTS.md          ← 100줄짜리 목차
├── docs/
│   ├── architecture.md
│   ├── conventions.md
│   ├── gotchas.md     ← 자주 틀리는 것들
│   └── plans/
│       └── feature-x.md  ← ExecPlan

2. Architectural Constraints — 보이지 않는 울타리

"기계적으로 강제할 수 없으면, 에이전트는 반드시 벗어난다."

OpenAI는 6계층 의존성 아키텍처를 강제했다:

Types → Config → Repo → Service → Runtime → UI
          (의존성 방향: 오직 왼→오른쪽만 허용)

• 커스텀 린터가 위반을 감지하면 빌드 즉시 실패
• 흥미로운 건, 이 린터 자체도 Codex 에이전트가 작성했다는 것
• 에러 메시지가 단순 경고가 아니라 교육적 해결법을 포함 — "매 실패 메시지가 다음 시도의 컨텍스트가 된다"

3. Garbage Collection — AI 쓰레기 청소부

코드가 100만 줄이 되면, 문서는 빠르게 낡는다. 처음엔 매주 금요일에 사람이 "AI slop"(에이전트가 만든 저품질 코드)을 정리했지만, 확장이 안 됐다.

해결책: 백그라운드 에이전트를 돌렸다.

• 낡은 문서 감지 → 자동 정리 PR 생성
• 아키텍처 위반 탐지 → 자동 리팩토링 PR
• 품질 기준 위반 → 자동 수정

"인간의 취향을 한 번 캡처하고, 지속적으로 강제한다."

Vibe Coding vs. Harness Engineering

요즘 "바이브 코딩"이라는 말을 많이 듣는다. 대충 말하면 AI가 알아서 코드를 짜주는 것. 재미있고 빠르다. 하지만 프로덕션에서는?

2025년 8월, 18명의 CTO를 대상으로 한 설문에서 16명이 AI 생성 코드로 인한 프로덕션 장애를 경험했다고 답했다.

가장 생산적인 패턴은 둘의 결합이다: 하네스로 울타리를 치고, 그 안에서 바이브하게 코딩한다.

숫자가 증명하는 것

가장 충격적인 실험 결과는 Can.ac 벤치마크에서 나왔다:

하네스(에디트 도구 인터페이스)만 바꿨을 뿐인데, 모델 가중치는 건드리지 않고:

• Grok Code Fast 1: 6.7% → 68.3% 성공률
• GPT-4 Turbo: 26% → 59% 성공률

모델보다 하네스가 더 큰 성능 변수라는 뜻이다.

엔지니어의 새로운 역할

하네스 엔지니어링에서 엔지니어의 일은:

1. 환경 설계 — 에이전트가 작동할 제약과 가이드라인 구축
2. 의도 명세 — ExecPlan으로 "무엇을", "왜"를 명확히 기술
3. 피드백 루프 구축 — 실패가 자동으로 학습되는 시스템
4. 아키텍처 게이트키퍼 — 라인별 리뷰가 아닌 방향성 판단

OpenAI 팀은 엔지니어 1명당 4~8개 에이전트를 동시 실행했다:

엔지니어 (1명)
├── 에이전트 A: 기능 구현
├── 에이전트 B: 코드 리뷰
├── 에이전트 C: 보안 점검
├── 에이전트 D: 문서 정리
├── 에이전트 E: 테스트 작성
└── 에이전트 F: 버그 수정

에이전트끼리 서로 리뷰하고, 인간은 최종 방향성만 판단한다. OpenAI는 이걸 내부적으로 "Ralph Wiggum Loop" 라고 불렀다.

핵심 원칙 5가지

OpenAI의 100만 줄 실험에서 추출한 5가지 원칙:

1. 에이전트가 볼 수 없는 것은 존재하지 않는다

모든 결정을 마크다운, 스키마, ExecPlan으로 레포에 기록한다. Slack 대화? Google Docs? 에이전트에겐 존재하지 않는 것이다.

2. "왜 실패했지?"가 아니라 "어떤 능력이 부족한가?"

에이전트 실패 = 디버깅 대상이 아니라 설계 입력. 실패할 때마다 하네스에 도구/규칙/문서를 추가한다.

3. 문서보다 기계적 강제

사람이 "이렇게 해주세요"라고 써놓는 것보다, 린터가 "이건 안 됩니다"라고 빌드를 실패시키는 게 100배 효과적이다.

4. 에이전트에게 눈을 줘라

Chrome DevTools Protocol로 실제 UI를 보게 하고, 로그/메트릭으로 성능을 확인하게 한다. "startup이 800ms 이내인지 확인해"처럼 측정 가능한 지시가 가능해진다.

5. 매뉴얼이 아니라 지도

100줄짜리 조감도. 아키텍처 경계만 명확히. 압도적인 세부사항은 오히려 해롭다.

한계와 비판도 있다

모든 것이 장밋빛은 아니다. 주요 비판들:

검증 부재 문제

Martin Fowler 사이트의 Birgitta Böckeler가 지적: OpenAI 글에는 "시스템이 실제로 올바르게 작동하는지 검증하는 방법"에 대한 논의가 없다. 에이전트는 작업 완료라고 표시하지만, 실제로 동작하는지 확인하지 않는 경우가 많다.

레트로핏 문제

성공 사례 대부분이 그린필드 프로젝트(처음부터 새로 시작)다. 10년 된 레거시 코드베이스에 하네스를 적용하는 건 완전히 다른 문제다.

초기 투자 비용

OpenAI의 하네스를 구축하는 데 5개월이 걸렸다. 빠른 시작이 아니다.

과잉 엔지니어링 위험

하네스에 너무 많은 "똑똑한" 로직을 넣으면, 모델이 업데이트될 때 시스템이 깨진다. Manus는 6개월 동안 하네스를 5번 리팩토링했다.

당장 시작할 수 있는 체크리스트

대규모 팀이 아니어도, 개인 개발자로서 적용할 수 있는 것들:

문서 인프라

• CLAUDE.md / AGENTS.md를 ~100줄 목차 형태로 재구조화
• docs/ 디렉토리에 아키텍처, 규칙, 알려진 이슈 분리
• 새 기능마다 ExecPlan(실행 계획서) 먼저 작성

기계적 강제

• 린터에 프로젝트 규칙 추가 (SwiftLint, ESLint 등)
• 아키텍처 레이어 위반을 잡는 구조적 테스트 1개 이상
• CI에서 린터 + 테스트 통과 필수

피드백 루프

• 에이전트 실패 시 즉시 docs/gotchas.md 업데이트
• 에러 메시지에 해결법 포함 (교육적 에러)
• 작은 작업 단위마다 커밋 (세이브 포인트)

마인드셋 전환

• "왜 실패했지?" → "어떤 능력이 부족한가?"
• 라인별 리뷰 → 아키텍처 게이트키핑
• 계획과 실행 반드시 분리

마무리: 패러다임이 바뀌었다

하네스 엔지니어링의 본질은 이것이다:

병목은 환경이었다. 에이전트에게 코드를 짤 능력이 부족했던 게 아니라, 구조와 도구와 피드백과 명확한 제약이 부족했던 것이다.

우리는 지금 "코드를 잘 짜는 사람"에서 "코드가 안전하게 생성되는 환경을 설계하는 사람" 으로의 전환점에 서 있다.

프롬프트를 잘 쓰는 것보다, 컨텍스트를 잘 설계하는 것보다, 결국 하네스를 얼마나 견고하게 짓느냐가 개발자의 경쟁력이 되는 시대. 이미 시작됐다.

참고 자료

• Harness engineering: leveraging Codex in an agent-first world | OpenAI
• Unlocking the Codex harness | OpenAI
• Unrolling the Codex agent loop | OpenAI
• Harness Engineering | Martin Fowler
• OpenAI Introduces Harness Engineering | InfoQ
• The Harness Problem (benchmarks) | Can.ac
• 5 Harness Engineering Principles | Tony Lee
• Harness Engineering: The Moat Isn't Code Anymore | TechWithDarin
• Harness Engineering Is Not Context Engineering | mtrajan

이전 포스팅과 결이 이어지도록 독백체(~다, ~했다)를 사용했고, 기술적인 깊이는 유지하되 읽기 편하게 비유를 적극적으로 활용했습니다. 바로 복사해서 Velog에 올리시면 됩니다!

[Spring Boot] 예약 동시성 제어 삽질기: 비관적 락만 믿었다가 통수 맞은 썰

"분명히 예약 확인 로직을 짰는데, 왜 1자리 남은 예약에 2명이 성공하는 거지?"

FitLink 프로젝트의 예약 시스템을 구현하면서 만난 가장 큰 산, 바로 동시성(Concurrency) 문제다.

일상생활로 치면 이런 거다. 영화관에 좌석이 딱 1개 남았다. A와 B가 동시에 "오, 1자리 남았네!" 하고 예매 버튼을 누른다. 시스템은 두 사람 모두에게 "예매 완료!"를 띄워준다. 하나의 좌석에 두 명의 주인이 생겨버린 대참사다.

우리는 이걸 Check-Then-Act(확인 후 실행) 패턴의 함정이라고 부른다. "빈자리 확인(Check)"과 "예약 생성(Act)" 사이에 찰나의 시간차가 존재하고, 그 틈에 다른 스레드가 비집고 들어오는 것이다.

이 문제를 해결하기 위해 도입했던 3중 방어선과, 그 과정에서 겪은 짜릿한 실패(?)의 기록을 공유한다.

1. 🔒 1차 시도: 비관적 락(Pessimistic Lock)이면 다 될 줄 알았다

가장 먼저 떠올린 해결책은 JPA의 @Lock이었다. DB 레벨에서 행을 꽉 잠가버리면(SELECT FOR UPDATE), 두 스레드가 동시에 접근해도 한 명은 대기할 테니 완벽하다고 생각했다.

// 냅다 락부터 걸어버리기
@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("SELECT r FROM Reservation r WHERE r.trainer.id = :trainerId AND r.reservationDate = :date ...")
List<Reservation> findOverlappingReservations(...);

호기롭게 동시성 테스트를 돌렸다. 스레드 2개가 동시에 같은 시간에 예약을 시도하는 시나리오. 당연히 1명은 성공하고 1명은 실패할 줄 알았다.

결과: Success = 2, Fail = 0 (테스트 실패 ❌)

어? 왜 둘 다 성공하지? 로그를 뜯어보고 나서야 엄청난 착각을 하고 있었다는 걸 깨달았다. 바로 '빈 행(Empty Row) 문제'다.

SELECT FOR UPDATE는 '이미 DB에 존재하는 행'을 잠그는 기술이다. 그런데 첫 예약이 들어오는 시점에는 해당 시간대의 예약 데이터가 아예 없다. 잠글 행 자체가 없으니, 두 스레드 모두 빈 결과를 받고 유유히 락을 통과해 버린 것이다.

(참고로 MySQL InnoDB는 갭 락(Gap Lock) 덕분에 빈 행도 막아주지만, 테스트 환경인 H2나 PostgreSQL에서는 얄짤없이 뚫린다.)

2. 🛡️ 최후의 방어선: DB Unique 제약조건과 saveAndFlush

애플리케이션 레벨의 Check-Then-Act는 동시성에 너무 취약했다. 결국 믿을 건 DB 엔진뿐이었다. DB는 데이터의 고유성 확인과 INSERT를 하나의 원자적(Atomic) 연산으로 처리하기 때문이다.

(1) Unique 제약조건 걸기

Reservation 엔티티에 트레이너 ID + 날짜 + 시작 시간 조합으로 유니크 제약조건을 걸었다.

@Table(uniqueConstraints = {
    @UniqueConstraint(columnNames = {"trainer_id", "reservation_date", "start_time"})
})

이제 두 스레드가 락을 통과해서 동시에 INSERT를 시도하더라도, 한 놈은 무조건 DB 단에서 Unique constraint violation 에러를 맞고 튕겨 나간다.

(2) save()가 아니라 saveAndFlush()인 이유

DB가 튕겨내는 건 좋은데, 이 에러를 우아하게 잡아서 사용자에게 "이미 예약된 시간입니다"라고 알려줘야 한다.

처음엔 평소처럼 repository.save()를 쓰고 try-catch로 묶었다. 그런데 예외가 안 잡히고 밖으로 터져버렸다. 왜 그럴까?

// ❌ save()의 배신
try {
    repository.save(reservation); // 영속성 컨텍스트에만 저장 (SQL 안 날림)
} catch (Exception e) {
    // 여기서 에러 안 터짐!
} 
// 메서드가 끝나는 시점(@Transactional 커밋)에 INSERT가 날아가서 밖에서 터짐!

이럴 때 필요한 게 saveAndFlush()다.

// ✅ saveAndFlush()로 즉시 SQL 날리기
try {
    repository.saveAndFlush(reservation); // "지금 당장 DB에 쿼리 쏴!"
} catch (DataIntegrityViolationException e) {
    throw new BusinessException(ErrorCode.RESERVATION_TIME_CONFLICT);
}

DB 제약조건 위반 에러를 즉시 캐치해서, 우리가 정의한 비즈니스 예외로 깔끔하게 변환(Translation)할 수 있게 되었다.

3. 🧪 진짜 동시성 테스트는 어떻게 짤까? (feat. CountDownLatch)

해결책을 만들었으니 검증을 해야 한다. 그런데 일반적인 단위 테스트(@ExtendWith(MockitoExtension.class))로는 절대 동시성을 테스트할 수 없다. Mock 객체는 DB의 락이나 Unique 제약조건을 흉내 내지 못하기 때문이다.

반드시 실제 DB와 멀티 스레드 환경이 필요하다.

주의 1: @Transactional을 과감히 버려라

이전 포스팅에서 다뤘듯, 스프링의 @Transactional은 ThreadLocal을 기반으로 동작한다. 테스트 클래스에 @Transactional을 붙여버리면, 메인 스레드가 만든 테스트 데이터(트레이너, 회원 등)를 새로 생성된 작업 스레드들이 읽지 못하는 불상사가 발생한다. 동시성 테스트에서는 무조건 빼고, 데이터 정리는 @BeforeEach에서 수동으로(deleteAll()) 해줘야 한다.

주의 2: 3단계 CountDownLatch로 '진짜 동시'를 만들어라

단순히 ExecutorService로 스레드를 여러 개 던진다고 해서 완벽한 동시 출발이 보장되진 않는다. 육상 경기를 하듯 정확한 타이밍 제어가 필요하다.

int threadCount = 2;
CountDownLatch readyLatch = new CountDownLatch(threadCount); // 선수 입장 확인
CountDownLatch startLatch = new CountDownLatch(1);           // 출발 총성
CountDownLatch doneLatch = new CountDownLatch(threadCount);  // 결승선 통과 확인

executorService.submit(() -> {
    readyLatch.countDown(); // "저 준비됐어요!"
    startLatch.await();     // 총소리 울릴 때까지 대기 🔫

    try {
        reservationService.createByTrainer(...); // ★ 진짜 동시 접근 발생 ★
        successCount.incrementAndGet();
    } finally {
        doneLatch.countDown(); // "경기 끝!"
    }
});

readyLatch.await();      // 선수들 다 올 때까지 메인 스레드 대기
startLatch.countDown();  // 탕! (모든 스레드 동시 출발)
doneLatch.await();       // 모두 끝날 때까지 대기 후 검증

이 정도로 타이밍을 쥐어짜야 비로소 의미 있는 동시성 테스트 결과를 얻을 수 있다.

🎯 결론: 실패가 알려준 '3중 방어선'

만약 처음부터 정답(DB Unique 제약조건)만 쏙 빼서 적용했다면 금방 끝났을 거다. 하지만 비관적 락을 먼저 시도했다가 '빈 행 문제'로 시원하게 통수를 맞아본 덕분에, 락의 한계와 DB 엔진별 동작의 차이를 뼛속까지 이해하게 되었다.

현재 우리 시스템의 동시 예약 제어는 다음 3중 방어선으로 이루어져 있다.

1. 비관적 락 (@Lock): 이미 존재하는 예약이 있을 때 순서를 보장 (1차 방어)
2. DB Unique 제약: 빈 행 상태에서 들어오는 동시 INSERT를 원자적으로 차단 (최후의 보루)
3. saveAndFlush + Exception Catch: DB 에러를 우아한 비즈니스 예외로 변환 (사용자 경험)

코드는 의도한 대로 완벽하게 1승 1패(1 성공, 1 예외)를 기록하며 테스트를 통과했다. 동시성, 겪어보기 전엔 무서웠는데 막상 부딪혀보니 이거... 꽤 재밌다.

"방금 짠 이 CRUD 코드, 왜 이렇게 짰는지 설명할 수 있어요?"

멘토링을 진행하면서 Spring Boot로 백엔드 서버를 만들고 있다. 솔직히 처음엔 'CRUD 쯤이야...' 라고 생각했다. Controller 만들고, Service에서 비즈니스 로직 쓱쓱 짜고, Repository로 DB 접근하고. 컴파일 통과, 테스트 통과. 깔끔하게 끝인 줄 알았다.

그런데 멘토님과 대화를 나누다 보니, 내가 짠 이 몇 줄의 코드가 단순히 '돌아가는 것'에서 끝나는 게 아니었다. 이 평범해 보이는 Service 코드가 실제 JVM 위에서, 수많은 스레드에 의해, 메모리(GC)의 감시를 받으며 돌아간다는 걸 간과하고 있었던 거다.

오늘은 "그냥 남들이 다 그렇게 짜니까" 넘어갔던 단순 CRUD 뒤에 숨겨진 프레임워크와 자바의 핵심 동작 원리를 정리해 보려고 한다.

1. 🧵 Service는 왜 무상태(Stateless)여야 할까? (스레드와 메모리)

보통 비즈니스 로직을 짤 때 @Service를 붙여서 클래스를 만든다. 그런데 만약 이 Service 안에 데이터(상태)를 저장하는 전역 변수를 두면 어떻게 될까?

@Service
public class TrainerProfileService {
    // 🚨 대참사의 시작
    private String currentUserName; 

    public void updateProfile(String name) {
        this.currentUserName = name;
        // ... 로직 처리
    }
}

Spring Boot(기본 내장 Tomcat)는 사용자의 요청이 들어올 때마다 스레드 풀(Thread Pool)에서 스레드를 하나씩 꺼내서 할당하는 Thread-per-Request 방식을 쓴다.

문제는 스프링 컨테이너가 이 @Service 객체를 싱글톤(Singleton)으로 딱 하나만 만들어서 관리한다는 거다. 만약 100명의 사용자가 동시에 프로필을 수정한다고 치자. 100개의 스레드가 단 1개의 Service 객체(메모리 주소)에 동시에 접근해서 저 currentUserName을 바꾸려고 난리를 칠 거다. 당연히 데이터가 뒤섞이는 동시성 이슈가 터진다.

스택(Stack)과 힙(Heap)의 차이

• 클래스의 필드 변수: JVM의 Heap 영역에 저장된다. 힙은 모든 스레드가 모여 노는 '공용 운동장'이다. 여기서 값을 바꾸면 모두가 영향을 받는다.
• 메서드 내부의 지역 변수: JVM의 Thread Stack 영역에 저장된다. 스택은 스레드마다 주어지는 '개인실'이다. 스레드끼리 절대 섞이지 않는다.

💡 결론 여러 스레드가 동시에 접근하는 Service는 반드시 무상태(Stateless)로 설계해야 한다. 객체의 의존성(Repository 등)은 final로 박아둬서 불변성을 보장하고, 변경되는 데이터는 무조건 메서드의 파라미터(지역 변수)로만 주고받아야 안전하다.

2. 🗑️ 조회만 했는데 서버가 뻗는다고? (JPA와 GC)

JPA를 쓰면 보통 @Entity 객체로 데이터를 조회해온다. 그런데 대량의 데이터를 리스트로 뽑아올 때, 무지성으로 Entity로 다 끌고 오면 어떻게 될까?

Entity로 조회할 때 벌어지는 일

JPA는 Entity를 DB에서 가져오는 순간, "아 이건 내가 계속 관리해야 하는 애구나!" 하고 영속성 컨텍스트(1차 캐시)에 올려버린다. 심지어 나중에 수정될까 봐 원본 스냅샷까지 메모리에 복사해 둔다.

만약 데이터 수만 건을 Entity로 가져오면? 이 무거운 객체들이 JVM의 Heap 메모리를 가득 채운다. 트랜잭션이 길어져서 이 객체들이 오랫동안 살아남으면, 가비지 컬렉터(GC)가 얘네를 Old 영역으로 보내버리고, 결국 무거운 Major GC(Stop-The-World)가 터지면서 서버가 순간적으로 멈춰버릴 수 있다.

DTO로 직접 꽂아버리면? (Projection)

반면에 JPQL이나 QueryDSL을 써서 Entity가 아니라 내가 만든 순수 DTO로 바로 매핑해서 가져오면 얘기가 달라진다.

JPA는 이걸 보고 "이건 내 관리 대상(Entity)이 아니네?" 하고 영속성 컨텍스트에 올리지 않는다. 덕분에 이 DTO 객체들은 클라이언트에게 응답을 주는 즉시 가비지(Garbage)가 되고, 가볍고 빠른 Minor GC가 슉슉 청소해 버린다. 메모리 낭비가 0에 수렴하는 거다.

💡 결론 데이터를 수정할 일이 없는 단순 리스트 조회(Read-Only) API에서는, 무작정 Entity를 쓰지 말고 DTO 직접 조회(Projection)를 활용해서 영속성 컨텍스트를 우회하자. 이게 곧 메모리 관리이자 성능 최적화다.

3. 🎩 @Transactional의 배신 (마법이 아니었어)

우리는 너무나 자연스럽게 Service 메서드 위에 @Transactional을 붙인다. 트랜잭션이 유지되려면 시작부터 끝까지 '같은 DB 커넥션'을 물고 있어야 하는데, 코드를 보면 Service에서 Repository로 커넥션 객체를 파라미터로 넘겨주는 부분이 전혀 없다.

어떻게 커넥션이 유지되는 걸까? 스프링이 마법이라도 부리는 걸까?

구원자: ThreadLocal

스프링은 자바의 ThreadLocal이라는 녀석을 쓴다. 이건 "현재 실행 중인 스레드만 열어볼 수 있는 전용 사물함"이다.

1. 트랜잭션 시작: 스프링이 DB 커넥션을 획득한 뒤, 현재 일하고 있는 스레드의 ThreadLocal 사물함에 커넥션을 몰래 넣어둔다.
2. Repository 실행: 개발자가 쿼리를 날리면, 내부적으로 파라미터를 넘기지 않아도 자기 사물함(ThreadLocal)을 열어서 아까 넣어둔 커넥션을 꺼내 쓴다. (대박..)
3. 종료: 커밋이나 롤백이 끝나면 ThreadLocal을 깨끗하게 비운다.

🚨 여기서 주의할 점 (진짜 중요)

만약 이 원리를 모른 채로, @Transactional이 붙은 메서드 안에서 성능 좀 높이겠다고 비동기 스레드(CompletableFuture 등)를 새로 파서 Repository를 호출하면 어떻게 될까?

새로 만든 스레드의 ThreadLocal 사물함은 당연히 텅 비어있다! 스프링이 기존 스레드 사물함에 넣어둔 커넥션을 찾을 수 없으니, 기존 트랜잭션과 완전히 분리되어 버리는 대참사가 일어난다.

💡 결론 @Transactional은 마법이 아니다. 하나의 스레드 내부에서만 커넥션을 공유해 주는 ThreadLocal 기반의 기술이라는 걸 반드시 알고 써야 한다.

🎯 마무리

"기능이 돌아가면 끝난 거 아냐?" 라고 생각했던 오만함이 싹 사라졌다.

단순해 보이는 CRUD 코드 한 줄이라도, 어떤 메모리 영역(Stack/Heap)에 올라가는지, 가비지 컬렉터(GC)에 어떤 영향을 주는지, 스레드(ThreadLocal)와 트랜잭션이 어떻게 엮여서 돌아가는지 알고 짜는 것과 모르고 짜는 것은 하늘과 땅 차이인 것 같다.

이제 그냥 생각 없이 키보드부터 두드리는 짓은 못 할 것 같다. (오히려 좋아) 앞으로는 "왜 이렇게 짰어?"라는 질문에 당당하게 이유를 설명할 수 있는 코드를 짜야겠다.

PT 예약 시스템을 만들면서 처음 테스트 코드를 작성한 과정을 정리했다. "테스트 코드를 짜본 적이 없는" 상태에서 시작해, Entity → Service까지 34개의 테스트를 작성하면서 배운 것들.

테스트는 입력값 유효성 체크가 아니다

처음 테스트를 작성하려니 떠오르는 건 이런 것뿐이었다.

• "시작 시간이 종료 시간보다 늦으면?"
• "종료 시간이 시작 시간보다 빠르면?"

둘 다 입력값 유효성 체크다. 물론 이것도 테스트하지만, 테스트의 전부가 아니다.

테스트가 검증하는 건 크게 3가지다:

1. 올바르게 만들어지는가? (생성)

TrainerSchedule schedule = TrainerSchedule.create(
    trainer, DayOfWeek.MONDAY, LocalTime.of(9, 0), LocalTime.of(18, 0));

assertThat(schedule.getIsAvailable()).isTrue();  // 생성하면 항상 true인가?

"내가 의도한 대로 객체가 만들어지는지" 검증한다.

2. 올바르게 동작하는가? (행위) ← 핵심

// 09:00~18:00 근무 스케줄에서
assertThat(schedule.isWithinWorkingHours(LocalTime.of(9, 0))).isTrue();   // 시작 정각은?
assertThat(schedule.isWithinWorkingHours(LocalTime.of(18, 0))).isFalse(); // 종료 정각은?

비즈니스 로직이 기대한 대로 동작하는지 검증한다. 이게 테스트의 핵심이다.

3. 잘못된 상황에서 안전한가? (방어)

assertThatThrownBy(() -> TrainerSchedule.create(
    trainer, DayOfWeek.MONDAY, LocalTime.of(18, 0), LocalTime.of(9, 0)))
    .isInstanceOf(IllegalArgumentException.class);

예외 상황에서 터져야 할 게 터지는지 검증한다.

테스트를 짜려면 비즈니스 로직을 이해해야 한다

당연한 말 같지만, 테스트 코드를 처음 접하면 놓치기 쉽다.

isWithinWorkingHours() 메서드를 보자:

public boolean isWithinWorkingHours(LocalTime time) {
    if (!this.isAvailable) return false;
    return !time.isBefore(this.startTime) && time.isBefore(this.endTime);
}

이 코드를 이해하면 자연스럽게 질문이 나온다:

"이러면 어떻게 되지?"라는 질문 = 테스트 시나리오다.

Entity / Repository / Service 테스트의 차이

테스트 파일을 보면 entity/, repository/, service/ 폴더가 있다. 뭐가 다른 걸까?

Entity 테스트 — 순수 로직

Mock: 없음 | DB: 없음 | 속도: 가장 빠름

// "09:00은 근무시간인가?" — 순수 Java 객체만으로 검증
TrainerSchedule schedule = TrainerSchedule.create(...);
assertThat(schedule.isWithinWorkingHours(LocalTime.of(9, 0))).isTrue();

객체 자체의 규칙을 검증한다. new 해서 메서드 호출하고 결과 확인. DB도 없고 Mock도 없다.

Repository 테스트 — 쿼리 검증

Mock: 없음 | DB: 있음 (H2) | 속도: 중간

@DataJpaTest  // 실제 H2 DB가 뜬다
class MembershipRepositoryTest {
    @Test
    void ACTIVE_수강권을_찾는다() {
        membershipRepository.save(membership);  // 실제 DB에 저장
        Optional<Membership> found = membershipRepository
            .findByMemberIdAndStatus(1L, MembershipStatus.ACTIVE);  // 실제 SQL 실행
        assertThat(found).isPresent();
    }
}

JPA 쿼리 메서드가 의도한 데이터를 가져오는지 검증한다. 실제 DB(H2)가 뜬다.

Service 테스트 — 비즈니스 흐름

Mock: 있음 (Repository를 가짜로) | DB: 없음 | 속도: 빠름

@Mock MembershipRepository membershipRepository;  // 가짜
@InjectMocks MembershipService membershipService;

@Test
void 다른_트레이너_소속이면_예외() {
    given(memberRepository.findById(2L)).willReturn(Optional.of(otherMember));

    assertThatThrownBy(() -> membershipService.createByTrainer(...))
        .isInstanceOf(BusinessException.class);
}

Repository는 가짜(Mock)로 대체하고, 서비스 로직의 흐름을 검증한다. "A 다음에 B 하고, 조건 안 맞으면 예외" 같은 시나리오.

한 줄 비교

테스트 코드의 기본 구조: given / when / then

모든 테스트는 이 3단계를 따른다:

@Test
@DisplayName("마지막 1회를 차감하면 상태가 EXPIRED로 전이된다")
void it_expires_when_last_count_is_used() {
    // given — 준비: 1회짜리 수강권
    Membership membership = createMembership(1);

    // when — 실행: 차감
    membership.decreaseCount();

    // then — 검증: 0회, EXPIRED
    assertThat(membership.getRemainingCount()).isEqualTo(0);
    assertThat(membership.getStatus()).isEqualTo(MembershipStatus.EXPIRED);
}

• given: 테스트할 상황을 만든다
• when: 테스트 대상 동작을 실행한다
• then: 결과가 기대한 대로인지 확인한다

예외를 검증할 때는 when & then이 합쳐진다:

// when & then — "이걸 하면 이 예외가 터져야 한다"
assertThatThrownBy(() -> membership.decreaseCount())
    .isInstanceOf(IllegalStateException.class)
    .hasMessageContaining("남은 PT 횟수가 없습니다");

테스트가 설계를 개선한다

이번에 가장 크게 배운 점이다.

TrainerSchedule.create()에 시작 시간이 종료 시간보다 늦은 경우를 테스트하려고 했는데:

// 이 테스트를 짜려고 보니... create()에 guard가 없다!
TrainerSchedule.create(trainer, DayOfWeek.MONDAY,
    LocalTime.of(18, 0), LocalTime.of(9, 0));  // 18:00~09:00 — 에러 안 남

테스트를 작성하면서 프로덕션 코드의 빈틈을 발견한 거다. 결국 guard를 추가했다:

public static TrainerSchedule create(...) {
    if (!endTime.isAfter(startTime)) {
        throw new IllegalArgumentException("종료 시간은 시작 시간보다 이후여야 합니다.");
    }
    // ...
}

Membership.create()에서도 같은 일이 있었다. 날짜 검증과 횟수 검증이 없었는데, 테스트를 짜려다 보니 "이거 guard가 없네?"를 발견했다.

테스트 코드는 검증 도구이자 설계 리뷰 도구다.

실전에서 작성한 테스트 목록

Entity 테스트 (Mock 없음, 순수 로직)

Service 테스트 (Mockito, Repository Mock)

빠르게 기억할 치트시트

테스트 = "이러면 어떻게 되지?"를 코드로 증명하는 것

given  → 상황 만들기
when   → 실행하기
then   → 결과 확인하기

Entity 테스트   → 객체의 규칙 (Mock X, DB X)
Repository 테스트 → 쿼리 동작 (Mock X, DB O)
Service 테스트   → 비즈니스 흐름 (Mock O, DB X)

assertThat(값).isEqualTo(기대값)     → 같은지
assertThat(값).isTrue() / isFalse()  → 참/거짓
assertThatThrownBy(() -> 실행)       → 예외 터지는지
verify(mock).메서드()                → Mock이 호출됐는지
verify(mock, never()).메서드()       → Mock이 호출 안 됐는지

사이드 프로젝트로 PT(Personal Training) 예약 관리 시스템을 만들고 있다. Spring Boot + Next.js 구성이다.

이번 글에서는 실제 기능을 구현하면서 마주친 설계 시행착오를 정리한다. 완성된 결과보다 왜 그렇게 결정했고, 어떤 트레이드오프가 있었는지에 집중한다.

1. /api/trainers/me/members — 그 URL이 정말 맞아?

상황

트레이너가 자기 회원 목록을 조회하는 API가 필요했다. 세 가지 후보가 있었다.

1. GET /api/trainers/members
2. GET /api/trainers/{trainerId}/members
3. GET /api/trainers/me/members

내 선택: 3번

이유는 두 가지였다.

• me는 JWT에서 추출하니까 다른 트레이너의 ID를 넣을 여지 자체가 없다. IDOR(Insecure Direct Object Reference) 취약점이 구조적으로 차단된다.
• URL만 봐도 "나의 회원"이라는 의미가 명확하다.

실제로 이 패턴은 널리 쓰인다:

• Microsoft Graph: GET /v1.0/me
• Spotify: GET /v1/me/playlists
• Discord: GET /users/@me
• GitHub: GET /user/repos (singular, ID 없이)
• Google People: GET /v1/people/me

그런데 이건 RESTful한가?

엄밀히 말하면 아니다. Roy Fielding의 REST 원칙에서 URI는 하나의 리소스를 식별해야 한다. 그런데 /me는 토큰에 따라 다른 리소스를 가리키는 컨텍스트 의존적 별칭(alias)이다. 같은 GET /me가 사용자마다 다른 결과를 반환하니까, 하나의 URI = 하나의 리소스 원칙에 위배된다.

Kevin Dunglas(API Platform 메인테이너)는 이렇게 말했다:

"Creating an endpoint like /api/users/me isn't stateless, can create cache problems if you rely on some reverse proxies and break the REST pattern."

캐싱 문제도 있다. CDN이나 리버스 프록시가 URL을 캐시 키로 쓰면, User A의 /me 응답이 User B에게 전달될 수 있다. Vary: Authorization 헤더로 해결은 가능하지만, 기본 CDN 설정에서는 동작하지 않는 경우가 많다.

내가 인지한 트레이드오프

기존 프로젝트의 다른 엔드포인트들(/api/reservations, /api/memberships)은 me 패턴을 안 쓰고, JWT에서 email을 추출해서 내부적으로 처리한다. 여기만 다른 패턴을 쓰는 셈이다.

일관성 문제를 알면서도 진행한 이유? 새로운 패턴을 경험해보고 싶었기 때문이다. 실무에서 쓸지 말지는 트레이드오프를 직접 느껴본 뒤에 판단해도 늦지 않다.

OCTO REST API Cookbook의 권장사항: /me는 초기 부트스트랩용으로만 제한적으로 사용하고, 이후에는 정규 URI(/users/{id}/...)를 쓰는 하이브리드 접근이 좋다.

2. "프론트에서 체크하면 되지 않나?" — 검증은 어디서 해야 하는가

상황

이용권(Membership)을 등록하는 API를 만들면서, 종료일이 시작일보다 앞서는 경우(날짜 역전)를 어디서 막을지 고민했다.

처음엔 당연히 "프론트에서 체크할 문제"라고 생각했다. Date Picker 컴포넌트에서 제한하면 되니까.

왜 그게 위험한가

OWASP Input Validation Cheat Sheet에 이런 문장이 있다:

"Input validation must be implemented on the server-side before any data is processed, as any JavaScript-based input validation can be circumvented by an attacker who disables JavaScript or uses a web proxy."

프론트 검증은 UX(사용자 편의)를 위한 것이고, 백엔드 검증은 데이터 무결성을 위한 것이다. 이 둘은 목적이 다르다.

실제로 프론트 검증만 믿다가 터진 사례들이 있다:

• OTP 우회: 클라이언트에서만 OTP를 검증 → 공격자가 API 응답의 상태 코드를 401에서 200으로 변조해서 인증 우회
• 결제 금액 조작: JavaScript 변수에 저장된 가격을 Burp Suite로 변조 → 서버가 그대로 수용
• HackerOne 최소 바운티 우회: 보안 플랫폼인 HackerOne 자체에서 클라이언트 입력을 신뢰해서 최소 금액 제한이 뚫림

검증 피라미드

Frank de Jonge의 "Where Does Validation Live?"에서 제안하는 3계층 검증:

[Frontend]     형태 검증, 즉각적 UX 피드백 (보안 아님)
     ↓
[Controller/DTO]  구조적 검증: @NotNull, @Min, 타입 체크
     ↓
[Service]      비즈니스 규칙: 권한, 중복, 정책
     ↓
[Entity]       불변식(invariant): 도메인 모델이 스스로를 보호
     ↓
[Database]     제약조건: NOT NULL, UNIQUE, FK (최후의 방어선)

Greg Young은 2009년 "Always Valid" 글에서 이렇게 주장했다:

Entity는 절대로 유효하지 않은 상태로 존재해서는 안 된다. 유효하지 않은 상태의 Entity는 설계 결함이다.

Vladimir Khorikov는 이걸 비유로 설명한다:

"삼각형은 변이 3개인 도형이다. 4번째 변을 추가하면, 그건 더 이상 삼각형이 아니라 사각형이다."

내가 적용한 구조

// Entity — 도메인 모델이 스스로를 보호한다
public static Membership create(Member member, Trainer trainer,
                                Integer totalCount,
                                LocalDate startDate, LocalDate endDate) {
    if (endDate.isBefore(startDate)) {
        throw new IllegalArgumentException("종료일은 시작일보다 이후여야 합니다.");
    }
    if (totalCount <= 0) {
        throw new IllegalArgumentException("총 PT 횟수는 1 이상이어야 합니다.");
    }
    return Membership.builder()
            .member(member)
            .trainer(trainer)
            .totalCount(totalCount)
            .remainingCount(totalCount)
            .startDate(startDate)
            .endDate(endDate)
            .status(MembershipStatus.ACTIVE)
            .build();
}

Jimmy Bogard는 반대 의견도 있다 — "Validate commands, not entities"(Entity가 아니라 커맨드에서 검증해라). 하지만 DDD 커뮤니티의 주류 의견은 Entity가 자신의 불변식을 보호해야 한다는 쪽이다. 특히 복잡한 도메인에서.

핵심은 이거다:

프론트 검증과 백엔드 검증은 중복이 아니다. 서로 다른 목적을 위한 서로 다른 방어선이다.

3. Controller는 trainer에, Service는 member에 — 크로스 도메인 의존의 딜레마

상황

회원 목록 API의 패키지 구조를 이렇게 잡았다:

• TrainerMemberController → domain/trainer/controller/
• MemberService → domain/member/service/

이유는 명확했다:

• Controller는 URL 경로를 따른다 → /api/trainers/me/members니까 trainer 패키지
• Service는 데이터 소유자를 따른다 → 회원 데이터를 다루니까 member 패키지

Martin Fowler가 경고한 빈약한 도메인 모델(Anemic Domain Model) 안티패턴을 피하려면, 데이터를 소유한 주체가 비즈니스 로직도 가져야 한다.

그런데 의존성 그래프를 보면

TrainerMemberController (trainer 도메인)
    └── MemberService (member 도메인)
            ├── MemberRepository (member 도메인)       ← 같은 도메인, OK
            ├── MembershipRepository (membership 도메인) ← 크로스!
            └── TrainerRepository (trainer 도메인)      ← 크로스!

3개의 도메인이 하나의 Service에서 만난다. 이건 문제인가?

이게 문제가 되는 시점

지금은 문제없다. 프로젝트가 작고, 도메인 간 경계가 명확하다.

문제가 되는 시점은:

• MembershipRepository의 API가 바뀌면 MemberService도 깨진다 (다른 도메인의 내부 구현에 의존)
• member와 trainer 패키지가 서로를 참조하기 시작하면 순환 의존이 생긴다
• Spring Modulith를 도입하면 다른 모듈의 하위 패키지 접근이 차단된다

해결 패턴들

Philipp Hauer의 "Package by Feature" 글과 Spring Modulith 가이드에서 제안하는 패턴들:

패턴 A: 인터페이스로 의존성 역전

// member 모듈이 인터페이스를 정의
public interface MembershipInfoProvider {
    MembershipSummary getActiveMembership(Long memberId);
}

// membership 모듈이 구현
@Service
public class MembershipInfoProviderImpl implements MembershipInfoProvider {
    // MembershipRepository는 여기서만 사용
}

패턴 B: 이벤트 기반

// 직접 호출 대신, 이벤트를 발행하고 구독하는 방식
// Spring Modulith가 권장하는 모듈 간 통신
applicationEventPublisher.publishEvent(new MemberQueryEvent(memberId));

패턴 C: 모듈 합치기 member와 membership이 항상 함께 쓰인다면, 애초에 하나의 바운디드 컨텍스트(Bounded Context)일 수 있다.

내가 인지한 트레이드오프

현재는 가장 단순한 방법(직접 의존)을 선택했다. PT 예약 시스템 규모에서 인터페이스 분리나 이벤트 기반은 과설계(over-engineering)다.

하지만 이 의존 관계를 인지하고 있는 것과 모르고 지나가는 것은 다르다. 나중에 도메인이 커지면, 위 패턴들이 필요한 시점이 온다.

Eric Evans는 Bounded Context 사이에는 Anti-Corruption Layer를 두라고 했다. 지금은 모노리스 안에서의 패키지 경계지만, 마이크로서비스로 분리한다면 이 크로스 도메인 의존이 가장 먼저 문제가 된다.

정리

세 가지 판단 모두 정답이 아닐 수 있다. 하지만 왜 그렇게 결정했고, 어떤 문제가 생길 수 있는지 알고 있다. 그게 중요하다고 생각한다.

참고 자료

URL 설계 / /me 패턴

• OCTO REST API Cookbook — Resources depending on authenticated user
• API Platform — Best Practice for adding a /me route (GitHub Issue #477)
• Roy Fielding — REST APIs must be hypertext-driven
• Vinay Sahni — Best Practices for a Pragmatic RESTful API

검증 / 보안

• OWASP — Input Validation Cheat Sheet
• OWASP Proactive Controls C3 — Validate Input
• Vladimir Khorikov — Always-Valid Domain Model
• Greg Young — Always Valid (2009)
• Frank de Jonge — Where Does Validation Live?
• DeepStrike — Client-Side Validation: Security Flaws and Real Exploits

패키지 구조 / DDD

• Philipp Hauer — Package by Feature
• Martin Fowler — BoundedContext
• Martin Fowler — Anemic Domain Model
• Spring Modulith and Breaking Dependency Cycles
• Microsoft — Domain Model Layer Validations

프로젝트: FitLink — PT 예약 관리 시스템 기술 스택: Spring Boot 3.3 + Java 21 + Next.js 16 + Zustand + TanStack Query

개요 📝

Flutter 앱에서 Firebase Authentication과 함께 구글, 애플, 카카오 로그인을 모두 구현한 경험을 정리했다. 각 플랫폼별 특징과 주의사항, 그리고 실제 구현 과정에서 마주한 문제점들까지 기록해보자.

⚡ 이 글의 특징:

• 최신 버전 완벽 대응: firebase_core: 4.0.0, firebase_auth: 6.0.0, google_sign_in: 7.1.1, sign_in_with_apple: 7.0.1, kakao_flutter_sdk: 1.9.6
• 바이럴 코딩(AI 도구)에만 의존했다가 겪은 시행착오 공유
• 모든 플랫폼별 최신 API 변경사항 상세 분석 및 대응 방법 제시

전체 아키텍처 설계 🏗️

1. 기본 구조

Firebase Auth (중심축)
├── Google Sign-In
├── Apple Sign-In  
└── Kakao Sign-In → Firebase Custom Token

2. 로그인 플로우 설계

1. 사용자 선택 → 로그인 방식 선택
2. 각 플랫폼 인증 → 플랫폼별 토큰 획득
3. Firebase 연동 → Firebase Auth로 통합 관리
4. 사용자 정보 저장 → Firestore에 프로필 데이터 저장

구현 방법 🛠️

1. 구글 로그인 구현

가장 간단하고 Firebase와 연동이 쉬운 방식이다. 하지만 7.1.1 버전부터 API가 크게 변경되었으니 주의!

🔄 바이럴 코딩의 함정과 API 변화

처음엔 GitHub Copilot과 ChatGPT가 추천한 구 버전 코드를 그대로 사용했다가 계속 오류가 발생했다. 알고보니 google_sign_in 7.1.1부터 API가 완전히 바뀌었던 것!

구 버전 (7.0.0 이전) 방식:

// ❌ 이제 안 되는 방식
final GoogleSignInAccount? googleUser = await GoogleSignIn().signIn();

신 버전 (7.1.1+) 방식:

// ✅ 새로운 방식
final GoogleSignIn signIn = GoogleSignIn.instance;
await signIn.initialize();
final GoogleSignInAccount? googleUser = await signIn.authenticate();

💡 교훈: AI 도구들은 항상 최신 API를 반영하지 못한다. 공식 문서와 changelogs 확인이 필수!

의존성 추가 (최신 버전)

# pubspec.yaml - 2025년 8월 기준 최신 안정 버전
dependencies:
  firebase_core: 4.0.0
  firebase_auth: 6.0.0
  google_sign_in: 7.1.1  # 🔥 7.1.1부터 API 대폭 변경!

핵심 코드

Future<void> signInWithGoogle() async {
  try {
    final GoogleSignIn signIn = GoogleSignIn.instance;
    await signIn.initialize();
    final GoogleSignInAccount? googleUser = await signIn.authenticate();
    if (googleUser == null) {
      debugPrint('Google 로그인 취소 또는 사용자 없음');
      return;
    }
    final GoogleSignInAuthentication googleAuth = await googleUser.authentication;
    final credential = GoogleAuthProvider.credential(
      idToken: googleAuth.idToken,
    );
    await _auth.signInWithCredential(credential);
    notifyListeners();
  } catch (e, st) {
    debugPrint('Google 로그인 오류: $e\n$st');
    rethrow;
  }
}

✅ 장점: Firebase 공식 지원, 구현 간단
⚠️ 주의점: iOS에서는 URL Scheme 설정 필요

2. 애플 로그인 구현

iOS 13+ 필수 요구사항이며, 개인정보 보호에 특화되어 있다. 7.0.1 버전에서 안정성이 크게 개선되었다!

🔄 최신 버전 7.0.1 주요 개선사항

바이럴 코딩으로 찾은 예전 글들은 대부분 5.x 버전 기준이었는데, 7.0.1에서는 다음과 같은 개선이 있었다:

• iOS 17 완벽 지원
• 에러 핸들링 개선
• 성능 최적화

의존성 추가 (최신 버전)

# pubspec.yaml - 2025년 8월 기준 최신 안정 버전
dependencies:
  sign_in_with_apple: 7.0.1  # 🔥 7.0.1 최신 버전 사용!

🚀 바이럴 코딩 성공 사례: iOS 설정

애플 로그인은 오히려 바이럴 코딩이 빛을 발한 케이스였다! GitHub Copilot이 Info.plist 설정을 완벽하게 제안해주었다:

<!-- ✅ iOS Info.plist - 바이럴 코딩으로 빠르게 완성! -->
<key>CFBundleURLTypes</key>
<array>
    <!-- Google 로그인 -->
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>com.googleusercontent.apps.36163303930-1shl4p0i3fm7jsd01ir542pd0jnq5g0a</string>
        </array>
    </dict>
    <!-- Apple 로그인: 실제 번들 ID 사용 -->
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>com.byseungje.myApp</string>
        </array>
    </dict>
    <!-- Kakao 로그인 -->
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>kakaoa{네이티브 앱 키}</string>
        </array>
    </dict>
</array>

💡 iOS는 바이럴 코딩 천국: URL Scheme부터 Xcode 설정까지 AI가 거의 완벽하게 도와줬다!

핵심 코드 (7.0.1 버전)

Future<UserCredential?> signInWithApple() async {
  try {
    final appleCredential = await SignInWithApple.getAppleIDCredential(
      scopes: [
        AppleIDAuthorizationScopes.email,
        AppleIDAuthorizationScopes.fullName,
      ],
    );

    final oauthCredential = OAuthProvider("apple.com").credential(
      idToken: appleCredential.identityToken,
      accessToken: appleCredential.authorizationCode,
    );

    return await FirebaseAuth.instance.signInWithCredential(oauthCredential);
  } catch (e) {
    debugPrint('Apple Sign-In Error: $e');
    return null;
  }
}

✅ 장점: 개인정보 보호 우수, iOS 생태계 완벽 지원, 바이럴 코딩으로 빠른 개발 가능
⚠️ 주의점: 이메일 숨기기 기능으로 실제 이메일 접근 어려움

3. 카카오 로그인 구현

한국 서비스라면 필수! 하지만 Firebase 직접 연동이 안 되어 Custom Token 방식을 사용해야 한다. 1.9.6 버전에서 Flutter 3.8+ 완벽 지원!

🔄 최신 버전 1.9.6 주요 개선사항

예전 AI 도구들이 추천한 1.7.x 버전과 달리, 1.9.6에서는:

• Flutter 3.8+ 완벽 호환
• 새로운 카카오 정책 대응
• AndroidManifest 설정 방식 변화

의존성 추가 (최신 버전)

# pubspec.yaml - 2025년 8월 기준 최신 안정 버전
dependencies:
  kakao_flutter_sdk: 1.9.6  # 🔥 1.9.6 최신 버전 사용!

🔥 AndroidManifest.xml 설정 - 중요!

코파일럿의 추천을 따라 intent-filter만 추가했다가 계속 오류가 발생했다. 카카오 디벨로퍼 문서를 다시 읽어보니 새로운 activity 전체를 추가해야 하는 것이었다!

<!-- 카카오 로그인을 위한 AuthCodeHandlerActivity -->
<activity android:name="com.kakao.sdk.flutter.AuthCodeCustomTabsActivity">
    <intent-filter android:label="flutter_web_auth">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- Redirect URI: "kakao${NATIVE_APP_KEY}://oauth" -->
        <data android:scheme="kakaoa9f72088774650dd0f2413f8df7a4c92" android:host="oauth"/>
    </intent-filter>
</activity>

💡 교훈: intent-filter 추가가 끝이 아닌, 새로운 activity 추가였다. 새로운 기능 구현에 앞서 문서 정독은 필수라는 걸 다시 한번 깨달았다.

🚨 바이럴 코딩의 최대 함정: OIDC vs Custom Token

카카오 로그인 구현 중 가장 큰 삽질이었다. Firebase와 카카오를 연동하려고 할 때마다 AI들이 계속 OIDC 방식을 추천했는데, 막상 구현해보면 오류가 발생했다.

AI가 자꾸 추천한 OIDC 방식:

// ❌ AI가 추천했지만 실제로는 안 되는 방식
final provider = OAuthProvider("oidc.kakao");
// 계속 오류 발생...

실제로 작동하는 Custom Token 방식:

// ✅ 결국 이 방식으로 해결
Future<UserCredential?> signInWithKakao() async {
  try {
    OAuthToken token = await UserApi.instance.loginWithKakaoTalk();

    // Firebase Custom Token 생성을 위해 서버로 카카오 토큰 전송
    final customToken = await createFirebaseCustomToken(token.accessToken);

    return await FirebaseAuth.instance.signInWithCustomToken(customToken);
  } catch (e) {
    debugPrint('Kakao Sign-In Error: $e');
    return null;
  }
}

💡 교훈: AI가 이론적으로 가능하다고 추천해도, 실제 카카오-Firebase 연동은 Custom Token이 정답이었다!

Firebase Functions (Custom Token 생성)

// functions/src/index.ts
exports.createCustomToken = functions.https.onCall(async (data, context) => {
  const { kakaoAccessToken } = data;

  // 카카오 사용자 정보 검증
  const userInfo = await verifyKakaoToken(kakaoAccessToken);

  // Firebase Custom Token 생성
  const customToken = await admin.auth().createCustomToken(userInfo.id, {
    provider: 'kakao',
    email: userInfo.kakao_account?.email,
    name: userInfo.properties?.nickname
  });

  return { customToken };
});

통합 Provider 설계 🎯

모든 로그인 방식을 하나의 Provider로 관리해서 일관성을 유지했다.

class AuthProvider extends ChangeNotifier {
  User? _user;
  LoginType? _loginType;

  Future<bool> signIn(LoginType type) async {
    try {
      switch (type) {
        case LoginType.google:
          await signInWithGoogle();
          break;
        case LoginType.apple:
          await signInWithApple();
          break;
        case LoginType.kakao:
          await signInWithKakao();
          break;
      }

      if (FirebaseAuth.instance.currentUser != null) {
        _user = FirebaseAuth.instance.currentUser;
        _loginType = type;
        notifyListeners();
        return true;
      }
      return false;
    } catch (e) {
      debugPrint('로그인 실패: $e');
      return false;
    }
  }
}

바이럴 코딩 현실 체크 🤖 vs 📖

이번 프로젝트를 통해 바이럴 코딩(AI 도구 활용)의 명암을 확실히 경험했다.

🟢 바이럴 코딩이 빛난 순간들

1. iOS 설정: Info.plist URL Scheme 설정을 완벽하게 제안
2. 구글 로그인 기본 틀: 전체적인 구조와 Provider 패턴 제안
3. 에러 핸들링: try-catch 구조와 디버그 출력 패턴

🔴 바이럴 코딩이 삽질을 유발한 순간들

1. 구글 로그인 API: 7.1.1 신버전 API를 모르고 구버전 추천
2. 안드로이드 카카오 설정: intent-filter만 추가하라고 해서 계속 오류
3. 카카오-Firebase 연동: OIDC 추천했지만 실제로는 Custom Token 필요

💡 결론: 바이럴 코딩 + 문서 검증 = 최강

• AI 도구로 빠르게 프로토타입 생성
• 오류 발생 시 반드시 공식 문서로 검증
• 최신 버전 변경사항은 AI가 놓치는 경우 많음

주요 이슈 & 해결책 🚨

1. 카카오 로그인 AndroidManifest 설정 (바이럴 코딩 최대 함정)

• 문제: GitHub Copilot이 intent-filter만 추가하라고 해서 계속 오류 발생
• AI 추천: 기존 MainActivity에 <intent-filter> 태그만 추가
• 실제 해결: 완전히 새로운 <activity> 태그 전체를 추가해야 함
• 교훈: 안드로이드 manifest 설정은 AI보다 카카오 디벨로퍼 공식 문서가 정확

2. Google Sign-In 7.1.1 API 변화 (바이럴 코딩 시차 문제)

• 문제: ChatGPT, Copilot 모두 구버전 API(GoogleSignIn().signIn()) 추천
• 실제 해결: 7.1.1부터 initialize() + authenticate() 방식으로 변경
• 교훈: AI는 최신 Breaking Changes를 즉시 반영하지 못함

3. Apple Sign-In 7.0.1 버전 호환성 (바이럴 코딩 성공 사례)

• 문제: 구 버전 5.x 코드가 iOS 17에서 간헐적 오류 발생
• AI 도움: Copilot이 7.0.1 버전 업그레이드와 Info.plist 설정을 완벽 제안
• 결과: 업그레이드 후 iOS에서 가장 안정적으로 작동

4. Kakao SDK 1.9.6 Flutter 3.8+ 대응

• 문제: 바이럴 코딩으로 찾은 1.7.x 버전이 최신 Flutter와 호환 문제
• 해결: pub.dev에서 직접 확인 후 1.9.6 업데이트로 완벽 호환성 확보

5. 카카오-Firebase OIDC vs Custom Token (AI의 이론 vs 현실)

• 문제: AI들이 계속 OIDC 방식(OAuthProvider("oidc.kakao")) 추천
• 현실: 실제로는 Custom Token 방식만 안정적으로 작동
• 교훈: AI가 이론적으로 가능하다고 해도 실제 구현에서는 다를 수 있음

5. iOS Apple Sign-In 인증서 설정

• 문제: Xcode에서 Sign-In with Apple capability 누락
• 해결: Capabilities 탭에서 Sign-In with Apple 활성화

4. 로그인 상태 지속성

• 문제: 앱 재시작 시 로그인 상태 유지 안됨
• 해결: Firebase Auth의 authStateChanges 스트림 활용

성능 최적화 팁 ⚡

1. 지연 로딩: 각 로그인 SDK는 필요할 때만 초기화
2. 토큰 캐싱: 로그인 토큰을 안전하게 캐싱해서 재로그인 빈도 줄이기
3. 에러 핸들링: 사용자에게 친화적인 에러 메시지 제공

마무리 🎉

Firebase와 소셜 로그인을 모두 구현하면서 각 플랫폼의 특징을 이해할 수 있었다. 특히 카카오 로그인에서 문서를 제대로 읽지 않아 삽질한 경험과, 구글 로그인에서 바이럴 코딩만 믿다가 API 변경사항을 놓친 경험이 가장 기억에 남는다.

🚨 바이럴 코딩의 현실적 한계:

• AI 도구들은 최신 버전 변경사항을 즉시 반영하지 못함 (특히 Google Sign-In 7.1.1)
• 이론적으로 가능한 방식과 실제 작동하는 방식이 다름 (카카오 OIDC vs Custom Token)
• 플랫폼별 세부 설정은 공식 문서가 더 정확함 (안드로이드 manifest)
• 하지만 iOS 설정과 전체 구조 설계에서는 큰 도움이 됨

핵심 교훈:

• 공식 문서를 꼼꼼히 읽자 📖
• AI 도구로 빠른 프로토타입 → 공식 문서로 검증 🔍
• 각 플랫폼별 특성을 이해하고 구현하자 💪
• 최신 버전 변경사항은 반드시 직접 확인하자 🔄
• 바이럴 코딩 ≠ 만능, 적재적소에 활용하는 지혜 필요 🧠

🔮 앞으로의 계획

이 글은 2025년 8월 기준 최신 안정 버전으로 작성되었다:

• firebase_core: 4.0.0
• firebase_auth: 6.0.0
• google_sign_in: 7.1.1
• sign_in_with_apple: 7.0.1
• kakao_flutter_sdk: 1.9.6

하지만 Flutter와 Firebase 생태계는 빠르게 변화한다.

📝 지속적인 업데이트 다짐:

• 🔄 월 1회 버전 체크: 새로운 버전 출시 시 즉시 테스트 및 글 업데이트
• 🚨 Breaking Changes 대응: 주요 API 변경 시 48시간 내 마이그레이션 가이드 추가
• 📦 새 플랫폼 추가: 네이버, 페이스북 등 추가 소셜 로그인 구현 시 즉시 공유
• 💬 커뮤니티 피드백: 댓글로 받은 최신 이슈들 반영해서 지속 개선

⚠️ 주의: 이 글을 참고하실 때는 현재 사용 중인 패키지 버전을 확인하고, 필요시 최신 공식 문서를 함께 참조해주세요!

Flutter 앱에서 Pretendard Variable 폰트를 사용했는데, Android에서만 텍스트가 흐릿하게 렌더링되는 문제가 발생했습니다.

# 문제가 있던 설정
fonts:
  - family: Pretendard
    fonts:
      - asset: assets/fonts/PretendardVariable.ttf

!Before

🔍 원인 분석

Variable 폰트(.ttf)는 하나의 파일에 여러 weight를 포함하고 있어 편리하지만, Android의 폰트 렌더링 엔진에서 최적화 문제를 일으킬 수 있습니다.

• iOS: Variable 폰트 렌더링 ✅
• Android: Variable 폰트 렌더링 ❌ (흐림 현상)

✅ 해결 방법

1. Static 폰트 파일 다운로드

Pretendard GitHub에서 Static 폰트들을 다운로드합니다.

# assets/fonts/ 폴더에 다운로드
curl -L -o "Pretendard-Light.otf" "https://github.com/orioncactus/pretendard/raw/main/packages/pretendard/dist/otf/Pretendard-Light.otf"
curl -L -o "Pretendard-Regular.otf" "https://github.com/orioncactus/pretendard/raw/main/packages/pretendard/dist/otf/Pretendard-Regular.otf"
curl -L -o "Pretendard-Medium.otf" "https://github.com/orioncactus/pretendard/raw/main/packages/pretendard/dist/otf/Pretendard-Medium.otf"
curl -L -o "Pretendard-SemiBold.otf" "https://github.com/orioncactus/pretendard/raw/main/packages/pretendard/dist/otf/Pretendard-SemiBold.otf"

2. pubspec.yaml 수정

fonts:
  - family: Pretendard
    fonts:
      - asset: assets/fonts/Pretendard-Light.otf
        weight: 300
      - asset: assets/fonts/Pretendard-Regular.otf
        weight: 400
      - asset: assets/fonts/Pretendard-Medium.otf
        weight: 500
      - asset: assets/fonts/Pretendard-SemiBold.otf
        weight: 600

3. 프로젝트 클린 빌드

flutter clean
flutter pub get
flutter run

🎯 결과

!After

Android에서도 선명하고 깔끔한 Pretendard 폰트 렌더링이 가능해졌습니다!

💡 핵심 포인트

Variable vs Static 폰트 선택 기준

추가 최적화 팁

// 텍스트 렌더링 최적화
Text(
  '텍스트 내용',
  style: TextStyle(
    fontFamily: 'Pretendard',
    fontSize: 20.sp,
    fontWeight: FontWeight.w600,
    letterSpacing: -0.5, // 한글 최적화
  ),
  textScaleFactor: 1.0, // 시스템 폰트 크기 무시
)

🔗 참고 자료

• Pretendard GitHub
• Flutter 폰트 설정 가이드

바로 key.properties 설정과 keystore를 통한 앱 서명(Signing) 과정이다.

많은 튜토리얼이 "그냥 이대로 따라하세요"라고 하지만,
나는 이번에 배포하면서 왜 이런 게 필요한지, 이 구조가 뭘 의미하는지가 정말 궁금했다.
그래서 하나하나 뜯어보며 정리해봤다.

📦 key.properties가 뭐길래 꼭 만들라고 할까?

Flutter 공식 가이드에서 Android 배포를 위해 아래와 같은 파일을 만들라고 한다:

storePassword=abc12345
keyPassword=abc12345
keyAlias=upload
storeFile=../upload-keystore.jks

이 파일은 앱 서명에 필요한 비밀번호와 키 정보를 담고 있고, 이를 통해 Gradle이 앱을 릴리즈 모드로 빌드할 때 자동으로 서명할 수 있도록 도와준다.

❗ 중요한 건, 이 파일은 git에 절대 올리지 말아야 하며 .gitignore에 반드시 추가해줘야 한다.

🔐 keystore.jks는 뭐고, 어떻게 만들지?

서명을 하려면 “키”가 필요하다. 이 키는 keystore.jks 파일 안에 들어있고, 우리가 직접 생성해야 한다.

keytool -genkey -v \
 -keystore upload-keystore.jks \
 -alias upload \
 -keyalg RSA \
 -keysize 2048 \
 -validity 10000

이 명령어는 Java가 설치돼 있으면 터미널에서 바로 실행할 수 있다.

입력값: • keystore 파일명 • alias (키 이름) • 비밀번호 (2개: storePassword, keyPassword) • 유효 기간 등

⚙️ build.gradle.kts는 왜 필요한가?

key.properties를 만든 것만으로 끝이 아니다. 실제 앱 빌드시 그 정보를 사용하는 코드가 android/app/build.gradle.kts 안에 존재해야 한다.

signingConfigs {
    create("release") {
        keyAlias = keystoreProperties["keyAlias"] as String
        keyPassword = keystoreProperties["keyPassword"] as String
        storeFile = file(keystoreProperties["storeFile"] as String)
        storePassword = keystoreProperties["storePassword"] as String
    }
}

이 설정은 Gradle에게 릴리즈 빌드 시 어떤 키로 서명할지 알려주는 역할을 한다.

🛠️ 릴리즈 빌드할 때 서명은 어떻게 동작할까?

flutter build apk --release

이 명령어를 실행하면, Flutter는 내부적으로 Gradle을 실행하고 signingConfigs.release 설정을 참조해서 앱을 keystore.jks로 서명한다.

🔍 반대로 디버그 빌드 (flutter run, flutter build apk --debug) 는 Android가 자체 제공하는 디버그 키로 자동 서명된다.

🔄 Google Play가 서명을 대신 해준다는데… 왜 내가 keystore를 만들어야 할까?

key.properties를 세팅하다가, 이번에 우연히 Google Play App Signing이라는 개념을 처음 제대로 알게 됐다. ‘어? 구글이 알아서 서명까지 해준다고? 그럼 내가 굳이 keystore 만들 필요 없지 않나?’ 싶었다.

하지만 이걸 알아보면 볼수록, 앱 서명의 흐름과 키 관리의 중요성에 대해 반드시 이해해야겠다는 생각이 들었다.

💡 App Signing 구조 이해

Google Play는 앱을 대신 서명해주는 구조를 제공한다. 하지만 여전히 우리가 만든 keystore.jks는 필요하다.

왜냐하면…

용어 설명 업로드 키 (Upload key) 우리가 직접 만든 키. 이걸로 서명된 APK만 Google Play에 업로드 가능 서명 키 (App Signing key) Google이 따로 보관하는 키. 실제 사용자에게 배포되는 APK는 이 키로 다시 서명됨

즉, • 우리가 만든 키는 앱을 Google Play에 업로드하는 권한을 가진 인증서 역할 • Google은 실제 배포 전에 서명 키로 다시 서명해서 배포

🔐 중요한 점: 업로드 키를 분실하면?

➡️ Google에 업로드 자체가 불가능하다.(재발급 가능!) ➡️ 앱을 다시 새로 올려야 하는 경우도 발생.

따라서 이 키는 GitHub에 올리지 않되, 꼭 안전한 곳에 백업해두는 것이 중요하다.

🧾 해시 키(SHA-1, SHA-256)는 왜 필요한가?

앱이 서명되면, 서명된 키로부터 해시 값(SHA-1, SHA-256 등) 을 뽑아낼 수 있다. 이 값은 외부 인증 연동 시 꼭 필요하다.

🔐 주요 사용처 • Google 로그인, Firebase 인증 • 카카오 / 네이버 로그인 • Facebook 로그인

🔧 출력 방법

keytool -exportcert \
  -alias upload \
  -keystore upload-keystore.jks \
  -storepass abc12345 \
  -keypass abc12345 \
  | openssl sha1 -binary | openssl base64

결과로 나오는 SHA1: 또는 SHA256: 값을 콘솔에 복사해서, Firebase 콘솔이나 카카오 디벨로퍼에 등록하면 된다.

🔒 key.properties 보안 관리 팁 • .gitignore에 반드시 추가 • key.properties.template 같은 샘플은 공유 가능 • CI/CD(GitHub Actions, Bitrise 등)에서는 secrets 기능을 이용해 주입

예: GitHub Actions에서 환경 변수로 등록 후, key.properties를 런타임에 생성

✅ 마무리하며

Flutter로 Android 앱을 배포할 때 반드시 알아야 할 것들:

항목 설명 keystore.jks 내가 만든 서명 키 저장소 key.properties 민감한 정보를 안전하게 분리 build.gradle.kts 릴리즈 빌드 시 서명에 적용 Google Play App Signing 실제 배포는 Google이 서명하되, Upload Key는 필요 해시 키 출력 인증 연동 필수 정보 보안 관리 백업 + 비공개 저장 + CI/CD 연동 고려

단순히 “하라는 대로 따라하기”를 넘어서, 서명의 구조를 이해하고, 리스크를 줄이며, 제대로 된 배포를 할 수 있는 개발자가 되자. 🧠

요즘은 나 자신에게 자주 묻는다.
지금 나는 어떤 걸 만들고 싶을까?
누구와 만들고 싶을까?

10년 동안 개발자로 일해왔다.
수많은 프로젝트를 겪고, 크고 작은 서비스를 만들었다.
하지만 언젠가부터
‘어떻게’ 만드는지는 익숙해졌는데,
‘왜’ 만드는지에 대한 감각은 흐려지고 있었다.

얼마 전, 플랫폼 서비스를 직접 만들어본 일이 있다.
기획, 설계, 마케팅, 영업까지 —
모든 걸 혼자 해보는 도전이었다.
잘 해내고 싶었다. 진짜로 끝까지 가보고 싶었다.

그래서 밤을 새우며 기획서를 쓰고,
디자인 툴을 독학하고,
SNS 광고 문구를 고치고 또 고쳤다.
개발은 익숙했지만,
그 외의 것들은 낯설고 버거웠다.

그 과정에서 다행히 두 명의 지인이 도와줬다.
한 명은 디자인을, 또 한 명은 기획을 함께 봐줬다.
둘 다 본업이 있는 사람들이었지만,
틈틈이 시간을 내어 함께 회의하고, 조언도 아끼지 않았다.

그때 처음 알게 됐다.
혼자서 할 수 없다는 건 ‘일의 양’ 때문만은 아니라는 걸.

함께하면,
같은 문제도 다른 각도로 바라보게 되고
놓치고 있던 흐름이 문득 보이기도 했다.
일을 나눈 게 아니라, 시야를 나눈 것이었다.

그 경험이 나를 바꿨다.
‘혼자 만드는 것’이 아니라
‘여럿이 함께 탐색하는 실험’에 마음이 끌리기 시작했다.

그래서 오픈플랜이라는 이름을 붙였다.
어떤 거창한 철학이 담긴 건 아니다.
그냥, 열린 계획.
여러 사람의 시선이 모이는 작은 실험실 같은 모임.

내가 만든 글 하나로 몇 명이 모였다.
직업도, 관심사도, 말투도 다 달랐다.
누군가는 UI/UX를 탐구하고 싶다고 했고,
누군가는 데이터를 만지고 싶다고 했고,
누군가는 “왜 이런 서비스는 아직 없을까?” 하는 질문을 품고 있었다.

그게 좋았다.
전문가가 아니어도,
공부 중이거나 막 관심이 생긴 단계여도 괜찮았다.
그 다양한 시선들이,
내가 혼자선 보지 못한 것들을 보여줬다.

우리는 아직 아무것도 확실하지 않다.
어떤 플랫폼을 만들지,
어디까지 갈 수 있을지,
우리도 잘 모른다.

하지만 이 모임은 분명
오래 닫혀 있던 나의 호기심을 다시 열었고,
머릿속에만 맴돌던 아이디어에 온기를 불어넣었다.

이 글은 그 시작의 기록이다.
누군가 이 글을 읽고,
비슷한 고민을 하고 있었다면 —
언젠가 우리는 같은 테이블에 앉아 있을지도 모른다.

그럼, 다음 이야기는 또 다음에.

✅ 기본 사용법

flutter create 프로젝트명

예:

flutter create byseungjeapp

위 명령어 하나로 아래와 같은 멀티 플랫폼 프로젝트가 생성된다:

• Android
• iOS
• 웹
• macOS
• Windows (설정 시)

하지만 여기서 진짜 중요한 건 "이 명령어가 무엇을 만들어 주느냐" 이다.

📦 flutter create가 실제로 생성하는 것

flutter create 명령어는 단순히 파일을 생성하는 수준이 아니다. Flutter SDK 내부 템플릿 시스템을 기반으로 다음을 자동 구성한다:

• android/, ios/: 플랫폼별 네이티브 프로젝트 (Gradle, Xcode 기반)
• lib/main.dart: 앱 진입점 (Flutter 앱의 시작 지점)
• test/: 테스트 디렉토리
• pubspec.yaml: 의존성, 앱 정보, 에셋 관리 파일
• .gitignore, README.md, analysis_options.yaml 등 개발 편의 파일

즉, Flutter 앱을 만들기 위한 골격을 완성해주는 작업이다.

🔧 자주 쓰는 옵션 정리

앱을 생성하면서 한 번에 설정하면 좋은 옵션들을 정리했다 👇

📌 --org

앱의 패키지 이름을 정한다. 보통 도메인을 반대로 써서 고유 식별자를 만든다.

--org com.byseungje

💡 결과: com.byseungje.byseungjeapp 같은 형태의 패키지 ID 생성 👉 Android의 applicationId, iOS의 bundleIdentifier에 영향을 준다

📌 --project-name

프로젝트 이름 지정 (디렉토리명 = 앱명 기준). ⚠️ 소문자와 _(언더스코어)만 허용됨

--project-name byseungjeapp

💡 CLI 내부에서 이 값이 class 이름, 디렉토리 명 등에 영향을 줌

📌 --description

앱 설명. pubspec.yaml에 자동 반영된다. (패키지로 배포할 때 중요한 메타 정보!)

--description "flutter를 생성하는 명령어에 대한 설명!"

📌 --platforms

필요한 플랫폼만 선택해서 생성 가능 필요 없는 플랫폼을 제거하면 불필요한 리소스와 설정을 줄일 수 있다.

--platforms=android,ios

💡 예: macOS, 웹을 지원하지 않을 경우 명시적으로 제외하는 것이 좋음

💡 실제 사용 예

나는 아래와 같이 명령어를 사용해서 프로젝트를 생성했다:

flutter create \
  --org com.byseungje \
  --project-name byseungjeapp \
  --description "flutter를 생성하는 명령어에 대한 설명!" \
  --platforms=android,ios \
  byseungjeapp

📁 생성된 디렉토리 구조

실행하면 아래와 같은 디렉토리 구조가 생성된다:

byseungjeapp/
├── android/          # 안드로이드 네이티브 프로젝트
├── ios/              # iOS 네이티브 프로젝트
├── lib/              # Flutter 코드 (main.dart 위치)
├── test/             # 테스트 코드
└── pubspec.yaml      # 앱 설정과 의존성 관리

🧠 왜 이런 옵션들이 중요한가?

생성형 AI 시대에 단순 명령어는 쉽게 찾을 수 있다. 하지만 왜 그 명령어를 써야 하는지, 어떤 설정이 앱의 구조에 어떤 영향을 주는지를 아는 건 여전히 중요하다.

• --org: 나중에 앱 배포 시 충돌 방지 및 고유 식별
• --project-name: 앱 코드의 기본 네이밍 컨벤션과 연결
• --description: 패키지 관리와 메타데이터 관리를 위해
• --platforms: 빌드 시간과 앱 크기 최적화

✨ 마무리

flutter create는 단순한 시작 명령이 아니다. 앱 구조, 플랫폼, 패키지 ID 같은 중요한 기초 설계를 설정하는 단계다.

🚀 처음부터 정확히 설정하면 나중에 수정할 일이 줄어든다. 🎯 특히 --org, --platforms는 나중에 변경하기 복잡하니 신중하게 설정하자!

“서버는 어떻게 요청이 앱에서 왔는지, 웹에서 왔는지 알 수 있을까?”

최근 프로젝트에서 요청을 구분해서 로깅하거나 통계 처리를 하다 보니, 사용자 디바이스 종류(iOS/Android/Web 등)를 서버에서 식별할 필요가 생겼습니다. 이럴 때 핵심적으로 사용하는 게 바로 HTTP 헤더입니다.

1. HTTP 헤더란?

HTTP 헤더는 클라이언트와 서버 간의 요청/응답에서 부가 정보를 담는 메타데이터입니다. 모든 HTTP 요청은 헤더와 함께 오고, 이 정보를 기반으로 서버는 다양한 처리를 할 수 있습니다.

GET /hello HTTP/1.1
Host: example.com
User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)
Authorization: Bearer eyJhbGciOi...

2. 주요 요청 헤더

3. User-Agent로 웹/앱 구분하기

User-Agent에는 클라이언트 정보가 포함되어 있어, 간단한 문자열 비교만으로 디바이스 종류를 구분할 수 있습니다.

예:

String ua = request.getHeader("User-Agent");

if (ua.contains("Dart") || ua.contains("PostmanRuntime")) {
    return "앱 요청";
} else if (ua.contains("Mozilla") || ua.contains("Chrome") || ua.contains("Safari")) {
    return "웹 요청";
}

참고: Flutter에서 Dio로 요청하면 Dart 문자열이 포함됩니다.

4. 더 정밀한 기기 구분: 커스텀 헤더

User-Agent 만으로는 iOS/Android/웹 정도만 구분할 수 있고, 기기 모델명이나 앱 버전은 알 수 없습니다.
이럴 때는 앱에서 커스텀 HTTP 헤더를 만들어서 보내면 됩니다.

Flutter 예시

final dio = Dio();
dio.options.headers["X-Device-Model"] = "iPhone13,4";
dio.options.headers["X-App-Version"] = "1.2.3";

서버 (Spring Boot)

String model = request.getHeader("X-Device-Model");
String version = request.getHeader("X-App-Version");

이렇게 하면 로그나 통계 시스템에서 앱 버전별 이슈 파악, 기기별 오류 분석도 가능해져 실무에서 매우 유용합니다.

5. 실무 팁

• 모든 API 요청에 X-Platform-Type, X-App-Version, X-Device-Model 같은 헤더를 포함하세요.
• 디바이스 분류 (0: 앱, 1: 웹, -1: 미분류) 정도는 공통 유틸로 분리해 관리하면 편리합니다.
• 로그 시스템에 이 정보를 함께 저장하면 사용자 경험 개선에 큰 도움이 됩니다.

마무리

서버는 기본적으로 사용자의 디바이스 정보를 직접 알 수 없습니다.
하지만 HTTP 헤더를 잘 활용하면 요청을 구분하고, 디바이스 특성에 맞게 처리하는 유연한 백엔드 시스템을 만들 수 있습니다.