1년 가까이 Claude Code로 작업하면서, 처음에는 프롬프트를 잘 쓰는 데 집중했고 그다음엔 컨텍스트를 잘 만드는 데 집중했습니다. 그런데 지금 돌아보니, 에이전트가 일하는 환경을 설계하는 일이 가장 중요한 것 같습니다. 환경을 어떻게 구성하면 에이전트가 더 잘 일하는지를 4가지 장치로 정리한 노트입니다.

개요: 환경을 고치면 결과가 바뀐다

에이전트가 같은 실수를 반복할 때, 결과물을 사람이 고치는 건 초보적인 단계이며, 지속 가능하지 않습니다. 왜냐하면 ai에이전트의 생산속도는 우리가 리뷰하고 고치는 속도를 이미 뛰어넘었기 떄문입니다. 오히려 에이전트에게 같은 실수를 다시 못 하도록 환경을 고치는 게 현재 단계에서 가장 효과적인 전략입니다. 물론, 다음 주만 되어도 이 전략이 구식이 될 수도 있습니다(그러길 바래요!)

1년 정도 에이전트로 일해본 현재 단계에서 여기저기 귀동냥 하고 공부하며 어떻게 구성하면 에이전트가 더 잘 일하는지를 제 기준으로 정리한 노트입니다. 메모리 룰, Don'ts 룰을 비롯해서 여러 내/외부 도구를 운영하면서 만든 팁을 4가지 카테고리로 풀어봤습니다.

4가지 장치 분류(Commands/Rules/Skills/Hooks)는 Anthropic의 Harness design for long-running apps 자료와 교차 검증해 정리했습니다.

이미 이전에 제 velog에 작성한 에이전트 폭주 방지, 페르소나의 한계, 살아남은 Skill 5종 등 포스팅을 통해 공유한 팁의 총합본 같은 느낌입니다.

1. 프롬프트 < 컨텍스트 < "환경"

필드에 있으면서 느낀 AI 엔지니어링의 무게중심은 이렇게 옮겨온 것 같습니다. (더 빨리 옮겨졌을 수 있음!)

프롬프트와 컨텍스트는 휘발성입니다. 세션이 끝나면 사라집니다. 반면 환경 설계는 리포지토리에 남는 자산입니다. 이게 무게중심 이동의 핵심 분기점입니다.

다음 호출에서도 살아남는 것을 만들기 위해서 기술도 발전하고, 기술을 사용하는 개발자들도 같이 발전한 것 같아요.

2. 1년 운영하면서 굳어진 결론 세 가지

Flutter APP, SAAS web, Unity 게임, React + Supabase 웹앱 등을 포함해 여러 프로젝트를 매니징 해주고, 그 외에도 내가 귀찮아 하고 어려워 하는 마케팅·기획·CS·책 노트·요리까지 묶은 허브 리포지토리(나는 ideaBank라고 부르고, 다른 사람에게는 자비스라고 소개중)를 동시에 굴리면서 1년을 보냈습니다. 도메인이 전혀 다른데도 같은 실수가 다른 모습으로 반복되더군요 — Unity 퀘스트 가드 누락이나 React 컴포넌트 prop drilling이나, 결국은 "에이전트가 같은 패턴을 다시 만들고 있는데 이걸 막을 룰이 없다"는 한 가지 문제로 수렴했습니다. 룰을 어디에 어떻게 쌓느냐에서 나온다는 게 보였습니다.

이 시행착오를 압축하면, 제 개발 기록을 통해서는 3가지 정도 팁을 얻을 수 있습니다.

1. 에이전트의 실수는 코드의 문제가 아니라 환경 설계의 미비다.

• 에이전트가 실수했을 때 결과물을 사람이 고치는 건 하수. 에이전트가 다시는 그 실수를 못 하도록 규칙·검증·훅을 수정하는 게 고수라고 개발자 선배가 그러더라구요?
• 예를 들어 개발중인 게임에서 퀘스트 보상이 두 번 지급되는 버그를 잡았을 때, 코드만 고치고 끝낸 게 아니라 "퀘스트 조건 체크 시 isCompleting 가드 필수"를 룰로 승격시킵니다.
• 이러면 어떤 모델과 일하는 지는 상관없이, 다음 작업에서는 자동으로 막힙니다. 이걸 donts.md와 feedback_*.md 메모리 파일에 꼼꼼히 기재하도록 규칙을 세워 꾸준히 실수 패턴을 축적해보니 확실히 개선되는게 보였습니다(같은 실수를 두 번 보면 룰로 승격시킨다는 단순한 원칙입니다)

2. 자율성과 통제는 반비례가 아니라 정비례다.

• 모델이 똑똑해질수록 runaway(통제 불능) 위험도 같이 커집니다. 다행히 전 그런 일이 없었는데, 모델이 마음대로 마케팅 강의를 결제하거나 하는 등 폭주한 사례는 이미 유명하죠?!
• 앞서서 "폭주 방지"에 대한 velog글도 썼는데, 그것도 여기서 출발했습니다. "적합한" 통제 장치가 잘 세팅되면 더 큰 작업을 안전하게 맡길 수 있습니다. 하네스 엔지니어링이라고 부르죠 이젠?!

3. 개발자는 코드를 짜는 사람이 아니라, AI가 코드를 잘 짤 수 있는 환경을 짓는 건축가다.

• 손으로 친 코드 라인 수보다, 에이전트가 잘 작동하도록 만든 룰·훅·도구의 코드 라인이 이제 비교할 수 없을 만큼 깁니다. 우리는 "AI-native 개발자 / Harness Engineer"가 되기 위해 노력하고, 개발을 잘 기획하는 사람이 되기 위해 노력해야 하는 시대가 되었다고 생각합니다.

3. Claude 사용 환경을 구성하는 4가지 장치

환경을 구성하는 4개의 카테고리입니다. 각 장치가 어떤 역할을 하는지, 제 시스템에서 어떻게 작동하는지 매핑해봤습니다.

각 장치는 다른 조건을 책임집니다. Commands는 반복 진입의 일관성, Rules는 상시 판단의 기준, Skills는 확장된 능력, Hooks는 이벤트 기반 강제력. 4개가 한 세트로 갖춰지면 에이전트가 같은 작업에서 매번 같은 품질을 내고, 같은 실수를 반복하지 않으며, 사람이 일일이 검토하지 않아도 결과물이 안정됩니다.

하나라도 비면 다른 쪽에 부담이 쏠립니다. 예를 들어 Hook이 약하면 Rules에 "이건 하지 마세요"를 10배 적어야 해서 컨텍스트 예산만 잡아먹습니다. Skills가 빈약하면 같은 작업을 매번 프롬프트로 풀어 설명하느라 토큰을 낭비합니다.

4. 4가지 장치로 본 제 시스템의 약한 지점

잘 갖춰진 영역은 3부작에서 이미 써봤으니, 이번엔 비어 있는 쪽에 집중해봤습니다. *Claude가 분석해주었습니다

이 표를 만들고 보니, 제 시스템은 Commands와 Rules는 촘촘한데, Hooks와 감사 루틴이 얇다는 비대칭이 있었습니다. 다음에 손봐야 할 우선순위가 여기서 나옵니다.

5. 약점을 어떻게 메우고 있나

5.1 보안 스캔으로 Hook 커버리지 보완

현재 제가 쓰는 ideaBank 프로젝트엔 9개의 커스텀 에이전트 + 다수 hook + MCP 서버 7개(Context7, PixelLab, Notion 등) + 권한관련 설정(settings.json)이 있습니다.

그런데 가장 문제가 이 환경 자체를 정기 검사하는 수단이 없었습니다. 뭘 더 좋아지게 만드려면 혹은 사고치는걸 막으려면 제대로 검사를 해야하는데.. 에이전트 정의에 시크릿이 흘렀는지, hook에 명령 주입 여지가 있는지, MCP 권한이 과한지 점검할 도구 자체가 없어서 고민이 좀 있었습니다.

Everything Claude Code 레포의 security-scan 스킬(AgentShield, 1282 tests / 102 rules)을 한 번 돌렸습니다. 결과:

• 위험 명령 차단을 위한 deny list 보강
• 자동 커밋 hook이 토큰을 흘릴 수 있는 경로를 잡아 시크릿 필터 + 로테이션
• 노출 가능성 있는 Vercel 토큰 회수

Hook 자체가 두꺼워진 건 아니지만, 기존 Hook의 약한 지점을 데이터로 본 것만으로도 다음 보강 우선순위가 명확해졌습니다.

5.2 실수 패턴 방지 제도

(4번 표에선 두 약점으로 나눴지만 결국 같은 결의 문제 — 룰을 어떻게 쌓고 어떻게 승격시키느냐. 처방을 묶어서 다룹니다)

feedback_*.md 메모리가 30+개로 누적되는데 일부만 정식 룰로 승격되는 게 가장 큰 문제였습니다. 그래서 두 가지 절차를 박았습니다.

(1) 삼진아웃 제도 — 같은 패턴이 몇 번 반복되면 룰로 올리는지 명시:

