안녕하세요, 1편에서 '운명 분석 엔진' 이야기를 들려드린 지 벌써 시간이 꽤 흘렀네요. 오랜만에 인사드립니다. 990원이라는 가격에 반신반의하며 올렸던 서비스에 감사하게도 7,000명이라는 유저분이 다녀가셨고, 그 지표들을 분석하며 다음 스텝을 준비하느라 꽤 바쁜 시간을 보냈습니다.

0. 근황: 7,000번의 데이터로 검증한 가설

1편을 작성할 당시 제 마음은 "내가 만든 알고리즘이 시장에서 통할까?"라는 호기심이 컸습니다. 990원이라는 가격은 수익보다는 '최소한의 결제 허들'을 넘기는지 확인하기 위한 장치였죠.

결과적으로 7,000명이 넘는 유저가 유료 결제를 했습니다. 별다른 마케팅 예산 없이 SEO와 커뮤니티 공유만으로 일궈낸 수치라 더 의미가 있었습니다. 이 과정을 통해 한 가지 확실한 비즈니스 인사이트를 얻었습니다.

"사람들은 자기 자신에 대한 이야기, 그리고 남에게 보여주고 싶은 콘텐츠에 기꺼이 지갑을 연다."

1. 사주 다음은 왜 '관상'인가?

인생스포(사주)를 운영하며 유저들의 행동 패턴을 분석해 보니, 다음 스텝은 자연스럽게 '이미지'로 향했습니다. 관상은 사주와 같은 결의 도메인이지만 개발자로서 매력적인 UX 포인트가 몇 가지 더 있었습니다.

• 압도적으로 낮은 진입 장벽: 사주는 태어난 '시(時)'를 모르면 정확도가 떨어지지만, 관상은 셀카 한 장이면 끝납니다. 3초면 인풋이 완성되죠.
• 공유의 트리거: 텍스트 위주의 사주 결과보다, '내 얼굴'과 '캐릭터 이미지'가 결합된 결과물이 SNS(Threads, X 등)에서 훨씬 더 강력한 전파력을 가집니다.

그래서 만들었습니다. '보이지 않는 운명'에 이어 '보이는 운명'을 분석하는 서비스, 관상스포입니다.

2. 셀카 한 장에서 관상 데이터를 뽑아내는 과정

단순히 "AI가 사진 보고 말해줍니다"라고 하면 기술적으로 재미가 없죠. 관상의 신뢰도를 높이기 위해 설계한 데이터 추출 파이프라인을 소개합니다.

① 사진에 얼굴이 있긴 한 거야? — 얼굴 감지

사용자가 사진을 올리면 가장 먼저 "이 사진에 얼굴이 있는가"를 판단해야 합니다. 풍경이나 음식 사진이 올라와 서버 비용이 새나가는 것을 막기 위해 온디바이스 ML(On-device ML)을 활용했습니다. 서버 왕복 없이 브라우저에서 즉시 얼굴 유무를 판단하고 업로드를 제어합니다.

② 얼굴을 숫자로 바꾸기 — 관상학 지표 수치화

AI에게 사진만 던지면 "느낌적인 느낌"으로만 대답하는 문제가 발생합니다. "눈이 좀 큰 것 같네요" 같은 모호한 표현을 피하기 위해, 얼굴 위에 수백 개의 랜드마크 좌표를 찍고 관상학 프레임으로 수치화했습니다.

• 오관(五官): 눈썹, 눈, 코, 입, 귀의 형태와 비율 측정.
• 삼정(三停): 이마 / 눈코 / 코턱의 세로 비율 측정.

여기서 핵심은 '절대 길이'가 아닌 '비율'을 사용하는 것입니다. 그래야 카메라와의 거리나 사진 크기에 상관없이 일관된 분석 결과가 나옵니다.

③ AI에게 사진 + 수치를 함께 전달

이렇게 추출된 수치 데이터는 AI(Gemini)에게 사진과 함께 전달됩니다. 수치가 '앵커(Anchor)' 역할을 해주기 때문에, AI는 훨씬 구체적이고 근거 있는 해석을 내놓을 수 있습니다.

AS-IS (사진만): "눈이 큰 편이시네요." TO-BE (사진+수치): "눈꼬리가 위로 12도 가량 올라가 있어 날카로운 인상을 주지만, 눈의 세로 폭이 넓어 차가운 인상을 보완해 줍니다."

3. 기획의 핵심: 공유를 부르는 '소름 포인트'

개발자로서 서비스의 성능만큼 고민한 것이 '어떻게 하면 유저가 이 화면을 캡처하게 만들까?'였습니다. 관상스포의 리포트 구조는 철저히 이 '공유 트리거'에 집중했습니다.

• 숫자의 구체성: "성격이 밝네요"보다 "겉과 속의 괴리율 78%"라는 숫자가 훨씬 강력합니다. 사람들은 정량화된 수치에 반응하고, 이를 근거로 친구들과 대화를 시작합니다.
• 자극적인 키워드: '조심해야 할 빌런 관상'이나 '찰떡 궁합 동물상' 같은 섹션을 배치해, 혼자 보고 끝내는 것이 아니라 주변 지인들을 태그하거나 연인과 함께해보도록 유도했습니다.

4. 왜 하필 Gemini Flash인가?

비즈니스 측면에서 가장 중요한 것은 Unit Economics(건당 경제성)였습니다. 990원짜리 서비스에서 모델 호출 비용이 수익의 절반을 차지하면 지속 불가능하니까요.

• Cost-Efficiency: Gemini 1.5 Flash는 이미지 인지 능력이 뛰어나면서도 토큰당 비용이 압도적으로 저렴합니다.
• Native Multimodal: 별도의 Vision 모델을 거치지 않고 직접 이미지를 컨텍스트로 수용하기 때문에 지연 시간(Latency)을 획기적으로 줄일 수 있었습니다.
• Prompt Engineering: 수치가 포함된 프롬프트를 통해 "점술가 같으면서도 현대적인" 밸런스를 찾는 데 집중했습니다.

5. 마치며: 사이드 프로젝트는 '시리즈물'이다

인생스포를 만들지 않았다면 관상스포는 세상에 나오지 못했을 겁니다. 7,000명의 유저 데이터와 피드백이 있었기에 "사진 기반의 서비스가 더 확장성이 크겠다"는 확신을 가질 수 있었죠.

결국 사이드 프로젝트는 마침표가 아니라 다음 프로젝트로 연결되는 징검다리라고 생각합니다. 앞선 프로젝트에서 확보한 유저들이 다음 서비스의 마중물이 되고, 두 서비스가 서로 크로스셀링(Cross-selling)되는 구조를 만드는 경험은 1인 개발자로서 매우 값진 자산이 되었습니다.

과연 7,000명의 사주 유저들이 얼굴도 보여줄까요? 지표가 나오면 또 공유해 보겠습니다.

관상스포 구경하기: https://life-spoiler.com/face-spoiler

"개발자가 무슨 미신이냐" 하실 수 있겠지만, 로직을 파고들다 보니 이거... 완벽한 알고리즘과 데이터베이스의 세계였습니다.

그래서 만들었습니다. 라이프 스포일러 (Life Spoiler)

오늘은 이 서비스를 만들게 된 기술적 배경과 990원이라는 마이크로 BM(Business Model)을 설정한 이유를 회고 형식으로 공유합니다.

1. Tech Stack : 왜 Next.js + Supabase 인가?

빠른 MVP(Minimum Viable Product) 출시와 유지보수 편의성을 위해 '국밥 조합'을 선택했습니다.

• Frontend: Next.js (App Router)
• SEO 최적화는 기본이고, 정적인 텍스트 결과가 많은 사주 서비스 특성상 SSR(Server Side Rendering)의 이점을 최대한 살렸습니다.
• 결과 페이지의 로딩 속도를 줄여 사용자 이탈을 막는 데 주력했습니다.

• Backend & DB: Supabase
• 사이드 프로젝트의 영원한 친구. Auth 처리부터 DB 관리까지 백엔드 리소스를 획기적으로 줄여줬습니다.
• 자미두수의 방대한 별자리 데이터와 해석 데이터를 RDBMS 형태로 구조화하여 쿼리 속도를 최적화했습니다.

2. 도메인 로직 : 자미두수(紫微斗數)는 코딩이다

보통 사주(명리학)를 많이 보지만, 개발자 관점에서는 자미두수가 훨씬 매력적입니다. 명리학이 '기운'과 '조화' 같은 추상적인 느낌이라면, 자미두수는 별(Star)들의 배치(Layout)와 상호작용(Event Logic) 으로 이루어져 있기 때문입니다.

• Input: 생년월일시 (사용자 파라미터)
• Process: 100여 개의 별을 특정 궁(Position)에 배치하는 알고리즘 연산
• Output: 정확한 운명 데이터 도출

마치 복잡한 조건문이 얽힌 레거시 코드를 리팩토링해서, "너 이때 에러(사고) 터질 거야", "이때 트래픽(재물) 폭주할 거야" 라고 알려주는 모니터링 시스템과 비슷하다는 느낌을 받았습니다.

직접 제 데이터를 넣고 돌려봤을 때, 지난 20년의 굴곡이 정확히 매핑되는 걸 보고 소름이 돋아 배포를 결심했습니다.

3. Pricing : 왜 하필 990원인가?

시중 점술 서비스는 비쌉니다. (보통 1~3만 원) 하지만 저는 개발자답게 생각하기로 했습니다.

*"어차피 로직은 내가 짰고, 들어가는 건 서버비와 API 비용뿐인데?"*

SaaS 모델처럼 접근 장벽을 극단적으로 낮추고 싶었습니다. 트래픽(Traffic)이 곧 깡패라는 생각으로, 누구나 부담 없이 자신의 운명을 '디버깅' 해볼 수 있는 가격.

• 평생 총운: 990원
• 올해(2026) 신년 운세: 990원

커피 한 잔 값도 안 됩니다. 개발자분들이라면 아시겠지만, 이 가격은 사실상 마진보다는 "내 알고리즘이 얼마나 맞는지 테스트해보고 싶은 욕구"가 더 컸습니다.

4. 마치며 : 인생도 디버깅이 필요하다

우리는 코드를 짤 때 항상 예외 처리(Exception Handling)를 합니다. 그런데 정작 우리 인생에는 try-catch 문을 걸어두지 않고 살고 있진 않나요?

라이프 스포일러 는 여러분 인생의 로그(Log)를 미리 보여주는 서비스입니다. 미리 알면 대비할 수 있고, 피해 갈 수 있습니다.

개발자 동료 여러분, 심심하실 때 재미 삼아 접속해서 여러분의 2026년 Config 파일을 한번 열어보세요. 생각보다 소름 돋게 맞을지도 모릅니다.

👉 서비스 바로가기

들어가며

코드 다 짰어요. 이제 PR 올리면 끝…일 줄 알았죠. 근데 PR 단계에서 갑자기 일이 늘어납니다.

• “커밋 메시지 뭐라고 쓰지?”
• “PR 설명에 뭘 써야 하지?”
• “리뷰 달렸네… 또 수정해야 하나…”
• “코멘트 5개 달렸는데 하나씩 보기 귀찮아…”

가끔은 이런 생각도 들어요.

내가 개발을 하고 있는 건지, PR 매니저를 하고 있는 건지…

그래서 만든 게 /pr과 /apply-review입니다.

코드 작성 → PR 생성 → 리뷰 반영 이 전체 흐름을 명령어 두 개로 끝내버리는 자동화.

/pr이 하는 일: “PR 올리는 과정”을 통째로 줄이기

실행은 한 줄입니다.

/pr

하지만 내부적으로는 아래를 순서대로 처리합니다.

1. 변경 사항 분석 — git diff로 뭐가 바뀌었는지 파악
2. 커밋 메시지 생성 — 변경 내용을 요약한 메시지 작성
3. 커밋 실행 — 스테이징 → 커밋
4. 브랜치 푸시 — 원격 저장소로 push
5. PR 생성 — GitHub에 Pull Request 생성 (gh CLI 활용)

즉, 개발자는 “코드만 수정”하고 나머지 PR 관련 반복 작업은 /pr이 처리합니다.

커밋 메시지: 자동이지만 ‘의미 있게’ 만들기

자동 커밋 메시지라고 하면 걱정부터 들죠.

“Update file” “Fix bug” 이런 거 나오면 오히려 히스토리가 망한다…

그래서 저는 커밋 메시지를 규칙으로 강제했습니다.

1) Conventional Commits 형식 고정

<type>(<scope>): <description>

<body>

예시:

feat(auth): 카카오 로그인 기능 추가

- 카카오 OAuth 연동
- 토큰 저장 및 갱신 로직 구현
- 로그인 화면 UI 추가

이 형식의 장점은 딱 하나입니다. 커밋을 읽는 순간 변경의 성격이 보인다는 것.

2) 타입 자동 분류 (feat/fix/refactor…)

Claude가 변경 내용을 보고 타입을 고릅니다.

타입이 일관되면 릴리즈 노트 생성이나 변경 추적도 훨씬 편해져요.

3) 설명은 한글로 (팀 컨벤션 반영)

저희 팀은 한글이 더 빨리 읽혀서, 한글로 고정했습니다.

feat(api): 재시도 로직 추가

- 네트워크 에러 시 최대 3회 재시도
- 지수 백오프 적용 (1초, 2초, 4초)
- 타임아웃 설정 추가

이 부분은 팀 성향에 따라 영어로 바꿔도 되고, scope 규칙을 더 엄격히 해도 됩니다.

PR 설명: “리뷰어가 코드부터 열지 않게” 만드는 자동 생성

PR 본문은 팀 생산성에서 생각보다 큰 비중을 차지합니다. 본문이 빈약하면 리뷰어가 코드부터 열어서 맥락을 추측해야 하거든요.

/pr은 PR 본문도 템플릿 기반으로 생성합니다.

기본 템플릿 구조

## Summary
- 변경 사항 요약 (1-3 bullet points)

## Test plan
- [ ] 테스트 항목 1
- [ ] 테스트 항목 2

실제 생성 예시

## Summary
- 카카오 로그인 기능 추가
- 기존 Apple/Google 로그인과 동일한 인터페이스로 통합
- 로그인 화면에 카카오 버튼 추가

## Test plan
- [ ] 카카오 계정으로 로그인 성공 확인
- [ ] 토큰 만료 시 자동 갱신 확인
- [ ] 로그아웃 후 재로그인 정상 동작 확인
- [ ] 기존 Apple/Google 로그인 영향 없음 확인

이렇게 되면 리뷰어가 PR을 열자마자 “이 PR이 뭘 하는지”가 보이고, 테스트 플랜까지 있으니 질문이 줄어듭니다.

/apply-review: 리뷰 대응을 “작업”이 아니라 “반영”으로 만들기

PR 올리면 끝이 아니라, 이제 리뷰가 오죠.

- "이 함수 이름 좀 더 명확하게 바꿔주세요"
- "에러 핸들링이 빠진 것 같아요"
- "타입을 더 구체적으로 해주세요"
- "테스트 케이스 추가해주세요"

이걸 하나씩 열고, 파일 찾고, 수정하고, 커밋하고, 푸시하고… 리뷰 반영 자체가 일입니다.

그래서 /apply-review는 한 줄로 시작합니다.

/apply-review

/apply-review가 하는 일

1. 리뷰 코멘트 수집 — 현재 브랜치의 PR에서 모든 코멘트를 가져옴
2. 코멘트 분석 — 각 코멘트가 요구하는 변경을 분류
3. 코드 수정 — 요청 내용대로 반영
4. 반영 커밋 생성 — 리뷰 반영 커밋 작성 (요청자 정보 포함)
5. 푸시 — 원격 브랜치에 재푸시

즉, 리뷰어의 말이 “할 일 목록”으로 남는 게 아니라 코드 변경으로 바로 이어지게 하는 게 목표예요.

리뷰 반영 예시: 코멘트가 코드로 변환되는 순간

Before: 리뷰 코멘트

@reviewer: 이 함수 에러 핸들링이 없네요. try-catch로 감싸주세요.

After: 코드 수정

// Before
async function fetchUser(id: string) {
  const response = await fetch(`/users/${id}`);
  return response.json();
}

// After
async function fetchUser(id: string) {
  try {
    const response = await fetch(`/users/${id}`);
    if (!response.ok) {
      throw new ApiError(response.status, "Failed to fetch user");
    }
    return response.json();
  } catch (error) {
    if (error instanceof ApiError) throw error;
    throw new ApiError(500, "Network error");
  }
}

자동 생성된 커밋

fix(api): 에러 핸들링 추가

- fetchUser 함수에 try-catch 추가
- 응답 상태 코드 검증 추가
- 네트워크 에러 처리 추가

Requested by @reviewer

여기서 제가 좋았던 포인트는 이거예요.

• “무슨 변경을 했는지”가 커밋 메시지에 남고
• “누가 요청했는지”까지 기록되니 나중에 히스토리 추적이 쉬워집니다.

리뷰 타입별로 ‘다르게’ 처리합니다

리뷰는 전부 “고쳐주세요”가 아니죠. 그래서 /apply-review는 코멘트를 분류해서 행동을 달리합니다.

1) 코드 수정 요청

"변수명 더 명확하게 바꿔주세요"
→ 코드 변경 + 커밋

2) 질문

"이 로직이 왜 필요한가요?"
→ 코드 주석 추가 또는 PR 코멘트로 설명

3) 제안

"이렇게 분리하면 어떨까요?"
→ 적용 여부 판단 후 반영하거나, 거절 사유를 남김

4) 승인(LGTM)

"LGTM!"
→ 액션 없음

결과적으로 “리뷰를 처리하는 방식” 자체가 표준화돼서 리뷰 대응이 훨씬 덜 피곤해집니다.

워크플로우 전체 그림: 5개 명령어의 완성형

이 시리즈에서 소개한 명령어들을 한 번에 연결하면 이렇게 됩니다.

/spec user-notification     # 1) 명세 기반 구현
/create-jest                # 2) 테스트 자동 생성
/w-context                  # 3) 맥락 문서화

/pr                         # 4) 커밋 + PR 생성
/apply-review               # 5) 리뷰 반영 + 재푸시

코드 작성부터 리뷰 반영까지, 명령어 5개로 한 사이클이 완성됩니다.

왜 이 방식이 효과적이었나

1) PR 올리는 심리적 허들이 줄어듭니다

커밋 메시지/PR 본문 고민이 사라지면, PR을 더 자주 올리게 돼요. PR이 작아지면 리뷰도 쉬워지고, 충돌도 줄어듭니다.

2) 커밋 히스토리 품질이 올라갑니다

수동으로 쓰면 귀찮아서 “fix”만 남발하게 되는데, 자동이더라도 규칙이 있으니 품질이 균일해집니다.

3) 리뷰 반영 속도가 빨라집니다

리뷰가 달리면 미루게 되잖아요. 근데 /apply-review는 “미루기 어려울 정도로 가볍게” 처리됩니다.

4) 리뷰어-작성자 사이의 마찰이 줄어듭니다

“제가 말한 건 그게 아닌데…” 같은 오해가 줄어드는 편이었어요. 특히 변경사항이 커밋 메시지로 요약되니 커뮤니케이션이 더 명확해집니다.

실제 명령어 파일 구조 (핵심만)

/pr 명령어 예시

# pr.md

현재 변경사항을 커밋하고 PR을 생성합니다.

## 실행 절차
1. git diff로 변경 사항 확인
2. 변경 내용 분석하여 커밋 메시지 생성
3. 변경 파일 스테이징 및 커밋
4. 원격 브랜치에 푸시
5. gh pr create로 PR 생성

## 커밋 메시지 규칙
- Conventional Commits
- 타입: feat, fix, refactor, style, docs, test, chore
- 설명은 한글

## PR 템플릿
## Summary
- 변경 사항 요약 (1~3개)

## Test plan
- [ ] 테스트 항목들

/apply-review 명령어 예시

# apply-review.md

현재 브랜치의 PR 리뷰를 분석하고 반영합니다.

## 실행 절차
1. 현재 브랜치의 PR 확인
2. gh api로 리뷰 코멘트 수집
3. 코멘트 분석 및 액션 결정
4. 코드 수정
5. 반영 커밋 생성 (리뷰어 정보 포함)
6. 푸시

## 리뷰 타입별 처리
- 수정 요청: 코드 변경 + 커밋
- 질문: 주석 추가 또는 답변
- 제안: 적용 여부 판단
- 승인: 액션 없음

커스터마이징 포인트

프로젝트마다 팀 룰이 다르니까, 아래는 쉽게 바꿀 수 있게 열어두는 편이 좋아요.

1) 커밋 메시지 언어/톤

- 영어로 작성
- 동사 원형으로 시작 (Add/Fix/Update/Remove)

2) PR 템플릿 확장

## Changes
- 상세 변경 내용

## Screenshots
<!-- UI 변경 시 -->

## Checklist
- [ ] 테스트 통과
- [ ] 문서 업데이트(해당 시)

3) 브랜치 네이밍 자동화

- feat/: 새 기능
- fix/: 버그 수정
- refactor/: 리팩토링
예: feat/kakao-login

4) 리뷰 반영 후 자동 코멘트

"리뷰 내용을 반영했습니다. 확인 부탁드립니다!"

주의사항

1) 민감한 변경은 자동화만 믿지 않기

보안/결제/개인정보 같은 영역은 자동 커밋 전에 꼭 사람이 확인하는 게 안전합니다.

2) 리뷰가 너무 함축적이면 오해 가능

"이거 좀…"
"여기 그렇게 하면 안 되는데"

이런 코멘트는 AI도 사람도 해석이 어렵습니다. 리뷰어가 “요청 형태”로 써주면 자동화가 훨씬 잘 굴러가요.

3) 충돌은 수동 해결이 필요할 수 있음

머지 충돌은 자동 처리의 한계가 있는 영역이라, 충돌 해결 후 다시 실행하는 흐름이 필요합니다.

4) CI 실패는 별도 대응

PR 생성 후 CI가 깨지는 건 /apply-review로 자동 해결되지 않을 수 있어요. CI 로그 기반 수정은 별도의 작업으로 보는 게 좋습니다.

마치며

/pr과 /apply-review의 핵심은 한 문장입니다.

리뷰 “과정”이 아니라, 리뷰의 결과(품질 개선)에 집중하게 만드는 것.

• 커밋 메시지/PR 본문 작성 같은 반복 작업은 자동화하고
• 리뷰 코멘트는 코드로 빠르게 반영해서 사이클을 줄이고
• 개발자는 더 중요한 판단(설계/품질)에 에너지를 쓰게 됩니다

이 시리즈에서 소개한 명령어를 다시 정리하면:

물론 완벽한 자동화는 없어요. 아키텍처 결정이나 논쟁이 필요한 리뷰는 여전히 사람이 해야 합니다.

하지만 기계적인 반복 작업을 AI에게 맡기고, 우리는 더 가치 있는 판단에 집중할 수 있게 됐습니다.

이게 제가 생각하는 “AI와 같이 일하는 개발 워크플로우”의 형태였습니다.

참고: Link Dropper 프로젝트

이 글에서 소개한 명령어들은 제가 만들고 있는 Link Dropper 프로젝트에서 실제로 사용하고 있습니다.

• App Store에서 다운로드하기
• 웹에서 사용하러 가기
• 크롬 익스텐션 설치하기

들어가며

Claude Code를 쓰다 보면 이런 상황, 은근 자주 마주칩니다.

• “이 폴더 구조 왜 이렇게 돼 있어?” → Claude: (모든 파일을 읽으며 추론 시작…)
• “여기에 기능 추가해줘” → Claude: (구현은 했는데 기존 패턴이랑 미묘하게 다름)
• “이 모듈 어떻게 쓰는 거야?” → Claude: (코드 분석은 하는데 ‘설계 의도’는 알 수 없음)

AI는 코드를 읽을 수는 있어요. 그런데 코드를 이해하려면 결국 맥락이 필요합니다.

그래서 만든 게 /w-context입니다.

AI가 읽을 수 있는 README를 자동으로 만들어주는 명령어. 코드 주석 대신, 설계 의도와 사용 패턴을 한 곳에 모아두는 문서화 방식.

CONTEXT.md가 뭔가요?

한 문장으로 하면 이렇습니다.

AI를 위한 모듈 설명서입니다.

README.md가 “사람”에게 설치/사용/기여 방법을 알려주는 문서라면, CONTEXT.md는 “AI가 이 폴더를 처음 볼 때 반드시 알아야 할 것”에 집중합니다.

README vs CONTEXT

여기서 핵심은 딱 하나예요.

AI가 흔히 놓치는 건 구현력이 아니라, “왜 이렇게 했는지”입니다.

