본문으로 건너뛰기

하네스 적용의 어려움과 덜어냄

Sss

2026.08.11

하네스 적용의 어려움과 덜어냄 본문 이미지

소개

하네스를 만든 다음 대화에서 실제로 그 규칙대로 작업을 시켜봤다. 잘 작동은 했는데, 만든 사람 입장에서 다시 읽어보니 같은 말이 여러 번 반복되고 있어서 줄일 수 있는 부분을 요청했습니다.

(내용 입력)

진행 방법

어떤 도구를 사용했고, 어떻게 활용하셨나요?

클로드 코드, 헤르메스

결과와 배운 점

지난 글에 이어서 하네스에 대한 적응기

세 번째 글까지 렌탈 시스템을 만들면서 겪은 버그와 시행착오가 꽤 쌓였다. "이거 또 설명해야 하나?" 싶은 게 반복되길래, 하네스를 만들어보기로 했다.

하네스(harness) — AI가 매번 같은 설명을 안 들어도, 미리 정해둔 규칙과 순서를 따라 알아서 일관되게 작업하게 만든 문서 구조.

public/rental/ 폴더 안에 파일 두 개를 만들었다:

  • AGENTS.md — 무엇을 지켜야 하는지 (규칙)

  • WORKFLOW.md — 어떤 순서로 진행하는지 (절차)

prompt()가 미리보기에서 막히는 것, 관리자/유저 권한 가드, 데이터 구조, 모바일 대응 체크리스트 — 지금까지 겪은 것들을 전부 정리해서 넣었다.

하네스를 만든 다음 대화에서 실제로 그 규칙대로 작업을 시켜봤다. 잘 작동은 했는데, 만든 사람 입장에서 다시 읽어보니 같은 말이 여러 번 반복되고 있었다.

구체적으로:

  1. WORKFLOW.md의 STEP 3(규칙 대조) 가 AGENTS.md의 내용을 통째로 다시 베껴 쓰고 있었다. prompt() 금지, 권한 가드, 마이그레이션 — 이미 AGENTS.md에 있는 내용을 그대로 또 나열.

  2. AGENTS.md 안에서도 중복이 있었다. "권한" 항목에서 관리자 가드를 문단으로 한 번 설명하고, 바로 밑에 체크리스트로 거의 같은 내용을 또 나열했다.

  3. 코드 예시 블록이 필요 이상으로 길었다. ❌ 이렇게 쓰지 않는다 / ✅ 이렇게 쓴다 두 줄이면 충분한데 앞뒤로 설명이 더 붙어 있었다.

결과: 규칙 문서 두 개 합쳐서 215줄, 10,581글자. 매번 이 두 파일을 읽고 작업을 시작해야 하는데, 그중 상당 부분이 "같은 말 다른 표현"이었다.


왜 이게 문제인가 — "길다 = 성능이 나쁘다"

Claude Code 같은 AI 도구는 작업을 시작할 때 관련 문서를 읽고 그 내용을 맥락(context)으로 기억한 채 움직인다. 이 맥락이 길어지면:

  • 매번 읽는 시간·비용이 늘어난다 — 중복된 문장도 똑같이 다 읽어야 한다

  • 핵심 규칙이 반복되는 문장들 사이에 묻힌다 — 정말 중요한 규칙과 부연 설명의 비중이 흐려진다

  • 관리가 어려워진다 — 규칙을 하나 바꾸면 두 곳(원본 + 중복된 곳)을 다 고쳐야 하고, 하나만 고치면 서로 다른 말을 하는 문서가 된다

그러니까 "하네스를 간결하게 만든다"는 건 단순히 "짧아서 좋다"가 아니라, AI가 규칙을 더 정확하고 빠르게 지킬 수 있게 만드는 작업이다.


실제로 어떻게 줄였나

1. 중복 삭제 — 같은 내용을 두 번 안 쓴다

WORKFLOW.md STEP 3에서 AGENTS.md 내용을 베껴 쓰던 부분을 지우고, 한 줄로 바꿨다:

2. **읽고 대조** — 관련 함수를 Read로 먼저 읽는다. AGENTS.md의 금지·권한·데이터 규칙과 대조한다.

"AGENTS.md를 보라"는 링크 하나면 충분한데, 굳이 내용을 복사해둘 필요가 없었다.

2. 문단 → 한 줄 요약

"관리자만 삭제할 수 있다"는 규칙을 예로 들면:

전 (문단 + 체크리스트 중복):

- `isAdmin()` — 현재 로그인한 사람이 관리자인지 체크하는 함수. 모든 삭제·수정 버튼에

이걸로 감싼다.

- 상품 삭제, 사이트·팀 삭제는 관리자만 가능.

