열정을 기록하기

Claude Code Skills로 코드리뷰 Skill 커스텀 해보기

huncozyboy — Mon, 23 Mar 2026 18:20:39 +0900

들어가며

Claude Code의 Skills는 Claude가 특정 작업을 더 잘 수행하도록 지침, 스크립트, 리소스를 폴더 단위로 묶어두는 방식이다.
쉽게 말하면, 비슷한 역할을 수행하는 기능들을 하나의 묶음으로 구성해 재사용 가능하게 만든 구조라고 이해하면 된다

공식 문서에서는 Skills를 이렇게 설명한다.

Skills extend what Claude can do.
Create a SKILL.md file with instructions, and Claude adds it to its toolkit.

SKILL.md 파일 하나만 만들어줘서 Claude의 “능력” 자체를 확장할 수 있다는 의미다

https://code.claude.com/docs/en/slash-commands

Extend Claude with skills - Claude Code Docs

Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom commands and bundled skills.

code.claude.com

SKILL.md를 중심으로 동작하고, 필요하면 /skill-name 형태로 직접 호출할 수도 있다. Claude 내부 context에 로드시켜서 특정 명령어를 입력한다면, Claude가 작업 문맥에 맞춰 자동으로 불러오기도 한다. 만약에 반복해서 하는 작업들이 있다면 재사용이 가능하도록, 리소스를 줄일 수 있다

해당 기능을 사용해보면서, 개발자가 아니여도 PDF, PPT, Word, Excel 같은 것도 원하는대로 커스텀하여 제작 시간을 줄일 수도 있겠다라는 생각이 들기도 하였다

Anthropic에서 공식으로 Skills 마켓플레이스를 제공해주고 있으니까, 여러가지 내용들을 둘러보고 필요한 내용들은 활용해준다면 좋을거같다

https://github.com/anthropics/skills

GitHub - anthropics/skills: Public repository for Agent Skills

Public repository for Agent Skills. Contribute to anthropics/skills development by creating an account on GitHub.

github.com

공식 문서 기준으로 Skill은 아래의 구조처럼 생성된다고 설명한다

1. Skills 구조 이해하기

위는 예시이고, 여기서 SKILL.md를 커스텀한다고 생각해주면 된다

name은 레거시 코드 내용 팔로업으로 네이밍하고, description에서는 간단하게 코드 팔로업용 Skill과 아래의 내용들을 작성해놓을 수도 있다
코드를 설명시, 아래 내용 포함 :

1. 비유

2. 다이어그램

3. API 요청 - 응답 플로우

2. Skill은 언제 실행될까?

Claude uses skills when relevant, or you can invoke one directly with /skill-name.

크게 보면 자동 실행 (문맥 기반)과 앞서 서론에서 짧게 설명한 수동 실행 (/skill-name) 방식을 의미한다

좀 더 자세히 설명해보면, 자동 실행은 Claude가 현재 요청의 의도를 해석한 뒤 가장 적절한 Skill을 스스로 선택해 적용하는 방식이다. 예시로 테스트 코드 작성이나 깃허브 PR, 이슈 등등의 문서처럼 반복적인 컨벤션이 있는 작업에서는 사용자가 명시하지 않아도 별도의 호출 없이 관련 Skill이 자연스럽게 적용될 수도 있다

해당 이유에서 수동 실행의 세부적인 커스텀이 중요하다. 결론부터 먼저 얘기하자면 수동 실행을 잘쓰기 위해선 description을 잘 써야 한다. 이유는 description이 모호하면 의도하지 않은대로 자동 실행이 작동할 수도 있고, 만약에 Skill을 사용하여 수동으로 호출하더라도 의도한 방식으로 동작하지 않을 가능성이 높기때문이다

추가적으로 /skill-name 을 설정해두면 편리한 이유는 로고, 폰트, 색상 같은 브랜딩 규칙이나 특정 팀의 문서 양식, 리뷰 기준, 출력 형식을 클로드에게 반복해서 설명하지 않아도 된다는 점이다. 한번 Skill로 정의해두면 Claude가 해당 컨텍스트를 일관되게 재사용하기 때문에, 기준이 흔들리지 않고 원하는 품질에 가깝게 결과를 유지할 수 있다

본론

이제 본격적으로 코드리뷰 관련 Skills를 만드는 예시를 설명해보려한다

1. 초기 세팅

skill-creator는 document-skills가 아니다. 이게 무슨 말이냐면, document-skills는 이름 그대로 문서 생성 계열 Skill 묶음일 뿐이고 코드리뷰 Skill을 만들고 싶다면 document-skills만 설치해서는 부족하다는 뜻이다. 따라서 추가적인 설치가 필요하다는 뜻이다

/plugin marketplace add anthropics/skills

/plugin install document-skills@anthropic-agent-skills

/plugin install example-skills@anthropic-agent-skills

/reload-plugins

만약에 문서 생성만 하고싶다면 두번째 줄 플러그인만 설치해도 충분하지만, 코드 리뷰용 Skill을 만들기 위해서는 해당 플러그인들이 모두 필요하다고 이해해주면 된다

2. 코드 리뷰 가이드 생성

개인적으로 먼저 Claude에게 가이드를 주고 시작하는 것이 좀 더 완성도가 높았던거같다. 예를 들면 아래처럼 시작할 수 있다

코드리뷰 관련 skills를 작성하고 싶은데, 먼저 코드리뷰 best practice를 찾아서 학습해봐. 특히 아키텍처 경계, 예외 처리, 테스트 가능성, 성능, 보안, 가독성 관점으로 정리해줘.

3. skill-creator로 코드리뷰 Skill 만들기

기준 정리가 끝나면 이제 실제 Skill 생성을 시킬 수 있는데, 아래는 예시니까 참고만 해주면 좋을거같다

이제 skill-creator skills를 써서

방금 학습한 코드리뷰 철학으로 코드리뷰 Skills를 만들어줘.

Compaction이 일어나도 중요한 상태를 유지할 수 있게

reference 파일, 체크리스트, 중간 산출물 구조도 함께 고려해줘.

이렇게 하면 서론에 설명한거처럼 Skills.md가 생성되는데, 레퍼런스 파일들도 함께 생성됩니다

여기서 SKILL.md의 frontmatter는 최대한 자세하게 적어주는게 좋다

4. Compaction까지 고려해서 설계

여기서 중요한 점이 하나 있는데, Skill 자체가 대화 상태를 영구 저장해주는 것은 아니다. Claude Code는 컨텍스트가 차면 자동으로 또는 /compact 명령으로 대화를 요약해 공간을 확보할 수 있는데, 이 과정에서 세부 맥락이 일부 사라질 수도 있다. 공식 문서도 compaction 이후 중요한 문맥이 손실될 수 있다고 설명하면서, SessionStart hook의 compact matcher를 이용해 핵심 컨텍스트를 다시 주입하는 예시를 제공해주기도 한다

따라서 아래의 내용처럼 설계해주면, 커스텀한 내용들이 휘발되지 않도록 복구하는 플로우를 생성해줄 수도 있다

첫째, SKILL.md에는 핵심 workflow만 두고 상세 기준은 references/로 분리

둘째, 리뷰 중간 결론이나 체크포인트는 .claude/state/code-review-summary.md 같은 파일에 따로 남긴다

셋째, compaction 이후 이 파일을 다시 읽게 만드는 hook을 둔다

마치며

개인적으로 해당 방식의 장점은 명확하다고 생각한다

1. 한 번 잘 만들어둔 작업 방식을 계속 재사용할 수 있다

2. document-skills와 결합하면, 코드리뷰 이후 결과를 Word나 PPT 요약본 등으로 시각화 할 수도 있다

3. Anthropic에서 제공해주는 공식 플러그인이라 그런지 퀄리티는 보장해주는거같다

클로드 코드 개발자 Boris Cherny의 클로드 코드 사용법 (Claude Code)

huncozyboy — Sat, 7 Feb 2026 19:56:56 +0900

들어가며

요즘 클로드 코드(Claude Code)가 정말 빠른 속도로 발전하고 있다고 생각한다. 얼마전에 1000개 이상의 쿼리를 단기간에 마이그레이션 하기위해서 Copilot Agent Mode 를 활용했던거 처럼, 단순 AI 발전 말고도 개발자의 더 명확한 판단 능력, 검증을 설계하는 능력, 작업을 자동화하는 능력 등등이 더 중요해지고 있다고 판단했다.
https://huncozyboy.tistory.com/66

AI Copilot Agent Mode로 SQL 쿼리 마이그레이션 (Copilot)

들어가며CUBRID 데이터베이스 환경에서 돌아가던 SQL 쿼리들을 MySQL 8.x로 마이그레이션하는 작업을 한 내용으로 포스팅을 해보려고 한다.AI Copilot(Agent Mode)을 활용해 1000개가 넘는 쿼리 변환을 성공

huncozyboy.tistory.com

이번 글은 클로드 코드를 만든 사람, 보리스(Boris Cherny)가 직접 공유한 사용법을 인용해서 정리해보았다.

본론

1) Claude 프로세스 5개를 동시에 실행

먼저 터미널에서 Claude 프로세스 5개를 동시에 실행한다.

탭에 1~5번까지 번호를 매기고, 시스템 알림을 사용하여 Claude 프로세스가 입력을 필요로 할 때를 알 수 있다.

좀 더 추가적으로 설명하자면 1번 프로세스는 특정 기능 구현, 2번 프로세스는 테스트 코드 작성, 3번 프로세스는 작업한 내용 문서화,
4번 프로세스는 PR 내용 작성 등등으로 한가지의 큰 task가 아닌 여러가지의 task들을 동시에 돌리는 것들도 가능하다는 얘기이다.
(한 세션에서 복잡해진 대화가 다른 작업을 오염시키지 않는다는 점이다. 대신 같은 파일을 여러 세션이 동시에 건드리면 충돌이 날 수 있으니, 보통은 큰 API에 대한 작업이라면 작업 범위를 파일/도메인 단위로 분리해서 맡기기도 한다.)

