비개발자가 하네스 엔지니어링을 학습하는 방법 — Claude Code로 인터랙티브 리더 만들기

현재 3명이서 서비스를 만들고 있습니다. 두 레포를 단일 모노레포로 합치는 큰 리팩토링이 예정되어 있었고, 그 전에 "하네스" 를 먼저 잘 설계해야 했는데요. 호기롭게 하네스를 챙겨보겠다고 했지만… 막상 해보니 비개발자가 하네스를 살뜰히 챙기기엔 단어 자체가 벽이었어요.

그래서 제가 학습하기 위한 도구를 따로 만들었습니다. 아티클만 제대로 읽어도 하네스 엔지니어링의 기초를 잡고 좋은 팁들을 얻을 수 있었기에, 읽고 인사이트를 적는 식으로 접근했어요.

우당탕탕 모노레포 대작전

저는 AI 콘텐츠/ 실습 두 프로젝트를 운영 중인데, 두 레포의 기술 스택이 거의 다 달라요.

이 둘을 단일 모노레포로 합칠 예정이었고, "합친 후에 3명이 같은 환경에서 충돌 없이 일하려면 하네스가 먼저"라는 게 핵심이었어요. 그래서 "제가 미리 확인해볼게요!" 했어요( ^^ 겁도없지)

"통합 CLAUDE.md를 어떻게 짤지", ".claude/ 디렉토리 트리는 어떻게 나눌지", "hook은 어디까지 강제할지" 같은 결정 7개와 산출물 5개를 정리한 문서요. 만들 때는 Claude한테 "이거 뭐야?" 물어가며 하나하나 합의했어요.

그런데 며칠 뒤 다시 펼쳐 읽으니 단어 자체가 벽이었어요.

"하네스(harness)"가 정확히 뭐지? 코드 위에 뭘 씌운다는 건데, 어떤 층이지?
"Turborepo"랑 "pnpm workspaces"는 뭐가 다르지? 우리는 어느 쪽으로 가는 거지?
"git subtree"로 합치면 history가 보존된다는데, 왜 중요하지?
"Skill / Agent / Slash command / Hook"의 차이가 헷갈림 — 어디서부터가 누구의 영역?

만들 때는 알아들은 줄 알았는데, 한 번 듣고 끝난 개념은 또 까먹어요. 다음 회의 때 또 같은 단어 앞에서 멈춰서야 할 처지였죠. 그래서 결심했어요. 이 문서를 제가 반복 학습할 수 있는 도구로 바꿔보자고요.

1단계 — 내가 가진 자산부터 끌어모으기

가장 먼저 떠올린 건 제가 관리하는 콕집이 DB였어요. 하루에도 수백개의 콘텐츠가 수집되는데
쌓인 수천개의 콘텐츠 중 "하네스" 관련만 골라보면 어떨까?

Claude한테 이렇게 요청했어요.

docs/handover-monorepo-harness-2026-04-30.md 읽고 관련된 콘텐츠를 수집해줘

Claude가 한 일:

• 핸드오프 문서 580줄을 읽고 핵심 토픽 10개를 추출 (모노레포 / Claude Code 하네스 / hooks / 빌드 검증 / Linear / Drizzle DB / 디자인 시스템 / git history / SRP 코드 품질)

• 토픽별 키워드 그룹으로 콕집이 DB(ops_kokjibi.contents)에 SQL 검색

• 총 48건 매칭 중 산출물 기준으로 큐레이션한 22건 정리

기특한 콕집이 .. 잘만든 contents admin은 선생님 못지않다 싶었습니다.

2단계 — 빈 영역은 외부 리서치로 보강

22건을 살펴보니 콕집이에 거의 없던 4개 영역이 보였어요: Turborepo, Drizzle 마이그레이션 운영, Next.js 16, git subtree. 진우님이 합칠 때 진짜로 필요한 것들인데 비어 있었죠.

Claude가 한 일:

• WebSearch로 4개 영역 병렬 검색

• 권위 자료 선별: next-forge 공식 템플릿, Vercel Monorepos 공식 문서, Drizzle Custom Migrations 공식, Netlify multirepo→monorepo 가이드 등