(2( 기능별 Don'ts 분리: 실수를 반복하지 않는 체계를 구축합니다. 그리고 파일에 다 쌓으면 컨텍스트 부담이 커지니 아래처럼 분기해두면 좋습니다.

• donts.md — 전역 (모든 작업 공통)
• donts/game.md — 게임/Unity 개발
• donts/someProject.md — 특정 프로젝트 개발
• donts/marketing.md — 마케팅/콘텐츠 아티클 발행 및 수정
• donts/images.md — 이미지/에셋

이젠 작업 진입 시 해당 파일만 로드하니 평소 컨텍스트가 가벼워졌습니다. 룰화 자체를 더 자동화하는 건 ECC /learn 패턴 시범 검토 중.

5.3 컨텍스트 예산 진단(Harness Audit 부재관련)

/context-budget을 한 번 돌려서 토큰 분포를 봤더니 매 세션 강제 로드는 ~3%로 양호했습니다. 그런데 부수 발견이 더 컸어요 — 마케팅 에이전트 3개(brand-manager, content-adapter, marketing-director)에 YAML frontmatter가 누락돼 있어 Claude Code가 자동 매칭으로 호출하지 못하는 상태였습니다. 진단한 같은 날 3개 모두 frontmatter 추가해 정상화.

진단 도구 한 번 돌리는 게 잠재 결함을 수면 위로 끌어올렸습니다. 정기 감사 루틴까진 아직이지만, 진단의 ROI는 확인됐어요.

5.4 포매터 강제 (Handoff 규격)

Designer → Implementer 전달물이 자유형 텍스트라 포맷이 들쭉날쭉한 문제는 에이전트 효율을 위해 중요한 문제라고 하더라구요. 그래서 이를 VLM 추론 결과 처리를 공부하며 3단 안전장치를 설계하고 적용하고 있습니다. (이전 글에 작성한 내용입니다.)

① 모델에 JSON 응답 모드 강제(responseMimeType: 'application/json'), ② 정규식으로 첫 {...} 블록만 추출(prose/펜스 섞여 와도 잡힘), ③ JSON.parse + 스키마 검증(필수 필드/타입 안 맞으면 명확한 에러로 차단).

이 패턴을 공부하며 ideaBank등 기존 프로젝트들에도 적용하려고 합니다. 이를 통해서 Designer에이전트가 Implementer에게 핸드오프 할 떄 효율을 올려볼 계획입니다.

정리: 환경을 개발하는 것이 자산이 되는 이유

모델을 믿지 말고, 모델이 최고 성능을 낼 수밖에 없는 환경을 만들어봅시다.

모델은 비정기적으로 바뀝니다. 그래도 잘 구축한 환경(Commands, Rules, Skills, Hooks)은 다음 모델에서도 그대로 살아남을 확률이 높습니다. 새 모델이 나왔을 때 개선점만 집어넣고, 처음부터 다시 시작하지 않아도 됩니다. 안그래도 최근에 Opus의 버전업과 동시에 Claude쪽에 이슈가 있었다는 개발자님들이 의견이 많이 보였습니다. 이러한 시행착오의 노트가 도움이 되기 바랍니다.

참고 자료

• 하네스 엔지니어링: 에이전트 폭주 방지 Tip
• 하네스 엔지니어링: 페르소나 설정은 정말 효율적인가?
• 하네스 엔지니어링: Claude Skill 작성 Tip
• Anthropic - Harness design for long-running apps
• Everything Claude Code : 앤쓰로픽 해커톤 우승작!!

공부하면서 알게된, LLM/VLM을 실제로 쓰는 개발자가 자주 마주치는 파라미터와 구조 뒤에 어떤 메커니즘이 있는지를 정리해 봤습니다.

개요

VLM(Vision-Language Model)으로 영상 행동 분류 PoC를 만들면서 모델 호출 옵션과 JSON 출력 안정화 코드를 직접 손대게 됐습니다. 에이전트로 컨트롤 하더라도 그 과정에서 코드에 자주 등장한 단어나, 개념들을 알아두어야 적절한 조정이 가능하기 때문에 직접 학습에 들어갔습니다.

처음 보면 당황할 만한 단어들이 많으니, 기본 개념을 공부해봅시다.

• temperature : 모델이 다음 토큰을 뽑을 때 확률 분포를 얼마나 뾰족하게 만들지 조절하는 파라미터
• topP(Top-P, Nucleus Sampling): 후보 토큰을 누적 확률 P까지만 남기고 자르는 규칙
• JSON 출력 방어: 모델 응답을 JSON 형식으로 안정적으로 받기 위한 다층 설계

이 단어들의 정확한 의미를 알고, 각 결정의 근거가 명확히 있어야 파라미터 선택이 추측이 아니게 됩니다.

어디에 쓰고, 어디에 도움이 될까?

메커니즘을 알면 LLM 도구 결정이 추측에서 근거로 바뀝니다. VLM으로 영상을 분류시킬 때 겪을 수 있는 다음 상황에서 의사결정의 근거가 됩니다.

• "프롬프트 이렇게 쓰면 좋다" 류 팁이 어떤 건 통하고 어떤 건 안 통하는지 안 보일 때. 표층 팁 뒤의 메커니즘이 보이면 그 팁이 통하는 조건과 안 통하는 조건이 분리됩니다.
• 같은 입력에 호출마다 다른 답이 나올 때. "왜 결과가 흔들리지?"를 "다양성이 너무 높아서"라는 일반론으로 넘기지 않고, 분포가 어떻게 만들어지고 어떻게 가공되는지를 알면 temperature 같은 파라미터를 손대는 근거가 생깁니다.
• 파라미터 추천값을 그냥 따라 썼는데 효과를 설명하기 어려울 때. topP 0.95가 후보 토큰을 어떻게 자르는지 메커니즘을 알면 0.95냐 0.5냐 결정이 추측이 아닌 계산이 됩니다.
• JSON 출력이 가끔 깨져서 후처리가 멈출 때. 프롬프트만 바꾸다가 안 풀리는 이유, 그리고 SDK 설정·정규식 fallback이 왜 따로 필요한지가 보입니다. 3단 설계로 갈 근거가 명확해집니다.
• VLM이 confidence 값을 같이 주는데 그걸로 뭘 해야 할지 막막할 때. 모델 자체 점수와 우리가 정하는 cutoff 룰이 어떻게 다른지 구분이 되면, "낮으면 재호출"이 아니라 "낮으면 사람 큐"라는 설계 결정이 자연스럽게 따라옵니다.

메커니즘 5가지

1. 어휘집(vocabulary)과 토큰 분포

개념:

• 모델이 아는 모든 토큰의 사전을 어휘집(vocabulary)이라 합니다(Gemini 2.5 Flash 기준 약 25만 개)
• 한 토큰을 생성할 때마다 이 25만 개 전체에 확률 분포가 만들어집니다. 즉, 매 스텝마다 25만 개 전체에 새 분포가 생기고 그 중 1개가 뽑힙니다.

비유:

• 날씨 예보와 같습니다. 내일 날씨 예보는 "비 70%, 흐림 15%, 맑음 10%, 눈 3%, 안개 2%"처럼 모든 가능성에 확률을 부여합니다. 비만 후보인 게 아니라 눈에도 작은 확률이 있습니다. 토큰 분포도 마찬가지입니다.

실전:

• 이 구조를 모르면 이후 공부할 temperature를 바꿔도 무슨 일이 벌어지는지 알 수 없습니다. 분포 가공 방법(temperature·topP)은 다음 항목에서 다룹니다.

2. Autoregressive 생성

개념:

• LLM은 토큰을 한 번에 다 만들지 않습니다. 직전까지 생성한 모든 토큰을 입력으로 받아 다음 토큰 하나를 예측하고, 그 토큰을 다시 입력에 추가해 다음을 예측하는 방식으로 순서대로 이어갑니다. 매 스텝마다 어휘집 전체 확률 분포를 새로 계산합니다.

• 끝말잇기와 같습니다. 이전에 나온 단어를 받아 다음 단어를 고르고, 그 단어가 또 다음 사람의 입력이 됩니다. 단어를 미리 다 정해두지 않습니다.
• 차이가 있다면, 끝말잇기는 직전 단어 하나에만 의존하지만, LLM은 처음 입력부터 직전 토큰까지 전체 문맥을 참조합니다.
• 그러다보니 응답 앞부분에서 잘못된 방향이 잡히면 뒷부분도 그 방향으로 이어집니다. 출력 형식을 초반에 명확히 유도하는 것이 중요한 이유입니다.

3. Temperature와 topP(Top-P, Nucleus Sampling)

개념:

• Temperature는 확률 분포 자체의 뾰족함을 조절하고, topP는 그 분포에서 후보 토큰 집합을 잘라냅니다.
• 즉, 같은 분포에 다른 방식으로 작용하는 두 파라미터 입니다.

예시 이미지를 보며 공부해보죠

위 이미지 상, topP 0.5에서 후보 토큰 집합이 "0개"가 아니라 1개인 이유는, 1등 토큰(0.70)이 cutoff(0.50)를 단독으로 이미 넘기 때문입니다.

비유:

• topP는 정원이 정해진 엘리베이터입니다. 누적 확률이 P에 닿으면 그 뒤 후보는 들이지 않습니다. 1등 토큰 혼자 cutoff를 단독으로 넘으면 그 토큰만 후보로 남습니다.

실전:

• 분류 task에서는 temperature 0.1 + topP 0.95 조합이 재현성과 꼬리 토큰 차단을 동시에 처리합니다.
• temperature를 기본값(1.0)으로 두면 같은 입력에 다른 라벨이 나와 평가 자체가 noisy해집니다.

4. Confidence value(신뢰도)와 threshold(임계값)

개념:

• 신뢰도(Confidence value)는 AI가 스스로 "내가 고른 이 답이 정답일 거야!"라고 확신하는 정도를 뜻하며, 앞서 우리가 이야기했던 '이 단어가 다음에 올 확률(Probability)'과 아주 밀접한 개념입니다. VLM이 자기 답에 매기는 점수(0.0~1.0)로, 출력 JSON에 직접 포함됩니다.
• 임계값(Confidence threshold)은 어떤 변화가 일어나거나 통과시키기 위해 반드시 넘어야 하는 '최소한의 기준선'을 말하며, 우리가 일상에서 흔히 말하는 시험의 '커트라인'이나, 방에 들어가기 위해 넘어야 하는 '문턱'이라고 생각하면 아주 쉽습니다. 즉, "value가 N 미만이면 자동 라벨로 채택하지 않는다"는 판단을 하게 만들어주는 값으로 우리 코드에서 지정합니다.
• 만일 분석 결과 신뢰도가 임계값 미만일 때, 정석 처리는 재호출이 아니라 사람이 재라벨하는 큐(human re-label queue)로 보내는 것입니다. 왜냐하면 temperature 0.1에서 같은 클립을 다시 호출해도 거의 같은 답이 나와서 사람이 직접 손을 대봐야 하는 단계기 때문입니다.
• 즉, confidence 후처리를 설계할 때 "낮으면 재호출" 대신 "낮으면 사람 큐"로 라우팅 설계를 잡아야 비용 낭비와 오답 반복을 막을 수 있습니다.

5. JSON 출력 3단 방어

왜 JSON 출력을 하는가요?

• LLM은 언어 모델이기 때문에(VLM도!) 출력 형식이 정해져있지 않습니다. 출력 형식을 통일하면 해석하는데 비용도 줄고, 속도도 빨라져요!

개념

• LLM의 JSON 출력을 안정적으로 받으려면 단일 방어선으로는 부족합니다. 각 층의 실패 모드가 다르기 때문입니다.

• 3층 레이어 구조로 방어해줘야 안정적으로 JSON을 받아낼 수 있습니다.

• 해당 레이어 구조는 아래와 같습니다. (1) 시스템 프롬프트에 "JSON only, no prose, no markdown fences" 명시 (2) SDK의 generationConfig.responseMimeType: 'application/json'으로 constrained decoding을 강제

  // Gemini SDK generationConfig에 명시
  const result = await model.generateContent({
    contents: [{ role: 'user', parts: [{ text: userPrompt }] }],
    generationConfig: {
      responseMimeType: 'application/json', // 이렇게!!
      temperature: 0.1,
      topP: 0.95,
    },
  });

(3) 응답에서 필요한 {...} 블록만 추출하는 regex fallback을 두기

실전:

• 이건 LLM호출의 여러 부분에 적용가능한데, 서브에이전트 등 호출시 응답 형식을 정해두면 서브에이전트를 사용하는 에이전트의 효율도 더 올라가는거 같습니다.
• 프롬프트에서 명시해도 JSON으로 안 나오는 경우가 있는데, 이거 때문에 이 팁을 연구한거고 대부분은 (2)항인 responseMimeType이 빠진 경우가 많습니다.
• 프롬프트 한 줄로 해결하려는 시도보다 SDK 설정이 조금 더 확실하게 출력 형식을 정해주는 거 같습니다.

마무리

각 비유는 외우는 도구가 아닙니다. 오개념이 어디서 생기는지를 드러내는 도구입니다. topP 0.5에서 "0개"라고 떠오른다면 날씨 비유로 다시 돌아오고, confidence 미만에서 "재호출"이 먼저 나온다면 학생 시험지 비유로 돌아오면 됩니다. 메커니즘이 잡히면 파라미터 결정에 근거가 생깁니다.

"프론트 잘하고 AI 잘 쓰는 개발자인데, 백엔드 약하면 결국 한계 아니에요?"라는 질문을 자주 받습니다. 최근 SAAS 협업툴의 Postgres 레이어를 맡으면서, 답이 "전문가 되기"가 아니라는 걸 알았습니다. 이 글은 멀티테넌시 전환 한 건과, 초대 role 버그에서 마주친 RLS 무음 실패 한 건을 통해, AI 하네스를 낀 프론트가 어떻게 DB 레벨 판단을 뚫는지 기록한 것입니다.

들어가며, 실전 팀 단위 SAAS개발(토이 프로젝트)

저는 Flutter/React 로 먹고살던 프론트엔드 개발자이고, 지금은 스스로를 AI-native 개발자 혹은 Harness Engineer라고 부릅니다. 최근 작성한 AI관련 블로그 포스팅이 주로 에이전트 시스템 설계에 치중되어 있었다면, 이 글은 같은 논지를 한 개인의 역량 확장에 적용한 버전입니다.

AI의 발달로 인해 러닝 커브는 극단적으로 짧아지고, 개발자도 본인이 잘하는 것만 하거나 개발만 하는 게 아니라 프로덕트를 제대로 이해하고 매니징할 수 있어야 하는 시대가 되었습니다. 그리고 이런 시대의 프론트엔드 출신 개발자는 무조건 이 질문과 조우하게 됩니다.

"AI 잘 쓰는 프론트라도, 백엔드 모르면 결국 반쪽 아니에요?"

결국에는 전 과정을 이해하고 있어야 합니다. 그리고 공부를 하지 않을 변명거리가 너무 궁색해져 버린 현실이기도 합니다. ai는 최고의 선생님이자 보조 개발자니까요. 공부도 마찬가지로 실전 프로젝트가 가장 빨리 늘겠죠? 저는 그래서 팀이 쓸 수 있는 가벼운 관리툴을 저렴하고 손쉬운 Supabase로 만들어보고 있었습니다. 이전에도 백엔드 공부를 독학으로 진행하고 있었지만, 토이 프로젝트이니 만큼 당장 무료플랜이 있느는 Supabase로 차근차근 진행하고 있는데, Supabase에 앱을 올리다 RLS가 막거나, 헬퍼 함수가 순환 참조로 터지거나, 트리거 하나가 흐름을 뒤집는 상황이 생깁니다. 프론트만 봐선 원인이 안 나오는 경우도 많고, 그러므로 우리는 나는 ㅁㅁ하는 사람이야 라고 스스로 선 긋기 보다는 넓게 공부하는게 맞는 것 같습니다.그렇다고 "풀스택 백엔드 전문가"가 되려고 공부하는 건 아닙니다.

전문가가 되기가 아니라, 충분히 판단할 수 있는 개발자가 되기.

제가 목표하는 건 이쪽입니다. AI는 설계 옵션을 나열해줍니다. 이 스키마로 갈지 저 RLS 조합으로 갈지, 어떤 헬퍼를 붙일지. 다만 어느 옵션을 고를지는 결국 사람이 판단해야 합니다. 트레이드오프를 읽고, 프로젝트 요구사항과 맞춰보고, 되돌리기 비용까지 가늠하는 일을 할 수 있어야 하는 시대인거 같습니다.. AI는 재료를 수십 배 빠르게 차려주지만, 선택의 책임을 대신 지지는 않습니다.

영역 확장 = AI 하네스로 판단 반경을 넓히는 것. 이 글은 그 프레임을 SAAS 협업툴에서 실제로 부딪힌 두 사건으로 풀어낸 기록입니다. 하나는 스키마 레벨의 큰 전환, 다른 하나는 "버그 하나가 나를 이틀 잡아먹은" 작은 사건. 둘 다 영역 확장의 다른 얼굴입니다.

토이라고 해서 문제 크기까지 토이는 아니었습니다. "팀 단위로 격리해서 여러 곳이 같이 쓰게 해달라" 같은 요구가 들어오면, 해결해야 할 DB 레벨 문제는 현장과 똑같아지거든요.

에피소드 1 : 단일 팀 전제로 만들었는데 "야 이거 옆 팀도 쓰고싶대"

첫 번째 덩어리는 "단일 팀 전제로 만들어진 SAAS 협업툴을 여러 회사가 각자 격리된 상태로 쓸 수 있게 바꾸는 것"이었습니다. 프론트 언어로 번역하면 "전역 싱글톤 store를 회사별 scope로 나누는 것"에 가깝습니다. 다만 대상이 Postgres입니다.

전환 전에는 모든 RLS가 auth.uid()만 믿고 "본인 것만"이라는 축으로 작성돼 있었고, company_id 컨셉 자체가 없었습니다. 회사 개념을 끼워 넣으려면 스키마·RLS·RPC를 전부 건드려야 합니다. 되돌리기 비용이 큰 작업이었습니다.

한 번에 안 하고 3파일로 쪼갰다

처음엔 SQL 파일 하나를 크게 쓸까 싶었고 AI도 단일 파일 쪽을 선호했지만, 회귀 감지 축에서 보면 나쁜 설계였습니다. 어디서 터졌는지 원인을 끊어 보기 어렵거든요. 3파일로 나눴습니다.

목적은 단순합니다. Supabase SQL Editor에서 하나씩 실행하며 즉시 회귀를 감지하기 위해서. 스키마만 올리고 앱을 돌려보면 어떤 쿼리가 깨지는지 눈에 보이고, RLS를 올리면 또 다른 증상이 나옵니다. 원인을 실행 단위로 분리하는 것이 3파일 분할의 실체입니다. 프론트의 "작은 PR로 쪼개기"와 같은 감각. 다만 대상이 스키마라 실수의 비용이 훨씬 큽니다.

헬퍼 함수에 SECURITY DEFINER를 붙인 이유

회사 범위로 필터링하려면 "지금 로그인한 사용자의 회사 ID"를 꺼내는 함수가 필요합니다.

CREATE OR REPLACE FUNCTION get_my_company_id()
RETURNS UUID
LANGUAGE sql
SECURITY DEFINER     -- 함수 소유자 권한으로 실행
STABLE               -- 같은 쿼리 안에서 결과 캐시
AS $$
  SELECT company_id FROM profiles WHERE id = auth.uid()
$$;

SECURITY INVOKER(기본값)로 두면 RLS가 걸린 profiles를 profiles RLS 안에서 읽어 순환 참조가 납니다. SECURITY DEFINER가 이 순환을 끊는 장치입니다. STABLE은 쿼리 내 캐시용인데, 하나의 FOR ALL 정책이 네 종류 커맨드(SELECT/INSERT/UPDATE/DELETE)에 전부 걸리고 각 정책에서 이 함수가 여러 번 호출되기 때문에, 이 한 줄이 I/O에 제법 영향을 줍니다.

이 지점에서 AI는 함수로 뺄지, 서브쿼리 직삽할지, JWT claim으로 뺄지를 나란히 제시했습니다. 고르는 건 제 몫이었고, 팀 전환 요구 때문에 JWT는 탈락, 직삽은 가독성 문제로 탈락이었습니다.

RLS 정책 텍스트가 곧 권한 명세가 된다

기존 정책을 전부 갈아엎으면서 골격을 통일했습니다. 소속 체크는 USING (company_id = get_my_company_id())로 기본 필터를 박고, 역할 체크는 EXISTS 서브쿼리로 별도 확인. "게스트는 민감 컬럼 못 봄" 같은 규칙을 정책 텍스트에 그대로 박았습니다. 권한을 별도 문서로 만드는 대신, RLS 정책 텍스트 자체가 권한 명세가 되는 구조입니다. 문서와 실코드의 드리프트가 생기지 않습니다. 프론트에서 권한을 Route Guard에 박아온 선호를 RLS에도 그대로 옮긴 셈입니다.

role을 의도적으로 두 군데에 저장했다

"한명의 유저가 여러 팀 개념에 속할 수 있다"는 요구가 추가되면서 user_companies junction 테이블이 생겼습니다. role을 user_companies 하나에만 둘지, 아니면 profiles.role과 이중으로 둘지 선택지가 있었고, 저는 이중 저장 + 단일 진입점을 택했습니다. 프론트 가드가 여러 군데서 profiles.role을 읽는 경로를 바꾸는 건 영향 범위가 넓어서, DB 쪽에서 한 스텝 감당하는 편이 합리적이었습니다. 대신 update_member_role, switch_company 같은 단일 진입점 RPC를 통해서만 역할이 바뀌게 걸었습니다. "프로젝트 구조와 어디서 role을 읽고 있는가"를 아는 사람만 할 수 있는 결정입니다. AI가 대신 짜주지 않습니다.

CASCADE 대신 SET NULL을 쓴 이유

profiles.company_id FK에 ON DELETE CASCADE가 아니라 SET NULL을 썼습니다. CASCADE였다면 "회사 삭제 → 소속 프로필 전부 삭제 → 실질적 유저 삭제"라는 재앙이 납니다. 반면 SET NULL이면 "회사가 없는 유저"라는 어색한 상태가 되지만, 복구 가능합니다. 둘 중 한 방향으로 터질 수밖에 없다면 복구 가능한 쪽으로 터지게 만든다는, fail-closed 원칙 그대로입니다.

초대 테이블엔 아직도 찜찜한 정책 하나가 있다

초대받은 사람은 아직 회사에 소속되지 않은 상태로 토큰을 수락합니다. 수락 시점에 company_id가 없습니다. 그래서 invitations RLS는 두 정책이 병렬로 걸립니다. admin이 자기 회사 초대를 관리하는 쪽은 USING (company_id = get_my_company_id()), 초대받은 사람이 자기 초대를 확인하는 쪽은 USING (true). 후자는 토큰 UUID의 무작위성에 보안을 맡깁니다. "토큰을 알면 조회 가능"으로 풀고 토큰의 추측 불가능성에 기대는 식. 이 프로젝트 RLS에서 가장 불편한 트레이드오프이고, 에피소드 2의 복선이 되는 지점이기도 합니다.

다음날 체크리스트 몇 개가 더 붙었다

정직하게 쓰자면, 이 작업을 끝낸 다음날 몇 가지 항목을 더 넣었습니다. 묻지 않으면 AI도 안 꺼내주는 종류였습니다. "모르는 걸 묻지 않으면 AI도 안 꺼낸다"는 감각이 또 박혔습니다. AI가 완벽한 초안을 주지 않기 때문에 판단자와 체크리스트가 더 중요해진다는 게 결론입니다.

에피소드 2 : 초대 role 버그, 그리고 RLS 무음 실패

에피소드 1이 큰 덩어리 하나였다면, 에피소드 2는 작은 버그 하나가 이틀을 잡아먹은 이야기입니다.

로그인은 되는데 전부 guest로 들어온다

프론트에서는 분명 member / admin 같은 역할을 선택해 초대 메일을 보냈는데, 받는 쪽 계정은 전부 guest로 저장됐습니다. 프론트 payload를 찍어봐도 role은 제대로 실려 있었고, invitations 테이블에 저장된 값도 맞았습니다. 그런데 유저가 토큰을 수락한 뒤 profiles.role을 열어보면 guest.

범인은 트리거의 한 줄

범인은 auth.users에 걸린 트리거였습니다.

CREATE OR REPLACE FUNCTION handle_new_user() RETURNS TRIGGER AS $$
BEGIN
  INSERT INTO profiles (id, email, role)
  VALUES (NEW.id, NEW.email, 'guest');  -- ← 무조건 guest, 하드코딩
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

NEW.raw_user_meta_data->>'role'을 읽지 않고 guest를 박아버립니다. 신규 가입자는 전원 guest로 태어납니다. 초대 role이 아무리 맞게 날아와도 트리거가 한 번 뭉개고 나면 끝.

트리거는 건드리지 않고 RPC로 덮었다

"원인을 알았으면 트리거를 고치면 되지 않나?" 쪽이 자연스러워 보입니다. 그런데 트리거는 안 건드리기로 했습니다. 대신 accept_invitation RPC가 수락 시점에 profiles.role을 덮어쓰게 했습니다.

CREATE FUNCTION accept_invitation(p_token TEXT, p_user_id UUID) ... AS $$
  SELECT * INTO v_inv FROM invitations
  WHERE token = p_token AND accepted_at IS NULL AND expires_at > NOW();

  UPDATE profiles
     SET role = v_inv.role, company_id = v_inv.company_id
   WHERE id = p_user_id;
$$;

왜 트리거를 안 고쳤느냐. 여기서부터는 추정입니다. (a) 트리거는 auth.users에 걸려 있어 건드리면 회원가입 흐름 전체에 영향을 줍니다. 되돌리기 비용이 큽니다. (b) 초대 없이 그냥 signUp한 유저는 실제로 guest가 맞습니다. 즉 하드코딩이 기본값 역할로는 정상 동작합니다. 고쳐야 할 것이 "기본값"이 아니라 "초대 수락 시점의 덮어쓰기 경로 부재"라면, 건드릴 곳은 트리거가 아니라 RPC 쪽이 됩니다.

판단을 한 줄로 적으면 이렇습니다. "고쳐야 할 것을 고치지 않고 우회한다"가 맞을 때가 있다. 영향 범위가 넓고 기본값으로는 정상인 경로는 건드리지 않고, 실제로 틀린 경로에 패치를 얹는 쪽이 되돌리기 비용이 낮습니다.

멀티팀 지원을 넣고 싶어지면서 이 RPC에 user_companies INSERT와 "신규 유저만 profiles.role을 덮어쓴다"는 가드도 더 붙었습니다. 기본 뼈대는 같습니다.

진짜 오래 걸린 이유는 RLS 무음 실패였다

사실 트리거와 RPC 구조를 파악하는 건 한나절이면 됐습니다. 제가 당시 이 버그에 이틀을 쓴 이유는 따로 있습니다.

처음 accept_invitation을 고쳤을 때, RPC는 성공했다고 응답했습니다. 에러 없음. 프론트는 조용히 다음 화면으로 넘어갔고, 재조회해 보니 profiles.role은 여전히 guest였습니다.

원인은 UPDATE가 RLS에 막혀서 0행이 갱신된 것이었습니다. Postgres의 UPDATE는 조건에 맞는 행이 0개여도 에러가 아닙니다. "0 rows updated"는 정상 결과이기 때문입니다. RLS가 행을 필터링해서 0행이 된 경우도 똑같이 "정상 실행"으로 처리됩니다. RPC 관점에서는 "UPDATE 문이 정상 실행됐다"가 사실이고, 프론트 관점에서는 "RPC가 성공 응답을 줬다"가 사실입니다. 양쪽 다 거짓말을 한 게 아닌데, 실제 DB 상태는 안 바뀌었습니다.

프론트 디버거로 payload를 아무리 찍어봐도 원인이 안 나옵니다. 네트워크 응답도 200입니다. 진짜 보스는 프론트도 RPC 내부 로직도 아니고, "RLS에 막혀서 조용히 실패하는 mutation"이었습니다.

사건을 Don't 노트에 박았다

결국 사건이 끝난 뒤 내 Don't 노트에 룰을 하나 승격시켰습니다. "Supabase mutation 후에는 .select() + row count 검증 필수". mutation 결과를 .select()로 받아와 실제로 몇 행이 바뀌었는지 확인하지 않으면, 다음에도 같은 함정에 다시 빠집니다.

RLS가 에러 없이 실패하는 세계에서, .select() 없는 mutation은 어둠 속 발사.

에피소드 2를 복기하면 배움이 세 가지로 압축됩니다. 첫째, 증상의 출처와 원인의 출처가 다를 수 있다. 프론트 버그처럼 보였지만 범인은 DB 트리거였고, 그 다음 범인은 RLS였습니다. 둘째, 고칠 곳을 고치지 않고 우회하는 판단이 맞을 때가 있다. 트리거는 영향 범위가 넓고 기본값으로는 정상이니, 건드릴 곳은 RPC였습니다. 셋째, 침묵하는 실패가 가장 비싸다. RLS 무음 실패처럼 에러를 안 던지는 실패는 체크 코드로 강제 소음화해야만 발견됩니다. 그리고 한 번 당한 건 개인 지식으로 끝내지 않고 내 Don't 노트에 박아두는 게 재발 방지의 실체입니다.

모르는 영역을 조금씩 찍먹해 봅시다

두 에피소드가 보여준 건 성격이 다른 두 종류의 판단입니다. 에피소드 1은 큰 덩어리를 어떻게 쪼갤지의 판단이었고, 에피소드 2는 작은 버그를 어디서 잡을지, 그리고 왜 안 잡히는지의 판단이었습니다. 스키마 설계와 디버깅, 결이 다른 영역이지만 공통점은 하나입니다. AI는 옵션을 나열해줬고, 선택의 책임은 저에게 있었다는 것.

이 두 판단을 하며 느낀 건 분명합니다. 백엔드 전문가가 된 게 아니라, 백엔드를 두려워하지 않게 된 것입니다. 스키마를 쪼개고, 트리거와 RPC 사이에서 어느 쪽을 건드려야 되돌리기 비용이 낮은지 가늠하고, RLS가 에러 없이 실패할 수 있다는 걸 아는 것. 이 정도면 판단 가능한 프론트로서 프로덕트 전 과정에 참여할 수 있습니다. 그게 제가 말하는 풀스택의 교두보입니다.

AI 하네스는 이 과정에서 옵션 제공자 역할을 합니다. 선택과 책임은 엔지니어의 몫입니다.

Claude Code에 Skill을 만들기 시작한 지 7개월. 처음엔 긴 프롬프트를 파일에 저장하는 정도였는데, 어느 순간 몇 개는 매일 쓰고 몇 개는 만들어놓고 쓴 적이 없다는 걸 알아챘습니다.

들어가며 — 7개월 써보고 살아남은 것만 추렸습니다

Claude Code에 Skill(슬래시 커맨드, 서브에이전트)을 만들기 시작한 지 7개월이 됐습니다. 처음엔 그냥 긴 프롬프트를 .claude/commands/ 아래 파일로 저장하는 정도였는데, 시간이 지나면서 몇 개는 거의 매일 쓰고 몇 개는 만들어놓고 한 번도 다시 찾지 않는 게 갈렸습니다.

이번에 8,041개 세션 히스토리를 훑어서 "실제로 살아남은 Skill"만 추려봤습니다. 10개 이상 프로젝트를 가로질러 반복 등장한 패턴이 5가지였습니다. 게임(Unity), 웹앱(React/Supabase), Flutter 앱, 기획·마케팅 문서 작업까지, 전혀 다른 도메인에서도 같은 구조가 계속 나왔습니다.

이 글은 그 5가지 패턴의 실물 코드와, 왜 그게 살아남았는지를 정리한 것입니다. 복붙해 쓸 수 있는 Skill 파일 구조를 함께 뒀으니, Claude Code를 쓰고 있거나 쓸 생각이 있으면 바로 적용할 수 있습니다. (여기서 Skill은 슬래시 커맨드와 서브에이전트를 포함한 포괄적인 개념입니다.)

1. Multi-Critic — 하나의 코드 변경에 비평가 4명 붙이기

가장 오래 살아남은 Skill 1위는 Multi-Critic입니다. 6개 이상의 프로젝트에 그대로 복붙해 쓰고 있는 패턴이고, 기능 구현이 끝난 직후 코드 리뷰 단계에서 매번 호출합니다.

구조는 단순합니다. 하나의 코드 변경에 대해 관점이 서로 다른 4개의 비평 에이전트를 단일 메시지에서 병렬 스폰하고, 결과를 메인 Claude가 종합합니다. 각 에이전트는 자기 영역만 봅니다. 데이터 무결성 / 로직 정합성 / 보안 리스크 / UX 품질을 독립 축으로 분리한 겁니다.

이걸 쓰는 이유는 단일 시점의 리뷰가 놓치는 사각지대를 구조적으로 제거하기 때문입니다. 4명이 각자 관점에서 훑고 나서 2명 이상이 동일 이슈를 지적하면 확정 결함으로, 1명만 지적한 건 참고 사항으로 분류합니다. 오탐(false positive)이 줄고, 과잉 수정도 방지됩니다.

아래는 실제로 쓰는 /critic Skill의 뼈대입니다. 4개 에이전트를 정의하고 메인 Claude가 결과를 종합 분석하도록 지시하는 구조입니다.

# Critic — 4 에이전트 병렬 코드 비평

## 실행 절차

1. 대상 파일 결정: $ARGUMENTS 또는 `git diff --name-only HEAD~1`
2. 변경 파일 10개 이상이면 기능별 그룹핑 → 핵심 그룹만 전달
3. **4개 에이전트를 단일 메시지에서 병렬 스폰**
4. 전체 결과를 메인 Claude가 종합 분석

## 에이전트 A — 데이터 무결성 감사

- 관점: 모든 수치는 증명되기 전까지 거짓이다
- 검증 축: 산술 정합성, 데이터 변환 손실, 캐시-원본 불일치
- 출력: 점수(N/10), 이슈 목록(파일:라인 + 심각도), 판정

## 에이전트 B — 로직 정합성 질문자

- 관점: 아무것도 모른다. 다만 질문할 뿐이다
- 검증 축: 상태 전이 일관성, 워크플로우 모순, 엣지케이스

## 에이전트 C — 보안/리스크 비관주의자

- 관점: 이 시스템은 뚫린다
- 검증 축: 권한 상승 경로, 데이터 노출, 인증 취약점

## 에이전트 D — UX/성능 파괴자

- 관점: '편리한 UI'라는 우상을 부수겠다
- 검증 축: 클릭 경제성, 에러 복구 비용, 접근성

## 종합 분석 규칙 (메인 Claude 수행)

- 2+ 에이전트 공통 지적 → 교차 패턴 테이블로 정리
- 우선순위 매트릭스: 순위 | 항목 | 지적 에이전트 | 영향도 | 수정 난이도

/critic 한 번의 호출로 전체 파이프라인이 자동 실행됩니다. 대상 미지정 시에는 최근 커밋의 변경 파일을 자동으로 감지합니다.

2. Architect → Implement → Review — 설계와 구현을 분리하는 파이프라인

두 번째는 하나의 기능 요청을 설계(Architect) → 구현(Implement) → 검증(Critic) 3단계로 분리하는 패턴입니다. 각 단계에 전문화된 에이전트를 배치하고, 단계 사이에는 사용자 승인 게이트를 둡니다. 이것도 3개 이상 프로젝트에 똑같은 구조로 적용돼 있습니다.

핵심은 관심사 분리입니다. 설계 에이전트는 코드를 쓰지 않고, 구현 에이전트는 설계를 바꾸지 않습니다. 설계 문서가 사용자 명시 승인을 받기 전까진 구현 단계로 넘어가지 못합니다. 이게 의도하지 않은 구현을 구조적으로 막아줍니다. (이 분리는 제가 쓰는 CAOF(Claude Agent Orchestration Framework, 에이전트 오케스트레이션 규약)의 핵심입니다. 왜 이런 분리가 필요한지는 2026-03-27 "Claude Code 에이전트가 폭주할 때" 글에서 다뤘습니다.)

아래는 설계 에이전트 Skill 파일입니다. 코드를 못 쓰게 막고, 사용자 승인 게이트까지 강제하는 구조입니다.

# Architect — 시스템 아키텍트

## 페르소나

10년차 시니어 아키텍트. 코드를 직접 작성하지 않는다 — 설계만 한다.
5원칙: 회의적 질문자, 복잡성 감시자, 실패 시나리오 집착, 단순함 옹호, 코드 금지.

## 절차

1. 기존 코드베이스와 규칙 파일 탐색 (Read/Grep/Glob만 허용)
2. 최소 3개의 공격적 질문 (목표, 범위, 제약, 트레이드오프, 실패 시나리오)
3. 설계 문서 작성:
   - 수정 대상 파일 테이블
   - 핵심 함수/메서드 명세
   - 재사용 가능한 기존 코드
   - 경고사항 및 실패 시나리오
4. 승인 게이트 — 사용자가 "approved" 할 때까지 구현 금지

## 출력

설계 문서를 `planning/YYYY-MM-DD-기능명.md`에 저장
완료 후 안내: `/implement planning/설계문서.md` 로 구현 시작

구현 에이전트는 별도 파일(/implement)로 분리돼 있고, 페르소나는 "8년차 시니어 개발자, 아키텍트의 설계를 충실히 실행한다"입니다. 핵심 제약은 세 가지입니다. 계획에 없는 코드 금지, "일단 고쳐보겠다" 금지(근본 원인 명시 + 선택지 제시 필수), 규칙 파일 위반 금지. 구현이 끝나면 변경 파일 목록과 설계 대비 이탈 사항, 자가점검 결과를 보고서로 남깁니다.

전체 체인은 /architect → (사용자 승인) → /implement 설계문서.md → /critic 순으로 진행됩니다. 각 단계 전환이 명시적 승인을 거치기 때문에, 잘못된 방향으로 15분 달리다 "아 이게 아닌데" 하고 되돌리는 일이 크게 줄었습니다.

3. Cross-Model Parallel Review — AI 모델 4개에 동시에 물어보기

세 번째는 동일한 코드 또는 기획 문서를 서로 다른 AI 모델 4개(Gemini, Claude Opus, Sonnet, Haiku)에 동시에 리뷰시키는 패턴입니다. 기획서 완성 후 구현 착수 전 Planning Review나, 대규모 코드 변경 후 Code Review에서 씁니다.

왜 모델을 나누냐면, 같은 모델이 자기 출력을 리뷰하면 자기 동의 편향(self-agreement bias)이 생겨서 사실상 쓸모없기 때문입니다. 모델마다 blind spot이 달라서, 다른 모델이 그 사각지대를 보완해줍니다. (이 문제를 페르소나 관점에서 어떻게 다뤄야 하는지는 2026-04-08 "AI 에이전트에게 넌 전문가야라고 말하면 진짜 잘할까" 글에서 다뤘습니다.)

각 모델에 역할을 다르게 줍니다. Gemini는 구조적 일관성, Claude Opus는 깊은 논리 분석, Sonnet은 실용성/구현 가능성, Haiku는 직관적 이상 탐지 필터. 아래는 실제 쓰는 /검수 Skill 구조입니다.

# 4모델 병렬 검수

## 모드 A — 기획서 검수 (기본)

1. 대상 문서 감지: specs/ 디렉토리 또는 $ARGUMENTS
2. 4개 에이전트 병렬 실행:
   - Gemini (외부 CLI): 구조적 일관성 검토
   - Claude Opus (서브에이전트): 깊은 논리적 분석
   - Claude Sonnet (서브에이전트): 실용성/구현 가능성 검토
   - Claude Haiku (서브에이전트): 직관적 이상 탐지 필터
3. 4개 보고서 수집 → 교차 분석 → 최종 보고서 저장

## 모드 B — 코드 검수 (`/검수 code`)

1. `git diff`로 변경 사항 수집
2. 동일한 4개 모델로 코드 레벨 리뷰
3. 최종 보고서 저장

## 판정 기준

- 3+ 모델 합의 → 확정적 이슈 (반드시 수정)
- 2 모델 합의 → 검토 필요 이슈
- 1 모델만 지적 → 참고 사항

다수결 기반 신뢰도 판정이 실전에선 꽤 잘 작동합니다. 3개 이상 모델이 같이 지적하면 거의 확정 결함이라 그냥 고치고, 1개만 지적한 건 "참고"로만 보고 넘어갑니다. 이 분류만으로도 "우선순위 어떻게 잡지" 고민이 사라졌습니다.

4. Domain-Specific Automation — 반복 작업을 슬래시 커맨드 한 줄로

네 번째는 프로젝트에서 반복적으로 하는 작업을 하나의 Skill로 캡슐화하는 패턴입니다. 경험상 ROI가 가장 높았던 유형입니다. 5~10단계의 수동 작업이 단일 명령으로 축소됩니다.

대표 사례 두 개만 보여드리겠습니다. 첫 번째는 버전 업데이트 자동화입니다. Flutter 앱을 배포할 때마다 pubspec.yaml 버전 올리고, 관련 설정 파일 3곳 동기화하고, 릴리즈 노트 쓰는 걸 매번 수동으로 했는데, 한 번 묶어놓으니 /version-up 한 줄로 끝납니다.

# Version Up — 원클릭 버전 관리

## 절차

1. 현재 버전 읽기 (pubspec.yaml)
2. 마이너 버전 +1, 빌드 넘버 +1
3. 관련 설정 파일 3곳 동기화 (네이티브 빌드 설정 포함)
4. 클린 빌드 실행
5. 최근 10개 커밋 분석 → 릴리즈 노트 자동 생성
   - 앱스토어용 영문 카피
   - 다국어 4줄 업데이트 노트

두 번째는 다국어 처리 자동화입니다. 하드코딩된 자국어 문자열을 찾아서 번역 키를 만들고, 영문 번역을 붙여서 번역 사전에 등록하고, 원본 코드에서 문자열을 키 호출로 교체하는 5단계 작업입니다. 이것도 /i18n 한 줄로 압축해뒀습니다.

# i18n — 하드코딩 텍스트 다국어 전환

## 절차

1. 대상 파일에서 하드코딩된 자국어 문자열 검출
2. 번역 키 자동 생성 (섹션\_의미 네이밍 규칙)
3. 영문 번역 생성
4. 번역 사전 파일에 양방향 등록
5. 원본 코드에서 문자열을 번역 키 호출로 교체
6. 결과 보고 (변환 건수, 누락 건수)

이런 Automation Skill의 진짜 가치는 실수 방지입니다. 수동으로 할 때 "3곳 중 2곳만 동기화"하거나 "번역 키 등록 누락" 같은 실수가 생기는데, 이걸 명령 하나에 묶어두면 그런 누락이 사라집니다. 프로젝트 맥락을 잠시 잊은 상태에서도 명령만 실행하면 결과가 나와서 컨텍스트 복원 비용이 줄어드는 것도 큰 이점입니다.

5. Hook-Based Auto-Routing — 프롬프트 키워드로 에이전트 자동 배치

다섯 번째는 사용자가 입력하는 자연어 프롬프트의 키워드를 실시간으로 감지해서, 적절한 에이전트 조합을 자동으로 컨텍스트에 주입하는 패턴입니다. 명시적으로 에이전트를 호출하지 않아도 시스템이 키워드를 보고 알아서 올바른 워크플로우로 유도합니다.

아래는 실제 쓰는 Hook 두 개입니다. 첫 번째는 프롬프트 감지 Hook으로, 모든 사용자 입력을 받아 키워드 매칭이 되면 에이전트 조합을 주입합니다.

#!/bin/bash
# UserPromptSubmit Hook — 모든 프롬프트에서 실행

PROMPT="$1"

# 도메인 키워드 감지 → 에이전트 조합 자동 주입
if echo "$PROMPT" | grep -qE '구현해|버그|스크립트'; then
  echo '{"additionalContext": "CAOF 라우팅: Designer + Implementer 배치"}'
  exit 0
fi

# 이미지 생성 키워드 → 사전 승인 요청 주입
if echo "$PROMPT" | grep -qE '이미지.*만들|생성'; then
  echo '{"additionalContext": "이미지 생성 전 반드시 사용자 승인 필요"}'
  exit 0
fi

exit 0  # 매칭 없으면 무시

두 번째는 위험 명령 차단 Hook입니다. 되돌릴 수 없는 명령(force push, hard reset 등)을 자동으로 차단합니다.

#!/bin/bash
# PreToolUse Hook — 모든 Bash 명령 실행 전 검사

COMMAND="$1"

# 되돌릴 수 없는 명령 차단
if echo "$COMMAND" | grep -qE 'git reset --hard|git push --force|git clean -f'; then
  echo "BLOCKED: 되돌릴 수 없는 명령입니다. 사용자에게 확인하세요."
  exit 2
fi

exit 0

settings.json의 hooks 섹션에 등록해두면 모든 세션에서 자동으로 돌아갑니다. 에이전트 호출을 깜빡해도 시스템이 알아서 라우팅하고, 파괴적 명령은 실행 전에 막힙니다. 설정 후엔 가장 편하지만, 처음 세팅에는 한 번 앉아서 Hook 구조를 이해하고 붙여야 한다는 점이 주의할 부분입니다. 앞선 4개 Skill보다 진입장벽이 조금 있어서, 저도 가장 나중에 손댔습니다.

Skill 유형별 비교 요약

Skill은 "프롬프트 저장소"가 아니라 "판단 구조의 라이브러리"입니다

7개월 써보고 얻은 제일 큰 깨달음은 이겁니다. Skill은 단순히 긴 프롬프트를 저장하는 게 아니라, 누가 / 무엇을 / 어떤 기준으로 판단하는가를 구조화한 것이라는 점입니다.

같은 Multi-Critic 구조가 웹앱, 모바일앱, 게임, 데이터 분석 등 전혀 다른 도메인에 재적용되면서 검증 축만 도메인에 맞게 교체됐습니다. Architect-Implement 분리도 마찬가지입니다. 어떤 언어·프레임워크에서도 "설계자는 코드를 쓰지 않는다, 구현자는 설계를 바꾸지 않는다"는 판단 경계는 그대로 유지됩니다. 바뀌는 건 도메인 용어뿐입니다.

결국 Skill 라이브러리는 재사용 가능한 판단 구조의 저장소에 가깝습니다. 이게 제가 찾은 자동화의 3계층 구조입니다.

Layer 3: Hook (항상 실행, 키워드 감지 → 라우팅)
Layer 2: Pipeline (사용자 호출, 다단계 워크플로우)
Layer 1: Single Skill (사용자 호출, 단일 작업)

이 3계층이 결합되면서 "적절한 에이전트가 적절한 타이밍에 적절한 깊이로" 개입하는 체계가 만들어집니다.

어느 것부터 시작하면 좋을까

"5개 다 해보고 싶은데 뭐부터 손대지?"라는 질문을 받으면 저는 이렇게 답합니다. Domain Automation부터 시작하는 게 제일 낫습니다. 난이도가 가장 낮고 ROI가 가장 빠릅니다. 매번 하는 반복 작업 하나를 골라서 .claude/commands/ 아래 슬래시 커맨드 파일 하나만 만들어보면, 다음 주부터 바로 체감됩니다. 버전 업데이트든 번역 키 교체든, 매번 손이 가는 작업이 있다면 그게 1순위 후보입니다.

그 다음은 Multi-Critic이나 Architect-Implement Pipeline을 얹고, Cross-Model Review는 기획서를 자주 쓰게 되는 단계에서 추가하면 됩니다. Hook-Based Auto-Routing은 가장 나중에 손대시는 걸 권합니다. 가치는 가장 크지만 세팅 한 번에 시간이 좀 들어서, 앞의 4개 Skill을 충분히 써보고 "어떤 키워드에서 어떤 에이전트가 자동 배치되면 좋을지" 감이 생겼을 때 붙이는 게 효율이 좋습니다.

프론트엔드 개발자가 MCP로 DB 작업 빠르게 끝낸 후기

왜 Supabase인가

요즘 AI로 프로젝트 시작하는 사람이 진짜 많아지고 있다. 예전엔 백엔드/DB 쪽에서 가장 진입장벽이 낮은 게 Firebase였을지 모르지만, 현재는 Supabase라고 생각한다.

이유는.. 개인적으로는 다음과 같다.

• PostgreSQL 기반인데 SQL 몰라도 Dashboard에서 클릭으로 테이블 만들 수 있고, 엑셀 만 할 줄 알면 배울 수 있다!
• 인증, 스토리지, 실시간 구독이 다 내장되어 있어서 별도 서버 구축이 필요 없고, 심지어 Firebase처럼 소셜로그인도 도와준다.(물론 사업자나 개발자 계정 필요)
• 클라이언트 SDK가 잘 되어 있어서 프론트엔드 개발자가 바로 쓸 수 있다 (이게 가장 큰 장점중 하나인 것 같다)
• 무료 티어가 꽤 넉넉하다 — 프로젝트 2개, DB 500MB, Storage 1GB, 월 5만 API 호출. 사이드 프로젝트나 MVP 단계에서는 과금 걱정 없이 충분하다
• ✨️M✨️C✨️P✨️가 있다 - 그저 빛✨️..

Supabase 프로젝트 생성 ~ 연결까지

1단계: 프로젝트 만들기

1. supabase.com 접속 → Start your project 클릭
2. GitHub 계정으로 로그인(SSO로 해도 된다 그냥 되는거로!)
3. New Project 클릭
4. Organization 선택 (처음이면 자동 생성됨)
5. 프로젝트 이름, DB 비밀번호, Region 설정 → Create new project
6. 2~3분 기다리면 프로젝트가 올라온다

2단계: project_ref 확인

프로젝트가 만들어지면 Dashboard URL이 이런 형태다:

https://supabase.com/dashboard/project/abcdefghijklmnop
                                       ^^^^^^^^^^^^^^^^
                                       이 부분이 project_ref

Settings > General 순서로 눌러서 확인해보자

3단계: 클라이언트 연결 키 확인

Settings > API에 가면 두 가지 키가 있다:

프론트엔드 앱에서는 anon 키 + Project URL만 있으면 바로 연결 가능하다.

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  'https://abcdefghijklmnop.supabase.co',  // Project URL
  'eyJhbGciOiJIUzI1NiIsInR5...'            // anon key
)

여기까지 오면 Supabase 쓸 준비 완료인데, MCP로 연결하면 이거보다 더 빨리 할 수도 있다.

Another 3단계: Claude Code + MCP로 터미널에서 바로 DB 조작하기

근데 이 글의 핵심은 Dashboard를 왔다갔다하는 게 아니라, Claude Code 안에서 DB까지 한 번에 다루는 것이며, AI로 Supabase를 사용하는 대부분이 그것 때문에 이 글을 읽는다고 생각한다. 그걸 가능하게 해주는 게 Supabase MCP 서버이며 너무 간단하다.

Supabase 대시보드의 상단에서 (Connect) 버튼을 눌러서 MCP로 가면 친절하게 Claude와 연동되는 커맨드를 준다.

이대로 진행하면 대부분 Claude가 알아서 해주며, 너무너무 쉽고 빠르다.

하지만 FM(?)대로 연동하는 설명도 갖고왔다. 프로젝트 루트에 .mcp.json 파일 만들고 2단계에서 찾은 프로젝트 레퍼런스를 집어넣는다.

{
  "mcpServers": {
    "supabase": {
      "type": "url",
      "url": "https://mcp.supabase.com/mcp?project_ref=아까_확인한_project_ref"
    }
  }
}

그 다음 Claude Code를 실행하면 처음에 브라우저가 뜨면서 OAuth 인증을 요청하는데, 연동을 진행하면 웹 브라우저로 이동해서 Supabase 계정으로 승인 한 번만 하면 끝이다. 이후로는 Claude Code가 mcp__supabase__* 도구들을 자동으로 인식하며 날 도와준다.

연결 확인은 Claude Code에서 "테이블 목록 보여줘" 라고 하면 list_tables가 작동하면서 현재 DB 상태를 바로 가져온다. 그러면 실질적으로는 Dashboard 열 필요가 거의 없다.

이 상태에서 "이 JSON 파일 읽어서 DB에 넣어줘"라고 하면, Claude가 로컬 파일 읽기부터 SQL 생성(대부분 초보자들이 어려워 하는), 그리고 마지막으로 MCP로 실행까지 한 호흡에 처리 가능하다! 아마 대부분 이렇게 하지 않았을까 싶다.

실전 Supabase 적용, Flutter와 연동한다면?

Flutter 앱에 하드코딩된 로컬 데이터(Dart 상수 + JSON 파일)를 Supabase DB로 옮겨야 했다. 테이블 14개, 시드 데이터 253행, RLS 정책 32개.

기존이라면 이런 흐름이다:

VS Code에서 JSON 열기 → 브라우저에서 Supabase Dashboard 열기
→ 머리로 SQL 변환 → SQL Editor에 붙여넣기 → 에러
→ 다시 VS Code로 돌아와서 JSON 확인 → 반복

Supabase MCP를 쓰면 이렇게 바뀐다:

Claude가 로컬 JSON 읽기 → Claude가 SQL 생성 + 실행 → 에러 시 즉시 수정
→ 전 과정 한 대화에서 완료

"Dashboard 안 열어도 된다"도 좋은 포인트지만, 내가 보기에는 로컬 코드와 DB 사이의 컨텍스트가 끊기지 않는 것이 핵심인 것 같다. Claude가 양쪽을 동시에 보면서 변환하니까 초보적인 실수인 데이터 타입 불일치나 FK 누락이 거의 안 생겼다.

그렇다면 이제 Supabase를 사용하기 위한 기초 지식만 공부해보자. "DB란 대충 데이터를 많이 넣는 창고구나?" 라는 정도만 알고있다면 충분히 할 수 있다.

먼저, 편의점으로 이해하는 DB 기초

PostgreSQL 핵심 개념을 편의점에 빗대서 빠르게 정리한다. 이미 아는 사람은 실전 파트로 넘어가도 된다.

테이블 = 진열대

편의점에 진열대가 여러 개 있다. 음료 진열대, 과자 진열대, 도시락 진열대. DB에서 테이블이 바로 그것이다. 각 진열대(테이블)에는 같은 종류의 상품(데이터)이 정해진 규격으로 놓여 있는 느낌이다.

각 컬럼에는 타입이 정해져 있다. 가격에 "맛있음"이라고 적을 수 없듯이, price 컬럼에는 숫자만 들어간다. TypeScript의 타입 시스템과 같은 느낌이다.

FK(Foreign Key) = 발주서의 납품업체 코드

편의점에서 발주서를 작성할 때, 납품업체를 이름으로 적지 않고 업체 코드로 적는다. "업체 코드 A001의 콜라 30박스" 이런 식이다. 그 업체 코드가 FK(Foreign Key)다.

-- 납품업체 진열대 (부모)
CREATE TABLE suppliers (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL
);

-- 발주서 진열대 (자식) — supplier_id가 FK
CREATE TABLE orders (
  id UUID PRIMARY KEY,
  supplier_id TEXT REFERENCES suppliers(id),  -- "이 발주는 이 업체 거"
  item TEXT,
  quantity INT
);

REFERENCES suppliers(id) = "이 값은 반드시 suppliers 테이블에 있는 업체여야 한다." 존재하지 않는 업체에 발주할 수 없는 것처럼, FK가 데이터의 정합성을 지켜준다.

부모-자식 규칙도 편의점으로:

• 납품업체(부모) 등록 → 그 다음에 발주서(자식) 작성 가능
• 업체를 삭제하려면? 그 업체 발주서(자식)부터 정리해야 한다
• ON DELETE CASCADE = 업체 삭제하면 관련 발주서도 자동 폐기

RLS = 알바생 vs 점장 권한

편의점 POS 시스템에서 알바생은 결제만 할 수 있고, 점장만 매출 보고서를 볼 수 있다. RLS(Row Level Security)가 정확히 이것이다. 같은 데이터인데 누가 접근하느냐에 따라 보이는 게 달라진다.

-- 점장만 매입 단가를 볼 수 있다
CREATE POLICY "점장만 매입가 조회" ON products
  FOR SELECT
  USING (
    (SELECT role FROM profiles WHERE id = auth.uid()) = 'manager'
  );

프론트엔드에서 if (user.role !== 'manager') return [] 하는 거랑 뭐가 다르냐면 — 프론트는 데이터가 이미 브라우저에 왔는데 그냥 안 보여주는 것이다. 개발자 도구 열면 다 보인다. RLS는 DB 단에서 아예 안 준다. 데이터가 네트워크를 타지도 않는다.

뷰(View) = 일일 매출 요약표

점장이 매일 아침 보는 매출 요약표 같은 느낌이다. 여러 진열대(테이블)의 데이터를 한 장으로 모아놓은 것이다. 원본 데이터를 건드리지 않고, 필요한 정보만 뽑아서 보여주는 가상 테이블이다.

CREATE VIEW daily_sales_summary AS
SELECT date, SUM(amount) as total, COUNT(*) as order_count
FROM sales
GROUP BY date;

MCP 핵심 도구 3개

편의점 비유는 여기까지다. 이제부터 실전에서 쓰는 MCP 도구를 알아보자.

주의: 스키마 변경(CREATE/ALTER)은 반드시 apply_migration으로 해야 한다. execute_sql로 하면 마이그레이션 이력에 안 남아서 나중에 추적이 안 된다.

실전: 로컬 데이터를 DB로 옮긴 전체 과정

아까 비유했던 편의점, 이제 진짜로 만들어보자. 편의점 POS 시스템을 예시로 진행한다.

Step 1 — 스키마 설계 + 테이블 생성

아까 편의점에서 진열대 만든다고 했는데, SQL로는 이렇게 생겼다:

-- apply_migration(name: "create_store_tables")
CREATE TABLE product_categories (
  id          TEXT PRIMARY KEY,
  name        TEXT NOT NULL,       -- 음료, 과자, 도시락, 생활용품
  sort_order  INT DEFAULT 0
);

CREATE TABLE products (
  id            TEXT PRIMARY KEY,
  category_id   TEXT REFERENCES product_categories(id),  -- FK: 이 상품은 이 카테고리 소속
  name          TEXT NOT NULL,       -- 콜라, 새우깡, 삼각김밥
  price         INT NOT NULL,
  barcode       TEXT
);

이걸 직접 다 짤 필요는 없다. Claude에게 이렇게 요청하면 된다:

💬 Claude에게 이렇게 말한다:

"내 프로젝트의 docs/supabase-schema.md 파일을 읽어서 테이블을 만들어줘. FK 의존성 순서대로 마이그레이션을 분리해서 실행해."

설계 문서가 없어도 괜찮다. 기존 코드를 보여주면서 요청할 수도 있다:

💬 설계 문서 없이 요청하는 경우:

"src/data/models/ 폴더에 있는 모델 클래스들을 읽어서, 이 구조에 맞는 Supabase 테이블을 만들어줘. FK 관계도 잡아주고."

Claude가 모델 클래스를 분석해서 테이블 구조를 제안하고, 승인하면 apply_migration으로 바로 실행한다.

FK 의존성 순서가 중요하다. 납품업체 등록 안 하고 발주서 쓸 수 없는 것처럼, 부모 테이블부터 만들어야 한다:

product_categories → products → product_details
suppliers → inventory
(카테고리 먼저)    (상품 다음)  (상세 정보는 상품 다음에)

마이그레이션도 역할별로 분리했다:

1. create_store_tables    → 상품/카테고리/납품업체 테이블
2. create_sales_tables    → 매출/매출항목 테이블
3. create_staff_tables    → 직원/근무기록 테이블
4. create_indexes         → 인덱스
5. enable_rls             → RLS 정책

한 방에 다 넣으면 어디서 에러가 터졌는지 찾기 어렵다. 이 분리도 Claude에게 "역할별로 나눠서 마이그레이션 해줘"라고 하면 알아서 해준다.

Step 2 — 데이터 시딩 (INSERT)

여기서 MCP의 진가가 나온다. Claude에게 이렇게 말하면 된다:

💬 Claude에게 이렇게 말한다:

"assets/data/products.json 파일을 읽어서 products 테이블에 넣어줘."

이러면 Claude가 로컬 JSON을 읽고 → SQL INSERT문을 만들고 → execute_sql로 바로 실행한다. 한 흐름이다.

소스 코드에 하드코딩된 데이터도 마찬가지다:

💬 하드코딩된 상수를 옮기는 경우:

"lib/data/product_repository.dart에 하드코딩된 상품 데이터를 읽어서 products 테이블에 INSERT 해줘. category_id FK도 맞춰서."

Claude가 소스 코드의 상수를 분석해서 SQL로 변환하고, FK 관계까지 맞춰서 넣어준다. 이게 수동으로 하면 가장 귀찮은 작업인데, Claude가 양쪽 파일을 동시에 보고 있으니까 타입 변환 실수가 안 생긴다.

데이터 소스 매핑 예시:

하드코딩 (product_repository.dart)    → products 테이블
JSON (assets/data/categories.json)   → product_categories 테이블
JSON (assets/data/suppliers.json)    → suppliers 테이블
JSON (assets/data/inventory.json)    → inventory 테이블

JSON의 중첩 객체도 JSONB로 깔끔하게 들어간다:

INSERT INTO products (id, category_id, name, price, nutrition) VALUES (
  'cola-500',
  'beverage',
  '코카콜라 500ml',
  1800,
  '{"calories":210,"sugar":53,"caffeine":60}'::jsonb
);

대량 데이터는 배치 분할이 필요하다. 이것도 직접 나눌 필요 없이:

💬 대량 데이터 요청:

"assets/data/inventory.json에서 전체 재고 데이터를 inventory 테이블에 넣어줘. 양이 많으면 배치로 나눠서."

데이터가 100개 이상이면 한 번에 넣을 때 SQL 길이 제한에 걸리는데, Claude가 알아서 배치로 나눠서 실행해준다.

각 INSERT 후에는 확인도 한마디면 된다:

💬 "지금까지 넣은 데이터 행 수 확인해줘"

product_categories: 4 ✓
products: 120 ✓
suppliers: 8 ✓
inventory: 350 ✓

Step 3 — RLS 정책

RLS도 Claude에게 맡길 수 있다:

💬 Claude에게 이렇게 말한다:

"상품/카테고리 테이블은 누구나 읽을 수 있게, 매출/근무기록 테이블은 해당 직원 본인 데이터만 접근 가능하게 RLS 설정해줘."

Claude가 테이블 구조를 보고 적절한 패턴을 골라서 적용해준다. 결과적으로 두 패턴이 사용된다:

패턴 A: 공개 읽기 — 상품 정보는 누구나 볼 수 있다:

ALTER TABLE products ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Public read" ON products
  FOR SELECT USING (true);
-- INSERT/UPDATE/DELETE 정책 없음 → 관리자(service_role)만 수정 가능

패턴 B: 본인 데이터만 — 내 근무기록은 나만 볼 수 있다:

ALTER TABLE shift_logs ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Own data only" ON shift_logs
  FOR SELECT USING (auth.uid() = staff_id);
CREATE POLICY "Own insert" ON shift_logs
  FOR INSERT WITH CHECK (auth.uid() = staff_id);

테이블에 staff_id가 없는 경우(자식 테이블)는 부모를 타고 올라간다:

-- sale_items에는 staff_id가 없다. sale_id만 있다.
-- → sales 테이블을 경유해서 소유권 확인
CREATE POLICY "Own sale items" ON sale_items
  FOR SELECT USING (
    EXISTS (
      SELECT 1 FROM sales
      WHERE sales.id = sale_items.sale_id
        AND sales.staff_id = auth.uid()
    )
  );

삽질 포인트: 정책만 만들고 ENABLE ROW LEVEL SECURITY를 빠뜨리면 RLS가 작동 안 한다. list_tables의 rls_enabled 필드로 꼭 확인해야 한다.

삽질 방지 체크리스트

실전에서 걸린 것들을 정리한다:

핵심 정리

1. MCP 도구 3개만 기억하자: apply_migration(스키마), execute_sql(데이터), list_tables(검증)
2. FK 순서: 부모 먼저, 자식 나중. 마이그레이션은 역할별로 분리한다
3. RLS 패턴 2개: 공개 읽기(USING (true)) / 본인 데이터(auth.uid() = user_id)
4. 설계 문서 먼저: CREATE TABLE DDL을 미리 정리해두면 MCP 실행은 복붙 수준이다
5. 레퍼런스 vs 유저 데이터 분리: 인증 없이 바로 쓸 수 있는 것과 로그인 후 쓸 수 있는 것을 나눠두면 단계적 연동이 가능하다

한 줄 감상

솔직히 제일 놀란 건 속도보다 에러가 안 난다는 것 이었다. 기존에는 JSON 보고 SQL 쓰면서 타입 틀리고, FK 빠뜨리고, 작은따옴표 이스케이프 깜빡하고... 그런 자잘한 삽질이 작업 시간의 절반이었는데, Claude가 양쪽 파일을 동시에 보고 있으니까 그런 실수가 구조적으로 안 생긴다.

"AI가 코드를 짜준다" 아니면 "AI가 딸깍해준다"보다 "AI가 두 시스템 사이의 번역기가 된다"가 MCP의 진짜 가치인 것 같다. DB 작업이 어려운 게 SQL 문법이 어려워서가 아니라, 내 코드와 DB 사이를 왔다갔다하면서 컨텍스트를 유지하는 게 어려운 것 같다. 우선 기초만 내 머릿속에 들어가 있다면 이제 나머지는 다 쉬워진다.

앱에 이미 쌓아둔 데이터를 먼저 쓰고, 거기서 답이 안 나올 때만 LLM을 부르는 하이브리드 채팅을 Flutter로 만든 과정입니다. 지금은 혼자 보니까 무료 API(Groq)만 갖고 돌아갑니다.

정적 데이터만 갖고 부족한데 어쩌지?

개인적으로 키우는 도마뱀과 동물들을 위해 반려동물 건강 가이드 앱을 만들고 있습니다. 앱 안에 동물 별 건강 정보를 JSON으로 넣어뒀는데, 이런 질문에는 답을 줄 수 없었습니다.

• "골든리트리버 관절 영양제 뭐가 좋아?"
• "강아지가 구토를 하는데 언제 병원 가야 해?"
• "포메라니안 슬개골 탈구 예방법은?"

정적 위키는 "ㅁㅁ견종의 적정 체중: 5~8kg"이라고만 알려줍니다. 상황에 따른 구체적 질문에는 무력합니다.

그렇다고 LLM에게 모든 걸 맡기면? 앱 안에 검증해둔 데이터가 있는데 그걸 무시하고 LLM의 일반 지식에만 의존하게 됩니다. 할루시네이션 위험은 덤이고요.

원하는 구조는 이겁니다:

사용자 질문
  → 앱 내부 데이터에서 관련 정보 찾기
  → 있으면: 그 데이터를 LLM에게 컨텍스트로 넘겨서 답변 생성
  → 없으면: LLM 일반 지식으로 답변 + "일반 지식 기반" 표시

LLM을 "만능 답변기"로 쓰는 게 아니라, 내 데이터를 읽고 설명해주는 도우미로 쓰는 겁니다.

전체 구조

┌──────────────────────────────────────────┐
│            사용자 질문 입력                  │
└───────────────┬──────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────┐
│  1. 질문 분석 — 무슨 주제에 대한 질문인가?        │
│     키워드 매칭으로 품종(breed) + 카테고리 감지   │
└───────────────┬──────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────┐
│  2. 내부 데이터 검색                         │
│     감지된 품종 + 카테고리로 JSON 데이터 조회     │
│     → 관련 스니펫 추출                       │
└───────────────┬──────────────────────────┘
                │
        ┌───────┴───────┐
        ▼               ▼
   데이터 있음        데이터 없음
        │               │
        ▼               ▼
┌─────────────┐  ┌─────────────┐
│ 시스템 프롬프트 │  │ 시스템 프롬프트 │
│ + 내부 데이터  │  │ (데이터 없이)  │
│ + 질문       │  │ + 질문       │
└──────┬──────┘  └──────┬──────┘
       │                │
       └───────┬────────┘
               ▼
┌──────────────────────────────────────────┐
│  3. LLM API 호출 (Groq, 무료)              │
└───────────────┬──────────────────────────┘
                │
                ▼
┌──────────────────────────────────────────┐
│  4. 앱 코드가 출처/경고를 강제 첨부              │
│     데이터 있었음 → "📎 출처: PetMD..."       │
│     데이터 없었음 → "⚠️ 일반 지식 기반"         │
└──────────────────────────────────────────┘

핵심은 LLM을 항상 부르되, 내부 데이터가 있으면 컨텍스트로 넘긴다는 점입니다. 내부 데이터만으로 답변을 완성하는 게 아니라, LLM이 내부 데이터를 "참고"해서 자연어 답변을 만들도록 하는 구조입니다.

1단계: 무료 LLM 프로바이더 세팅

Groq를 선택한 이유

Groq는 가입만 하면 하루 1,000번 무료로 쓸 수 있고, OpenAI 호환 API라서 나중에 프로바이더를 바꾸고 싶으면 URL과 모델명만 교체하면 됩니다.

Flutter에서 API 호출

// llm_api_repository.dart
Future<String> sendChat(List<Map<String, String>> messages) async {
  final response = await http.post(
    Uri.parse('https://api.groq.com/openai/v1/chat/completions'),
    headers: {
      'Authorization': 'Bearer $apiKey',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'model': 'llama-3.3-70b-versatile',
      'messages': messages,
      'max_tokens': 1024,
      'temperature': 0.3,  // 사실 기반 답변 → 낮게
    }),
  );

  final data = jsonDecode(response.body);
  return data['choices'][0]['message']['content'];
}

