평소엔 가볍게, 코딩할 땐 무겁게. 두 단으로 나눈 안전장치 하나면, AI를 마음 놓고 부릴 수 있습니다.
비개발자를 위한 하네스 안내서
평소 → 🪶 가볍게(전역) · 코딩 → 🛡️ 무겁게(프로젝트)
이 책자는 "하네스"라는 말을 처음 듣는 분을 위한 안내서입니다.
당신의 직책은 결정권자 — AI는 당신을 대신해 일하지만, 대신 결정하지는 않습니다.
목차
무엇을 담았나요
코딩을 몰라도 괜찮습니다. 앞에서부터 한 장씩 읽으면, "무슨 말을 하면 무슨 일이 일어나는지" 자연스럽게 익힐 수 있습니다.
01하네스가 뭔가요 — AI에게 채우는 안전벨트
02왜 두 단으로 나눴나 — 평소는 가볍게, 코딩은 무겁게
031단 · 전역 하네스 — 평소 쓰는 가벼운 결
042단 · 코딩 하네스 — 켜는 법과 작동 루프
05하네스의 네 가지 부품 — 쉽게 풀어보기
06이렇게 말하면 이렇게 됩니다 — 실제 대화
07초보가 피해야 할 실수
08노하우 · 한눈에 보는 흐름
💡 명령어를 외울 필요는 없습니다
이 책에는 /로 시작하는 명령어가 몇 개 나옵니다. 외우지 않아도 됩니다.
"이런 게 있구나" 정도만 알아두고, 평소엔 명령어 없이 그냥 말하듯 쓰면 됩니다.
2
CHAPTER 01
하네스가 뭔가요
"AI에게 일을 시키되, 사고는 못 치게 막아두는 틀" — 그것이 하네스입니다.
Claude Code는 AI에게 내 컴퓨터에서 실제 작업을 시키는 도구입니다. 웹브라우저에서 쓰는 Claude.ai와는 다릅니다.
챗봇이 아니라 "AI 직원"에 가깝습니다 — 내 폴더의 파일을 읽고, 고치고, 프로그램을 실제로 돌릴 수 있습니다.
힘이 센 만큼, 위험도 따라옵니다. 안전장치가 없으면 AI가 파일을 지우거나 엉뚱한 코드를 만들어도 막을 방법이 없습니다.
하네스(harness)란 바로 그 안전장치입니다. AI가 제멋대로 행동하지 않도록
규칙·안전장치·검증 루프를 묶어둔 틀입니다.
🦺 비유로 이해하기
하네스(harness)는 원래 등산가나 작업자가 몸에 차는 안전벨트·고리줄을 뜻합니다. 떨어지지 않게 잡아주는 장치죠.
AI에게도 똑같은 걸 채웁니다 — 일은 하되, 벼랑 밑으로 굴러떨어지지는 못하게.
두 도구의 차이를 표로 봅니다. (여기서 터미널은 글자로 명령을 주고받는 검은 창을 말합니다.)
구분
Claude.ai (웹)
Claude Code (터미널)
파일 수정
불가
가능
코드 실행
불가
가능
내 폴더 접근
불가
가능
대화 기억
대화가 끝나면 잊음
기억장치를 둘 수 있음(5장)
⚠️ 이건 꼭 기억하세요
AI가 뭔가를 만들었다고 하면, 반드시 직접 확인해야 합니다.
AI가 "완료했습니다"라고 해도 실제로 완료가 아닌 경우가 많습니다. (HC — 이 시스템을 실제로 운용하는 분 — 의 실전 경험)
3
CHAPTER 02
왜 두 단으로 나눴나
평소는 가볍게, 코딩은 무겁게 — 안전장치도 상황에 맞게 무게를 바꿉니다.
하네스를 항상 무겁게 두면 어떻게 될까요? 메모를 정리하거나 간단한 자동화를 시킬 때마다 거추장스러운 규칙이 따라붙습니다.
반대로 항상 가볍게 두면, 정작 코딩처럼 위험하고 복잡한 작업에서 안전장치가 모자랍니다.
그래서 HC는 하네스를 두 단(段)으로 나눴습니다. 2026년 5월 29일에 세운 운영 구조입니다.
1단 — 전역(가볍게): 어디서 작업하든 항상 켜져 있는, 가벼운 기본 장치.
2단 — 코딩 프로젝트(무겁게): 정식 코딩 프로젝트에서만 내가 직접 켜는 무거운 규율.
핵심은 무겁게 가는 건 내가 켤 때만이라는 것입니다.
평소에는 가볍게 두어 빠르고 저렴하게, 진짜 코딩할 때만 무겁게 켜서 꼼꼼하게.
🚗 비유로 이해하기
동네 마트에 갈 때와 고속도로를 달릴 때, 운전 태도가 다른 것과 같습니다. 평소엔 가볍게.
빠르고 위험한 길에 들어설 때만 안전벨트를 단단히 조이고 속도계를 주시합니다. 늘 똑같이 긴장할 필요는 없죠.
💡 토큰과 집중의 경제
AI는 처리하는 텍스트의 양(토큰)이 많을수록 비용이 늘고, 한꺼번에 너무 많은 규칙을 주면 일부를 무시하기 시작합니다.
그래서 평소엔 규칙을 가볍게 둡니다. 무거운 규율은 정작 필요한 코딩 프로젝트에만 몰아주는 게 더 싸고 더 정확합니다.
4
CHAPTER 03
1단 · 전역 하네스
어느 폴더에서 일하든 늘 켜져 있는 가벼운 기본 장치 — 따로 켤 필요 없이 항상 작동합니다.
1단은 어느 폴더에서 일하든 늘 켜져 있는 가벼운 기본 장치입니다. 세 가지가 핵심입니다.
① 메모리 연계 — 어제 한 일을 오늘도 기억한다
Claude Code는 기본적으로 한 번의 대화(세션)가 끝나면 기억을 잃습니다. 내일 다시 열면 오늘 한 일을 모릅니다.
1단 하네스는 새 세션을 열 때마다 전역 메모리 인덱스와 최근 대화 맥락을 자동으로 불러옵니다.
그래서 새 창을 열어도 "내가 이전에 무엇을 결정했는지, 왜 그렇게 했는지"를 AI가 이어받습니다.
②/learn — 모르는 개념을 쉽게 설명받기
/learn은 HC가 만들어 쓰는 개념 설명 스킬입니다. 작업 중 모르는 용어가 나오면 불러서 쉬운 말로 풀어달라고 할 수 있습니다.
평소엔 조용히 있다가, 부를 때만 작동합니다. (이 역시 HC 개인 스킬이라 여러분 컴퓨터엔 기본으로 있지 않습니다 — 만드는 법은 5장 ③에서 봅니다.)
/learn📘 개념 설명 · HC 개인 스킬 예시
비개발자 눈높이로 개념·용어를 쉽게 설명합니다.
성격호출할 때만 작동 (평소엔 끼어들지 않음)
③ 자가발전 — 쓸수록 똑똑해진다
AI가 대화 중 알게 된 것을 스스로 기억(auto-memory)에 쌓고, 주기적으로 그 기억들을 정리해 패턴으로 통합합니다.
쓰면 쓸수록 내 습관과 맥락에 맞춰 자라는 도구가 됩니다.
💡 1단의 성격 한 줄
1단은 "가볍게, 늘 켜져 있고, 부를 때만 거든다"입니다. 메모리로 맥락을 이어주고, 물어보면 설명해주고, 알아서 조금씩 똑똑해집니다.
코딩이 아닌 평소 작업은 여기까지면 충분합니다.
5
CHAPTER 04
2단 · 코딩 하네스
정식 코딩 프로젝트를 시작할 때, 그 프로젝트에서만 무거운 개발 규율을 켭니다. 이것이 2단입니다.
켜는 법 — /project-harness
📌 먼저 알아둘 것 — 이건 HC가 직접 만든 명령입니다
아래 /project-harness는 HC가 자기 컴퓨터에 만들어 둔 개인 스킬입니다. Claude Code를 막 설치한 분에게는 이 명령이 아직 없습니다 — 그대로 쳐도 아무 일도 일어나지 않습니다. "이런 걸 만들어 쓸 수 있구나"라는 사례로 보시고, 실제로 만드는 길은 뒤(5장 ③ 스킬)에서 안내합니다.
HC의 경우, 작업하려는 프로젝트 폴더 안에서 이 명령을 부르면 아래 절차가 한 번에 돌아갑니다.
/project-harness🛡️ 코딩 하네스 켜기 · HC 개인 스킬 예시
이 프로젝트에만 코딩용 안전장치·개발 규율을 일괄 설정합니다.
쓰는 곳정식 코딩 프로젝트 폴더 안 (볼트·단순 자동화에는 쓰지 않음)
이 명령어를 부르면, 안에서 다음 순서로 차근차근 진행됩니다.
📋 진행 순서
사전 확인 — 여기가 정말 코딩 프로젝트가 맞는지 먼저 확인합니다. 단순 메모 폴더라면 "여기는 하네스가 과한 곳입니다. 정말 켤까요?"라고 되묻습니다.
개발 방법론 켜기 — 그 프로젝트에서만 superpowers라는 개발 방법론을 켭니다. (조사 → 계획 → 실행 → 검수의 흐름을 담당합니다. 다른 폴더에는 영향을 주지 않습니다.)
프로젝트 가이드 + 학습모드 만들기 — 그 프로젝트 전용 안내 파일을 만들고, "사용자는 비개발자다 — 왜 그렇게 하는지 쉬운 비유로 설명하며 진행하라"는 학습모드 지침을 넣습니다.
(선택) 에이전트팀 제안 — 여러 전문 역할이 필요한 큰 프로젝트(예: 재고·회계·주문·리포트가 다 필요한 ERP)라면, 역할별 팀 뼈대를 만들자고 제안합니다. 강제하지는 않습니다.
마무리 보고 — 무엇을 켰는지 쉬운 한국어로 요약하고, "이제 만들고 싶은 걸 말해주세요"로 안내합니다.
💡 한 번 켜면 그 프로젝트에선 계속
한 번 켜두면, 다음부터 그 폴더에서 작업할 때는 자동으로 "계획 → 실행 → 검수" 흐름이 적용됩니다.
매번 다시 켤 필요가 없습니다. 그러면서도 다른 가벼운 작업에는 전혀 영향을 주지 않습니다.
6
CHAPTER 04
작동 루프 — 조사 → 계획 → 실행 → 검증
2단 하네스를 켜면 코딩이 이런 흐름으로 흘러갑니다. 성급히 코딩부터 하지 않는 것이 핵심입니다.
FIGURE 01 · 작동 루프 — 조사 → 계획(승인) → 실행 → 코드리뷰 → 마무리
이 흐름의 가장 중요한 길목은 계획 단계에서 내 승인을 받는 것입니다.
AI가 바로 손대지 않고 먼저 계획을 세워 보여주는 모드를 Plan Mode(계획 모드)라고 합니다.
예시 대화 — 계획 먼저 받기
계획 먼저 세워줘. 고객 주문 관리 앱을 만들고 싶어.
🤖 Claude: 계획을 세우기 전에 몇 가지 확인하겠습니다. 1. 주문을 어디서 받나요? (카카오톡, 전화, 웹사이트 등) 2. 몇 명이 사용하나요? 3. 기존에 쓰는 스프레드시트나 도구가 있나요?
(답을 주면 단계별 계획이 나옵니다) → "좋아, 시작해" → 그때 실제 작업 시작
🎓 실사용자의 말
"모든 첫 프롬프트는 항상 Plan Mode로 시작합니다. 바로 만들기로 넘어가는 대신 Claude가 먼저 계획을 세웁니다."
— Futurepedia (YouTube)
"계획 모드 없이 시작하면, Claude가 만들다 말고 이미 만든 걸 갈아엎게 됩니다."
— AI Master (YouTube)
언제 계획 모드를 써야 하나요? — 3단계 이상의 작업, 여러 파일을 동시에 수정하는 작업, 새로운 기능을 처음 만드는 경우, 복잡한 구조 변경.
✅ 사람이 할 일 — 마지막 검증
마지막 "마무리"는 사람의 몫입니다. AI가 "완료"라고 해도 그대로 믿지 말고 "실제로 동작하는지 테스트해줘"를 습관처럼 붙이세요.
결정권자는 끝까지 당신입니다.
7
CHAPTER 05
하네스의 네 가지 부품
하네스는 네 가지 부품으로 이루어집니다. 이름만 들으면 어렵지만, 하나씩 보면 단순합니다.
① CLAUDE.md — AI의 장기 기억
Claude가 항상 읽는 "규칙서"이자 "기억 저장소"입니다. 세션이 끝나도 사라지지 않는, AI의 장기 기억이죠.
위치
역할
~/.claude/CLAUDE.md (전역)
모든 프로젝트에 공통 적용
프로젝트폴더/CLAUDE.md (프로젝트)
해당 프로젝트에만 적용
둘 다 있으면 둘 다 읽고, 프로젝트 파일이 전역 파일보다 우선합니다.
⚠️ 짧게 유지하세요
"CLAUDE.md가 80줄을 초과하면 Claude가 일부를 무시합니다." — abhishekray07 (GitHub)
"CLAUDE.md 4,000토큰(약 3,000단어) 초과 시 준수율 30%로 하락. 65줄 템플릿이 준수율 약 80%." — HC 실전 경험
그래서 HC의 원칙은 전역은 최소화입니다. 무거운 규칙은 프로젝트별 CLAUDE.md나 스킬로 분리합니다.
② 훅(Hook) — 자동으로 강제되는 규칙
CLAUDE.md가 "제발 이렇게 해줘" 하는 부탁이라면, 훅은 "이건 물리적으로 불가능해" 하는 차단입니다.
특정 행동을 할 때 자동으로 실행되는 짧은 프로그램이죠.
🎓 전문가의 말
"CLAUDE.md는 개발자가 온보딩 때 한 번 읽고 대부분 잊어버리는 가이드처럼 작동합니다.
직접 프롬프트에 지시하는 것이 더 강하고, 린터나 훅은 그보다 더 강합니다."
— r/ClaudeAI (Reddit, 추천 412개를 받은 글)
HC는 현재 훅 4개를 실전에서 운용합니다.
훅
역할
guard-destructive.sh
rm -rf(모든 파일 삭제) 등 9가지 위험 명령어 차단
scan-secrets.sh
.env·SSH 개인키·클라우드 자격증명 등 민감 파일 접근 차단
inject-global-memory.sh
세션 시작 시 전역 메모리 인덱스 자동 주입
inject-chatvault-profile.sh
세션 시작 시 최근 대화 맥락 25줄 자동 주입
✅ 초보자도 최소 두 개는
1) 위험한 명령어 차단 훅, 2) 민감한 파일 접근 차단 훅. 이 둘이 없으면 AI가 실수로 중요한 파일을 지울 수 있습니다. 다는 법도 어렵지 않습니다 — Claude에게 "위험한 명령어(rm -rf 등)를 차단하는 훅과, .env 같은 민감 파일 접근을 막는 훅을 만들어줘"라고 부탁하면 됩니다.
8
CHAPTER 05
하네스의 네 가지 부품 (이어서)
③ 스킬(Skill) — 재사용하는 작업 템플릿
/명령어 형태로 부르는 재사용 가능한 작업 템플릿입니다. 앞에서 본 /project-harness도, /learn도 여기에 속합니다.
중요한 건, 스킬은 누구나 자기 필요에 맞게 만들어 쓰는 것이라는 점입니다 — 아래 표는 HC가 직접 만들어 쓰는 예시이고, 여러분 컴퓨터엔 기본으로 들어있지 않습니다. HC는 이렇게 만든 스킬을 15개 이상 운용 중입니다.
HC가 만들어 쓰는 스킬 예시 (기본 내장 아님)
기능
/new-project
폴더명 제안 → README·CLAUDE.md 자동 생성 → 첫 커밋
/project-harness
프로젝트용 안전장치 일괄 설정
/ontology-ask
지식그래프에서 관련 맥락 조회
/ytreport
YouTube 영상 요약 보고서 생성
만드는 법은 어렵지 않습니다 — Claude에게 "이런 작업을 자주 하니 스킬로 만들어줘"라고 부탁하면 됩니다. (반대로 6장에 나오는 /init·/help 같은 건 처음부터 들어있는 기본 명령어입니다.)
④ 서브에이전트 — 역할을 나눠 맡는 팀
하나의 AI가 다 하는 대신, 역할을 나눈 여러 전문 일꾼(에이전트)에게 일을 나눠 맡길 수 있습니다.
큰 프로젝트(예: 재고·회계·주문·리포트가 다 필요한 ERP)라면 역할별 팀 뼈대를 만들어 분담시킵니다.
2단 하네스를 켤 때 필요하면 제안되는 선택 부품입니다.
FIGURE 03 · 네 가지 부품(CLAUDE.md · 훅 · 스킬 · 서브에이전트)이 묶여 하나의 하네스가 된다
9
CHAPTER 06
이렇게 말하면 이렇게 됩니다
명령어를 외우는 것보다, "어떻게 말하면 좋은 결과가 나오는지"를 익히는 게 더 중요합니다.
예시 대화 — 요청은 구체적으로
🙆 좋은 요청: 고객 이름, 전화번호, 주문 내용을 저장하는 엑셀 파일을 만들어줘. 오늘 날짜가 자동으로 들어가고, 저장 버튼 하나로 추가되면 좋겠어.
🙅 나쁜 요청: 더 좋게 만들어줘
🎓 "'더 좋게 만들어줘'는 Claude에게 아무 정보도 주지 않습니다." — AI Master (YouTube)
대화 중 상황별로 쓰면 좋은 말들입니다.
상황
쓰면 좋은 말
작업 전 계획 요청
"먼저 계획을 세우고 내 승인 받은 다음에 시작해줘"
설명 요청
"이 파일이 무엇을 하는지 설명해줘, 수정은 하지 말고"
단계별 진행
"한 단계씩 진행하고 매번 확인을 받아줘"
실수 복구
"방금 전으로 되돌려줘, 수정하기 전 상태로"
비용 절약
"간단하게 설명해줘, 코드 예시는 최소화해서"
자주 쓰는 슬래시 명령어
외우지 않아도 됩니다 — 이런 게 있다는 정도만.
/init
현재 프로젝트 분석 → CLAUDE.md 자동 생성
/help
사용 가능한 명령어 목록 보기
/model [모델명]
AI 모델 변경 (예: /model sonnet)
/compact
긴 대화를 핵심만 남기고 압축 (비용 절약)
/clear
대화 기록 초기화 (새로 시작)
/cost
이번 세션 토큰 사용량·비용 확인
💡 모델 골라 쓰기
같은 Claude 안에서도 모델을 고를 수 있습니다. Opus는 가장 강력(설계·계획에 적합),
Sonnet은 균형(실제 구현에 적합), Haiku는 가장 빠르고 저렴(단순 반복에 적합).
실전 전략은 "계획은 Opus로, 구현은 Sonnet으로." (Futurepedia + AI Master, YouTube)
10
CHAPTER 07
초보가 피해야 할 실수
실제 커뮤니티(Reddit·YouTube)와 HC의 경험에서 수없이 반복된 실수들입니다. 핵심만 추렸습니다.
⚠️ 자주 나는 사고들
CLAUDE.md 없이 시작 — 세션마다 처음부터 설명하게 됩니다. → 새 프로젝트는 /init 먼저.
모호한 프롬프트 — "더 좋게 만들어줘"는 정보가 0입니다. → "배경색을 흰색에서 연한 파란색(#E8F4FD)으로"처럼 구체적으로.
계획 모드 건너뛰기 — 중간에 다 뜯어고치게 됩니다. → 복잡한 작업은 "계획 먼저".
AI의 "완료"를 무조건 믿기 — 실제로는 완료가 아닌 경우가 많습니다(HC 실전 경험). → 항상 직접 테스트.
안전장치 없이 삭제 허용 — 훅이 없으면 rm -rf가 실행될 수 있습니다. → 차단 훅 설정.
복잡한 전문가용 틀을 그대로 허용 — "React(전문 개발자용 조립 틀)를 모른다면 이 앱은 나중에 문제가 나도 못 고칩니다."(r/ClaudeAI, 추천 258개를 받은 글) → AI에게 "React 같은 복잡한 틀 말고 가장 기본 재료(HTML·CSS·JavaScript)로 만들어줘"라고 하세요.
한 번에 너무 많이 요청 — "작은 반복 변경이 한 번의 거대한 프롬프트보다 낫습니다."(@code_rams, X) → 단계를 나눠서.
✅ 같은 버그를 세 번 반복했다면
"같은 버그를 세 번 반복했다면 새 세션을 열고 문제를 깔끔하게 다시 설명하세요.
깨끗한 컨텍스트가 긴 것보다 거의 항상 낫습니다." — AI Master (YouTube)
그리고 실수가 났다면 CLAUDE.md에 기록하세요. "AI가 이런 실수를 했음, 앞으로 이렇게 하지 말 것"을 추가하면 같은 실수가 반복되지 않습니다.
11
CHAPTER 08
노하우 · 한눈에 보는 흐름
두 단을 한 그림으로 — 평소는 1단, 코딩할 때만 내가 켜는 2단.
두 단을 한 그림으로
FIGURE 02 · 두 단으로 나눈 하네스 — 1단(바깥, 늘 켜짐) 안에 /project-harness로 2단(안쪽)을 켠다
핵심 노하우 한 줌
평소는 가볍게, 코딩만 무겁게. 무거운 건 내가 켤 때만. 그래야 싸고 정확합니다.
계획에서 멈춰 승인을 받는다. AI가 바로 손대지 않게 하는 이 한 박자가 사고를 가장 많이 막습니다.
AI의 "완료"를 그대로 믿지 않는다. 마지막 검증은 사람의 몫. 결정권자는 당신입니다.
강제할 건 훅으로, 부탁할 건 CLAUDE.md로. HC의 원칙 하나 — "도구가 강제할 수 있는 것은 글로 쓰지 않는다."
80점으로 시작해 피드백으로 키운다. 완벽한 설정보다 "지금 쓸 수 있는 설정"이 먼저입니다.
🎓 마지막으로
파워유저도 처음엔 초보자였습니다. HC의 현재 세팅은 수개월의 실전 경험과 수많은 실수에서 나온 것입니다.
한 번에 다 갖추려 하지 마세요. 1단을 평소에 쓰고, 코딩할 일이 생기면 그때 /project-harness로 2단을 켜면 됩니다.
그거면 충분히 시작입니다.
2단 하네스 사용설명서 · 비개발자를 위한 하네스 안내서
집필: 데이터 · 검수: 소니 · 첫독자: 앨리스 · 편집: 베이맥스 · 발간 2026-06-21 · 개정 2026-07-03