https://code.claude.com/docs/en/terminal-config#iterm-2-system-notifications

2) 로컬 Claude 세션 병렬 실행

그 다음 로컬 Claude 세션과 병렬로 https://claude.ai/code 서버에서 5~10개의 Claude 세션을 실행한다.

터미널에서 코딩할 때, 종종 로컬 세션을 웹 서버로 전환(& 사용)하거나 Chrome에서 수동으로 세션을 시작하기도 한다.

Boris는 --teleport 명령어를 사용하여 터미널과 웹 서버를 오가기도 하면서, 매일 아침과 하루 동안 휴대폰(Claude iOS 앱)에서 몇 개의 세션을 시작하고 나중에 확인한다고 말했다. (즉, 터미널만 사용한다기보다는 로컬 세션을 웹/모바일로 이어받거나, 웹에서 시작한 세션을 터미널로 가져오는 식의 작업들도 가능하다)

3) Opus 4.5 모델 사용

모델은 모든 것에 사고 기능을 갖춘 Opus 4.5를 사용한다.

제가 사용해 본 코딩 모델 중 최고이며, Sonnet보다 크고 느리긴 하지만,

직접 조작할 필요가 적고 도구 활용 능력이 뛰어나기 때문에 결과적으로는 더 작은 모델을 사용하는 것보다 거의 항상 더 빠르다고 한다.
(+ 2026년 3월 기준으로는 opusplan을 사용하여 plan mode에서는 Opus를 쓰고 실행 단계에서는 Sonnet을 사용 하는거처럼 유동적으로도 가능하다)

4) Claude Code md 파일 설정

Boris의 팀은 Claude Code 저장소에 대해 하나의 CLAUDE.md 공유한다. 변경사항을 git에 커밋하고, 팀 전체가 일주일에 여러 번 기여한다. Claude가 잘못된 작업을 수행하는 것을 발견할 때마다 CLAUDE.md 에 추가하여 Claude가 다음번에 같은 실수를 하기 위함이기 때문에, 다른 팀들은 자체적인 CLAUDE.md '를 유지한다. 각 팀은 자신의 '를 최신 상태로 유지해야 할 책임이 있다.

아키텍처 원칙
테스트 코드 컨벤션, 실행 순서
수정하면 안되는 파일
코드 스타일
DB/도메인 규칙
N+1 위험이 있는 쿼리 패턴 지양

5) PR에 @.claude를 태그

코드 리뷰 중에 Boris는 종종 동료들의 PR에 @.claude를 태그하여 PR의 일부로 CLAUDE.md 에 무언가를 추가한다고 한다. 이를 위해 Claude Code GitHub 액션 (/install-github-action)을 사용한다. 해당 내용은 @danshipper 의 Compounding Engineering과 유사한 기능을 의미한다.

6) 계획 모드 -> 승인 모드 전환

대부분의 세션은 계획 모드(Shift+Tab 두 번 누르기)에서 시작한다. 만약에 풀 리퀘스트를 작성하는 것이 목표라면 계획 모드를 사용하고, 마음에 드는 계획이 나올 때까지 Claude와 의견을 주고받고, 계획이 완성되면 편집 자동 승인 모드로 전환하고, Claude는 보통 한 번에 풀 리퀘스트를 승인하는 과정을 가진다고 한다.

(개인적으로 클로드를 다른 AI와 구분하여, 제일 선호하는 이유이기도 하다. Claude가 변경 대상 파일, 영향 범위, 위험 지점, 테스트 전략 등등을 제안하며 수준 높은 바이브 코딩이 가능하다고 생각한다.)

7) 내부 루프 워크플로에 슬래시 명령어를 사용

하루에도 여러 번 반복해서 수행하는 모든 내부 루프 워크플로에 슬래시 명령어를 사용한다고 한다. 이렇게 하면 반복적인 프롬프트 표시를 피할 수 있고, Claude도 이러한 워크플로를 사용할 수 있으며, 명령어는 Git에 커밋되어 .claude/commands/ 디렉토리에 저장되어 관리된다. 예를 들어, Claude와 매일 수십 번씩 /commit-push-pr 슬래시 명령어를 사용하는데, 해당 명령어는 인라인 bash를 사용하여 git 상태와 몇 가지 다른 정보를 미리 계산하여 명령어가 빠르게 실행되고 모델과의 반복적인 상호 작용을 방지할 수 있는 효과가 있다.(https://code.claude.com/docs/en/slash-commands#bash-command-execution).

8) 몇 가지 서브에이전트의 정기적으로 사용

code-simplifier는 Claude가 작업을 완료한 후 코드를 간소화하고, verify-app은 Claude 코드의 엔드 투 엔드 테스트에 대한 자세한 지침을 제공하는 등의 기능을 해준다. Boris는 슬래시 명령어와 마찬가지로 서브에이전트는 대부분의 PR에서 수행하는 가장 일반적인 워크플로를 자동화하는 도구라고 생각한다.

https://code.claude.com/docs/en/sub-agents

code-simplifier.md: 구현 끝난 뒤 복잡도 낮추기, 가독성 높이기 등등
verify-app.md: 테스트, 브라우저, E2E 검증
oncall-guide.md: 장애 대응 점검 절차
db-reviewer.md: 쿼리, 인덱스, N+1 점검

만약 퇴근시에 background로 작업한 내용들이 궁금하다면 session-summary.md 등의 파일을 활용하여 작업에 대한 원하는 양식으로 요약을 담당할 수도 있고, Notification hook 등의 md 파일을 관리하여 작업한 내용에 대한 알림을 받을 수도 있다.

9) PostToolUse 훅을 사용하여 Claude의 코드 형식을 지정

Claude는 일반적으로 기본적으로 형식이 잘 지정된 코드를 생성하며, 이 훅은 나중에 CI에서 형식 오류가 발생하지 않도록 나머지 10%를 처리한다. hook은 CLAUDE.md와 다르게 결정론적으로 실행되는 자동화다. 공식 문서도 “CLAUDE.md는 advisory, hooks는 deterministic”이라고 설명한다. 그래서 Claude가 파일을 수정할 때마다 아래 명령어 들을 ostToolUse hook으로 돌리면, 사람이 마지막에 검증시에 시간을 덜 쓰게 된다. 이 설정은 .claude/settings.json 또는 /hooks 메뉴로 관리할 수 있다.

spotlessApply
Gradle에 붙인 Spotless 포맷터를 실행해서, 프로젝트에 설정된 Java/Gradle/Kotlin 등의 코드 스타일 위반을 자동으로 수정해준다. (Java라고 가정시에 17, 21 버전 등등에 맞게 설정 가능)

./gradlew ktlintFormat
Kotlin 프로젝트에서 ktlint 규칙에 맞게 .kt, Kotlin script 파일들을 자동 포맷한다. ktlint Gradle plugin 공식 문서에 잘 나와있으며, ktlintFormat을 Kotlin 파일과 Kotlin script를 코드 스타일에 맞게 format

10) --dangerously-skip-permissions 옵션 미사용

--dangerously-skip-permissions 옵션을 사용하는대신 /permissions 명령어를 사용하여 제 환경에서 안전하다고 판단되는 일반적인 bash 명령어를 미리 허용함으로써 불필요한 권한 요청 메시지를 방지한다. 해당 설정 대부분은 .claude/settings.json 파일에 저장되어 팀과 공유된다.

11) Claude Code에서도 사용하는 모든 도구를 활용 (MCP)

Boris는 MCP 서버를 통해 Slack에 검색 및 게시물을 올리고, bq CLI를 사용하여 BigQuery 쿼리를 실행하여 분석 관련 질문에 답변하고, Sentry에서 오류 로그를 가져오는 등의 작업을 수행한다고 한다. 또한 Slack MCP 구성은 .mcp.json 파일에 커밋되어 팀과 공유된다.

MCP란 ?
Claude Code에 외부 도구, 데이터베이스, API를 붙이는 표준 방식을 말한다. 공식 문서도 MCP를 통해 수백 개의 외부 도구와 데이터 소스에 연결할 수 있다고 설명한다. 보통 팀 실무에서는 .mcp.json을 저장소에 커밋해 두고, 프로젝트 공통 도구를 함께 쓰게 만들어주기도 한다.

매우 오래 걸리는 작업의 경우,

(a) 작업이 완료되면 백그라운드 에이전트를 사용하여 Claude가 작업을 확인하도록 메시지를 표시하거나,

(b) 에이전트 Stop 후크를 사용하여 보다 확정적으로 확인하거나,

(c) ralph-wiggum 플러그인(원래 @GeoffreyHuntley 이 구상함)을 사용한다. 또한 샌드박스 환경에서 --permission-mode=dontAsk 또는 --dangerously-skip-permissions 옵션을 사용하여 세션에 대한 권한 프롬프트를 방지함으로써 Claude가 제 작업으로 인해 차단되지 않고 작업을 수행할 수 있도록 한다.

https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-wiggum

https://code.claude.com/docs/en/hooks-guide

13) Claude에게 작업 검증 방법을 제공

Claude Code -- 에서 훌륭한 결과를 얻기 위한 가장 중요한 것은 Claude에게 작업 검증 방법을 제공하는 것이다.

Claude가 이러한 피드백 루프를 갖추면 최종 결과의 품질이 2~3배 향상될 것이라고 Boris는 말한다.

긴 테스트, 빌드, 시뮬레이터, 브라우저 검증 같은 건 Claude Code가 background bash로 돌릴 수 있고, subagent도 background로 운영할 수 있다.

좀 더 구체적으로는 Claude는 Claude Chrome 확장 프로그램을 사용하여 https://claude.ai/code 에 적용하는 모든 변경 사항을 테스트한 다음, 브라우저를 열고 UI를 테스트한 다음 코드가 작동하고 UX가 만족스러울 때까지 반복한다.

