"나중에 읽어야지" 하고 카카오톡 나와의 채팅방이나 브라우저 탭에 쌓아둔 수많은 링크들, 결국 다시 안 보신 적 많으시죠?
쏟아지는 정보 속에서 핵심만 쏙 뽑아 정리해 주는 나만의 AI 북마크 비서, 미드나잇 클리퍼(Midnight Clipper)를 소개합니다!

🧐 미드나잇 클리퍼는 어떤 서비스인가요?

미드나잇 클리퍼(Midnight Clipper)는 웹 서핑 중 발견한 유용한 기사, 블로그, 칼럼 링크나 긴 텍스트를 저장하면, Google Gemini AI가 즉시 핵심 3줄 요약과 자동 분류 태그를 만들어 주는 차세대 스마트 북마크 스튜디오입니다.

• 🌐 서비스 바로가기: https://bookmark-assistant-hline.vercel.app
• 💰 이용 요금: 완전 무료 (Free)
• ⚡ 주요 AI 엔진: Google Gemini AI

✨ 핵심 기능 5가지 한눈에 보기

1. 🔗 링크만 넣으면 끝! 'AI 핵심 3줄 요약'

긴 칼럼이나 영문 아티클도 URL만 입력창에 넣으면 AI가 본문을 자동으로 분석하여 가장 중요한 핵심 3줄로 깔끔하게 정리해 줍니다. 바쁜 일상 속에서 글을 다 읽지 않아도 요점만 10초 만에 파악할 수 있습니다.

2. 📝 링크가 없어도 OK! '텍스트 직접 스크랩'

웹 링크뿐만 아니라 뉴스레터 내용, 업무 메모, 유용한 팁 등 복사한 텍스트를 그대로 붙여넣어도 AI가 알아서 제목을 정하고 3줄 요약과 태그를 붙여 저장해 줍니다.

3. 💬 카카오톡으로 링크 보내면 실시간 자동 저장!

PC를 켜지 않아도 모바일 카카오톡 챗봇에 링크나 글을 쓱 공유하기만 하면, 내 미드나잇 클리퍼 서재에 실시간으로 3줄 요약과 함께 저장됩니다.

4. 🏷️ 스마트 자동 태깅 & 상세 조건 검색

AI가 글의 주제를 분석해 #AI, #생산성, #개발, #트렌드 같은 카테고리 태그를 자동으로 달아줍니다. 나중에 저장한 글이 수백 개로 늘어나도 [제목 / 요약문 / 태그 / URL]을 지정하여 원하는 자료를 1초 만에 찾아낼 수 있습니다.

5. 🌙 눈이 편안한 미드나잇 다크 테마

늦은 밤 자료 조사를 하거나 침대에서 아티클을 읽을 때도 눈의 피로를 최소화해 주는 감성적인 딥 네이비 & 골드 다크 모드를 지원합니다.

🚀 1분 만에 시작하는 초간단 사용 방법

STEP 1. 사이트 접속 & 원클릭 구글 로그인