- 유저가 기존 상품을 열면 읽기 전용(`pmRO` 플래그)으로 열린다.

- UI에서 버튼을 숨기는 것과 별개로, 함수 안에서도 가드를 꼭 넣는다.

새 기능을 만들 때 체크리스트:

- [ ] 이 기능은 관리자만? 유저도 가능?

- [ ] 버튼을 숨겼는가?

- [ ] 함수 진입점에도 권한 체크를 넣었는가?

후 (한 줄로):

- `isAdmin()` — 삭제·수정은 버튼과 함수 진입부 양쪽에 가드. 버튼만 숨기면 콘솔로 우회 가능.

- 유저가 기존 상품 열면 읽기 전용(`pmRO`) — 입력칸 readonly, 저장 버튼 없음.

"왜 그런지" 이유는 남기고, "무엇을 하라"는 반복만 지웠다. 이유가 있어야 애매한 상황에서 판단할 수 있기 때문에 이유는 끝까지 지우지 않았다.

3. 절차를 8단계 → 6단계로 병합

WORKFLOW.md의 "STEP 7. 테스트 데이터 정리"와 "STEP 8. 보고"처럼 성격이 비슷한 단계를 하나로 합쳤다. 순서가 세밀하게 쪼개져 있다고 더 잘 지켜지는 게 아니라, 오히려 단계 수가 많으면 하나씩 빠뜨리기 쉬웠다.


결과

AGENTS.md

WORKFLOW.md

합계

줄 수

129 → 34

86 → 12

215 → 46 (78% ↓)

글자 수

6,736 → 2,033

3,845 → 1,028

10,581 → 3,061 (71% ↓)

빠진 건 없다. prompt() 금지, 권한 이중 가드, 데이터 마이그레이션, 반응형 체크, 사례글 규칙 — 규칙 항목 수는 그대로다. 같은 말을 두 번 하던 부분, 없어도 되는 부연 설명만 걷어냈다.


배운 것

"많이 적었다"와 "잘 정리했다"는 다르다.

하네스를 처음 만들 때는 "빠뜨리면 안 되니까 최대한 자세히 적어야지"라는 마음으로 썼다. 근데 실제로 다시 읽어보니, 자세함이 아니라 같은 말의 반복이었다. 진짜 정보량은 안 늘어났는데 분량만 늘어난 것.

하네스도 유지보수가 필요하다.

한 번 만들고 끝이 아니라, 실제로 써보고 "이 부분은 겹치네", "이 예시는 너무 기네" 하고 다시 다듬는 과정이 필요하다는 걸 알았다. 코드에 리팩토링이 있듯, 규칙 문서에도 같은 게 필요하다.

AI에게 주는 문서도 "독자를 배려한 글쓰기"가 똑같이 적용된다.

사람이 읽는 문서를 간결하게 쓰라고 하는 이유(핵심이 묻히지 않게, 유지보수 쉽게)가 AI에게 주는 문서에도 그대로 적용된다는 게 흥미로웠다.

1

함께 이야기해요 1

로그인하고 댓글을 남겨 주세요

Giacomo 프로필 이미지
Giacomo2026.08.16

215줄·10,581자를 46줄·3,061자로 줄인 수치보다, 무엇을 지웠고 무엇을 남겼는지가 먼저 눈에 들어왔어요. WORKFLOW.md가 AGENTS.md의 금지·권한·데이터 규칙을 다시 베끼던 부분은 링크 한 줄로 바꾸고, 권한 가드에서는 ‘버튼만 숨기면 콘솔로 우회 가능’이라는 이유를 남겼죠. 분량을 줄이면서 판단 근거까지 깎지 않은 점이 좋았습니다.

규칙 항목 수를 그대로 둔 채 8단계를 6단계로 합친 과정도 설득력 있었어요. 규칙과 절차의 역할을 갈라 놓으니 한 규칙을 바꿀 때 두 문서가 서로 다른 말을 할 위험까지 함께 줄었습니다.

압축 뒤의 다음 최소 검증은 압축 전후에 같은 네 가지 작업을 맡겨 허용·차단 결과를 나란히 보는 회귀표로 잡을 수 있겠어요. prompt() 호출, 비관리자 삭제, 데이터 마이그레이션, 모바일 화면 점검처럼 본문에 남긴 규칙을 쓰면, 문서에서 빠진 항목이 없다는 확인과 실제 행동이 유지됐다는 확인을 구분할 수 있습니다.

하네스를 한 번 쓰고 봉인하지 않고, 실제 사용 뒤 중복을 찾아낸 태도가 인상 깊었습니다. 세부 규칙을 더 쌓지 않고 이유와 절차의 자리를 갈라 놓은 작업이 하네스를 읽히는 문서로 바꿔 놓았어요.

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기