/w-context가 하는 일

실행은 한 줄입니다.

/w-context

그러면 Claude가 현재 작업 중인 폴더를 기준으로 CONTEXT.md를 생성(또는 업데이트)합니다.

1. 폴더 파악 — 지금 작업하는 모듈이 무엇인지 확인
2. 파일 분석 — 코드 구조/역할/패턴을 읽어냄
3. 기존 문서 확인 — CONTEXT.md가 있으면 업데이트, 없으면 생성
4. CONTEXT.md 작성 — 팀 규칙에 맞춰 문서화

중요한 건 이게 “한 번 만들고 끝”이 아니라는 점이에요.

코드가 바뀌면 /w-context를 다시 실행해서 문서도 같이 최신화합니다.

문서가 최신 상태로 유지되면, AI가 같은 모듈을 수정할 때 “처음 보는 프로젝트”처럼 헤매지 않게 됩니다.

CONTEXT.md에는 무엇을 넣나요?

저는 CONTEXT.md를 5개 섹션으로 고정했습니다. 이 정도면 AI가 맥락을 잡기에 충분하면서, 과하게 길어지지도 않더라고요.

1) 이 모듈이 하는 일 (한 문장으로 끝)

## 이 모듈이 하는 일

HTTP 요청을 표준화된 방식으로 처리하고, 인증/재시도/에러 핸들링을 자동화합니다.

이 한 줄이 있으면 AI는 첫 줄에서 이렇게 판단합니다.

“아, 이 폴더는 API 클라이언트 레이어구나.”

이게 없으면 Claude는 “파일 다 읽고 추론”부터 시작해요. 작업 속도가 달라질 수밖에 없습니다.

2) 파일 구조와 역할 (어디를 고쳐야 하는지 바로 보이게)

## 파일 구조와 역할

- `client.ts`: 핵심 HTTP 클라이언트, fetch 래핑, 재시도 로직
- `types.ts`: 요청/응답 타입 정의
- `interceptors.ts`: 요청/응답 인터셉터
- `index.ts`: public API 내보내기

이 섹션이 있으면 “수정 지점”을 찾는 시간이 줄어요.

• 재시도 로직 추가? → client.ts
• 에러 타입 추가? → types.ts
• public export 변경? → index.ts

AI도 사람이랑 똑같이 “어디부터 볼지”가 중요합니다.

3) 핵심 설계 결정 (가장 중요한 파트: Why)

이게 CONTEXT.md의 진짜 목적입니다. AI가 기존 방향을 존중하게 만드는 장치예요.

## 핵심 설계 결정

1. **fetch 직접 래핑**
   - axios 대신 네이티브 fetch 사용
   - 번들 사이즈 최소화
   - React Native/Web에서 동일하게 동작

2. **재시도는 네트워크 에러만**
   - 4xx는 재시도하지 않음
   - 비즈니스 에러는 재시도해도 결과가 같음
   - 불필요한 서버 부하 방지

3. **토큰 자동 주입**
   - 모든 요청에 인증 헤더 자동 추가
   - 호출부에서 토큰 관리 코드 제거
   - 토큰 갱신 로직 중앙화

이런 내용이 없으면 AI는 보통 “자기가 생각하는 베스트 프랙티스”로 구현하려고 합니다. 그게 항상 틀린 건 아니지만, 프로젝트의 의도와 다를 수 있어요.

4) 사용 패턴 (AI가 ‘복붙’할 수 있는 예시)

## 사용 패턴

```ts
import { apiClient } from "@/libs/api";

// GET
const users = await apiClient.get<User[]>("/users");

// POST
const newUser = await apiClient.post<User>("/users", {
  body: { name: "John", email: "john@example.com" }
});

// 에러 처리
try {
  await apiClient.get("/protected");
} catch (error) {
  if (error instanceof ApiError) {
    // 401이면 로그아웃 처리
  }
}

AI는 “예시 코드”를 굉장히 잘 따릅니다.  
즉, 사용 패턴 섹션은 **미래의 코드 스타일을 유도하는 템플릿**이에요.

---

### 5) 확장 시 고려사항 (미리 알려주면 삽질이 줄어든다)

```md
## 확장 시 고려사항

- 새 HTTP 메서드 추가 시 `client.ts`의 request 메서드 확장
- 인터셉터 추가 시 실행 순서 주의 (요청은 정순, 응답은 역순)
- 에러 타입 추가 시 `types.ts`의 ApiError 클래스 확장
- 캐싱 도입 시 React Query와의 역할 분리 고려

이게 없으면 AI가 기능 추가하면서 “좋아 보이는 방향”으로 확장하는데, 그게 나중에 구조를 망가뜨리는 경우가 있어요.

확장 포인트를 미리 적어두면, AI가 안전한 레일 위에서 움직입니다.

실제 생성 결과 예시 (libs/api/에서 실행하면)

libs/api/ 폴더에서 /w-context를 실행하면 대략 이런 문서가 생깁니다.

# API 클라이언트 컨텍스트

이 문서는 AI가 api 모듈의 설계 의도와 사용 방법을 빠르게 파악할 수 있도록 작성되었습니다.

## 이 모듈이 하는 일
HTTP 요청을 표준화된 방식으로 처리하고, 인증 토큰 관리와 에러 핸들링을 자동화합니다.

## 파일 구조와 역할
- `client.ts`: fetch 래핑, 재시도 로직
- `types.ts`: 요청/응답 타입, 에러 클래스
- `auth/`: 인증 관련 API
- `user/`: 사용자 관련 API
- `index.ts`: public API export

## 핵심 설계 결정
- axios 대신 fetch 사용
- 네트워크 에러만 재시도 (지수 백오프)
- ApiError로 에러 표준화

## 사용 패턴
(예시 코드...)

## 확장 시 고려사항
- 도메인별 폴더로 분리 (`links/`, `folders/`)
- 캐싱은 React Query에서 처리

이 문서 하나만 있으면 AI는 “추측”이 아니라 “이해”를 기반으로 움직이게 됩니다.

기존 CONTEXT.md가 있으면? 덮어쓰지 않고 “동기화”합니다

문서 자동 생성의 최대 단점은 이거죠.

“내가 손으로 다듬은 내용이 날아갈까 봐 무섭다”

그래서 /w-context는 “갈아엎기”가 아니라 “동기화”로 설계했습니다.

1. 기존 CONTEXT.md 구조는 유지
2. 코드 변경사항 분석
3. 새 파일/기능은 추가 반영
4. 삭제된 요소는 문서에서 제거
5. 설계 결정/사용 패턴이 바뀌면 해당 섹션만 업데이트

즉, 문서를 코드와 같은 생명주기로 관리합니다.

왜 코드 주석 대신 CONTEXT.md인가?

주석으로도 설명할 수는 있어요. 그런데 저는 CONTEXT.md가 “AI 시대에는” 더 실용적이라고 느꼈습니다.

주석의 한계

// 재시도 로직
// - 네트워크 에러만 재시도
// - 최대 3회
// - 지수 백오프 적용
async function fetchWithRetry() {}

• 파일 곳곳에 흩어져 있음
• 전체 설계 그림이 한눈에 안 보임
• AI가 맥락 파악하려면 여러 파일을 다 읽어야 함

CONTEXT.md의 장점

• 한 곳에 모인다 → 맥락을 빠르게 로딩
• Why 중심 → 설계 의도를 명시
• AI 친화적 → 한 번에 읽고 이해 가능
• 유지보수 쉬움 → 코드와 분리, 업데이트도 명령어로

한마디로, 주석은 “로컬 설명”, CONTEXT는 “모듈의 지도”입니다.

저는 언제 /w-context를 실행하나요?

저는 아래 타이밍을 루틴으로 만들었습니다.

1) 새 모듈을 만들었을 때

mkdir libs/cache
# 코드 작성...
/w-context

2) 기존 모듈을 크게 수정했을 때

# libs/api 구조 변경
/w-context

3) /spec으로 구현을 끝낸 직후

/spec user-profile
/w-context

구현 직후가 설계 의도가 가장 선명할 때라 문서 품질이 좋아요.

4) PR 올리기 직전

/w-context
/pr

PR에서 “문서 최신인가?”를 사람이 체크하지 않게 만들기.

CONTEXT.md는 어디에 생기나요?

현재 작업 중인 폴더 내부에 CONTEXT.md로 생성됩니다.

libs/
├── api/
│   ├── client.ts
│   ├── types.ts
│   └── CONTEXT.md
├── logger/
│   └── CONTEXT.md
└── utils/
    └── CONTEXT.md

모듈별로 하나씩 있으면, AI가 특정 폴더를 작업할 때 그 폴더의 맥락만 빠르게 읽고 들어올 수 있어요. (프로젝트 전체 README 한 장으로는 절대 못 하는 일입니다.)

커스터마이징 포인트

프로젝트 성격에 따라 CONTEXT.md 템플릿을 바꿀 수 있어요.

1) 필수 섹션 추가

## 필수 포함 내용
1. 이 모듈이 하는 일
2. 파일 구조와 역할
3. 핵심 설계 결정
4. 사용 패턴
5. 확장 시 고려사항
6. 성능 고려사항 (선택)
7. 보안 관련 사항 (선택)

2) 작성 언어

영어 프로젝트면 작성 언어만 바꾸면 됩니다.

- Use English for all sections
- Keep it concise and technical

3) 생성 위치 변경

모듈 안이 아니라, docs로 모아도 됩니다.

- `docs/context/{module}.context.md`에 생성

/spec, /create-jest와 붙이면 “개발 3종 세트”가 됩니다

/spec user-notification
/create-jest
/w-context

이렇게 하면

• 구현은 명세서 기반으로 일관되게
• 테스트는 자동으로 따라오고
• 맥락은 문서로 남아서 다음 작업 품질이 올라갑니다

즉, 한 번 만든 모듈이 시간이 지나도 “설계 의도”를 잃지 않게 돼요.

왜 이 방식이 효과적이었나

1. AI의 맥락 부족 문제 해결 코드만 보면 AI는 추측할 수밖에 없는데, CONTEXT.md가 있으면 확신을 갖고 작업합니다.

2. 온보딩 시간 단축 새 팀원, 새 AI 세션 모두 “CONTEXT부터 읽고 시작”이 가능해집니다.

3. 일관된 코드 스타일 유지 설계 결정과 사용 패턴이 문서화되어 있으니, 사람이든 AI든 같은 방향으로 코드를 씁니다.

4. 미래의 나를 위한 보험 3개월 뒤 “왜 이렇게 했지?”라는 질문에 CONTEXT.md가 답해줍니다.

주의사항

1) 모든 폴더에 만들 필요는 없습니다

단순 UI 컴포넌트까지 CONTEXT.md를 만들면 오히려 노이즈가 됩니다. 복잡한 로직/규칙이 있는 모듈에만 집중하는 게 좋아요.

2) 코드와 문서의 동기화가 핵심입니다

문서가 코드와 달라지면 혼란을 줍니다. 큰 변경 후에는 /w-context로 업데이트하는 습관이 중요해요.

3) 민감 정보는 절대 쓰지 마세요

API 키, 내부 보안 규칙, 인증 우회 힌트 같은 건 문서에 남기면 안 됩니다. “설계 의도”와 “비밀 정보”는 다릅니다.

실제 명령어 파일은 이렇게 생겼습니다 (핵심만)

# w-context.md

현재 작업 중인 폴더에 CONTEXT.md 파일을 생성하거나 업데이트합니다.

## 목적
AI가 해당 모듈의 맥락을 빠르게 파악할 수 있도록 자연어 문서를 작성합니다.

## 실행 방법
1. 현재 폴더 확인
2. 폴더 내 파일 분석
3. CONTEXT.md 존재 여부 확인
   - 없으면 생성
   - 있으면 변경사항 동기화

## CONTEXT.md 작성 규칙
### 필수 포함
1. 이 모듈이 하는 일
2. 파일 구조와 역할
3. 핵심 설계 결정
4. 사용 패턴
5. 확장 시 고려사항

### 작성 원칙
- 코드를 읽지 않아도 이해 가능해야 함
- 구현 디테일보다 의도/맥락 중심
- 핵심만 간결하게

마치며

/w-context의 핵심은 이거였습니다.

AI가 코드를 “읽는” 수준에서 멈추지 않고, “이해하고 같은 방향으로 수정”하도록 돕는 것.

처음엔 “문서 또 써야 해?” 싶을 수 있어요. 근데 /w-context는 한 줄이고, 효과는 꽤 큽니다.

다음 5편에서는 /pr과 /apply-review로 PR 생성부터 리뷰 반영까지 워크플로우를 자동화한 이야기를 정리해볼게요.

참고: Link Dropper 프로젝트

이 글에서 소개한 명령어들은 제가 만들고 있는 Link Dropper 프로젝트에서 실제로 사용하고 있습니다.

• App Store에서 다운로드하기
• 웹에서 사용하러 가기
• 크롬 익스텐션 설치하기

들어가며

테스트 코드, 좋은 건 알아요. 근데 현실은 대개 이렇죠.

• “이거 테스트는… 나중에 쓰자” (안 씀)
• “급하니까 일단 배포하고…” (영원히 안 씀)
• “기존 테스트 깨졌네? 일단 스킵…” (테스트의 죽음)

저도 똑같았습니다. 테스트가 필요 없는 게 아니라, 테스트를 쓰는 데 드는 에너지가 문제였어요.

그래서 만든 게 /create-jest입니다.

“코드 바꾸면 → 테스트가 따라온다” 라는 규칙을 고민이 아니라 시스템으로 강제해버린 명령어.

/create-jest가 하는 일 (진짜로는 “테스트 파이프라인”)

실행은 한 줄입니다.

/create-jest

하지만 내부적으로는 아래를 순서대로 처리해요.

1. 변경된 파일 감지 — git diff로 무엇이 바뀌었는지 확인
2. 테스트 대상 필터링 — “테스트할 파일”만 규칙으로 추려냄
3. 테스트 생성/업데이트 — 있으면 수정, 없으면 새로 생성
4. 테스트 실행 — 작성한 테스트가 실제로 통과하는지 확인

즉, “테스트 파일 만들어드립니다”가 아니라

코드 수정 → /create-jest → 테스트까지 끝

이 흐름을 만드는 게 목표였습니다.

핵심 설계: 자동화의 성패는 “무엇을 테스트할지”가 결정한다

테스트 자동화를 시도할 때 제일 먼저 부딪히는 문제가 이거예요.

• 다 테스트하려면 유지보수가 지옥
• 너무 덜 테스트하면 의미가 없음

그래서 저는 “테스트할 것 / 안 할 것”을 명확히 분리했습니다.

✅ 테스트 대상 (효율 좋은 구역만)

- `libs/**/*.ts` - 공통 라이브러리
- `hooks/**/*.ts` - 커스텀 훅
- `utils/**/*.ts` - 유틸리티 함수
- `services/**/*.ts` - 서비스 레이어

이 영역들은 보통 순수 로직이 많고, 테스트 비용 대비 효과가 커요. 즉 “자동 생성”과 궁합이 좋습니다.

❌ 테스트 제외 (여긴 다른 전략이 낫다)

- `app/**/*` - 앱 라우터 (E2E로 커버)
- `components/**/*` - React 컴포넌트 (별도 컴포넌트 테스트)
- `**/*.d.ts` - 타입 정의 파일
- `**/index.ts` - re-export만 하는 파일
- `**/__tests__/**` - 테스트 파일 자체
- `*.config.*` - 설정 파일

UI/라우팅은 단위 테스트로 무리해서 커버하기보다, E2E나 컴포넌트 테스트 전략이 더 적합하다고 판단했어요. 그래서 /create-jest는 “로직 구역”만 확실히 쌓아주는 역할을 맡습니다.

테스트 파일 위치/네이밍: 흩어지지 않게 “한 규칙”으로

테스트가 자동으로 생기기 시작하면, 다음 문제가 옵니다.

“어디에 생겼더라?” “왜 어떤 건 여기 있고 어떤 건 저기 있어?”

그래서 무조건 같은 규칙으로 생성하도록 했어요.

위치: 동일 경로의 __tests__ 폴더

libs/fetch/
├── core.ts
├── types.ts
├── index.ts
└── __tests__/
    └── fetch.test.ts

소스랑 같은 위치에 있으니 찾기 쉽고, 모듈 단위로 묶여서 관리도 편합니다.

네이밍: “모듈 크기” 기준으로 실용적으로

작은 모듈은 통합 테스트 파일 하나가 관리가 쉽고, 큰 모듈은 파일 단위로 쪼개야 유지보수가 됩니다.

테스트 작성 규칙: “팀 컨벤션”을 명령어에 박아두기

여기가 /create-jest의 진짜 핵심이에요.

테스트를 못 쓰는 이유는 보통 “시간”보다도 매번 선택해야 하는 것들이 너무 많아서예요.

• describe 어떻게 나누지?
• 케이스는 뭐부터 쓰지?
• 모킹은 어디까지 하지?
• 테스트명은 영어로? 한글로?

그래서 저는 그 선택을 명령어가 대신 하도록 만들었습니다.

1) 한글 테스트명 (실패 로그가 곧 문서가 된다)

it("사용자를 생성한다", () => {});
it("유효하지 않은 이메일이면 에러를 던진다", () => {});

한글 테스트명의 장점은 단순해요.

• 실패했을 때 로그만 봐도 “뭐가 깨졌는지” 바로 이해됨
• 팀원이 테스트 파일을 읽을 때도 맥락이 빨리 잡힘

테스트는 “작성자”보다 “미래의 유지보수자”를 위한 거라서, 저는 한글이 더 실용적이었습니다.

2) AAA 패턴 강제 (테스트 구조를 자동으로 통일)

it("정상 케이스를 처리한다", () => {
  // Arrange
  const input = { name: "홍길동", email: "hong@test.com" };

  // Act
  const result = createUser(input);

  // Assert
  expect(result).toEqual({ id: expect.any(String), ...input });
});

AAA(Arrange-Act-Assert)를 강제하면 좋은 점:

• 테스트가 길어져도 읽기 쉬움
• “준비/실행/검증”이 섞이지 않아서 수정하기 쉬움
• 팀원이 테스트 스타일로 싸울 일이 사라짐

3) describe로 기능 단위 그룹화 (실패 위치를 즉시 좁힌다)

describe("UserService", () => {
  describe("createUser", () => {
    it("정상 케이스를 처리한다", () => {});
    it("중복 이메일이면 에러를 던진다", () => {});
  });

  describe("updateUser", () => {
    it("존재하는 사용자를 업데이트한다", () => {});
    it("존재하지 않는 사용자면 에러를 던진다", () => {});
  });
});

이 구조는 테스트가 많아질수록 효과가 커집니다. 특히 CI에서 실패했을 때 “어느 기능이 문제인지”가 바로 찍혀요.

테스트 케이스 우선순위: 중요한 것부터 자동으로 채운다

Claude가 테스트를 생성할 때 저는 우선순위를 고정했습니다.

1. Happy Path — 정상 입력/정상 결과
2. Edge Cases — 경계값, 빈 값, null/undefined
3. Error Cases — 예외 상황, 에러 핸들링
4. Integration (필요시) — 모듈 간 상호작용

이렇게 하면 최소한

• “정상 동작”은 보장하고
• “자주 터지는 경계/에러”도 같이 잡습니다

자동 생성 테스트가 “쓸모없는 테스트”가 되지 않게 만드는 장치예요.

모킹 규칙: 과하게 하지 않기 (테스트가 깨지는 진짜 이유)

테스트가 깨지기 쉬운 가장 흔한 원인이 과도한 모킹이더라고요. 내부 구현을 잔뜩 mock 해버리면, 코드가 조금만 바뀌어도 테스트가 와르르 깨집니다.

그래서 /create-jest는 원칙이 단순합니다.

• 외부 의존성만 모킹한다 (네트워크, 파일 시스템, 외부 API)
• 내부 구현은 가능한 실제로 실행한다

// ✅ Good: 외부 의존성만 모킹
const mockFetch = jest.fn();
global.fetch = mockFetch;

// ❌ Bad: 내부 구현을 과하게 모킹
jest.mock("./internal-helper");

이렇게 하면 테스트가 “구현 디테일”에 덜 묶여서 유지보수가 쉬워집니다.

기존 테스트가 있으면? “갈아엎지 않고” 업데이트만

자동화의 또 다른 함정은 이거예요.

“테스트 새로 만들어줬는데… 기존 테스트 스타일이랑 완전 다르네?”

그래서 변경된 파일에 테스트가 이미 있으면 /create-jest는 이렇게 행동합니다.

1. 기존 테스트 구조 유지
2. 변경된 기능에 대한 테스트만 수정/추가
3. 삭제된 기능의 테스트 제거
4. 새 기능의 테스트 추가
5. 전체 테스트가 통과하는지 확인

즉, 전체를 다시 쓰지 않고 변경분만 안전하게 다룹니다. (이게 안 되면 팀 프로젝트에서 바로 반발 나옵니다…)

실제 사용 예시: “재시도 로직 추가했더니 테스트도 같이 자랐다”

예를 들어 libs/api/client.ts에 재시도 로직을 추가했다고 해볼게요.

# 1) 코드 수정 후 변경 파일 확인
git diff --name-only
# libs/api/client.ts

# 2) 테스트 생성/업데이트
/create-jest

그러면 결과는 이런 식으로 요약됩니다.

## 테스트 작성 완료

### 업데이트된 테스트
- libs/api/__tests__/client.test.ts

### 테스트 결과
✓ 12 tests passed
✗ 0 tests failed

### 주요 테스트 케이스
- apiFetch: GET/POST, 재시도, 에러 처리 등
- createApiClient: 인스턴스 생성, baseURL 설정 등

중요한 건 “파일 하나 늘어났네요”가 아니라, 변경한 로직(재시도)이 테스트 케이스로 바로 박제된다는 점입니다.

/spec과 같이 쓰면 “명세→구현→테스트”가 두 줄로 끝난다

2편에서 다룬 /spec과 붙이면 흐름이 깔끔해져요.

/spec user-auth
/create-jest

• /spec: 명세서 기반 구현 + 검증
• /create-jest: 변경 기반 테스트 생성 + 실행

이렇게 하면 “테스트를 쓰는 사람”이 아니라, 테스트가 기본으로 따라오는 구조가 됩니다.

왜 이 방식이 효과적이었나

1) “테스트 쓸까?”라는 고민이 사라짐

테스트가 선택이 아니라 루틴이 됩니다. 루틴이 되면 지속됩니다.

2) 테스트 스타일이 통일됨

한글 테스트명, AAA, describe 구조… 팀원마다 다르게 쓰던 테스트가 “명령어 규칙”으로 정렬됩니다.

3) 리뷰어가 편해짐

PR에 테스트가 항상 포함되니, “테스트는요?”라는 질문 자체가 줄어듭니다.

4) 회귀 테스트가 자동으로 쌓임

수정할 때마다 테스트가 업데이트되니까, 어느 순간부터는 “테스트가 나를 지켜주는 순간”이 오더라고요.

실제 명령어 파일은 이렇게 생겼습니다 (핵심만)

/create-jest 명령어는 결국 규칙을 마크다운으로 적어둔 것입니다.

# create-jest.md

변경된 파일에 대한 테스트 코드를 생성하거나 업데이트합니다.

## 실행 절차
1. git diff로 변경된 파일 목록 확인
2. 테스트 대상 파일 필터링
3. 기존 테스트 여부에 따라 생성 또는 업데이트
4. 테스트 실행하여 통과 확인

## 테스트 대상 규칙
### 포함
- libs/**/*.ts
- hooks/**/*.ts
- utils/**/*.ts
- services/**/*.ts

### 제외
- app/**/*
- components/**/*
- **/*.d.ts
- **/index.ts
- **/__tests__/**
- *.config.*

## 테스트 작성 규칙
1. 한글 테스트명
2. describe 구조화
3. AAA 패턴
4. 모킹은 외부 의존성만

이렇게 “팀 룰”을 문서로 남기면, Claude는 그걸 매번 일관되게 따라줍니다.

커스터마이징 포인트 (프로젝트마다 여기만 바꾸면 됨)

1) 테스트 대상 경로

- src/domain/**/*.ts
- src/application/**/*.ts

2) 테스트 파일 위치

• 소스 파일 옆에 *.test.ts 생성 또는
• 루트 tests/에 동일 폴더 구조로 생성

3) 프레임워크 변경

• Jest 대신 Vitest
• Testing Library 규칙 추가

주의사항 (자동 생성 테스트를 “과신”하지 않기)