각 도메인마다 검증 방식이 다르고, 간단한 bash 명령어 실행부터 테스트 스위트 실행, 브라우저나 모바일 시뮬레이터에서의 앱 테스트까지 다양한 방법이 있을 수 있다. 무엇보다 중요한 것은 이러한 검증 과정을 철저하게 구축하는 것이라고 한다.

느낀점

최근에 클로드를 동시에 여러개 돌리면서, 확실히 발전이 체감이 되는거같다. 예전 같으면 몇 주 걸렸을 일들이 며칠 안에 정리되는 적도 있었다. 동시에 드는 생각은 구현 속도가 빨라진 만큼 잘못된 방향으로 가는 속도도 같이 빨라진다. 그래서 이제는 타이핑을 누가 더 빨리 하냐보다, 그 폭발적인 속도의 AI를 올바른 방향으로 가도록 결정하는 개발자의 판단이 더 중요해지는 것 같다.

참고한 자료

https://code.claude.com/docs/en/chrome

https://x.com/bcherny/status/2007179833990885678?s=12

AI Copilot Agent Mode로 SQL 쿼리 마이그레이션 (Copilot)

huncozyboy — Fri, 30 Jan 2026 22:15:12 +0900

들어가며

CUBRID 데이터베이스 환경에서 돌아가던 SQL 쿼리들을 MySQL 8.x로 마이그레이션하는 작업을 한 내용으로 포스팅을 해보려고 한다.

AI Copilot(Agent Mode)을 활용해 1000개가 넘는 쿼리 변환을 성공적으로 마칠 수 있었고, 최근 AI 기술 발전에 관심 있는 개발자분들에게 해당 경험 공유가 도움이 되었으면 좋겠다.

MySQL 8.x 로 마이그레이션을 결정한 이유

먼저 기존의 CUBRID 시스템에서 MySQL 8.x 로 옮기게된 이유부터 설명하려고 한다.

첫번째, 잦은 Lock 발생

RANGE 조건이 들어간 쿼리가 특정 시간대에 몰리면, 인덱스 범위 스캔 과정에서 잠금이 생각보다 넓게, 많이 잡히는 순간이 종종 있었다. 특히 업데이트 + 삭제처럼 쓰기 작업이 섞이면, 한 건이 느린 게 아니라 대기열이 길어지며 다른 트랜잭션까지 줄줄이 밀리는 형태로 체감 성능이 급격히 떨어졌다. MySQL(InnoDB)은 기본적으로 인덱스 레코드 단위로 잠금을 잡는 구조라 같은 범위 조건이라도 인덱스 + 쿼리 전략을 잘 짜줘서 영향 범위를 더 잘 쪼개줘서 버틸 수 있다고 알고있었지만, CUBRID 쪽은 특정 패턴에서 락이 누적되며 운영이 빡세다고 생각했었다.

두번째, 대용량 동시성 처리에서 비효율

이런 락이 많이 걸리는 순간은 데이터가 커지고 동시 요청이 늘면서 더 곤란해졌다. CUBRID는 락을 너무 많이 관리하게 되면 상위 단위로 락을 격상을 수행할 수 있는데, 이게 발생하면 개별 행 단위로 버티던 흐름이 더 거친 단위의 락으로 바뀌면서 동시 처리 효율이 확 떨어질 수 있다. 반면 MySQL(InnoDB)은 기본적으로 인덱스 레코드 기반 row-level locking을 중심으로 동시성을 유지하는 설계라 특정 트랜잭션이 과도하게 커질때에도 버티는 비용이 CUBRID 대비 많이 좋다고 판단했다.

본론

여기까지가 서론이고, 그렇다면 1000개 이상의 쿼리를 단기간에 변환하기 위한 효율적인 방법으로 Copilot을 어떻게 활용했을까 ?

마이그레이션에 Copilot 활용

핵심은 Copilot Agent Mode였다. Claude 4 기반 모델에 agent-prompt.md 를 컨텍스트로 주입해 변환 규칙을 고정하고, Agent가 쿼리를 읽어 변환 → 누락 체크 → 재수정까지 한 흐름으로 반복 처리하도록 구성해주었다.

프롬프트 작성 과정

일단 1000개라는 양의 쿼리를 한번에 바꾸기보다는, 프롬프트를 점차적으로 완성하는 방식으로 진행했다.
간단한 쿼리부터 점차적으로 변환을 시켜보고, Copilot 이 놓치거나 틀린 부분을 발견하면 특정 규칙을 agent-prompt.md 파일에 추가하는 방식으로 반복했다. (기억에 남는 내용들은 아래와 같았다.)

OUTER JOIN (+) 변환 누락
GROUP BY가 ONLY_FULL_GROUP_BY에서 터지게 변환됨
긴 WHERE 조건 일부 누락

agent-prompt.md 커스터마이징

Alias 규칙 고정
a,b,c 금지. 테이블명 그대로 alias 사용
-> 쿼리만 봐도 어떤 테이블 컬럼인지 즉시 추적 가능해서 디버깅과 리뷰 시간이 줄어듦. 조인 늘어날수록 실수도 줄고, 팀 내 스타일도 자동으로 통일할 수 있었다.
CUBRID Outer Join(+) ANSI JOIN으로 강제 변환
(+)는 WHERE에 섞여 있어 조건 누락/방향 실수가 자주 발생하다고 판단
-> LEFT/RIGHT JOIN으로 명시하면 조인 의도가 드러나고, ON/WHERE 분리가 되어 유지보수와 성능 튜닝과 인덱스 확인이 쉬워졌다.
DB 힌트 제거
MySQL에서 의미 없는 힌트는 혼란만 준다고 판단
-> CUBRID 힌트가 남아 있으면 무시되거나 오해를 유발할 수 있었다. 실행계획 분석 시 방해만 되니, MySQL 기준으로 깔끔한 쿼리만 남기는 게 안전하독 생각하였다.
ONLY_FULL_GROUP_BY 대응은 원칙적으로 하도록
ANY_VALUE() 금지(정합성 보장 불가). ROW_NUMBER() + rn=1 패턴 사용
-> ANY_VALUE는 같은 그룹에서도 어떤 행이 선택될지 보장되지 않아 장애/데이터 불일치로 이어질 수 있기때문에, ROW_NUMBER로 대표 행 선택 기준을 고정하여 결과가 항상 동일해져 테스트가 용이해졌다.
예약어 컬럼 처리
user, level 같은 애들 안전하게 백틱 처리
-> 환경과 버전에 따라 예약어 해석이 달라지면 배포 후 갑자기 쿼리가 깨질 수 있다고 판단하였다. 초기부터 백틱으로 고정해두어 신규 컬럼 추가 시에도 병목이 없도록 설정해주었다.
재귀 쿼리 변환: CONNECT BY → WITH RECURSIVE
DISTINCT 금지 제약 인지 , 임의 depth 제한 X
-> MySQL 재귀 CTE는 제약이 있어서 임의 depth 제한은 데이터 누락을 만들기 쉬울 수 있다. 따라서 중복 제거가 필요하면 재귀 밖에서 처리해 원본 계층 구조를 그대로 살려주었다.

agent-prompt.md

CUBRID -> MySQL 8 쿼리 변환 일부

GROUP BY 변환 Before: CUBRID

GROUP BY 변환 After: MySQL 8

Outer Join(+) 변환 Before: CUBRID

Outer Join(+) 변환 Before: MySQL 8

재귀 변환 Before: CUBRID

재귀 변환 After: MySQL 8

이렇게 변환 쿼리들은 무조건 실제 DB에서 실행 하여서 오류 발생을 예방하였다. 또한 긴 쿼리 분할은 AI가 한번에 처리하도록 하기보다는, 여러 개의 작은 단위로 나누어 변환을 요청했을 때 더 안정적이고 정확한 결과를 얻을 수 있었다.

마치며

최근에 AI가 빠른 속도로 발전하면서, AI를 활용한 문서화나 자동화에 관심이 많이 생기게 되었다. 그중에서도 Claude 4는 이런 부분에서 선두에 있다고 개인적으로 생각한다. 물론 agent-prompt.md 를 반복적으로 커스텀한 이유처럼, AI한테 맡기되 맹신하기 보다는 결정적인 책임은 사람이 무조건 해야한다고 생각하고 있다.

아무리 agent-prompt.md 를 명확하게 작성하여 지시한다고 하여도, 결과물에 대한 꼼꼼한 검증이 필수적이라고 생각하였다. 이번 글에서는 방대한 양의 쿼리를 처리해야했기에 더더욱

참고한 자료

# MySQL: ONLY_FULL_GROUP_BY / GROUP BY 처리
https://dev.mysql.com/doc/refman/8.3/en/group-by-handling.html
https://dev.mysql.com/doc/en/sql-mode.html

# MySQL: Window Function (ROW_NUMBER 등)
https://dev.mysql.com/doc/refman/8.0/en/window-functions-usage.html

# MySQL: WITH / WITH RECURSIVE (CTE)
https://dev.mysql.com/doc/refman/en/with.html

스웨거 typescript-api로 자동화 하는법 (Swagger)

huncozyboy — Thu, 20 Nov 2025 07:12:34 +0900

들어가며

Swagger 공식문서 이미지

Sopt에서 Lococo를 개발하면서 스웨거가 단순히 문서화 툴일 뿐만 아니라, 클라쪽에서 자동화로 뽑아서 코드를 작성해줄 수 있는 툴이 있음을 알게되었었다. 그래서 NestJS의 공식 문서를 보다가, 흥미로운 내용이 있어서 포스팅을 작성하게 되었다. @nestjs/swagger, FastAPI, Springdoc-openapi 같은 것들이 대표적인데, 이런 프레임워크들은 컨트롤러/라우트 정의를 읽어서 OpenAPI 문서를 뽑아주기까지 할 수 있다.

https://docs.nestjs.com/openapi/introduction

Documentation | NestJS - A progressive Node.js framework