OpenAI SDK 없이 http 패키지 하나로 충분합니다. temperature: 0.3은 창의적 답변보다 정확한 답변이 중요한 도메인 특화 앱에 맞는 설정입니다.

2단계: 질문 분석 — 키워드 매칭

LLM에게 "이 질문이 무슨 주제야?"라고 물어볼 수도 있지만, 그러면 API를 두 번 부르게 됩니다. 대신 키워드 매칭으로 로컬에서 처리합니다.

// context_builder.dart

// 카테고리 키워드
static const _categoryKeywords = {
  'joints':      ['관절', '슬개골', '고관절', '디스크', '연골'],
  'skin':        ['피부', '알러지', '탈모', '가려움', '아토피'],
  'diet':        ['사료', '간식', '영양제', '칼슘', '급여량'],
  'vaccination': ['백신', '접종', '예방', '항체', '부스터'],
  // ...
};

Set<String> detectCategories(String question) {
  final matched = <String>{};
  for (final entry in _categoryKeywords.entries) {
    for (final keyword in entry.value) {
      if (question.contains(keyword)) {
        matched.add(entry.key);
        break;
      }
    }
  }
  return matched;
}

"골든리트리버 관절 영양제 뭐가 좋아?" → joints + diet 카테고리 감지. 이 결과로 내부 데이터에서 관절·영양 관련 정보만 꺼냅니다.

