[Part 5] 시행착오와 해결 과정

시리즈 목차

문제 1: 과도한 문서 → 토큰 낭비

문제 상황

처음에는 하네스 문서를 최대한 상세하게 작성했다. “자세할수록 좋겠지”라고 생각했다.

에이전트 정의 파일 하나가 500줄이 넘어갔다. 모든 예외 케이스, 가능한 시나리오, 상세한 예시를 다 담으려 했다.

결과는 토큰 낭비였다. 에이전트가 작업을 시작할 때마다 수천 토큰을 문서 로딩에 소비했다. 정작 필요한 정보는 그 중 일부였는데.

해결 방법

Progressive Disclosure 원칙을 적용했다.

• 핵심 문서는 500줄 이하로 유지
• 상세 내용은 references/ 폴더로 분리
• 필요할 때만 참조 문서를 로드

Before:
agents/qa-agent.md (800줄, 모든 내용 포함)

After:
agents/qa-agent.md (200줄, 핵심만)
└── references/
    ├── test-patterns.md
    ├── coverage-rules.md
    └── report-templates.md

에이전트가 항상 읽는 문서는 가볍게, 상세 규칙은 필요할 때만 로드하도록 구조를 바꿨다.

문제 2: 역할 모호함 → 의도와 다른 동작

문제 상황

에이전트와 스킬의 역할을 명확히 구분하지 않았더니 이런 일이 생겼다.

나: "이 코드 린트 검사해줘"

기대: 빠르게 ESLint 실행하고 결과만 보여주기
실제: 전체 코드 리뷰를 시작하며 리팩토링까지 제안

나: "SEO 전략 수립해줘"

기대: 종합적인 SEO 분석과 전략 제안
실제: 메타 태그 몇 개만 확인하고 끝

작업 규모와 응답이 맞지 않았다.

해결 방법

CLAUDE.md에 역할 구분과 위임 규칙을 명시했다.

## 스킬과 에이전트의 역할 구분

- **스킬 = 도구**: 한 가지 명확한 작업을 수행
  - 예: `/lint-check` → ESLint 실행하고 결과 보고

- **에이전트 = 전문가**: 도메인 전체를 종합적으로 다룸
  - 예: `seo-specialist` → 분석 + 설계 + 구현 + 검증

## 에이전트 위임 필수 조건

| 요청 패턴 | 위임 대상 |
|-----------|-----------|
| "전반적으로 분석해줘" | 해당 도메인 에이전트 |
| "설계해줘" | ux-designer |
| "검사해줘", "확인해줘" | 해당 스킬 |

역할을 명시하니 요청의 규모에 맞는 응답이 돌아오기 시작했다.

아직도 가끔 의도와 다르게 동작하는 경우가 있다. 하지만 초기에 비하면 훨씬 적은 빈도로 발생하고, 대부분 의도대로 동작한다.

문제 3: 컨벤션 미비 → 코드 일관성 붕괴

문제 상황

컨벤션을 대략적으로만 정의하고 개발을 시작했다. “TypeScript strict 모드”, “Tailwind 사용” 정도만 적어뒀다.

결과는 코드 스타일이 뒤죽박죽이 됐다.

• 어떤 파일은 function 선언, 어떤 파일은 화살표 함수
• 어떤 컴포넌트는 인라인 스타일, 어떤 컴포넌트는 Tailwind만
• 비슷한 로직인데 파일마다 구현 방식이 다름

나중에 이걸 통일하느라 사후 수정 비용이 컸다.

해결 방법

컨벤션을 세부적으로 정의하고, 위반 시 즉시 수정하도록 했다.

# conventions/coding.md

## 함수 선언
- 모든 함수는 화살표 함수로 작성
- 예외 없음

## 스타일링
- 인라인 스타일 금지 (style 속성 사용 불가)
- Tailwind 유틸리티 클래스 우선
- Tailwind로 불가능한 경우만 <style> 블록 사용

## 타입
- any 사용 금지
- as 타입 단언 지양, 타입 가드 우선

그리고 즉시 수정 원칙을 적용했다.

나: "이 코드 왜 function 선언으로 작성했어?"

에이전트: "conventions/coding.md에 화살표 함수 규칙이 있는데,
이 케이스에서는 호이스팅이 필요해서..."

나: "호이스팅이 필요한 이유가 뭐야?"

에이전트: "확인해보니 구조를 바꾸면 호이스팅 없이도 가능합니다.
화살표 함수로 수정하겠습니다."

컨벤션을 어긴 이유를 확인하고, 타당하면 컨벤션에 예외를 추가하고, 타당하지 않으면 코드를 수정했다.

진행 중인 작업이 끝나면 일괄 수정도 진행했다. 새로 추가된 컨벤션이 기존 코드에도 적용되도록.

문제 4: 기능이 모호한 에이전트/스킬

문제 상황

처음에는 “나중에 필요할 것 같은” 에이전트와 스킬을 미리 많이 만들어뒀다. 생각나는 대로 추가했다.

문제는 실제로 사용하지 않는 것들이 많았다는 점이다. 그리고 비슷한 기능이 여러 곳에 분산되어 있어서 어떤 걸 써야 할지 헷갈렸다.

해결 방법

실제로 사용하면서 정리했다.

• 사용하지 않는 에이전트/스킬은 제거
• 비슷한 기능은 하나로 통합
• 새로운 기능이 필요하면 그때 추가

지금도 12개 에이전트와 9개 스킬이 많은 편인지 고민 중이다. 다음 프로젝트에서는 필요한 것만 명확히 정의하고 시작할 계획이다.

해결의 핵심: Why-First 원칙

모든 문제의 해결에 공통적으로 적용한 원칙이 있다. “왜”를 먼저 설명하는 것.

# BAD — 규칙만 나열
- 함수는 화살표 함수로 작성한다

# GOOD — 이유를 함께 설명
- 함수는 화살표 함수로 작성한다
  → this 바인딩 문제 방지, 코드 스타일 통일
  → 예외: 클래스 메서드는 일반 메서드 문법 사용

이유를 알면 에이전트가 엣지 케이스에서도 올바르게 판단할 수 있다. 규칙만 알면 기계적으로 따르다가 이상한 결과가 나온다.

아직 개선 중인 부분

모든 문제가 해결된 건 아니다. 지금도 개선 중인 부분들:

• 에이전트가 의도와 다른 스킬을 호출하는 경우

  • 빈도는 줄었지만 여전히 발생
  • description을 더 명확하게 다듬는 중

• 토큰 사용량 최적화

  • 어느 정도가 적정선인지 아직 감이 없음
  • 사용량 측정 도구가 있으면 좋겠음

• 에이전트/스킬 개수 적정화

  • 12개 에이전트가 많은 건지 적은 건지
  • 사용 빈도를 추적해서 정리할 예정

정리

시행착오는 불가피하다. 중요한 건 문제를 인식하고 하네스를 개선하는 것이다. 하네스는 한 번 만들고 끝이 아니라, 프로젝트와 함께 진화하는 문서다.