• 100% 커버리지가 목표가 아닙니다. 자동 생성은 “기본 안전망”을 깔아주는 역할이에요.
• 생성된 테스트는 한 번은 눈으로 검토하세요. 가끔 표면적인 테스트(예: 단순 snapshot 느낌)가 나올 수 있습니다.
• 테스트가 쌓이면 실행 시간이 늘어요. CI에서 병렬 실행/캐싱 같은 운영 최적화도 고려해볼 만합니다.

마치며

/create-jest의 핵심은 한 문장입니다.

테스트 작성을 “의지”에서 “시스템”으로 옮기는 것.

• “어떻게 테스트하지?” 고민을 없애고
• 팀 컨벤션에 맞는 테스트를 자동으로 만들고
• 코드 변경과 테스트가 항상 같이 다니게 만들었습니다

완벽하진 않아요. 하지만 테스트 0개보다 자동 생성된 테스트 10개 + 중요한 곳 수동 보완 2개가 훨씬 낫잖아요.

다음 4편에서는 /w-context를 다룹니다. AI가 코드를 더 잘 이해하도록 CONTEXT.md를 자동 생성하는 흐름이에요.

참고: Link Dropper 프로젝트

이 글에서 소개한 명령어들은 제가 만들고 있는 Link Dropper 프로젝트에서 실제로 사용하고 있습니다.

• App Store에서 다운로드하기
• 웹에서 사용하러 가기
• 크롬 익스텐션 설치하기

지난 글에서 Claude Code의 Custom Commands로 구현부터 PR까지 자동화한 이야기를 했어요. 오늘은 그중에서도 제 워크플로우의 심장 같은 존재, /spec 명령어를 깊게 파헤쳐보려고 합니다.

솔직히 AI 코딩 도구를 쓰면서 이런 답답함, 한 번쯤 느끼셨을 거예요.

• “코드는 만들어주는데… 왜 이렇게 만들었는지 모르겠어”
• “요청한 것만 딱 만들고 끝. 나머지는 결국 내가 마무리해야 해”
• “날마다 결과물이 들쭉날쭉해서, 다시 손대느라 시간이 더 든다”

/spec은 이 문제를 ‘명세서 기반 개발’로 정면 돌파합니다.

AI에게 “구현해줘”라고 말하는 대신, 결정을 명세서에 미리 담고 /spec으로 실행한다.

이 한 줄이 생각보다 큰 차이를 만들더라고요.

/spec이 뭔가요?

한 줄 요약은 이렇게 할게요.

명세서를 주면, Claude가 분석→계획→구현→검증→보고까지 “개발 프로세스”를 그대로 수행하는 명령어

/spec user-auth  # specs/user-auth.md를 읽고 구현

그리고 여기서 가장 중요한 키워드가 하나 있습니다.

“질문 없이”

보통 AI에게 기능 구현을 부탁하면 이런 흐름이 반복되죠.

AI: "인증은 JWT로 할까요? 세션으로 할까요?"
나: "JWT요"
AI: "토큰 저장은 어디에 할까요?"
나: "AsyncStorage요"
AI: "에러 처리는 어떻게 할까요?"
나: (이미 지침)

/spec은 이 핑퐁을 줄이는 게 아니라, 애초에 필요 없게 만들어요.

• 선택지를 AI가 묻기 전에
• 사람이 답변하느라 흐름이 끊기기 전에
• 명세서에 결정을 박아두는 방식입니다.

/spec이 동작하는 핵심 원칙 4가지

/spec은 “코드 생성”이라기보다, 코드를 만들기 위한 규칙 세트에 가까워요.

1) 명세서만으로 끝나야 한다

명세서가 충분히 상세하면 Claude는 추가 질문 없이 구현에 들어갑니다. 즉 명세서는 단순 문서가 아니라 실행 가능한 문서가 됩니다.

2) 품질을 기본값으로 둔다

“일단 돌아가는 코드”가 아니라

• 가독성
• 성능
• 확장성
• 보안

까지 기본값으로 깔고 들어가요. 목표는 프로덕션에 올려도 부끄럽지 않은 코드입니다.

3) 우선순위 기반으로 구현한다 (🔴→🟡→🟢)

필수부터 먼저 완성하고, 시간이 남으면 권장/선택 기능으로 넘어갑니다. 이 구조 덕분에 “시간이 부족해서 다 못 했어요”여도 핵심 기능은 살아있어요.

4) 한 명령어는 한 가지 일만

테스트는 /create-jest, 문서는 /w-context로 분리했어요. /spec은 구현과 검증에만 집중합니다.

/spec 실행 흐름: Phase 0 → Phase 6

/spec이 “그냥 생성”이 아니라 “개발 프로세스”인 이유가 여기 있어요. 총 7단계를 항상 같은 순서로 밟습니다.

Phase 0: 명세서 로드
Phase 1: 명세서 분석 및 이해
Phase 2: 구현 전 검토 (질문 필요 시)
Phase 3: 구현 계획 수립
Phase 4: 코드 구현
Phase 5: 검증
Phase 6: 완료 보고

각 단계를 짧게(하지만 핵심은 빠짐없이) 살펴볼게요.

Phase 0: 명세서 로드

/spec              # 인자 없이 실행하면 목록 표시
/spec user-auth    # specs/user-auth.md 로드

• 인자가 없으면 사용 가능한 명세서 목록을 보여주고
• 인자가 있으면 해당 파일을 불러옵니다.

파일이 없으면 이렇게 깔끔하게 실패합니다.

❌ specs/user-auth.md 파일을 찾을 수 없습니다.
사용 가능한 명세서: [목록]

Phase 1: 명세서 분석 및 이해

이 단계가 품질을 결정합니다. Claude가 바로 코딩부터 하지 않고, 명세서에서 필요한 정보를 구조적으로 뽑아내요.

그리고 여기서 중요한 한 가지.

CONTEXT.md를 같이 읽습니다

기존 코드의 설계 의도와 사용 패턴을 놓치면 “프로젝트랑 따로 노는 코드”가 나오거든요.

# 예: libs/fetch 모듈을 활용한다면
cat libs/fetch/CONTEXT.md

이 과정을 넣어두니, 결과물이 “그럴듯한 예제 코드”가 아니라 우리 코드베이스의 일부처럼 나오기 시작했습니다.

Phase 2: 구현 전 검토 (질문이 정말 필요한지 판단)

/spec이 “질문이 없다”는 건 무조건 묻지 않는다가 아니라, 정말 필요한 경우에만 묻도록 설계했다는 뜻입니다.

질문하는 경우

• 구현 위치가 불명확하거나 선택지가 여럿인 경우
• 기존 코드와 충돌 가능성이 큰 경우
• 보안/성능에 큰 트레이드오프가 있는 경우

질문 없이 진행하는 경우

• 명세서가 충분히 구체적인 경우
• 컨벤션(CLAUDE.md)으로 답이 이미 정해지는 경우
• 업계 표준 베스트 프랙티스가 명확한 경우

여기서 얻은 인사이트는 딱 하나였어요.

질문이 많이 나온다면 /spec이 문제라기보다, 명세서가 덜 익은 것이다.

Phase 3: 구현 계획 수립 (Todo 리스트 자동 생성)

명세서 요구사항을 바탕으로 Todo를 뽑고, 우선순위를 고정합니다.

1. 🔴 필수 요구사항 (모두 완료해야 함)
2. 🟡 권장 요구사항 (시간이 허락하면)
3. 🟢 선택 요구사항 (추가 개선)

그리고 보통 이런 흐름으로 구현 순서를 잡아요.

1. 타입 정의
2. 에러/결과 모델
3. 핵심 로직
4. 유틸리티
5. API 라우트
6. UI 컴포넌트
7. 페이지 통합
8. export 정리

타입부터 잡아두면 이후 구현이 안정적으로 굴러가서, 결과적으로 수정량이 줄었습니다.

Phase 4: 코드 구현 (하지만 “아무렇게나”는 금지)

여기서는 명세서 + 컨벤션을 근거로 구현합니다. 원칙은 딱 5가지로 고정했어요.

• 컨벤션 준수 (네이밍, import 순서, 코드 스타일)
• 성능 고려 (불필요 연산/렌더 최소화)
• 가독성 고려 (단일 책임, 명확한 이름, 필요한 곳만 주석)
• 확장성 고려 (인터페이스 기반, 하드코딩 지양)
• 보안 고려 (입력 검증, 민감 정보 노출 방지)

이게 좋아서라기보다, 원칙이 고정돼 있으니 결과가 안정적입니다.

Phase 5: 검증 (여기서 “진짜 자동화”가 갈립니다)

코드만 만들고 끝내면 AI 도구가 아니라 “코드 생성기”죠. /spec은 검증을 기본 프로세스에 넣었습니다.

pnpm build   # 타입 체크
pnpm lint    # 린트 체크
pnpm test -- <관련 테스트 경로>  # 관련 테스트 (필요 시)

그리고 중요한 포인트.

에러가 나면 “에러 났어요”로 끝나는 게 아니라, 수정 후 재시도합니다.

이 부분 때문에 “결과물의 신뢰도”가 확 올라갔어요.

Phase 6: 완료 보고 (사람이 바로 판단 가능하게)

마지막에 구조화된 보고서를 출력합니다. 예시는 이런 느낌이에요.

## ✅ 구현 완료: 사용자 인증

### 요약
> 소셜 로그인을 통한 사용자 인증 시스템

### 구현된 요구사항
- [x] 🔴 Apple 로그인
- [x] 🔴 Google 로그인
- [x] 🟡 자동 로그인

### 생성된 파일
| 파일 | 설명 |
|------|------|
| `libs/auth/types.ts` | 타입 정의 |
| `libs/auth/core.ts` | 핵심 로직 |

### 검증 결과
| 항목 | 결과 |
|------|------|
| 타입 체크 | ✅ 통과 |
| 린트 | ✅ 통과 |

### 사용 예시
```typescript
import { signInWithApple } from "@/libs/auth";

const user = await signInWithApple();

다음 단계

/create-jest
/w-context

덕분에 “뭐가 됐고, 뭐가 남았고, 다음은 뭘 하면 되는지”가 한눈에 들어옵니다.

---

## 좋은 명세서 작성법: 질문을 0에 가깝게 만드는 체크리스트

`/spec` 품질은 결국 **명세서 품질**에 달려있습니다.  
제가 가장 효과를 봤던 팁들만 모아볼게요.

### 1) 구현 위치를 무조건 적는다
```markdown
## 구현 위치

### 생성할 파일
- `libs/auth/types.ts`
- `libs/auth/core.ts`
- `libs/auth/index.ts`

### 수정할 파일
- `stores/authStore.ts`

경로가 없으면 100% “어디에 만들까요?”가 나옵니다.

2) 타입을 명세서에 박아두기

## 타입 정의

```typescript
interface AuthUser {
  id: string;
  email: string;
  name: string;
  provider: 'apple' | 'google' | 'kakao';
}

타입이 있으면 결과물이 흔들리지 않아요. (그리고 나중에 타입 수정 지옥이 줄어듭니다.)

### 3) 에러 케이스는 표로 정리
```markdown
## 에러 처리

| 상황 | 코드 | 사용자 메시지 | 처리 |
|---|---|---|---|
| 네트워크 끊김 | NETWORK_ERROR | 인터넷 연결을 확인해주세요 | 재시도 |
| 토큰 만료 | TOKEN_EXPIRED | 다시 로그인해주세요 | 로그인 이동 |

표로 쓰면 “빼먹는 에러”가 확 줄어듭니다.

4) 우선순위는 🔴🟡🟢로 고정

AI가 “어느 것부터?”를 고민할 필요가 없게 만드는 장치입니다.

5) “기존 코드 활용” 섹션을 꼭 둔다

## 기존 코드 활용

- `libs/api/client.ts` - API 호출 패턴 참고
- `stores/authStore.ts` - 상태 관리 패턴 참고

이게 있으면 결과물이 “우리 코드”에 훨씬 자연스럽게 붙습니다.

실제 명세서 예시 (일부)

제가 실제로 링크 드라퍼에서 사용한 명세서 일부입니다.

# 공유 익스텐션 메타데이터 크롤링

## 개요
iOS Share Extension에서 공유된 URL의 메타데이터를 크롤링하여
링크 정보를 자동으로 채우는 기능

## 기능 요구사항
### 🔴 필수
- Open Graph 메타데이터 추출
- 제목/설명/이미지 URL 파싱
- 타임아웃 및 에러 처리

### 🟡 권장
- 이미지 없을 시 파비콘 폴백
- 캐싱으로 중복 요청 방지

## 구현 위치
### 생성할 파일
- `libs/crawler/types.ts`
- `libs/crawler/parser.ts`
- `libs/crawler/index.ts`

## 타입 정의
```typescript
interface LinkMetadata {
  title: string | null;
  description: string | null;
  imageUrl: string | null;
  faviconUrl: string | null;
}

에러 처리

이 정도만 적어도 `/spec`이 **질문 없이 구현**을 끝내는 편이었습니다.

---

## `/spec`이 바꾼 내 개발 방식

### Before: 대화형 개발(=핑퐁 지옥)
```text
나: "인증 기능 만들어줘"
AI: "어떤 방식으로?"
나: "소셜 로그인"
AI: "어떤 제공자?"
나: "Apple, Google"
AI: "토큰 저장은?"
나: (이때부터 집중력 붕괴)

After: 명세서 기반 개발(=실행)

나: "/spec user-auth"
AI: 분석 → 계획 → 구현 → 검증 → 보고
나: (검증 통과한 코드 받음)

시간이 줄어든 것도 좋았지만, 더 큰 변화는 이거였어요.

명세서가 같으면 결과도 비슷하다. 즉, 코드 품질이 ‘컨디션’이 아니라 ‘프로세스’에 의해 결정된다.

마치며

/spec은 단순히 “코드를 잘 뽑는 명령어”가 아니라,

• 명세서를 실행 가능한 문서로 만들고
• 개발 프로세스(분석→계획→구현→검증)를 강제하고
• 결과물의 품질을 안정화하는 장치였습니다.

명세서를 쓰는 시간이 들긴 해요. 그런데 그 시간은 대부분 “AI와 핑퐁하며 잃는 시간”을 통째로 대체하더라고요.

다음 글(3편)에서는 /create-jest를 다룹니다. /spec으로 만든 코드에 테스트를 자동으로 붙이는 흐름이 어떻게 굴러가는지 공유해볼게요.

시리즈 안내

링크 드라퍼, 정식 출시!

링크 드라퍼는 단순 저장 툴이 아니라, “다시 꺼내보게 만드는” 링크 관리 도구를 지향합니다.

• 빠르고 간편한 링크 저장: iOS/Android 앱, 웹, 크롬 익스텐션
• 폴더로 깔끔하게 정리: 읽을 거리, 레퍼런스, 쇼핑 후보까지
• 폴더 공유: 같이 보는 자료는 폴더 단위로 한 번에
• 크롬 익스텐션 원클릭 저장: 보고 있는 페이지를 바로 저장

링크 드라퍼 앱 다운로드 (iOS) 링크 드라퍼 웹에서 사용하러 가기 크롬 웹스토어에서 익스텐션 설치하기

개발하면서 진짜 자주 드는 생각이 있어요.

• “테스트… 또 써야 하지?”
• “PR 본문… 또 정리해야 하지?”
• “리뷰 코멘트… 또 반영하고 답글 달아야 하지?”

문제는 이 작업들이 매번 조금씩 다르지만, 패턴은 거의 동일하다는 겁니다. 그래서 저는 Claude Code의 Custom Commands 기능을 이용해, 반복되는 흐름을 명령어 5개로 고정해버렸습니다.

이 글에서는 “어떤 명령어를 어떻게 묶어서” 개발 워크플로우 전체를 자동화했는지, 그리고 왜 이 방식이 생각보다 강력했는지를 벨로그 스타일로 편하게 공유해볼게요.

Claude Code의 Custom Commands란?

Claude Code에서는 .claude/commands/ 폴더에 마크다운 파일을 만들어두면, 터미널에서 /명령어 형태로 실행할 수 있어요.

.claude/
└── commands/
    ├── spec.md          # /spec으로 실행
    ├── create-jest.md   # /create-jest로 실행
    ├── w-context.md     # /w-context로 실행
    ├── pr.md            # /pr로 실행
    └── apply-review.md  # /apply-review로 실행

포인트는 이겁니다.

“스크립트를 짜는 게 아니라, 작업 지시서를 마크다운으로 적는다.”

즉, 마크다운 안에 자연어로 “이 상황에서는 이렇게 분석하고, 이런 규칙을 따라, 이런 결과를 만들어줘” 라고 적어두면 Claude가 그걸 그대로 실행 가능한 워크플로우로 돌려줍니다.

내가 자동화한 개발 워크플로우 (한 장 요약)

제가 만든 명령어 5개는 개발 사이클을 처음부터 끝까지 커버합니다.

기능 명세서 작성
      ↓
  ① /spec         →  명세서 기반 코드 구현
      ↓
  ② /create-jest  →  테스트 코드 자동 생성
      ↓
  ③ /w-context    →  AI용 문서(CONTEXT.md) 작성
      ↓
  ④ /pr           →  커밋 & PR 생성
      ↓
  ⑤ /apply-review →  코드 리뷰 자동 반영

여기서 중요한 건, 이 흐름이 “AI가 똑똑해서 알아서”가 아니라 명령어마다 역할과 규칙을 명확히 분리해두었기 때문에 안정적으로 돌아간다는 점이에요.

그럼 각각을 짧게 살펴볼게요.

1) /spec — 명세서 기반 코드 구현

한 줄 요약: 명세서를 주면, 구현을 “절차적으로” 끝냅니다.

/spec user-auth  # specs/user-auth.md를 읽고 구현

specs/ 폴더에 기능 명세서를 마크다운으로 작성해두면, Claude가 아래처럼 단계적으로 구현합니다.

• Phase 0: 명세서 로드
• Phase 1: 명세서 분석 및 이해
• Phase 2: 구현 전 검토 (질문 필요 시)
• Phase 3: 구현 계획 수립
• Phase 4: 코드 구현
• Phase 5: 검증 (타입 체크, 린트)

제가 느낀 체감 포인트는 두 가지였어요.

• “바로 코딩”이 아니라 “이해→계획→구현→검증”이 강제됨
• 결과가 코드만 던지고 끝이 아니라, 생성 파일/검증 결과/사용 예시까지 보고서처럼 나옴

즉, 단순 생성기가 아니라 “개발 프로세스”를 명령어에 박아둔 느낌입니다.

2) /create-jest — 테스트 코드 자동 생성

한 줄 요약: git diff 기준으로 바뀐 파일을 잡고 테스트를 만들어줍니다.

/create-jest  # git diff 기반으로 테스트 대상 파일 자동 감지

특히 마음에 들었던 건 “테스트 대상 선정”을 규칙으로 박아둔 부분이에요.

• libs/, hooks/, utils/, services/ 등 테스트 대상 폴더를 정의
• __tests__/에 테스트 파일 생성
• 테스트명은 한글로 (it("사용자를 생성한다", ...))
• AAA 패턴(Arrange-Act-Assert) 적용

이렇게 해두면, 테스트를 “쓸지 말지 고민”하는 단계가 줄어듭니다. 그냥 변경되면 → 테스트가 생깁니다.

3) /w-context — AI를 위한 문서(CONTEXT.md) 작성

한 줄 요약: 주석 대신, “모듈의 설계 의도”를 문서로 남깁니다.

/w-context  # 현재 폴더에 CONTEXT.md 생성

이건 생각보다 효과가 컸어요. 코드는 시간이 지나면 “왜 이렇게 했지?”가 남는데, 그걸 보통 주석이나 위키로 해결하려다 실패하잖아요.

/w-context는 아예 AI가 다음 수정 때 읽을 문서를 만들어줍니다.

• 이 모듈이 하는 일 (한 문장)
• 파일 구조와 역할
• 핵심 설계 결정
• 사용 패턴 예시
• 확장 시 고려사항

결과적으로 다음 작업에서 Claude가 맥락을 먼저 잡고 들어오니까, 수정 품질이 확 좋아지더라고요.

4) /pr — 커밋 & PR 생성

한 줄 요약: 변경사항을 분석해서 “커밋하고 PR까지” 올려줍니다.

/pr  # 자동으로 브랜치 생성, 커밋, PR 생성

PR은 사실 코딩보다도 피로도가 큰 작업이죠.

• 브랜치 이름 자동 생성 (feature/, fix/, hotfix/)
• 변경사항을 논리 단위로 나눠 커밋
• PR 제목/본문 자동 작성
• gh CLI로 GitHub 연동

커밋 메시지 포맷도 프로젝트 규칙으로 고정했습니다.

[카테고리] 작업 제목

작업 설명 (복잡한 변경일 경우에만)

이렇게 해두면 PR 품질이 개인 컨디션에 따라 흔들리지 않습니다. “늘 일정한 수준”으로 나오는 게 팀에서는 진짜 큰 장점이에요.

5) /apply-review — 코드 리뷰 자동 반영

한 줄 요약: 리뷰 코멘트를 읽고 “반영/거절/답글”까지 처리합니다.

/apply-review  # 현재 브랜치의 PR 리뷰를 가져와서 처리

제가 이 명령어에서 제일 중요하게 둔 건 “무조건 반영”이 아니라, 판단 기준을 넣는 것이었습니다.

적용하는 경우

• 버그 지적, 보안 이슈, 성능 문제
• 코드 컨벤션 위반, 가독성 개선

거절하는 경우

• 단순 취향 차이
• 과도한 추상화 요청
• PR 범위를 벗어난 리팩토링 요청

그리고 반영 후엔 PR에 자동으로 답글도 남깁니다.

• “반영했습니다”
• 혹은 “이번 PR 범위를 넘어선 변경이라 다음 작업으로 분리하겠습니다” 같은 거절 사유

리뷰 대응에서 에너지가 많이 빠지는데, 이걸 “규칙화” 해두니까 팀 커뮤니케이션도 훨씬 매끄러워졌어요.

왜 이 방식이 효과적이었나

1) 자연어로 정의되는 “팀의 규칙”

스크립트는 유지보수 비용이 커요. 그런데 마크다운 지시서는 읽고 고치기 쉬워서 팀 규칙을 담기에 좋습니다.

2) 프로젝트 맞춤형 커스터마이징이 쉬움

• 커밋 메시지 규칙
• 폴더 구조
• 테스트 스타일(한글 테스트명, AAA 패턴)

이런 것들이 “우리 팀 방식”인데, 명령어로 고정해두면 신규 인원 온 날부터 바로 맞춰집니다.

3) 개선 루프가 빠름

명령어가 마음에 안 들면?

• .md 파일 열고
• 문장 몇 줄 고치고
• 다시 실행

피드백 반영 속도가 빨라서 “우리 팀에 맞는 자동화”로 점점 진화합니다.

4) 공유가 쉽다

.claude/commands/를 Git에 올리면 끝입니다. 온보딩 문서에 “이거 하세요” 적는 것보다, 명령어로 강제하는 게 더 강력하더라고요.

시리즈 안내

이 글은 전체 개요이고, 다음 글부터는 각 명령어를 더 깊게 파볼 예정입니다.

마치며

Custom Commands는 “AI 기능”이라기보다, 제게는 개발 프로세스를 마크다운으로 코드화하는 도구처럼 느껴졌습니다.

• 반복 작업을 줄이는 수준을 넘어서
• 팀의 컨벤션과 판단 기준을 명령어로 고정하고
• 결과 품질을 일정하게 만들 수 있었거든요.

다음 글에서는 가장 핵심인 /spec를 깊게 다뤄보겠습니다. 명세서를 어떻게 써야 Claude가 덜 헤매는지, 그리고 실제로 어떤 흐름으로 구현이 진행되는지 예시까지 포함해서 정리해볼게요.

10. 🧪 링크 드라퍼, 정식 출시!

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있어요.

🔗 빠르고 간편한 링크 저장 iOS/Android 앱, 웹, 크롬 익스텐션 어디서든 바로 저장 🧠 폴더별로 깔끔하게 정리 읽을 거리, 레퍼런스, 쇼핑 후보까지 주제별 정리 🌐 폴더를 친구에게 공유 같이 보는 자료는 폴더 단위로 링크 한 번에 공유 ⚡ 크롬 익스텐션 원클릭 저장 지금 보고 있는 페이지를 버튼 한 번으로 저장

👉 링크 드라퍼 앱 다운로드 (iOS) 👉 링크 드라퍼 웹에서 사용하러 가기 👉 크롬 웹스토어에서 익스텐션 설치하기

앱을 조금만 운영해 보면 금방 이런 생각이 듭니다.