1. 미드나잇 클리퍼 웹사이트(https://bookmark-assistant-hline.vercel.app)에 접속합니다.
2. 상단의 [Google 로그인]을 누르면 별도 가입 절차 없이 1초 만에 시작할 수 있습니다.

👉 https://bookmark-assistant-hline.vercel.app

STEP 2. 링크 또는 텍스트 입력 ➔ [북마크 추가]

1. 메인 화면 입력창에 저장하고 싶은 웹 페이지 URL을 붙여넣습니다. (또는 텍스트를 직접 붙여넣어도 자동 감지됩니다.)
2. [북마크 추가] 버튼을 클릭합니다.
3. 잠시 후 AI가 생성한 제목, 3줄 핵심 요약, 스마트 태그가 달린 북마크 카드가 내 서재에 쏙 들어옵니다!

STEP 3. 카카오톡 챗봇과 내 계정 연결하기 (모바일 스크랩)

1. 상단 메뉴의 [카카오 연동] 버튼을 클릭합니다.
2. 화면에 나타난 8자리 연동 코드를 확인합니다.
3. 카카오톡 미드나잇 클리퍼 챗봇에게 연동 코드를 전송하면 연결 완료!
4. 이제 스마트폰으로 웹 서핑을 하다가 [공유하기 ➔ 카카오톡]으로 링크만 보내면 내 웹 서재에 자동 요약 저장됩니다.

STEP 4. 상세 검색으로 원하는 정보 찾기

• 상단 검색창에 키워드를 입력하고, 검색 필터(전체 / 제목 / 요약 / 태그 / 링크)를 선택하면 수많은 자료 중 원하는 정보만 빠르고 정확하게 찾아볼 수 있습니다.
• 마음에 드는 요약문은 언제든 수정하거나 원본 링크로 바로 이동할 수 있습니다.

🎯 이런 분들께 강력 추천합니다!

• 📌 유용한 글을 모아두지만 바빠서 다시 읽을 시간이 없는 직장인 & 학생
• 📌 매일 수많은 뉴스레터와 IT 트렌드 기사를 모니터링해야 하는 기획자/마케터/개발자
• 📌 카카오톡 '나와의 채팅방'이 온갖 정리 안 된 링크로 가득 차 있는 분
• 📌 긴 아티클에서 핵심만 10초 만에 빠르게 훑어보고 싶은 분

🌙 지금 바로 무료로 사용해 보세요!

정보 과부하 시대, 읽지 못하고 쌓아두기만 했던 북마크들을 AI와 함께 스마트한 나만의 지식 보관소로 바꿔보세요.

👉 미드나잇 클리퍼 바로가기: https://bookmark-assistant-hline.vercel.app

Git GUI 툴인 Fork(git-fork.com) 를 사용하다 보면, 좌측 사이드바의 Branches 목록에서 잘 작업하던 브랜치 옆에 경고 느낌표(!) 아이콘이 표시되는 경우가 있습니다.

갑자기 느낌표가 뜨면 내 코드에 치명적인 충돌이나 에러가 발생한 것은 아닌지 당황하기 쉬운데요.

이번 글에서는 Fork에서 브랜치 옆에 느낌표 아이콘이 뜨는 정확한 원인 과 상황별 대처 및 정리 방법 을 정리합니다.

1. Fork 브랜치 아이콘의 의미와 느낌표(!)의 정체

Fork는 로컬 브랜치와 원격 저장소(upstream/origin)의 추적 상태를 시각적으로 구분할 수 있도록 3가지 형태의 아이콘을 제공합니다.

즉, 느낌표(!)는 코드가 깨진 것이 아니라 "이 로컬 브랜치가 바라보고 있던 원격(Remote) 브랜치가 GitHub/GitLab 등에서 이미 삭제되었습니다" 라는 일종의 연결 끊김 알림(Orphaned Branch)입니다.

2. 왜 원격 브랜치가 삭제되었을까?

보통 팀 협업 환경에서 다음과 같은 작업이 일어났을 때 느낌표가 나타납니다:

1. Pull Request(PR) 머지 후 원격 브랜치 자동 삭제
   • GitHub이나 GitLab에서 PR이 통과되어 main 또는 develop에 머지된 후, "Delete branch" 버튼을 눌러 원격 브랜치를 삭제한 경우입니다.
2. 동료 개발자가 작업 완료 후 원격 브랜치를 정리한 경우
3. Fetch with Prune 실행 후 갱신
   • Fork에서 Fetch (with Prune)를 수행하면서 로컬이 원격의 최신 삭제 내역을 감지했을 때 느낌표로 전환됩니다.

3. 상황별 해결 및 대처 방법

느낌표 아이콘을 발견했다면 현재 작업 상태에 따라 아래 두 가지 중 하나로 조치하시면 됩니다.

상황 1: 이미 PR이 머지되어 작업이 완전히 끝난 경우 (가장 흔함)

원격에서 이미 머지되어 삭제된 브랜치이므로, 내 컴퓨터(로컬)에 남아있는 해당 브랜치도 안전하게 삭제하여 목록을 정리하면 됩니다.

1. 좌측 사이드바 Branches에서 느낌표(!)가 뜬 브랜치를 우클릭합니다.
2. Delete '브랜치명'… 을 클릭합니다.
3. 팝업 확인창에서 삭제를 완료하면 사이드바가 깔끔해집니다.

상황 2: 아직 작업 중인데 실수로 원격 브랜치가 지워졌거나 다시 올려야 하는 경우

로컬에 작성된 커밋들은 그대로 남아있으므로, 원격 저장소에 다시 푸시해주면 느낌표가 사라지고 정상 동기화 아이콘으로 돌아옵니다.

1. 해당 브랜치를 더블 클릭하여 체크아웃(Checkout) 합니다.
2. 상단 툴바의 Push 버튼을 클릭합니다.
3. Push to: 항목에 대상 원격 저장소(origin)를 지정하고 푸시를 진행합니다.
4. 원격에 브랜치가 다시 생성되면서 느낌표 아이콘이 사라집니다.

💡 추가 꿀팁: 원격에서 지워진 브랜치 한 번에 감지하기 (Prune)

GitHub 웹상에서 브랜치를 삭제했더라도 로컬 Fork에서는 여전히 남아있는 것처럼 보일 수 있습니다. 주기적으로 원격의 삭제 상태를 로컬과 동기화하려면 Prune 옵션을 켜두는 것이 좋습니다.

• Fork 상단 툴바 Fetch 클릭 ➔ Prune tracking branches no longer on remote 체크 ➔ Fetch 실행

이렇게 하면 원격에서 사라진 브랜치들을 한 번에 스캔하여, 로컬 브랜치에 느낌표(!)를 즉시 띄워주므로 불필요한 브랜치를 제때 정리할 수 있습니다.

Git GUI 툴인 Fork(git-fork.com) 에서는 터미널 명령어나 복잡한 우클릭 메뉴 없이도 마우스 동작만으로 브랜치를 합치는 기능을 지원합니다.

Fork 기능 소개:
*"Fork now allows for a more intuitive way to merge and rebase branches – drag & drop. Use the mouse to drag a branch on the sidebar into another branch, and choose whether to merge or rebase from the resulting popover."*
(번역) Fork에서 드래그 앤 드롭(Drag & Drop)을 통해 브랜치를 병합하고 리베이스할 수 있는 한층 더 직관적인 방식을 지원합니다. 사이드바에서 브랜치를 마우스로 끌어 다른 브랜치 위에 놓은 뒤, 나타나는 팝오버 창에서 Merge 또는 Rebase를 선택하기만 하면 됩니다.

1. 드래그 앤 드롭(Drag & Drop) 사용 방법

1. 브랜치 끌어오기:
   Fork 좌측 사이드바의 Branches 목록에서 병합할 소스 브랜치를 마우스 왼쪽 버튼으로 클릭한 채 유지합니다.
2. 대상 브랜치에 올려놓기(Drop):
   합쳐질 타깃 브랜치 위로 끌고 가 마우스 버튼을 놓습니다.
3. 동작 선택 (Popover):
   마우스를 놓으면 팝업(Popover) 창이 즉시 나타납니다:
   • Merge...: 소스 브랜치를 대상 브랜치로 일반 병합(Merge Commit 생성 또는 Fast-Forward).
   • Rebase...: 대상 브랜치의 최신 커밋 위로 소스 브랜치를 재배치(Rebase).

2. 언제 쓰면 좋을까? 

케이스 1: 기능 개발 완료 후 작업 브랜치를 develop에 병합할 때 (Merge)

• 상황: feature/login 브랜치에서 기능 개발과 테스트를 모두 끝내고 공용 개발 브랜치인 develop에 합쳐야 하는 상황.
• 적용: 사이드바에서 feature/login 브랜치를 끌어 develop 브랜치 위에 드롭한 뒤 Merge를 선택합니다. 체크아웃을 번거롭게 여러 번 바꿀 필요 없이 즉시 병합 작업을 마칠 수 있습니다.

케이스 2: 상위 최신 코드를 내 피처 브랜치에 가져와 히스토리를 정리할 때 (Rebase)

• 상황: 내가 작업 중인 feature/search 브랜치에 다른 팀원이 main에 올린 최신 변경 내역을 반영해 충돌을 미리 정리하고 싶을 때.
• 적용: main 브랜치를 드래그하여 내 feature/search 위에 놓거나, 내 브랜치를 끌어 main 위로 드롭해 Rebase를 선택합니다. 머지 커밋 없이 한 줄 히스토리로 깔끔하게 정리할 수 있습니다.

케이스 3: 릴리즈 브랜치 준비 및 핫픽스 적용 (Merge)

• 상황: 배포를 앞두고 검증된 release-1.0 브랜치를 main으로 밀어 넣거나, 긴급 수정 건(hotfix)을 develop과 main 양쪽에 각각 빠르게 합쳐야 하는 상황.
• 적용: 핫픽스 브랜치를 끌어 각 대상 브랜치에 순서대로 드롭 후 머지하면 작업 전환 실수를 줄이고 빠르게 동기화할 수 있습니다.

💡 팁 & 주의사항

• 방향 확인: A를 B로 드래그했을 때 "A를 B에 합칠 것인지" 팝업에 표시되는 브랜치 방향 문구를 실행 전 확인하세요.
• 충돌 처리: 드롭 후 머지/리베이스 진행 중 파일 충돌이 발생하면 Fork 상단에 충돌 알림 바와 함께 내장 Conflict Resolver(충돌 해결기)가 활성화되어 안전하게 코드를 정리할 수 있습니다.

로컬에서 이런저런 작업을 하다가 코드가 꼬였거나, 잘못된 커밋이 쌓여서 "내 로컬의 모든 수정을 버리고 원격 저장소(origin) 상태와 100% 똑같이 강제로 맞추고 싶을 때" 가 있습니다.

Git 개념상 로컬 작업을 유지한 채 베이스를 바꾸는 rebase와 달리, 원격 상태로 로컬을 완전히 덮어씌우는 작업은 Fetch 후 Hard Reset 방식으로 진행해야 합니다.

Fork(git-fork.com) GUI를 사용해 클릭 몇 번으로 로컬을 origin 최신 커밋으로 깔끔하게 강제 동기화하는 방법을 정리합니다.

⚠️ 주의사항: 작업 중인 변경 사항 영구 삭제

Hard Reset을 실행하면 아직 커밋하지 않은 수정 파일(Uncommitted changes)과 원격에 없는 로컬 커밋 내역이 완전히 삭제됩니다. 혹시 나중에 참고해야 할 임시 작업물이 있다면 미리 Stash(임시 저장)를 해두세요.

1단계: 원격 저장소(origin) 최신 커밋 가져오기 (Fetch)

로컬 Git이 origin의 가장 최신 커밋 위치를 알고 있어야 정확한 지점으로 되돌릴 수 있습니다.

1. Fork 상단 툴바에서 Fetch 아이콘을 클릭합니다.
2. Fetch from: 드롭다운에서 origin을 선택하고 Fetch 버튼을 누릅니다.
3. 이제 중앙 커밋 그래프 화면에 origin/main(또는 동기화할 브랜치명) 라벨이 최신 커밋 위치로 갱신됩니다.

2단계: 동기화할 로컬 브랜치 체크아웃

1. 좌측 사이드바 Branches 영역을 확인합니다.
2. 원격과 일치시키려는 내 로컬 브랜치(예: main 또는 작업 브랜치)를 더블 클릭하여 체크아웃합니다.
3. 브랜치명 옆에 체크 표시(✔) 또는 굵은 글씨로 활성화되었는지 확인합니다.

3단계: origin 브랜치를 기준으로 Hard Reset 실행 (핵심)

로컬 브랜치의 HEAD 포인터를 origin 브랜치 위치로 강제 이동시킵니다.

1. 좌측 사이드바의 Remotes ➔ origin ➔ 맞추고 싶은 브랜치(예: main) 를 찾습니다.
   (중앙 커밋 히스토리 그래프에서 origin/main 태그를 직접 찾아도 됩니다.)
2. 해당 브랜치를 우클릭합니다.
3. 메뉴에서 Reset '현재브랜치명' to Here... 를 클릭합니다.
   • 예: Reset 'main' to Here...
4. 옵션 선택 팝업창에서 Reset 방식을 선택합니다:
   • Hard 옵션을 선택합니다.
     (Hard: 로컬의 모든 변경 사항과 커밋을 버리고 대상 커밋 상태로 완벽히 일치시킴)
5. Reset 버튼을 클릭하여 실행합니다.

💡 실행 결과 확인

• 커밋 그래프 정리: 내 로컬 브랜치 태그(main)와 원격 브랜치 태그(origin/main)가 그래프상에서 완전히 동일한 커밋 위치에 나란히 배치됩니다.
• 작업 디렉토리 초기화: 좌측 상단 Changes 탭이 0으로 비워지며, 로컬의 모든 파일이 원격 저장소의 코드 상태와 100% 동일해집니다.

연관글 어느 날 갑자기 내 Git에 Pull 대기 건수가 117건이나 떴다 (원인 분석과 안전한 해결책)

본 글은 하네스 엔지니어링 with 클로드 코드 기반으로 작성되었습니다. 해당 책을 같이 보시면 이해에 도움이 됩니다
https://product.kyobobook.co.kr/detail/S000220048885

Part 04. 하네스 실전편: 실제로 돌아가는 4가지 AI 팀 만들기

Chapter 11. 코드 리뷰 자동화 팀

실전 시나리오: 깃허브 코드 검토

개발자가 코드를 새로 작성해서 올렸을 때(PR), 사람이 일일이 수백 줄의 코드를 읽다 보면 치명적인 보안 구멍이나 데이터베이스 렉을 유발하는 코드를 놓치기 쉽습니다. 이를 자동으로 꼼꼼히 점검해 주는 2인 리뷰 팀을 만듭니다.

팀 구성과 역할

• 보안 검사관 (SecurityAgent): 해커가 침투할 수 있는 비밀번호 노출이나 악성 코드 취약점만 현미경으로 들여다봅니다.
• DB 성능 코치 (SqlAgent): 데이터베이스에서 자료를 불러오는 쿼리문이 너무 느리거나 서버를 멈추게 만들 위험이 없는지 점검합니다.

명령어 하나로 필요한 검사만 골라 부르기

전체 코드를 다 볼 때는 /review-all을 치면 두 명이 순서대로 코드를 살펴봅니다.
하지만 단순한 쿼리 하나만 확인하고 싶을 때 전체 팀을 깨우면 시간과 돈이 낭비됩니다. 이때는 /review-sql [쿼리문]만 입력합니다. 오케스트레이터가 보안 검사는 건너뛰고 DB 성능 코치 1명만 즉시 깨워 1초 만에 실행 계획을 튜닝해 줍니다.

Chapter 12. 풀스택 기능 구현 팀

실전 시나리오: "새로운 로그인 화면 만들어줘"

새로운 웹사이트 기능을 만들 때는 화면을 예쁘게 만드는 일(프론트엔드)과 데이터베이스에 비밀번호를 저장하는 일(백엔드)이 동시에 필요합니다.

부채를 펼치고 접는 팬아웃 · 팬인 워크플로우

1. Phase 1 (기획자): 어떤 화면이 필요하고 데이터는 어떤 규칙으로 주고받을지 '약속 규격(API 명세)'을 먼저 종이에 적습니다.
2. Phase 2 (팬아웃 - 부채 펴기):

• 백엔드 AI는 서버 코드를 짜고,
• 프론트엔드 AI는 로그인 버튼과 화면 디자인을 동시에 병렬로 작성합니다. 작업 시간이 절반으로 줄어듭니다.

3. Phase 3 (팬인 - 부채 접기): 통합 검증 AI가 둘이 만든 코드를 합쳐서 실제로 로그인이 잘 되는지 한 번에 테스트합니다.

이때 두 AI가 서로 다른 생각을 하지 않도록, 기획자가 작성한 약속 규격을 공유 칠판(State)에 딱 붙여두고 보면서 코딩하게 만드는 것이 핵심입니다.

Chapter 13. 레거시 마이그레이션 팀 (3,500개의 낡은 테스트 파일)

실전 시나리오: 3,500개의 오래된 파일 일괄 업데이트

회사 시스템을 최신 버전으로 업그레이드할 때, 과거에 작성된 3,500개의 낡은 파일들을 새 문법으로 일일이 바꿔야 하는 거대한 작업이 있습니다. AI에게 "알아서 다 바꿔줘"라고 한꺼번에 던지면 중간에 멈추거나 코드가 꼬여 대형 사고가 납니다.

족보(의존성) 먼저 그리고 바구니에 나누어 담기

1. Phase 1 (의존성 매핑): 가장 먼저 3,500개 파일 중 "누가 누구의 도움을 받아 돌아가는지" 가계도(족보)를 먼저 그립니다. 이 단계의 정리를 아까워하면 나중에 무한 오류에 빠집니다.
2. Phase 2 (배치 분할): 3,500개를 한 번에 돌리지 않고, 서로 영향이 없는 파일들끼리 50개씩 작은 묶음(Batch)으로 쪼개어 차례대로 변환합니다.
3. Phase 3 (3%의 수작업 격리): 3,500개 중 3,400개는 AI가 완벽히 고치지만, 구조가 너무 꼬여있는 100개 파일은 AI도 갈팡질팡합니다. 이때 억지로 AI에게 시키지 않고 "사람 확인 필요 바구니(manual-queue)"로 자동으로 던져두어, 나중에 사람이 직접 눈으로 보고 고칠 수 있게 격리합니다.

Chapter 14. 디버깅 및 RCA(원인 분석) 팀

실전 시나리오: "내 컴퓨터에선 잘 되는데 서버에선 왜 터지지?"

개발자들이 가장 머리 아파하는 순간은 "분명 내 노트북에서는 잘 돌아가던 프로그램이 실제 서버에 올리니 먹통이 될 때"입니다. 감으로 때려맞히지 않고 탐정처럼 근본 원인(RCA)을 밝혀내는 팀을 꾸립니다.

탐정 3인방의 수사 과정

1. 로그 수집관: 에러가 난 순간의 서버 기록(로그)을 싹 긁어모아 붉은색 에러 메시지를 찾아냅니다.
2. 환경 비교관: 개발자 노트북과 실제 서버의 환경(파이썬 버전, 메모리 크기, 네트워크 설정)을 대조해 숨은 차이점을 밝혀냅니다.
3. 해결-검증관: "원인은 메모리 부족 때문"이라는 가설을 세우고, 코드를 고친 뒤 모의 테스트를 돌려 가설이 맞는지 확인합니다.

모든 수사가 끝나면 팀은 "어디가 범인이었고, 어떻게 고쳤으며, 재발을 막으려면 무엇을 해야 하는지" 깔끔한 원인 분석 보고서 1장을 사람에게 제출하고 깔끔하게 해산합니다.

본 글은 하네스 엔지니어링 with 클로드 코드 기반으로 작성되었습니다. 해당 책을 같이 보시면 이해에 도움이 됩니다
https://product.kyobobook.co.kr/detail/S000220048885

Part 03. 메타스킬(Meta-Skill)과 아키텍처 패턴: 팀을 조립하고 배치하는 법

Chapter 07. 메타스킬 파이프라인과 슬래시 명령어

조립 설명서를 만드는 '레시피': 메타스킬

레고 블록을 조립할 때, 매번 부품을 상자에서 하나씩 뒤져가며 감으로 맞추면 시간도 오래 걸리고 모양도 엉망이 됩니다. 하지만 "어떤 블록을 몇 번 순서로 꺼내서 조립하라"는 조립 설명서가 있으면 누구나 5분 만에 멋진 우주선을 완성할 수 있습니다.

메타스킬(Meta-Skill)은 에이전트 시스템의 조립 설명서입니다.

• "보안 검사관 1명과 DB 전문가 1명을 소집해라."
• "보안 검사가 통과되면 DB 전문가에게 넘겨라."
• "작업이 끝나면 팀을 해산하고 결과만 보고해라."

이처럼 팀원을 어떻게 모으고 어떤 순서로 일시킬지 적어둔 지휘 매뉴얼 마크다운 문서를 바로 메타스킬이라고 부릅니다.

부르면 즉시 출동하는 마법 주문: 슬래시 명령어

에이전트에게 매번 "이 코드를 보고 보안 검사관이랑 DB 전문가를 불러서 차례대로 검토해 줘"라고 길게 말할 필요가 없습니다.

마크다운 문서 맨 위에 /review-all처럼 전용 주문(슬래시 명령어)을 딱 하나 등록해 두면 됩니다.

• /review-all [내 코드]를 치는 순간, 오케스트레이터는 긴말하지 않고 즉시 해당 팀을 조립해 작업을 시작합니다.
• 특정 친구만 부르고 싶다면 /review-sec [내 코드]처럼 보안 담당자만 핀포인트로 깨울 수도 있습니다.

반장이 혼자 아는 척하지 못하게 막기

명령어를 쓰지 않고 자연어로 "쿼리 튜닝 좀 해줘"라고 말하면, 오케스트레이터(반장)가 전문 에이전트를 부르지 않고 "어? 나도 그거 아는데 그냥 내가 대충 답해줄게"라며 자기가 아는 척 글을 써버리는 실수를 합니다.

전문가가 가진 엄격한 체크리스트를 완전히 무시해 버리는 치명적인 문제입니다. 그래서 오케스트레이터에게는 "너는 직접 글을 쓰지 말고, 정해진 슬래시 명령어가 들어오면 무조건 해당 전문가만 호출하라"는 단단한 브레이크(가드레일)를 걸어두어야 합니다.

Chapter 08. 6가지 핵심 아키텍처 패턴

팀을 세우는 모양에 따라 결과가 달라진다

축구 경기에서 공격수와 수비수의 진형을 짜듯, AI 에이전트들도 일의 성격에 맞게 대형을 짜야 합니다. 대표적인 6가지 대형이 있습니다.

1. 파이프라인 (이어달리기): 1번 주자가 글을 다 쓰면 2번 주자가 오탈자를 잡고, 3번 주자가 번역하는 직렬 방식.
2. 팬아웃 · 팬인 (부채 펼치고 접기): 1개의 주제를 여러 에이전트에게 동시에 뿌려서 조사하게 한 뒤(팬아웃), 마지막에 한 명의 에이전트가 결과를 하나로 합치는(팬인) 병렬 방식.
3. 전문가 풀 (안내 데스크): 입구에서 질문을 듣고 영어 질문은 영어 선생님에게, 수학 질문은 수학 선생님에게 연결해 주는 방식.
4. 생성-검증 (숙제 검사): 작성자가 글을 만들어오면 검사관이 확인하고, "불합격"이면 다시 고쳐오게 만드는 반복 피드백 방식.
5. 감독자 (현장 지휘관): 상황을 실시간으로 보면서 "이번엔 네가 가봐", "다음은 저쪽이야"라고 그때그때 일감을 나눠주는 방식.
6. 계층적 위임 (회사 조직도): 부장 $\rightarrow$ 과장 $\rightarrow$ 사원처럼 위에서 아래로 세부적인 일을 쪼개어 내려보내는 방식.

팬아웃(Fan-out)과 팬인(Fan-in)의 저울질(트레이드오프)

부채를 쫙 펼치듯 여러 명에게 동시에 일을 시키면 순서대로 할 때보다 끝나는 시간(속도)은 엄청나게 빨라집니다.

하지만 얻는 것이 있으면 반드시 잃는 것도 있습니다.

• 3명을 동시에 부르면 컴퓨터 자원과 요금(토큰)도 3배로 한 번에 나갑니다.
• 3명 중 2명은 1초 만에 끝났는데 1명이 인터넷 오류로 멈추면, 결국 그 1명을 기다리느라 전체 결과 합치기(팬인)가 지연됩니다.
  따라서 무조건 병렬로 돌리기보다는 "서로 기다릴 필요가 없는 독립된 조사 작업"에만 팬아웃을 쓰는 것이 현명합니다.

Chapter 09. 실행 모드: 심부름꾼 vs 동아리 팀 vs 하이브리드

• 서브에이전트 (심부름꾼): 메인 에이전트가 중심을 잡고 "너 계산기 좀 두드려와", "너 날씨 좀 검색해 와" 하고 간단한 잔심부름을 시킨 뒤 결과를 바로 뺏어오는 구조.
• 에이전트 팀 (동아리 조원): 기획자, 디자이너, 개발자가 동등한 위치에서 서로 의견을 주고받으며 하나의 결과물을 깎아 나가는 협동 구조.
• 하이브리드 (혼합형): 큰 단계(기획 $\rightarrow$ 제작 $\rightarrow$ 검토)는 팀으로 움직이되, 각 단계 안에서 생기는 단순 검색은 심부름꾼을 시키는 가장 실무적인 구조.

내 작업에 어떤 방식이 어울릴지 헷갈린다면, 고민할 필요 없이 제미나이에게 "내 작업 내용을 이 3가지 방식으로 돌렸을 때 속도와 비용, 결과 품질이 어떻게 다를지 가상으로 표를 그려서 비교해 줘"라고 요청하면 최적의 답을 미리 찾아줍니다.

Chapter 10. 하네스 등록, 감사(Audit), 지속적 진화

배포 전 5가지 함정 검사하기 (안티패턴 감사)

시스템을 완성했다고 바로 쓰면 안 됩니다. 마치 비행기를 띄우기 전에 점검표를 확인하듯 아래 5가지를 꼭 확인해야 합니다.

1. 혼자 다 하려는 욕심 (중앙 허브): 반장이 모든 데이터를 직접 고치며 병목을 만들고 있지는 않은가?
2. 반장의 아는 척 (라우터 하이재킹): 전문가를 부르지 않고 반장이 직접 답변해 버리는 구멍이 있는가?
3. 끝없는 핑퐁 (무한 루프): 검토자와 작성자가 끝없이 "다시 해와"를 외치다 요금이 폭발하지 않도록 "최대 3회" 제한을 걸었는가?
4. 연장 주머니 과적 (도구 과적): 한 에이전트 손에 도구를 10개 넘게 쥐여주어 헷갈리게 만들지 않았는가?
5. 비상구 없음 (블랙박스 에이전트): 에이전트 하나가 고장 났을 때 전체 시스템이 멈추지 않고 사람 바구니(manual-queue)로 넘어가게 했는가?

기계의 장부(batches.json)를 사람이 손으로 고치면 안 되는 이유

시스템이 여러 작업을 돌릴 때 어디까지 끝났는지 적어두는 메모장을 batches.json 같은 상태 파일이라고 부릅니다.

작업이 조금 늦어진다고 사람이 답답해서 이 메모장 글자를 직접 키보드로 수정해 버리면, "AI가 기억하는 현재 상태"와 "사람이 바꾼 실제 상태"의 싱크가 깨져버립니다. AI는 영문도 모른 채 이미 끝난 숙제를 다시 하거나 시스템 전체가 멈춰버리는 락(Lock)에 걸리므로, 상태 파일은 반드시 기계 시스템의 자동 루틴을 통해서만 변경되도록 두어야 합니다.

Fork 프로그램(GUI)을 사용하면 복잡한 터미널 명령어 없이 클릭과 드래그 앤 드롭만으로 원본 저장소(upstream)의 변경 사항을 가져와 깔끔하게 커밋 히스토리를 정렬(Rebase)할 수 있습니다.

1단계: 원본 저장소(Upstream) Remote 등록하기 (최초 1회)

내 Fork 원격 저장소(origin) 외에 오픈소스/프로젝트 원본 저장소를 Fork 앱에 등록합니다.

1. Fork 상단 메뉴에서 Repository ➔ Add Remote... 를 클릭합니다.

(또는 좌측 사이드바의 Remotes 항목 우클릭 ➔ Add New Remote...)
2. 설정 창에서 다음 항목을 입력합니다:

• Name: upstream
• Repository URL: 가져올 원본 저장소 Git URL

3. Add 버튼을 누릅니다.

(좌측 사이드바 Remotes 아래에 origin과 upstream이 나란히 표시되면 성공입니다.)

2단계: 최신 코드 패치(Fetch) 및 리베이스(Rebase) 진행

1. 최신 커밋 가져오기 (Fetch)

• 상단 툴바의 Fetch 아이콘을 클릭합니다.
• Fetch from: 항목에서 upstream을 선택(또는 All Remotes 체크)하고 Fetch를 누릅니다.

2. 작업할 로컬 브랜치 체크아웃

• 좌측 사이드바 Branches에서 동기화할 내 로컬 브랜치(예: main)를 더블 클릭하여 체크아웃합니다.

3. Upstream 기준으로 Rebase 실행

• 좌측 사이드바의 Remotes ➔ upstream ➔ main 브랜치를 찾습니다.
• upstream/main을 우클릭한 뒤 Rebase 'main' on 'upstream/main' 을 클릭합니다.
• (가운데 커밋 그래프 화면에서 upstream/main 브랜치 태그를 우클릭해도 동일합니다.)*

💡 GUI에서의 Rebase 동작 방식
upstream의 최신 커밋들을 먼저 내 브랜치 밑으로 깔끔하게 배치한 후, 내가 로컬에서 작업한 커밋들을 그 위로 다시 쌓아 올립니다. 불필요한 "Merge branch..." 커밋이 남지 않아 그래프가 한 줄로 깨끗하게 유지됩니다.

3단계: 충돌(Conflict) 해결하기 (발생 시)

코드 충돌이 발생하면 Fork 상단에 Rebase in progress 알림 창이 뜨며 충돌 상태가 표시됩니다.

1. 좌측 Changes 탭으로 이동하면 충돌이 발생한 파일 목록이 빨간색 아이콘 등으로 표시됩니다.
2. 충돌 파일을 클릭한 후 Fork 내장 Merge Tool / Conflict Solver 창에서 유지할 코드를 선택(Resolve)하고 저장합니다.
3. 충돌 해결이 끝난 파일을 Stage 영역으로 올립니다.
4. 상단 알림 바의 Continue Rebase 버튼을 클릭하여 다음 단계를 진행합니다.

• (리베이스를 완전히 취소하고 이전 상태로 되돌리려면 상단 바의 Abort 버튼을 클릭합니다.)

4단계: 내 원격 저장소(Origin)로 강제 푸시(Force Push)하기

Rebase를 마치면 로컬 커밋의 해시값이 새로 갱신되므로 일반 푸시 시 오류가 발생합니다. 내 Fork 원격 저장소(origin)에 반영하기 위해 강제 푸시를 수행해야 합니다.

1. 상단 툴바에서 Push 아이콘을 클릭합니다.
2. 대상 저장소가 내 원격 저장소인 origin과 현재 브랜치(예: main)로 선택되어 있는지 확인합니다.
3. 창 하단의 Force Push 체크박스를 활성화합니다.

• (만약 체크박스가 비활성화되어 있다면, 체크박스 우측의 안내 문구를 클릭하거나 설정에서 안전 잠금을 해제해야 체크가 가능합니다.)

4. Push를 누르면 내 GitHub/GitLab Fork 저장소에 원본의 최신 변경 사항과 내 작업 내역이 한 줄로 깨끗하게 반영됩니다.

본 글은 하네스 엔지니어링 with 클로드 코드 기반으로 작성되었습니다. 해당 책을 같이 보시면 이해에 도움이 됩니다
https://product.kyobobook.co.kr/detail/S000220048885

Part 02. 하네스 구성하기: 에이전트 · 스킬 · 오케스트레이터의 책임 분리

Chapter 03. 3대 핵심 요소와 책임 분리

한 장의 종이에 모든 걸 적으면 생기는 일

학급 규칙을 정할 때 한 장의 종이에 "반장의 역할, 청소도구 사용법, 지각생 벌점 기준, 축제 준비 순서"를 빽빽하게 다 적어두면 어떻게 될까요? 청소당번이 자기 할 일을 찾으려다가 축제 준비 규칙을 읽고 헷갈려 엉뚱한 행동을 하게 됩니다.

AI도 마찬가지입니다. 프롬프트 하나에 페르소나(성격), 사용할 도구 목록, 전체 작업 순서를 한꺼번에 다 적어두면 AI의 머릿속이 복잡해져서 도구를 엉뚱한 곳에 쓰거나 거짓말(환각)을 하기 시작합니다. 그래서 우리는 일을 셋으로 엄격하게 쪼개야 합니다.

3대 핵심 요소의 명확한 역할

• 에이전트 (Agent - 사람): "나는 누구인가?"를 정합니다. 성격, 말투, 전문 분야, 그리고 절대 넘지 말아야 할 규칙을 담습니다.
• 스킬 (Skill - 도구): "어떤 연장을 쓸 수 있는가?"를 정합니다. 계산기, 인터넷 검색기, 사전처럼 필요할 때 손에 쥐여주는 도구 사용법입니다.
• 오케스트레이터 (Orchestrator - 진행자): "누가 언제 나설 차례인가?"를 정합니다. 1번 주자가 끝나면 2번 주자에게 신호를 주는 '신호등' 역할만 맡습니다.

Chapter 04. 에이전트(Agent) 정의와 가드레일

에이전트에게 명확한 신분증 만들어주기

에이전트를 만들 때는 "너는 똑똑한 조수야"라고 뭉뚱그려 말하면 안 됩니다. 학생증처럼 이름표와 맡은 과목을 정확히 적어주어야 합니다.

• 이름: 수학 채점관
• 목표: 풀이 과정에서 덧셈/뺄셈 기호가 틀렸는지만 찾아낸다.

'절대 하지 말아야 할 일'을 먼저 정하기

에이전트가 똑똑하게 일하게 만드는 진짜 비결은 "무엇을 해라"보다 "이것만큼은 절대 하지 마라"를 정해두는 것입니다. 이를 가드레일(안전 울타리)이라고 부릅니다.

• "틀린 문제를 네가 직접 다시 풀어주지 마라." (채점만 할 것)
• "학생에게 친절한 위로의 말을 덧붙이지 마라." (결과만 건넬 것)

이런 금지선을 명확히 그어두지 않으면, 에이전트는 친절함을 발휘하려다 정작 중요한 채점 규칙을 어기게 됩니다.

Chapter 05. 스킬(Skill) 설계와 점진적 공개(Progressive Disclosure)

AI는 도구의 '이름'이 아니라 '설명'을 보고 고른다

필통 속에 여러 자루의 펜이 들어있을 때, 펜 뚜껑에 'Pen_01'이라고 적혀 있으면 어떤 펜을 써야 할지 알 수 없습니다. "이것은 빨간색 채점용 펜입니다"라는 설명표가 붙어 있어야 알맞게 집어 듭니다.

AI에게 도구를 줄 때도 마찬가지입니다. 도구 이름보다 "이 도구는 언제, 왜 써야 하는지"를 명확한 문장으로 적어주는 것(Description)이 핵심입니다.

도서관 책 찾기: 점진적 공개

도서관에 가서 책을 찾을 때 처음부터 10만 권의 책을 다 꺼내서 바닥에 펼쳐놓지 않습니다.

1. 먼저 컴퓨터 검색창(목차)에서 책이 어느 서가에 있는지 위치만 확인합니다.
2. 그 서가로 걸어가서 필요한 책 딱 1권만 꺼내 읽습니다.
3. 다 읽었으면 책을 제자리에 꽂아두고 빈손으로 나옵니다.

AI 시스템도 똑같습니다. 처음부터 수십 개의 도구 매뉴얼을 다 읽히지 않고, 목차만 보여주었다가 진짜 필요한 순간에만 도구 설명서를 쥐여주는 방식을 써야 머리가 복잡해지지 않고 요금도 절약됩니다.

Chapter 06. 오케스트레이터와 통신 프로토콜

반장은 모든 숙제를 대신 검사하는 사람이 아니다

팀 프로젝트를 할 때 제일 나쁜 반장은 모든 조원들의 숙제를 자기가 중간에서 일일이 받아 읽고, 수정해서 다음 친구에게 전달하는 반장입니다. 반장은 지쳐 쓰러지고, 중간에 전달을 잘못해서 숙제가 엉망이 됩니다.

훌륭한 오케스트레이터는 '신호등' 역할만 합니다.

• 글쓴이 AI가 초안을 다 썼으면, 오케스트레이터는 "초안 작성 완료 신호"만 확인합니다.
• 내용을 직접 읽어서 고치지 않고, "자, 이제 검토자 AI 차례야. 파일 확인해"라고 순서만 넘겨줍니다.

도저히 못 푸는 문제는 선생님 바구니(manual-queue)로

아무리 훌륭한 AI라도 사람이 보기에 애매하거나 위험한 3%의 예외 문제는 생기기 마련입니다.

이때 AI가 억지로 답을 지어내게 내버려두면 대형 사고가 납니다. AI가 처리할 수 있는 범위를 벗어났다면 즉시 "사람 확인 필요 바구니(manual-queue)"에 그 작업을 쏙 집어넣고 빠져야 합니다. 3%의 까다로운 문제는 사람이 직접 검토하게 분리하는 것이 전체 시스템을 가장 안전하게 지키는 방법입니다.

본 글은 하네스 엔지니어링 with 클로드 코드 기반으로 작성되었습니다. 해당 책을 같이 보시면 이해에 도움이 됩니다 

https://product.kyobobook.co.kr/detail/S000220048885

Part 01. 하네스란 무엇인가: 모델을 감싸는 안전장치

Chapter 01. 왜 하네스인가

AI 혼자 일하게 두면 생기는 일

최신 인공지능에게 복잡한 프로그래밍이나 문서 작성을 통째로 맡겨보면, 처음에는 막힘없이 글을 쓰는 것처럼 보입니다. 하지만 결과물을 자세히 뜯어보면 존재하지 않는 가짜 규칙을 지어내거나, 앞서 작성한 중요한 기준을 스스로 지워버리는 실수를 자주 저지릅니다.

가장 큰 문제는 AI가 자기가 만든 실수를 스스로 알아채지 못한다는 점입니다. 사람은 글을 쓰다가 이상하면 멈추고 다시 읽어보지만, 언어 모델은 그저 확률적으로 그럴듯한 다음 단어를 이어 붙일 뿐이기 때문입니다. 혼자 일하는 AI는 자신이 틀렸다는 사실조차 모른 채 엉뚱한 방향으로 계속 달려갑니다.

똑똑한 머리보다 중요한 것은 '일하는 틀'

제미나이는 책 수십 권 분량의 글을 한 번에 읽을 수 있을 만큼 방대한 기억 공간(컨텍스트 창)을 가지고 있습니다. 하지만 문제를 해결하지 못하는 진짜 이유는 지능이나 기억력이 부족해서가 아닙니다. 바로 일하는 구조가 잡혀있지 않기 때문입니다.

시험공부를 할 때 책상 위에 온갖 교과서와 참고서를 무작정 쌓아두면 집중력이 흐려지는 것과 같습니다. AI에게도 모든 정보를 한 번에 던져주기보다, "지금은 이 부분만 읽고, 정해진 순서대로 확인하라"는 명확한 작업 틀을 짜주어야 실수가 사라집니다. 병목은 모델의 머리가 아니라 구조에서 발생합니다.

하네스(Harness)란 무엇인가

말이나 강아지에게 씌우는 줄을 '하네스'라고 부릅니다. 힘이 센 동물이 제멋대로 뛰쳐나가지 않고 주인의 통제 안에서 안전하게 달릴 수 있도록 몸을 감싸는 안전장치입니다.

AI 시스템에서 말하는 하네스(Harness) 역시 똑같습니다. 인공지능 모델 자체의 성능을 억지로 뜯어고치는 것이 아니라, 모델 바깥에 '안전 펜스'를 쳐주는 것입니다.

• 에이전트가 절대로 넘어가면 안 되는 행동 경계선
• 입력받을 데이터와 출력할 답변의 정해진 양식
• 문제가 생겼을 때 스스로 작업을 멈추고 사람에게 보고하는 규칙

이처럼 모델의 주변(Around the Model)을 감싸서 규격을 강제하는 소프트웨어 장치를 하네스라고 부릅니다.

Chapter 02. 30분 Quick Start: 2인 팀 만들기

하네스가 있고 없고의 차이

"이 글을 보고 취약점을 찾아서 완벽하게 고쳐줘"라고 AI 한 명에게만 명령하면, AI는 그럴듯하게 글을 수정하지만 정작 핵심 취약점을 빠뜨리거나 문맥을 왜곡하기 쉽습니다.

하지만 하네스를 씌워 역할을 쪼개면 결과가 완전히 달라집니다.

• 하네스가 없을 때: 한 명이 글도 쓰고, 검토도 혼자 다 하다가 자기 실수를 놓침.
• 하네스가 있을 때: 글을 고치는 AI(작성자)와 규칙대로 고쳤는지 감시하는 AI(검토자)를 분리하고, 둘 사이에 "검토자가 승인하지 않으면 글을 끝낼 수 없다"는 규칙을 강제함.

마크다운으로 2인 팀 조립하기

복잡한 프로그래밍 코드를 짤 필요 없이, 마크다운 문서 두 장으로 간단한 2인 팀을 만들 수 있습니다.

• writer.md: 당신은 원고 작성자입니다. 주어진 지침에 따라 초안을 수정하십시오.
• reviewer.md: 당신은 깐깐한 교열자입니다. 원고 작성자가 사실관계를 왜곡했거나 문법을 틀렸는지 확인하고, 이상이 없을 때만 PASS를 외치십시오.

이렇게 둘을 마주 보게 세워두면 작성자가 실수하더라도 검토자가 즉시 브레이크를 밟아 실수를 바로잡습니다.

처음 팀을 만들 때 자주 하는 3가지 실수

1. 역할을 섞어버리는 실수: 검토자에게 "틀린 걸 찾아서 네가 직접 고쳐라"고 시키면 안 됩니다. 검토자는 문제점만 지적하고, 수정은 다시 작성자가 하도록 역할을 명확히 떼어놓아야 합니다.
2. 탈출 조건을 빼먹는 실수: 두 AI가 서로 "다시 고쳐와", "이렇게 고쳤어"를 끝없이 반복하면 요금이 폭증합니다. "최대 3번까지만 확인하고 안 되면 사람을 부른다"는 탈출 규칙을 반드시 적어야 합니다.
3. 한 번에 너무 많은 자료를 주는 실수: 처음부터 전체 규정집을 다 읽히면 AI가 길을 잃습니다. 지금 단계에 꼭 필요한 요약본만 쥐여주어야 합니다.

Google Cloud Console에서 OAuth 동의 화면의 브랜딩(앱 이름, 로고, 홈페이지 URL 등)을 설정하고 인증을 요청했을 때, 아래와 같은 반려 메시지가 나타나는 경우가 있습니다.

인증 상태: 브랜딩이 사용자에게 표시되고 있지 않습니다.
다음 문제를 해결한 후 다시 인증하세요.
이전 인증 시도에서 발견된 문제:
홈페이지 URL("https://your-domain.vercel.app/")의 웹사이트가 나에게 등록되어 있지 않습니다.

이 에러는 Google Cloud 계정이 해당 도메인의 실제 소유자인지 확인하지 못했을 때 발생합니다. Google Search Console 소유권 인증 과 Vercel 배포 보호 해제 를 통해 해당 문제를 완벽하게 해결하는 단계를 정리합니다.

1. 에러 발생 원인

Google은 피싱 및 명의 도용을 방지하기 위해 OAuth 동의 화면에 입력된 홈페이지 URL 및 개인정보처리방침 URL 도메인의 소유권을 Google Search Console을 통해 엄격히 검증 합니다.

• 동일 계정 미등록: Google Cloud Console에 로그인된 구글 계정이 Search Console에 해당 도메인의 소유자로 등록되어 있지 않음.
• Vercel 인증 차단: Vercel의 배포 보호(Deployment Protection) 기능이 켜져 있어 Google의 인증 확인 봇이 페이지에 접근하지 못해 인증이 실패함.

2. 해결 단계 가이드

[1단계] Vercel 배포 보호(Deployment Protection) 해제 (⭐ 필수)

Google Search Console에서 인증 파일을 검증할 때 Vercel 로그인 창이 뜨면 봇이 파일을 읽지 못해 인증이 무조건 실패합니다. 인증 전 보호를 먼저 비활성화해야 합니다.

1. Vercel 대시보드 에 접속합니다.
2. 프로젝트 우측의 ... (점 3개) 클릭 ➔ View project settings 를 클릭합니다.
3. 좌측 메뉴에서 Deployment Protection (또는 Security)으로 이동합니다.
4. Vercel Authentication (또는 Password Protection) 항목을 Disabled (비활성화) 로 변경 후 Save 를 클릭합니다.

[2단계] Google Search Console에서 도메인 소유권 인증

Google Cloud Console을 사용하는 동일한 구글 계정 으로 Google Search Console에 접속해 소유권을 등록합니다.

1. Google Search Console 에 접속합니다.
2. 속성 추가 화면에서 URL 접두사 방식을 선택하고 내 서비스 URL(예: https://your-domain.vercel.app/)을 입력합니다.
3. 소유권 확인 방법 중 HTML 파일 업로드 를 선택하고 제공되는 google[인증코드].html 파일을 다운로드합니다.
4. Next.js 프로젝트의 public/ 디렉토리에 해당 HTML 파일을 추가합니다:
   ```text
   my-project/
   ├── public/
   │ └── google[인증코드].html <-- 여기에 위치
   └── ...