AI 코딩 안전벨트 · Claude Code에 설치
AI랑 과속해도,
안전벨트는 hi-vibe가.
Claude Code로 Python 프로젝트를 만드는
입문자·1인 개발자를 위한 안전벨트예요.
어려운 명령어 외울 필요 없이 평소처럼 개발하면 돼요.
Python 3.8+ 프로젝트에 최적화핵심 훅은 외부 패키지 0기존 설정 안 덮어써요
설치하기 전에
이런 불편을 겪고 있다면
hi-vibe는 Claude Code로 개발할 때 자주 빠뜨리는 확인과 기록을 작업 흐름 안에서 자동으로 챙겨줍니다.
Python 프로젝트와 Claude Code 중심의 개인 개발 흐름에 맞춰 만들었어요. 짧은 실습이나 이미 리뷰·문서 자동화가 갖춰진 팀에서는 효과가 작을 수 있어요.
설치 전 미리보기
내 프로젝트에서는 무엇을 도와줄까요?
프로젝트 링크를 넣고 질문을 복사해 보세요.
AI가 hi-vibe의 실제 구현과 내 프로젝트 코드를 함께 살펴보고, 어떤 기능이 도움이 될지 구체적으로 알려줍니다.
내 프로젝트로 확인하기
공개 GitHub 저장소라면 실제 코드까지 확인해, 내 프로젝트의 어느 자리에서 무엇이 도움이 될지 파일 단위로 짚어줘요.
- 내 프로젝트 GitHub 링크를 넣어요
- 오른쪽 질문을 복사해요 — 넣은 링크가 질문 안에 자동으로 들어가요
- 쓰고 있는 AI에 붙여넣어요 — Claude·ChatGPT 아무거나 괜찮아요
https://github.com/jx-hxxx/hi-vibe
hi-vibe의 실제 구현과 아래 프로젝트의 코드를 확인하고,
이 프로젝트에서 hi-vibe를 어떻게 활용하면 좋을지 알려주세요.
제 프로젝트:
[내 프로젝트 GitHub 링크]
다음을 실제 파일이나 코드 사례와 함께 살펴봐 주세요.
1. 기존 구현 탐색과 중복 작업 방지가 도움이 될 부분
2. 구현 후 리뷰가 오류나 누락을 발견할 수 있는 부분
3. 세션 간 작업 맥락과 트러블슈팅 기록 관리가 특히 도움이 될 부분
4. 중복 코드·안 쓰는 코드·비밀키 등 전체 점검이 유용할 부분
5. 기존 테스트·lint·CI·문서와 함께 적용하는 방법
비슷한 파일이 있다는 이유만으로 기능이 같다고 단정하지 말고,
실제 동작을 확인할 수 없다면 확인 불가라고 밝혀 주세요.
마지막에는 다음만 간단히 정리해 주세요.
- 가장 도움이 될 지점 3가지
- 관련된 실제 파일
- 설치한다면 권장하는 첫 사용 순서
이런 실수, 막아줘요
AI에게 코딩을 맡기면 이런 일이 자주 생겨요.
빠르게 만들 수 있지만, 프로젝트가 커질수록 작은 실수가 조용히 쌓여요.
어떻게 막나 · 세 겹으로
말이 아니라 구조로 막아요.
안전벨트를 세 겹으로 짜요.
위는 부드럽게 챙겨주고, 아래로 갈수록 기계가 확실히 막아요.
기억을 대신 적어둬요
무슨 프로젝트인지, 어디까지 했는지, 뭐가 바뀌었는지를 자동으로 적어둬요. 그래서 대화가 새로 시작돼도 이어갈 단서가 남아 있어요.
AI한테 규칙을 심어요
“만들기 전에 있는지 먼저 찾아봐”, “에러는 원인부터 봐”, “확인 안 한 건 단정하지 마” 같은 규칙을 AI한테 미리 심어서, 스스로 지키게 해요.
기계가 직접 막아요
코드를 자동으로 검사하는 도구가 위험한 코드를 그 자리에서 잡아요. 원하면 GitHub에 올릴 때 아예 통과 못 하게 막을 수도 있어요.
기능 하나하나
설치하면, 프로젝트에 이런 게 생겨요.
추상적인 "좋아져요"가 아니라, 실제로 만들어지고 봐주는 것들이에요.
핵심은 문서를 한 파일에 몰아넣지 않고 역할별로 나눠 둔다는 거예요. 코드를 바꾸면 리뷰가 어떤 문서를 고쳐야 하는지 같이 확인해요.
/hi-vibe:init은 가볍게 시작하고, 나머지 문서는 필요할 때 알아서 생겨요CLAUDE.md코드만 봐서는 모를 것 — 개요·제약·함정·결정 이유·실행 명령. 폴더 목록은 안 넣어요(ls로 1초면 보이고 금방 낡으니까) (init 때)handover.md세션 인수인계 — 다음 대화가 이어갈 단서를 남겨요(최근 요청·수정 파일·Git·테스트 상태). 대화 정리(compact) 직전 ·/clear· 창을 닫을 때 자동 기록돼요 (init 때)api/MODULE.md그 폴더의 상세 설계·데이터·주의점 — 폴더가 복잡해질 때 생겨요 (폴더마다 하나씩)CHANGELOG.md트러블슈팅 기록 — 뭐가 언제 왜 바뀌었나. 버그를 고쳤으면 증상과 원인까지 남겨요("고쳤다"만 있으면 나중에 소용없으니까). (init 때)evidence/METRICS.md정량 성과 근거 — 비교 가능한 전후 수치가 생겼을 때만 측정 명령·환경·표본·원본 결과와 함께 만들어요
새 함수·파일을 만들기 전에 "이미 있는지" 먼저 찾아봐요. AI가 세션마다 있던 걸 또 만드는 걸 막죠. 없을 땐 "스캔한 N개 파일에서 못 찾았어요"라고 범위까지 밝혀요.
에러를 fallback으로 덮는 대신 원인부터 보게 해요. 몰래 삼키는 코드(빈 catch, except: pass)를 쓰는 순간 감지해요. 의도한 거면 주석 한 줄로 통과.
"아마 이럴 거예요"를 사실처럼 말하지 않게 해요. 수치·API는 확인하고 답하거나, 못 하면 "추정입니다"라고 밝혀요. (context7 연결 시 최신 문서까지 조회)
코드를 짠 기억이 전혀 없는 딴 클로드가 편견 없이 봐요. 고치다 만 데를 먼저 봐요 — 한 파일을 고쳤는데 그걸 가리키는 다른 파일이 안 따라간 것 같은 거요. 과잉설계·불필요한 기능도 짚어주고요. 안 쳐도 돼요 — 리뷰 안 받은 변경이 남아 있으면 훅이 대화를 붙잡고 리뷰를 시켜요.
대화가 정리(compact)될 때마다 진행상황을 자동 기록하고, 새 대화엔 최근 인수인계를 다시 넣어줘요. "예전에 왜 이렇게 했지?" 하면 날짜·이유까지 답해요.
hook은 방해 안 하려고 조용히 실패하게 설계돼서, 망가져도 에러조차 안 떠요. 이제 hook이 돌 때마다 흔적을 남기고, 그게 낡으면 알려줘요. 세워둔 CI가 연속 실패 중일 때도 세션 첫머리에 짚어주고요.
"90% 비슷하게 또 만든" 함수·안 쓰는 코드·너무 큰 파일, 하다 만 것(에러 삼킴·TODO·테스트 없는 모듈)까지 짚어줘요. 후보를 그냥 던지지 않고 딴 클로드가 열어봐 "12건 중 진짜 3건"으로 줄여줘요.
gate면 로컬에 검사기(ruff·eslint·타입·순환의존)를 설치해 빨간 줄로 표시. GitHub에 올리는 프로젝트면 push마다 검문도 같이 제안해요 — 리모트가 있는지 보고 알아서 판단해요.
"안 쓰는 코드"라고 잘못 짚는 걸 막아요. 프레임워크가 이름 없이 부르는 함수·테스트·export default·만드는 중인 코드를 죽은 코드로 오해하지 않게 인덱스로 관리해요.
무엇이 보장되나
여기까진 기계가.
여기서부턴 AI가.
”전부 자동!”이라고 뭉뚱그리지 않아요. 기계가 확실히 하는 것과 AI가 알아서 하는 것을 나눠서 보여줘요.
왼쪽은 설치하면 늘 돌아가고, 오른쪽은 Claude가 판단해서 해요.
기계가 확실히 하는 것
- 대표적인 위험 패턴(숨는 에러·비밀키) 경고Claude가 Write/Edit로 코드 쓸 때
- 대화가 사라지기 전에 진행상황 저장자동 정리·/compact 직전 · /clear · 창 닫을 때
- 새로 시작할 때 규칙 다시 챙겨주기새 대화 시작할 때
- 아무도 안 본 코드 변경이 있으면 대화를 붙잡고 리뷰를 시키기대화가 끝나려 할 때 · 리뷰 수행은 Claude가
- 리뷰를 끝냈다는데 딴 클로드는 안 불렀으면 다시 붙잡기대화 기록을 훅이 직접 세요 · 파일 2개 이상일 때
AI가 알아서 하는 것
- “만들어줘” 하면 이미 있는지 먼저 찾기새로 만들기 전
- “다 했어” 하면 점검하고 문서도 맞추기다 만든 후
- 돌아온 리뷰 결과를 읽고 뭘 고칠지 판단하기훅이 턴을 막고 리뷰를 지시한 뒤
- “고쳐줘” 하면 대충 덮지 말고 근본 원인부터버그·에러 고칠 때
/hi-vibe:check 하나면 돼요 — 저장소 전체를 훑어 놓친 걸 모아 보여줍니다.init 한 번이면 훅 6종이 자동으로 돌아요. Claude가 Write/Edit로 코드를 쓸 때마다 에러 삼킴·비밀키를 잡고, 아무도 안 본 변경이 있으면 대화를 붙잡고 review를 시켜요. “커밋해줘”라고 하면 커밋 직전에 코드를 짠 기억이 없는 딴 클로드가 아직 커밋 안 한 변경을 설계 관점으로 한 번 봐요. compact 직전, /clear, 창을 닫고 나갈 때 handover에 이어갈 단서를 남기고, 새 세션이 열리면 그걸 다시 읽혀요. (건질 게 없는 세션엔 아무것도 안 써요.) 그리고 코드만이 아니라 AI가 쓴 답도 봐요 — "이 파일은 이렇게 동작해요"라고 설명하면서 정작 그 파일을 안 열었으면 대화를 붙잡고 열어 보게 해요. 기억으로 지어낸 설명은 확인한 설명과 똑같이 확신에 차서 나오거든요. 자동으로 매여 있고, 풀리면 알려주는 안전벨트.review는 “다 했어” 한마디에도 걸리고, 건너뛰면 1단의 훅이 붙잡아요. 나머지는 AI가 놓치면 안 걸리니, 확실히 하고 싶을 때만 직접 치면 돼요. 잔소리하는 코치.check 하나예요(궁금할 때마다 몇 번이든). gate는 복잡도·돌고 도는 의존성까지 잡는 검사라 제일 많이 걸러내지만, 프로젝트 설정 파일에 손을 대니 준비됐을 때 한 번만 돌리면 돼요(필수 아님).명령어 한눈에
대부분 자동. 필요할 때만 직접.
자동은 평소처럼 말하면 알아서 걸리고,
직접은 설치·점검처럼 내가 필요할 때 눌러요.
# 목록에 등록 /plugin marketplace add jx-hxxx/hi-vibe # 설치하고 지금 켜기 /plugin install hi-vibe@hi-vibe-marketplace /reload-plugins
# 이 프로젝트에 켜고, 제대로 도는지 확인 (프로젝트 당 1회성) /hi-vibe:init /hi-vibe:doctor # 코드 검사기 + CI까지 설치 (선택 - 프로젝트 당 1회성) /hi-vibe:gate
init은 프로젝트마다./plugin install은 유저 스코프(전역)라 한 번 설치하면 모든 프로젝트에서 /hi-vibe: 명령어를 써요(재설치 X).하지만 자동 기능(훅)은 쓸 프로젝트마다 최상위 폴더에서 /hi-vibe:init을 해야 켜져요. .hi-vibe/가 있는 폴더에서만 돌아요.init 안 한 다른 프로젝트엔 전혀 개입하지 않아요. 전역 설치인데도 원하지 않는 곳에서 훅이 도는 걸 막는 안전장치예요.(새 프로젝트에서 쓰려면 그 폴더에서 /hi-vibe:init 한 번.)| 명령어 | 언제 쓰나 | 발동 |
|---|---|---|
/hi-vibe:welcome | 처음이라 뭐부터 할지 모를 때 | 직접 |
/hi-vibe:init | 프로젝트마다 1회, 켜기 | 직접 |
/hi-vibe:doctor | init 직후, 제대로 도는지 확인 | 직접 |
/hi-vibe:gate | 코드 자동 검사기 설치 (프로젝트마다 1회 → 자동) | 직접 |
/hi-vibe:check | 중복·안 쓰는 코드·큰 파일 + 하다 만 것(에러 삼킴·TODO·테스트 없는 모듈) — 딴 클로드가 후보를 열어봐 오탐을 걸러줘요 | 직접 |
/hi-vibe:find | “이 기능 만들어줘” 할 때 (있는지 먼저 검색) | 자동 |
/hi-vibe:review | 리뷰 안 받은 변경이 있으면 훅이 대화를 붙잡고 Claude에게 리뷰를 시켜요 (범위·깊이·병렬은 알아서 정하고, 딴 클로드가 다시 봐요) | 자동 |
/hi-vibe:handover | 대화가 정리(compact)되기 직전, /clear, 창을 닫을 때 — 다음 세션이 이어갈 단서 기록 | 자동 |
/hi-vibe:log | 코드가 바뀐 걸 CHANGELOG(변경 이력)에 남기기 | 자동 |
/hi-vibe:recall | “예전에 왜 이렇게 했지?” | 자동 |
상황별 빠른 시작 — 그래서 뭘 치면 돼요?
설명 다 안 읽어도 돼요. 지금 내 상황을 찾으세요. 실제로 치는 건 세팅할 때 셋, 평소엔 하나예요.
/hi-vibe:init → /hi-vibe:doctor (이 프로젝트에 켜기 → 제대로 도는지 확인)init → doctor → check (지금까지 쌓인 코드를 통째로 스캔하고, 딴 클로드가 후보를 하나씩 열어봐요 — 강력 추천)/hi-vibe:find)review를 시켜요./hi-vibe:check (스캔 후 딴 클로드가 후보를 열어보고 진짜만 골라줘요)/hi-vibe:gate (프로젝트마다 1회 · GitHub에 올리는 프로젝트면 push마다 자동 검문도 제안)/hi-vibe:welcome이 프로젝트에서 빼고 싶다면
들어올 때보다 나갈 때가 쉬워야 한다고 봐요. 빼는 전용 명령어는 만들지 않았어요 — 외울 게 하나 더 늘 뿐이라서요.
touch .hi-vibe/optout · 훅만 조용해지고 명령어는 그대로 써요rm -rf .hi-vibe .repo-xray (init 안 한 상태로 돌아가요)/plugin uninstall hi-vibe@hi-vibe-marketplace (모든 프로젝트에서 사라져요)CLAUDE.md·handover.md·CHANGELOG.md·evidence/METRICS.md는 전부 여러분의 파일이에요. 필요 없으면 직접 지우시면 돼요더 자세히 — 헷갈리기 쉬운 것들 (펼쳐 보기)
review가 알아서 정하는 것들
check vs review — 헷갈리기 쉬운데 완전 달라요
check는 기계(스캐너)가 저장소 구조를 훑고, 그 후보를 딴 클로드(proof-eyes)가 열어봐 진짜인지 가려요 — 중복 코드·안 쓰는 코드·너무 큰 파일. 사실 확인이에요.의심하는 대상이 스캐너라 증거가 필요해요.review는 서브에이전트(fresh-eyes)가 방금 바꾼 코드를 설계 관점으로 봐 “잘 만들었는지”를 판단해요 — 절반만 끝난 변경·과잉설계·더 단순한 길. 의견·판단이에요.의심하는 대상이 코드라 의도가 필요해요.한 줄로: check = 뭐가 있는지(사실), review = 잘 만들었는지(판단). 겹치는 게 아니라 서로 보완이에요.check와 gate는 리듬이 반대예요
check는 내가 돌리는 진단 — 구조가 궁금할 때마다 몇 번이든 반복해요.gate는 프로젝트마다 한 번 깔면 끝인 관문 — 설치는 1회, 이후 push마다 GitHub이 자동 검문(다시 칠 필요 없어요).Claude Code 기본 기능이랑 겹치지 않나요?
/init(CLAUDE.md 생성) · auto memory(기억) · /code-review(리뷰라는 목적) · /verify(실행 검증) · /doctor(이름만 같고 검사 대상은 달라요)hi-vibe만 하는 것 — 에러를 조용히 넘기는 코드·비밀키 바로 잡기 · 프로젝트 전체에서 중복 코드와 안 쓰는 코드 찾기 · 무엇이 왜 문제였는지까지 남는 CHANGELOG · 프로젝트별 opt-in차이 하나 — 언제 도느냐.Claude Code 공식 문서에 이렇게 적혀 있어요 — “/verify와 /code-review는 직접 부를 때만 돕니다. v2.1.215 전에는 Claude가 알아서 돌리기도 했습니다.” 알아서 돌던 게 없어진 자리예요. hi-vibe는 기능을 다 만들면 리뷰를 거치기 전엔 대화가 안 끝나요. 이미 리뷰한 코드는 다시 보고 검사하지 않아요.차이 둘 — 누가 보느냐.리뷰는 두 겹이고, 서는 자리가 달라요. 턴이 끝날 때 체크리스트가 빠뜨린 것을 훑어요 — 에러를 조용히 넘겼는지, 실제로 돌려는 봤는지, 문서는 고쳤는지. 찾으면 그 자리에서 고치고 다시 검사해요. 그리고 커밋 직전에 코드를 짠 기억이 없는 딴 클로드(fresh-eyes)를 새로 불러 잘 만들었는지를 봐요 — 고치다 만 데는 없나, 과하게 만들지 않았나, 더 단순한 길은 없나.기본 /code-review를 대신 눌러주는 게 아니에요. hi-vibe가 직접 만든 에이전트예요. 같은 대화를 이어온 Claude는 자기가 쓴 코드를 제대로 의심하지 않거든요.막는 데까지가 hi-vibe가 하는 일이고, 코드를 읽고 판단하는 건 Claude가 해요.뒤에서 뭐가 도나 — 스킬(엔진) ↔ 명령어(버튼)
쉬운 명령어는 버튼일 뿐, 실제 일은 뒤의 스킬(엔진)이 해요.
같은 엔진을 명령어로도, "평소 말"로도, AI가 알아서도 불러요.
| 스킬 (엔진) | 이걸로 불러요 | 하는 일 |
|---|---|---|
repo-xray | check | 구조 스캔 — 중복·죽은 코드·큰 파일 |
write-gate | find · review | 코드 작성 전·후 게이트 |
docs-keeper | handover · log · evidence · recall · init · welcome | 문서·측정 근거 자동화 + 첫 안내 |
guards-setup | gate | 린트·CI 관문 설치 |
grounded-answers | (자동) “얼마야 · 지원돼?” 등 | 확인 안 하고 단정하는 것 방지 |
root-cause-first | (자동) 버그·에러 고칠 때 | 땜빵 대신 근본 원인 |
user-invocable: false).숨겼다고 안 도는 건 아니에요 — Claude는 알아서 불러요.같은 엔진(repo-xray)을 부르는 길은 둘이에요 — ① check 명령어 · ② “중복 찾아줘”라고 말하기hi-vibe: 접두사는 “이 플러그인 소속”이라는 이름표예요.doctor는 스킬 없이 훅·스캐너를 직접 돌려요.업데이트 기록은 CHANGELOG에서 자동으로 가져와요.
”설명이 안 낡게 해줍니다”를 말로만 하지 않아요. 아래 업데이트 목록은 hi-vibe가 스스로 관리하는 CHANGELOG에서 자동으로 만들어져요 —
릴리스할 때마다 손으로 옮겨 적지 않아요. 자동인 건 이 목록이고, 페이지의 나머지는 손으로 써요.
git add -A && git commit 한 줄이었어요. 훅은 그 줄이 실행되기 전에 끼어들어 "무엇이 커밋되나"를 보는데, 파일을 올리는 일이 바로 그 줄 안에 있으니 그 시점엔 올라간 파일이 하나도 없습니다. 게이트는 "커밋할 코드가 없네"로 읽고 조용히 통과시켰어요 — 훅이 죽은 게 아니라 헛다리를 짚은 겁니다. 그래서 "올라간 파일"이 아니라 "아직 커밋 안 된 변경 전부"를 보도록 고쳤습니다. 대가도 밝혀 둡니다: 문서 한 줄만 커밋해도 작업하다 만 코드가 남아 있으면 걸립니다. 억울할 땐 "그냥 커밋해"라고 하면 지나가요(같은 커밋은 두 번 막지 않습니다). 자가진단(doctor)도 일부러 stage하지 않은 상태로 검사하도록 바꿨습니다 — 예전 검사는 이 구멍을 그대로 통과시켰거든요./clear로 세션을 끊어도 이어갈 맥락을 제대로 넘겨줍니다. 컨텍스트를 아끼려 /clear를 자주 쓰면 그때마다 handover 기록이 다음 세션의 유일한 단서가 되는데, 지금까지 /clear 직후에는 그 기록의 앞 4줄만 들어갔습니다. 그 4줄은 제목·빈 줄·Git·첫 항목이라 정작 이어받는 데 필요한 줄이 잘려 나갔고, "다음 세션에서 다듬어 주세요"라고 적어둔 뼈대를 다듬으라는 지시도 없었습니다. 이제 /clear는 compact과 같은 대우를 받습니다 — 최신 항목 전량과 다듬기 지시가 함께 들어갑니다. 그리고 훅이 턴을 막을 때 나오던 설명이 짧아졌습니다. 차단 사유는 모델에게 가는 지시이면서 동시에 화면에 그대로 찍히는 글인데, 리뷰 절차를 통째로 옮겨 적어 매번 화면을 덮고 있었습니다. 절차의 유일본은 스킬에 두고, 사유에는 무엇이 걸렸는지·어떻게 멈추는지만 남겼습니다.* 이 목록은 릴리스마다 CHANGELOG에서 자동으로 생성돼요. (scripts/build-showcase.py + GitHub Actions)