1. “아… 이 버그 오늘 안에라도 고치고 싶은데, 스토어 심사는 너무 느리다.”
2. “이 구버전은 진짜 더 이상 쓰면 안 되는데… 강제로라도 막고 싶다.”

Expo를 쓴다면 이 두 가지는 이렇게 나뉩니다.

• OTA(Over-The-Air) 업데이트 → EAS Update로 JS 번들을 즉시 교체
• 네이티브(스토어) 업데이트 → App Store / Play Store 심사를 거치는 일반적인 업데이트

Link Dropper 앱에서는 이 두 가지를 동시에 가져가는 구조를 만들었습니다.

• JS 코드, UI, 로직은 EAS Update(OTA)로 빠르게 수정
• 꼭 막아야 하는 구버전은 서버에서 “최소 지원 버전”을 내려서 강제 업데이트

이 글에서는 그 구조를 처음부터 끝까지 한 번에 정리해 봅니다.

2. OTA vs 네이티브 업데이트, 경계 어디까지?

먼저, 어떤 변경을 어디서 처리해야 할지 기준을 세워야 합니다.

2-1. OTA 업데이트 (EAS Update)

• 변경 가능 범위

  • JavaScript 코드
  • React 컴포넌트
  • 이미지 등 번들에 포함된 에셋

• 배포 속도

  • 거의 즉시 (스토어 심사 없음)

• 언제 쓰는가

  • 버그 수정
  • UI/UX 개선
  • 비즈니스 로직 수정

2-2. 네이티브 업데이트 (스토어 배포)

• 변경 가능 범위

  • 네이티브 코드 (Swift, Kotlin, 네이티브 모듈)
  • Expo SDK 버전 업그레이드
  • 권한 추가/변경 (예: 푸시, 위치, 카메라)

• 배포 속도

  • 심사 + 전파 시간: 1~7일 정도

• 언제 쓰는가

  • 새로운 네이티브 기능 도입
  • SDK 버전 올리기
  • 빌드 세팅 변경

정리하면: OTA로 가능한 건 일단 OTA로 빠르게. 네이티브/SDK/권한이 엮이면 스토어로 정식 배포.

3. “필수 업데이트”는 왜, 언제 필요한가

OTA만으로는 해결할 수 없는 상황이 분명 존재합니다.

• 서버 API가 크게 바뀌어서 → 이전 버전이 더 이상 정상 동작하지 않을 때
• 심각한 보안 취약점이 발견되어 → 특정 버전 이상만 쓰게 강제해야 할 때
• 네이티브 기능이 필수인데 → 해당 기능이 없는 옛 빌드를 막고 싶을 때

이럴 땐 결국 이렇게 해야 합니다.

1. 스토어에 새로운 버전을 올리고
2. 서버에서 “최소 지원 버전”을 올리고
3. 그보다 낮은 버전의 앱은 → 강제 업데이트 알럿만 띄우고, 정상 사용은 막는다

이 글에서 설명하는 구조가 바로 이 부분을 담당합니다.

4. 전체 흐름 한 번에 보기

먼저, 앱 시작 시 전체 흐름은 이렇게 설계했습니다.

[앱 시작]
      │
      ▼
1. 서버에서 최소 지원 버전 조회
   (GET /app-config/version)
      │
      ▼
2. 현재 앱 버전 < 최소 버전 ?
      │
  ┌───┴──────────────┐
 YES                  NO
  │                   │
  ▼                   ▼
[강제 업데이트 알럿]   3. OTA 업데이트 확인
(스토어로 이동)          (Updates.checkForUpdateAsync)
                      │
                      ▼
              [업데이트 있음? → 다음 실행 시 적용]

즉, “필수 업데이트 체크”를 먼저 하고, 통과하면 그 다음에 OTA 업데이트를 확인합니다.

5. EAS Update 기본 세팅

5-1. app.json / app.config 설정

{
  "expo": {
    "runtimeVersion": {
      "policy": "appVersion"
    },
    "updates": {
      "url": "https://u.expo.dev/[프로젝트 ID]"
    }
  }
}

• runtimeVersion.policy: "appVersion" → “앱 버전(예: 1.2.0)이 같은 앱끼리만 같은 OTA 업데이트를 받는다”는 정책 → 네이티브가 바뀌면 앱 버전을 올려야 한다고 이해하면 됩니다.

5-2. eas.json 설정

{
  "cli": {
    "appVersionSource": "remote"
  },
  "build": {
    "production": {
      "autoIncrement": true,
      "channel": "production"
    }
  }
}

• channel: OTA 업데이트를 적용할 채널 이름
• autoIncrement: 빌드 번호 자동 증가

6. 서버에서 “최소 지원 버전” 관리하기

필수 업데이트를 위해서는 서버가 “이 버전 미만은 막아라”를 알고 있어야 합니다.

6-1. 응답 타입 설계

// GET /app-config/version

interface ServerVersionResponse {
  ios: string;      // iOS 최소 버전 (예: "1.2.0")
  android: string;  // Android 최소 버전 (예: "1.1.0")
  updatedAt: string;
}

6-2. 예시 응답 JSON

{
  "ios": "1.2.0",
  "android": "1.1.0",
  "updatedAt": "2024-12-15T10:00:00Z"
}

• 플랫폼별로 따로 두면 → iOS/Android 배포 속도가 달라도 유연하게 대응할 수 있습니다.

7. 버전 비교 유틸리티

버전 비교는 결국 1.2.3 형식의 문자열을 숫자로 쪼개서 비교하는 방식으로 구현했습니다.

// libs/utils/version/index.ts

export const isVersionSufficient = (current: string, minimum: string): boolean => {
  const currentParts = current.split('.').map(Number);
  const minParts = minimum.split('.').map(Number);

  for (let i = 0; i < 3; i++) {
    const curr = currentParts[i] || 0;
    const min = minParts[i] || 0;

    if (curr > min) return true;
    if (curr < min) return false;
  }

  return true; // 같으면 충분
};

export const isValidVersion = (version: string): boolean => {
  const versionRegex = /^\d+\.\d+\.\d+$/;
  return versionRegex.test(version);
};

• isVersionSufficient → current >= minimum 이면 true
• isValidVersion → x.y.z 패턴인지 간단히 검증

8. UpdateManager: 업데이트 체크의 허브

이제 실제로 “앱 시작 시 한 번만 부르면 되는 함수”를 만드는 단계입니다.

8-1. 타입 정의

// types/config.ts

export type UpdateStatus =
  | 'UP_TO_DATE'
  | 'NATIVE_UPDATE_REQUIRED'
  | 'OTA_UPDATE_AVAILABLE'
  | 'ERROR';

export interface UpdateCheckResult {
  status: UpdateStatus;
  currentVersion?: string;
  minimumVersion?: string;
  error?: Error;
}

8-2. 현재 버전 & 최소 버전 가져오기

import * as Application from 'expo-application';
import { Platform } from 'react-native';

const getCurrentVersion = (): string => {
  return Application.nativeApplicationVersion || '0.0.0';
};

const selectMinimumVersion = (config: ServerVersionResponse): string | undefined => {
  return Platform.select({
    ios: config.ios,
    android: config.android,
  });
};

8-3. 네이티브(스토어) 업데이트 필요 여부 체크

const checkNativeUpdate = async (): Promise<UpdateCheckResult> => {
  try {
    const config = await fetchMinimumVersion(); // 서버 API 호출
    const minVersion = selectMinimumVersion(config);
    const currentVersion = getCurrentVersion();

    if (!minVersion || !isValidVersion(minVersion)) {
      // 서버가 이상한 값을 주면 일단 통과 (Fail-Open)
      return { status: 'UP_TO_DATE', currentVersion };
    }

    if (!isVersionSufficient(currentVersion, minVersion)) {
      return {
        status: 'NATIVE_UPDATE_REQUIRED',
        currentVersion,
        minimumVersion: minVersion,
      };
    }

    return { status: 'UP_TO_DATE', currentVersion, minimumVersion: minVersion };
  } catch (error) {
    // 네트워크 오류 시에도 앱은 사용 가능하게 둔다 (Fail-Open)
    return {
      status: 'ERROR',
      error: error instanceof Error ? error : new Error('Unknown error'),
    };
  }
};

9. Fail-Open 정책: 서버 장애에도 앱은 살아 있어야 한다

업데이트 체크 중에 에러가 나면 어떻게 할까요?

9-1. 두 가지 선택지

• Fail-Close

  • “버전 체크에 실패했으니, 위험하니 앱을 막자”
  • 보안/규제 산업에서는 타당한 선택

• Fail-Open

  • “버전 체크에 실패했지만, 일단 앱은 쓰게 하자”
  • UX와 가용성에 더 무게를 둔 선택

Link Dropper에서는 Fail-Open을 선택했습니다.

const checkAppUpdates = async (): Promise<void> => {
  const nativeResult = await checkNativeUpdate();

  if (nativeResult.status === 'NATIVE_UPDATE_REQUIRED') {
    showForceUpdateAlert();
    return;
  }

  // 에러가 나도 앱은 계속 사용 가능
  if (nativeResult.status === 'ERROR') {
    console.warn('Native version check failed, but continuing (Fail-Open)');
  }

  // OTA 업데이트 체크
  await checkAndApplyOTAUpdate();
};

이유는 간단합니다.

• 서버가 잠깐 터졌다고 전체 앱이 “열리지 않는 서비스”가 되는 건 → 작은 팀에게 치명적
• “업데이트 강제”보다 더 큰 악영향은 → “앱 자체가 안 열리는 경험”

보안 등급이 높은 서비스라면 반대 선택을 할 수도 있습니다. 중요한 건 정책을 의식적으로 선택하는 것.

10. OTA 업데이트 체크 & 적용

이제 OTA 쪽입니다.

import * as Updates from 'expo-updates';

const checkAndApplyOTAUpdate = async (): Promise<UpdateCheckResult> => {
  try {
    const update = await Updates.checkForUpdateAsync();

    if (!update.isAvailable) {
      return { status: 'UP_TO_DATE' };
    }

    // 백그라운드에서 다운로드
    await Updates.fetchUpdateAsync();

    // 기본 전략: 다음 앱 실행 시 적용
    return { status: 'OTA_UPDATE_AVAILABLE' };
  } catch (error) {
    return {
      status: 'ERROR',
      error: error instanceof Error ? error : new Error('Unknown error'),
    };
  }
};

만약 “지금 당장 바로 적용하고 싶다”면:

// 즉시 재시작 (사용자 경험에 주의)
await Updates.reloadAsync();

• 스플래시 화면이 다시 뜨고 앱이 새로 부팅되는 느낌이 나기 때문에 → 사용자에게 한 번은 안내해 주는 편이 좋습니다.

11. 강제 업데이트 알럿 UX

이제 스토어 업데이트가 ‘필수’일 때 띄우는 알럿입니다.

import { Alert, AppState, Linking } from 'react-native';

const STORE_URL = 'https://appstore.com/your-app'; // 실제 스토어 URL

const showForceUpdateAlert = (): void => {
  Alert.alert(
    '업데이트 필요',
    '새로운 버전이 출시되었습니다. 계속 사용하려면 앱을 업데이트해 주세요.',
    [
      {
        text: '업데이트',
        onPress: () => {
          // 스토어로 이동
          Linking.openURL(STORE_URL);

          // 스토어 다녀와서도 여전히 구버전이면 다시 알럿
          const subscription = AppState.addEventListener('change', async (nextState) => {
            if (nextState === 'active') {
              subscription.remove();
              const result = await checkNativeUpdate();
              if (result.status === 'NATIVE_UPDATE_REQUIRED') {
                showForceUpdateAlert();
              }
            }
          });
        },
      },
    ],
    { cancelable: false }, // 뒤로가기/바깥 터치로 닫기 불가
  );
};

포인트는 세 가지입니다.

1. 취소 버튼이 없다 → 이번 세션에서는 반드시 업데이트를 유도
2. 스토어 → 다시 돌아온 뒤에도 재검사 → 진짜로 업데이트가 되었는지 확인
3. 최소 버전은 서버에서 관리 → 비즈니스/CS 상황에 따라 언제든 조정 가능

12. 앱 시작 시 한 번만 호출하면 끝

이제 이 모든 걸 앱 시작 루틴에 한 줄로 넣습니다.

// app/_layout.tsx (또는 App.tsx)

import { useEffect } from 'react';
import { checkAppUpdates } from '@/services/UpdateManager';

export default function RootLayout() {
  useEffect(() => {
    const initialize = async () => {
      await initI18n();

      kakaoAuth.initialize();
      googleAuth.initialize();
      checkAuthStatus();

      // ✅ 여기서 한 번만 호출
      checkAppUpdates();

      setIsInitialized(true);
    };

    initialize();
  }, []);

  // ...
}

이렇게 하면:

1. 앱이 켜질 때
2. 서버에서 최소 버전을 받아와 강제 업데이트 여부 판단
3. 통과하면 OTA 업데이트까지 확인

까지 한 번에 처리됩니다.

13. 실제 운영 시나리오별 대응 방법

이제 운영하면서 자주 만나는 상황별로 어떻게 대응하는지 정리해 봅니다.

13-1. JS 코드만 바꿔도 되는 “긴급 버그”

# 코드 수정 후
eas update --channel production --message "긴급 버그 수정"

• 스토어 심사 없이 바로 배포
• 사용자는 앱을 재시작하는 순간 최신 로직으로 동작

13-2. 네이티브 라이브러리 추가 / SDK 업그레이드

# 1. app.json에서 앱 버전 올리기
# 2. 새 빌드 생성
eas build --platform all --profile production

# 3. 스토어 제출
eas submit --platform all

# 4. 필요한 시점에 서버의 최소 버전 업데이트

• “이전 버전은 절대 쓰면 안 된다” 수준이 아닐 땐 → 최소 버전 업데이트 시점은 조금 여유롭게 잡을 수도 있습니다.

13-3. 보안 이슈로 특정 버전 강제 차단

1. 새 버전 빌드 & 스토어 배포
2. 스토어 전파가 어느 정도 완료되면
3. 서버 DB에서 ios / android 최소 버전을 새 버전으로 업데이트
4. 이후 구버전 사용자는 앱 실행 시 알럿만 보고 막히게 됨

14. 한 장으로 정리

Expo의 EAS Update와 서버 기반 버전 관리를 조합하면,

• 배포 속도와
• 버전 통제를 둘 다 어느 정도 만족시키는 구조를 만들 수 있습니다.

🧪 링크 드라퍼, 정식 출시!

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있어요.

• 🔗 빠르고 간편한 링크 저장 iOS/Android 앱, 웹, 크롬 익스텐션 어디서든 바로 저장
• 🧠 폴더별로 깔끔하게 정리 읽을 거리, 레퍼런스, 쇼핑 후보까지 주제별 정리
• 🌐 폴더를 친구에게 공유 같이 보는 자료는 폴더 단위로 링크 한 번에 공유
• ⚡ 크롬 익스텐션 원클릭 저장 지금 보고 있는 페이지를 버튼 한 번으로 저장

👉 링크 드라퍼 앱 다운로드 (iOS) 👉 링크 드라퍼 웹에서 사용하러 가기 👉 크롬 웹스토어에서 익스텐션 설치하기

이 글은 “링크 저장 앱”을 만들면서 iOS Share Extension + Android 공유 인텐트를 붙인 개발기입니다. Expo 쓰면서 “이거 되는 게 맞나…?” 했던 분들 대상으로 씁니다.

0. 문제의식: 왜 굳이 Share Extension까지?

링크 저장 앱을 만들다 보면 이런 UX가 꼭 필요해집니다.

1. Safari / Chrome에서 글을 읽다가
2. 🔘 공유 버튼 → 공유 시트 열고
3. 우리 앱 아이콘을 누르면
4. 바로 ‘링크 저장’ 화면이 뜨고, 앱 전환 없이 저장 끝 ✅

iOS에서는 이걸 Share Extension, Android에서는 Share Intent로 구현합니다.

이 글에서는 Expo(Managed + EAS Build) 환경에서

• iOS: expo-share-extension으로 커스텀 Share UI 만들고
• Android: expo-share-intent로 공유 인텐트 처리

까지 실제로 동작하는 구조를 예시 코드로 정리합니다.

1. Share Extension 한 줄 정의

“다른 앱에서 공유한 데이터를 받아, 작은 별도 프로세스로 처리하는 iOS 확장 앱”

특징만 요약하면:

1. 독립 프로세스

   • 메인 앱과 완전히 분리된 Target / 프로세스로 돌아감

2. 리소스 제한

   • 메모리·시간 제한이 있어서, 무거운 작업(대량 이미지 분석 등)은 매우 비추천

3. 공유 스토리지 필요

   • 메인 앱과 로그인 상태/데이터를 공유하려면

     • App Group / Keychain Access Group 같은 iOS 메커니즘을 써야 함

2. 어떤 라이브러리를 쓸 것인가

Expo에서 “다른 앱 → 우리 앱” 공유를 받으려면, 기본 expo-sharing으로는 안 됩니다. 공식 문서에도 “다른 앱에서 우리 앱으로 공유 받는 건 지원 안 함”이라고 박혀 있습니다.

그래서 커뮤니티 라이브러리를 씁니다.

2-1. 사용한 라이브러리

// package.json (예시)
{
  "dependencies": {
    "expo-share-extension": "^5.0.0",
    "expo-share-intent": "^5.1.0"
  }
}

버전은 예시입니다. 실제 프로젝트에서는 Expo SDK 버전에 맞는 버전 매트릭스를 꼭 확인하세요.

2-2. 역할 분담

이번 구조는 이렇게 가져갑니다.

• iOS

  • expo-share-extension으로 커스텀 Share Extension

• Android

  • expo-share-intent로 공유 인텐트 → 메인 앱 라우팅

3. app.json / app.config 설정

3-1. 기본 Expo 설정 (예시)

// app.json (예시용)
{
  "expo": {
    "name": "MyLinkBox",
    "slug": "my-link-box",
    "scheme": "mylinkbox",
    "ios": {
      "bundleIdentifier": "com.mycompany.mylinkbox",
      "entitlements": {
        "com.apple.security.application-groups": [
          "group.com.mycompany.mylinkbox"
        ],
        "keychain-access-groups": [
          "ABCDE12345.*"
        ]
      }
    },
    "android": {
      "package": "com.mycompany.mylinkbox",
      "intentFilters": [
        {
          "action": "android.intent.action.SEND",
          "category": ["android.intent.category.DEFAULT"],
          "data": { "mimeType": "text/plain" }
        }
      ]
    },
    "plugins": [
      [
        "expo-share-extension",
        {
          "activationRules": [
            { "type": "url", "max": 1 },
            { "type": "text" }
          ],
          "backgroundColor": {
            "red": 255,
            "green": 255,
            "blue": 255,
            "alpha": 1
          },
          "appGroupIdentifier": "group.com.mycompany.mylinkbox"
        }
      ],
      [
        "expo-share-intent",
        {
          // iOS는 커스텀 Share Extension을 쓸 거라서 비활성화
          "disableIOS": true,
          "androidIntentFilters": ["text/*"],
          "androidMultiIntentFilters": []
        }
      ]
    ]
  }
}

3-2. 핵심 옵션 해설

🔸 activationRules (expo-share-extension)

iOS의 NSExtensionActivationRules를 추상화해 둔 옵션입니다.

"activationRules": [
  { "type": "url", "max": 1 },
  { "type": "text" }
]

• type: "url"

  • Safari에서 페이지 공유 시, URL이 있을 때 활성화

• type: "text"

  • 선택한 텍스트 공유에도 반응 (텍스트 안에 URL이 섞인 케이스까지 케어하고 싶을 때 유용)

• max

  • 동시에 받을 수 있는 항목 개수 (지정 안 하면 기본값 1)

🔸 appGroupIdentifier

"appGroupIdentifier": "group.com.mycompany.mylinkbox"

• 메인 앱 / Share Extension이 같이 쓰는 App Group ID
• 이 그룹 안의 공유 컨테이너에 파일·데이터를 같이 저장할 수 있습니다.

🔸 entitlements.keychain-access-groups

"keychain-access-groups": [
  "ABCDE12345.*"
]

• iOS Keychain 공유를 위한 그룹
• 실제로는 ABCDE12345.group.com.mycompany.mylinkbox 처럼 팀 ID + 그룹명 형태를 더 엄밀히 쓰기도 합니다.
• 글에서는 예시라 ABCDE12345.* 처럼 단순화했습니다.

🔸 expo-share-intent의 disableIOS

expo-share-intent는 기본적으로 iOS/Android 모두에 확장을 추가하지만, 우리는 iOS에서 expo-share-extension을 따로 쓰므로 iOS 쪽은 꺼 줍니다.

4. iOS Share Extension UI 만들기

4-1. 엔트리 포인트: index.share.js

// index.share.js
import { AppRegistry } from 'react-native';
import ShareExtension from './ShareExtension';

// 👇 이름은 반드시 "shareExtension"
AppRegistry.registerComponent('shareExtension', () => ShareExtension);

AppRegistry.registerComponent의 첫 번째 인자가 반드시 "shareExtension" 이어야 합니다.

4-2. ShareExtension 컴포넌트 (예시 버전)

// ShareExtension.tsx (예시)
import React, { useEffect, useState } from 'react';
import { InitialProps, close } from 'expo-share-extension';
import {
  View,
  Text,
  Button,
  ActivityIndicator,
  StyleSheet,
  TouchableOpacity,
} from 'react-native';

// ───────────────────────
// 1. 예시용 유틸 / API
// ───────────────────────
async function getAuthTokenFromSecureStore(): Promise<string | null> {
  // 실제 앱에서는 expo-secure-store + accessGroup 사용
  return 'dummy-token';
}

type Folder = { id: string; name: string };

async function fetchFolderList(token: string): Promise<Folder[]> {
  console.log('fetch folder with token', token);
  return [
    { id: 'inbox', name: '📥 인박스' },
    { id: 'read-later', name: '나중에 읽기' },
  ];
}

function extractUrlFromSharedContent(text?: string | null): string | null {
  if (!text) return null;
  const match = text.match(/https?:\/\/\S+/);
  return match ? match[0] : null;
}

function isValidUrl(url: string | null): boolean {
  if (!url) return false;
  try {
    new URL(url);
    return true;
  } catch {
    return false;
  }
}

async function saveLinkToServer(params: {
  url: string;
  folderId: string | null;
  token: string;
}) {
  console.log('save link', params);
  // 실제 앱에서는 여기서 API 호출
}

// ───────────────────────
// 2. ShareExtension UI
// ───────────────────────
type Props = InitialProps;