후속 질문 대응

"관절 영양제 뭐가 좋아?" 다음에 "그러면 겨울에는?"이라고 물으면 키워드가 없습니다. 이때는 이전 대화 4개를 스캔해서 카테고리를 계승합니다.

if (categories.isEmpty) {
  final history = chatRepo.getRecentMessages(conversationId, limit: 4);
  for (final msg in history) {
    categories = detectCategories(msg.content);
    if (categories.isNotEmpty) break;
  }
}

형태소 분석 없는 단순 키워드 매칭이지만, 도메인이 좁으면 이 정도로 충분합니다.

3단계: 컨텍스트 빌딩 — 핵심

여기가 이 구조의 가치를 결정하는 부분입니다. 같은 LLM이라도 컨텍스트 품질에 따라 답변이 극적으로 달라집니다.

BuildContextResult buildContext(String question, String? breedId) {
  // 1. 품종 + 카테고리 감지
  final breed = detectBreed(question) ?? breedId;
  final categories = detectCategories(question);

  // 2. 내부 데이터에서 관련 스니펫 추출
  String? healthSnippet;
  List<String> sources = [];

  if (breed != null && categories.isNotEmpty) {
    final healthInfo = healthInfoRepo.getHealthInfo(breed);
    healthSnippet = extractSnippet(healthInfo, categories);
    sources = filterSources(categories);  // 카테고리 관련 출처만
  }

  // 3. 시스템 프롬프트 조립
  final systemPrompt = '''
반려동물 건강 전문 AI. 주요 견종별 건강 정보 제공.
${healthSnippet != null ? '\n[앱 데이터]\n$healthSnippet' : ''}

규칙:
- [앱 데이터]가 있으면 참고하되, "앱 데이터에 따르면" 같은 메타 언급 없이 바로 답변.
- [앱 데이터]가 없어도 일반 지식으로 성실히 답변.
- 한국어, 간결체. 출처표기 금지 — 출처는 앱이 자동으로 붙입니다.
''';

  return BuildContextResult(
    messages: [
      {'role': 'system', 'content': systemPrompt},
      ...recentHistory,  // 최근 6개 메시지
      {'role': 'user', 'content': question},
    ],
    hasHealthData: healthSnippet != null,
    sources: sources,
  );
}

포인트 세 가지:

① 내부 데이터를 시스템 프롬프트에 [앱 데이터]로 삽입합니다. LLM은 이걸 "자기가 아는 것"처럼 자연스럽게 답변에 녹여냅니다.

② hasHealthData 플래그를 반환합니다. 이 값으로 나중에 "출처 있음/없음"을 앱 코드가 결정합니다. LLM에게 판단을 맡기지 않습니다.

③ 출처도 카테고리별로 필터링합니다. 관절 질문에 백신 관련 출처를 보여주면 신뢰가 떨어집니다.

4단계: 출처와 신뢰도 — LLM에게 맡기지 않는 것들

이 구조에서 가장 중요한 설계 결정입니다.

처음에는 프롬프트에 "답변 끝에 출처를 달아줘"라고 시켰습니다. 결과:

LLM은 답변 생성에만 집중시키고, 메타데이터는 앱 코드가 처리합니다:

// chat_providers.dart — AI 응답 수신 후
String finalContent = aiResponse;

if (contextResult.hasHealthData) {
  final sourceText = contextResult.sources
      .map((s) => '- $s')
      .join('\n');
  finalContent += '\n\n📎 출처:\n$sourceText';
} else {
  finalContent += '\n\n⚠️ 일반 지식 기반 답변입니다';
}

이렇게 하면 출처 표시 일관성이 100%가 됩니다. LLM 재량에 맡겼을 때는 40% 정도였습니다.

사용자가 보는 화면:

• 내부 데이터 기반 답변 → 답변 끝에 📎 출처: PetMD, AKC Canine Health
• 일반 지식 답변 → 답변 끝에 ⚠️ 일반 지식 기반 답변입니다

사용자는 이 답변이 검증된 데이터에 근거한 건지, LLM의 일반 지식인지 바로 알 수 있습니다.

5단계: 대화에서 지식 쌓기

여기까지면 "잘 만든 챗봇"입니다. 한 단계 더 간 부분은 대화에서 재사용 가능한 지식을 자동으로 추출·축적하는 시스템입니다.

Day 1: "강아지 피부에 빨간 반점이 생겼어" → AI 답변 → 지식으로 저장 (confidence: 0.5)
Day 3: "알러지인지 어떻게 구분해?"       → 기존 지식을 컨텍스트에 추가 → 더 정확한 답변
Day 10: 비슷한 피부 질문               → 캐시 히트! API 호출 없이 즉시 응답

반복 질문에 대한 답변이 점점 좋아지고, 일정 수준 이상이면 API를 부르지 않아 한도도 아낍니다.

오답이 영원히 반복되면?

이 시스템의 가장 큰 위험입니다. 틀린 답변이 캐시되면 계속 틀린 답을 줍니다. 차단 장치 세 가지:

1. confidence 최대 0.9 — 자동으로 1.0에 도달 불가 (사람 검증 없이는)
2. "부정확" 버튼 — 사용자가 누르면 confidence -0.3
3. 자동 삭제 — confidence ≤ 0.1이면 엔트리 삭제 (신고 3회면 거의 확실히 삭제)

토큰 예산 — 무료 티어에서 살아남기

Groq 무료 티어는 하루 1,000 요청, 500K 토큰입니다. 한 번 요청에 얼마나 쓰는지 관리해야 합니다.

Groq의 Llama 3.3 70B는 128K 컨텍스트이므로 매우 여유 있습니다. 내부 데이터 스니펫을 카테고리별로 필터링하는 이유가 여기에도 있습니다 — 전체 데이터를 때려넣으면 토큰 낭비입니다.

이 구조를 다른 앱에 쓰려면

도메인에 종속된 부분과 아닌 부분을 분리하면 재사용할 수 있습니다.

그대로 쓸 수 있는 것:

• LLM API 호출 모듈 (OpenAI 호환이면 URL만 교체)
• 지식 축적/캐시 시스템 (confidence + 피드백)
• 출처 강제 첨부 패턴 (hasHealthData 분기)
• 대화 저장/한도 관리

도메인별로 바꿔야 하는 것:

• 카테고리 키워드 목록
• 엔티티 키워드 (여기서는 견종)
• 시스템 프롬프트
• 내부 데이터 구조와 스니펫 빌더
• 출처 URL 매핑

인터페이스 하나로 정리하면:

abstract class ChatConfig {
  String get systemPrompt;
  Map<String, List<String>> get categoryKeywords;
  Map<String, List<String>> get entityKeywords;
  Future<({String snippet, List<String> sources})> buildDataSnippet(
    String entityId, Set<String> categories);
}

이 인터페이스만 구현하면 요리 레시피 앱이든, 건강 관리 앱이든, 법률 상담 앱이든 같은 구조로 돌아갑니다.

결과물 미리보기

• 조금 더 다듬어야 하겠지만, 컨텍스트도 잘 이어지고 원하는대로 잘 동작하고 있습니다.
• 예시 질문은 레오파드 게코로 했습니다. 귀엽거든요.

정리

1. LLM을 만능으로 쓰지 않습니다. 내부 데이터가 있으면 컨텍스트로 넘기고, LLM은 그걸 자연어로 풀어주는 역할만 합니다.
2. 메타데이터는 앱 코드가 결정합니다. 출처 표기, 신뢰도 표시를 LLM에게 맡기면 일관성이 깨집니다. 코드로 강제하면 100%입니다.
3. 무료 API로 충분합니다. Groq 무료 티어 + 키워드 기반 컨텍스트 빌딩 + 지식 캐시로, 비용 없이 쓸 만한 AI 채팅을 앱에 넣을 수 있습니다. (나중에 유저가 많아지면 갈아끼워요!)

저는 페르소나 설정의 신봉자였습니다. 모든 AI 에이전트에 정체성을 부여하고, 그게 당연히 성능을 높인다고 믿었습니다. 그런데 논문을 파보니, 이 믿음이 반만 맞았습니다.

저는 이렇게 쓰고 있었습니다

저는 Claude Code 위에 CAOF(Claude Agent Orchestration Framework)라는 에이전트 오케스트레이션 시스템을 운영하고 있습니다. 게임 기획 에이전트, Unity 구현 에이전트, 웹앱 개발 에이전트 등 역할별로 전문 에이전트를 나누고, 각각에 페르소나를 부여합니다.

예를 들면 이런 식입니다:

• game-designer: "넌 비판적 기획자야. 기획 의도를 검증하고, 스코프가 현실적인지 따져"
• unity-game-coder: "넌 Unity C# 전문가야. 최소 변경 원칙을 따르고, New Input System만 써"
• content-adapter: "넌 콘텐츠 편집자야. 원본의 톤을 살리면서 플랫폼에 맞게 변환해"

이게 잘 작동한다고 느꼈고, 페르소나가 핵심이라고 생각했습니다. 그런데 "왜 잘 되는 거지?"를 논문으로 파보니, 제가 생각한 이유와 실제 이유가 달랐습니다.

"페르소나 효과 있냐?"는 잘못된 질문이었습니다

"AI에게 페르소나를 주면 효과가 있냐?"는 "약을 먹으면 낫냐?"와 같은 질문입니다. 어떤 약을, 어떤 증상에 쓰느냐에 따라 답이 달라지듯, 페르소나도 태스크에 따라 정반대로 작용합니다.

USC 연구팀의 PRISM 논문(2026.03)이 이걸 명확하게 보여줬습니다.

이유는 직관적입니다. "넌 전문가야"라고 말해서 전문 지식이 생기는 건 아닙니다. 페르소나는 모델의 출력 분포를 특정 방향으로 밀어버리는데, 이게 스타일에는 도움이 되지만 팩트 검색에는 오히려 노이즈가 됩니다.

논문들이 말하는 5가지 원칙

아래 내용은 제 주장이 아닙니다. PRISM, Jekyll & Hyde, RRP 등 관련 논문과 실전 사례를 종합한 결과입니다.

1. 스타일이 중요한 곳에만 페르소나를 씁니다

페르소나가 효과적인 영역은 정렬(alignment) 태스크입니다. 톤 유지, 규칙 준수, 역할극, 글쓰기 — 이런 곳에서 페르소나는 확실히 작동합니다.

반대로, 코딩 정확도나 수학 문제 풀이에는 페르소나 대신 구체적인 규칙과 예시를 주는 게 낫습니다.

2. 모호한 페르소나는 효과가 없습니다

❌ "넌 전문 개발자야."
✅ "넌 React 테스트 엔지니어로, 소스코드는 절대 수정하지 않고, 아래 예시를 따른다."

Agentic Thinking의 가이드에서 정리한 좋은 페르소나의 조건은 두 가지입니다:

• Expertise: 에이전트가 깊이 아는 것 — 구체적이고 범위가 제한된 지식
• Process: 출력을 일관되게 만드는 단계별 방법론

3. 페르소나 + 규칙 시스템을 결합해야 합니다

Rule-based Role Prompting(RRP) 논문이 이걸 증명했습니다. 단독 페르소나보다 character-card + scene-contract + function calling 강제를 조합했을 때 성능이 가장 높았습니다(대화 에이전트 점수 0.571 vs 제로샷 0.519).

ESLint 창시자 Nicholas Zakas도 비슷한 결론에 도달했습니다. AI를 단일 어시스턴트가 아니라 전문가 팀으로 운영하되, 각 역할에 구체적인 규칙과 프로세스를 묶었을 때 생산성이 올라갔다고 합니다.

4. LLM이 만든 페르소나가 수작업보다 안정적입니다

Jekyll & Hyde 논문(2024.08)과 PromptHub 테스트에서 공통으로 확인된 결과입니다. LLM에게 "이 태스크에 최적화된 페르소나를 만들어줘"라고 요청한 것이, 사람이 직접 설계한 것보다 더 안정적이었습니다.

직접 페르소나를 깎아 만들 시간에, LLM에게 초안을 뽑게 하고 그걸 다듬는 게 효율적입니다.

5. 코딩 에이전트는 정체성 선언보다 규칙에 무게를 둡니다

RRP 논문의 결론은 명확합니다 — 페르소나 단독은 별로지만, 페르소나 + 규칙 시스템의 조합이 최고 성능이었습니다. 그리고 코딩처럼 사전학습 지식에 의존하는 태스크에서는 그 비율이 규칙 쪽으로 기울어야 합니다.

이걸 알고 나서 제 에이전트 파일을 다시 보니, 흥미로운 패턴이 보였습니다:

• 기획 에이전트 (game-designer): 정체성 선언("넌 비판적 기획자야")의 비중이 큼 → 톤, 관점 유지에 기여
• 구현 에이전트 (unity-game-coder): 정체성 선언은 짧고, 대부분이 "New Input System만 써라", "최소 변경 원칙", "isCompleting 가드 필수" 같은 구체적 규칙

페르소나를 빼라는 게 아닙니다. 논문이 말하는 건, 코딩 에이전트에서는 "넌 전문가야"보다 "이 규칙을 따라"가 성능에 더 크게 기여한다는 것입니다. 저는 무의식적으로 이 비율을 맞추고 있었는데, 논문을 읽고 나서야 그 이유를 이해했습니다.

한 장으로 정리

페르소나가 효과적인 곳     페르소나가 위험한 곳
━━━━━━━━━━━━━━━━━━    ━━━━━━━━━━━━━━━━━
톤/스타일 유지            코딩 정확도
규칙 준수                수학/논리 추론
역할극/서사 생성          팩트 기반 QA
공감적 대화              일반 지식 검색

저는 여전히 모든 에이전트에 페르소나를 부여합니다. 다만 논문을 읽기 전에는 "페르소나가 효과적이다"라고만 생각했고, 읽은 후에는 "왜 효과적인 곳과 아닌 곳이 나뉘는지"를 이해하게 되었습니다.

"넌 전문가야"는 양날의 검입니다. 중요한 건 페르소나를 쓰냐 마냐가 아니라, 어떤 태스크에서 페르소나와 규칙의 비율을 어떻게 잡느냐입니다.

참고 논문/자료

• PRISM: Expert Personas Improve LLM Alignment but Damage Accuracy — USC, 2026.03
• Persona is a Double-edged Sword (Jekyll & Hyde) — 2024.08
• Rule-based Role Prompting (RRP) — 2025.09
• EmotionPrompt: LLMs Understand Emotional Stimuli — 2023.07
• Nicholas Zakas: Persona-based AI-Assisted Programming
• Agentic Thinking: Agent Personas That Actually Work

#AI실전 #프롬프트엔지니어링 #에이전트 #개발생산성 #ClaudeCode

같은 모델이 자기 코드를 리뷰하면 결함을 못 잡는다. 다른 모델로 리뷰하면 검출률이 올라간다.

패턴

문제: 자기 동의 편향 (Self-Agreement Bias)

Claude Opus가 코드 작성 → Claude Opus가 리뷰
→ "네, 이 코드는 잘 작성되었습니다" (자기가 쓴 거니까)

사람도 자기 글을 교정할 때 오타를 못 보는 것과 같은 원리. AI는 이 편향이 더 심하다 — 같은 모델은 같은 사고 패턴을 공유하므로, 같은 맹점을 가진다.

해결: 4모델 병렬 교차 리뷰

작업 완료 → Gemini가 리뷰 (구조적 관점)
          → Claude Opus가 리뷰 (깊은 논리 분석)
          → Claude Sonnet이 리뷰 (실용적 관점)
          → Claude Haiku가 리뷰 (직관적 필터)
          → 4개 결과 병합

모델마다 역할이 다르다: | 모델 | 역할 | 강점 | |------|------|------| | Gemini (API) | 구조적 일관성 | 수치 불일치, 네이밍 비일관성, 패턴 위반 | | Claude Opus | 깊은 논리 분석 | 엣지케이스, 비즈니스 로직, 설계 판단 | | Claude Sonnet | 실용적 관점 | 과잉 설계, 단순화, 구현 현실성 | | Claude Haiku | 직관적 필터 | "이거 정말 필요해?", 최대 위험 하나 |

실전 구현

ideaBank의 /검수 시스템 (4모델)

기획 검수:  Gemini + Opus + Sonnet + Haiku → 4개 병렬 실행 → 종합 보고서
코드 검수:  Gemini + Opus + Sonnet + Haiku → 4개 병렬 실행 → 종합 보고서

보고서 5종 생성:

1. *-gemini.md — 구조적 일관성 발견
2. *-claude-opus.md — 깊은 논리 분석 발견
3. *-claude-sonnet.md — 실용성 평가
4. *-claude-haiku.md — 직관적 판단
5. *-final.md — 종합 (다수 공통 → 2모델 공통 → 단독 순으로 정리)

i-spider의 review 스킬

• Architect(Opus)가 쓴 계획을 Implement(Sonnet)가 구현
• Review 스킬이 "계획 vs 실제" 비교 — 다른 세션이므로 맥락이 분리됨
• 추가로 외부 모델(Codex 등)로 보완 리뷰 가능

결과

교차 리뷰에서 실제로 잡힌 것들

• Gemini가 잡고 Claude가 놓친 것: 스펙 문서 간 수치 불일치, 네이밍 비일관성
• Claude가 잡고 Gemini가 놓친 것: 런타임 엣지케이스, 비동기 타이밍 이슈
• 둘 다 잡은 것: 누락된 에러 처리, 미사용 코드 (이건 높은 신뢰도)
• Haiku의 직관: "이 시스템 자체가 불필요하다" 수준의 과감한 판단 (2026-03-20 개선안 검토에서 B, C를 깔끔하게 No 판정)

신뢰도 기준 (4모델 체계)

• 3~4개 모델 공통 지적: 거의 확실한 결함 → 반드시 수정
• 2개 모델 공통 지적: 높은 신뢰도 → 수정 권장
• 1개 모델 단독 지적: 오탐 가능성 → 확인 후 판단

비용 대비 효과

• Gemini: 무료 한도 내 (Gemini Flash API)
• Claude Opus/Sonnet/Haiku: 구독 내 포함
• 추가 비용 거의 없이 4개 관점 확보

교훈

1. 3개 이상 모델이 지적한 이슈는 거의 확실한 결함이다 — 최우선 처리
2. 1개 모델만 지적한 이슈는 검토가 필요하다 — 오탐(false positive)일 수 있음
3. 리뷰 결과는 파일로 저장한다 — 대화 컨텍스트는 날아가지만 파일은 남는다
4. 자동화할수록 좋다 — /검수처럼 한 명령으로 병렬 리뷰가 돌아가야 실제로 쓰게 된다

도입 최소 단위

# 1단계: git diff를 다른 모델에게 보내기
git diff | ./tools/code-review.sh output.md  # Gemini 리뷰

# 2단계: 결과를 현재 세션에서 검토
# Claude가 Gemini 리뷰 결과를 읽고 동의/반박

# 3단계: /검수 커맨드로 원클릭 자동화

AI 코딩 에이전트로 앱을 만들면서 겪은 실패 패턴 5가지. 코드를 대신 짜주는 건 해결됐지만, "어떻게 시키느냐"는 여전히 사람의 몫이었습니다.

배경

AI 코딩 에이전트(Claude Code)로 사이드 프로젝트를 진행하고 있습니다. Flutter 앱과 React 웹앱을 동시에 개발하는데, UI 구현부터 상태 관리, API 연동까지 대부분의 코드를 AI가 작성합니다.

개발 속도는 확실히 빨라졌습니다. 하루 만에 로그인 화면, 리스트 UI, 상세 페이지, 상태 관리까지 돌아가는 프로토타입이 나왔으니까요.

문제는 속도가 아니라 방향이었습니다. 빠르게 잘못된 곳으로 갈 수 있다는 걸, 하루 세션에서 여러 번 확인했습니다.

함정 1: "개선해줘" → 화면 전체 재작성

무슨 일이 있었나

나: "이 주문 목록 화면 좀 개선해줘."
AI: 네, 전체 구조를 개선하겠습니다.
    - StatefulWidget → Riverpod AsyncNotifier로 전환
    - ListView → CustomScrollView + SliverList로 교체
    - 에러/로딩/빈 상태를 별도 위젯으로 분리
    ...

이 한 마디에 AI가 화면 하나를 통째로 재작성했습니다. 상태 관리 방식이 바뀌었고, 스크롤 구조가 달라졌으며, 기존에 맞춰둔 애니메이션 타이밍이 전부 깨졌습니다.

결과? 롤백하는 게 더 빠를 정도의 나쁜 수정.

왜 이렇게 됐나

AI는 "개선"이라는 단어를 "더 좋게 다시 짜기"로 해석했습니다. 하지만 기존 코드에는 수십 번의 디바이스 테스트와 미세 조정이 녹아있었어요.

// AI가 "매직 넘버"라고 판단하고 삭제한 코드
const kCardHeight = 72.0;    // 72px — 터치 타겟 최소 48px + 패딩. 갤럭시 폴드에서 검증
const kScrollThreshold = 0.85; // 85% — 0.9로 하면 느린 네트워크에서 로딩 스피너가 안 보임
const kAnimDuration = 180;    // 180ms — 200ms는 체감상 느림, 150ms는 끊겨 보임 (Galaxy A13 기준)

// AI가 "깔끔하게" 바꾼 코드
const kCardHeight = 56.0;      // Material 기본값
const kScrollThreshold = 0.9;  // 일반적인 값
const kAnimDuration = 300;     // Material 기본 애니메이션

카드 높이, 스크롤 임계값, 애니메이션 시간 — 이것들은 여러 기기에서 테스트하고 나서 조정한 값이지 임의의 숫자가 아니었습니다.

교훈

"개선" 요청 전에, 진짜 문제가 뭔지 먼저 파악하세요.

실제로 급했던 건 목록 하단의 페이지네이션 버그였습니다. 화면 전체 재설계가 아니라 스크롤 리스너 조건문 하나 수정이면 될 일이었어요.

// 이렇게 시켰어야 했다
나: "주문 목록에서 마지막 페이지 로드가 안 돼.
    _onScroll 메서드의 페이지네이션 로직만 봐줘.
    다른 코드는 건드리지 마."

AI에게 "개선해줘"라고 하면, AI는 자기가 할 수 있는 최대치를 합니다. 변경 범위를 먼저 정해주지 않으면, 범위는 끝없이 커집니다.

함정 2: 코드만 보고 에셋/설정은 안 봄

무슨 일이 있었나

앱에서 이미지가 간헐적으로 깨져서 나오는 문제가 있었습니다. AI는 이미지 로딩 코드를 분석하고 캐시 로직을 수정했습니다.

나: "프로필 이미지가 가끔 깨져서 나와."
AI: CachedNetworkImage의 캐시 정책을 분석해보겠습니다.
    → cacheManager의 maxAge가 너무 짧은 것이 원인입니다. 7일 → 30일로 수정했습니다.
나: "아직 깨지는데?"
AI: 추가로 placeholder와 errorWidget의 처리를 개선하겠습니다.
나: "... 여전히 깨지는데?"

캐시 코드를 3번이나 수정했지만 핵심 문제는 그대로였습니다.

왜 이렇게 됐나

원인은 코드가 아니라 pubspec.yaml과 이미지 에셋이었습니다. flutter_image_compress 패키지 버전이 올라가면서 HEIC 포맷 처리가 바뀌었고, 특정 안드로이드 기기에서 변환이 실패하고 있었어요.

$ git diff --stat
 pubspec.lock                    | 12 +++---  # ← AI가 무시한 변경
 lib/widgets/profile_image.dart  | 25 ++++++---
 lib/services/image_cache.dart   | 18 ++----

git diff에 pubspec.lock 변경이 찍혀 있었는데, AI는 .dart 파일에만 집중하느라 패키지 버전 변경을 무시했습니다.

교훈

"코드가 맞는데 동작이 이상하다" → 에셋·설정·패키지부터 확인 → 코드는 그 다음.

AI 코딩 에이전트는 본능적으로 코드를 먼저 봅니다. 하지만 앱 개발에서 "특정 기기에서만 이상하다"의 원인은 코드가 아니라 패키지 버전, 에셋 포맷, 빌드 설정인 경우가 많습니다. git diff에 pubspec.lock, build.gradle, Podfile.lock 변경이 있으면 반드시 확인하세요.

함정 3: AI가 만든 설계안을 그대로 믿을 뻔함

무슨 일이 있었나

앱이 커지면서 상태 관리가 복잡해졌고, AI에게 아키텍처 개선 보고서를 생성시켰습니다. 보고서가 꽤 그럴듯했어요:

## 아키텍처 개선 제안 (AI 생성)

1. Clean Architecture 도입 (Domain/Data/Presentation 3레이어 분리)
2. 모든 API 호출을 UseCase 클래스로 래핑
3. Repository 패턴 + DataSource 추상화
4. DI 컨테이너: get_it + injectable
5. 에러 처리: Either<Failure, Success> (dartz 패키지)
6. 라우팅: go_router + ShellRoute 기반 네비게이션 재설계

화면 8개, 개발자 1명인 사이드 프로젝트에 UseCase 클래스 20개, Repository 인터페이스 10개라니. 이건 대규모 엔터프라이즈 앱이지, 내 프로젝트가 아닙니다.

왜 이렇게 됐나

AI는 "아키텍처 개선"이라는 키워드만 보고 업계 베스트 프랙티스를 제안했습니다. 앱 규모, 팀 크기, 출시 일정 같은 맥락이 프롬프트에 충분히 들어가지 않았어요.

다행히 "비판적으로 검수해봐"라고 다른 모델에게 요청한 덕분에, 이런 피드백이 돌아왔습니다:

