어제 '바이브코딩 응급실' 카톡방 대화 내보내기를 받았다. 5월 중순 며칠간 오간 대화인데, 이미지 생성 이야기부터 시작해서 컨텍스트 관리, 클로드 장애 대응, API 재판매 경고, 맥미니 세팅까지 주제가 굴러갔다. 그중에서 유독 멈춰서 다시 읽은 부분이 있었다. 누군가 "md 파일 구조화와 분류가 바이브코딩의 70%"라고 한 말이다. 처음엔 과장이라고 생각했다. 그런데 OpenClaw로 에이전트를 돌리면서 겪은 걸 돌아보니, 부정할 수가 없었다.
하네스가 없으면 AI는 매번 첫날 출근한 사람이다
하네스 엔지니어링이라는 단어를 처음 들으면 어렵게 느껴진다. 나도 그랬다. 그런데 원래 뜻은 단순하다. 말이나 개를 부리는 가죽 끈이 harness다. AI가 엉뚱한 방향으로 가지 않게 방향을 잡아주는 장치, 그게 하네스다.
AI에게 기억이 없다는 건 이미 다 아는 사실이다. 세션 하나가 끝나면 초기화된다. 어제 Claude Code와 함께 어떤 프로젝트를 3시간 동안 만들었어도, 오늘 새 세션을 열면 그 AI는 그 프로젝트에 대해 아는 게 없다. 매번 첫날 출근한 사람인 셈이다. 그런데 이 첫날 출근한 사람에게 "어제 우리 여기까지 했거든, 이어서 해줘"라고 말로 설명하는 건 불가능하다. AI는 대화 맥락을 물리적으로 들고 있지 않기 때문이다.
그래서 파일 시스템을 외부 기억으로 쓴다. 이게 하네스의 핵심이다. CLAUDE.md에 전체 컨벤션과 기술 스택을 적어둔다. PLAN.md에 로드맵을, TODO.md에 완료와 미완료 체크리스트를 둔다. history 폴더에 각 기능별 구현 히스토리를 md로 쌓는다. 새 세션을 열 때는 이 파일들을 읽고 시작하게 한다. AI가 맥락을 "기억"하는 게 아니라 "읽고" 시작하는 것이다.
카톡 대화에서 누군가 컨텍스트 관리를 어떻게 하느냐고 물었다. 돌아온 답들은 놀라울 정도로 일관되었다. 큰 기획을 먼저 잡고, 세션을 step과 task 단위로 쪼개고, 완료 후에는 TODO와 history를 마크다운으로 남겨서 다음 세션으로 넘긴다. /compact를 쓰기도 하지만 맹신하면 안 된다는 지적도 있었다. 요약 과정에서 정보가 누락되기 때문이다. 결국 문서로 남기는 게 정답이었고, 그 문서가 곧 하네스다.
RAWDATA만 바꾸면 차트와 필터가 달라진다
내가 하네스 엔지니어링을 체감한 가장 인상적인 경험은, 하네스를 설계하고 나면 프로그램 자체를 수정할 필요가 없어진다는 거다. 이걸 이해하는 데 시간이 좀 걸렸다.
보통 코딩이라 하면, 로직을 바꾸고 싶을 때 코드를 수정한다. if문 조건을 바꾸거나, 함수 시그니처를 고치거나, 새 분기를 추가한다. 그런데 하네스 엔지니어링 패러다임에서는 다르게 접근한다. 하네스 자체는 그대로 둔다. 대신 하네스가 처리하는 RAWDATA를 분석해서 투입하는 방식을 바꾼다. 그러면 같은 하네스 구조 안에서 다른 결과가 나온다.
구체적으로 설명하겠다. 내가 만든 데이터 시각화 하네스가 있다. RAWDATA를 넣으면 차트가 생성되고, 필터가 자동으로 만들어진다. 여기서 핵심은 내가 프로그램을 수정하지 않는다는 거다. RAWDATA의 구조가 달라지면, 같은 하네스가 그 데이터를 분석해서 차트 형태도 바꾸고 필터 구성도 바꾼다. 데이터에 날짜 컬럼이 있으면 시계열 차트가 나오고, 카테고리 컬럼이 있으면 분류별 필터가 생성된다. 하네스는 하나지만 RAWDATA에 따라 출력이 변형되는 것이다.
이걸 처음 겪었을 때 좀 놀랐다. 코드를 하나도 안 고쳤는데 결과물이 달라졌으니까. 예전 같으면 데이터 형식이 바뀔 때마다 차트 렌더링 로직을 수정하고, 필터 조건을 추가하고, 새 케이스에 대한 분기를 만들었을 거다. 그런데 하네스 안에서는 RAWDATA가 바뀌면 AI가 그 데이터를 읽고 알아서 적절한 차트와 필터를 구성한다. 내 역할은 데이터를 던지는 것뿐이다.
이 경험에서 깨달은 건, 하네스를 잘 설계하면 "수정"이라는 개념 자체가 바뀐다는 거다. 코드를 뜯어고치는 게 아니라, 입력을 다르게 준다. 같은 구조 안에서 다른 결과를 이끌어낸다. 이게 사실상 프로그래밍 패러다임의 전환이다. 명령형 프로그래밍에서는 "이렇게 하라"고 단계를 지시한다. 하네스 엔지니어링에서는 "이런 결과가 나오는 환경"을 설계하고, 데이터를 흘려보낸다.
컨벤션을 나열하지 말고 레퍼런스를 명시하라
카톡 대화에서 가장 실용적인 팁 중 하나가 최수민님의 조언이었다. 프로젝트 컨벤션을 CLAUDE.md에 일일이 적는 것보다, 컨벤션이 잘 지켜진 레퍼런스 파일의 경로를 명시하는 게 더 효과적이라는 거다.
이건 프롬프트 엔지니어링의 기본 원칙과 연결된다. LLM은 긴 지시문보다 구체적인 예시에서 더 잘 학습한다. "코드는 이런 스타일로 작성해"라고 10줄로 적는 것보다, "이 파일(src/components/auth/LoginForm.tsx)의 스타일을 따라 해"라고 한 줄 적는 게 더 잘 듣는다. 에이전트가 그 파일을 읽고 패턴을 추론하기 때문이다.
내 OpenClaw 환경에도 비슷한 패턴이 있다. AGENTS.md에 오케스트레이션 규칙, MEMORY.md에 장기 기억, SOUL.md에 페르소나, USER.md에 내 성향이 정리되어 있다. 이 파일들이 각자 독립적으로 존재하는 게 아니라 서로를 참조한다. AGENTS.md는 study-clipper 스킬의 스크립트 경로를 명시하고, study-clipper는 MEMORY.md의 이메일 주소와 Notion DB ID를 참조한다. 이게 하네스의 구조적 특성이다. 개별 파일이 아니라 파일 간 참조 관계가 전체 시스템을 만든다.
juu라는 닉네임의 분이 프로젝트 컨벤션을 어디까지 명세하느냐고 물었다. 폴더 구조, Tanstack Query, React-hook-form 같은 핵심 라이브러리까지 코드 컨벤션을 적어놓는데 너무 긴가 싶더라는 거였다. 답은 "레퍼런스 파일 경로를 명시하라"였다. 그리고 한 발 더 나가서, 리팩토링이 끝난 후에 그 레퍼런스 파일 경로를 업데이트하라는 조언도 나왔다. AI가 이전 코드 스타일을 보고 따라 하는 걸 방지하기 위해서다.
다시 만드는 게 수정보다 빠르다
여기서 하나의 결론에 도달한다. 하네스를 잘 설계해두면, 수정하는 것보다 처음부터 다시 만드는 게 더 빠르다.
이건 직관에 반한다. 보통은 "고치는 게 빠르지"라고 생각한다. 그런데 바이브코딩에서는 반대다. AI가 코드를 생성하는 속도가 워낙 빠르니까, 기존 코드를 이해하고 수정하는 컨텍스트 비용보다, 하네스를 그대로 두고 RAWDATA만 새로 넣어서 처음부터 만드는 게 더 빠르다. 내가 겪은 일이다. 결과물이 마음에 안 들면 스크립트를 뜯어고치려고 들어가는 것보다, 입력을 다르게 해서 한 번에 다시 돌리는 게 더 빨랐다.
이게 가능한 이유는 하네스가 "재사용 가능한 구조"이기 때문이다. 차트 생성 하네스는 하나다. 숫자 데이터를 넣으면 막대 차트가, 시계열 데이터를 넣으면 선 차트가, 카테고리 데이터를 넣으면 필터가 자동으로 따라 나온다. 내가 하는 일은 RAWDATA를 준비해서 흘려보내는 것뿐이다. 하네스가 나머지를 처리한다. 결과가 마음에 안 들면? 스크립트를 수정하는 게 아니라, 입력 데이터의 구조를 조정하거나 하네스의 RAWDATA 분석 규칙을 다시 잡아준다. 코드 수정이 아니라 환경 조정이다.
카톡방의 '개발자'라는 닉네임을 쓰시는 분이 "md파일 구조화 시키고 분류시키는게 정짜 바이브코딩의 70%"라고 했다. 나는 여기에 한 가지를 더하고 싶다. 나머지 30%는 RAWDATA를 읽고 분석하는 능력이다. 하네스가 70%라고 해서 나머지가 중요하지 않다는 뜻이 아니다. 좋은 하네스도 있고, 그 하네스 위에 좋은 데이터를 흘려보내는 감각도 있다. 둘이 합쳐져야 진짜 바이브코딩이 완성된다.
그런데 하네스 엔지니어링에 정답이 있는 건 아니다. 카톡 대화에서도 gStack, Superpowers, ECC, OMC 같은 도구들이 언급되었다. 누군가는 하네스를 강제화하는 도구를 쓰고, 누군가는 손수 md 파일을 만든다. 중요한 건 도구가 아니라, AI가 일하는 환경을 의식적으로 설계하고 있다는 사실 자체다. 그 환경이 없으면 AI는 매번 첫날 출근한 사람이고, 그 환경이 있으면 AI는 두 번째 날 출근한 사람이 된다. 단 하루 차이지만, 생산성은 몇 배가 다르다.