export default function ShareExtension(props: Props) {
  const { url, text } = props;

  const [token, setToken] = useState<string | null>(null);
  const [folders, setFolders] = useState<Folder[]>([]);
  const [selectedFolder, setSelectedFolder] = useState<Folder | null>(null);
  const [saving, setSaving] = useState(false);
  const [saved, setSaved] = useState(false);

  const sharedUrl = extractUrlFromSharedContent(url || text);

  useEffect(() => {
    (async () => {
      const t = await getAuthTokenFromSecureStore();
      setToken(t);
      if (!t) return;

      const list = await fetchFolderList(t);
      setFolders(list);
      setSelectedFolder(list[0] ?? null);
    })();
  }, []);

  const handleSave = async () => {
    if (!token) return;
    if (!isValidUrl(sharedUrl)) return;

    try {
      setSaving(true);
      await saveLinkToServer({
        url: sharedUrl!,
        folderId: selectedFolder?.id ?? null,
        token,
      });
      setSaved(true);

      setTimeout(() => {
        close(); // 1.5초 후 Share Extension 닫기
      }, 1500);
    } finally {
      setSaving(false);
    }
  };

  if (!token) {
    return (
      <View style={styles.container}>
        <Text style={styles.title}>로그인이 필요합니다</Text>
        <Text style={styles.subtitle}>
          앱에서 먼저 로그인한 뒤 다시 공유해주세요.
        </Text>
        <Button title="닫기" onPress={close} />
      </View>
    );
  }

  return (
    <View style={styles.container}>
      <Text style={styles.title}>링크 저장하기</Text>
      <Text style={styles.subtitle}>
        {isValidUrl(sharedUrl) ? sharedUrl : '유효한 URL이 없습니다.'}
      </Text>

      {/* 폴더 선택 (예시) */}
      <View style={{ marginVertical: 12 }}>
        {folders.map((folder) => (
          <TouchableOpacity
            key={folder.id}
            style={[
              styles.folderItem,
              folder.id === selectedFolder?.id && styles.folderItemSelected,
            ]}
            onPress={() => setSelectedFolder(folder)}
          >
            <Text>{folder.name}</Text>
          </TouchableOpacity>
        ))}
      </View>

      {saving ? (
        <ActivityIndicator />
      ) : saved ? (
        <Text>저장 완료! 🎉</Text>
      ) : (
        <Button
          title="저장하기"
          onPress={handleSave}
          disabled={!isValidUrl(sharedUrl)}
        />
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 16,
    backgroundColor: '#fff',
    justifyContent: 'flex-start',
  },
  title: {
    fontSize: 18,
    fontWeight: '600',
  },
  subtitle: {
    marginTop: 8,
    color: '#555',
  },
  folderItem: {
    paddingVertical: 8,
    paddingHorizontal: 12,
    borderRadius: 8,
    borderWidth: 1,
    borderColor: '#ddd',
    marginBottom: 8,
  },
  folderItemSelected: {
    borderColor: '#4f46e5',
    backgroundColor: '#eef2ff',
  },
});

4-3. UX 핵심 포인트

1. 토큰 없이 들어온 경우

   • “로그인 필요” 메시지 + 닫기 버튼만 보여줌

2. URL 추출

   • props.url이 없고 텍스트만 올 수도 있으니 text에서도 정규식으로 URL 추출

3. 저장 후 자동 닫기

   • 저장 완료 → 짧게 피드백 → close() 호출로 Share Extension 종료

5. 인증 토큰 공유: SecureStore + Keychain Access Group

실제 서비스에서는 “Extension에서도 인증된 사용자로 API를 호출”해야 합니다. 이걸 해결하기 위해 iOS Keychain 공유를 씁니다.

5-1. 예시 코드

// secureStore.ts (예시)
import * as SecureStore from 'expo-secure-store';

const TOKEN_KEY = 'MY_APP_AUTH_TOKEN';
// 실제 프로젝트에서는 팀 ID가 포함된 값 사용 권장
const ACCESS_GROUP = 'ABCDE12345.*';

export async function saveAuthToken(token: string) {
  await SecureStore.setItemAsync(TOKEN_KEY, token, {
    accessGroup: ACCESS_GROUP,
  });
}

export async function getAuthToken() {
  try {
    const token = await SecureStore.getItemAsync(TOKEN_KEY, {
      accessGroup: ACCESS_GROUP,
    });
    return token;
  } catch (e) {
    console.error('failed to get token', e);
    return null;
  }
}

⚠️ 주의

• 실제 앱에선 keychain-access-groups entitlement와 accessGroup 값이 서로 일관되게 설정되어야 합니다.
• 팀 ID 접두(ABCDE12345.)를 어떻게 붙일지는 프로젝트마다 다를 수 있어서, 여기선 의도만 보이는 예시로 적었습니다.

6. Android: Intent Filter + expo-share-intent

Android는 Share Extension이 따로 없고, Intent Filter를 매니페스트(app.json)로 설정한 뒤, expo-share-intent 훅으로 데이터를 받습니다.

6-1. Android intentFilters (app.json 예시)

"android": {
  "intentFilters": [
    {
      "action": "android.intent.action.SEND",
      "category": ["android.intent.category.DEFAULT"],
      "data": {
        "mimeType": "text/plain"
      }
    }
  ]
}

6-2. 공유 데이터 처리 (Expo Router 예시)

// app/_layout.tsx (혹은 App.tsx)
import { useEffect } from 'react';
import { Platform } from 'react-native';
import { useRouter } from 'expo-router';
import { useShareIntent } from 'expo-share-intent';

export default function RootLayout() {
  const router = useRouter();
  const { hasShareIntent, shareIntent, resetShareIntent } = useShareIntent();

  useEffect(() => {
    if (Platform.OS !== 'android') return;
    if (!hasShareIntent || !shareIntent) return;

    const url = shareIntent.webUrl ?? shareIntent.text;
    if (!url) return;

    // 공유된 URL을 저장 화면으로 라우팅
    router.push({
      pathname: '/save',
      params: { url },
    });

    resetShareIntent();
  }, [hasShareIntent, shareIntent]);

  return (
    // ... 실제 앱 네비게이션/레이아웃
    null
  );
}

expo-share-intent는 네이티브 모듈이라 Expo Go에서는 동작하지 않고, 반드시 prebuild + dev client / EAS Build 환경에서 테스트해야 합니다.

7. 네이티브 코드 개념만 살짝 보기 (Swift 예시)

expo-share-extension을 쓰면 iOS 타겟/Swift 코드는 플러그인이 알아서 생성해 줍니다. 관심 있는 부분만 추상화해서 보면 대략 이런 구조입니다.

// ShareExtensionViewController.swift (개념 예시)
class ShareExtensionViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()
    loadReactNativeContent()
  }

  private func loadReactNativeContent() {
    getShareData { [weak self] sharedData in
      guard let self = self else { return }

      let rootView = reactNativeFactory!.rootViewFactory.view(
        withModuleName: "shareExtension", // index.share.js에서 등록한 이름
        initialProperties: sharedData
      )

      self.view.addSubview(rootView)
      rootView.frame = self.view.bounds
    }
  }

  private func getShareData(completion: @escaping ([String: Any]?) -> Void) {
    guard let items = extensionContext?.inputItems as? [NSExtensionItem] else {
      completion(nil)
      return
    }

    var result: [String: Any] = [:]

    // URL / 텍스트 추출 (단순화 예시)
    for item in items {
      for provider in item.attachments ?? [] {
        if provider.hasItemConformingToTypeIdentifier("public.url") {
          provider.loadItem(forTypeIdentifier: "public.url", options: nil) { value, _ in
            if let url = value as? URL {
              result["url"] = url.absoluteString
            }
            completion(result)
          }
        } else if provider.hasItemConformingToTypeIdentifier("public.text") {
          provider.loadItem(forTypeIdentifier: "public.text", options: nil) { value, _ in
            if let text = value as? String {
              result["text"] = text
            }
            completion(result)
          }
        }
      }
    }
  }

  func close() {
    extensionContext?.completeRequest(returningItems: [], completionHandler: nil)
  }
}

역할은 단순합니다.

1. extensionContext에서 공유된 데이터 파싱
2. React Native shareExtension 모듈을 띄우며 initialProperties로 전달
3. JS에서 close() 호출 시 네이티브에서 completeRequest로 Extension 종료

8. EAS Build에서 App Extension 인식시키기

Expo 공식 문서에 따르면, EAS Build가 app extension 타겟을 제대로 인식하게 하려면 extra.eas.build.experimental.ios.appExtensions 설정을 권장합니다.

{
  "expo": {
    "extra": {
      "eas": {
        "build": {
          "experimental": {
            "ios": {
              "appExtensions": [
                {
                  "targetName": "MyShareExtension",
                  "bundleIdentifier": "com.mycompany.mylinkbox.ShareExtension",
                  "entitlements": {
                    "com.apple.security.application-groups": [
                      "group.com.mycompany.mylinkbox"
                    ]
                  }
                }
              ]
            }
          }
        }
      }
    }
  }
}

• 이 설정이 있으면 EAS가

  • Share Extension용 Provisioning Profile까지 같이 생성해 줘서
  • “iOS 빌드만 돌리면 되게” 도와줍니다.

9. 내용 검증 & 주의할 점 요약

질문 주셨던 “틀린 내용이 있는지” 기준으로 정리하면:

1. expo-share-extension 사용 방식

   • activationRules, appGroupIdentifier, index.share.js에서 "shareExtension" 등록 등은 공식 README와 일치합니다.

2. expo-share-intent 사용 방식

   • useShareIntent 훅 사용, disableIOS, androidIntentFilters 설정 모두 공식 README와 패턴이 동일합니다.

3. “App Group을 통한 데이터 공유”라는 설명

   • iOS에서 메인 앱/Share Extension 사이 데이터 공유는

     • App Group (파일/컨테이너 공유) +
     • Keychain Access Group (SecureStore 등 키체인 공유) 조합으로 구현하는 패턴이 맞습니다.

4. EAS Build + appExtensions 설정

   • extra.eas.build.experimental.ios.appExtensions를 통해 EAS가 미리 extension 정보를 알고 서명/프로비저닝을 처리해 준다는 설명도 최신 Expo 문서와 일치합니다.

5. 토큰 공유 코드에 대한 한 가지 주의

   • 예시에서는 이해를 위해 accessGroup: 'ABCDE12345.*'처럼 단순화했지만,
   • 실제 앱에서는 Apple Team ID + 그룹명이 포함된 정확한 Keychain 그룹 값을 써야 할 수 있습니다.
   • 이 부분은 각자 Apple 계정/기존 앱 구조에 따라 달라서, 글에서는 “패턴만” 보여주는 수준으로 두었습니다.

10. 🧪 링크 드라퍼, 정식 출시!

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있어요.

🔗 빠르고 간편한 링크 저장 iOS/Android 앱, 웹, 크롬 익스텐션 어디서든 바로 저장 🧠 폴더별로 깔끔하게 정리 읽을 거리, 레퍼런스, 쇼핑 후보까지 주제별 정리 🌐 폴더를 친구에게 공유 같이 보는 자료는 폴더 단위로 링크 한 번에 공유 ⚡ 크롬 익스텐션 원클릭 저장 지금 보고 있는 페이지를 버튼 한 번으로 저장

👉 링크 드라퍼 앱 다운로드 (iOS / Android) 👉 링크 드라퍼 웹에서 사용하러 가기 👉 크롬 웹스토어에서 익스텐션 설치하기

링크 드라퍼(Link Dropper)의 탐색 페이지를 개발하면서, 다양한 높이의 콘텐츠를 자연스럽게 정렬하는 Masonry 레이아웃과 무한 스크롤 기능을 구현하게 되었습니다. 단순히 보기 좋은 UI를 넘어서 사용자 경험을 해치지 않고 성능까지 고려한 구조를 만드는 것이 핵심 과제였습니다.

이 글에서는 CSS만으로 구현했던 초기 시도부터 Flexbox 기반의 명시적 레이아웃으로의 전환, 그리고 무한 스크롤과 스켈레톤 로딩까지, 실제 구현 과정과 트러블슈팅 경험을 모두 공유합니다.

프로젝트 요구사항 정리

탐색 기능은 아래와 같은 요구를 충족해야 했습니다:

1. Masonry 레이아웃 (다양한 높이의 링크 카드 배치)
2. 무한 스크롤 (스크롤 시 자동으로 다음 페이지 로드)
3. 반응형 지원 (모바일: 1열, 태블릿: 2열, 데스크톱: 3~4열)
4. 로딩 시 기존 콘텐츠 위치 유지
5. 스켈레톤 UI와 다크모드 지원

기술 스택 선택

TanStack Query (React Query)

무한 스크롤과 서버 상태 관리를 위해 useInfiniteQuery 훅을 사용했습니다.

선택 이유:

• 직관적인 페이지네이션 (getNextPageParam)
• 중복 요청 방지
• 캐싱 및 백그라운드 데이터 업데이트

Intersection Observer API

scroll 이벤트 대신 Intersection Observer를 선택해 뷰포트 진입을 감지했습니다.

선택 이유:

• 메인 스레드 부담이 적음
• 트리거 시점(threshold) 세밀 조정 가능

시도 1: CSS Column 기반 Masonry 레이아웃

간단한 코드로 구현 가능한 column-count 속성을 먼저 사용했습니다.

.ExploreLinkList {
  column-count: 4;
  column-gap: 1.5rem;
}

.card {
  break-inside: avoid;
  margin-bottom: 1rem;
}

문제 발생: 무한 스크롤로 새 아이템이 로드되면 기존 카드들이 다른 컬럼으로 재배치되는 현상이 발생했습니다. 이는 사용자 경험을 해치는 큰 단점이었습니다.

시도 2: Flexbox 기반 명시적 Masonry 레이아웃

이 문제를 해결하기 위해 Flexbox를 사용한 명시적 컬럼 분배 방식으로 전환했습니다.

컬럼 분배 로직 (Round-robin 방식)

export const useMasonryLayout = <T extends { id: number }>(
  items: T[],
  columnCount: number
): T[][] =>
  useMemo(() => {
    const columns: T[][] = Array.from({ length: columnCount }, () => []);

    items.forEach((item, index) => {
      const columnIndex = index % columnCount;
      columns[columnIndex].push(item);
    });

    return columns;
  }, [items, columnCount]);

반응형 대응

useEffect(() => {
  const updateColumnCount = () => {
    if (window.innerWidth <= 480) setColumnCount(1);
    else if (window.innerWidth <= 768) setColumnCount(2);
    else if (window.innerWidth <= 1024) setColumnCount(3);
    else setColumnCount(4);
  };

  updateColumnCount();
  window.addEventListener("resize", updateColumnCount);

  return () => window.removeEventListener("resize", updateColumnCount);
}, []);

Flexbox 레이아웃

.ExploreLinkList {
  display: flex;
  gap: 1.5rem;
  padding: 1.5rem;
  max-width: 73rem;
  margin: 0 auto;
  align-items: flex-start;
}

.column {
  display: flex;
  flex-direction: column;
  flex: 1;
  gap: 1rem;
  min-width: 0;
}

무한 스크롤 구현

Intersection Observer 훅

const observer = new IntersectionObserver(
  (entries) => {
    if (entries[0].isIntersecting) fetchNextPage();
  },
  { threshold: 0.1 }
);

hasNextPage, isFetchingNextPage 조건에 따라 옵저버 등록 여부를 조절합니다.

스켈레톤 로딩 전략

초기 로딩: 실제 컬럼 구조 반영

컬럼 수에 맞게 스켈레톤 아이템 분배.

const loadingColumns = Array.from({ length: columnCount }, (_, i) => i);
const itemsPerColumn = Math.ceil(12 / columnCount);

추가 로딩: 간단한 가로 스켈레톤 4개

별도의 레이아웃 변화 없이 사용자에게 로딩 상태를 전달합니다.

성능 최적화

useMemo로 재연산 최소화

• 평탄화된 링크 배열
• 컬럼 분배 결과

const allLinks = useMemo(() => data?.pages.flatMap(p => p.links) ?? [], [data]);

이벤트 위임

카드 클릭 이벤트를 부모 요소에서 처리하여 리스너를 단 하나로 유지.

React Query 캐싱 전략

staleTime: 5 * 60 * 1000

탐색 페이지 재방문 시 캐시 데이터를 그대로 사용해 UX 개선.

개선 아이디어

1. 스마트한 컬럼 배치

각 컬럼의 총 높이를 추적해 가장 짧은 컬럼에 배치.

const shortestColumnIndex = columnHeights.indexOf(Math.min(...columnHeights));

2. 가상 스크롤 도입

렌더링 성능 개선을 위해 react-window 또는 react-virtual 사용 고려.

3. 낙관적 업데이트

서버 응답 없이 먼저 UI 반영 후, 실패 시 롤백.

마무리하며

이번 구현을 통해 얻은 가장 큰 인사이트는 다음과 같습니다:

• CSS Column은 동적 콘텐츠에 불리하다
• 명시적인 JavaScript 제어가 예측 가능한 레이아웃을 만든다
• 라이브러리 선택이 복잡도를 줄여준다
• 퍼포먼스 최적화는 필수

적용 가능한 사례

• Pinterest/Unsplash 스타일 이미지 갤러리
• 무한 스크롤 기반 블로그/뉴스 피드
• 상품 목록, 게시판 등

🧪 링크 드라퍼, 정식 출시!

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 수정하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있습니다.

• 🔗 빠르고 간편한 링크 저장 • 🧠 저장한 링크를 폴더별로 정리 • 🌐 폴더를 친구에게 공유 가능 • ⚡ 크롬 익스텐션 원클릭 저장

👉 링크 드라퍼 사용하러 가기 👉 크롬 웹스토어에서 설치하기

💬 카카오톡 채널 추가하고 소식 받기

서비스 업데이트 기능 꿀팁 카카오톡 채널을 통해 빠르게 받아보세요! 👉 카카오톡 채널 추가하기

“링크만 잔뜩 쌓이는 북마크를, 한 번에 읽을 수 있는 노션 스타일 요약 문서로 바꿔보자.”

링크 드라퍼에 웹 링크 자동 요약 + 자동 태깅 기능을 추가하면서 겪었던 기술적 선택과 시행착오를 정리해 보았습니다. 단순히 제목/설명 메타태그를 긁어오는 수준이 아니라, 실제 본문을 분석해서 구조화된 마크다운 문서와 상위 카테고리 태그까지 뽑아내는 것이 목표였습니다.

참고: 현재는 영상 위주 콘텐츠나 본문이 거의 없는 페이지는 요약이 실패하는 한계가 있습니다. 이 부분은 빠르게 개선 중입니다.

1. 무엇을 해결하고 싶었나

북마크 서비스나 “나중에 읽기” 도구를 써보면, 결국 이렇게 되기 쉽습니다.

• 제목만 잔뜩 쌓이고
• 나중에 보면 왜 저장했는지 기억 안 나고
• 다시 읽기엔 시간이 부족한 링크 더미…

그래서 링크 드라퍼에서는 “링크를 저장하면, 바로 요약과 태그까지 자동으로 만들어주는 기능”을 만들기로 했습니다.

• 링크를 저장하면
• 서버에서 HTML을 크롤링 → 본문 추출 → LLM으로 요약/태깅
• 결과를 노션 스타일 마크다운 문서 + 상위 카테고리 태그로 저장

사용자는 “링크 목록”이 아니라 “요약된 문서 컬렉션”을 보게 되는 경험을 목표로 했습니다.

2. 전체 아키텍처 한 번에 보기

기술 스택

• Backend: FastAPI
• LLM: Upstage Solar Pro
• HTML 파싱/조작: BeautifulSoup4, lxml

처리 플로우

1. 사용자가 URL 저장
   ↓
2. 웹 크롤링으로 HTML 수집
   ↓
3. HTML에서 본문 텍스트 추출
   ↓
4. 노이즈 제거 및 텍스트 정제
   ↓
5. LLM에 요약 + 태그 요청
   ↓
6. 구조화된 마크다운(summary) + 태그(tags) 반환
   ↓
7. DB 저장 및 링크 드라퍼에서 노션 스타일로 표시

API 설계 (텍스트 직접 요약용)

# 텍스트 직접 입력 방식
POST /summarize-text
{
  "text": "요약할 본문 텍스트..."
}

# 응답 형식
{
  "summary": "## 제목\n\n### 섹션1\n내용...",
  "tags": ["개발", "AI"]
}

실제 서비스에서는 URL을 받아서 내부에서 HTML → 텍스트 추출 후, 이 /summarize-text 흐름으로 연결해 사용하고 있습니다.

3. 본문 추출: 노이즈 제거가 품질의 절반

“아무리 좋은 LLM도, 쓰레기 입력에는 쓰레기 출력(Garbage In, Garbage Out)” 그래서 제일 먼저 신경 쓴 건 본문만 깔끔하게 추출하는 것이었습니다.

3.1 노이즈 제거: XPath + 스팸 키워드

HTML에는 우리가 원하지 않는 것들이 너무 많이 섞여 있습니다.

• 댓글
• 사이드바
• 푸터
• 광고
• 스팸 링크 블록 등

lxml의 XPath를 활용해서, 이런 영역을 사전에 날려버리는 전략을 썼습니다.

# XPath 기반 노이즈 블록 제거
NOISE_XPATHS = [
    "//*[contains(@id,'comment')]",
    "//*[contains(@class,'sidebar')]",
    "//*[contains(@id,'footer')]",
    "//*[contains(@class,'ad')]",
]

# 스팸 키워드 필터링
SPAM_KEYWORDS = [
    "casino", "betting", "카지노", "토토", "대출"
]

구현 포인트는 대략 이런 느낌입니다.

• lxml으로 DOM을 파싱하고, NOISE_XPATHS에 해당하는 노드를 통째로 제거
• 특정 스팸 키워드를 다수 포함한 블록은 과감히 필터링
• 다중 링크만 잔뜩 들어 있는 라인도 스팸 후보로 간주

이렇게 본문 후보를 최대한 깨끗하게 만든 뒤에, Trafilatura로 넘깁니다.

3.2 Trafilatura로 본문 추출

BeautifulSoup만으로는 “어디까지가 본문인지” 판단하기 어렵습니다. 그래서 머신러닝 기반 본문 추출 라이브러리인 Trafilatura를 사용했습니다.

def parse_content(html: str) -> Optional[str]:
    """Trafilatura를 활용한 본문 추출"""
    text = trafilatura.extract(
        html,
        include_comments=False,  # 댓글 제외
        include_tables=True,     # 표 포함
        no_fallback=False        # 폴백 활성화
    )

    # 최소 100자 이상일 때만 유효
    if text and len(text.strip()) > 100:
        return text.strip()

    return None

선택 이유는 다음과 같습니다.

• BeautifulSoup는 “태그 파서”일 뿐, 본문/비본문 구분에 특화되어 있지 않음
• Trafilatura는 다양한 사이트 구조에 대해 경험적으로 꽤 높은 정확도를 보여줌
• 옵션으로 댓글 제외, 테이블 포함 등을 섬세하게 조정할 수 있음

len(text) > 100 같은 간단한 기준이지만, 실제로 너무 짧은 텍스트는 요약의 의미가 없는 경우가 많아서 유효성 체크에 꽤 도움이 됐습니다.

4. LLM 요약 서비스: Upstage Solar Pro

본문 텍스트가 준비되면, 이제 LLM에 넘겨서 “노션 스타일 요약 문서 + 태그”를 만들어야 합니다.

4.1 서비스 구조

class SummarizationService:
    def __init__(self):
        self.client = OpenAI(
            api_key=UPSTAGE_API_KEY,
            base_url="https://api.upstage.ai/v1/solar"
        )

    def summarize(self, text: str) -> dict:
        response = self.client.chat.completions.create(
            model="solar-pro",
            messages=[
                {"role": "system", "content": SYSTEM_PROMPT},
                {"role": "user", "content": user_prompt}
            ],
            temperature=0.1,      # 일관성 중시
            max_tokens=8192,      # 충분한 응답 길이
        )

        result = parse_llm_json(response.choices[0].message.content)
        return result

설계 선택 포인트:

• Temperature 0.1 창의적인 문장보다는, 일관되고 재현 가능한 요약이 더 중요하다고 판단했습니다.
• max_tokens 8192 긴 글도 통으로 넣고 싶어서 토큰을 넉넉하게 잡았습니다. (초기에는 4096으로 했다가, 긴 문서가 뒷부분에서 잘리는 문제가 있었고, 이후 8192로 올렸습니다.)

4.2 JSON 파싱 지옥 탈출기

LLM에게 “JSON으로만 답해줘”라고 아무리 말해도, 현실은 이렇게 옵니다.

1. ```json
   { ... }

2. { ... }
3. 설명 텍스트... { ... } 설명 텍스트...
4. 심지어 후행 쉼표(trailing comma)까지…

그래서 응답 파싱 로직을 꽤 튼튼하게 만들 필요가 있었습니다.

```python
def extract_json_string(raw_text: str) -> str:
    # 1순위: 마크다운 코드 블록 내 JSON 추출
    code_block_match = re.search(
        r"```(?:json)?\s*(\{[\s\S]*?\})\s*```",
        raw_text
    )
    if code_block_match:
        return code_block_match.group(1)

    # 2순위: 문자열 시작부터 JSON
    if raw_text.lstrip().startswith("{"):
        return raw_text

    # 3순위: 텍스트 중간에 포함된 JSON 객체
    json_match = re.search(r"\{[\s\S]*\}", raw_text)
    if json_match:
        return json_match.group(0)

    raise ValueError("JSON 응답을 찾을 수 없습니다")

여기에 더해:

• 후행 쉼표(trailing comma) 제거
• json.loads 실패 시 로그 남기고 재시도/실패 처리

등을 유틸 함수(utils/llm_json.py)로 분리해서, 다른 LLM 연동에도 재사용할 수 있게 만들었습니다.

5. 프롬프트 엔지니어링: “추측하지 마”를 가르치기

가장 시간이 많이 들어간 부분은 프롬프트 엔지니어링이었습니다. 원하는 건 “간단한 요약”이 아니라:

• 원문에 없는 내용은 절대 넣지 않고
• 수치/날짜 등은 정확히 보존하면서
• 노션 페이지처럼 구조화된 마크다운을 뱉는 것이었습니다.

5.1 시스템 프롬프트: 엄격 원칙

SYSTEM_PROMPT = """당신은 정확한 요약 및 상위 분류 전문가입니다.

[엄격 원칙]
1) 제공된 본문만 사용하고, 배경지식/추측/외부 사실을 추가하지 마세요.
2) 수치·날짜·고유명사·단위 등 사실 요소는 원문 그대로 보존하세요.
3) 정보가 불명확하거나 부족하면 그 사실을 간단히 언급하고 추론하지 마세요.
4) 콘텐츠가 아닌 잡음(메뉴/광고/저작권 문구)은 무시하세요.
5) 어조는 중립적·비평가적이며 과장이나 축소 없이 기술하세요.
"""