검수 결과 (다른 모델):
❌ Clean Architecture 3레이어 — 화면 8개에 파일 수만 3배. 유지보수 비용 > 이득
❌ UseCase 클래스 — API 호출을 그대로 전달하는 패스스루 클래스가 대부분일 것
❌ dartz Either — 러닝커브 대비 효과 미미. try-catch + sealed class로 충분
⚠️ Repository 패턴 — 서버가 1개인데 DataSource 추상화는 과잉. 직접 접근이 더 간단
✅ go_router — 네비게이션 개선은 유효. 단, ShellRoute 전면 재설계는 점진적으로

요청하지 않았으면 그대로 설계에 반영했을 겁니다.

교훈

AI가 생성한 설계안은 "초안"이지 "결정"이 아닙니다.

AI는 "기술적으로 가능한 최선"을 제안하지, "이 규모와 이 상황에서 현실적인 최선"을 제안하지 않습니다. "구현 가능한가"뿐 아니라 "우리 앱 규모에 맞는가"를 반드시 검증하세요. 이 문제를 구조적으로 해결한 방법은 다음 글에서 다룹니다.

함정 4: 문제를 새 패키지로 해결하려는 본능

무슨 일이 있었나

앱의 메인 리스트 화면이 버벅거린다는 피드백이 들어왔습니다.

나: "메인 피드가 스크롤할 때 버벅여. 개선 방안 제안해줘."
AI: 다음 3가지를 제안합니다:
    1. flutter_staggered_animations로 지연 렌더링 도입
    2. 상태 관리를 Provider → Riverpod으로 마이그레이션
    3. 이미지 로딩을 CachedNetworkImage → fast_cached_network_image로 교체

전부 새로운 패키지 도입이나 대규모 마이그레이션이었습니다.

왜 이렇게 됐나

기존 코드를 살펴보니 이미 문제가 보였습니다:

// 문제 1: ListView.builder를 안 쓰고 전체 리스트를 한 번에 빌드
Widget build(BuildContext context) {
  return ListView(
    children: items.map((item) => FeedCard(item: item)).toList(),
    // 아이템 200개면 → 위젯 200개를 한 번에 생성
  );
}

// 문제 2: 매 빌드마다 이미지 URL 파싱
class FeedCard extends StatelessWidget {
  Widget build(BuildContext context) {
    final url = Uri.parse(item.imageUrl);  // 스크롤할 때마다 파싱
    final resized = url.replace(queryParameters: {'w': '300'});  // 매번 새 객체
    return CachedNetworkImage(imageUrl: resized.toString());
  }
}

// 문제 3: setState로 전체 화면 리빌드
void _onLike(String itemId) {
  setState(() {
    items = items.map((i) => i.id == itemId ? i.copyWith(liked: true) : i).toList();
    // 좋아요 1개 누르면 → 아이템 200개 전부 리빌드
  });
}

실제 해결: 새 패키지 0개.

• ListView → ListView.builder (화면에 보이는 것만 빌드)
• 이미지 URL 파싱을 모델 생성 시 한 번만 수행
• 좋아요를 개별 아이템의 ValueNotifier로 분리 → 해당 카드만 리빌드

jank이 완전히 사라졌습니다.

교훈

"화면이 버벅인다" ≠ "새 패키지가 필요하다"

앱 개발자(그리고 AI)의 본능은 "더 좋은 패키지로 교체"이지만, 실제 필요한 건 기존 코드의 위젯 빌드 최적화인 경우가 많습니다.

기존 코드에 이미 답이 있는데 새로 도입하려는 건, 사람도 AI도 똑같이 빠지는 함정입니다.

잘 된 것: 병렬 에이전트 대량 투입

실패 사례만 있는 건 아닙니다.

6개의 독립적인 화면을 구현할 때, AI 에이전트 6개를 동시에 투입했습니다.

에이전트 A → 주문 상세 화면   (새 파일: order_detail_screen.dart)
에이전트 B → 결제 화면        (새 파일: payment_screen.dart)
에이전트 C → 리뷰 작성 화면   (새 파일: review_write_screen.dart)
에이전트 D → 알림 목록 화면   (새 파일: notification_list_screen.dart)
에이전트 E → 설정 화면        (새 파일: settings_screen.dart)
에이전트 F → 프로필 편집 화면 (새 파일: profile_edit_screen.dart)

규칙: "각자 새 파일만 생성. 기존 파일 수정 금지. 공통 위젯과 모델만 import."

결과: ~5분 만에 전부 완료. 파일 충돌 0건.

성공 요인은 단순했습니다:

• 각 에이전트에 "이 파일만 생성, 기존 파일 수정 금지" 규칙
• 기존 공통 위젯과 모델만 import (에이전트 간 의존성 차단)
• 화면 스펙 문서를 에이전트에 직접 전달 (자율 구현)

AI에게 자율성을 줄 때, 경계를 명확히 정해주면 병렬 처리의 위력이 폭발합니다.

정리: AI 코딩 에이전트 활용 체크리스트

매 작업 전에 확인하는 목록입니다:

다음 글

함정 3에서 "AI 설계안을 검수해야 한다"고 했는데, 구체적으로 어떻게 검수할까요?

같은 모델에게 "이거 괜찮아?"라고 물으면, "네, 괜찮습니다"라고 답합니다. 자기가 만든 걸 자기가 리뷰하면 결함을 못 잡아요.

다음 글에서는 이 "자기 동의 편향"을 깨는 방법 — 교차 모델 리뷰에 대해 작성해 보겠습니다.

Claude Code로 서브에이전트를 활용한 개발 워크플로우를 운영하고 있다. 설계자(Architect)가 분석하고, 구현자(Implementer)가 코드를 쓰고, 검증자(Reviewer)가 리뷰하는 구조다. CAOF(Claude Agent Orchestration Framework)라는 이름을 붙였다.

잘 돌아갈 때는 마법 같다. 문제는 잘 안 돌아갈 때다.

사건: 50분간 응답 없음

React + Next.js 프로젝트(KARS)에서 /review 명령을 실행했다. 22개 파일이 변경된 상태에서 전체 코드 리뷰를 요청한 것이다.

50분이 지나도 응답이 없었다. 토큰은 계속 소비되고 있었다. 강제 중단하고 확인해보니, 리뷰 작업 자체는 이미 끝나 있었다. 결과 보고서를 생성하는 과정에서 멈춘 것이다.

원인: 3가지가 겹쳤다

1. 22개 파일을 한 번에 읽었다

에이전트가 git diff로 변경 파일 목록을 받고, 22개를 전부 Read했다. 컨텍스트 윈도우가 가득 차면 토큰 생성 속도가 극적으로 느려진다.

2. 빌드 실패 → 수정 → 재빌드 무한 루프

"빌드 실패 시 즉시 수정, 다음 단계 진행 금지"라는 규칙이 있었는데, 중단 조건이 없었다. npm run build가 25분이니까, 5회 반복하면 그것만 2030분.

3. 장문 보고서 생성 병목

모든 에이전트에 테이블, 시나리오, 체크리스트가 포함된 상세 보고서를 요구했다. 작업은 끝났는데 보고서 쓰는 데 수십 분이 걸렸다.

첫 번째 시도: 제한을 걸었다 — 그리고 의문이 생겼다

처음에는 직관적인 해결책을 적용했다:

- 파일 읽기 최대 10개
- 디렉토리 전체 탐색 금지
- docs/ 읽기 금지

효과는 있었다. 폭주는 멈췄다. 하지만 역효과가 보이기 시작했다.

BLE 센서 분석처럼 깊은 탐색이 필요한 작업에서 "파일 10개 읽었으니 여기서 멈춥니다"가 발생했다. 에이전트의 능력을 깎고 있었던 거다.

깨달음: 제한이 아니라 전략

사용자가 직접 에이전트에게 이렇게 말했더니 정상 동작했다:

"overview 먼저 하고, 기능별로 나눠서 순차적으로 리뷰해"

파일 22개를 읽는 건 똑같은데, 한 번에 읽느냐 나눠서 읽느냐의 차이였다.

이게 핵심이다. 에이전트를 제한하면 안 되고, 에이전트의 접근법을 바꿔야 한다.

해결: 전략 → 간소화 → 안전장치

1. 전략: 대규모 변경 처리법 (가장 효과적)

1. Overview: git diff --stat으로 파일 목록만 확인
2. 그룹핑: 기능별로 묶기 (품목 관리, 발주, 판매...)
3. 순차 처리: 그룹별로 관련 파일만 읽고 작업
4. 종합: 그룹별 결과를 합산

이걸 에이전트 프롬프트에 기본 동작으로 넣었다:

변경 파일 10개 이상일 때:
한 번에 전부 읽지 않는다. overview → 그룹핑 → 순차 처리.

탐색도 마찬가지:

# 제한 (❌)
"파일 읽기 최대 10개"

# 전략 (✅)
"Grep 먼저, Read 나중. 디렉토리를 통째로 읽지 않는다."

2. 간소화: 출력 형식 줄이기

에이전트 간에 주고받는 산출물은 기계가 읽는 것이다. 예쁘게 꾸밀 필요 없다.

# 변경 전 (리뷰 에이전트)
심각/경고/권장 분류 테이블 + 6개 체크리스트 + 빌드 상태 + 설계 일치도

# 변경 후
대상: path, path
빌드: TS ✅ | Lint ✅
이슈:
- 🔴 path:line — 설명
체크: 권한 ✅ | 캐시 ✅ | 날짜 ✅

간결한 출력이 빠른 응답이다.

3. 안전장치: 실패 제한 (전략이 아니라 안전장치)

전략으로 해결되지 않는 영역도 있다. 빌드 무한 루프 같은 건 전략이 아니라 중단 조건이 필요하다:

빌드 수정: 최대 3회. 초과 시 에러 목록 정리 후 중단.
에이전트 스폰 재시도: 최대 3회. 초과 시 메인 Claude가 직접 처리.

4. 최후 수단 (선택): Claude Code Hook

위 3가지로 대부분 해결된다. 하지만 에이전트 시스템이 복잡하거나(4+ 에이전트, 병렬 비평 등) 반복적으로 폭주가 발생하면 물리적 차단을 추가할 수 있다.

Claude Code의 PreToolUse Hook은 도구 호출 전에 스크립트를 실행하고, deny를 반환해서 차단한다.

#!/bin/bash
# 세션 파일 크기로 컨텍스트 포화 감지
INPUT=$(cat)
TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
SIZE_MB=$(( $(stat -f%z "$TRANSCRIPT") / 1048576 ))

if [[ $SIZE_MB -ge 6 ]]; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "세션 크기 초과. 새 세션에서 이어가세요."
    }
  }'
fi

모든 도구 호출마다 스크립트가 돌아가므로 오버헤드가 있다. 필요할 때만 도입하자.

왜 "제한"이 아니라 "전략"인가

처음에는 직감적으로 제한을 걸었다. 그런데 적용하고 보니:

• "파일 10개 제한"은 더 깊이있는 호출에서 역효과 — 깊은 탐색이 필요한데 능력을 깎았다
• "overview → 순차 처리"는 동일한 효과를 내면서 능력은 보존 — 22개 파일을 다 읽되, 나눠서 읽었다
• 숫자 제한은 프로젝트마다 적정값이 다름 — 유지보수 비용이 높다

제한은 증상을 억누르고, 전략은 원인을 해결한다.

정리

에이전트 오케스트레이션은 "잘 돌아갈 때"만 설계하면 안 된다. 실패할 때 어떻게 멈추는가, 그리고 멈추는 방법이 에이전트의 능력을 깎지 않는가가 더 중요하다.

AI 코딩 에이전트와 함께 일하면서, 작업 추적을 어떻게 해야 하는지 삽질하고 도달한 결론을 공유합니다.

1. 문제: AI가 코드를 짜는 시대에, 작업 추적은 누가 하나?

AI 코딩 에이전트(Claude Code, Cursor, Copilot 등)의 등장으로 개발 속도가 확 바뀌었습니다. "이 기능 구현해줘"라고 하면 코드 작성부터 커밋까지 해주는 세상이에요.

그런데 막상 써보면, 묘하게 불편한 순간이 옵니다.

"이 기능 구현해줘" → AI가 코드를 완성하고 커밋까지 해줌 → 다음 날 프로젝트 관리 도구를 열어보면... 티켓 상태는 '진행 중'

코드는 이미 main에 머지됐는데, 프로젝트 보드는 "아직 하고 있음"이라고 말하고 있습니다. AI가 빠르게 구현해준 덕에 코드는 앞서가는데, 관리 체계는 그 속도를 못 따라가는 거예요.

AI가 코드를 대신 짜주는 건 해결됐지만, "지금 뭘 하고 있고, 어디까지 됐는지" 추적하는 문제는 오히려 더 복잡해졌습니다.

2. 삽질기 — 69개 문서, 11,000줄

처음엔 "제대로 해보자"는 마음이었습니다. Jira나 Linear에서 보던 방식 — 큰 기능을 Epic으로 묶고, 구체적인 작업을 Ticket으로 쪼개고, 상태를 단계별로 전환하는 그 프로세스를 마크다운으로 옮겨서 AI 개발에 적용해봤습니다.

구조

planning/
├── epic-auth.md           # Epic (큰 기능 단위)
├── tickets/
│   ├── T-001.md           # Ticket (구체적 작업)
│   ├── T-002.md
│   └── ...
└── usecases/
    ├── usecase-login.md   # Usecase (사용자 시나리오)
    └── ...

• 3계층: Epic → Ticket → Usecase
• 5단계 상태 전환: draft → ready → in-progress → review → done
• 권한 분리: 사람은 상태 승인, AI는 구현

결과물: 69개 마크다운 파일, 총 11,000줄.

AI에게 "T-003 구현해줘"라고 하면 정확히 무엇을 만들어야 하는지 알려줄 수 있었습니다. 그 부분은 확실히 좋았어요.

그런데...

한 달 뒤 상태를 점검해봤더니:

69개 문서 중 80%의 상태가 실제 코드와 불일치. 티켓을 보고 판단하면 오히려 틀린 판단을 하게 되는 상황이었습니다.

3. 왜 실패했나 — "수동 상태 관리는 반드시 실패한다"

원인을 파고들면 결국 하나로 수렴합니다:

코드를 구현하는 행위와, 상태를 업데이트하는 행위가 별개의 작업이다.

AI가 코드를 짜고 커밋까지 했는데, 그 다음에 "이제 티켓 파일 열어서 status를 review로 바꿔"라는 건 코딩과 무관한 별도 작업입니다. 사람도, AI도 이걸 빼먹습니다.

코드 구현 ──→ 커밋 ──→ (여기서 끝내고 싶음)
                        ↓
                  status 필드 수동 갱신 ← 이건 코딩이 아니라 행정이다
                        ↓
                  (귀찮아서 안 함)
                        ↓
                  상태 불일치 발생

Jira든, Linear든, 마크다운 티켓이든 마찬가지입니다. 별도 상태 필드가 존재하는 한, 반드시 코드와 어긋나게 됩니다.

다른 사람들은 어떻게 하고 있을까?

이게 나만의 문제인지 궁금해서 11개 접근법을 조사해봤습니다.

• Cursor Rules / Memory Bank: IDE 안에서 규칙 파일로 맥락을 유지하지만, 작업 이력 추적이 약함
• SDD(Spec-Driven Development): Thoughtworks/GitHub 주도의 스펙 기반 개발. 구조적이되 유연한 방향
• AGENTS.md / Copilot Agent: 에이전트에게 맥락을 주는 데 집중하되, 상태 관리는 Git 기반으로 파생

이름과 형태는 달라도, 공통 트렌드가 하나 보였습니다:

별도 상태 필드 대신, 기존 인프라(Git, 체크리스트)에서 상태를 파생(derive)하는 방향.

그래서 결론에 도달했습니다.

"상태를 어떻게 정확하게 관리할까?"     ← 잘못된 질문
"수동 상태 관리는 반드시 실패한다"     ← 발견
"상태 필드를 제거하면?"               ← 발상의 전환
"체크리스트 자체가 상태다"             ← 해결

4. 해결: 체크리스트 = 상태

핵심 원리는 간단합니다.

Before (별도 상태 필드)

# 소셜 로그인
status: review        ← 이걸 누가 언제 바꾸나? → 아무도 안 바꿈
assignee: ai
priority: high

## 수락 기준
- Google OAuth 연동
- 프로필 정보 저장
- 에러 핸들링

After (체크리스트가 곧 상태)

# 소셜 로그인

> 사용자가 Google 계정으로 로그인할 수 있게 한다

## 수락 기준
- [x] Google OAuth 연동
- [x] 프로필 정보 저장
- [ ] 에러 핸들링

이것만 보면 "2/3 완료, 에러 핸들링만 남음"이라는 상태가 자명합니다. 별도 필드가 필요 없어요.

왜 이게 작동하는가

1. AI가 코드를 구현하면서 항목을 체크하는 건 자연스러운 동작입니다. "status 필드를 review로 바꿔"가 아니라, 구현이 끝난 항목에 [x]를 넣는 건 작업의 연장선이에요.

2. 상태가 존재하는 곳이 딱 한 군데입니다. 이중 관리 자체가 불가능하므로, 불일치도 불가능합니다.

3. "완료 처리해줘"라고 말할 필요가 없습니다. 체크리스트가 다 차면 끝입니다.

상태 파생 규칙

active/, done/ 같은 하위 폴더도 필요 없습니다. 폴더 이동도 수동 작업이니까, 역시 누락됩니다.

5. 뭘 버렸고, 왜 괜찮은가

한 파일이 기존의 Epic + Ticket + Usecase 역할을 모두 합니다. 3개 파일로 분산되던 정보가 하나로 합쳐지니, 동기화할 대상 자체가 없어요.

스펙 파일 템플릿

# {기능명}

> {이 기능이 해결하는 문제를 한 줄로}

## 배경

왜 이 기능이 필요한지. 사용자 관점에서 설명.

## 수락 기준

- [ ] 기준 1 — 구체적이고 검증 가능한 조건
- [ ] 기준 2
- [ ] 기준 3
- [ ] 빌드 성공

## 설계 메모

구현 방향, 기술 선택, 참고할 기존 코드 등.
처음엔 비어 있어도 됨. AI가 구현하면서 채울 수도 있음.

전체 10~30줄. 155줄짜리 티켓 문서와 비교해보세요.

비교표

실제 예시

69개 문서의 삽질 이후, 같은 프로젝트의 새 기능을 이 방식으로 관리해봤습니다:

# 시계열 메트릭 수집 및 조회

> 운동 중 시간/거리 기반으로 속도·거리 데이터를 샘플링하여 서버에 저장

## 수락 기준

### 데이터 수집
- [x] MetricsCollector 구현 — 시간 기준(5초) + 거리 기준(1m) 샘플링
- [x] Basic Training에 collector 연동
- [x] Interval Training에 collector 연동
- [x] Course Training에 collector 연동

### API 연동
- [x] WorkoutDetail 모델 생성
- [x] History POST 시 메트릭 데이터 포함하여 전송
- [x] 전송 실패 시 메트릭 제거 후 History만 재시도 (fallback)

### 디버그 확인 (현 단계)
- [ ] History 조회 시 메트릭 포함하여 파싱
- [ ] 디버그 위젯으로 메트릭 표시

### 유저 시각화 (추후)
- [ ] 속도-시간 그래프 표시
- [ ] 속도-거리 그래프 표시

이 파일 하나로 "데이터 수집과 API 연동은 끝났고, 프론트엔드 표시가 남았다"가 즉시 보입니다. 155줄짜리 티켓 3개를 만들 때보다 파악이 빨라요.

스펙이 필요 없는 경우

모든 작업에 스펙을 쓸 필요는 없습니다.

6. 도입 가이드 — 5분이면 됩니다

Step 1: 폴더 + 템플릿 (1분)

mkdir specs
# 위 템플릿을 specs/_template.md로 저장

Step 2: AI 설정 파일에 규칙 추가 (2분)

CLAUDE.md, .cursorrules 등 사용 중인 AI 도구의 설정 파일에 추가합니다:

## 스펙 기반 개발

- `specs/` 폴더에 기능별 스펙 파일이 있다.
- 스펙 구현 요청 시: 스펙 읽기 → 구현 → 수락 기준 체크(✅) → 커밋
- 커밋 메시지: `{type}({스펙파일명}): {설명}`
- status 필드 없음. 체크리스트의 체크 상태가 곧 진행률이다.
- 전부 체크되면 완료. 작은 작업은 스펙 없이 바로 커밋.

Step 3: 첫 스펙 작성 (2분)

지금 진행 중인 기능 하나를 골라서 스펙으로 작성해보세요. AI에게 "이 기능 코드를 분석해서 스펙으로 정리해줘"라고 시켜도 됩니다.

커밋 컨벤션 (선택)

feat(auth-social-login): Google OAuth 연동 구현
fix(payment-refund): 환불 금액 계산 오류 수정

스펙 파일명을 커밋에 포함하면 git log --grep="auth-social-login"으로 해당 기능의 전체 이력을 추적할 수 있습니다.

진행 상황 확인

