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는 Python 프로젝트를 Claude Code로 개발하는 개인 개발자를 위한 플러그인입니다.
아래 프로젝트 저장소를 가능하면 실제 코드까지 확인하고, hi-vibe가 제 프로젝트의 개발 과정에 실질적으로 도움이 될지 분석해 주세요.
제 프로젝트:
[내 프로젝트 GitHub 링크]
README의 설명뿐만 아니라 hi-vibe의 실제 구현도 함께 살펴보고, 다음 내용을 평가해 주세요.
1. 기존 구현 탐색과 중복 작업 방지에 도움이 되는지
2. 기능 구현 후 자동 리뷰가 발견할 수 있는 문제
3. 세션 간 작업 맥락과 트러블슈팅 기록 관리의 활용도
4. 프로젝트 전체 점검 기능이 필요한 규모와 구조인지
5. 현재 사용 중인 도구나 작업 방식과 겹치는 부분
6. 이 프로젝트에서 기대할 수 있는 장점과 한계
가능하면 제 프로젝트의 실제 파일이나 코드에서 확인한 구체적인 사례를 들어 설명해 주세요. 직접 확인하지 못한 내용은 추측하지 말고 확인 불가라고 밝혀 주세요.
마지막에는 다음 내용을 간단히 정리해 주세요.
- 가장 유용할 것으로 예상되는 기능
- 활용도가 낮거나 필요하지 않은 기능
- 이 프로젝트에 설치를 추천하는지와 그 이유
이런 실수, 막아줘요
AI에게 코딩을 맡기면 이런 일이 자주 생겨요.
빠르게 만들 수 있지만, 프로젝트가 커질수록 작은 실수가 조용히 쌓여요.
어떻게 막나 · 세 겹으로
말이 아니라 구조로 막아요.
안전벨트를 세 겹으로 짜요.
위는 부드럽게 챙겨주고, 아래로 갈수록 기계가 확실히 막아요.
기억을 대신 적어둬요
무슨 프로젝트인지, 어디까지 했는지, 뭐가 바뀌었는지를 자동으로 적어둬요. 그래서 대화가 새로 시작돼도 이어갈 단서가 남아 있어요.
AI한테 규칙을 심어요
“만들기 전에 있는지 먼저 찾아봐”, “에러는 원인부터 봐”, “확인 안 한 건 단정하지 마” 같은 규칙을 AI한테 미리 심어서, 스스로 지키게 해요.
기계가 직접 막아요
코드를 자동으로 검사하는 도구가 위험한 코드를 그 자리에서 잡아요. 원하면 GitHub에 올릴 때 아예 통과 못 하게 막을 수도 있어요.
기능 하나하나
설치하면, 프로젝트에 이런 게 생겨요.
추상적인 "좋아져요"가 아니라, 실제로 만들어지고 봐주는 것들이에요.
핵심은 문서를 한 파일에 몰아넣지 않고 역할별로 나눠 둔다는 거예요. 코드를 바꾸면 리뷰가 어떤 문서를 고쳐야 하는지 같이 확인해요.
/hi-vibe:init은 가볍게 시작하고, 나머지 문서는 필요할 때 알아서 생겨요CLAUDE.md코드만 봐서는 모를 것 — 개요·제약·함정·결정 이유·실행 명령. 폴더 목록은 안 넣어요(ls로 1초면 보이고 금방 낡으니까) (init 때)handover.md세션 인수인계 — 다음 대화가 이어갈 단서를 남겨요(최근 요청·수정 파일·Git·테스트 상태). 대화 정리(compact) 직전 ·/clear· 창을 닫을 때 자동 기록돼요 (init 때)api/MODULE.md그 폴더의 상세 설계·데이터·주의점 — 폴더가 복잡해질 때 생겨요 (폴더마다 하나씩)CHANGELOG.md트러블슈팅 기록 — 뭐가 언제 왜 바뀌었나. 버그를 고쳤으면 증상과 원인까지 남겨요("고쳤다"만 있으면 나중에 소용없으니까). (init 때)
새 함수·파일을 만들기 전에 "이미 있는지" 먼저 찾아봐요. 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가
AI가 알아서 하는 것
- “만들어줘” 하면 이미 있는지 먼저 찾기새로 만들기 전
- “다 했어” 하면 점검하고 문서도 맞추기다 만든 후
- 돌아온 리뷰 결과를 읽고 뭘 고칠지 판단하기훅이 턴을 막고 리뷰를 지시한 뒤
- “고쳐줘” 하면 대충 덮지 말고 근본 원인부터버그·에러 고칠 때
코드를 훑어 버그를 찾아주는 도구가 아니라, AI가 대충 못 하게 만드는 안전벨트예요. 버그를 잡는 건 결국 Claude의 추론이고, hi-vibe는 그 추론을 빡세게 하도록 강제하는 규율·문서·기계 장치예요. "자동으로 다 잡아줘요"가 아니라 "안 하던 규율을 강제로 하게 만들어요" — 기대를 여기 맞추면 실망이 없어요.
AI가 깜빡할 수도 있어요. 그래서 평소에 치는 건
/hi-vibe:check 하나면 돼요 — 저장소 전체를 훑어서 놓친 걸 모아 보여줍니다.리뷰가 자동으로 걸리면 대화가 한 번 더 돌고, 코드를 짠 기억이 없는 딴 클로드까지 불러요. 그만큼 답이 늦어지고 토큰도 더 씁니다. 놓치는 것보다 낫다고 봐서 그렇게 만들었지만, 값을 치르는 건 맞아요. 급할 땐 “가볍게 봐줘”라고 하면 체크리스트만 돌아요.
init 한 번이면 훅 5종이 자동으로 돌아요. Claude가 Write/Edit로 코드를 쓸 때마다 에러 삼킴·비밀키를 잡고, 아무도 안 본 변경이 있으면 대화를 붙잡고 review를 시켜요. compact 직전, /clear, 창을 닫고 나갈 때 handover에 이어갈 단서를 남기고, 새 세션이 열리면 그걸 다시 읽혀요. (건질 게 없는 세션엔 아무것도 안 써요.) 자동으로 매여 있고, 풀리면 알려주는 안전벨트.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 | 새 프로젝트마다 한 번, 켜기 | 직접 |
/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더 자세히 — 헷갈리기 쉬운 것들 (펼쳐 보기)
review가 알아서 정하는 것들
깊이: 코드를 짠 기억이 없는 서브에이전트(fresh-eyes)가 편견 없는 눈으로 과잉설계·숨은 결합을 봐요. 늘 켜져 있어요 — 설계랄 게 없는 작은 변경일 때만 건너뛰고, 건너뛰면 그렇다고 말해줘요.
병렬: 변경이 크면 여러 리뷰어에게 나눠 맡겨요. 고르라고 묻지 않고, 그렇게 한다는 것과 토큰을 더 쓴다는 걸 알리고 진행해요.
가볍게 보고 싶으면 “가볍게 봐줘”, 범위를 좁히려면 “로그인 쪽만”처럼 말로 하면 돼요.
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 · recall · init · welcome | 문서 자동화 + 첫 안내 |
guards-setup | gate | 린트·CI 관문 설치 |
grounded-answers | (자동) “얼마야 · 지원돼?” 등 | 확인 안 하고 단정하는 것 방지 |
root-cause-first | (자동) 버그·에러 고칠 때 | 땜빵 대신 근본 원인 |
스킬 6개는 엔진이지 버튼이 아니라서 메뉴에서 숨겼어요(
user-invocable: false). 안 그러면 16개가 뜹니다.숨겼다고 안 도는 건 아니에요 — Claude는 알아서 불러요. 같은 엔진(repo-xray)을 부르는 길은 둘입니다: ①
check 명령어 · ② “중복 찾아줘”라고 말하기.hi-vibe: 접두사는 “이 플러그인 소속”이라는 이름표예요. doctor는 스킬 없이 훅·스캐너를 직접 돌립니다.업데이트 기록은 CHANGELOG에서 자동으로 가져와요.
”설명이 안 낡게 해줍니다”를 말로만 하지 않아요. 아래 업데이트 목록은 hi-vibe가 스스로 관리하는 CHANGELOG에서 자동으로 만들어져요 —
릴리스할 때마다 손으로 옮겨 적지 않습니다. 자동인 건 이 목록이고, 페이지의 나머지는 손으로 써요.
* 이 목록은 릴리스마다 CHANGELOG에서 자동으로 생성돼요. (scripts/build-showcase.py + GitHub Actions)