이런 원칙이 없으면 LLM은 쉽게:

• 배경지식을 섞어서 “그럴듯한 이야기”를 만들어내거나
• 숫자/날짜를 자기 멋대로 바꾸는 할루시네이션을 일으키거나
• “~ 것으로 보인다” 같은 애매한 추론 문장을 추가합니다.

원문을 기반으로 한 정확한 요약이 목표이기 때문에, 이 부분을 계속 강조했습니다.

5.2 마크다운 출력 구조 강제

요약 결과는 Link Dropper에서 노션 페이지처럼 바로 읽히는 문서여야 합니다. 그래서 아예 마크다운 구조를 프롬프트에 못 박았습니다.

[마크다운 문서 작성 규칙]
- 이모지 사용 절대 금지
- 노션 페이지처럼 제목과 섹션으로 구조화된 완성된 문서
- 반드시 다음 구조를 따르세요:
  * ## [본문의 핵심 주제] - 문서 제목 (H2)
  * ### [섹션명] - 주요 섹션 구분 (H3, 2-3개 섹션 권장)
  * 각 섹션은 2-3개의 완전한 문장으로 구성
  * **굵은 글씨**: 중요 키워드, 수치, 날짜 강조
- 전체 길이: 일반적으로 1,200자 이내

예상하는 결과물은 이런 느낌입니다.

## AI 에이전트의 미래와 도전과제

### 기술 발전 현황
최근 **LangChain**과 **AutoGPT** 같은 프레임워크가 등장하면서
AI 에이전트 개발이 대중화되고 있습니다. **2024년 1분기** 기준으로
관련 오픈소스 프로젝트가 **300% 증가**했습니다.

### 남은 과제들
그러나 환각(hallucination) 문제와 비용 증가가 상용화의 걸림돌로
작용하고 있습니다. 특히 **GPT-4**를 사용할 경우 토큰당 비용이
이전 모델 대비 **10배** 높아졌습니다.

이렇게 구조를 강제해 두면, 링크 드라퍼 쪽에서는 별도의 후처리 없이 바로 보여줄 수 있습니다.

5.3 카테고리 태그 시스템

태그는 자유롭게 적게 두면 너무 세분화되어서 관리가 안 되기 때문에, 상위 카테고리 집합을 만들어 두었습니다.

ALLOWED_TAG_CATEGORIES = {
    "기술/개발": ["개발", "AI", "클라우드", "데이터", "보안"],
    "비즈니스": ["경제", "금융", "스타트업", "마케팅"],
    "사회/문화": ["사회", "정치", "교육", "문화"],
    "과학": ["과학", "의료", "환경"],
    "기타": ["스포츠", "엔터테인먼트", "게임"]
}

[태그 선택 규칙]
- 가능한 한 상위(넓은) 범주를 고르세요
- 태그 수는 2-4개를 넘지 마세요

의도한 효과:

• 태그가 지나치게 쪼개지지 않도록 제어
• 검색/필터링에 의미 있는 상위 카테고리 수준 유지
• LLM이 태그를 마구 찍어내지 않도록 제한

5.4 체크리스트로 자가 검증 유도

프롬프트 끝에는 LLM이 스스로 출력물을 점검해 보도록 체크리스트를 추가했습니다.

[출력 점검 체크리스트]
- [ ] "summary"는 ## 제목으로 시작하는 노션 스타일 문서인가?
- [ ] ### 섹션 제목이 2-3개 포함되어 있는가?
- [ ] 이모지가 전혀 사용되지 않았는가?
- [ ] 핵심 수치/이름/날짜가 **굵게** 강조되었는가?
- [ ] 본문에 없는 주장·해석이 없는가?
- [ ] "tags"는 2-4개이며 허용 집합에서만 선택했는가?

체감상:

• 이모지 사용 금지
• 섹션 개수/구조 준수

같은 부분에서 프롬프트 준수율이 30~40% 정도는 올라간 느낌이었습니다.

6. 데이터 검증 & 에러 처리

LLM 응답을 그대로 신뢰할 수는 없기 때문에, 검증 레이어를 여러 단계로 두었습니다.

6.1 요청 검증: Pydantic

너무 짧은 텍스트는 요약해도 의미가 없기 때문에, 요약 API 요청 자체를 검증했습니다.

class SummarizeTextRequest(BaseModel):
    text: str

    @field_validator('text')
    @classmethod
    def validate_text(cls, v: str) -> str:
        if not v or not v.strip():
            raise ValueError("텍스트는 비어있을 수 없습니다")

        word_count = len(v.split())
        if word_count < 10:
            raise ValueError(
                f"텍스트가 너무 짧습니다. "
                f"최소 10단어 이상 필요합니다. (현재: {word_count}단어)"
            )

        return v

이 단계에서 걸러지면, 굳이 LLM 호출 비용을 쓰지 않아도 됩니다.

6.2 응답 검증: 필수 필드 체크

LLM 응답이 JSON이라 해도, 필수 필드가 빠져 있을 수 있습니다.

def summarize(self, text: str) -> dict:
    result = parse_llm_json(content)

    # 필수 필드 검증
    if "summary" not in result or "tags" not in result:
        raise ValueError("응답에 필수 필드가 없습니다")

    # summary 검증
    if not result["summary"]:
        raise ValueError("summary가 비어있습니다")

    # tags 검증
    if not isinstance(result["tags"], list) or len(result["tags"]) == 0:
        raise ValueError("tags는 비어있지 않은 리스트여야 합니다")

    return result

이렇게 검증 레이어를 여러 개 두면:

• 디버깅 포인트가 명확해지고
• “요약이 안 됐다”는 이슈가 왔을 때, 어느 단계에서 실패했는지 빠르게 확인할 수 있습니다.

7. 1차 구현 → 2차 리팩토링: 뭐가 달라졌나

7.1 초기 문제들

처음 구현했을 때는 다음과 같은 문제들이 있었습니다.

• max_tokens=4096으로 인해 긴 문서 요약이 중간에서 잘림
• 프롬프트가 너무 자유로워서 출력 형식이 제각각
• LLM이 JSON을 깨끗하게 안 보내서 파싱 실패 케이스 다수

7.2 개선 작업 (커밋 로그 느낌으로)

[설정] 요약 기능을 위한 상수 및 설정 파일 추가
[유틸리티] 텍스트 정제 및 노이즈 제거 유틸리티 추가
[서비스] LLM 기반 텍스트 요약 서비스 추가
[Refactor] LLM JSON 파싱 유틸 도입
[Refactor] 요약 프롬프트 상수 구조화
[요약] maxToken 놀리기 (4096 → 8192)

주요 변경 사항은 네 가지였습니다.

1. 프롬프트 상수 분리

   • 하드코딩된 프롬프트 → constants/summarize.py로 분리

2. JSON 파싱 유틸 모듈화

   • 응답 파싱 로직 → utils/llm_json.py로 분리, 재사용 가능하게

3. maxTokens 증가 (4096 → 8192)

   • 긴 문서에서도 요약이 중간에서 끊기지 않도록

4. 텍스트 정제 강화

   • 노이즈 제거, 최소 길이 체크 등 입력 품질 높이기

7.3 성능 변화

수치 자체는 체감 기반이지만, 실제로 운영하면서 느끼는 에러 빈도와 수동 수정 빈도는 확실히 줄어든 편입니다.

8. 현재 한계와 앞으로의 계획

8.1 현재 한계

1. 영상 위주 콘텐츠 요약 미지원

   • 유튜브처럼 영상만 있고, 본문 텍스트가 거의 없는 페이지는 현재 요약에 실패합니다.
   • 자막/트랜스크립트 기반 요약은 별도의 파이프라인이 필요해서, 추후 작업으로 분리해두었습니다.

2. 본문이 없는 랜딩 페이지

   • 이미지/레이아웃 위주의 랜딩 페이지도 마찬가지로, 텍스트 추출 자체가 어려워서 요약이 실패합니다.

이 부분은 사용자에게도 명시적으로 안내하고, 빠른 시일 내에 개선할 예정입니다.

8.2 앞으로 하고 싶은 것들

1. 스트리밍 응답 지원

   • 현재는 서버에서 요약이 완전히 끝날 때까지 기다렸다가 한 번에 반환합니다.
   • 추후에는 스트리밍 형태로 문서가 채워지는 UX를 검토하고 있습니다.

2. 캐싱 전략

   • 동일한 URL을 여러 번 요약하는 것은 낭비이기 때문에, Redis 같은 캐시를 두고 중복 요약을 피하는 전략을 도입할 계획입니다.

3. 다국어 지원 강화

   • 지금은 한국어/영어 중심으로 동작하지만,
   • 언어별로 프롬프트를 최적화해서 다국어 페이지에 더 잘 대응하고 싶습니다.

4. 요약 품질 평가 메트릭 도입

   • 현재는 사람 눈으로만 “좋다/별로다”를 판단하고 있습니다.
   • 가능하면 ROUGE, BERTScore 같은 지표를 참고해 정량적인 지표를 도입해 보는 것이 목표입니다.

9. 마치며

겉으로 보기에는 “링크 요약 기능 하나 추가했다”처럼 보이지만, 실제 구현은:

• 웹 크롤링
• 본문 추출
• 텍스트 정제
• LLM 프롬프트 설계
• JSON 파싱
• 데이터 검증 & 에러 처리

까지 여러 레이어가 겹쳐 있는 꽤 긴 파이프라인이었습니다.

특히 느낀 점은:

• 프롬프트 엔지니어링은 한 번에 끝나지 않는다 → 실제 사용 데이터를 보면서 계속 다듬어야 합니다.
• LLM 응답은 항상 예외 케이스가 있다 → 파싱과 검증 로직을 충분히 탄탄하게 짜두는 게 중요합니다.
• 노이즈 제거가 요약 품질의 50% → 좋은 모델을 쓰는 것만큼, 좋은 입력을 만들어 주는 것이 중요합니다.

지금은 링크 드라퍼에서 링크를 저장하면 자동으로 요약 문서와 태그가 붙는 경험을 제공하고 있고, 앞으로는 영상/비텍스트 페이지까지 커버하도록 계속 확장해 나갈 예정입니다.

🧪 링크 드라퍼, 정식 출시!

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 수정하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있습니다.

• 🔗 빠르고 간편한 링크 저장 • 🧠 저장한 링크를 폴더별로 정리 • 🌐 폴더를 친구에게 공유 가능 • ⚡ 크롬 익스텐션 원클릭 저장

👉 링크 드라퍼 사용하러 가기 👉 크롬 웹스토어에서 설치하기

💬 카카오톡 채널 추가하고 소식 받기

서비스 업데이트 기능 꿀팁 카카오톡 채널을 통해 빠르게 받아보세요! 👉 카카오톡 채널 추가하기

• DB 단계 최적화: 불필요 인덱스/과도한 CASCADE 정리 → 쓰기 성능 및 무결성 개선.

• 쿼리 구조 개선: N+1 제거(폴더별 미읽은 수 집계), 다건 UPDATE를 CASE 단일 쿼리로 통합.
• 동시성 활용: 순차 처리 → Promise.all 기반 병렬 처리로 대량 작업 가속.
• 결과: 응답 시간 50%+ 단축, DB 부하 70%↓, 코드 403줄 순감.

왜 이 글을 읽어야 할까?

운영 환경에서 API 응답이 튀고, 피크 타임에 DB가 뜨거워지는 문제는 대부분 “쿼리 구조·인덱스·동시성” 3축에서 원인이 드러납니다. 본 리팩터링은 이 세 축을 단계적으로 다뤄 측정 가능한 성과를 만들었습니다. (응답시간/부하/코드 줄 수)

1) 스키마·인덱스 정비: 쓰기 성능과 무결성을 동시에

운영 중 적체가 보이는 프로젝트의 공통점은 인덱스 과다와 과격한 CASCADE입니다. 이번 작업에서는 인덱스를 최소화하고, 외래키의 삭제 전이를 보수적으로 조정해 INSERT/UPDATE 성능을 회복하고 무결성을 보강했습니다.

예시 코드 (단순화된 엔티티)

// Before: 인덱스/연쇄 옵션이 과함 (예시)
@Entity('resource')
@Index(['ownerId', 'isArchived'])
export class Resource {
  @Column({ default: false }) isArchived: boolean;
  @ManyToOne(() => Folder, { onDelete: 'CASCADE' }) folder: Folder | null;
}

// After: 필요한 관계만, 보수적 전이 (예시)
@Entity('resource')
export class Resource {
  @Column({ default: false }) isArchived: boolean;
  @ManyToOne(() => Folder) folder: Folder | null; // onDelete 생략 → 애플리케이션 레벨로 제어
}

2) N+1 제거: “폴더별 미읽은 개수”를 한 방에

기존엔 폴더 수만큼 COUNT가 반복되는 N+1 쿼리였고, 이를 IN + GROUP BY 단일 쿼리로 교체했습니다.

예시 코드 (집계 API)

// Before: 폴더마다 개별 COUNT (예시)
const withUnread = await Promise.all(
  folders.map(async (f) => ({ ...f, unread: await countUnread(f.id) }))
);

// After: 한 번에 묶어서 조회 (예시)
const ids = folders.map(f => f.id);
const rows = await db.query(/* sql */ `
  SELECT folder_id, COUNT(*) AS unread
  FROM link
  WHERE is_trashed = false
    AND last_use_at IS NULL
    AND folder_id = ANY($1)
  GROUP BY folder_id
`, [ids]);

const unreadMap = new Map(rows.map(r => [Number(r.folder_id), Number(r.unread)]));
const withUnreadFast = folders.map(f => ({ ...f, unread: unreadMap.get(f.id) ?? 0 }));

폴더 10개 기준 11쿼리 → 2쿼리로 축소(82%↓).

3) 대량 UPDATE 최적화: CASE 문으로 원자적 일괄 반영

아이템 정렬처럼 “행마다 다른 값”을 갱신해야 한다면, 반복 UPDATE 대신 CASE-based 단일 UPDATE로 전환합니다. 트랜잭션 비용이 줄고, 원자성이 보장됩니다.

예시 코드 (정렬 순서 일괄 반영)

// Before: 항목마다 UPDATE (예시)
for (const it of items) {
  await db.update('sort', { sort_order: it.order }, { item_id: it.id });
}

// After: CASE 한 번으로 (예시)
const ids = items.map(x => x.id);
const cases = items.map(x => `WHEN item_id = ${x.id} THEN ${x.order}`).join(' ');
await db.query(`
  UPDATE sort
  SET sort_order = CASE ${cases} ELSE sort_order END
  WHERE item_id = ANY($1)
`, [ids]);

실측 예시: 5개 항목 정렬 시 10쿼리 → 1쿼리(90%↓).

4) 순차 → 병렬: 대량 이동·복사 작업 가속

목록 이동/복사 등 I/O가 많은 작업은 타입별 분리 + Promise.all로 병렬화하여 전체 처리 시간을 줄였습니다.

예시 코드 (이동 작업)

// Before: 순차 처리 (예시)
for (const it of items) await moveOne(it);

// After: 타입별 병렬 처리 (예시)
const linkItems = items.filter(i => i.type === 'link');
const folderItems = items.filter(i => i.type === 'folder');

await Promise.all([
  Promise.all(linkItems.map(moveOneLink)),
  Promise.all(folderItems.map(moveOneFolder)),
]);

10개 항목(링크5/폴더5) 이동 시, 쿼리 수와 경로가 단축되며 처리 시간 체감이 발생.

5) 응용: Publication/Item 서비스 단순화

복잡한 재귀를 반복/분할로 치환하고, 알림 등 부가 책임을 분리했습니다. 정렬은 머지 정렬 커스텀 코드 → 내장 Array.prototype.sort로 단순화해 가독성과 성능을 동시에 얻었습니다.

예시 코드 (정렬 단순화)

// Before: 커스텀 병합 정렬 (예시)
function mergeSortByOrder(listA, listB) { /* ...길고 복잡... */ }

// After: 내장 sort로 충분 (예시)
const sorted = [...links, ...folders].sort((a, b) => a.order - b.order);

6) 유지·데이터 모델 개선: Soft Delete/Unique 명시

운영 로그성 데이터엔 Soft Delete가 유용합니다. 또한 URL 등 고유키는 Unique 제약을 스키마에 명확히 두어 중복을 차단합니다.

예시 코드

// Soft Delete (예시)
@Entity('maintenance')
class Maintenance {
  @DeleteDateColumn() deletedAt: Date;
}

// Unique 제약 (예시)
@Entity('og_metadata')
@Unique(['url'])
class OgMeta {
  @Column() url: string;
}

성과 (운영 지표 기준)

• 응답 시간: 50%+ 단축
• DB 부하: 70% 감소
• 코드베이스: 403줄 순감(677 삭제, 274 추가)
• 확장성/안정성: 대량 처리 시 일관된 성능 유지, 트랜잭션/원자성 보장 근거: 프로젝트 정리 문서의 결론/지표 요약.

체크리스트: 우리 팀에 바로 적용하려면

1. 스키마: 과도한 인덱스/연쇄 옵션 제거, 유니크/널 제약을 모델 의도로 맞춤.
2. 쿼리: N+1 의심 구간을 IN+GROUP BY로 통합, 다건 UPDATE는 CASE 단일화.
3. 동시성: CPU/IO 바운드별로 병렬화 설계(Promise.all/배치 크기 제한).
4. 코드 품질: 커스텀 정렬·재귀 로직을 내장 함수/반복으로 단순화.
5. 삭제 정책: 로그·이력엔 Soft Delete, 하드 삭제는 최소화.

마무리

이번 리팩터링은 DB 설계 → 쿼리 전략 → 동시성 → 도메인 로직을 한 흐름으로 정돈해, 측정 가능한 성과를 냈다는 점이 핵심입니다. 같은 문제를 겪는 팀이라면 위 체크리스트부터 적용해 보세요. 성능은 결국 구조에서 나옵니다. (요약 근거)

참고: 본 글의 기술 근거는 사용자가 제공한 리팩터링 분석 파일을 기반으로 하며, 예시 코드는 운영 코드와 무관하게 이해를 돕기 위해 별도로 구성되었습니다.

🧪 링크 드라퍼, 정식 출시!

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 수정하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있습니다.

• 🔗 빠르고 간편한 링크 저장 • 🧠 저장한 링크를 폴더별로 정리 • 🌐 폴더를 친구에게 공유 가능 • ⚡ 크롬 익스텐션 원클릭 저장

👉 링크 드라퍼 사용하러 가기 👉 크롬 웹스토어에서 설치하기

💬 카카오톡 채널 추가하고 소식 받기

서비스 업데이트 기능 꿀팁 카카오톡 채널을 통해 빠르게 받아보세요! 👉 카카오톡 채널 추가하기

링크 드라퍼(Link Dropper) 서비스에 DOCK 기능을 추가하면서, 단순한 링크 고정보다 중요한 것은 사용자 경험(UX) 이었습니다. 링크를 고정하는 동작이 ‘자연스럽고 예측 가능’하게 이루어지도록 하기 위해선, 시각적 피드백, 즉각적인 반응, 실패 대비 처리 등 다양한 요소가 필요했죠.

이번 글에서는 @dnd-kit과 Zustand를 이용해 DnD 인터랙션을 어떻게 설계하고, 낙관적 UI를 어떤 방식으로 구현했는지를 예시 코드와 함께 공유합니다.

🎯 기능 설계의 핵심 포인트

문제 정의

• 고정된 링크 영역(DOCK)과 최근 본 링크 목록 간의 이동이 필요하다.
• 사용자가 링크를 드래그할 때 자연스럽게 느껴져야 하며, UX가 끊기면 안 된다.
• 순서 변경, 고정 해제 등 다양한 액션을 드래그로 구현해야 한다.

주요 과제

🧩 DnD 컨텍스트 설계

DnD 컨텍스트를 따로 Provider로 만들고, 이 안에서 draggable 요소들과 drop zone들을 관리합니다. 여기서 중요한 것은 item.id의 명명 규칙이에요. recent-{id} vs dock-{id} 패턴으로 id를 정하면, 드래그 중 어디서 왔고 어디로 가는지를 쉽게 판단할 수 있습니다.

const items = useMemo(() => [
  ...recentLinks.map(link => ({ id: `recent-${link.id}` })),
  ...dockItems.map(item => ({ id: `dock-${item.id}` })),
  { id: "dock-drop-zone" },
], [recentLinks, dockItems]);

👉 이 구조는 이후 onDragEnd에서 drop 위치를 판별하는 기준이 되며, if 조건문이 훨씬 명확해집니다.

⚙️ 드래그 동작 중의 시각 피드백: DragOverlay

드래그 중인 요소를 사용자에게 보여주는 시각적 피드백은 필수적 UX 요소입니다.

<DragOverlay>
  {activeItem ? (
    <div className="drag-overlay">
      <LinkThumbnail link={activeItem.link} />
    </div>
  ) : null}
</DragOverlay>

• 사용자는 지금 어떤 링크를 드래그 중인지 인식할 수 있음
• 오버레이는 별도의 z-index로 띄워서 다른 UI와 겹치지 않게 처리

이 구성은 단순하지만 드래그가 "진짜 되는 것처럼 보이게 만드는 데" 큰 역할을 합니다.

🔄 상태 관리: 왜 Zustand인가?

기존의 React state 혹은 Redux가 아닌 Zustand를 사용한 이유는 다음과 같습니다:

• 간결한 코드로 전역 상태를 관리 가능
• snapshot 같은 일시적 저장 구조를 쉽게 구현할 수 있음
• React Context 없이도 작동하며, DnD처럼 상태 변화가 자주 발생하는 구조에 적합

상태 구조 설계

interface DockState {
  dockItems: DockItem[];
  snapshot: DockItem[];
  setDockItems: (items: DockItem[]) => void;
  snapshotCurrent: () => void;
}

• snapshot: 실패 시 복구할 수 있도록 이전 상태를 임시 저장
• setDockItems: 상태 갱신
• snapshotCurrent: 낙관적 UI 이전에 꼭 호출해야 하는 액션

🚀 낙관적 UI — 빠른 피드백을 위한 선택

드래그 후 링크를 DOCK으로 옮기는 순간, UI가 반응이 없다면 사용자 입장에서는 버그처럼 느껴질 수 있습니다. 이를 해결하기 위해 "먼저 UI를 갱신하고, 나중에 서버에 반영하는" 낙관적 UI 패턴을 도입했습니다.

async function handleDropToDock(link: Link, insertAfterId: number | null) {
  snapshotCurrent(); // 현재 상태 백업

  // 1. UI 선반영
  const reordered = computeNewOrder(dockItems, link, insertAfterId);
  setDockItems(reordered);

  try {
    // 2. 서버에 반영
    await api.addToDock(link.id);
    await api.updateDockOrder(reordered);
  } catch {
    // 3. 실패 시 롤백
    setDockItems(snapshot);
  }
}

낙관적 UI를 구현할 땐 항상 롤백 경로를 열어두는 게 중요합니다. 여기서 snapshot이 큰 역할을 하죠.

🧠 드래그 종료 처리: onDragEnd

드래그 종료 이벤트에는 모든 분기처리 로직이 집약되어 있습니다. DnD 흐름을 정리하면 다음과 같습니다:

function handleDragEnd(event: DragEndEvent) {
  const { active, over } = event;
  if (!over) return;

  const activeId = active.id;
  const overId = over.id;

  if (activeId.startsWith("recent-") && overId === "dock-drop-zone") {
    const linkId = activeId.replace("recent-", "");
    onDropToDock(findLinkById(linkId), null);
    return;
  }

  if (activeId.startsWith("dock-") && overId.startsWith("dock-")) {
    onReorderDockItems(/* ... */);
  }
}

• ID 패턴을 이용해 출발지와 도착지를 명확히 파악
• 서로 다른 행동을 조건 분기로 구분 (추가 vs 정렬 변경)

🧪 결과: 기능 이상의 경험

✅ 사용성 개선 포인트

• 즉각적인 피드백: 드래그만 하면 바로 반응
• 자연스러운 애니메이션과 UI 흐름
• API 실패 대응까지 고려된 안정성

🏁 마무리하며

이번 DOCK 기능 구현은 작아 보이지만 깊은 고민이 담긴 작업이었습니다. @dnd-kit의 유연함과 Zustand의 간결함, 그리고 낙관적 UI의 UX적 강점을 조화롭게 적용한 좋은 경험이었고, 이런 방식이 여러분의 프로젝트에도 영감을 줄 수 있기를 바랍니다.