• 11건 추가 → 총 33건

특히 Netlify 가이드에서 "squash하면 history 다 날아감"이라는 결정적 주의사항을 찾았는데, 이건 우리 핸드오프에 빠진 항목이라 바로 "v2에 추가" 표시를 해뒀어요.

ALT

한국사이트 스크린샷

3단계 — HTML 리더로 변환 (1차)

내가 얘네를 다 읽어볼 수 있게 html을 만들어줄 수 있어? 하네스관리에 도움이 되어야해

Claude가 만든 1차 리더:

• 좌측 사이드바에 섹션 TOC + 진행률 바

• 메인 영역에 카드 형식으로 33건 배치

• 카드마다 "왜 이 글?" 박스 (우리 결정과 어떻게 연결되는지 1줄)

• "하네스 적용 메모" textarea — 읽으면서 메모하면 localStorage에 자동 저장

• 메모 일괄 마크다운 복사 버튼

여기까지가 "읽기 도구"의 완성형이었어요. 그런데 진짜 전환점은 다음 단계였어요.

4단계 (전환점) — "읽고 끝"이면 의미가 없다는 깨달음

이걸 만들면서도 뭔가 부족한 느낌이었어요. 그래서 Claude한테 솔직히 물었어요.

이걸 더 디벨롭 시키고 내가 더 잘 이해하려면 어떤식으로 구성하는게 좋을 것 같아?$

Claude의 답이 정확했어요.

이 리더의 근본 문제는 "읽기"에 머무는 도구라는 것. 본인이 원하는 "하네스를 더 잘 이해"의 진짜 척도는 "읽었나"가 아니라 "이 핸드오프 문서를 갱신할 수 있나"가 되어야 함.

그리고 5가지 발전 방향을 제안했는데, 그 중 2개를 선택했어요:

② 카드마다 "우리 결정과 비교" 패널 추가 외부 글의 핵심 포인트를 우리 핸드오프 §X 결정과 직접 비교. ✓ 있음 / △ 약함 / ✗ 없음으로 표시.

④ 페이지 상단에 관계도 추가 외부 콘셉트 → 우리 결정 노드를 6개 축으로 그룹핑. 클릭하면 해당 카드로 점프.

이 두 가지가 들어가니까 도구의 성격이 완전히 바뀌었어요. "읽기 도구"가 "핸드오프 v2 작성 도구"가 된 거예요.

5단계 (의외의 결과) — "갭 Top 5" 자동 산출

비교 패널을 37개 카드 전부에 붙이고 보니, 자동으로 누적되는 데이터가 생겼어요. 각 카드의 "✗ 없음" 카운트요.

Claude가 알아서 "갭이 3개 이상인 영역"을 우선순위로 묶어줬는데, 보니까:

이게 진짜 핵심으로 떠올랐어요. 사람이 우선순위 잡는 것보다 도구가 자동 누적해주는 게 더 객관적이더라고요. "내일부터 핸드오프 v2에 뭘 추가할지"가 도구에서 자동으로 나오는 거예요.

원래는 비교 패널이 메인 기능이었는데, 의외로 "갭 Top 5"가 떠올랐어요. 만들기 전엔 예상 못 한 효과였습니다.

결과

가장 큰 변화는 "이해의 척도"가 바뀐 것이에요. "읽었나"에서 "실제 하네스 문서화에 도움이 되나?"로요. 같은 시간을 써도 머리에 남는 게 달랐어요.

AI 활용 팁!

• "외부 글 ↔ 우리 결정" 매핑이 핵심이에요. 외부 글을 그냥 모으기만 하면 결국 안 읽혀요. 카드마다 "우리 §X와 어떻게 연결되는지" 1줄이 있어야 학습이 됩니다.

• 갭(✗) 자동 집계가 v2 우선순위를 만들어줘요. 각 카드의 "없음" 체크를 누적하면 도구가 알아서 "무엇부터 추가할지" 알려줘요. 사람이 우선순위 잡는 것보다 빠릅니다.

• 그냥 읽기가 아니라 인터렉티브 리더를 구현한 것이 좋았어요!