하네스란 무엇인가
하네스(harness)는 원래 말이나 낙하산을 몸에 고정하는 '안전벨트·마구'를 뜻하는 영어 단어다. 소프트웨어에서는 뜻이 조금 옮겨와, AI 같은 도구가 정해진 틀 안에서 안정적으로 일하도록 미리 잡아두는 장치를 가리킨다. 바이브 코딩에서 하네스란, AI에게 매번 설명하지 않아도 되도록 프로젝트의 규칙·배경·내 요구사항을 파일로 적어두는 것을 말한다.
사람 신입에게 첫날 건네는 온보딩 문서를 떠올리면 쉽다. '우리 회사는 이런 곳이고, 이 폴더에는 이런 게 있고, 이건 하지 말라'를 문서로 정리해두면 신입이 매번 물어보지 않아도 된다. 하네스는 AI에게 주는 바로 그 온보딩 문서다. AI는 기억이 대화(세션)마다 초기화되기 때문에, 이 문서를 대화 시작마다 다시 읽어 '이 프로젝트가 뭔지 아는 상태'로 일을 시작한다.
왜 비개발자에게 하네스가 특히 필요한가
AI 코딩 도구는 기본적으로 상대가 개발자라고 가정하고 말한다. 학습한 자료 대부분이 개발자끼리 주고받은 문서·코드·질문답변이기 때문이다. 그래서 아무 설정 없이 쓰면, 비개발자에게도 '의존성', '환경 변수', '빌드', '배포 파이프라인' 같은 용어가 설명 없이 쏟아진다.
이때 흔한 오해가 '내가 못 알아듣는 건 내 실력이 부족해서'라는 생각이다. 아니다. AI는 상대가 누구인지 모르기 때문에 가장 무난한 기본값(개발자)으로 답할 뿐이다. 내가 누구인지 한 줄만 알려주면, 같은 AI가 전혀 다른 눈높이로 말하기 시작한다. 하네스는 이 '내가 누구인지'를 매번 말하지 않고 한 번에 고정해두는 방법이다.
CLAUDE.md·AGENTS.md는 무엇이고 어디에 만드나
CLAUDE.md와 AGENTS.md는 특별한 프로그램이 아니라 그냥 글자로 된 메모 파일이다. 확장자 .md는 '마크다운'이라는 형식인데, 서식 없는 보통 메모장 파일이라고 생각하면 된다. 특별한 편집기 없이 아무 텍스트 에디터로 열고 쓸 수 있다.
두는 위치가 중요하다. 이 파일은 반드시 '프로젝트 폴더의 맨 위(루트)'에 있어야 한다. 프로젝트 폴더란 지금 만들고 있는 결과물(웹사이트든 앱이든) 하나가 담긴 폴더를 말한다. 그 폴더를 열면 바로 보이는 위치에 CLAUDE.md 파일을 만든다.
만드는 법은 두 가지다. 첫째, 그냥 AI에게 말로 시키면 된다. Claude Code나 Cursor에서 'CLAUDE.md 파일을 만들고 거기에 내가 개발자가 아니라는 걸 적어줘'라고 하면 AI가 알아서 만들어준다. 둘째, 직접 만들려면 프로젝트 폴더 안에 파일 하나를 새로 만들고 이름을 정확히 CLAUDE.md로 저장하면 된다(대소문자까지 그대로).
비개발자가 가장 먼저 넣을 한 줄
파일을 만들었으면, 다른 건 몰라도 이 한 줄부터 넣는다.
나는 개발자가 아니다. 전문용어는 반드시 쉬운 말로 풀어서, 최대한 짧고 간결하게 설명하라.이 한 줄이 답변을 어떻게 바꾸나
이게 전부다. 이 한 문장이 매 대화의 첫머리에서 AI에게 '이 사람은 비개발자다'라고 알려주고, AI는 그 전제 위에서 답을 고른다. '환경 변수'라는 말을 쓰게 되면 '(프로그램에 넘겨주는 설정값)'처럼 괄호로 뜻을 풀어주고, 길게 늘어놓던 설명을 핵심만 남겨 짧게 답한다. 매번 '쉽게 설명해줘'라고 부탁할 필요도 없어진다.
한 줄에서 몇 줄로 — 실전 하네스 예시
익숙해지면 여기에 몇 줄을 더 얹어 AI를 내 방식에 더 맞출 수 있다. 여전히 한 문단을 넘지 않아도 충분하다.
나는 개발자가 아니다. 전문용어는 반드시 쉬운 말로 풀어서, 최대한 짧고 간결하게 설명하라.
- 코드를 고칠 때는, 무엇을 왜 바꾸는지 한국어로 먼저 한 줄 설명한 뒤 진행하라.
- 명령어를 실행하라고 안내할 때는, 어디에(어느 창에) 무엇을 붙여넣어야 하는지까지 알려달라.
- 위험하거나 되돌리기 어려운 작업(파일 삭제 등) 전에는 반드시 먼저 물어보라.CLAUDE.md와 AGENTS.md, 뭘 쓰나
각 줄은 결국 '내가 매번 반복해서 부탁하던 말'을 한 번 적어둔 것뿐이다. 하네스는 이렇게 대화하면서 불편했던 점을 한 줄씩 파일에 옮겨 담아 조금씩 키워가면 된다. 처음부터 완벽하게 쓰려 애쓸 필요는 없다.
그렇다면 CLAUDE.md와 AGENTS.md 중 뭘 써야 할까. 둘은 역할이 같다. 모두 'AI에게 주는 프로젝트 안내문'이다. 차이는 어떤 도구가 읽느냐다. CLAUDE.md는 이름 그대로 Claude(Claude Code)가 읽는 파일이고, AGENTS.md는 특정 회사에 매이지 않은 공용 표준이라 Cursor·Codex 같은 다른 AI 도구들도 함께 읽는다.
실무 팁 하나. 두 파일을 똑같이 두 벌 관리하면 번거로우니, 내용은 AGENTS.md 한 곳에 적고 CLAUDE.md는 그걸 가리키게 연결해두는 방식을 많이 쓴다. 하지만 처음이라면 그냥 CLAUDE.md 하나만 만들어도 충분하다. Claude Code를 쓴다면 CLAUDE.md, 여러 도구를 섞어 쓸 계획이면 AGENTS.md — 이 정도로 기억하면 된다.
이 한 줄이 아껴주는 것
별것 아닌 한 줄 같지만, 효과는 매 대화마다 복리로 쌓인다. 첫째, 매번 '쉽게 설명해줘'라고 다시 부탁하는 수고가 사라진다. 둘째, 설명이 짧아지니 읽는 시간이 줄고, 무슨 말인지 몰라 다시 되묻는 왕복도 준다. 셋째, 눈높이가 맞으니 잘못 이해한 채로 엉뚱한 걸 실행하는 실수가 줄어든다.
바이브 코딩을 잘한다는 것은 코드를 잘 짜는 게 아니라, AI가 나를 잘 돕도록 판을 깔아주는 일에 가깝다. 그리고 그 판의 첫 벽돌이 바로 '나는 개발자가 아니다'라는 한 줄이다. 거창한 준비 없이, 지금 만들고 있는 프로젝트 폴더에 CLAUDE.md 하나를 만들고 이 문장을 적는 것에서 시작하면 된다.