🧪 링크 드라퍼, 지금 베타 테스트 중입니다

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 수정하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있습니다.

• 🔗 빠르고 간편한 링크 저장 • 🧠 저장한 링크를 폴더별로 정리 • 🌐 폴더를 친구에게 공유 가능 • ⚡ 크롬 익스텐션 원클릭 저장

👉 링크 드라퍼 사용하러 가기 👉 크롬 웹스토어에서 설치하기

💬 카카오톡 채널 추가하고 소식 받기

서비스 업데이트 기능 꿀팁 카카오톡 채널을 통해 빠르게 받아보세요! 👉 카카오톡 채널 추가하기

이 글에서는 이벤트 위임(Event Delegation)의 개념, 왜 쓰는지, 언제 쓰면 좋고 언제 피해야 하는지, 실제 코드 예제와 함께 링크/폴더 구조 같은 상황에서 적용할 수 있는 구체적인 해결 방안을 다룹니다.

📌 이벤트 위임이란 무엇인가?

이벤트 위임(Event Delegation)은 다음 개념들의 조합을 활용합니다:

1. 이벤트 버블링 (Event Bubbling) 자식 요소에서 발생한 이벤트가 DOM 트리 상위로 전파(flows up)되는 특성입니다.

2. 상위 요소에 이벤트 리스너를 한 번만 등록 여러 하위 요소(each child)에 개별적으로 onClick/onDoubleClick 등을 붙이는 대신, 상위(wrapper 또는 컨테이너) 요소에 이벤트 리스너를 걸어두고, 이벤트가 상위까지 올라왔을 때 어느 자식에서 일어났는지 평가하여 처리합니다.

3. 대상(target) 판별 로직 event.target, event.target.closest(selector), matches(), dataset 속성 등을 활용해 클릭된 요소가 어떤 타입(예: 링크 vs 폴더 vs 특정 버튼)인지 구분합니다.

⚠️ 반복된 방식의 문제점: 왜 이벤트 위임이 필요했나

링크(link)와 폴더(folder)에 각각 onClick, onDoubleClick 등을 직접 붙이는 기존 방식이 가진 구체적인 단점들은 다음과 같습니다:

링크+폴더 예제에서는 “링크 클릭” / “폴더 더블클릭” 등의 동작이 반복 요소마다 있고, 어떤 경우엔 폴더가 동적으로 추가되기도 할 것임. 이런 구조에서는 위임이 유리합니다.

🛠 위임 전략 적용하기: 링크·폴더 구조 예시

아래는 링크/폴더 구조에 이벤트 위임을 적용하는 실전 예제입니다.

구조 가정

• 여러 개의 아이템(item)이 있고, 각각 아이템은 “링크” 혹은 “폴더” 타입
• 유저가 링크 클릭 또는 폴더 더블클릭을 할 때 별도 동작 수행
• 폴더 더블클릭은 ‘더블클릭’ 이벤트로, 링크는 단일 클릭

HTML / JSX 구조

<ul id="item-list">
  {items.map(item => (
    <li key={item.id}
        data-type={item.type}    // "link" 또는 "folder"
        data-id={item.id}>
      {item.type === "link"
        ? <a href={item.url} className="item-link"> {item.name} </a>
        : <span className="item-folder"> {item.name} </span>}
    </li>
  ))}
</ul>

이벤트 위임 코드 (클릭 + 더블클릭 분리)

const itemList = document.getElementById('item-list');

// 단일 클릭 처리
itemList.addEventListener('click', function(event) {
  const li = event.target.closest('li');
  if (!li) return;

  const type = li.dataset.type;
  const id   = li.dataset.id;

  if (type === 'link') {
    // 링크 클릭 동작
    console.log(`링크 클릭됨: ${id}`);
    // 여기서는 기본 동작(navigation) 허용하거나
    // event.preventDefault() 등 제어 가능
  }
  // 폴더 클릭 시 (폴더 단축 클릭) 다른 동작이 필요하다면 여기에
});

// 더블클릭 처리 (폴더 전용)
itemList.addEventListener('dblclick', function(event) {
  const li = event.target.closest('li');
  if (!li) return;

  const type = li.dataset.type;
  const id   = li.dataset.id;

  if (type === 'folder') {
    console.log(`폴더 더블클릭됨: ${id}`);
    // 폴더 더블클릭 처리
  }
});

추가 고려: 이벤트 간 충돌 처리

• 단일 클릭과 더블클릭이 같은 요소에서 모두 가능할 때, 일반적으로 클릭 이벤트가 먼저 실행되고 더블클릭이 이어지는 구조여서 클릭 동작과 더블클릭 동작이 서로 간섭할 수 있음.

• 해결책:

  1. 타이머 기반 분기 더블클릭이 아닌 단일 클릭으로 보고 일정 시간 이후(예: 300ms) 클릭 로직 실행.

  2. 이벤트 취소 더블클릭 이벤트가 발생했을 때 단일 클릭 이벤트의 실행을 막거나 무시하도록 로직 구성.

예시 (간단한 타이머 방식):

let clickTimer = null;
const clickDelay = 300;

itemList.addEventListener('click', function(event) {
  const li = event.target.closest('li');
  if (!li) return;

  const type = li.dataset.type;
  const id   = li.dataset.id;

  // 링크 단일 클릭만 처리
  if (type === 'link') {
    // 링크는 단일 클릭만 필요하다면 바로 처리
    handleLinkClick(id);
  } else if (type === 'folder') {
    // 폴더는 단일 클릭 vs 더블클릭 분기
    clearTimeout(clickTimer);
    clickTimer = setTimeout(() => {
      handleFolderSingleClick(id);
    }, clickDelay);
  }
});

itemList.addEventListener('dblclick', function(event) {
  const li = event.target.closest('li');
  if (!li) return;

  const type = li.dataset.type;
  const id   = li.dataset.id;

  if (type === 'folder') {
    clearTimeout(clickTimer);
    handleFolderDoubleClick(id);
  }
});

⚙ 이벤트 위임의 장·단점 & 실무적 고려사항

✅ 장점

• 핸들러 수 감소 → 메모리 & 이벤트 리스너 관리 비용 절감 반복되는 하위 요소가 많을수록 이득이 커짐. 동적 요소 생성에도 추가 처리 필요 없음.

• 코드 일관성 / 유지보수성 향상 이벤트 로직이 한 곳에 집중됨. 수정/추가/버그 수정 시 변경 지점을 최소화 가능.

• 성능 개선 많은 이벤트 리스너가 걸려 있는 경우, 브라우저 이벤트 처리 및 가비지 컬렉션 부담 감소.

• 확장성 요소 타입이 추가되더라도, 상위 로직 쪽에서 타입만 판별하여 처리하면 됨.

❌ 단점 / 주의할 점

🔍 언제 위임 vs 직접 등록이 더 좋은가?

아래 상황들을 비교하며 판단하면 됩니다:

🔧 실무 적용 시 체크리스트

• DOM 구조를 설계할 때 식별자(identifier) 설정: 클래스명, data- 속성, 태그명 등을 미리 정리해두면 이벤트 타깃 판별이 쉬움
• closest() 와 matches() 사용법 숙지
• 더블클릭 vs 클릭 분기 필요 시 타이밍, 이벤트 취소(logic) 고려
• stopPropagation(), stopImmediatePropagation() 등이 이벤트 흐름을 끊는 곳이 없는지 점검
• Shadow DOM, 웹 컴포넌트 사용 시 이벤트 전파 특성 이해
• 개발자 도구(Chrome DevTools 등)의 Performance / Memory 탭을 활용해 핸들러 수, 이벤트 처리 지연 등의 지표 측정

✅ 결론

• 이벤트 위임은 반복적이고 동적인 UI 구성에서 성능, 유지보수, 확장성을 개선해 주는 매우 유용한 패턴입니다.
• 하지만 모든 경우에 만능은 아니므로, 위에서 언급한 고려사항들을 기반으로 “언제 위임할 것인가, 언제 직접 이벤트를 붙일 것인가”를 판단하는 것이 중요합니다.
• 특히 링크 + 폴더 구조처럼 반복되는 항목이 많고 사용자 인터랙션 종류가 제한적이라면, 지금 바로 이벤트 위임으로 리팩터링 해보시는 걸 추천드립니다.

🧪 링크 드라퍼, 지금 베타 테스트 중입니다

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 수정하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있습니다.

• 🔗 빠르고 간편한 링크 저장 • 🧠 저장한 링크를 폴더별로 정리 • 🌐 폴더를 친구에게 공유 가능 • ⚡ 크롬 익스텐션 원클릭 저장

👉 링크 드라퍼 사용하러 가기 👉 크롬 웹스토어에서 설치하기

💬 카카오톡 채널 추가하고 소식 받기

서비스 업데이트 기능 꿀팁 카카오톡 채널을 통해 빠르게 받아보세요! 👉 카카오톡 채널 추가하기

대규모 언어 모델(LLM)은 단순한 텍스트 생성기를 넘어 “에이전트”로 진화하고 있습니다. 이제 AI는 외부 시스템과 연동하고, 다른 AI와 협업하며 복잡한 작업을 자동으로 처리할 수 있어야 합니다.

그렇다면 이 복잡한 연동과 협업은 어떻게 표준화되어 있을까요?

👉 해답은 바로 두 가지 핵심 프로토콜, MCP (Model Context Protocol)와 A2A (Agent-to-Agent Protocol)에 있습니다.

🛠 MCP: 도구를 호출하는 LLM의 새로운 습관

✅ MCP란?

MCP는 LLM이 외부 도구(API, DB, 서비스 등)를 호출할 수 있도록 도와주는 도구 호출용 프로토콜입니다. 기존의 프롬프트 기반 도구 설명 방식에서 벗어나, 기계가 해석 가능한 JSON 형식으로 도구를 등록하고 호출할 수 있게 합니다.

마치 LLM에게 “이 도구는 이렇게 쓰는 거야”라고 가르쳐주는 인터페이스입니다.

🔍 작동 방식 요약

1. tools/describe: 사용 가능한 도구 목록과 파라미터 구조를 조회
2. tools/call: 도구 호출 및 결과 수신
3. 호출 형식: JSON-RPC 2.0 기반

📦 호출 예시

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "getWeather",
    "arguments": {
      "location": "Seoul"
    }
  }
}

✅ 장점 요약

• 프롬프트 반복 없이 도구 호출 가능
• LLM이 상황에 따라 자동 도구 선택
• 복잡한 도구 체계도 쉽게 확장 가능

🤝 A2A: 에이전트가 에이전트를 부르는 법

✅ A2A란?

A2A는 하나의 에이전트가 다른 에이전트에게 작업(Task)을 위임하고 결과를 기다릴 수 있게 해주는 에이전트 간 협업 프로토콜입니다.

예: 법률 분석 에이전트 → 번역 에이전트 → 요약 에이전트로 이어지는 다단계 작업

🔍 주요 구성 요소

• Agent Card: 에이전트 기능 정의 (API 경로, 입력값, 인증 등 포함)
• Task 객체: 작업 요청 및 상태 관리 (submitted → working → completed)
• Transport: JSON-RPC over HTTP, SSE 또는 Webhook 기반

📦 예시

{
  "task_id": "translate_contract",
  "from": "agent://legal_reader",
  "to": "agent://translator",
  "input": {
    "text": "이 계약서는..."
  }
}

✅ A2A의 장점

• 에이전트의 역할을 능력 단위로 분리 가능
• 상태 기반 비동기 작업 관리 가능
• 병렬, 순차 작업 조합이 자유로움
• Agent Directory를 통한 동적 연결/탐색 가능

🔗 A2A와 MCP는 어떻게 함께 쓰일까?

MCP와 A2A는 역할이 다르지만, 실제 환경에서는 서로 보완적으로 사용됩니다.

예시 시나리오

1. 사용자가 “배송 상태 확인” 요청
2. 메인 에이전트는 배송 전용 에이전트에게 A2A로 위임
3. 배송 에이전트는 MCP를 통해 배송 API 호출
4. 결과는 A2A를 통해 메인 에이전트 → 사용자에게 전달

📊 MCP vs A2A 비교

🔀 참고로 알아두면 좋은 용어: ACP

• ACP (Agent Communication Protocol)은 메시징 중심 구조
• A2A는 작업(Task) 위임 중심
• MCP는 도구와 직접 상호작용을 위한 인터페이스

→ 세 가지는 목적과 역할이 서로 다르며, 필요에 따라 함께 사용됩니다

🧠 마무리: 에이전트 시대의 필수 프로토콜

MCP와 A2A는 단순한 기술이 아닙니다. AI가 현실의 문제를 해결하기 위해 도구를 쓰고, 다른 AI와 협업할 수 있도록 만드는 핵심 인프라입니다.

앞으로 LLM 기반 시스템을 개발한다면, MCP와 A2A는 반드시 이해하고 설계에 반영해야 할 요소입니다.

🧪 링크 드라퍼, 지금 베타 테스트 중입니다

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 수정하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있습니다.

• 🔗 빠르고 간편한 링크 저장 • 🧠 저장한 링크를 폴더별로 정리 • 🌐 폴더를 친구에게 공유 가능 • ⚡ 크롬 익스텐션 원클릭 저장

👉 링크 드라퍼 베타 체험하러 가기 👉 크롬 웹스토어에서 설치하기

💬 카카오톡 채널 추가하고 소식 받기

서비스 업데이트 기능 꿀팁 카카오톡 채널을 통해 빠르게 받아보세요! 👉 카카오톡 채널 추가하기

궁금하신 점이나 실제 구현에 대한 내용이 있다면 댓글로 남겨주세요! 🙌

React Query의 Hydrate 컴포넌트를 활용하면 이 문제를 깔끔하게 해결할 수 있습니다. 이번 글에서는 Hydrate의 개념, 동작 원리, 그리고 실제로 어떻게 Next.js 프로젝트에 적용하는지를 상세하게 설명합니다.

🤔 왜 Hydrate가 필요할까?

서버 사이드 렌더링을 사용하는 경우, 서버에서 데이터를 미리 받아와 화면을 렌더링합니다. 그러나 클라이언트는 이 상태를 알지 못하므로, React Query는 동일한 데이터를 클라이언트에서 다시 요청하게 됩니다. 이로 인해 불필요한 중복 요청과 느린 사용자 경험이 발생할 수 있습니다.

Hydrate를 사용하면 서버에서 가져온 데이터를 클라이언트 React Query의 QueryClient 상태에 미리 주입할 수 있으므로, 다음과 같은 이점이 있습니다:

• ✅ 중복 요청 방지: 클라이언트에서 불필요하게 API를 다시 호출하지 않음
• ⚡ 빠른 첫 렌더링: 사용자에게 더 빠른 페이지를 제공
• 🔄 일관된 상태 유지: SSR과 CSR 간의 상태 불일치 문제 해결

🔍 Hydrate의 동작 원리

Hydrate는 서버에서 React Query의 상태(QueryClient 내부 상태)를 dehydrate() 함수를 통해 JSON 직렬화 가능한 형태로 변환한 뒤, 클라이언트에서 Hydrate 컴포넌트를 통해 이를 QueryClient에 복원하는 방식으로 동작합니다.

이 과정을 요약하면 다음과 같습니다:

1. 서버에서 QueryClient로 데이터를 prefetch
2. dehydrate 함수로 직렬화
3. Next.js의 getServerSideProps나 getStaticProps를 통해 props로 전달
4. 클라이언트에서 Hydrate 컴포넌트로 역직렬화 후 QueryClient에 주입

이렇게 주입된 초기 캐시는 클라이언트에서 useQuery 훅으로 접근 시 바로 사용되며, 같은 queryKey와 동일한 fetch 함수를 사용하는 경우 새로운 요청 없이 즉시 캐시 데이터를 보여줍니다.

🛠 예제 코드로 살펴보는 Hydrate 활용법

1. 서버에서 QueryClient 생성 및 데이터 prefetch

// pages/index.tsx
import { dehydrate, QueryClient, useQuery } from '@tanstack/react-query';
import { GetServerSideProps } from 'next';

const fetchData = async () => {
  const res = await fetch('https://api.example.com/data');
  return res.json();
};

export const getServerSideProps: GetServerSideProps = async () => {
  const queryClient = new QueryClient();
  await queryClient.prefetchQuery(['data'], fetchData);

  return {
    props: {
      dehydratedState: dehydrate(queryClient),
    },
  };
};

export default function Home() {
  const { data, isLoading } = useQuery(['data'], fetchData);
  return <div>{isLoading ? 'Loading...' : JSON.stringify(data)}</div>;
}

2. _app.tsx에서 Hydrate로 상태 복원

// pages/_app.tsx
import { Hydrate, QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useState } from 'react';
import type { AppProps } from 'next/app';

export default function MyApp({ Component, pageProps }: AppProps) {
  const [queryClient] = useState(() => new QueryClient());

  return (
    <QueryClientProvider client={queryClient}>
      <Hydrate state={pageProps.dehydratedState}>
        <Component {...pageProps} />
      </Hydrate>
    </QueryClientProvider>
  );
}

⚠️ Hydrate 사용 시 주의할 점

• Hydrate는 반드시 QueryClientProvider 내부에 위치해야 합니다.
• dehydrate로 직렬화된 데이터는 JSON으로 직렬화 가능한 값이어야 합니다.
• queryKey와 fetch 함수의 구현이 서버와 클라이언트에서 동일해야 캐시가 재활용됩니다.

💡 응용 팁과 실전 활용

• 정적 페이지 (SSG)에서도 활용 가능: getStaticProps와 함께 사용하여 정적 페이지도 빠르게 구성 가능
• 다국어 지원 시 유용: 초기 번역 데이터를 서버에서 주입하면 클라이언트에서 로딩 없이 UI 구성 가능
• 로그인 사용자 정보 프리패칭: 로그인한 사용자의 프로필 정보를 미리 캐시에 넣어둘 수 있음
• persistQueryClient와의 차이: Hydrate는 SSR 데이터 복원에 사용되며, persistQueryClient는 로컬 스토리지 등을 통한 캐시 지속에 활용됨

🧩 마무리: Hydrate는 선택이 아닌 필수!

React Query와 Next.js의 조합에서 Hydrate는 단순한 옵션이 아니라 꼭 활용해야 할 기능입니다. 서버에서 가져온 데이터를 클라이언트와 자연스럽게 이어주어 중복 요청을 방지하고, UX를 극대화하며, 성능까지 향상시켜주는 고마운 존재입니다.

Next.js 프로젝트에서 SSR을 적용하고 있다면, Hydrate를 반드시 고려해 보세요. 서버 상태 관리의 끝판왕으로, 더 빠르고 안정적인 웹 애플리케이션을 만들 수 있습니다.

🧪 링크 드라퍼, 지금 베타 테스트 중입니다

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 수정하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있습니다.

• 🔗 빠르고 간편한 링크 저장 • 🧠 저장한 링크를 폴더별로 정리 • 🌐 폴더를 친구에게 공유 가능 • ⚡ 크롬 익스텐션 원클릭 저장

👉 링크 드라퍼 베타 체험하러 가기 👉 크롬 웹스토어에서 설치하기

💬 카카오톡 채널 추가하고 소식 받기

서비스 업데이트 기능 꿀팁 카카오톡 채널을 통해 빠르게 받아보세요! 👉 카카오톡 채널 추가하기

안녕하세요, Link Dropper 팀의 개발자이자 늘 새로운 기술을 탐구하는 블로거입니다. 오늘은 제가 최근 흥미를 느끼고 있는 개념인 '바이브 코딩(Vibe Coding)'에 대해 이야기해보려 합니다. 코딩 없이 개발이라니, 정말 가능할까요? 이 글을 끝까지 읽으시면 그 궁금증이 해소될 겁니다!

1. 바이브 코딩이란?

1-1. 바이브 코딩, 대체 무엇인가요?

바이브 코딩은 AI의 도움을 받아 최소한의 코드 작성 또는 아예 코드 작성 없이 아이디어의 '바이브(Vibe)', 즉 느낌과 흐름을 즉시 구현해내는 개발 방식을 의미합니다. 기존의 개발 방식이 상세한 설계와 복잡한 코딩 과정을 거쳤다면, 바이브 코딩은 마치 디자이너가 스케치하듯 빠르게 아이디어를 구현하고, AI가 그 빈틈을 채워주며 완성도를 높이는 형태라고 할 수 있습니다.

이는 기존의 '노코드(No-code)' 또는 '로우코드(Low-code)' 플랫폼과는 조금 다릅니다. 노코드/로우코드가 미리 정의된 컴포넌트나 드래그 앤 드롭 방식을 통해 개발한다면, 바이브 코딩은 AI와의 상호작용을 통해 아이디어의 추상적인 부분까지 구체적인 결과물로 만들어내는 것에 가깝습니다. 단순히 기능 블록을 조립하는 것을 넘어, "이런 느낌의 웹사이트를 만들고 싶어", "사용자가 이런 경험을 하게 하고 싶어"와 같은 추상적인 지시어를 AI가 해석하여 코드를 생성하거나 UI/UX를 제안하는 등 훨씬 더 유연하고 창의적인 결과물을 만들어낼 수 있습니다.

1-2: 왜 바이브 코딩을 배워야 할까요? (비개발자 vs. 개발자)

그렇다면 왜 우리는 바이브 코딩에 주목해야 할까요? 비개발자와 개발자 모두에게 엄청난 기회를 제공하기 때문입니다.

👩‍💻 비개발자 관점: 내 아이디어를 코딩 없이 현실로!

많은 비개발자분들이 번뜩이는 아이디어를 가지고도 '코딩'이라는 장벽 앞에서 좌절하곤 합니다. 외주를 주거나 개발자를 찾는 과정은 비용과 시간, 그리고 커뮤니케이션의 어려움이 따르죠. 하지만 바이브 코딩은 이러한 문제를 단숨에 해결해 줍니다. 복잡한 프로그래밍 언어를 배우지 않아도, 내가 생각하는 기능과 디자인의 '느낌'만으로도 MVP(Minimum Viable Product, 최소 기능 제품)를 빠르게 만들어 볼 수 있습니다.

예를 들어, "사용자가 글을 쓰고, 좋아요를 누를 수 있는 간단한 커뮤니티 웹사이트를 만들어줘"라고 지시하면, AI가 기본적인 구조와 필요한 코드를 생성해 주는 식입니다. 아이디어 구상부터 서비스 론칭까지의 시간을 획기적으로 단축시켜, 시장의 변화에 발 빠르게 대응하고 끊임없이 아이디어를 테스트해 볼 수 있는 강력한 무기가 됩니다. 비개발자도 이제 '창작자'이자 '서비스 기획자'로서 자신의 아이디어를 직접 구현할 수 있는 시대가 온 것입니다.

👨‍💻 개발자 관점: 지루한 반복 작업은 AI에게! 핵심 로직에 집중하고, 디자인 스트레스는 그만!

"개발자인데 왜 코딩 없이 개발하는 방법을 배워야 해?"라고 생각할 수도 있습니다. 하지만 바이브 코딩은 개발자에게도 혁신적인 도구입니다.

가장 큰 장점은 **'디자인 및 프론트엔드 개발에 대한 부담 감소'**입니다. 많은 개발자가 백엔드 로직이나 핵심 기능 구현에는 강하지만, 프론트엔드의 세부적인 디자인이나 CSS 작업에 많은 시간을 할애하며 스트레스를 받곤 합니다. 바이브 코딩을 활용하면, AI가 디자인 시스템이나 레이아웃 구성을 제안하고 기본적인 UI 컴포넌트들을 생성해 주기 때문에, 개발자는 번거로운 디자인 작업을 크게 신경 쓸 필요 없이 서비스의 핵심 로직과 복잡한 기능 구현에만 집중할 수 있습니다.

또한, 반복적이고 boilerplate(보일러플레이트) 코드를 작성하는 시간을 절약하고, 초기 프로토타이핑을 훨씬 빠르게 진행할 수 있습니다. 이는 개발 생산성을 극대화하고, 더욱 창의적이고 도전적인 개발 프로젝트에 몰두할 수 있는 여유를 제공합니다. 마치 강력한 조수가 옆에서 늘 대기하고 있는 것과 같죠.

2. 바이브 코딩으로 만든 서비스 소개: 상상 그 이상의 구현!

바이브 코딩의 강력함을 증명하기 위해 제가 직접 만들어본 서비스들을 소개해 드립니다. 짧은 시간에 이렇게 다양한 기능들을 구현할 수 있다는 사실에 저 스스로도 놀랐습니다.

