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

소개

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

(내용 입력)

진행 방법

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

클로드 코드, 헤르메스

결과와 배운 점

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

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

하네스(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. 보고"처럼 성격이 비슷한 단계를 하나로 합쳤다. 순서가 세밀하게 쪼개져 있다고 더 잘 지켜지는 게 아니라, 오히려 단계 수가 많으면 하나씩 빠뜨리기 쉬웠다.

결과

ALT

한국의 인구수를 보여주는 그래프

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

배운 것

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

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

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

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

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

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