# 완료된 스펙 (미체크 항목 없음)
grep -rL "\- \[ \]" specs/*.md

# 진행 중인 스펙 (미체크 항목 있음)
grep -rl "\- \[ \]" specs/*.md

7. 이 방법이 안 맞는 경우

만능은 아닙니다.

이 프로세스가 최적인 상황:

• 1인 개발 + AI
• 소규모 팀 (1~2명)
• 빠른 이터레이션이 중요한 프로젝트
• 사이드 프로젝트부터 중규모 앱까지

8. 정리

69개 문서, 11,000줄 → specs/ 폴더에 기능당 10~30줄짜리 파일 하나.
5단계 상태 전환 → 체크리스트가 곧 상태.
3계층 구조 → 한 파일이 전부.

핵심은 이겁니다:

"상태를 더 잘 관리하자"가 아니라, "상태 필드를 지우자"가 답이었다.

AI와 함께 일하면서 가장 먼저 깨진 게 "수동 상태 관리"였고, 가장 효과적이었던 건 "관리할 대상을 줄이는 것"이었습니다.

지금 바로 mkdir specs를 치고, 진행 중인 기능 하나를 10줄짜리 스펙으로 적어보세요. 다음에 AI한테 "이 스펙 구현해줘"라고 했을 때, 체크리스트가 알아서 채워지는 걸 보면 감이 올 겁니다.

AI 코딩 에이전트가 복잡한 작업에서 반복 실패하는 문제를, 역할 분리와 게이트 시스템으로 해결한 실전 프레임워크.

문제 인식: AI는 왜 같은 실수를 반복하는가

Claude Code 같은 AI 코딩 에이전트에게 복잡한 작업을 맡기면 특유의 실패 패턴이 나타난다:

1. "이미 알고 있다"는 과신 — 리서치를 건너뛰고 기억에 의존해 코드를 작성
2. 증상 패치의 반복 — 근본 원인을 분석하지 않고 보이는 에러만 수정
3. 범위의 무한 확장 — 한 파일 수정이 다른 파일로 번지고, 원래 의도와 동떨어진 변경이 쌓임

실제로 한 게임 프로젝트에서 UI 전환 시스템을 구현할 때, AI에게 직접 코딩을 맡긴 결과 7회 연속 실패했다. 매번 다른 증상이 나타났지만, 근본 원인은 동일했다 — 분석 없이 코딩부터 시작하는 구조적 문제.

바뀌어야 할 건 AI의 코딩 실력이 아니라, AI를 운용하는 프로세스였다.

핵심 아이디어: 역할 분리

CAOF의 핵심은 단순하다. "분석하는 AI"와 "구현하는 AI"를 분리한다.

왜 이게 작동하는가?

• Designer가 코드를 쓰지 않으므로 분석에 집중할 수 있다
• Implementer가 분석하지 않으므로 계획서 범위 안에서만 움직인다
• Reviewer에게 반박 의무가 있으므로 "돌아가니까 통과"가 불가능하다

이것은 소프트웨어 공학의 오래된 원칙 — 관심사의 분리(Separation of Concerns) — 을 AI 에이전트 운용에 적용한 것이다.

모든 작업에 적용하지 않는다: 트랙 시스템

CAOF의 실용성은 "언제 적용하고 언제 건너뛰는가"에 있다.

판단 기준은 코드 줄 수가 아니라 "실패 시 되돌리기 비용"이다.

1줄 변경이라도 물리 엔진 파라미터나 DB 스키마 변경이면 Standard 이상. 100줄 변경이라도 새 유틸 함수 추가면 Trivial일 수 있다.

GATE 파이프라인: Critical 트랙의 7단계

Critical 트랙은 다음 7개 게이트를 순서대로 통과해야 한다. 이전 단계의 산출물이 없으면 다음 단계를 시작할 수 없다.

GATE 0 — 필요성 검증

산출물: "왜 필요한가" 1문장

• "이걸 왜 만들어야 하는가?"
• "기존 시스템으로 해결 가능하지 않은가?"
• 가장 자주 스킵되지만, 가장 비용을 아끼는 단계

GATE 1 — 리서치

산출물: 리서치 요약

• 기술적 불확실성을 웹 검색 등으로 조사
• "이미 알고 있다"는 스킵 사유가 아님 — 목적은 "모르는 것을 모르는 상태" 방지
• 프로젝트 내 검증된 패턴은 코드베이스 탐색으로 대체 가능

GATE 2 — 설계

산출물: 구현 계획서 + 성공 기준

Designer가 파일/함수 수준의 구체적인 계획서를 작성한다:

- 수정 파일: 경로
- 수정 함수: 이름
- 근본 원인: (1줄)
- 수정 전 동작 / 수정 후 기대 동작
- 건드리지 않는 것: (명시)
- 성공 기준: (체크리스트)

"건드리지 않는 것"을 명시하는 게 핵심이다. Implementer의 범위 확장을 사전에 차단한다.

GATE 3 — 승인

산출물: 사용자 "승인"

계획 요약을 사용자에게 제시하고, 승인 후에만 구현을 시작한다.

GATE 4 — 구현

산출물: 수정된 코드

• 반드시 Implementer 에이전트가 구현 (Designer가 직접 코딩하지 않음)
• GATE 1 리서치 + GATE 2 계획서를 컨텍스트로 전달
• 구현 중 "모르는 동작" 발견 시 즉시 중단, GATE 1로 복귀

GATE 5 — 검수

산출물: 검수 보고서

• GATE 2의 성공 기준 대비 결과를 대조
• 교차 모델 검수 권장 — 같은 모델의 자기 검수는 자기 동의 편향(self-agreement bias) 위험
• Reviewer는 반박 의무가 있음

GATE 6 — 테스트

산출물: 사용자 테스트 결과

• 사용자가 직접 테스트
• 버그 발견 시 버그 수정 파이프라인(Standard 트랙) 적용

버그 수정: Designer를 거치는 이유

Implementer에게 직접 버그를 넘기지 않는다.

버그 증상 + 로그
    ↓
Designer: 근본 원인 분석 + 수정 방향 + 영향 범위
    ↓
Implementer: 수정 방향대로만 구현
    ↓
검수 + 테스트

Implementer는 코딩 전문이지 진단 전문이 아니다. 원인 분석 없이 넘기면 증상만 패치하게 된다. 이것이 "7회 연속 실패"의 직접적 원인이었다.

실패 에스컬레이션: 3회면 멈춘다

1회 실패: Implementer가 원인 분석 후 재시도
2회 실패: Designer가 원인 재분석
           → 구현 문제: 다른 접근법으로 재구현
           → 설계 문제: GATE 2로 롤백
3회 실패: 즉시 중단 + 사용자에게 보고
           → 기능 범위 축소 또는 대안 기능으로 전환

"접근 전환"의 구체적 행동:

• 추가 리서치 (새 키워드, 다른 기술 스택)
• Designer 교체 (다른 모델에 위임)
• 기능 범위를 MVP로 축소
• 최소 재현 테스트로 가설 검증

중요한 건 "빨리 해", "바로 구현해"는 게이트 스킵 승인이 아니라는 점이다. "N단계 스킵 승인"이라는 명시적 문구만 허용한다.

에이전트 설계: 극단적 페르소나가 역할 분리를 만든다

Claude Code의 커스텀 에이전트(.claude/agents/)를 활용해 역할을 구현한다.

에이전트 카드 구조

---
name: [에이전트 이름]
description: [한 줄 설명]
model: [opus/sonnet — Designer는 opus, Implementer는 sonnet 권장]
tools: [사용 가능한 도구]
---

# 페르소나
[2~3줄로 사고방식과 가치관. 극단적일수록 좋다.]

## 사고 원칙
1. [최우선 원칙]
2. [두 번째 원칙]

## 범위 제약
- 이 에이전트가 하는 것
- 이 에이전트가 하지 않는 것 ← 이게 더 중요

## 과거 교훈
- [실패에서 학습한 내용 — 날짜와 함께]

4가지 설계 원칙

1. 페르소나가 극단적이어야 역할 분리가 작동한다 — "꼼꼼한 개발자"는 약하다. "버그를 못 찾으면 잠을 못 자는 15년차 시니어"는 강하다.
2. "하지 않는 것"이 "하는 것"보다 중요하다 — Designer가 코드를 쓰기 시작하면 역할 분리가 무너진다.
3. 모델 선택: Designer = Opus, Implementer = Sonnet — Designer는 깊은 분석이 필요하고, Implementer는 빠른 실행이 필요하다.
4. 교훈 섹션이 에이전트를 성장시킨다 — 프로젝트에서 발견한 실수를 에이전트 카드에 축적하면, 같은 실수를 반복하지 않는 구조가 된다.

모델 선택과 교차 검증

Designer = Opus, Implementer = Sonnet

교차 모델 검수의 필요성

같은 모델이 자기 코드를 검수하면 자기 동의 편향(self-agreement bias)이 발생한다. 자신이 작성한 로직을 "합리적"으로 판단하는 경향이 있어, 실제 결함을 놓친다.

CAOF에서는 구현과 검수에 서로 다른 모델을 사용하는 교차 검증을 권장한다:

• Sonnet이 구현 → Opus + Gemini가 검수
• 4모델 병렬 검수 (Gemini + Opus + Sonnet + Haiku)로 다각도 리뷰

실전 검증 데이터

Phase 0에서 7회 실패하던 작업이, CAOF 도입 후 Phase 14에서 각각 12회만에 성공했다. 변한 건 AI 모델이 아니라 프로세스다.

새 프로젝트에 적용하는 법

Step 1: 프로젝트의 실패 비용 분석

• 이 프로젝트에서 가장 비싼 실수는 무엇인가?
• 실수 후 되돌리기에 얼마나 걸리는가?
• 과거에 같은 실수를 반복한 적이 있는가?

Step 2: Designer/Implementer 역할 결정

Step 3: 에이전트 카드 작성

.claude/agents/ 디렉토리에 Designer와 Implementer 에이전트를 생성한다.

Step 4: CLAUDE.md에 CAOF 규칙 삽입

트랙 분류 기준, 라우팅 트리, 실패 에스컬레이션 규칙을 프로젝트 설정에 추가한다.

Step 5: 첫 기능으로 캘리브레이션

첫 Critical 기능을 풀 GATE로 실행하면서 병목을 측정하고, 5개 기능 완료 후 회고로 프레임워크를 조정한다.

프로젝트 유형별 적용 예시

Designer가 없으면 메인 Claude가 겸임하되, 교차 검증으로 자기 동의 편향을 보완한다.

핵심 교훈

1. AI의 코딩 실력은 충분하다. 부족한 건 프로세스다. — 같은 모델이 프로세스만 바꿔도 성공률이 극적으로 올라간다.
2. 역할 분리의 핵심은 "하지 않는 것"을 정의하는 것이다. — Designer가 코드를 쓰는 순간 프레임워크가 무너진다.
3. 되돌리기 비용이 트랙을 결정한다. — 줄 수, 파일 수는 보조 지표일 뿐이다.
4. "빨리 해"는 게이트 스킵이 아니다. — 급할수록 프로세스를 지켜야 한다. 7회 실패와 1회 성공 중 어느 쪽이 더 빠른가.
5. 에이전트는 경험으로 성장한다. — 실패 교훈을 에이전트 카드에 축적하면, 프로젝트가 진행될수록 에이전트가 똑똑해진다.
6. 자기 동의 편향은 실재한다. — 반드시 교차 모델 검수를 적용해야 한다.

CAOF는 Claude Code의 커스텀 에이전트 시스템 위에 구축된 실전 프레임워크입니다. 2026년 3월, 실제 프로젝트에서의 반복 실패를 계기로 설계되었으며, 도입 후 구현 성공률이 극적으로 개선되었습니다.

주의! 이미 GetX를 사용하고 있는 프로젝트에서 올바른 사용법을 제시하는 것이 목적입니다. 절대로 새로운 프로젝트에 GetX 도입을 권장하는 것이 아닙니다. 새 프로젝트에서는 Provider, Riverpod 등의 권장 패턴을 써주세요!

개요

Bindings는 인스턴스의 의존성 주입과 라이프사이클을 관리하는 GetX의 핵심 메커니즘입니다.

GetX Bindings의 주요 특징:

• 의존성 주입 관리: 컨트롤러, 서비스, 저장소 등의 의존성을 자동으로 관리, Get.put()과 Get.find() 사용
• 메모리 최적화: 페이지 생성 시에만 의존성을 주입하고, 페이지 제거 시 자동으로 메모리에서 해제
• 생명주기 관리: 라우트 기반으로 의존성의 생명주기를 자동 관리

이 글에서는 GetX 공식 문서의 Bindings 개념과 참여했던 실제 프로젝트에서 어떻게 적용했는지 비교 분석해보겠습니다.

GetX Bindings란?

공식 문서 정의(공식문서)

Bindings는 인스턴스의 의존성 주입과 라이프사이클을 관리하는 GetX의 핵심 메커니즘 이며, 다음과 같은 특징을 가집니다:

• 의존성 주입 관리: 컨트롤러, 서비스, 저장소 등의 의존성을 자동으로 관리
• 메모리 최적화: 페이지가 생성될 때만 의존성을 주입하고, 페이지가 제거될 때 자동으로 메모리에서 해제
• 생명주기 관리: 라우트 기반으로 의존성의 생명주기를 자동 관리, 알아서 켜지고 꺼지고

확실히 '마법같은' 기능을 제공하기로 유명한 만큼, 개발자들이 놓칠 수 있는 부분을 알아서 잡아주는 편리함이 눈에 띄네요.

기본 사용법

class HomeBinding extends Bindings {
  @override
  void dependencies() {
    Get.put<HomeController>(HomeController());
    Get.lazyPut<ApiService>(() => ApiService());
  }
}

이런 식으로 HomeBinding을 구성하고, HomePage의 라우트에 같이 묶어둡니다. 그리고 Get.put 메서드에는 주입하는 의존성의 타입을 정확하게 명시해주세요.

static final routes = [
  GetPage(
    name: HomePage.routeName,
    page: () => const HomePage(),
    binding: HomeBinding()),
  ...
  ];

이제 HomePage로 라우팅 할 때 HomeBinding에 붙어있는 의존성들이 줄줄히 인스턴스화 됩니다. put메서드가 아니라 lazyPut메서드로 주입한건 '필요할 때만 생성'됩니다. 아래에서 또 언급 하겠습니다.

GetMaterialApp과 Bindings의 관계

GetMaterialApp의 핵심 역할

GetX의 모든 기능은 GetMaterialApp 내에서 동작합니다. 이는 일반 Flutter의 MaterialApp을 확장한 것으로, GetX의 상태관리, 라우팅, 의존성 주입 등의 기능을 제공합니다. 물론 Binding도 이 안에서 사용해야겠죠?

class App extends StatefulWidget {
  @override
  Widget build(BuildContext context) {
    return GetMaterialApp(
      title: 'WheelyX',
      initialRoute: PageRouter.initial,
      getPages: PageRouter.routes,
      initialBinding: InitialBinding(),  // 앱 전체 초기 의존성
      // ... 기타 설정들
    );
  }
}

Bindings의 계층 구조

GetMaterialApp사용 하에 Bindings는 라우터에만 거는게 아니라, 다양한 방식으로 여러곳에 묶을 수 있습니다.

1. InitialBinding: 앱 시작 시 전역적으로 필요한 의존성 (상시 의존)
2. Route Binding: 각 페이지별로 필요한 의존성 (페이지에 의존)

GetMaterialApp 환경에서 Bindings는 다음과 같은 계층 구조로 관리됩니다:

My App Service
├── InitialBinding (앱 전체)
│   ├── AuthStore (permanent: true)
│   ├── FCM Controller (permanent: true)
│   └── Repository Layer (fenix: true)
└── Route Bindings (페이지별)
    ├── HomeBinding
    ├── AuthBinding
    └── TrainingBinding

InitialBinding - 앱 전체 초기 의존성

주로 앱 전체에서 공유되는 핵심 서비스들을 여기에 걸어둡니다.

class InitialBinding extends Bindings {
  @override
  void dependencies() {
    // FCM 푸시메세지 관리자
    Get.put<FcmFirebaseController>(
      FcmFirebaseController(messaging: FirebaseMessaging.instance),
      permanent: true,  // 앱 종료까지 유지
    );

    // 항상 관리해야 하는 중요한 상태
    Get.put<AuthStore>(AuthStoreImpl(), permanent: true);
    Get.put<HistoryStore>(HistoryStoreImpl(), permanent: true);

    // Repository 계층
    Get.lazyPut<AuthRepository>(
      () => AuthRepositoryImpl(authDio: Get.find<AuthDio>()),
      fenix: true,  // 사용 후에도 메모리에 유지
    );
  }
}

이렇게 선언후 위의 GetMaterilaApp의 initialBinding에 넣어주면 됩니다. 프로젝트에서 InitialBinding에 포함시켜야 할 주요 의존성은 대부분 전역에서 관리해야 하는 객체들로, 아래처럼 정리할 수 있을 것 같습니다.

포함해야 할 의존성:

• 앱 생명주기와 일치하는 서비스
• 전역 상태 관리 객체
• 시스템 서비스 (푸시 알림, 센서 연결 등)
• 인증 관련 서비스

제외해야 할 의존성:

• 페이지별 ViewModel
• 초기화 비용이 높은 서비스
• 조건부로만 필요한 기능

여기서 짚어봐야 할 점이 있습니다. 바로 Get.put과 lazyPut이라는 인스턴스의 두 개의 의존성 생산 전략과, 이들과 함께 붙는 permanent, fenix 파라미터 입니다. 잠시 체크하고 가겠습니다.

Get.put() vs Get.lazyPut()

생성 시점과 메모리 비용 효율성을 고려해서 어떻게 생성할 건지를 결정하는 메서드인 만큼, 잘 골라서 사용해야 합니다.

permanent vs fenix 심화 이해

permanent의 경우는 말 그대로 true로 하는 경우 어떤 상황에도 종료되지 않고 항시 인스턴스가 유지되도록 해주는 기능입니다. 앱이 종료되기 전 까지 절대로 해제되지 않고 메모리에 상주시키며, 항상 접근이 가능한 기능입니다.

그렇다면 fenix(피닉스)는 lazyPut에 붙어서 사용 할 때마다 부활하는 특성을 보여주는 기능으로, 사용 후 메모리에서 해제되지만 재사용 시 기존 인스턴스를 그대로 활용하는 기능입니다.

좀 유치하지만 "불사조(Phoenix)" 패턴이라고 부르던데.. 아래와 같은 동작방식을 가지니 알아두면 좋을 것 같습니다.

동작 방식:

1. 첫 번째 Get.find: 인스턴스가 생성되고 메모리에 저장됨
2. 사용 완료: 일반적으로 lazyPut은 사용 후 메모리에서 해제됨
3. 재사용 시: fenix: true가 있으면 기존 인스턴스를 재활용
4. 메모리 효율성: 사용하지 않을 때는 메모리에서 해제되지만, 재사용 시 빠른 접근 가능

즉, 인스턴스를 새로 만들지 않고, 기존 인스턴스가 잠깐 죽어있다가 부활한다는 의미입니다.

AuthRepository에 왜 lazyPut과 fenix를 사용했을까요?

항시 켜놓아도(put과 permanent를 통해) 상관없을지 모르지만, repository계층의 특성을 생각하면 lazyPut이 적합하다고 판단했습니다. 하지만 인스턴스는 쓰던 놈을 계속 써야 하죠. 정리하자면 아래와 같은 이유가 있습니다.

• 네트워크 연결 재사용: HTTP 클라이언트(Dio) 연결을 재활용하여 성능 향상
• 토큰 관리: 인증 토큰이 저장된 Repository 인스턴스를 재사용
• 메모리 효율성: 사용하지 않을 때는 메모리에서 해제, 필요할 때만 유지
• 빠른 응답: 재사용 시 새로운 인스턴스 생성 시간 절약

실제 프로젝트에서의 활용 예시도 볼까요?

// AuthDio - HTTP 클라이언트 (토큰 관리)
Get.lazyPut<AuthDio>(
  () => AuthDio(locale: Get.locale, dio: Dio(), storage: FlutterSecureStorage()),
  fenix: true,
);

// AuthRepository - 인증 관련 API 호출
Get.lazyPut<AuthRepository>(
  () => AuthRepositoryImpl(authDio: Get.find<AuthDio>()),
  fenix: true,
);

이렇게 fenix: true를 사용하면 메모리 효율성과 성능을 동시에 확보할 수 있습니다. 주로 Repository, API 클라이언트같은** 무거운 객체, 네트워크 연결, 데이터베이스 연결 같은 초기화 비용이 높은 객체, 특정 기능에서만 **가끔 사용하는 객체 등을 등록해주시면 됩니다.

RouteBinding - 라우트 기반 의존성 관리

Route Bindings는 각 페이지별로 필요한 의존성을 관리하는 핵심 메커니즘입니다. InitialBinding에서 전역 서비스를 관리했다면, Route Bindings는 페이지 생명주기와 연결된 컨트롤러와 서비스를 관리합니다.

기본 구현 패턴

1. 단일 ViewModel Binding

class HomeBinding extends Bindings {
  @override
  void dependencies() {
    Get.put<HomeViewModel>(HomeViewModel(
      authRepository: Get.find<AuthRepository>(),
      authStore: Get.find<AuthStore>(),
    ));
  }
}

특징:

• 페이지 진입 시 ViewModel 생성
• 페이지 종료 시 자동으로 메모리에서 해제
• InitialBinding의 전역 의존성 활용

2. 다중 의존성 Binding

여러 기능을 하나의 ViewModel에 묶어서 사용하는 경우 다중 의존성 Binding기법을 사용해주세요.

제 프로젝트에서는 운동을 수행할 때, 유저 정보, 히스토리(운동 기록)정보, 블루투스 연결, 운동을 수행하는 트레이닝 서비스 등등 많은 기능이 필요했습니다.

class TrainingBinding extends Bindings {
  @override
  void dependencies() {
    // ViewModel 주입
    Get.put<BasicTrainingViewModel>(BasicTrainingViewModel(
      authRepository: Get.find<AuthRepository>(),
      historyRepository: Get.find<HistoryRepository>(),
      bluetoothStore: Get.find<BluetoothStoreImpl>(),
    ));

    // 페이지별 서비스 주입
    Get.put<TrainingService>(TrainingService());
    Get.put<TimerService>(TimerService());

    // Lazy 의존성 주입
    Get.lazyPut<SensorDataProcessor>(() => SensorDataProcessor());
  }
}

Route Bindings 심화 패턴

1. 조건부 Bindings

Get.arguments를 통해 매개변수를 전달 받아서 의존성을 조건부로 주입합니다.

class HistoryDetailBinding extends Bindings {
  @override
  void dependencies() {
    // 기본 ViewModel
    Get.put<HistoryDetailViewModel>(HistoryDetailViewModel(
      historyRepository: Get.find<HistoryRepository>(),
    ));

    // 조건부 서비스 주입
    final args = Get.arguments as HistoryDetailArgs?;
    if (args?.isGameHistory == true) {
      Get.put<GameAnalysisService>(GameAnalysisService());
    }

    if (args?.needsComparison == true) {
      Get.lazyPut<ComparisonService>(() => ComparisonService());
    }
  }
}

혹은 Get.parameters를 사용해도 됩니다.

class CourseBinding extends Bindings {
  @override
  void dependencies() {
    // 트레이닝 코스를 판별
    final courseId = Get.parameters['courseId'];

    // 특정 트레이닝 코스별로 기능 구분
    Get.put<CourseViewModel>(CourseViewModel(
      courseId: courseId,
      courseRepository: Get.find<CourseRepository>(),
    ));
    Get.lazyPut<CourseAnalyzer>(() => CourseAnalyzer(courseId: courseId));
  }
}

2. 계층형 Bindings

BaseBinding을 만들어서 코드의 중복을 줄이고, 공통 사용 의존성을 쉽게 관리합니다. Bindings도 클래스기 때문에 당연히 유효한 전략입니다.

// 공통 기능을 담당하는 Base Binding
abstract class BaseTrainingBinding extends Bindings {
  void registerCommonDependencies() {
    Get.put<SensorService>(SensorService());
    Get.put<AudioService>(AudioService());
  }
}

// 구체적인 트레이닝별 Binding
class ATrainingBinding extends BaseTrainingBinding {
  @override
  void dependencies() {
      // 공통 의존성 등록 딸깍
    registerCommonDependencies();

    Get.put<ATrainingViewModel>(ATrainingViewModel(
      sensorService: Get.find<SensorService>(),
      audioService: Get.find<AudioService>(),
    ));
  }
}

class BTrainingBinding extends BaseTrainingBinding {
  @override
  void dependencies() {
      // 공통 의존성 등록 딸깍
    registerCommonDependencies();

    Get.put<BTrainingViewModel>(BTrainingViewModel(
      sensorService: Get.find<SensorService>(),
      audioService: Get.find<AudioService>(),
    ));

    // B 트레이닝에만 붙는 서비스
    Get.put<SpecialTimerService>(SpecialTimerService());
  }
}

마무리 및 GetX Bindings 사용 시 주의사항

마무리로 Bindings사용 전략을 정리하고, 권장 패턴과 안좋은 패턴을 알아보고 끝내겠습니다.

1. 과도한 전역 의존성 지양: InitialBinding에는 정말 필요한 것만 등록
2. 타입 안전성: Get.put<Type>()에서 타입을 명시적으로 선언
3. 메모리 관리: permanent와 fenix 옵션을 적절히 활용
4. 의존성 순서: 의존성 간의 순서를 고려하여 등록

권장 패턴

// ✅ 좋은 예
class WellStructuredBinding extends Bindings {
  @override
  void dependencies() {
    // 1. 필수 서비스부터
    Get.put<CoreService>(CoreService());

    // 2. ViewModel 등록
    Get.put<PageViewModel>(PageViewModel(
      coreService: Get.find<CoreService>(),
    ));

    // 3. 옵셔널 서비스는 lazy로
    Get.lazyPut<OptionalService>(() => OptionalService());
  }
}

비 권장 패턴

// ❌ 피해야 할 예
class PoorBinding extends Bindings {
  @override
  void dependencies() {
    // 타입 명시 없음
    Get.put(SomeController());

    // 불필요한 permanent 사용
    Get.put(TemporaryService(), permanent: true);

    // 의존성 순서 무시
    Get.put(DependentService(Get.find<NotYetRegistered>()));
  }
}

Unhandled Exception: [firebase_auth/invalid-credential] Invalid OAuth response from apple.com

Firebase Authentication 관련해서, 특히 Apple 소셜로그인 기능에서 해당 에러가 발생하는데 원인과 해결책을 공유하고자 합니다.

이것은.. Firebase 인증을 사용하여 Flutter 앱에 Apple로 로그인 기능을 통합할 때 발생하는 "[firebase_auth/invalid-credential] Invalid OAuth response from apple.com" 오류입니다.

이 오류는 Firebase에 제공된 OAuth 자격 증명이 불완전하거나 유효하지 않을 때 발생합니다.

[ERROR:flutter/runtime/dart_vm_initializer.cc(41)] Unhandled Exception: [firebase_auth/invalid-credential] Invalid OAuth response from apple.com
#0      FirebaseAuthHostApi.signInWithCredential (package:firebase_auth_platform_interface/src/pigeon/messages.pigeon.dart:1098:7)
<asynchronous suspension>
#1      MethodChannelFirebaseAuth.signInWithCredential (package:firebase_auth_platform_interface/src/method_channel/method_channel_firebase_auth.dart:306:22)
<asynchronous suspension>
#2      FirebaseAuth.signInWithCredential (package:firebase_auth/src/firebase_auth.dart:515:9)
<asynchronous suspension>
#3      AuthService.signInWithApple (package:parkbestapp/services/auth_service.dart:73:9)
<asynchronous suspension>

위와 같이 에러가 나오더라도, 처음 직면했다면 원인을 어디부터 찾아야 할 지 애먹을 수 있습니다.

원인 분석

Firebase Auth, 특히 애플쪽 에러는 4가지를 체크 해야 합니다.

1단계: Apple Developer Console 설정 2단계: Firebase Console 설정 3단계: 내 프로젝트 코드 확인

현재 문제는, 결론부터 말씀 드리면 3단계, 내 프로젝트 코드부터 체크 해야 하는 문제로, 이전까지 OAuthCredential을 생성하기 위해 넣던 데이터에 한 가지를 추가로 넣어주어야 합니다. FirebaseApple 로그인 프로세스에서 검색된 accessToken이 누락되거나 유효하지 않기 때문입니다.

특히 내 패키지들 버전(혹은 플러터 버전도 같이)을 훅 올렸을 때 직면하게 되는 문제인데, firebase_auth 패키지 버전 4.3.0부터 웹 Firebase SDK v9의 모듈식 접근 방식과 관련된 변경 사항이 적용되었고 이로 인해 Apple로 로그인 시 accessToken 또는 authorizationCode를 전달해주도록 변경되었습니다.

그러므로 3단계 코드 수정부터 들어가고, 이후 1, 2단계 부분을 어떻게 확인해야 하는지도 같이 살짝 들여다보겠습니다. (필요 없으신 분들은 바로 아래에 있는 "3단계: 코드 수정하기"까지만 봐주세요!)

3단계: 코드 수정하기

코드 '수정하기' 인 만큼, 이전에 애플 소셜로그인 기능을 이미 다 구현했다고 생각하고 진행 하겠습니다. 처음 구현해야 한다면 이 블로그 글로 가주세요!

아마 대부분의 플러터 개발자 분들이 FlutterFire 공식 docs를 보고 애플 소셜 로그인 기능을 구현 하실텐데요, 아직 이 공식문서에도 문제 해결 방법은 적용이 안 되어 있습니다.

위에서 말씀드린 OAuthCredential 생성 부분입니다.

  // Create an `OAuthCredential` from the credential returned by Apple.
  final oauthCredential = OAuthProvider("apple.com").credential(
    idToken: appleCredential.identityToken,
    rawNonce: rawNonce,
  );

이 부분에서 accessToken이라는 한 가지 매개변수를 추가해주면 됩니다.

final oauthCredential = OAuthProvider("apple.com").credential(
  idToken: appleCredential.identityToken,
  rawNonce: rawNonce,
  accessToken: appleCredential.authorizationCode, // 이제 appleCredential의 인증 코드를 넣어주세요
);

끝이냐구요? 네, 끝입니다. accessToken을 넣어준 것으로 생성되는 OAuthCredential객체가(위 코드에는 타입이 안 써있지만, oauthCredential의 명시적 타입입니다.) 필요한 데이터를 잘 받게 되었으니 이제 다른 firebase나 apple developer쪽에 문제가 없으면 로그인이 정상적으로 잘 될 것입니다.

그래도 혹시 모르니 print를 촘촘하게 찍어서 모두 체크해주세요. 이런식으로 보면 서로 알기 쉽고 좋습니다.

여기 말고도 FirebaseAuth의 소셜 로그인 Flow마다 응답 객체와 승인 여부를 함께 확인해주세요.

이후에도 로그인이 안 된다면, 아래 1단계, 2단계 설정 확인 방법을 진행해주세요.

1단계: Apple Developer Console 설정

https://developer.apple.com/account 로 접속후 로그인, 이후 '인증서, ID 및 프로파일(Certificates, Identifiers & Profiles)'에서 다음 설정을 확인해주세요:

1-1. 식별자(Identifiers) 확인하기

위 스크린샷 처럼 Service ID를 찾아서 들어간 후, 소셜로그인에 사용하고 있는 Service ID를 누릅니다.

그리고 위와 같이 primary app id, domain, returl url이 잘 적혀있는지 체크해주세요.

primary app id는 'Identifiers'의 'App IDs'에서 확인할 수 있는데, 프로젝트를 등록할 때 필수로 쓰는 'com.myCompany.projectName'같은 값을 말합니다.

Return URL의 경우는 Firebase Console의 Authentication-로그인 방법-로그인 제공업체 중 Apple로 들어가시면 확인할 수 있습니다.

Domain은 Return URL에서 맨 앞의 'https(혹은 http)://'와 맨 뒤의 '/__/auth/handler'를 뺀 부분입니다.

1-2. Keys확인하기

다시 Certificates, Identifiers & Profiles에서 이제는 Keys로 들어갑니다. 그러면 내 소셜로그인에 사용하고 있는 Key가 보일텐데, 들어가서 'Sign In with Apple'서비스가 Enable되어 있는지, 'Primary App ID'가 'Service ID'에 설정한 'Primary App ID'랑 동일한지를 확인해주세요.

이미 만들어놓은 key의 경우 .p8파일 다운로드가 안되니, 어디에 잘 보관해두신 파일이 있는지 찾아보거나 새로 만들어주세요!

이 Service ID와 key는 Firebase Console에 그대로 넣어야 합니다.

2단계: Firebase Console 설정

내 프로젝트의 Authentication-로그인 방법-로그인 제공업체 중 Apple로 들어가서, 위의 Apple Developer Console에서 확인한 정보들이 잘 기입되어 있는지 체크합니다.

특히 비공개 키의 경우, 위에서 말씀드린 대로 사용하시는 키의 .p8파일을 코드에디터로 열어서 그 안에 있는 내용을 전체 다 복붙 해줘야 합니다.

자 이제 Apple Developer Console 점검 방법, Firebase Console 점검 방법, 내 코드 점검 방법까지 확인해봤습니다. 에러가 해결되셨기를 바라며 마치겠습니다.

그러기 앞서 먼저 Flutter의 기본 골자에 대해서 다시 복습해 보죠.

Flutter의 기본 구조: Widget, Element, RenderObject 트리

Widget: UI를 설명하는 불변(immutable) 객체입니다. 단순한 설계도 역할을 합니다.

Element: Widget의 런타임 표현으로, 실제 사용 중에 상태를 관리하고 연결을 유지합니다.

RenderObject: Element와 연결되어 실제 화면을 구성하고 그림을 그리는 객체입니다.

즉, Flutter는 Widget → Element → RenderObject로 이어지는 구조를 통해 화면을 구성합니다. provider또한 이 구조를 사용해서 상태를 관리하고 리렌더링을 하게 되는데, 특히 데이터를 효율적으로 전달하기 위해 element 트리를 활용합니다.

Provider의 Element활용

1. Provider의 기본: InheritedWidget 기능 확장

• (1장 내용)Provider는 Flutter의 InheritedWidget을 기반으로 하여, 데이터 전파와 상위-하위 위젯 간 데이터 공유를 가능하게 합니다.

• 하지만 정확히 말하면, Provider는 InheritedWidget을 확장(extend)하여 InheritedElement를 통해 상태 관리와 화면 리렌더링을 제어하고 있어요. 여기에 상태관리 기능(DelegateState)을 추가한거죠.

• InheritedWidget인은 InheritedElement를 만들어서 관리하는데, Provider는 내부적으로 InheritedWidget의 메커니즘을 extend하고 있기 때문에 마찬가지로 InheritedElement를 사용합니다.

2. BuildContext와 Element의 관계

• Flutter에서 BuildContext는 사실상 하나의 Element입니다. build메서드는 보통 build(BuildContext context)이렇게 선언되잖아요?

• 모든 위젯이 빌드 될 때에 이(BuildContext context)가 포인터 개념이 되어서 자신의 위치를 알려주게 됩니다.

• 이것을 응용해서 Provider는, Provider.of(context), context.watch() 등을 호출하면, context를 시작으로 가장 가까운 InheritedElement를 탐색하도록 구성되어 있습니다. 마찬가지로 1장에서 다뤘듯, .of메서드는 dependOnInheritedWidgetOfExactType을 래핑해놓은 문법적 설탕이죠

• 자 이제 탐색 과정에서 내가 찾고있는 데이터가 있으면 의존성 등록을 하여, 이후 데이터 변경을 감지할 수 있게 됩니다.

InheritedWidget dependOnInheritedWidgetOfExactType<T extends InheritedWidget>() {
  registerDependency(this, inheritedElement);
  return inheritedElement.widget as T;
}

• registerDependency(의존성 등록)에 inheritedElement를 넣잖아요? 해당 Element의 _dependencies 목록에 등록되어, Provider가 데이터 변경(notify) 시 관련 위젯들이 리빌드됩니다.

3. 데이터 변경 통지 과정

Provider 내부 데이터가 변경되면, (1)의존성을 등록했던 Consumer 위젯들이 다시 알림을 받고, (2)didChangeDependencies()가 호출되며, (3) 마침내 해당 위젯들이 다시 build()됩니다.

이렇게 Element 구조를 이용해 Provider는 효율적으로 화면을 리렌더링합니다.

DelegateState의 동작 방식

다음은 Provider 내부 구조의 핵심 중 하나인 DelegateState에 대해서 보겠습니다.

1. DelegateState란?

• Provider 패키지에서 상태 관리와 생명주기를 처리하기 위한 내부 클래스입니다. 이 클래스는 실제 상태 객체(실제 관리하는 값)을 관리하고, 상태 생명주기를 제어합니다.
• 또한 실제로 필요할 때까지 상태 객체 생성을 지연시키는 등 리소스 효율성을 향상시키도록 설계되어 있습니다.

2. 내부 구조

• 이번에도 실제 코드를 보면서 공부해봅시다.

  // Provider 패키지 내부에서 꺼내옴 (간략히)
  class _DelegateState<T> {
  // 상태 값 저장
  T? _value;
  bool _hasValue = false;
  
  // 값에 접근하는 방법, getter사용
  bool get hasValue => _hasValue;
  T get value {
    if (!_hasValue) throw StateError('대충 값 없다는 내용');
    return _value as T;
  }
  
  // 상태 업데이트, 값을 저장해줌!!
  void update(T newValue) {
    _value = newValue;
    _hasValue = true;
  }
  
  // 상태 폐기
  void dispose() {
    // 리소스 정리 로직
    _hasValue = false;
    _value = null;
  }
  }
  

- 구성은 생각보다 단순합니다. 그저 상태 객체의 생성 여부를 추적하고, dispose하면 리소스를 정리해주죠
- 즉, 정리하면 '값을 가지게 되는 컨테이너'이면서,  생명주기(lifecycle)를 관리해주는 놈입니다.


### 3. DelegateState의 작동 흐름

```dart
Provider<Counter>(
  create: (_) => Counter(),
  child: MyWidget(),
)

• 이런식으로 Provider를 등록하면, create메서드가 내가 원하는 값 객체(지금은 카운터죠)를 만듭니다.
• 그 후 DelegateState가 update()로 이 Counter 객체를 저장하고, 값을 보관해줍니다.
• 이후에 값을 찾는 메서드, 예를 들어서 context.read<Counter>() 같은 코드가 호출되면 이제서야 DelegateState가 내부에 저장된 Counter 객체를 value로 꺼내서 우리에게 보여주는거죠.
• 바로 이 DelegateState가 Element안에 붙어있게 되는데, _InheritedProviderScopeElement 내부를 보면 해당 코드가 있습니다.

class _InheritedProviderScopeElement<T> extends InheritedElement {
  final _DelegateState<T> _delegateState = _DelegateState<T>();
}

정리해보면, (1)엘리멘트 트리에 올라간 하나의 Provider마다 하나의 엘리멘트, _InheritedProviderScopeElement가 만들어지는데, ** (2) 여기에 하나의 DelegateState가 생성되고(내부 변수로), ** ** (3)이 친구가 Element와 값을 분리해서 element를 새로 짜더라도 값을 유지해줍니다.**

최종 정리 Provider의 데이터 변경 흐름

Provider가 어디에 배치되고, 어떻게 동작하는지를 알아봤고, 값이 어디에 저장되는지 까지 알아봤으니 이제 전체적인 흐름을 다시 보겠습니다.

값의 변경 흐름 추적하기

(1) 사용자 액션 발생 (값 입력이나 버튼 클릭 등등)

(2) Provider가 관리하는 객체(T value)가 notifyListeners() 호출

(3) _InheritedProviderScopeElement가 감지

(4) 필요하면 DelegateState에 새로운 값을 update() (DelegateState.update(newValue)를 통해 값만 갱신)

(5) 그러고 나서 notifyClients() 호출

(6) 의존성 걸린 Consumer들이 didChangeDependencies() 호출

(7) Consumer.build()를 통해 리빌드 발생

결론

Provider는 Element 트리를 기반으로 DelegateState에 상태를 저장하고, 변경을 감지하여 필요한 부분만 효율적으로 리렌더링하는 구조를 가지고 있습니다.

Consumer 위젯의 이해

• Consumer 위젯은 Provider 패키지에서 제공하는 위젯으로, Provider를 통해 제공되는 상태 변화를 감지하고 해당 상태를 사용하는 위젯을 다시 빌드하는 역할을 합니다.
• Consumer로 감싸진 위젯은 자신이 리슨(listen)하고 있는 데이터가 변경될 때마다 자동으로 다시 빌드됩니다. 이 위젯은 위젯 트리의 상위에 있는 Provider로부터 필요한 데이터를 얻어옵니다.  

  Consumer<MyModel>(
  builder: (context, model, child) {
    return Text(model.someValue);
  },
  )

• 컨슈머는 위와 같이 기본적으로 구성 되는데요, <MyModel>처럼 제네릭으로 어떤 타입의 데이터를 listen할지 구체적으로 명시 해야 합니다. 그러면 우리가 이전에 공부했던 위젯 트리에서 해당 제네릭의 프로바이더를 찾아서 필요한 데이터를 긁어오고, notifyListeners()의 알림도 들어줍니다.

그러면, 똑같은 타입의 프로바이더가 여러개면요?

• 기본적으로는 위젯 트리 내에서 더 가까운 프로바이더를 우선해서 가져옵니다.

  ChangeNotifierProvider<MyModel>( // 첫 번째 MyModel Provider
  create: (context) => MyModel(data: 'Data from Provider 1'),
  child: Builder(
    builder: (context) {
      return ChangeNotifierProvider<MyModel>( // 두 번째 MyModel Provider (더 가까움)
        create: (context) => MyModel(data: 'Data from Provider 2'),
        child: Consumer<MyModel>(
          builder: (context, myModel, child) {
            return Text(myModel.data); // Data from Provider 2가 표시
          },
        ),
      );
    }
  ),
  );

  하지만 우리가 알고싶은건 이런게 아니죠, MultiProvider로 같이 꽂아버리면 어떻게 될까요?

MultiProvider(
  providers: [
    Provider<MyModel>(create: (_) => MyModel(data: '1번타자')),
    Provider<MyModel>(create: (_) => MyModel(data: '2번타자')),
  ],
  child: MyWidget(),
);

• 이런 상상을 하셨다면, 아래같은 에러 부터 보게 됩니다. Error: Multiple providers of the same type found at the same level in the widget tree. 예외는 프로바이더를 만드신 선배님들이 처리했으니 안심하라구!

• 즉, 같은 타입의 프로바이더는, 위젯트리의 같은 위치에 중복 배치가 불가능하며 필수적으로 레벨을 분리해야 하기 때문에, '더 가까운 놈'을 찾는다고만 생각하시면 됩니다.

Consumer 위젯의 구성

• 다음은 provider패키지의 src내에 있는 Consumer.dart를 일부 발췌한 것 입니다. Consumer2~6도 있지만 이건 나중에 ProxyProvider랑 같이 보는게 좋을 거 같아요.

  class Consumer<T> extends SingleChildStatelessWidget {
  /// {@template provider.consumer.constructor}
  /// Consumes a [Provider<T>]
  /// {@endtemplate}
  Consumer({
    Key? key,
    required this.builder,
    Widget? child,
  }) : super(key: key, child: child);
  
  /// {@template provider.consumer.builder}
  /// Build a widget tree based on the value from a [Provider<T>].
  ///
  /// Must not be `null`.
  /// {@endtemplate}
  final Widget Function(
    BuildContext context,
    T value,
    Widget? child,
  ) builder;
  
  @override
  Widget buildWithChild(BuildContext context, Widget? child) {
    return builder(
      context,
      Provider.of<T>(context),
      child,
    );
  }
  }

• 생성자 부터 볼까요? builder함수를 필수적으로 전달 받아야 하며 builder 함수는 세 개의 파라미터를 받습니다. 우리가 제시할 프로바이더의 타입<T>을 명시해주고, ChangeNotifier에서 notifyListeners()가 호출되면, 해당 Provider를 리슨하는 모든 Consumer 위젯의 builder 함수가 실행됩니다.

• child와 buildWithChild라는, 위에서 설명하지 않은 파라미터와 메서드가 보입니다. child는 Provider의 데이터 변경에 영향을 받지 않고 리빌드 되지 않는 위젯이며, 아래같이 전달 하는 것도 가능합니다.

  Consumer<MyModel>(
  builder: ((context, value, child) {
    return Column(
      children: [child!, Text("child를 이렇게 사용할 수 있어요.")],
    );
  }),
  child: Text("Consumer의 child 파라미터"),
  ),

• 마찬가지로 buildWithChild는 부모인 SingleChildStatelessWidget의 추상 메서드를 구현한 것이며, 개발자는 대부분 생성자를 사용하고 이 메서드를 직접 호출하지는 않습니다. Provider와의 상호작용, 데이터 가져오기, child 위젯 처리 등의 복잡한 로직을 buildWithChild 내부에 캡슐화 한 것입니다.

Consumer 위젯이 부분적으로 리빌드 되는 이유

• 부분적인 리빌드란 전체 화면이나 위젯 트리를 다시 빌드하는 대신, 상태가 변경된 특정 부분의 UI만 업데이트하는 것을 말 합니다. 이것은 데이터 변경이 잦은 서비스를 만들 때,UI성능 최적화에 매우 중요한 역할을 수행합니다.
• 예를 들어서 StatefulWidget에서 setState메서드를 호출하면 일반적으로 해당 위젯 자체와 그 자식 위젯들이 모두 다시 빌드되는 반면, Consumer 위젯을 사용하면 상태 변화에 의존하는 특정 위젯만 선택적으로 다시 빌드할 수 있습니다. 즉, Consumer 위젯으로 특정 위젯을 감싸면, 해당 위젯만이 Provider의 상태 변화에 반응하여 다시 빌드됩니다.
• 그러면 왜 리빌드 되는걸까요? Consumer의 builder메서드 자체가 직접 Provider의 데이터 변경을 감지하는 것은 아닙니다. Consumer 위젯 내부의 buildWithChild 메서드, 더 정확히는 그 안의 Provider.of(context)가 데이터 변경 감지와 builder 함수 호출을 담당합니다.
• of메서드는 context.dependOnInheritedWidgetOfExactType을 캡슐화 한 것이니 넘어가고, 중요한 것은 윗 부분에 언급한 buildWithChild 메서드 내에서 Provider.of(context)가 호출된다는 것 입니다. 이 다음은 Provider의 기본 동작과도 같죠? 위젯 트리에서 가장 가까운 Provider를 찾으며, 그것이 ChangeNotifierProvider면 ChangeNotifier의 addListener를 호출하여, ChangeNotifier의 데이터 변경을 구독(subscribe) 합니다.
• Provider.of(context)는 ChangeNotifier의 리스너 중 하나이므로, 데이터가 바뀌어서 notifyListeners() 호출을 받으면 Consumer 위젯을 rebuild시킵니다. 그러면 마지막으로 buildWithChild는 이 새로운 데이터와 함께 builder 함수를 호출합니다.

실제로 부분만 리빌드가 되는가?

• stateful위젯으로 리빌드마다 카운트를 해주는 기능을 붙여서, Provider의 동작과 전체 스크린의 rebuild가 별도로 일어나는지 확인해보겠습니다.

• 아래 위젯은 두 가지 기능을 합니다. ** 1. 전체 위젯의 리빌드 추적:**

  • rebuildCount 변수를 통해 전체 MyHomePage 위젯이 리빌드되는 횟수를 추적합니다.

  2. Consumer를 사용한 부분 리빌드:

  • 카운터 값 표시를 Consumer로 감싸놨으며, CounterProvider의 상태가 변경될 때만 해당 부분이 리빌드됩니다.

class MyHomePage extends StatefulWidget {
  MyHomePage({super.key});

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  int rebuildCount = 0;

  @override
  Widget build(BuildContext context) {
    rebuildCount++;
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: Text("current rebuild count is ${rebuildCount}"),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text("current rebuild count is ${rebuildCount}"),
            ElevatedButton(
              onPressed: () {
                setState(() {});
              },
              child: const Text('rebuild screen'),
            ),
            const Text(
              '현재 카운트:',
              style: TextStyle(fontSize: 20),
            ),
            Consumer<CounterProvider>(
              builder: (context, counter, child) {
                return Text(
                  '${counter.count}',
                  style: const TextStyle(
                      fontSize: 40, fontWeight: FontWeight.bold),
                );
              },
            ),
            const SizedBox(height: 20),
            Row(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                ElevatedButton(
                  onPressed: () {
                    context.read<CounterProvider>().decrement();
                  },
                  child: const Text('-'),
                ),
                const SizedBox(width: 20),
                ElevatedButton(
                  onPressed: () {
                    context.read<CounterProvider>().increment();
                  },
                  child: const Text('+'),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

  <img src="https://velog.velcdn.com/images/s_soo100/post/fd31f47f-6b03-448e-acfa-8398fc80dc1d/image.gif" width="50%"/>

• rebuild screen 버튼을 누르면 전체 위젯이 리빌드되어 rebuildCount가 증가합니다. 하지만 + 또는 - 버튼을 눌러 카운터 값을 변경할 때는 Consumer 내부의 Text 위젯만 리빌드되고, 전체 위젯은 리빌드되지 않습니다.

Selector 위젯의 개요, 강점

• Selector 위젯은 Provider 패키지에서 제공하는 또 다른 위젯으로, Provider의 데이터 중 특정 부분만 리슨하고 해당 부분이 변경될 때만 위젯을 리빌드하는 데 사용됩니다
• Selector는 Consumer에 비해 더욱 세밀한 리빌드 제어를 제공하여 성능 최적화에 유용합니다 위젯이 Provider의 전체 데이터가 아닌 특정 부분에만 의존하는 경우, Selector를 사용하면 불필요한 리빌드를 방지할 수 있습니다. 엄청 테크니션한 느낌이 들죠?
  • 예를 들어 햄버거, 감자튀김, 콜라를 모두 한 모델에서 관리하고 있다고 가정하고, 남은 콜라의 양을 표시하는 위젯이 하나 있다고 하겠습니다. Consumer를 사용하면 감자튀김을 먹어서 감자튀김 양은 변했지만 콜라 양은 전혀 변하지 않았는데 리빌드를 강제한다면, Selector는 콜라를 마셨을 때만 위젯을 리빌드 해 줍니다.

Selector<MyModel, String>(
  selector: (context, model) => model.specificValue,
  builder: (context, value, child) {
    return Text(value);
  },
)

• 생성자를 보며 설명하자면, MyModel까지는 Consumer와 동일합니다. 그 뒤에 붙는 String이 내가 MyModel안에서 주시할 데이터 타입 입니다. 그리고 그 타입의 값을 selector: (context, model) => model.specificValue 형태로 콕 찝어서 골라놓고, 이 값이 변하는지만 예의주시 합니다.

Selector의 심화 사용

• Selector 위젯은 shouldRebuild라는 콜백 함수를 쥐어 줄 수 있습니다. 이것은 Selector의 핵심 기능 중 하나로, rebuild 에 조건을 추가할 수 있는 기능입니다.

• selector 함수가 반환하는 값이 변경되었을 때, 실제로 UI를 rebuild 할 필요가 있는지를 추가적으로 판단하는 역할을 합니다.

  예를 들어서, 감자튀김의 갯수를 표시하고 있다고 해볼까요? 중요한 것은 갯수이지, 감자튀김 각각의 사이즈나 눅눅해진 정도가 아니겠죠? 이 경우 아래처럼 구현 할 수 있습니다.

Selector<MyModel, List<int>>(
  selector: (context, model) => model.potato,
  shouldRebuild: (previous, next) => previous.length != next.length, 
  // 리스트의 길이가 변경된 경우에만 rebuild
  builder: (context, numbers, child) {
    return Text('감자튀김 ${numbers.length}개 남음');
  },
)

• 위의 Selector는 배열의 길이가 변경될 때만 리빌드 되며, 내부요소가 변경되더라도 길이가 같다면 리빌드 되지 않습니다.
• 요소가 변경된 건 어떻게 아냐구요? Selector는 DeepCollectionEquality를 사용해서 요소 변경도 반응하게 설계 되었습니다.

Read와 Watch등 다른 상태 소비(consume)방식과의 비교

• Provider 패키지에서는 Consumer와 Selector 외에도 다양한 방식으로 상태에 접근하고 사용할 수 있습니다. '소비(consume)'한다고 표현하기도 합니다. 그리고 프로바이더는 read, watch, Consumer, Selector라는 네 가지 방식을 제공합니다. 각 방식은 상태를 접근하고 UI를 업데이트하는 방식과 성능에 미치는 영향이 다른데, 쉽게 한번 표로 보겠습니다. (올려놓고 보니 잘 안보이는거 같네요..)

간단히 정리하면 아래와 같으며, 내가 지금 사용하고자 하는 데이터의 특성에 맞춰서 전략적으로 사용해 보면 좋겠습니다 :)

• context.read(): 상태를 한 번만 읽고, 변경 사항을 감지하지 않습니다.
• context.watch(): 상태를 읽고, 변경 사항을 감지하여 UI를 업데이트합니다.
• Consumer: 상태를 읽고, 변경 사항을 감지하여, builder 함수를 통해 UI의 일부분만 업데이트합니다.
• Selector<T, S>: 상태를 읽고, 특정 부분의 변경 사항만 감지하여, builder 함수를 통해 UI를 업데이트합니다.

• 이전 시간에는 Provider를 이루고 있는 Inherited Widget의 구성과 해당 위젯으로 상태관리를 하는 방법에 대해 알아보았습니다.

• 이번 시간에는 Provider가 Inherited Widget에 추가한 기능, 자동 화면 리빌드를 도와주는 notifyListeners() 메서드에 대해서 알아보려고 합니다.

• 그러기 위해서는 ChangeNotifierProvider와 ChangeNotifier라는 두 가지 클래스를 살펴보려고 합니다.

ChangeNotifierProvider

class ChangeNotifierProvider<T extends ChangeNotifier?>
    extends ListenableProvider<T> {

  ChangeNotifierProvider({
    Key? key,
    required Create<T> create,
    bool? lazy,
    TransitionBuilder? builder,
    Widget? child,
  }) : super(
          key: key,
          create: create,
          dispose: _dispose,
          lazy: lazy,
          builder: builder,
          child: child,
        );

// ...생략
}

• ChangeNotifierProvider는 가장 흔하게 쓰는 Provider의 위젯입니다. 아마 대부분 사용해 보셨을거에요. Provider의 상태 관리 기능과 ChangeNotifier의 자동 화면 리빌드가 함께 붙어있죠. 이는 아래 구조로 상속되어 있습니다.

  InheritedProvider -> ListenableProvider ---> ChangeNotifierProvider

  그리고 ChangeNotifierProvider 클래스는 ChangeNotifier의 하위 타입인<T extends ChangeNotifier?>를 반환합니다.

  InheritedProvider 기반으로 상태 관리를 해주며, ChangeNotifier.notifyListeners가 호출 될 때 마다 의존성이 있는 위젯들을 모두 다시 빌드합니다.

  ** 즉, 값을 감시하다가 값의 변동이 감지되면 build()함수를 호출합니다.**

notifyListeners()?

• Provider라이브러리의 notifyListeners()는 ChangeNotifier클래스를 기반으로 하는 상태 관리에서 핵심적인 역할을 합니다.

• ChangeNotifier는 Flutter의 Foundation 패키지에 포함된 클래스이며, 상태가 변경되었음을 구독자(Listeners)에게 알리는 역할을 수행합니다.

  그럼 우선 Flutter내부의 ChangeNotifier의 내부 구현 코드를 보겠습니다. (주석은 제외함)

  // flutter/lib/src/foundation/change_notifier.dart
  class ChangeNotifier {
    ObserverList<VoidCallback>? _listeners = ObserverList<VoidCallback>();
  
    void addListener(VoidCallback listener) {
      _listeners?.add(listener);
    }
  
    void removeListener(VoidCallback listener) {
      _listeners?.remove(listener);
    }
  
    @protected
    void notifyListeners() {
      if (_listeners != null) {
        for (final VoidCallback listener in List<VoidCallback>.from(_listeners!)) {
          listener();
        }
      }
    }
  }
  

  위의 코드에서 보면 _listeners 리스트에 리빌드가 필요한 위젯의 콜백 함수(listener)를 저장합니다. notifyListeners()가 호출되면, _listeners에 저장된 모든 리스너가 실행되면서 여기에 등록된 build()함수가 호출되며,addListener()를 호출한 순서대로(FIFO, First-In-First-Out) 실행됩니다. 이런 식으로notifyListeners()는 Flutter안에서 우리의 친구인setState()`처럼 동작하여 화면을 다시 그리도록 하는 핵심 메커니즘 입니다.

ChangeNotifier를 활용한 상태 관리

(이해하셨다면 여기는 예시 부분이니 안 보셔도 괜찮습니다)

• 이제 ChangeNotifier를 활용하여 실제로 상태를 관리하는 방법을 살펴보겠습니다. ChangeNotifierProvider를 이용하기 위해 우리는 ChangeNotifier를 상속하는 클래스를 만들어 "상태"를 관리하고, notifyListeners()를 호출하여 UI가 자동으로 갱신되도록 할 수 있습니다.
• 간결하게 봐야 하니 다시 counter 위젯으로 해볼게요.

1. ChangeNotifier를 상속한 모델 클래스 생성

이전 시간에 만든 counter모델 클래스와 동일합니다.

import 'package:flutter/material.dart';

class CounterModel extends ChangeNotifier {
  int _count = 0;

  int get count => _count;

  void increment() {
    _count++;
    notifyListeners(); // 값 변경 알림~~
  }
}

• counter가 지겨워도 이만한 예시가 없습니다. 위 코드에서 CounterModel은 ChangeNotifier를 상속받고 있으며, 내부적으로 _count 상태를 관리합니다. increment() 메서드를 호출하면 _count 값을 증가시키고, notifyListeners()를 호출하여 UI가 변경되었음을 알립니다.

2. ChangeNotifierProvider로 모델을 제공(Provide)

• 자 인제 ChangeNotifierProvider를 사용하여 CounterModel을 위젯 트리에 등록하고, UI에서 이를 사용해 보겠습니다.

  // main.dart
  import 'package:flutter/material.dart';
  import 'package:provider/provider.dart';
  import 'counter_model.dart'; // 방금 만든 모델 클래스
  

void main() { runApp( ChangeNotifierProvider( create: (context) => CounterModel(), child: MyApp(), ), ); }

class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return MaterialApp( home: CounterScreen(), ); } }

class CounterScreen extends StatelessWidget { @override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: Text("Provider 상태 관리")), body: Center( child: Column( mainAxisAlignment: MainAxisAlignment.center, children: [ Consumer( builder: (context, counter, child) { return Text( "현재 카운트: ${counter.count}", ); }, ), ElevatedButton( onPressed: () { context.read().increment(); }, child: Text("카운트 증가"), ), ], ), ), ); } }

- 위 코드를 보면, ChangeNotifierProvider가 CounterModel을 생성하여 앱의 위젯 트리에 제공하고 있습니다.
그리고 `Consumer<CounterModel>`을 사용하여 count 값이 변경될 때마다 해당 부분만 다시 빌드됩니다.
- increment호출에 `.read()`메서드를 사용하고 있는데요, `context.watch<T>()`는 상태 변경 시 UI를 리빌드하고, `context.read<T>()`는 상태 변경을 감지하지 않고 값을 가져옵니다.
- 함수 호출시 onPressed 내부에서 `.watch()`메서드를 사용하면버튼 자체가 상태 변경을 감지하여 불필요하게 다시 빌드될 가능성이 있습니다. 이 메서드는 값(상태)을 감시해야 할 때만 써주세요!


### notifyListeners()가 없으면 어떻게 될까?
- 그렇다면 만약 `notifyListeners()`를 호출하지 않는다면 어떤 일이 일어날까요?
CountModel에서 `notifyListeners()`를 주석 처리 해보겠습니다.
```dart
class CounterModel extends ChangeNotifier {
  int _count = 0;

  int get count => _count;

  void increment() {
    _count++;
    // notifyListeners(); 호출하지 않음
  }
}

• 이렇게 하면 increment()가 호출되어 _count 값이 증가해도 UI는 업데이트되지 않습니다. 즉, Provider를 사용해도 상태가 변경되었음을 알리지 않으면 화면이 리빌드되지 않습니다.

정리

1. notifyListeners()는 ChangeNotifier에서 상태가 변경되었음을 위젯 트리에 알리는 역할을 합니다.
2. ChangeNotifierProvider를 사용하면 ChangeNotifier 객체를 위젯 트리에 제공할 수 있습니다.
3. notifyListeners()는 상태 변경시 ChangeNotifier안의 listener 콜백들을 순차적으로 실행합니다. (이 때에 화면도 리빌드 됩니다)

🚀Provider pub dev 링크 🚀Provider github repo 링크 🚀InheritedWidget Flutter 공식문서 링크

뿌리를 찾아서, InheritedWidget

• 프로바이더를 맨 처음 공부하며 이런 이미지를 많이 봤을 것입니다. 위젯 트리에서 각자 멀리 떨어진 위젯들이 값을 공유하고, update되면 알려줄 수 있는 상태관리 기능이 프로바이더의 핵심이기 때문입니다.

• 이런 WidgetTree 의 상위 위젯들에 접근하여 데이터를 가져오게 할 수 있도록 하는 근간이 바로 Inherited Widget입니다.

• Provider 라이브러리의 다양한 Provider위젯들은 모두 InheritedWidget를 베이스로 제작 되었습니다. 그리고 InheritedWidget은 ProxyWidget을 상속하고 있는 추상 클래스인데, 몇몇 중요한 특징을 가지고 있습니다.

  1. 상태를 하위 위젯 트리에 전달
  2. BuildContext의 dependOnInheritedWidgetOfExactType() 메서드를 사용해 하위 위젯에서 해당 위젯을 찾고 상태를 구독
  3. updateShouldNotify를 오버라이드하여 상태가 변경될 때 하위 위젯들에게 알릴지 여부를 결정

• 자동으로 화면을 리빌드하는 부분만 제외하면 Provider의 기본 기능과 동일합니다.
  InheritedWidget도 마찬가지로 위젯 트리의 상단에 배치해서 그 하위 위젯들에게 상태를 공유하는 역할을 하기 때문입니다.

  이제 Flutter를 열어 InheritedWidget의 코드를 보자. (보기 좋게 주석은 모두 제외하였음)

  // flutter/lib/src/widgets/framework.dart
  abstract class InheritedWidget extends ProxyWidget {
  const InheritedWidget({ super.key, required super.child });
  
  @override
  InheritedElement createElement() => InheritedElement(this);
  
  @protected
  bool updateShouldNotify(covariant InheritedWidget oldWidget);
  }

• override해 온 updateShouldNotify 메서드는 InheritedWidget이 가진 데이터가 변경되었을 때 그것이 기존의 데이터와 같은지 비교하고, 다를 경우에만 notify를 해줍니다.

  그리고 InheritedWidget의 실제 인스턴스이자 렌더링과 업데이트를 담당하는, InheritedElement를 만들어주는 createElement()메서드가 있습니다.

  그렇다면 부모를 확인했으니 우리도 Provider를 만들 수 있지 않을까요?

InheritedWidget으로 상태 관리하기

• provider에 대해서 초보자들이 질문하면 가장 많이 받는 답변이 하나 있습니다. 바로 "카운터 위젯을 Provider로 짜신 다음에 Flutter 기본 프로젝트랑 뭐가 다른지 비교해보세요!" 라는 말인데, (나 때는 그랬다) 우리도 Provider 라이브러리를 열어 보기 전에 InheritedWidget을 가지고 똑같은 일을 해보겠습니다.

• 우선 InheritedWidget으로 카운터를 만들겠습니다.

  숫자를 담는 count 변수와, count를 1씩 증가시키는 increment 함수만 가지고 있도록 단순하게 구성했다. 그리고 InheritedWidget은 하나의 자식 Widget을 받는습니다.

// MyInheritedWidget.dart
class MyInheritedWidget extends InheritedWidget {
  final int count;
  final VoidCallback increment;

  MyInheritedWidget({
    Key? key,
    required this.count,
    required this.increment,
    required Widget child,
  }) : super(key: key, child: child);

  @override
  bool updateShouldNotify(MyInheritedWidget oldWidget) {
    return oldWidget.count != count;
  }
}

• 이제 이 MyInheritedWidget을 담은 Provider를 만듭니다.

  // InheritedCounterProvider.dart
  class InheritedCounterProvider extends StatefulWidget {
  final Widget child;
  
  const InheritedCounterProvider({Key? key, required this.child})
      : super(key: key);
  
  @override
  _InheritedCounterProviderState createState() => _InheritedCounterProviderState();
  }
  

class _InheritedCounterProviderState extends State { int count = 0;

void increment() { setState(() { count++; }); }

@override Widget build(BuildContext context) { return MyInheritedWidget( count: count, increment: increment, child: widget.child, ); } }

- 자, 다 왔다. 이제 카운터를 보여줄 메인 페이지만 구성하면 됩니다.
```dart

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return InheritedCounterProvider(
      child: MaterialApp(
        title: 'Flutter Demo',
        theme: ThemeData(
          useMaterial3: false, 
        ), 
        home: InheritedHomePage(),
      ),
    );
  }
}

class InheritedHomePage extends StatelessWidget {
  const InheritedHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    final counterWidget =
        context.dependOnInheritedWidgetOfExactType<MyInheritedWidget>();

    return Scaffold(
      appBar: AppBar(title: Text('InheritedWidget Example')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('Counter: ${counterWidget?.count ?? 0}',
                style: TextStyle(fontSize: 24)),
            SizedBox(height: 20),
            ElevatedButton(
              onPressed: counterWidget?.increment,
              child: Text('Increment'),
            ),
          ],
        ),
      ),
    );
  }
}

InheritedWidget 구현 분석

• 이 구현의 포인트는 바로 BuildContext.dependOnInheritedWidgetOfExactType<T>() 메서드에 있으며, 이 메서드는 한 눈에 봐도 단어가 엄청 긴데, 'depend on inherited widget of "EXACT TYPE"', 즉, 상속된 위젯의 정확한 타입에 따라 달라진다. 라는 의미이며, 주석에는 이렇게 써있습니다.

  Returns the nearest widget of the given type T and creates a dependency on it, or null if no appropriate widget is found.

• 즉, 위젯트리에서 T 타입의 위젯 중 가장 가까운 것을 반환 해줍니다. 위의 코드에서는 MyInheritedWidget 타입을 찾아서 그 counter값과 increment함수를 사용했습니다. 이것은 Provider에서 .of()메서드의 동작과 동일합니다. 실제로 라이브러리를 열어보면 동일한 메서드를 사용하고 있습니다.

// provider/packages/provider/lib/src/provider.dart

...
static T of<T>(BuildContext context, {bool listen = true}) {
    ...
    final inheritedElement = _inheritedElementOf<T>(context);
    ...

    if (listen) {
      context.dependOnInheritedWidgetOfExactType<_InheritedProviderScope<T?>>();
    }
    ...
    final value = inheritedElement?.value;
    ...
    return value as T;
}

• 하지만 Provider와는 다르게 InheritedCounterProvider 위젯 코드 내에서 setState()를 호출해서 화면을 리빌드 하고 있습니다.

  또한 Provider는 Multi Provider, Proxy Provider등 다양하고 중요한 기능들을 미리 개발해서 제공하고 있습니다.

• 그러므로 위 코드는 단순히 Provider가 어떻게 만들어졌는지 파악하는 용도로 공부하면 좋을 것 같습니다.

  여기서 꼭 알아가야 할 포인트가 있다면 다음과 같습니다.

1. Provider의 부모인 InheritedWidget의 구성

• Flutter에서 상태를 하위 위젯에 전달하는 기본적인 위젯

• updateShouldNotify 메서드를 오버라이드하여 상태가 변경될 때 하위 위젯을 다시 빌드할지 결정

• context.dependOnInheritedWidgetOfExactType<T>()를 사용해 하위 위젯에서 접근 가능

  2. Widget Tree에서 InheritedWidget의 위치

• 보통 앱의 최상단 또는 특정 상태를 공유해야 하는 범위에 배치

• 그 하위 위젯들이 InheritedWidget의 데이터를 참조

  3. InheritedWidget을 통한 상태관리

  • 상태를 전달만 하는 역할이므로 직접적인 상태 변경 기능은 없음
  • StatefulWidget과 조합하여 상태 변경이 필요할 때 setState와 함께 사용
  • Provider는 InheritedWidget을 상속하여 이 부분을 보강하였음!

  다음 시간에는 본격적으로 Provider 라이브러리의 코드들을 열어보고 구성을 살펴보기로 하겠습니다.

• 확장(extends)기능은 코드를 재사용할 수 있는 좋은 기능이나, 클래스 간의 의존 관계를 만들기 때문에 가끔 문제를 일으키고는 합니다.
  
• Fragile Base Class Problem은 객체 지향 프로그래밍에서 발생하는 객체 지향 프로그래밍 시스템의 근본적인 아키텍처 문제로,
  부모 클래스의 변경이 자식 클래스에 side-effect를 발생시키는 현상을 말합니다.

예시 코드 1

class Parent {
  void methodA() {
    print("A");
    methodB();  // methodB 호출
  }

  void methodB() { 
    print("B");
  }
}

class Child extends Parent {
  @override
  void methodB() {
    super.methodB();  // 부모의 methodB도 호출
    print("Child's B");
  }
}

가장 쉬운 예시로 위 코드를 보겠습니다.
이 예시 코드에서 만약 부모 클래스의 methodA가 수정되어 methodB를 두 번 호출하도록 변경된다면 자식 클래스의 동작도 예상치 못하게 변경됩니다.
예를 들어 Child.methodA();를 호출한다면 Child는 알지 못하는 변경에 의해 본인의 methodB를 두 번 부르게 됩니다.
또는 이렇게 생각할 수 있습니다.
"Child의 methodB를 override 할 때, super.methodB를 호출하지 않고 새롭게 정의해서 쓰면 되는게 아닌가?"
이 경우 만약 Parent 클래스의 methodB를()가 중요한 검증 로직을 포함하고 있었다면 이를 호출하지 않으므로써 필수적인 알고리즘 단계를 건너뛰는 오류를 야기할 수 있으며, 이는 "계약 위반(Contract Violation)"이라는 새로운 문제가 발생하는 것 입니다.

예시 코드 2

class Parent {
  void validateBalance() {
    originMethod();
    checkNetwork();  // 나중에 추가된 필수 네트워크 체크
    print("checkNetwork후에 잔액 검증 하는 메서드");
  }

  void checkNetwork() { // 새로 추가된 필수 검증 메서드
    print("네트워크 상태 확인하는 메서드");
  }
}

조금 더 구체적인 예시는 "부모 클래스에 새로운 의존성이 추가되었을 때" 발생하는 문제 입니다.
Parent 클래스에 checkNetwork라는 새로운 의존성이 생겨버리면 Parent를 상속하는 많은 클래스들은 이를 알 수 없습니다.
이에 따라서 Child 클래스에서 side-effect가 발생하기 쉽습니다.

해결 방안

1. 템플릿 메서드 패턴 사용

abstract class Parent {
  // 템플릿 메서드 - final로 선언하여 오버라이드 방지
  final void methodA() {
    step1(); // 하위 클래스에서 구현
    if (shouldExecuteStep2()) {  // 선택적 기능을 제공하는 hook메서드
      step2();  // 하위 클래스에서 구현
    }
    _commonStep(); // 공통 기능은 접근 불가능하도록 
  }

  void step1(); // 추상 메서드 - 반드시 구현해야 함
  void step2() { // 선택적으로 구현 가능한 메서드 (훅 메서드)
    print("기본 step2 실행"); // 기본 구현을 제공하고 사용시 추가 구현
  }

  bool shouldExecuteStep2() { // 훅 메서드 - 실행 여부 결정
    return false;  // 기본값
  }

  void _commonStep() {  // private 메서드 - 변경 불가능한 공통 기능
    print("변경 불가능한 공통 기능 실행");
  }
}

// 구현 클래스 1
class Child1 extends Parent {
  @override
  void step1() {
    print("Child1의 step1 구현");
  }
}

// 구현 클래스 2
class Child2 extends Parent {
  @override
  void step1() {
    print("Child2의 step1 구현");
  }

  @override
  void step2() {
    print("Child2의 커스텀 step2 구현");
  }

  @override
  bool shouldExecuteStep2() {
    return true;  // step2 실행하도록 구현
  }
}

템플릿 메서드 패턴은 알고리즘의 구조를 메서드에 정의하고, 일부 단계를 하위 클래스에서 구현할 수 있도록 하는 패턴입니다.
알고리즘의 뼈대는 상위 클래스에서 정의하고, 일부 단계의 구현은 하위 클래스에 위임하는 형태입니다.
"템플릿"을 통해 알고리즘의 구조를 명확하게 하고 하위 클래스에서 수정 가능한 부분이 명확히 정의하기 때문에
공통 기능의 무결성이 보장되며 확장은 용이하되 기존 구조는 깨지지 않습니다. (패턴 자체에 대해서는 다른 글에서 더 자세히 다뤄보겠습니다)

2. 컴포지션 사용

class WithdrawValidator {
  void validate() {
    print("잔액 검증");
  }
}

class BankAccount {
  final WithdrawValidator validator; // 컴포지션으로, 상속이 아니라 내부변

  BankAccount(this.validator);

  void withdrawMoney() {
    validator.validate();
    processingWithdraw();
  }
}

컴포지션은 "has-a" 관계를 만드는 것으로, 상속("is-a" 관계) 대신 인스턴스를 내부에 포함시켜 사용하는 방식입니다.
상속과 달리 결합도가 매우 낮아 내부 구현 변경에 '덜'취약하며 테스트가 용이한 장점이 있습니다.

3. 인터페이스 정의

abstract class BalanceValidator {
  void validate();
}

class StandardValidator implements BalanceValidator {
  @override
  void validate() {
    print("표준 잔액 검증");
  }
}

class CustomValidator implements BalanceValidator {
  @override
  void validate() {
    print("커스텀 잔액 검증");
  }
}

BalanceValidator라는 부모 클래스의 구현을 포기하고 "인터페이스로 사용"하여 상세 구현을 모두 자식 클래스에서 한다면 해당 문제는 해결됩니다.

정리

• 상속은 강력한 기능이나 약점이 명확하며,Fragile Base Class Problem은 여러 명이 공동작업을 해야 하는 프로젝트 일수록 발생되기 쉽습니다.
• 상속에서 오는 고질적인 문제인 Fragile Base Class Problem를 피하기 위해서는 대신 위와 같은 설계 패턴을 사용하여 더 안전하고 유연한 구조를 만드는 것이 좋습니다.

빠르게 보는 modifier의 사용과 조합

• Dart의 주요 class modifier에는 abstract, final, sealed, base, mixin, interface 등이 있습니다. 에기에 class까지 해서 7개 키워드의 각 기능을 정리하면 아래와 같습니다. 생성자, 상속, 구현, 완전성 검사등의 유용한 기능들을 modifier를 사용해서 제한하거나 특정 상황에서만 동작하게 만들 수 있습니다. enum, typedef, extension, extension type 등에는 사용이 불가능합니다.

(공식문서의 Valid combinations)

기능의 한줄 설명

• construct: 클래스 인스턴스화
• extend: 다른 클래스를 부모로 상속
• implement: 인터페이스 메서드 구현
• mixin: 여러 클래스에 공통사용 가능한 기능을 추가
• exhaustive: 본인을 상속한 모든 하위 클래스를 처리하는 완전성 검사

각 기능들이 왜 중요한가요?

• 클래스 간의 관계와 동작을 정의하기 때문입니다. 객체 지향 프로그래밍(OOP) 에서 예를들어, 클래스의 확장과 구현은 OOP의 핵심 원리인 재사용성과 유연성을 실현하게 해줍니다.
  
  
• 확장(extends)은 기존 클래스를 상속하는 과정을 통해 이루어지는데,
  매번 기본 기능을 추가할 필요가 없어 코드의 재사용성을 올려주며, 기본 기능의 수정을 상위클래스에서 하면 상속자들에게 모두 반영되기 때문에 유지보수성이 좋다고 할 수 있습니다. (물론 여기서 발생되는 다른 문제들 또한 존재합니다)
  
  
• 구현(implements)은 구현자에게 인터페이스에 정의된 메서드 구현을 강제합니다.
  이는 OOP에서 다형성(polymorphism)을 지원하고, 일관된 동작을 제공하는 데 매우 유용합니다.
  이로 인해 클래스의 구성이 달라도 인터페이스가 같기 때문에 에러 없이 상호작용 할 수 있습니다.
  이는 상속과는 다른 방식으로 유연한 설계를 가능하게 해줍니다.

각 modifier의 원리와 사용구조

1. abstract(추상 클래스)

• abstract는 공통된 동작이나 기능을 여러 클래스에 제공하는 목적으로 사용됩니다.
  또한 클래스가 직접 인스턴스화될 수 없도록 만들며, 반드시 상속을 통해 구현해야 하는 메서드들을 정의하는 데 사용되며 각 하위 클래스는 필요에 따라 이를 확장하거나 수정할 수 있습니다.
• 하지만 모든 메서드를 추상화 해야 하는것은 아니며, 구현 메서드나 값 또한 포함할 수 있습니다.
• interface와 함께 사용할 수도 있습니다. 이 경우 굉장히 pure한 인터페이스를 만들 수 있습니다.

abstract class Animal {
  void makeSound(); // 추상 메서드
  void move() { // 구현 메서드
    print("move");
  }
}

class Dog extends Animal {
  @override
  void makeSound() {
    print('Woof!');
  }
}

2. final

• 변수에 사용하는 final 키워드와 달리 이는 상속을 방지하는 용도로 사용합니다.
  더이상 mixin이나 class가 상속되지 않도록 고정하며, abstract가 아니고 class로 만들었다면 인스턴스화는 가능합니다.

  final class Robot {
  void turnOn() {...}
  }
  

// class Gundam extends Robot {} // ERROR!! : Robot은 상속이 불가능합니다. Robot myRobot = Robot(); // 인스턴스화는 가능합니다.

## 3. sealed
- sealed 는 Dart 3.0에서 도입된 키워드로, 내 클래스를 같은 파일 안에서만 상속이 가능하도록 합니다.<br/>
즉, sealed 클래스를 상속하는 모든 하위 클래스는 같은 파일에 있어야 합니다.<br/>이를 통해 상속 계층을 더 엄격하게 관리할 수 있습니다.
- sealed 클래스를 상속받는 클래스는 enum과도 비슷하다고 생각 할 수 있습니다. 모든 하위 클래스를 포괄적으로 처리할 수 있는 `완전성(exhaustive)`을 제공하기 때문입니다.
  <br/>하위 클래스의 범위가 특정 파일 내(현재 파일 내)로 제한되기 때문에, 모든 확장 가능성을 알고 이를 처리할 수 있게 됩니다. 이를 통해 switch 구문이나 패턴 매칭에서 모든 하위 클래스를 반드시 처리할 수 있습니다.
- 정리하면 sealed는 코드의 안전성과 유지보수성을 극대화하는 기능입니다.
- 외부에서 직접 상속할 수 없는 클래스를 만들 때, sealed와 final이라는 두 가지 선택지가 주어집니다.<br/>이에 대한 비교는 별도의 글에서 다루도록 하겠습니다.

(sealed 예시코드는 역시 도형이 맛있다.)
```dart
sealed class Shape {}

class Circle extends Shape {}
class Square extends Shape {}

Shape shape = getShape();

switch (shape) {
  case Circle:
    // Circle 처리
    break;
  case Square:
    // Square 처리
    break;
  // 모든 하위 클래스를 처리하므로 오류 방지 가능
}

4. base

• 클래스 또는 믹스인 구현의 상속을 강제하는 모디파이어 입니다.
• base 클래스는 상속받을 수는 있지만 구현(implement)하거나 mixin사용은 불가능합니다.(명시적인 상속 제한이라 부릅니다.)
• 파일 경계를 넘어 상속이 가능하며, 상속받는 모든 클래스는 base, final, sealed중 하나의 키워드를 표시해야 합니다. ```dart
• ----a.dart base class Vehicle { void moveForward(int meters) { // ... } }
• ----b.dart import 'a.dart';

// Can be constructed. Vehicle myVehicle = Vehicle();

// Can be extended. base class Car extends Vehicle { int passengers = 4; // ... }

// ERROR: Can't be implemented. base class MockVehicle implements Vehicle { @override void moveForward() { // ... } }

## 5. interface
- 본래 Dart에서는 Java등과 다르게 interface라는 별도의 키워드가 없었으며 모든 클래스는 자동으로 인터페이스 역할을 했습니다.<br/>interface 키워드는 Dart 3.0 업데이트와 함께 추가되어 이를 통해 명시적으로 인터페이스로 사용할 클래스를 정의할 수 있습니다. 
- 이 키워드는 클래스 자체를 인터페이스로 사용하도록 구성하여 implements를 통해 내부 메서드들을 구현하도록 강제합니다.
- 상속을 방지하여 내부 로직이 의도치 않게 변경되는 것을 방지하고 `fragile base class problem`를 줄일 수 있습니다.(이 또한 다른 글에서 다루겠습니다)
- 추상 메서드가 아니라 구현 메서드도 내부에 포함할 수 있습니다.
```dart
interface class Vehicle {
  void moveForward(int meters) {
    // ...
  }
}

// 생성자 사용 가능
Vehicle myVehicle = Vehicle();

// ERROR!!: 상속 불가
class Car extends Vehicle {
  int passengers = 4;
  // ...
}

// 구현 가능
class MockVehicle implements Vehicle {
  @override
  void moveForward(int meters) {
    // ...
  }
}

6. mixin(믹스인)

• 상속, 구현과는 별개로 여러 클래스 위계에서 재사용 될 수 있는 코드를 만듭니다.
  특정 클래스 상속이 불가능하며 생성자 선언도 불가능합니다. 마찬가지로 자체 인스턴스 화도 불가능합니다.
• 기능을 재사용하고 코드 중복을 줄이는데 큰 도움을 주며,
  여러 클래스에서 사용할 내용을 하나의 mixin에서 한 번에 제공하도록 설계되어 있습니다.
• with 키워드로 클래스 명 혹은 부모 클래스 명 뒤에 기재하며, 복수 사용이 가능합니다.
• 추상 메서드/추상 변수를 가질 수 있으며, 믹스인 사용시 꼭 이를 구현해야 합니다.
• mixin class로 구성해서 상속과 믹스인 두 가지 용도로 사용하는 것 또한 가능합니다.

  mixin class Both {}
  

class UseAsMixin with Both {} class UseAsSuperclass extends Both {}

# modifier combinations
- modifier는 여러개를 조합해서 붙일 수 있습니다. 그중 아래 표의 조합만이 가능하며, 이는 클래스의 기능을 더 명확하게 제한해줍니다.
- 아까보다 조금 더 긴 표를 보겠습니다. 아래 조합만 valid하며, 표기되지 않은 조합(mixin abstract등)은 사용이 불가능 합니다.
- 이 조합을 통해 우리는 각각의 클래스가 상속, 구현, 믹스인이 가능한지 불가능한지를 정의합니다.<br/>
abstract interface class등을 통해 구현만 가능한 `pure`한 인터페이스를 정의하는 것도 가능합니다.
  <br/>




| Class Type                    |Construct | Extend | Implement | Mixin | Exhausive |
|-------------------------------|------------|---------------|------------------|--------------|--------|
| `class`                       | ✔          | ✔             | ✔                |              |        |
| `base class`                  | ✔          | ✔             |                  |              |        |
| `interface class`             | ✔          |               | ✔                |              |        |
| `final class`                 | ✔          |               |                  |              |        |
| `sealed class`                |            |               |                  |              | ✔      |
| `abstract class`              |            | ✔             | ✔                |              |        |
| `abstract base class`         |            | ✔             |                  |              |        |
| `abstract interface class`    |            |               | ✔                |              |        |
| `abstract final class`        |            |               |                  |              |        |
| `mixin class`                 | ✔          | ✔             | ✔                | ✔            |        |
| `base mixin class`            | ✔          | ✔             |                  | ✔            |        |
| `abstract mixin class`        |            | ✔             | ✔                | ✔            |        |
| `abstract base mixin class`   |            | ✔             |                  | ✔            |        |
| `mixin`                       |            |               | ✔                | ✔            |        |
| `base mixin`                  |            |               |                  | ✔            |        |