🚀 서비스 1: 초간단 투두리스트 (1시간 만에 뚝딱!)

처음으로 바이브 코딩의 힘을 시험해 본 프로젝트는 바로 투두리스트였습니다. 간단한 기능이지만, 백엔드까지 직접 구축하며 풀스택 개발 프로세스를 경험하고 싶었습니다.

• 소요시간: 단 1시간!
• 주요 특징:
  • 간단한 투두리스트 기능 구현
  • Firebase를 이용한 백엔드 구성으로 데이터 저장 및 관리
  • AI가 스스로 '개발자 도구'를 만들다! : 개발 과정에서 몇 가지 오류가 발생했는데, AI에게 "오류를 고쳐달라"고 요청했더니, AI가 스스로 개발자 도구를 만들어 주었습니다. 이 도구에는 Firebase 연결 테스트, 환경 진단, 샘플 데이터 생성 등 디버깅에 필요한 핵심 기능들이 포함되어 있어 정말 신기했습니다. AI의 문제 해결 능력과 창의성에 감탄할 수밖에 없었습니다.

🚀 서비스 2: AI 아티클 커뮤니티 (4시간 만에 완성!)

다음으로는 조금 더 복잡한 기능을 가진 AI 아티클 커뮤니티를 만들어 보았습니다. 사용자 간의 상호작용이 필요한 서비스였는데, 바이브 코딩 덕분에 빠른 시간 안에 구현할 수 있었습니다.

• 소요시간: 4시간
• 주요 특징:
  • AI 아티클 생성 에디터: 사용자가 AI에 대한 아티클을 직접 작성하고 게시할 수 있는 에디터 기능 구현.
  • 좋아요 및 댓글 기능: 게시물에 대한 좋아요와 댓글을 달 수 있어 사용자 간의 소통 활성화.
  • 1대1 채팅 기능: 사용자 간에 개별적으로 대화할 수 있는 채팅 기능까지 구현했습니다.
• 비고: 복잡한 기능들임에도 불구하고 AI와의 협업을 통해 빠르게 핵심 기능을 구현할 수 있었습니다.

🚀 서비스 3: 프롬프트 저장소 (8시간의 대장정, 풀스택 완성!)

마지막으로 도전한 프로젝트는 가장 규모가 컸던 프롬프트 저장소였습니다. AI 시대에 프롬프트의 중요성이 커지는 만큼, 프롬프트 작성이 어렵거나 개인 프롬프트를 관리하고 싶은 사용자들에게 프롬프트 피드백을 주고 성능 테스트를 도와주는 서비스를 만들고 싶었습니다.

• 소요시간: 8시간 (풀스택 서비스임에도 놀라운 속도!)
• 주요 특징:
  • 매력적인 랜딩 페이지: 서비스의 목적과 기능을 직관적으로 보여주는 랜딩 페이지 구축.
  • 프롬프트 작성 Form: 사용자가 다양한 카테고리의 프롬프트를 쉽게 작성하고 업로드할 수 있는 폼 제공.
  • 조회수 기록, 좋아요, Fork 기능: 인기 있는 프롬프트를 식별하고, 사용자가 다른 프롬프트를 자신에게 맞게 수정하고 저장할 수 있는 Fork 기능 구현.
  • 프롬프트 버전 관리: 프롬프트의 수정 이력을 추적하고, 이전 버전으로 되돌릴 수 있는 기능.
  • 프롬프트 분석 대시보드: 총 조회수, 총 좋아요 수 등 프롬프트의 성과를 차트 형태로 시각화하여 제공.
  • 프롬프트 커뮤니티: 사용자들이 프롬프트에 대한 의견을 나누고 정보를 공유하는 공간.
  • 프롬프트 엔지니어 토론장: 전문적인 프롬프트 엔지니어들이 심도 있는 토론을 펼칠 수 있는 장 마련.
  • 프롬프트 피드백: AI가 프롬프트를 피드백해주고 더 좋은 프롬프트를 제안. (구현 예정)
  • 프롬프트 성능 테스트: AI가 프롬프트의 성능을 테스트 (구현 예정)
• 비고: 이 프로젝트를 통해 바이브 코딩이 단순히 간단한 웹 페이지를 넘어, 복잡한 데이터 관리, 사용자 상호작용, 분석 대시보드까지 포함하는 종합적인 서비스 구현에도 탁월하다는 것을 깨달았습니다.

🌟 바이브 코딩, 개발의 미래를 그리다

바이브 코딩은 개발의 패러다임을 바꿀 강력한 도구라고 확신합니다. 이제 아이디어를 떠올리고, 그 아이디어를 즉시 구현해보는 것이 더 이상 '개발자'만의 특권이 아닙니다. 비개발자는 자신의 아이디어를 빠르게 검증하고 시장에 선보일 수 있으며, 개발자는 반복적인 작업에서 벗어나 더욱 창의적이고 핵심적인 문제 해결에 집중할 수 있게 됩니다.

물론, 바이브 코딩이 모든 것을 해결해 주지는 않을 겁니다. AI의 한계, 복잡한 커스터마이징의 어려움 등 넘어야 할 산은 분명히 있습니다. 하지만 중요한 것은, AI와의 협업을 통해 개발의 진입 장벽이 낮아지고, 아이디어의 구현 속도가 기하급수적으로 빨라진다는 사실입니다.

저는 앞으로도 바이브 코딩을 활용하여 더 다양한 서비스를 만들고, 그 경험과 노하우를 공유할 예정입니다. 여러분도 바이브 코딩으로 상상 속의 아이디어를 현실로 만들어보는 것은 어떨까요?

혹시 여러분만의 '바이브 코딩' 경험이나 아이디어가 있다면 댓글로 공유해 주세요! 만약 이 글의 반응이 좋다면, 다음 글에서는 제가 바이브 코딩을 활용한 구체적인 방법이나 꿀팁들을 소개해 드리겠습니다.

🧪 링크 드라퍼, 지금 베타 테스트 중입니다

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 수정하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있습니다.

• 🔗 빠르고 간편한 링크 저장 • 🧠 저장한 링크를 폴더별로 정리 • 🌐 폴더를 친구에게 공유 가능 • ⚡ 크롬 익스텐션 원클릭 저장

👉 링크 드라퍼 베타 체험하러 가기 👉 크롬 웹스토어에서 설치하기

💬 카카오톡 채널 추가하고 소식 받기

• 서비스 업데이트
• 기능 꿀팁 카카오톡 채널을 통해 빠르게 받아보세요!

👉 카카오톡 채널 추가하기

시작하며..!

이전에 코드 리뷰라는 주제로 포스팅을 한 적이 있었는데요, 저희는 실제로 두 명의 개발자가 서로 작성한 코드에 대해 리뷰를 주고받고 있습니다.

단순히 오류를 지적하는 것이 아니라, 작성자가 놓친 부분을 발견하거나 더 나은 코딩 방식을 제안하기 위한 목적이에요. 이를 통해 코드의 품질을 높이고, 서로의 성장까지 도모하기 위함이죠.

하지만 두 명만으로는 관점이 제한적일 수밖에 없고, 때로는 중요한 부분을 놓칠 수도 있습니다. 그래서 "AI가 우리가 놓친 부분까지 자동으로 리뷰해준다면 어떨까?" 라는 아이디어가 떠올랐습니다.

이번 포스팅에서는 직접 구현한, GitHub PR에 자동으로 AI가 리뷰 코멘트를 남기는 기능의 전체적인 흐름과 구현 과정을 간단히 소개해드릴게요!

🧩 어떤 기능인가요?

간단히 말하면, 누군가 GitHub에 Pull Request를 올리면, AI가 코드의 변경사항을 읽고 자동으로 리뷰 코멘트를 작성해서 남겨주는 기능입니다.

"어떤 부분이 개선될 수 있는지"나, "이건 왜 이렇게 했을까?" 같은 리뷰가 자동으로 달립니다. (실제로 어떤 종류의 리뷰를 작성할 지는, AI에게 어떻게 프롬프팅 하냐에 따라서 다르게 설정할 수 있어요!)

그럼 이 기능이 실제로 어떻게 동작하는지 하나씩 살펴볼게요.

🔁 전체 흐름 한눈에 보기

1. 누군가 특정 repo에 PR을 올린다

2. GitHub이 내 서버에 webhook 요청을 보낸다

3. PR 정보 확인 (내 서버)

4. 변경된 코드 내용 가져오기 (내 서버)

5. AI로 코드 리뷰 생성 (내 서버)

6. 다시 GitHub에 코멘트를 남긴다 🎯 (내 서버에서 -> github api를 통해)

🪜 각 단계별로 조금만 더 자세히 알아볼게요!

1. GitHub Webhook 이벤트 받기

GitHub에는 웹훅(webhook)이라는 기능이 있어요. 레포지토리에서 어떤 일이 발생했을 때 지정된 URL로 HTTP 요청을 보내주는 기능이죠.

(이 웹훅은 github에서 아래 과정에 따라 추가 가능해요!)

** 원하는 레포지토리 > Settings > Webhooks > Add webhook **

PR이 생성되거나 업데이트되면 GitHub은 저희가 만든 서버의 특정 엔드포인트로 POST 요청을 보냅니다

요청에는 PR 번호, 레포지토리 정보, 파일 목록 등 다양한 정보가 포함돼요

2. 요청의 진짜 여부 확인하기 🔐

요청이 진짜 GitHub에서 온 건지 확인하는 게 중요해요. 그래서 HMAC-SHA256 방식으로 서명(signature)을 검증합니다.

GitHub는 요청과 함께 X-Hub-Signature-256 헤더를 보내줍니다

우리는 같은 방식으로 서명을 계산해서 비교합니다 일치하지 않으면 요청을 거부해요.

3. PR 관련 이벤트만 처리

GitHub에서 보내는 이벤트는 정말 다양해요. 그 중 우리는 PR 관련 이벤트만 관심이 있습니다.

PR이 "열리거나(opened)", "업데이트(synchronize)"되었을 때만 처리합니다

그 외 이벤트는 무시하고 진행하지 않아요!

4. PR 정보 뽑기

이제 PR 번호와 레포지토리 정보를 꺼내야겠죠?

PR 번호 (pr_number) 레포지토리 이름 (repo_full_name)

이 정보는 나중에 GitHub API 호출에 꼭 필요합니다.

5. 리뷰 체인 실행하기 ⚙️

우선 모든 리뷰 과정을 담당하는 클래스를 하나 만들었어요. PRReviewChain

review_chain = PRReviewChain(pr_number, repo_full_name) review_chain.run()

이 클래스에 pr번호와, 레포지토리 이름을 전달하는 것으로 내부에 있는 다양한 과정들이 시작돼요!

6. GitHub API로 PR 정보 가져오기

GitHub의 공식 API를 사용해서 PR에 어떤 변경이 있었는지 확인합니다.

어떤 파일이 수정됐는지 (get_pull_request_files) 전체 diff 내용은 어떤지 (get_pull_request_diff) 이때 필요한 인증은 GitHub Access Token을 사용해 처리합니다.

7. LangChain + OpenAI로 리뷰 생성 🧠

이제, AI가 리뷰를 생성합니다!

AI로 리뷰를 생성할 때, LangChain이라는 프레임워크를 사용했어요. (LangChain은 GPT 같은 언어 모델을 다양한 도구와 쉽게 연결해주는 프레임워크에요. 단순히 프롬프트만 보내는 게 아니라, 외부 API 연결, 응답 가공, 히스토리 관리 등등 수많은 API들이 포함되어 있어요!)

아무튼, AI에게 저희가 사전에 설정한 프롬프트를 전달하게 돼요! 프롬프트에는 저희가 사용하는 코딩 컨벤션이나, 어떤 부분을 중점적으로 리뷰해야하는지 등 다양한 정보들을 같이 포함했어요!

8. GitHub PR에 코멘트 달기

이렇게 AI가 생성한 리뷰를 GitHub에 다시 올릴 차례!

전체 리뷰 → PR에 단일 코멘트로 추가 파일별 리뷰 → 각 파일 라인에 코멘트로 추가

이 작업도 GitHub API를 통해 처리됩니다.

이렇게 최종적으로, 실제 GitHub의 Pull-request에는 AI가 남긴 리뷰가 등록이 돼요!

🎨 그림 요약

간단하게는 github과 제 서버, 그리고 LLM이 아래와 같은 느낌으로 상호작용하고 있어요!

🙌 마무리하며 (프롬프트가 핵심이다!)

지금까지 소개해 드렸던 전체적인 흐름도 중요하지만, 사실 이 프로젝트의 가장 중요한 요소는 ‘프롬프트’에요.

어떤 질문을 어떻게 구성해서 AI에게 던질지에 따라, 리뷰의 품질이 완전히 달라지거든요. 예를 들어, “이 코드를 개선해줘”가 아니라, “이 코드에서 보안상 문제가 있는 부분을 알려줘”라고 하면 전혀 다른 리뷰가 나오게 돼요!

그래서 프롬프트를 어떻게 구성하느냐에 따라 리뷰 스타일, 깊이, 방향성을 원하는 대로 조정할 수 있어요. 앞으로 다양한 방식으로 프롬프트를 수정하며, 리뷰의 품질을 저희가 원하는 방향으로 개선해 볼 예정이에요!

🧪 링크 드라퍼, 지금 베타 테스트 중입니다

링크 드라퍼는 단순한 저장 툴이 아닙니다. 정리하고, 수정하고, 다시 꺼내보게 만드는 링크 관리 도구를 지향하고 있습니다.

• 🔗 빠르고 간편한 링크 저장 • 🧠 저장한 링크를 폴더별로 정리 • 🌐 폴더를 친구에게 공유 가능 • ⚡ 크롬 익스텐션 원클릭 저장

👉 링크 드라퍼 베타 체험하러 가기 👉 크롬 웹스토어에서 설치하기

💬 카카오톡 채널 추가하고 소식 받기

• 서비스 업데이트
• 기능 꿀팁

카카오톡 채널을 통해 빠르게 받아보세요!

👉 카카오톡 채널 추가하기

Next.js는 app router 기반 프로젝트에서 기본적으로 fetch와 page rendering을 SSR(Server Side Rendering) 또는 SSG(Static Site Generation) 방식으로 처리합니다. 여기서 캐시 전략을 어떻게 쓰느냐에 따라 페이지의 성능, 사용자 경험, SEO가 좌우됩니다.

🧩 캐싱 전략 ① Request Cache (요청 캐시)

동일한 fetch 요청은 한 번만 처리하고, 이후에는 결과를 재사용합니다.

✅ 특징

• 같은 fetch 요청이 여러 번 있어도, 한 번만 네트워크 요청이 발생
• 메모리 캐시 기반 (서버에서만 작동)
• 서버리스 환경에서는 인스턴스 간 캐시 공유 안 됨

✅ 예시 코드

const A = async () => await fetch('/api/workspace');
const B = async () => await fetch('/api/workspace'); 
// 같은 요청, 한 번만 요청됨

❗️주의사항

• URL, 쿼리, 헤더 등이 모두 일치해야 캐싱됩니다.
• 과도한 캐시는 메모리 문제를 유발할 수 있음

🔧 캐시 무효화 방법

await fetch('/api/data', {
  next: { cache: 'no-store' }
});

🧱 캐싱 전략 ② Build-time Cache (빌드 타임 캐시)

next build 시점에 fetch를 실행하고, 정적으로 캐싱합니다.

✅ 특징

• 빌드 시 데이터가 고정
• 실제 배포 환경에서는 auto 캐시 정책이지만, 정적 fetch는 force-cache처럼 동작

😨 문제가 생기는 시나리오

const TodoListPage = async () => {
  const todos = await getTodoList();
  return (
    <ul>
      {todos.map((todo, i) => <li key={i}>{todo}</li>)}
    </ul>
  );
}

const CreateTodoPage = () => {
  const onSaveTodo = async () => {
    await saveTodo();
    router.push('/todo-list');
  }

  return <button onClick={onSaveTodo}>생성</button>;
}

🛠 해결 방법

1. no-store 사용 (항상 최신 데이터)
2. revalidateTag로 특정 캐시 무효화

await fetch('/api/todos', {
  next: { tags: ['todos'] }
});

revalidateTag('todos');

📦 캐싱 전략 ③ Page Cache (페이지 캐시)

유저가 방문한 페이지를 캐싱하여 다음 요청 시 빠르게 응답합니다.

✅ 특징

• 요청 시 SSR 결과를 저장
• 이후 같은 요청이 오면 캐시로 응답
• ISR 기반으로 작동함

🚀 캐싱 전략 ④ Prefetch Cache (사전 로딩 캐시)

유저가 아직 클릭하지 않은 링크에 대해 백그라운드에서 미리 데이터를 가져옵니다.

✅ 작동 원리

• <Link>는 정적 경로에 대해 자동 prefetch
• Intersection Observer로 뷰포트 내에서만 작동
• 브라우저 캐시 활용

<Link href="/about">About</Link>
<Link href="/about" prefetch={false}>About</Link>

💡 성능을 위해 캐시 전략을 더 잘 쓰는 팁

1. fetch는 props 전달 대신, 하위 컴포넌트에서 다시 호출

const Parent = () => <Child />
const Child = async () => {
  const data = await fetchData();
}

2. Client Component는 꼭 필요한 경우만 사용

const Page = () => <ModalButton />

3. 서버에서 fetch 후 클라이언트에 전달

const Server = async () => {
  const data = await fetchData();
  return <Client data={data} />
}

📚 참고 자료

• 공식 문서: Next.js Data Fetching and Caching

🗂 Words

📢 함께 보면 좋은 소식

🧪 링크 드라퍼, 지금 베타 테스트 중입니다

링크 드라퍼는 링크를 저장하고, 정리하고, 다시 꺼내보게 만들어주는 서비스입니다.

• 📎 폴더별 링크 정리
• ✨ OG 이미지 자동 추출
• 🧠 공유 URL 생성 및 게시 기능
• ⚡ 크롬 익스텐션 원클릭 저장

👉 링크 드라퍼 베타 체험하러 가기 👉 크롬 웹스토어에서 설치하기

💬 카카오톡 채널 추가하고 소식 받기

• 서비스 업데이트
• 기능 꿀팁 카카오톡 채널을 통해 빠르게 받아보세요!

👉 카카오톡 채널 추가하기

스타트업, 사이드 프로젝트, 혹은 초기 단계의 조직에서는 코드리뷰를 하지 않아도 당장 눈에 띄는 문제는 없어 보입니다.

• “리팩터링은 나중에 하지 뭐”
• “어차피 혼자 짠 건데 뭐하러 리뷰해”
• “시간 없는데 코드 보느라 시간을 낭비할 순 없어”

하지만 코드는 '현재'만을 위한 것이 아닙니다. 2주 후, 2달 후, 또는 다른 사람이 봤을 때 잘 읽히고, 안전하고, 유지보수 가능한 코드여야 합니다.

코드리뷰는 바로 그 연결고리 역할을 합니다.

✅ 코드리뷰가 가져다주는 진짜 효과

1. ❗ 버그를 미리 발견할 수 있습니다

코드리뷰는 실시간 테스트 도구입니다. 의도하지 않은 side effect나 누락된 예외 처리를 빠르게 포착할 수 있습니다.

2. 📘 코드 스타일과 구조가 통일됩니다

비슷한 기능을 전혀 다른 방식으로 구현하면 기술 부채로 이어집니다. 리뷰를 통해 컨벤션을 지키고 통일성을 유지할 수 있습니다.

3. 🧠 비즈니스 로직 이해도와 팀 전파력이 올라갑니다

“이 기능 왜 이렇게 만들었지?”를 코드 안에서 유추하는 것이 아니라, 리뷰 과정을 통해 명시적이고 문맥적으로 전달할 수 있습니다.

4. 🙌 학습의 기회이자 성장의 루틴이 됩니다

리뷰는 단순 피드백이 아니라 지식 교류입니다. 주니어는 시니어의 관점을, 시니어는 주니어의 시도를 배울 수 있습니다.

은근히 많이 듣는 이야기: “리뷰하다가 내가 더 배웠어요.”

5. 🚀 리뷰는 곧 제품 품질입니다

성공적인 코드리뷰 문화는 곧 서비스 안정성으로 이어집니다.

❌ 그렇다면, 코드리뷰의 어려움은?

• 리뷰하는 데 시간이 걸립니다
• 코드 문맥을 모르면 피드백이 어렵습니다
• 감정 섞인 표현은 의도치 않게 상처가 될 수 있습니다

하지만 이건 도구와 문화로 극복할 수 있습니다:

• 리뷰 기준을 명확히 하고
• PR 템플릿을 도입하고
• 피드백의 목적이 '사람'이 아니라 '코드'라는 점을 잊지 않는 것

🤝 리뷰를 ‘지적’이 아닌 ‘제안’으로 바꾸는 법

리뷰어의 말 한 마디가 조직의 분위기를 바꿉니다.

❌ “이건 잘못됐어요.” ✅ “혹시 이런 방식은 어떨까요?”

❌ “이거 왜 이렇게 짰나요?” ✅ “이렇게 구현하신 이유가 궁금합니다!”

❌ “이 함수는 너무 복잡해요.” ✅ “한 번 분리해보면 가독성이 더 좋아질 수 있을 것 같아요!”

😌 리뷰를 받는 입장에서 기분 나쁘지 않게 하려면?

• 🙏 “질문드릴게요” → 상대에 대한 존중 표현
• 🙇‍♂️ “제가 잘 몰라서 여쭤봅니다” → 대화의 시작을 부드럽게
• 🤝 “이런 방향도 고려해보면 좋을 것 같아요” → 피드백보다는 협업 제안

📚 코드리뷰를 '배움'으로 바꾸는 팀 문화 만들기

• 코멘트가 마음에 안 들어도 일단 ‘왜 그렇게 말했을까?’ 생각하기
• 리뷰어도 반대로 리뷰받아보기 → ‘양방향 문화’ 조성
• 리뷰 요청 시: “특히 어떤 부분이 궁금한지” 적어두기
• 리뷰 후: 칭찬도 같이 남기기! (예: 네이밍 좋네요, 리팩터링 방향 좋습니다 등)

🏷️ Pn 룰 가이드

**Pn 룰(Priority Notation)**은 리뷰 코멘트를 우선순위 기반으로 분류하여, 리뷰어와 개발자 간의 커뮤니케이션을 더 명확하게 해주는 방법입니다.

💬 예시 코멘트

• P1: useEffect 안에 비동기 함수가 직접 들어가 있어서 에러가 발생할 수 있어요. 반드시 수정해주세요. (P1)
• P2: 이 API 호출은 debounce 처리하는 게 UX 측면에서 좋을 것 같아요. (P2)
• P3: 변수명을 조금 더 명확하게 해도 좋을 것 같아요. 예: result → userScore (P3)
• P4: 코드 스타일은 팀 내 규칙에 따라 정리하셔도 괜찮습니다. (P4)
• P5: 이 부분 개인적으로 너무 좋네요. 👍 (P5)

✍️ 코드리뷰를 요청하는 사람은 어떻게 해야 할까?

✅ 커밋을 논리적으로 잘게 나누기

• 기능 단위로 나누기: feat: 로그인 폼 레이아웃 추가, feat: 로그인 요청 API 연동
• 수정 단위로 나누기: fix: 로그인 상태관리 오류 수정

✅ 커밋 메시지를 명확하게 작성하기

• ❌ 불명확한 메시지: fix, update
• ✅ 명확한 메시지: fix: 로그인 API 요청 시 중복 호출 방지

✅ PR 설명을 꼼꼼하게 작성하기

## 작업 개요
- 로그인 기능 중 상태 관리 구조를 개선했습니다.

## 주요 변경 사항
- Zustand → Context API 마이그레이션
- API 요청 로직을 커스텀 훅으로 분리

## 리뷰 받고 싶은 부분
- 상태 구조가 적절한지
- 요청 훅 분리 방식에 개선 여지가 있는지

🧪 링크 드라퍼, 지금 베타 테스트 중입니다

링크 드라퍼는 링크를 저장하고, 정리하고, 다시 꺼내보게 만들어주는 서비스입니다.

• 📎 폴더별 링크 정리
• ✨ OG 이미지 자동 추출
• 🧠 공유 URL 생성 및 게시 기능
• ⚡ 크롬 익스텐션 원클릭 저장

👉 링크 드라퍼 베타 체험하러 가기 👉 크롬 웹스토어에서 설치하기

💬 카카오톡 채널 추가하고 소식 받기

• 서비스 업데이트
• 기능 꿀팁

카카오톡 채널을 통해 빠르게 받아보세요!

👉 카카오톡 채널 추가하기