Nest is a framework for building efficient, scalable Node.js server-side applications. It uses progressive JavaScript, is built with TypeScript and combines elements of OOP (Object Oriented Programming), FP (Functional Programming), and FRP (Functional Rea

docs.nestjs.com

본문

먼저 위처럼 타입 정의를 뽑아서 쓸 수 있다.
--no-client: API 클래스는 생성하지 않겠다는 의미이다

--union-enums: enum을 실제 TypeScript 유니온("A" | "B")으로 생성

이렇게 만들어진 marketplace.d.ts는 프로젝트 어디에서나 타입으로만 소비할 수 있다.

즉, 이 방식은 “타입 동기화” 측면에서만 도움을 줄 수 있고, 결국 API 호출부는 매번 손으로 짜야 하는 방식이다

swagger-typescript-api 활용하기

swagger-typescript-api가 제공하는 두 가지 커스터마이징 포인트를 이용하면, 위 문제를 꽤 깔끔하게 풀 수 있다.

템플릿(ejs) 커스터마이징
훅(hooks) 기반 플러그인 스타일 커스터마이징

1단계 – 기본 템플릿 뽑아서 레포에 복사

https://fig.io/manual/swagger-typescript-api/generate-templates

먼저, 공식 CLI가 제공하는 generate-templates 서브커맨드로 현재 버전의 기본 템플릿을 로컬에 복사한다

이렇게 하면 ./tools/swagger-templates 아래에 대략 이런 파일들이 생성된다.

http-client.ejs
data-contracts.ejs
api.ejs
(기타 헬퍼 템플릿들)

2단계 – http-client 템플릿에서 axios 인스턴스 주입 구조로 변경

http-client.ejs를 열어서 대략 아래와 비슷한 형태의 코드를 확인한다.

서론에서 얘기했듯이, “이미 만들어 둔 axios 인스턴스를 주입해서 쓰는 형태”로 활용하기 위해서 템플릿을 살짝 바꿔준다

3단계 – API 템플릿에서 메서드 이름과 반환 타입 컨벤션 정리

다음으로 api.ejs 쪽에서 메서드 이름과 반환 타입을 팀 컨벤션에 맞게 정리한다.

예를 들어, 기본 템플릿은 GET /v1/tickets 같은 엔드포인트를 getTickets 대신 ticketsControllerControllerListTickets 같은 장문의 이름으로 만들 수도 있다.

태그(tag) + HTTP 메서드 + 경로 일부 조합으로 깔끔하게 축약
operationId를 우선적으로 사용해서 백엔드에서 이름을 명시적으로 관리

4단계 – hooks 로 스키마/타입 수정하여 플러그인처럼 사용

위 소스코드처럼, onParseSchema, onCreateRouteName 등 다양한 훅을 조합하면 enum, 날짜 타입, 파일 업로드 타입 등을 우리 코드베이스에서 쓰는 타입으로 일괄 매핑 가능하다. 사실상 “젠 체인 앞단에서 동작하는 플러그인”처럼 사용이 가능해진다

마치며

이제 전체 플로우를 정리하며 글을 마무리 해보려고 한다.

서버에서 OpenAPI 스펙 자동 생성
- NestJS, Spring, FastAPI 등에서 /v3/api-docs, /openapi.json 등으로 노출
CI에서 swagger-typescript-api 실행
- 템플릿 + hooks를 이용해 타입 + axios 클라이언트 코드 생성
프론트/공유 라이브러리가 그 코드를 그대로 import
- 레포 간에는 git submodule, 패키지 배포 등으로 공유

결론적으로 스웨거 스펙을 최신 상태로 유지해주면, 타입 + axios 기반 클라이언트 코드가 함께 갱신되고 프론트/다른 서비스에서는 MarketplaceClient만 가져다 쓰면 되는 자동화 구조를 만들 수 있다.

참고 & 공식문서 링크

OpenAPI 공식 스펙 (3.1 기준)
https://swagger.io/specification/
OpenAPI 3.0 Paths & Operations 설명
https://swagger.io/docs/specification/v3_0/paths-and-operations/
swagger-typescript-api GitHub 리포지토리
https://github.com/acacode/swagger-typescript-api

Spring Boot 4.0 RC1 릴리즈 (Spring)

huncozyboy — Wed, 29 Oct 2025 18:57:20 +0900

서론

링크드인을 살펴보다가 2025년 10월 24일에 Spring Boot 버전이 메이저로 올라간 사실을 알게됐다. 정확히는 Spring Boot 4.0.0‑RC1이 릴리즈 되었다는 소식이었고, LTS(장기지원) 버전은 아니지만 메이저 버전 변경이라는 점에서 관심을 가지고 찾아보게 되었다. 이번 포스팅은 버전 4.0에서 주목할 만한 몇 가지 변경사항을 추려보고 앞으로 프로젝트 진행 시 참고할 만한 기능이 있는지, 그리고 Spring Boot가 어떤 방향으로 나아갈거같은지, 공유하고자 작성하게 되었다. ~~(물론 RC 버전이라 확정이 아님을 감안해주면 좋을거같다~~

Spring Boot 4.0.0‑RC1

본론

2025년 10월 23일(미국 기준)에 Spring 공식 블로그에는 “Spring Boot 4.0.0‑RC1 available now”라는 글이 올라왔고, 해당 버전이 Maven Central에 등록되었다는 안내가 있었다.

https://spring.io/blog/2025/10/23/spring-boot-4-0-0-RC1-available-now?utm_source=chatgpt.com

Spring Boot 4.0.0-RC1 available now

spring.io

이 릴리즈에는 176건의 기능 향상, 문서 개선, 의존성 업그레이드, 버그 수정 등이 포함되어 있다고 밝히면서, “현재까지의 관행을 바꾸겠다”, 혹은 “새로운 표준을 정하겠다” 정도의 의지가 담겨 있다고 많은 사람들이 해석하고 있다.

주요 변경 사항

이제 구체적인 예시 코드들을 보면서 함께, 4.0 버전부터 바뀌는 주요 업데이트 내용을 알아보자

RestClientTest 추가

import org.springframework.boot.test.autoconfigure.web.client.RestTestClient;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.beans.factory.annotation.Autowired;
import org.junit.jupiter.api.Test;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class UserControllerTest {

    @Autowired
    private RestTestClient restTestClient;

    @Test
    void getUser_returnsUser() {
        restTestClient.get()
            .uri("/api/users")
            .exchange()
            .expectStatus().isOk()
            .expectBody()
            .jsonPath("$.id").isEqualTo(1)
            .jsonPath("$.name").isEqualTo("jihun");
    }
}

먼저 기존 버전(3.x 등)에서는 WebTestClient(주로 WebFlux 환경)나 RestTemplate 등을 이용해 컨트롤러/서비스 테스트를 작성하곤 했고, 또 MockMvc 등 MVC 환경용 테스트 도구가 존재했었다.

이번 4.0 RC1에서는 RestTestClient 라는 테스트 도구가 새롭게 소개되어, MVC와 WebFlux 양쪽 프레임워크 모두에서 통합 테스트를 보다 수월하게 진행할 수 있게 되었다.

해당 업데이트가 시사하는 바로는, 이제 프레임워크 종류에 따라 테스트 도구를 나누지 않아도 되며, 하나의 테스트 클라이언트 API로 통합 가능하다는 점이 흥미로웠다. “컨트롤러와 서비스 사이 통신 흐름을 통합적으로 검증하고 싶을 때”, 아니면 “MVC → WebFlux 마이그레이션 중인 프로젝트”같은 경우에 특히 유용할 수 있겠다는 개인적인 생각도 들었다.

신규 어노테이션 @ObservationKeyValue

@Service
public class OrderCreateService {

    @ObservationKeyValue(key = "order.created", value = "true")
    public Order createOrder(Customer customer, Item item) {
        Order order = new Order(customer, item);
        return order;
    }
}

해당 내용은 본론을 시작하며 위에서 첨부했던 스프링 공식문서에도 담겨있었던 내용으로, 관측성(Observability) 에 대한 변화에 집중하겠다는걸 보여준 예시이기도 한거같다. @ObservationKeyValue 어노테이션을 통해 메트릭에 대한 키‑값을 보다 직관적으로 정의할 수 있게 되었다.

물론 리서치 해본 결과, key와 value가 반대로 들어간다든지, 내부 fallback 처리로 메서드 반환값이 value에 들어간다든지 하는 현상이 있다는 버그가 있다는 점은 참고하고, 정식 버전이 아니라는 점도 감안해주어야 할거같다.

여기서 개인적으로 재밌었던 점은, Spring Boot 3.x 버전에서도 메서드 파라미터를 기반으로 메트릭에 동적 태그를 추가하는 기능으로, @Timed나 @Counted 어노테이션과 함께 메서드 파라미터에 @MeterTag를 사용하여 동적으로 태그를 추가하는게 이미 존재했었다는 점이다.

그럼에도 @ObservationKeyValue 어노테이션이 나온 이유는, @Observed 어노테이션과 함께 사용할 수 있어, 메트릭과 트레이싱 모두에 동적 태그를 일관되게 추가할 수 있기때문이 아닐까라는 개인적인 생각인 생각이 들었다. 마찬가지로 "관측성" 측면에 집중한 업데이트 같았다.

// Spring Boot 3.x의 복잡한 방식
@Observed(name = "order.created")
public Order createOrder(String orderId) {
    Observation observation = registry.getCurrentObservation();
    if (observation != null) {
        observation.highCardinalityKeyValue("orderId", orderId);
    }
}

그리고 첫번째 첨부한 예시 코드랑 비교했을때, 두번째 첨부한 바로 위의 코드가 가독성도 조금 떨어진다고 생각하기에, 개인적으로 좋다고 생각하는 업데이트이다.

관측성 측면에서는 또 Micrometer나 Micrometer Tracing 등과의 연계, 분산 추적(Distributed Tracing) 기본 내장 등이 강화된 것으로 보이는데, 릴리즈 노트에서는 “Redis 관측성 개선(Redis observability improvements)” 등의 항목이 나와있어서 추후에 발표되는 내용들을 주의깊게 봐봐야할거같다.

직렬화/역직렬화 및 라이브러리 변화: Jackson 3 검토

추가로 Jackson 버전 3 도입 검토가 진행 중이라고 한다. 현재 Spring Boot는 Jackson 2.x 계열을 사용하고 있고, 이를 Jackson 3로 업그레이드하는 작업이 내부적으로 검토되고 있다고 한다. “Record 타입 직렬화/역직렬화”을 기대하셨는데, 실제로 Preview 분석 글에서도 Java Record 지원 강화가 언급되어 있다.

또한 4.0.0‑M1 릴리즈 노트에서는 의존성 업그레이드 항목으로 Jackson 3 미리보기 버전 가능성이 언급되어 있어서, 해당 부분도 참고해주면 좋을거같다

개인적으로도 불변 객체(Immutable Object), Record 타입을 많이 쓰시는 경험이 있었어서 이 변화가 반갑기도 했었다. 앞으로 클래스 + Lombok 방식 대신 Record 방식 + 제대로 된 직렬화/역직렬화 지원이 가능해지면 구조 설계 측면에서도 선택지가 넓어질 것 같다는 생각도 들었었다.

마치며

개인적으로 굳이 불변성을 지닌 객체에 대해서는 Lombok을 적용하는 것을 선호하지는 않았어서, 최대한 Lombok 적용을 고민해 보는편이였다. 그래서 Java Record의 개념은 앞서 얘기했듯이 내가 좋아하고 애용도 많이하지만, ObjectMapper가 직렬화/역직렬화를 제대로 지원하지 않아 Class로 변경하고 Lombok을 사용했던 경험도 있었다.

마찬가지로 RestTestClient도 RestClient는 도입해봤던 경험이 많지만, 결국 테스트는 WebTestClient나 RestTemplate을 사용하여 진행하였는데 이를 통합한 테스트 객체가 생겨서 너무 좋다고도 생각했다.

또한, 글에는 설명하지 않았지만 Virtual Threads 동시성 처리 개선,AOT 컴파일 최적화로 시작 속도 향상, 분산 추적 기본 내장와 같은 보완된 내용들이 있으니 참고하면 좋을 것 같다.

Conflict를 깃허브 웹에서 해결시 주의사항 (Github)

huncozyboy — Wed, 29 Oct 2025 17:55:15 +0900

들어가며

요즘 현업에서나 개인, 팀 플젝에서 GitHub를 활용해서 활발하게 PR(Pull Request) 기반 협업을 진행하고있다. 해당 과정에서 작업 브랜치와 동일한 브랜치에서 다른 작업들이 병합이 되면서 충돌(Merge Conflict)이 발생하는 경우가 있다.

물론 IntelliJ IDEA나 vs code를 활용하여 개발 환경 도구를 사용할 수도 있지만, 이러한 충돌을 웹 UI 상에서 간편하게 해결할 수 있다는 점이 GitHub의 장점이라고 필자도 생각하고 있다.

하지만 이번 포스팅은 해당 GitHub 웹에서 Conflict를 해결할때의 주의사항에 대해서 다루어보려고 한다.

이번 글에서는 웹 UI를 통한 충돌 해결 방식이 어떻게 동작하는지, 어떤 주의사항이 있는지, 그리고 충돌 해결 시 권장되는 방식에 대해서 다루어보려고 한다.

Github 웹에서 컨플릭트 해결하는 방법

먼저 컨플릭트에 대해 가벼운 설명이나, 컨플릭트를 최소화 하고싶은 방법이 궁금하다면, 아래 포스팅의 개발 전 고려사항 부분을 봐주어도 좋을거같다. 가치택시 프로젝트를 개발하며 컨플릭트와 관련해서 팀원들과 고민했던 과정이 담겨있다.

https://huncozyboy.tistory.com/7#%EA%B0%9C%EB%B0%9C%20%EC%A0%84%20%EA%B3%A0%EB%A0%A4%EC%82%AC%ED%95%AD-1-4

가치택시(매칭 알고리즘, Spring)

서론방학이 시작되고 Leets 4기에서 프로젝트를 시작하게 되었고, 내가 참여하여 시작한 프로젝트의 주제는 " 교내 학생들의 택시 이용시, 요금과 시간의 부담을 줄여줄 수 있는 택시 매칭 서비

huncozyboy.tistory.com

다시 돌아와서, 구체적인 컨플릭트 과정부터 살펴보자

공식 GitHub Webhook 설명서
" 동일한 브랜치를 기준으로 다른 브랜치에서 PR을 올렸을 때 같은 파일의 동일한 줄(line) 을 두 브랜치가 수정한 경우에 한해 웹 UI에서 충돌을 해결할 수 있는 옵션이 나옵니다"

https://docs.github.com/articles/about-merge-conflicts?utm_source=chatgpt.com

병합 충돌 정보 - GitHub Docs

병합 충돌은 경합 커밋이 있는 분기를 병합할 때 발생하며 Git가 최종 병합에 통합할 변경 내용을 결정하는 데 사용자의 도움이 필요합니다.

docs.github.com

위 공식문서 내용들을 보면 알 수 있듯이, 서론에서도 설명했듯이 간단하게 컨플릭트를 해결할 수 있다. 좀 더 구체적으론 아래처럼 할 수 있을거같다.

README.md 라는 간단한 컨플릭트 예시 (아마 예시와 달리 여러개의 파일이 동시에 컨플릭트가 일어나는 현상이 대부분일거다)

PR 페이지에서 “This pull request has conflicts that must be resolved” 등의 안내가 뜹니다.
“Resolve conflicts” 버튼을 클릭하면 충돌이 난 파일별로 편집 화면이 나옵니다.
< < < < < HEAD, =======, >>>>>>> branch-name 등의 충돌 마커(conflict markers)가 보이고, 원하는 코드만 남기고 마커를 삭제합니다.
모든 파일 충돌을 해결하고 나면 “Mark as resolved” → “Commit merge” 등의 버튼이 활성화됩니다.

가장 많이 사용하는 깃허브 전략

이런 귀찮거나 실수가 나올 수도 있는 컨플릭트 상황을 조금이라도 줄이거나, 충돌이 발생했을 때 효율적으로 대응하기 위해서는 브랜치 전략이 굉장히 중요하다고 생각하는데, 필자가 가장 많이 사용하는 깃허브 전략은 github flow이다.

GitHub Flow 전략에 대한 간단한 설명

간단하게 설명했을때, 아래 플로우로 진행이 된다

기능 별로 브랜치 생성 feat #1 회원가입 기능 구현
브랜치로 이동 git checkout -b
작업 (새로 생성한 브랜치에서) git add, git commit, git push,
Pull Request (PR) 생성 간단하게 서로 리뷰
메인에다가 머지 리뷰가 끝나면 머지
다시 Main 브랜치로 이동 git pull origin main
또 새로운 작업 들어가면 1번 반복

GitHub Flow는 비교적 간단하고 직관적인 구조를 가지고 있어서 협업이나 리뷰가 자주 이뤄지는 사이드 프로젝트에서 특히 유용하다고 느꼈다 (개인적인 생각)

본론

서론이 좀 길었는데, 그러면 이 포스팅의 제목인 깃허브 웹 UI를 활용해서 컨플릭트를 해결할시, 어떤 점을 주의해야할까 ?

base 브랜치 전체가 병합될 수 있다.

GitHub 웹 UI에서 Merge Conflict를 해결하면, 단순히 충돌된 파일만 병합되는 것이 아니라 PR의 base 브랜치 전체가 head(compare) 브랜치에 병합된다.

main과 feature/login 브랜치의 컨플릭트 예시

예를 들어, main 브랜치를 기준으로 feature/login 브랜치에서 PR을 만들었고 충돌이 생긴 경우, 웹에서 충돌을 해결하면 main 전체가 feature/login에 병합되는 것이다.

이는 우리가 웹 UI를 사용하지 않고 직접 충돌을 해결할 때를 생각하면 이해가 쉬운데, 기본적으로 웹 UI에서는 head(compare) 브랜치가 base 브랜치의 최신 변경사항을 반영한 뒤 병합되는 방식으로, UI상에서는 “버튼 클릭”으로 간편해 보이기 때문에 이 과정이 눈에 잘 띄지 않을 수 있다고 생각한다.

보통은 흔하게 아래 두가지 두가지 방법을 사용한다.

1. PR을 올린 반대 방향으로 merge하는 케이스
base 브랜치의 변경 사항이 head 브랜치에 반영됩니다. 웹 UI의 동작과 동일합니다.

2. 작업 브랜치를 rebase하는 케이스
마찬가지로 base 브랜치의 변경 사항이 head 브랜치에 반영됩니다.

이 때는 우리가 직접 merge나 rebase를 하면서 base 브랜치의 최신 내용을 반영한다는 사실을 자연스레 인지하는데, 웹 UI에서는 버튼 몇 번으로 간단하게 해결할 수 있다보니 이를 쉽게 간과할 수 있는 것 같다고 개인적으로 생각했다. 그리고 결론적으론 다음과 같은 상황에서는 더 주의해주어야한다.

base 브랜치의 최신 내용을 반영할 시에 주의사항

먼저 필자는 아래 3가지 case를 생각해보았다.

head 브랜치가 배포 대상인 브랜치일 때
충돌 해결 후 커밋 내용이 그대로 유지되어야 하는 경우
외부 브랜치나 포크 저장소에서 작업 중일 때

위 3가지의 케이스에서는 단순하게 GitHub 웹 UI에서 Merge Conflict 해결 방식을 사용할때 주의해야된다고 생각했다.

1번 case, 배포 브랜치에 직접적인 변경 이력이 남게 되는 위험이 존재한다.
웹 UI에서 병합을 진행하면 Merge commit이 자동 생성되는데, 이는 CI/CD 파이프라인이 트리거되어 의도치 않게 배포가 재실행될 수도 있다. 또한 병합 과정에서 테스트나 빌드 검증이 충분히 이루어지지 않은 상태로 main이나 release 브랜치에 반영될 수 있다는 점에서도 주의가 필요하다.

3번 case, 포크 저장소나 외부 협업 브랜치에서 권한 문제가 발생할 수 있다.
GitHub 웹 UI에서 병합을 시도하면, 저장소 권한이 제한된 경우 자동 병합이 불가능하거나, 원격 브랜치에 대한 push 권한 부족으로 인해 로컬 변경 사항이 반영되지 않는 문제가 생길 수 있다.

2번 case, 웹 UI 방식에서는 자동으로 병합 커밋이 생성되거나, 커밋 메시지가 시스템 기본값으로 작성되는 경우가 많다.
즉, 히스토리를 깨끗하게 관리해야 하는 프로젝트(예: git log를 통해 변경 흐름을 명확히 추적하거나, git bisect로 디버깅 가능한 상태를 유지해야 하는 경우)라면 웹 UI 방식을 사용하기보다는 로컬에서 명시적으로 커밋 메시지를 작성하고, 필요에 따라 squash 또는 rebase를 통해 이력을 정돈하는 방식을 추천한다.

권장하는 충돌 해결 방식 및 브랜치 전략

GitHub 웹에서 충돌을 해결하기 전, 다음과 같은 점들을 고려하는 것을 권장합니다:

1. 중요한 브랜치는 보호된 브랜치로 설정하기

Github 자체에서도 많은 기능을 제공해주기에, 직접 들어가서 보는걸 추천한다

main, release/* 등 주요 브랜치에 대해 보호 규칙(Protected Branches)을 걸어두는 것이 좋다.

직접 push 금지
force‑push 금지
리뷰 승인 필수 등
이렇게 하면 실수로 중요한 브랜치를 덮어쓰거나 병합하는 위험을 줄일 수 있음

2. “이 브랜치에 base 브랜치를 통째로 병합해도 괜찮은가?” 사전 검토

head 브랜치에 base 브랜치 전체를 반영해도 문제가 없는가?
→ 만약 head 브랜치가 배포 대상 브랜치이거나, 커밋 히스토리를 깔끔히 유지해야 하는 경우라면 앞서 짧게 설명했듯이 별도로 브랜치를 파서 충돌을 해결하는 편이 안전.

main-merge 라는 별도의 브랜치를 생성해서 안전하게 머지

커밋 히스토리가 깔끔하게 유지되어야 하는가?
→ 그렇다면 로컬에서 rebase 혹은 merge --no‑ff 방식으로 해결하는 것이 바람직함.

마치며

간단히 정리하자면, GitHub 웹 UI를 통한 충돌 해결 기능은 편리하지만, 그 내부에서 어떤 동작이 일어나는지, 그리고 너무 쉽게 누르다 보면 의도하지 않은 병합이 발생할 수 있다는 점을 반드시 인지하고 사용하면 더 좋을거같다는 생각에 포스팅을 작성하게 되었다.

참고한 링크

Resolving a merge conflict on GitHub – GitHub Docs: https://docs.github.com/articles/about-merge-conflicts
Resolving a merge conflict using the command line – GitHub Docs: https://docs.github.com/articles/resolving-a-merge-conflict-using-the-command-line
How GitHub merge conflict: How to handle the most common merge conflicts – CloudBees Blog

Instagram Basic Display API vs Graph API 무슨 차이가 있을까 (OAuth)

huncozyboy — Mon, 22 Sep 2025 06:27:47 +0900

들어가며

instagram, tiktok 계정연동 기능

글로벌 크리에이터, 브랜드를 연결해주는 서비스 Lococo를 개발하면서, 크리에이터는 브랜드가 올린 "캠페인"이라는 것에 신청하고, 해당 제품에 대한 후기를 SNS에 업로드하는 로직이 있었다. 때문에 업로드한 SNS에 대한 정보를 가져오기 위해서는 SNS 연동이 필수적이였는데, 해당 포스팅은 Instagram 연동을 하면서 고민했었던 내용을 작성해보려한다

본문

meta에 있는 공식문서

인스타그램 연동을 위해 공식 문서를 봐도 공식문서를 보면, Facebook 로그인을 통한 Instagram API랑 Instagram 로그인을 통한 Instagram API가 별도로 존재하는걸 알 수 있었다. 이 글에서는 내가 겪었던 혼란 포인트들을 공유하면서, 상황에 따라서 어떤 플로우를 선택해야 하는지와 OAuth 차이를 정리해보려고한다

로그인 화면의 차이

메타(페이스북)가 현재 유지하는 인스타그램 Oauth는 크게 두가지이다

1. Instagram API with Instagram Login

실제 Insta Oauth 경로로 접속시 화면

먼저 인스타그램으로 로그인은, 우리가 평소에 알던 인스타그램 화면이 뜨며 선택적으로 Facebook으로 로그인할 수 있는 플로우라고 이해해주면 된다. 만약 로그인한 인스타 계정이 프로페셔널(비즈니스/크리에이터) 계정이 아니라면, 계정 전환을 해달라는 별도의 페이지가 나온다

2. Instagram API with Facebook Login

실제 Facebook Oauth 경로로 접속시 화면

그리고 마찬가지로 Facebook Oauth는 역시나 우리가 알던 Facebook으로 로그인할 수 있는 플로우다. 하지만, 위 화면에서도 알 수 있듯이 Insta로 로그인할 수 없다고 생각해주면 될거같다

기본세팅 (Meta 콘솔 설정의 차이)

앞서 서두에 짧게 얘기했듯이, 페이스북과 인스타그램은 모두 메타가 제공해주는 Oauth이다. 때문에 다른 Oauth와 마찬가지로 기능을 구현하기 위해서 Meta Developers에서 별도의 콘솔 설정을 해준뒤, clientID, redirectURI 등등을 세팅해줘야한다고 생각해주면 된다

Meta for Developers 사이트

1. Instagram API with Instagram Login

먼저 인스타 로그인 콘솔 세팅이다

내앱 - 대시보드 - 제품추가

앞서 설명했듯이 clientID, redirectURI 등등의 세팅을 위해서 제품 추가를 해주어야하는데, 해당 Instagram이라고 되어있는 제품을 추가해준 뒤에

Instagram - Instagram 비즈니스 로그인이 포함된 API 설정

Instagram 비즈니스 로그인이 포함된 API 설정에서 기본 세팅을 진행하면 된다

2. Instagram API with Facebook Login

그리고 다른 Oauth인 Facebook login 콘솔 세팅이다

내앱 - 대시보드 - 제품추가

바로 이전에 나온 Instagram 콘솔과 똑같은 경로에서, 비즈니스용 Facebook 로그인이라고 되어있는 제품을 추가한 뒤에

비즈니스용 Facebook 로그인 - 설정

비즈니스용 Facebook 로그인 - 설정으로 들어가서 위 캡쳐화면에 나온 내용들을 설정할 수 있다 (Facebook 로그인의 clientID는 제품 추가시 별도로 설정되는 것이 아닌, 제일 상단에 있는 Meta 앱 ID와 동일하다)

얻을 수 있는 정보의 차이

해당 내용은 그렇다면 왜 나누어져 있는걸까 ? 먼저 Oauth API가 제공하는 정보의 차이가 존재한다

1) Instagram Basic Display API (개인 계정 전용·현재 중단)

엔드포인트: https://graph.instagram.com
제공 데이터:
- id, username
- media (사진/영상 URL, caption, timestamp 등)
제공하지 않음: like_count, comments_count, 노출/도달/저장/조회수 같은 인사이트

2) Instagram Graph API (Business/Creator 전용)

엔드포인트: https://graph.facebook.com
제공 데이터/기능:
- 인사이트(impressions, reach, engagement, saved, plays 등)
- 게시물·릴스·스토리 통계

결론적으로 우리 Lococo에서 필요한 Oauth API는 2번이였고, 해당 내용을 사용하기 위해선 사업자 등록이 필요했다

사업자 등록 플로우

앞서 설명한 " 사업자 " 라는 개념은, 우리 서비스에서 필요했던 정보인 게시글, 릴스 등의 인사이트(통계) 를 얻기위한 정보들이였는데,
비즈니스 검증(Business Verification)과 앱 검수(App Review)를 통과해야 실제 사용자에게 Advanced Access로 관련한 권한들을 제공받을 수가 있다

아래는 관련한 공식문서의 내용이다

https://developers.facebook.com/docs/instagram-platform/app-review

App Review - Instagram 플랫폼 - 문서 - Meta for Developers

If you request permissions or features that your app does not use or does not align with the allowed usage for that permission or feature, your submission will not be approved.

developers.facebook.com

마치며

마치면서, 실제 구현하면서 참고했었던 내용들의 링크를 첨부할테니 구현할때 참고 해주면 더 좋을거같다

실제 테스트했었던 API들....

참고 & 공식문서 링크

Basic Display API 종료 공지(Meta 블로그)
https://developers.facebook.com/blog/post/2024/09/04/update-on-instagram-basic-display-api

Instagram API with Instagram Login (동일 Graph 기반, 로그인 프로바이더만 변경)

https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login

Instagram API with Facebook Login (Get Started, 권한 흐름)

https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login

배포 후 구매한 도메인 연결하기 (Route 53)

huncozyboy — Fri, 19 Sep 2025 04:29:01 +0900

들어가며

EC2로 서버를 배포한 뒤에는 https://***.nip.io/ 라는 무료 도메인인 nip.io를 붙여주면 정상적으로 스웨거가 접속이 되며 테스트가 가능할 순 있다. 하지만 실제 유저를 받기 위해서 고유한 도메인을 구매한 뒤에 라우팅을 시켜줘야하는데, 이번 포스팅은 Route 53을 활용해서 가비아에서 구매한 도메인을 EC2 서버와 호스팅하는 플로우를 다루려고한다

실제 배포되어 운영중인 동아리 관리 서비스 Weeth 도메인 주소

Route 53이란 ?

AWS에서 지원하는 DNS(Domain Name System) 이라는 뜻을 가진다
쉽게 설명하면 도메인을 발급하고 관리해주는 서비스를 의미한다

여기서 DNS는 특정 컴퓨터가 가지는 고유한 IP 주소를 문자로 변환해주는 시스템을 의미하며, 결론적으로 프론트든 백엔드 서버든, 웹에서는 HTTPS를 적용한 도메인을 기반으로 통신하기에 DNS가 필요한 것이다

본문

1. 가비아 접속 및 원하는 도메인 구매

먼저 가비아에 접속해서 원하는 도메인을 검색해서 구매를 해준다

(대부분 학생 신분일거라고 생각하기때문에 도메인 기간은 1년으로 하는 것을 추천한다.... 서비스 동향 보고 변경을 하던, 투자해서 계속 갖고있던)

2. AWS Route 53 호스팅 영역 생성

도메인을 Route 53에 호스팅 시켜주기 위해서, AWS의 Route 53에 접속한 뒤에 호스팅 영역을 생성해준다

Route 53 - 시작하기 - 호스팅 영역 생성

구매한 도메인에 맞게 호스팅 생성

Route 53 콘솔 → “호스팅 영역 생성” → 도메인명 입력 (프로토콜(https://)이나 경로(/api) 같은 건 쓰지 않고, 순수하게 “example.com” 형태만 입력)

기본으로 생성된 SOA, NS 레코드는 일단 그대로 둔다

3. 레코드 확인 및 등록

그 다음 앞서 호스팅 영역에서 기본으로 생성된 레코드 확인한다

다시 Gabia에 접속한 뒤에, NS(Name Server)의 값/트래픽 라우팅 대상을 Gabia에 네임서버에 등록해준다

홈 - 도메인 정보 변경 - 네임 서버 - 설정

입력된 값들

이때, 1차 ~ 4차에 NS에 해당하는 값/트래픽 라우팅 대상의 4개의 값 넣어주는데 뒤에 . 은 제외하고 입력한다고 생각해주면 된다

4. EC2 주소에 맞게 유형 A 레코드 생성

AWS 접속 -> Route 53 → 좌측 “호스팅 영역” → 등록한 주소를 ( example.com ) 클릭

그 다음에는 AWS 콘솔에 다시 접속해서 레코드를 생성해주어야 한다
레코드 이름: (빈칸)

레코드 유형: A – IPv4 주소

값: 00.00.000.000 (EC2 IP값)

TTL(초): 기본 300 (권장: 300~600)

5. CNAME 레코드 만들기 (www 서브도메인 → Vercel)

마지막으로 동일한 호스팅 영역(example.com)에서 다시 “레코드 생성” 클릭 후 CNAME 레코드를 생성해주면 된다

레코드 이름: (빈칸) 혹은 @
레코드 유형: CNAME
값: (vercel 주소)
TTL(초): 기본 300

userId를 매번 입력받지않고도 로그인한 유저 정보를 가져올 수 있을까 ? (JWT)

huncozyboy — Fri, 19 Sep 2025 03:43:01 +0900

들어가며

스프링 시큐리티는 SecurityContext에 인증 객체(Authentication)를 저장한다

public String getCurrentUser() {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        
        // Principal 객체 (UserDetails 구현체) 가져오기
        Object principal = authentication.getPrincipal();

        if (principal instanceof UserDetails userDetails) {
            return "현재 로그인한 사용자: " + userDetails.getUsername();
        } else {
            return "현재 로그인한 사용자: " + principal.toString();
        }
    }

그래서 컨트롤러에서 SecurityContextHolder.getContext().getAuthentication() → getPrincipal()을 타고 들어가면 로그인한 사용자의 정보를 꺼낼 수 있지만, 이렇게 매번 SecurityContextHolder를 직접 꺼내 쓰면 컨트롤러 코드가 지저분해지고, 꺼낼 수 있는 정보도 상황에 따라 한정적이게된다

Authentication authentication =
SecurityContextHolder.getContext().getAuthentication();
CustomUser custom = (CustomUser) authentication == null ? null : authentication.getPrincipal();

Spring Security 3.2부터는 @AuthenticationPrincipal 어노테이션을 활용해 줄 수 있는데, 이 어노테이션은 현재 인증 객체의 principal을 메서드 파라미터로 “주입” 해준다

상세 내용

이번 포스팅은 앞서 설명한 AuthenticationPrincipal의 개념을 활용한 CurrentUser에 대한 내용을 다뤄보려고 한다

@CurrentUser 추상화

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/youtube")
public class YoutubeController {
    private final YoutubeCrawlerService youtubeCrawlerService;

    @Hidden
    @PostMapping("/{productId}/crawl")
    public ApiResponse<CrawlResponse> crawl(@PathVariable Long userId) {
        List<String> videoUrls = youtubeCrawlerService.crawlAndStoreReviews(userId);

        return ApiResponse.success(HttpStatus.OK, ResponseMessage.CRAWL_SUCCESS.getMessage(),
                CrawlResponse.of(videoUrls));
    }
}

먼저 흔히 사용할 수있는 컨트롤러의 예시이다.

로그인한 사용자와, 로그인하지 않은 사용자를 구분하기 위해 JWT 토큰을 헤더에 받고, 비즈니스 로직에서 유저와 관련한 정보를 필요로 하기때문에 userId를 헤더나 바디에 받는 방식이라고 이해해주면 된다

하지만 CurrentUser를 추상화해서 로직을 구현하면, 아래처럼 헤더에 토큰만 넣어준다면, 클라쪽에서 별도로 userId를 보내줄 필요가 없게된다

Authorization: Bearer eyJ...

즉, 토큰만 헤더에 실어서 보내면 서버가 자동으로 JWT 토큰에서 userId를 읽어 비즈니스 로직에 전달해준다. (요청 스펙이 깔끔해지고, 불필요한 필드가 하나 줄어든다)

어떤 원리로 가능한걸까 ?

@CurrentUser 작동 방식

JWT 원문

JWT는 “양 당사자 사이에서 전달할 클레임을 안전하게 표현”하는 표준이다(RFC 7519). 헤더 + 페이로드 + 서명 세 부분으로 구성되고, 페이로드에 sub, iss, exp 같은 표준 클레임과 id 같은 커스텀 클레임을 넣을 수 있는데, 우리는 여기에 userId를 담아둔다고 가정해보자

그러면 클라에서 요청을 보낼때 해당 값들로 암호화된 JWT가 담겨져서 온다면, 스프링 시큐리티에서 Authorization: Bearer 토큰을 자동으로 검증하고, Authentication을 구성해 SecurityContextHolder에 넣어서 principal이 Jwt 객체가 되어 클레임을 바로 읽을 수 있게 되는것이다

토큰에 어떤 값이 들어있는지 궁금하면 jwt.io 같은 디버거로 바로 확인할 수 있다

https://www.jwt.io/

JSON Web Tokens - jwt.io

JSON Web Token (JWT) is a compact URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is digitally signed using JSON Web Signature (JWS).

www.jwt.io

본문

이제 실제 구현한 내용을 단계별로 설명해보려고 한다

실제 구현 플로우

이제 실제 구현한 내용을 단계별로 설명해보려고 한다

@Target({ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface CurrentUser {
}

가장 먼저, 컨트롤러 파라미터에 붙일 마커 애노테이션을 정의해준다

그 다음 CurrentUserResolver를 구현해주었다

@Component
public class CurrentUserResolver implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.hasParameterAnnotation(CurrentUser.class)
                && parameter.getParameterType().equals(Long.class);
    }

    @Override
    public Object resolveArgument(MethodParameter parameter,
                                  ModelAndViewContainer mavContainer,
                                  NativeWebRequest webRequest,
                                  WebDataBinderFactory binderFactory) {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

        if (authentication == null || authentication.getPrincipal() == null
                || !(authentication.getPrincipal() instanceof Jwt jwt)) {
            return null; // or throw
        }

        return Long.valueOf(jwt.getClaimAsString(JwtProvider.ID_CLAIM));
    }
}

전체적인 메서드의 흐름은 아래와 같다

SecurityContextHolder에서 현재 토큰 꺼내기. (스레드 로컬 기반 컨텍스트)
principal은 보통 Jwt. 여기서 getClaimAsString("id") 같은 식으로 클레임을 읽어 userId로 변환
상황에 따라 null 대신 예외를 던질 수도 있음

그리고 구현한 리졸버를 MVC에 등록해야한다

@Configuration
@RequiredArgsConstructor
public class WebMvcConfig implements WebMvcConfigurer {

    private final CurrentUserResolver currentUserResolver;

    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.addFirst(currentUserResolver);
    }
}

나는 WebMvcConfigurer#addArgumentResolvers로 커스텀 리졸버를 가장 앞에 두도록하여 우선 적용되도록 설정해주었다

마치며

맨처음에 서론에서 설명했던 예시의 코드는 아래처럼 간단해진다

@PostMapping("/{productId}/crawl")
public ApiResponse<CrawlResponse> crawl(@CurrentUser Long userId) {
    List<String> videoUrls = youtubeCrawlerService.crawlAndStoreReviews(userId);
    return ApiResponse.success(HttpStatus.OK, ResponseMessage.CRAWL_SUCCESS.getMessage(),
            CrawlResponse.of(videoUrls));
}

사실 엄청 간단한 내용이지만, 클라이언트는 헤더에 토큰만 보내면 되기때문에 불필요한 request가 간소화될 수 있다. 또한 백엔드 측면에서도 바디/쿼리/경로에 userId를 두지 않아도 되고, 서버가 검증한 토큰의 값을 사용할 수 있어서 보안적인 측면에서도 이점이 있다

참고한 자료

https://docs.spring.io/spring-security/reference/api/java/org/springframework/security/core/annotation/AuthenticationPrincipal.html

https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html

슬랙 웹훅으로 신고하기 기능 구현하기 (Webhook)

huncozyboy — Thu, 28 Aug 2025 03:58:07 +0900

들어가며

먼저 링크 서비스에 기획에 대해서 가볍게 설명하려고 한다

페르소나 : 동아리에서 친해지기 위한 커뮤니케이션 수단이 필요한 동아리원

Leenk 서비스는, Leets라는 동아리를 운영하는 입장에서 생각했을때 동아리 원들의 커뮤니케이션 수단을 개발해서 제공해준다면 어떨까 ?? 라는 생각이 들어 시작하게된 서비스다

예쁜 디자인 + 랜딩 사이트 만들어주셔서 개큰감사 ‍♂️ (Shout out to 도연, 한별)

https://leets-makers.framer.website/

Leets Makers

Gachon University IT Collaboration Club, Leets Makers' Landing Page - Made by. Makers' Designer, Doaeng.

leets-makers.framer.website

실제 수료한 동아리 원들을 대상으로 한 설문조사 내용들

주요 기능인 피드 + 링크 기능

동아리원들이 자유롭게 사진을 공유하고, 모각작과 같은 링크를 생성하면서 특정 게시글을 신고할 수 있는 기능이 필요하여 도입하게 되었다 + TMI로 지금 생각해보면 정말 필요한 기능이였는가? 라는 생각도 들지만, 아래 사진에 나와있듯이 앱 출시 리젝 사유중에 " 신고 및 차단 기능이 존재해야함 " 이라는 내용이 있었어서 도입을 결정하게 되었다

문서화 했었던 앱 출시시 리젝 사유들

구현한 플로우

서론이 조금 길었지만, 다시 돌아와서 이번 포스팅에서 다룰 내용은 " 링크 신고하기 기능 " 이다. 유저가 신고하기 버튼을 누르면 Slack의 Webhook을 활용해서, 운영진의 슬랙으로 알림이 오는 로직으로 구현을 하였다

링크 신고하기 기능 바텀시트

1. 슬랙 웹훅 URL 환경변수 추가

먼저 아래의 앱추가를 눌러준다

앱추가 클릭

그 다음 아래처럼 생긴 웹훅 앱을 사용하고싶은 채널에 추가해주면 된다

web-hook-app 이라는 앱 추가

사용하고 싶은 채널을 선택해서 지정

위 사진처럼 웹훅 URL이 나오게 되는데 Copy를 눌러 복사

그 다음 yml 파일에 아래 처럼 선언하여, 위에서 복사한 웹훅 URL을 주입받는다고 이해해주면 된다

slack:
  webhook_url: ${SLACK_WEBHOOK_URL}

2. LeenkReportRequest 입력 DTO 추가

public record LeenkReportRequest(

        @NotBlank
        @Size(max = 100)
        String report
) {
}

기본 세팅이 끝난 뒤엔 먼저 위에 뷰에서도 나와있듯이, 신고 사유를 입력받을 수 있도록 LeenkReportRequest를 추가해주었다

3. reportLeenk 비즈니스 로직 구현

@Transactional(readOnly = true)
    public void reportLeenk(Long userId, Long leenkId, LeenkReportRequest request) {
        User user = userGetService.findById(userId);
        Leenk leenk = leenkGetService.findById(leenkId);

        notionDatabaseService.sendLeenkReport(request.report(), user.getId(), leenk.getId());
        slackWebhookService.sendLeenkReport(request.report());
}

또한 실제 존재하는 유저인지, 링크인지 조회해오면서 예외처리를 진행해주고 노션 데이터베이스와 슬랙 웹훅에 알림을 전송하는 로직을 구현했다 (노션 데이터베이스에도 저장하는 이유는 예상치 못한 장애 발생시에도 유실 방지 + 신고가 들어오면 회의때 쉽게 트래킹하기 위함)

4. sendLeenkReport로 슬랙에 신고 내용 전송

public void sendLeenkReport(String report) {
        String formatted = "*[링크 신고]*\n```" + report + "```";
        
        slackRestClient.post()
                .uri(webhookUrl)
                .header("Content-Type", "application/json")
                .body(Map.of("text", formatted))
                .retrieve()
                .toBodilessEntity();
}

SlackWebhookService에서 선언한 메서드인데, webhookUrl을 환경변수로 주입받아서 슬랙으로 전송할 최소 페이로드: {"text": "메시지"} 를 설정해주고, 위 코드를 보면 알 수 있듯이 json 형식으로 자유롭게 커스텀 할 수 있다고 생각해주면 된다

마치며

정상적으로 슬랙에 남는 신고 기능

위처럼 유저가 신고하기를 누르면, 슬랙에서 정상적으로 트래킹을 할 수 있었다

링크 서비스 피드백 기능

+ 추가로, 비슷한 플로우로 링크 서비스 자체에 대한 피드백도 위처럼 받을 수 있도록 구현해놓아서, 실제 사용자의 의견을 신속하게 받을 수 있도록 하였다

Discord Webhook 과의 차이점

바로 이전 게시글인데, Discord Webhook의 구현 플로우가 궁금하다면 아래 링크를 참고해주면 더 좋을거같다

https://huncozyboy.tistory.com/57

디스코드를 활용한 500 에러 알림 자동화 (Webhook)

들어가며지금 해당 API 500 뜨는데 원인 알 수 있을까요지금 오류 로그 한번만 확인해주실래요 ??해당 API 500 뜨는데 원인이 뭘까요백엔드로 다른 파트와 개발을 진행하다보면, 플젝을 진행하면서

huncozyboy.tistory.com

개인적으로 슬랙은 디스코드와 비교해서 JSON 문법이 엄격해서 테스트할때 잘못 보내면 400 에러가 나오는 경우가 더 많았었다. Block Kit 등 복잡한 구조를 공식 지원해주는 것은 장점이라고 생각했었다. 디스코드는 JSON 형태라기보다는, 텍스트 마크다운과 코드블럭을 기본 지원해주어서 표현 부분이 조금 다르다는 생각도 들었다

또한 추가로 찾아보다가 알게된 정보인데, Slack은 4,000자까지 UI 잘림 없이 잘 반환되지만, Discord는 2,000자 제한이 있기 때문에 긴 로그같은 내용은 분할하거나 파일로 첨부하는 방식도 있다고 나와있었다

채팅 기능이나, 매칭 기능, 알림 기능 등등에서 DLQ를 활용할 수 있듯이, 슬랙에서는 레이트 리밋 시 HTTP 429 + Retry-After 헤더로 백오프 로직을 짤 수 있고, 디스코드에서는 429 retry_after 기반으로 재시도 로직을 짤 수 있어 트래픽 병목이 생긴다면 해당 내용까지 고려해주면 더 좋은 설계가 될 수 있을거라고 생각했었다

참고한 자료

https://support.discord.com/hc/ko/articles/228383668

https://api.slack.com/messaging/webhooks

열정을 기록하기

Claude Code Skills로 코드리뷰 Skill 커스텀 해보기

들어가며

1. Skills 구조 이해하기

2. Skill은 언제 실행될까?

본론

1. 초기 세팅

2. 코드 리뷰 가이드 생성

3. skill-creator로 코드리뷰 Skill 만들기

4. Compaction까지 고려해서 설계

마치며

클로드 코드 개발자 Boris Cherny의 클로드 코드 사용법 (Claude Code)

들어가며

본론

1) Claude 프로세스 5개를 동시에 실행

2) 로컬 Claude 세션 병렬 실행

3) Opus 4.5 모델 사용

4) Claude Code md 파일 설정

5) PR에 @.claude를 태그

6) 계획 모드 -> 승인 모드 전환

7) 내부 루프 워크플로에 슬래시 명령어를 사용

8) 몇 가지 서브에이전트의 정기적으로 사용

9) PostToolUse 훅을 사용하여 Claude의 코드 형식을 지정

10) --dangerously-skip-permissions 옵션 미사용

11) Claude Code에서도 사용하는 모든 도구를 활용 (MCP)

13) Claude에게 작업 검증 방법을 제공

느낀점

AI Copilot Agent Mode로 SQL 쿼리 마이그레이션 (Copilot)

들어가며

MySQL 8.x 로 마이그레이션을 결정한 이유

첫번째, 잦은 Lock 발생

두번째, 대용량 동시성 처리에서 비효율

본론

마이그레이션에 Copilot 활용

프롬프트 작성 과정

agent-prompt.md 커스터마이징

CUBRID -> MySQL 8 쿼리 변환 일부

마치며

스웨거 typescript-api로 자동화 하는법 (Swagger)

들어가며

본문

swagger-typescript-api 활용하기

1단계 – 기본 템플릿 뽑아서 레포에 복사

2단계 – http-client 템플릿에서 axios 인스턴스 주입 구조로 변경

3단계 – API 템플릿에서 메서드 이름과 반환 타입 컨벤션 정리

4단계 – hooks 로 스키마/타입 수정하여 플러그인처럼 사용

마치며

Spring Boot 4.0 RC1 릴리즈 (Spring)

서론

본론

주요 변경 사항

RestClientTest 추가

신규 어노테이션 @ObservationKeyValue

직렬화/역직렬화 및 라이브러리 변화: Jackson 3 검토

마치며

Conflict를 깃허브 웹에서 해결시 주의사항 (Github)

들어가며

Github 웹에서 컨플릭트 해결하는 방법

가장 많이 사용하는 깃허브 전략

본론

base 브랜치 전체가 병합될 수 있다.

base 브랜치의 최신 내용을 반영할 시에 주의사항

권장하는 충돌 해결 방식 및 브랜치 전략

마치며

참고한 링크

Instagram Basic Display API vs Graph API 무슨 차이가 있을까 (OAuth)

들어가며

본문

로그인 화면의 차이

기본세팅 (Meta 콘솔 설정의 차이)

얻을 수 있는 정보의 차이

사업자 등록 플로우

마치며

배포 후 구매한 도메인 연결하기 (Route 53)

들어가며

Route 53이란 ?

본문

1. 가비아 접속 및 원하는 도메인 구매

2. AWS Route 53 호스팅 영역 생성

3. 레코드 확인 및 등록

직렬화/역직렬화 및 라이브러리 변화: Jackson 3 검토