Claude Code 하네스란?

Claude Code는 `~/.claude/CLAUDE.md`에 전역 지시사항을 작성할 수 있습니다. 저는 여기에 13개 역할의 오케스트레이터 시스템을 구축했으며, 내용은 아래와 같습니다.

- 기획, 아키텍처, UI/UX, 프론트엔드, 백엔드, DB, 인증/보안, AI, QA, 성능, 코드리뷰, 배포, 모니터링
- 각 역할에 맞는 에이전트와 스킬을 매핑
- 자동 파이프라인: 구현 → QA → 코드리뷰 → 배포 제안

하네스 적용 후 토큰 소모량의 증가

아이디어는 좋았지만, 문제가 있었습니다.
하네스 적용 후 토큰 소모가 체감될 정도로 빨라졌습니다. 원인을 분석해보니 다양한 강제 규칙이 생성되었습니다.

1. "필수/항상/모든" 등의 규칙이 생성되었습니다.

[필수] 구현 작업 시작 전:

- 병렬 독립 작업 → Skill('superpowers:dispatching-parallel-agents')
- 순차 의존 작업 → Skill('superpowers:subagent-driven-development')

자동 후속 단계 (항상 적용):

- 구현 완료 → QA → 코드 리뷰 → 배포 제안

결과적으로, "버튼 색깔 바꿔줘" 같은 간단한 요청에도 전체 파이프라인이 강제 발동되었습니다.

2. 에이전트 스폰 = 컨텍스트 곱셈

각 서브에이전트는 자체 컨텍스트 윈도우를 가집니다. 시스템 프롬프트가 복제되고, 각 에이전트가 스킬도 로드하여

사용자가 한 글자도 입력하기 전에 이미 시스템 프롬프트만으로 19,500개 이상의 토큰이 소모되고 있었습니다.

시나리오           에이전트 수    시스템 프롬프트 비용
─────────────────────────────────────────────────
간단한 버그 수정    3-4개        ~84,000 tokens
새 기능 구현       5+개         ~140,000 tokens

해결 

claude.md 파일의 "항상/필수/모든"을 제거하고, 작업 규모에 따라 Claude가 판단하게 변경했습니다.

BEFORE

당신은 프로젝트 매니저(오케스트레이터)입니다.
[필수] 구현 작업 시작 전 에이전트 스킬 호출
모든 구현 작업은 TDD로 진행
자동 후속 단계 (항상 적용)

AFTER

규모   기준                        처리 방식
──────────────────────────────────────────────────────────
소     단순 수정, Q&A              직접 처리 (에이전트 없이)
중     한 도메인 내 여러 변경       직접 우선, 필요 시 에이전트 1개
대     다중 도메인, 새 기능         plan 모드 → 에이전트 배치

13개의 역할 테이블은 유지하되, '에이전트 배치가 필요할 때만 참조'하는 룩업 테이블로 변경했습니다.
또한, 간단한 작업은 직접 처리하고, 복잡한 작업일 때만 에이전트를 배치합니다.

결과적으로, 시스템 프롬프트 토큰을 2900개의 사용에서 1,300개 사용으로 최적화 하였으며 약 55% 정도가 절약되었고
작업시간의 증가와 추가적인 토큰 소모가 방지되었습니다.

Hooks 설정

CLAUDE.md의 자동 파이프라인을 실제로 동작하게 할 hooks를 추가했습니다.

- SubagentStop: 서브에이전트 완료 시 규모 기반 파이프라인 reminder

이중 슬래시 버그

또한, 최적화 과정에서  Claude Code의 자체적인 버그도 발견할 수 있었습니다.

Claude Code가 Read 권한을 자동 추가할 때 경로에 `//`가 붙습니다

기대: Read(/Users/kanghyun/Desktop/project/**)
실제: Read(//Users/kanghyun/Desktop/project/**)

클로드코드의  v2.1.89버전에서 CHANGELOG에 관련 수정 기록이 있었습니다

> "Fixed `Edit(//path/**)` and `Read(//path/**)` allow rules to check the resolved symlink target"

하지만 이 수정은 기존 `//` 규칙을 체크하는 것이고 `//`가 생성되는 것을 방지한 게 아니었습니다.
이 문제는 현재 버전인v2.1.90에서도 계속 발생중입니다.

관련 내용을 찾아보니, GitHub에서 중복 이슈로 자동 닫힐 뻔했지만, 기존 이슈들은 Windows(WSL/Git Bash) 경로 문제였고 우리 이슈는 macOS에서 발생하는 별개의 버그였습니다.

따라서 위의 과정을 인식하고 추가적인 글을 claude Code의 git hub에 작성하였습니다.

- [#44106 - 등록한 이슈](https://github.com/anthropics/claude-code/issues/44106)

결과

항목               Before                    After
────────────────────────────────────────────────────────────────
CLAUDE.md          197줄, 2,900 tokens       91줄, 1,400 tokens
Hooks              없음                       2개 (파이프라인 자동화)
Claude Code 버그                              발견 → 이슈 등록

- CLAUDE.md의 파일이 197줄에서 91줄로 다이어트 하였으며, 2900개의 토큰 소모에서 1400개의 토큰 소모로 바뀌었습니다. (55% 감소)

- 작업 시간의 단축이 예상됩니다.

정리

- "항상, 필수, 모든" 등을 입력하면 하네스의 효과는 강력해지지만, 토큰의 소모가 배속화됩니다. AI 도구의 시스템 프롬프트는 짧으며 조건부여야 합니다.
- 에이전트 스폰은 비쌉니다. 각 에이전트마다 시스템 프롬프트가 복제되므로, 간단한 작업은 직접 처리가 훨씬 효율적입니다.
- 도구를 분석하다 보면 도구의 버그를 찾을 수 있게 되는 경험을 하였습니다. 오픈소스 기여의 시작점이 되었습니다.

지난 2월 2일, 멋쟁이사자처럼에서의 인턴에 지원하고 합격되었습니다. 선택한 업무는 OpenAI GPT를 연동한 AI 챗봇 서비스 구축입니다.

이때 저에게는 두 가지 선택지가 있었습니다.

1. 프론트엔드 중심: 이미 경험이 있어 익숙한 화면 구현에 집중하고, 백엔드는 최소한으로 처리한다.
2. 백엔드 중심: 낯설지만 데이터 설계와 API 서버 구축에 집중한다.

저는 고민 끝에 백엔드 프로젝트를 선택했습니다. 

백엔드 선택이유

프론트엔드 개발 경험이 있었기에 오히려 'API 생산자'의 관점이 절실히 필요했습니다.

'API 소비자'에서 'API 생산자'로

지금까지의 프로젝트에서는 백엔드 개발자가 만들어준 API 명세서를 보고 데이터를 화면에 구현습니다. 또한, 팀 프로젝트에서 백엔드의 역량 부족으로 구현에 한계가 있었습니다. 그러다 보니 서버 내부에서 데이터가 어떻게 가공되는지, 왜 이런 구조로 내려오는지에 대한 이해가 부족했습니다. 이번 기회에 반대로 직접 API를 설계하고 명세서를 작성하여, 클라이언트가 사용하는 API에 대해서 배워보는 것을 경험하고 싶었습니다.

화면은 그려본 경험은 있으나, 백엔드에 대한 이해도가 현저히 부족하면 서비스 전체가 흔들린다는 것을 인지하고 있었습니다.

이번 과제를 통해 API 명세, ERD 설계, 인증/인가 로직 등 백엔드의 역할을 다져놓아, 이 경험을 통해 어떤 프론트엔드를 붙여도 완성도 높은 풀스택 프로젝트로 확장할 수 있을 것이라 생각했습니다.

코드보다 설계를 먼저

백엔드 개발이 처음인 만큼, 무작정 코드를 작성하기보다 설계 단계에 집중했습니다. 이는 프론트엔드 개발 시 API 명세가 바뀔 때마다 겪었던 비효율을 줄이기 위함이기도 합니다.

• 요구사항 정의: "사용자는 대화의 맥락(Context)이 유지되기를 원한다"는 니즈를 파악하고, 이를 기술적으로 구현하기 위한 데이터 모델을 고민했습니다.
• API 명세서 작성: 요청(Request)과 응답(Response)의 JSON 스키마를 미리 정의하여, 인터페이스를 명확히 했습니다.
• ERD 설계: User - Conversation - Message로 이어지는 관계형 데이터베이스 구조를 정규화하여 설계했습니다.

정리

익숙한 프론트엔드가 아닌 백엔드 프로젝트를 선택햇습니다. 이번 인턴 기간의 목표는 '보여주기식 결과물'이 아니라 '개발자로서의 기초 증진'에 있습니다.

약점이라 생각했던 백엔드 영역을 정면으로 마주하고, 설계부터 구현까지 스스로의 힘으로 완주해보려 합니다. 이 4주간의 과정이 끝났을 때, API를 이해하고 설계할 줄 아는 개발자로 성장하길 바랍니다.

FSD(Feature-Sliced Design)란?

FSD는 이름 그대로 기능(Feature)을 중심으로 애플리케이션을 얇게 조각내어(Sliced) 설계(Design)하는 방법론입니다.

기존의 기술 중심적인 분리(예: 단순히 components, hooks, utils로만 나누는 방식)에서 벗어나, 비즈니스 로직과 사용자 기능을 기준으로 프로젝트 구조를 체계화합니다. 이를 통해 프로젝트의 규모가 커져도 유지보수성과 확장성을 잃지 않도록 돕습니다.

FSD의 핵심 철학 : 단방향 의존성 규칙

FSD를 관통하는 단 하나의 절대적인 규칙이 있습니다. 이 규칙만 이해해도 FSD의 절반은 성공입니다.

 "상위 계층은 하위 계층을 import 할 수 있지만, 하위 계층은 절대 상위 계층을 import 할 수 없다."

FSD는 엄격한 계층구조를 가지고 있으며, 의존성은 항상 위에서 아래로만 흘러야 합니다.

이 규칙 덕분에 순환 참조(Circular Dependency) 문제가 원천 차단되고, 특정 모듈을 수정했을 때 영향받는 범위를 예측하기 쉬워집니다. 하위 계층일수록 더 범용적이고 재사용성이 높습니다.

FSD의 6단계 계층 구조 (Layer)

FSD는 표준화된 6개의 계층을 제안합니다. 위로 갈수록 구체적인 화면에 가깝고, 아래로 갈수록 추상적이고 범용적인 코드에 가깝습니다.

(위에서부터 아래로 설명합니다. 위 계층이 아래 계층을 사용합니다.)

1. App (애플리케이션)

프로젝트의 진입점이자 껍데기입니다.

• 역할: 전역적인 설정, 스타일, 레이아웃, Context Provider 등 애플리케이션 전체를 초기화하고 감싸는 역할을 합니다.
• 예시: App.tsx, 라우터 설정, 글로벌 스타일 시트, Redux/Recoil Store 초기화.

2. Pages (페이지)

사용자가 보는 완성된 하나의 화면 단위입니다.

• 역할: 하위 계층(주로 Widgets)을 조립하여 라우팅 경로에 해당하는 페이지를 구성합니다. 실제 비즈니스 로직은 거의 포함하지 않고 '배치'에 집중합니다.
• 예시: 메인 페이지, 로그인 페이지, 상품 상세 페이지.

3. Widgets (위젯)

페이지를 구성하는 굵직한 독립적인 UI 블록입니다.

• 역할: Entities와 Features를 조합하여 만듭니다. 페이지에 가져다 붙이기만 하면 완성된 기능을 제공하는 '조립품'입니다.
• 예시: GNB(헤더), 푸터, 메인 뉴스 피드 섹션, 상품 결제 폼 영역.

4. Features (기능)

사용자의 상호작용(User Action)이 일어나는 단위입니다. 비즈니스 가치를 제공하는 '동작(Verb)'에 집중합니다.

• 역할: "사용자가 무엇을 하는가"를 다룹니다. 특정 Entity를 조작하거나 상태를 변경하는 로직이 포함됩니다.
• 예시: '장바구니 담기' 버튼 클릭 동작, '검색어 입력 후 엔터' 동작, '좋아요 토글' 기능.

 Entities (비즈니스 엔티티)

비즈니스 도메인 데이터 모델 그 자체를 다룹니다.

• 역할: "무엇을 보여주는가"에 집중합니다. 데이터 구조(Model)를 정의하고, 데이터를 화면에 표시하기 위한 순수한 UI 컴포넌트들이 위치합니다. 재사용성이 높습니다.
• 예시: 사용자(User) 정보 카드 UI, 상품(Product) 정보 타입 정의 및 가격 표시 컴포넌트.

6. Shared (공용)

특정 비즈니스 로직에 종속되지 않은 가장 기초적인 계층입니다.

• 역할: 프로젝트 전반에서 재사용되는 유틸리티, UI 라이브러리(버튼, 인풋 등), 설정 파일 등이 위치합니다.
• 예시: UI 키트(공통 버튼, 입력창), API 호출을 위한 Axios 인스턴스, 커스텀 훅(useInput), 날짜 포맷팅 함수.

FSD를 도입하는 이유

1. 명확한 코드 위치와 역할
"이 코드를 어디에 둘까?"라는 고민이 사라집니다. 각 계층의 역할이 명확하므로 새로운 팀원이 합류해도 프로젝트 구조를 빠르게 파악할 수 있습니다.

2. 높은 응집도와 낮은 결합도 (격리된 환경)
기능별로 폴더가 격리(Sliced)되어 있습니다. A 기능을 수정할 때 B 기능이 영향을 받을 확률이 현저히 줄어듭니다. 이는 사이드 이펙트에 대한 두려움 없이 리팩토링과 기능 추가를 가능하게 합니다.

3. 뛰어난 확장성
프로젝트 초기에는 조금 복잡해 보일 수 있지만, 프로젝트 규모가 커질수록 이 견고한 구조가 빛을 발합니다. 수년간 유지보수해야 하는 대규모 프로젝트에 특히 적합합니다.

정리

FSD는 단순한 폴더 구조 규칙이 아니라, 지속 가능한 프론트엔드 개발을 위한 하나의 사고방식입니다.

처음에는 계층을 나누는 기준이 헷갈릴 수 있습니다. 특히 Features와 Entities, Widgets의 경계가 모호하게 느껴질 수 있습니다. 하지만 "의존성은 아래로만 흐른다"는 대원칙을 지키며 적용해 나가다 보면, 어느새 스파게티 코드가 사라지고 깔끔하게 정돈된 아키텍처를 마주하게 될 것입니다.