뼈대는 Thoughtworks의 Juntao Qiu가 2023년 2월 martinfowler.com에 연재한 Modularizing React Applications with Established UI Patterns다. 원문을 그대로 옮기지 않고 필자의 말로 다시 풀었고, 본문의 그림은 모두 이 원문에서 가져왔다. 그 위에 저자의 예제 저장소를 받아 타입 검사와 테스트를 돌린 결과와, 같은 문제를 다룬 다른 자료를 덧붙였다.

React는 view library

React를 처음 배울 때 가장 매력적인 생각은 UI가 데이터를 DOM으로 바꾸는 순수 함수라는 것이다. 어느 정도는 맞다. 그런데 서버에 요청을 보내거나 페이지를 이동하는 순간 component는 더 이상 순수하지 않다. 여기에 전역 state와 지역 state가 얽히면 코드는 금방 복잡해진다.

저자의 답은 관점을 바꾸는 것이다. "React 애플리케이션"이라는 별종 소프트웨어는 없다. React는 UI를 그리는 library이고, 계산이나 업무 규칙을 어디에 둘지는 처음부터 관심사가 아니다. 그 위에 올라간 것은 평범한 JavaScript 앱이다. 그렇다면 데스크톱 GUI 시절부터 써 온 설계, 특히 코드를 presentation, domain, data 세 layer로 나누는 방식을 그대로 쓸 수 있다.

실제 프론트엔드 앱에는 view 말고도 router, local storage, 여러 수준의 캐시, 네트워크 요청, 외부 서비스 연동과 로그인, 보안, 로깅, 성능 조정이 있다. 이것을 전부 component와 hook에 밀어 넣으면 한 파일 안에서 주문 상태를 요청하는 줄 다음에 문자열 앞 공백을 자르는 줄이 오고, 그다음에 다른 화면으로 이동하는 줄이 온다. 읽는 사람은 추상화 수준을 계속 바꿔 가며 앞뒤로 오가야 한다.

나누는 이유는 두 가지로 정리된다. 화면은 업무 규칙보다 자주 바뀐다. 그리고 둘을 떼어 두면 한 번에 한 가지만 생각하면 된다. 두 번째 이유는 Martin Fowler가 PresentationDomainDataLayering에서 이 구분의 가장 큰 이점으로 든 것이다. 세 주제를 비교적 따로 생각할 수 있어서 주의를 기울일 범위가 줄어든다.

앱이 자라는 다섯 단계

저자는 리팩토링에 들어가기 전에 앱이 자라면서 구조가 어떻게 바뀌는지를 다섯 장의 그림으로 보여 준다. 중요한 것은 다음 단계로 넘어가는 계기다. 정해진 시점이 아니라 그 단계에서 생기는 불편이 다음 단계를 부른다. 그림의 색은 다섯 장 모두 같은 뜻이다. 연두는 state를 가진 container component, 진한 초록은 그리기만 하는 presentational component, 보라는 hook, 파랑은 domain object, 주황은 네트워크 같은 infrastructure다.

처음에는 component 하나가 네트워크 요청, state, 계산, render를 모두 갖는다. 작은 앱이나 일회성 프로젝트에서는 이것으로 충분하고, 코드가 HTML과 비슷해서 오히려 읽기 쉽다. 목록을 돌며 항목을 만드는 코드와 외부 component를 설정하는 코드가 섞여 무엇이 일어나는지 읽는 데 시간이 들기 시작하면 다음 단계로 간다.

화면이 커지면 결과 HTML의 모양을 따라 component를 나눈다. 그리기만 하는 component가 떨어져 나오지만, 맨 위 component에는 네트워크 요청, 응답을 화면용 모양으로 바꾸는 코드, 서버로 보낼 데이터를 모으는 코드가 그대로 남는다. 셋 다 UI가 아닌데 component 안에 있다.

그다음 state와 그 변화를 custom hook으로 뺀다. 그러자 hook 안에 side effect도 state도 아닌 순수 계산이 남는다.

그 계산을 React와 무관한 객체로 빼면 domain object가 생긴다. 데이터 형식 변환, null 검사, 대체값이 여기로 온다. 객체가 늘어나면 상속이나 다형성이 필요해지기 시작한다.

마지막으로 UI에도 속하지 않고 데이터가 서버에서 오는지 local storage나 캐시에서 오는지도 상관하지 않는 객체들이 보이면, 그것을 따로 model layer로 묶는다.

그림만 보면 추상적이다. 이 다섯 단계를 실제 코드로 한 번 지나가 보자. 저자가 고른 예제는 온라인 주문의 결제 화면이다.

결제 화면 하나에서 출발

결제 수단은 서버 설정에서 오고 나라마다 다르다. 서버가 하나라도 돌려주면 그 끝에 현금 결제를 붙여 기본으로 선택해 두고, 하나도 없으면 아무것도 보여 주지 않는다.

처음 코드는 튜토리얼에서 흔히 보는 모양이다. useEffect 안에서 fetch하고, 응답을 화면용 모양으로 바꾸고, 현금 결제를 붙이고, 라디오 목록을 그린다. 아래는 필자가 줄여 옮긴 것이다.

export const Payment = ({ amount }: { amount: number }) => {
  const [paymentMethods, setPaymentMethods] = useState<LocalPaymentMethod[]>([]);
 
  useEffect(() => {
    fetch(url)
      .then((res) => res.json())
      .then((methods: RemotePaymentMethod[]) => {
        if (methods.length === 0) return setPaymentMethods([]);
        const extended = methods.map((m) => ({ provider: m.name, label: `Pay with ${m.name}` }));
        extended.push({ provider: "cash", label: "Pay in cash" });
        setPaymentMethods(extended);
      });
  }, []);
 
  return (
    <div>
      {paymentMethods.map((method) => (
        <label key={method.provider}>
          <input type="radio" defaultChecked={method.provider === "cash"} />
          {method.label}
        </label>
      ))}
      <button>${amount}</button>
    </div>
  );
};

이 크기에서는 문제가 아니다. 그러나 이 component를 고치려면 네 가지를 함께 이해해야 한다. 네트워크 요청을 어떻게 시작하는지, 서버 데이터를 화면이 아는 모양으로 어떻게 바꾸는지, 결제 수단 하나를 어떻게 그리는지, 결제 영역 전체를 어떻게 그리는지다. 코드가 커지면 읽는 사람은 이 넷 사이를 계속 오가야 한다.

hook과 pure component

첫 번째로 꺼내는 것은 state와 fetch다. 판단 신호는 단순하다. render와 상관없는 코드가 component 본문의 절반을 넘으면 hook으로 뺀다. usePaymentMethods가 fetch와 변환을 맡고, component는 hook이 준 배열을 받아 그리기만 한다.

두 번째는 목록을 그리는 JSX다. props만 받아서 그릴 수 있는 블록이 보이면 component로 뗀다. PaymentMethods는 결제 수단 배열 하나만 받는 pure component라서 테스트와 재사용이 쉽다. 나중에 선택을 알리는 onSelect callback이 붙어도 바깥 state를 건드리지 않으니 여전히 pure하다.

const usePaymentMethods = () => {
  const [paymentMethods, setPaymentMethods] = useState<LocalPaymentMethod[]>([]);
  useEffect(() => { /* 위의 fetch와 변환 */ }, []);
  return { paymentMethods };
};
 
export const Payment = ({ amount }: { amount: number }) => {
  const { paymentMethods } = usePaymentMethods();
  return (
    <div>
      <PaymentMethods paymentMethods={paymentMethods} />
      <button>${amount}</button>
    </div>
  );
};

저자는 두 작업 모두 리팩토링 카탈로그의 Extract Function이라고 부른다. React에서는 component도 함수이기 때문이다. 새 개념을 들여온 것이 아니라 함수 하나를 둘로 나눴을 뿐이라는 점이 중요하다.

이 정도면 끝난 것처럼 보이지만 아직 두 군데가 남아 있다. view 안에는 "현금이면 기본 선택"이라는 판정이 있고, hook 안에는 응답을 화면용 모양으로 바꾸는 익명 함수가 있다. 저자는 이렇게 업무 규칙이 view와 hook으로 새어 나온 것을 logic leak이라고 부른다.

domain object로 모은 규칙

세 번째 신호는 같은 데이터에 대한 판정이 view와 hook에 흩어져 있을 때다. 새어 나온 판정과 변환을 PaymentMethod class 하나로 모은다. 이 블로그의 도메인 모델에서 다룬 것처럼, 규칙을 데이터 옆에 두는 것이다.

class PaymentMethod {
  constructor(private remote: RemotePaymentMethod) {}
  get provider() { return this.remote.name; }
  get label() { return this.provider === "cash" ? "Pay in cash" : `Pay with ${this.provider}`; }
  get isDefaultMethod() { return this.provider === "cash"; }
}
 
const convertPaymentMethods = (methods: RemotePaymentMethod[]) =>
  methods.length === 0
    ? []
    : [...methods.map((m) => new PaymentMethod(m)), new PaymentMethod({ name: "cash" })];

view의 라디오는 이제 defaultChecked={method.isDefaultMethod}로 객체에게 묻는다. 현금 결제 기본값도 같은 class의 인스턴스 하나로 표현된다. 서버가 준 것과 앱이 붙인 것이 같은 모양이 되니 view는 둘을 구분할 필요가 없다.

저자는 이 구조의 이점으로 테스트가 쉬워진다는 것을 든다. 원문은 그 말에서 멈추지만, 얼마나 쉬워지는지는 코드로 보는 편이 빠르다. 아래는 필자가 쓴 테스트다. React도, 렌더러도, fetch mock도 없다.

test("서버가 준 결제 수단 끝에 현금 결제를 기본값으로 붙인다", () => {
  const methods = convertPaymentMethods([{ name: "apple" }, { name: "google" }]);
 
  expect(methods.map((m) => m.label)).toEqual(["Pay with apple", "Pay with google", "Pay in cash"]);
  expect(methods.filter((m) => m.isDefaultMethod).map((m) => m.provider)).toEqual(["cash"]);
});
 
test("서버가 아무것도 주지 않으면 현금 결제도 보여 주지 않는다", () => {
  expect(convertPaymentMethods([])).toEqual([]);
});

같은 규칙을 처음 코드에서 확인하려면 component를 render하고, fetch를 가로채고, 라디오가 그려질 때까지 기다려야 했다. 규칙이 객체로 나온 순간 테스트는 함수 호출 한 줄이 된다.

또 하나의 이점은 새 요구가 왔을 때 갈 곳이 정해져 있다는 것이다. 이 시점의 파일 구조는 이렇다.

src
├── components
│   ├── Payment.tsx
│   └── PaymentMethods.tsx
├── hooks
│   └── usePaymentMethods.ts
└── models
    └── PaymentMethod.ts

구조가 정말 버티는지는 새 요구가 와야 안다. 저자는 여기서 기능을 하나 더한다.

기부 기능과 state machine으로서의 hook

새 요구는 주문 금액을 올림해 그 차액을 자선단체에 기부하게 하는 것이다. 19.80달러 주문이면 0.20달러 기부를 묻고, 동의하면 버튼에 20달러를 보인다.

저자는 일부러 처음에는 동의 여부 state와 계산을 결제 component 안에 넣는다. 체크박스 마크업, 문구 분기, 합계 계산이 한꺼번에 들어오면서 component가 다시 무거워진다. 정리하는 순서는 앞에서 본 그대로다. state와 계산은 useRoundUp hook으로, 문구 조립은 helper 함수로, 체크박스 마크업은 DonationCheckbox component로 간다.

export const useRoundUp = (amount: number) => {
  const [agreeToDonate, setAgreeToDonate] = useState(false);
 
  const { total, tip } = useMemo(() => ({
    total: agreeToDonate ? Math.floor(amount + 1) : amount,
    tip: parseFloat((Math.floor(amount + 1) - amount).toPrecision(10)),
  }), [amount, agreeToDonate]);
 
  const updateAgreeToDonate = () => setAgreeToDonate((v) => !v);
  return { total, tip, agreeToDonate, updateAgreeToDonate };
};

toPrecision(10)은 원문이 이유를 설명하지 않는 부분이다. 필자가 Node 24에서 돌려 보니 20 - 19.8은 0.1999999999999993이 나왔다. 부동소수 오차를 걷어 내는 장치다.

저자는 이런 hook을 "view 뒤의 state machine"으로 본다. UI에서 이벤트가 오면 새 state를 만들고, 새 state가 다시 render를 일으킨다. hook은 원래 여러 component가 logic을 나눠 쓰려고 만든 것이지만, 쓰는 곳이 하나여도 component를 render에 집중하게 해 주므로 뺄 가치가 있다는 것이 저자의 입장이다. 여기에 하나를 보태면, React 공식 문서의 Reusing Logic with Custom Hooks가 짚듯 custom hook이 나누는 것은 state를 다루는 logic이지 state 자체가 아니다. 이 state machine은 hook을 부르는 component마다 하나씩 따로 생긴다.

정리가 끝나면 결제 component는 hook 둘을 부르고 하위 component 둘과 버튼 하나를 늘어놓는 모양이 된다. 기능이 하나 늘었는데 결제 component의 역할은 그대로다.

나라별 규칙과 shotgun surgery

다음 요구는 나라마다 올림 단위를 다르게 하라는 것이다. 일본은 100엔 단위, 덴마크는 10크로네 단위다. 저자는 "쉬운 고침 같다"며 나라 코드를 prop으로 받아 분기를 넣는 길을 일부러 먼저 보여 준다.

// useRoundUp 안
total: agreeToDonate
  ? countryCode === "JP" ? Math.floor(amount / 100 + 1) * 100 : Math.floor(amount + 1)
  : amount,
 
// 체크박스 문구 helper 안
const currencySign = countryCode === "JP" ? "¥" : "$";
 
// 버튼 JSX 안
<button>{countryCode === "JP" ? "¥" : "$"}{total}</button>

같은 countryCode === "JP" 판정이 hook, helper, 버튼 세 자리에 하나씩 들어갔다. 덴마크를 더하면 세 자리를 모두 다시 고쳐야 하고, 삼항 연산자가 감당이 안 되면 나라 코드로 통화 기호를 찾는 표가 생긴다. 그 표도 결국 여러 곳에서 따로 참조된다. 변경 하나에 여러 모듈을 동시에 고쳐야 하는 이 냄새를 shotgun surgery라고 부른다.

이 단계가 앞의 세 단계와 다른 점은 판단 신호가 코드가 아니라 변경 요청에서 온다는 것이다. 지금 코드만 보면 분기 세 개는 읽기 어렵지 않다. 나라를 하나 더할 때 몇 군데를 고쳐야 하는지 세어 봐야 문제가 보인다. 그렇다면 흩어진 분기를 어디로 모아야 할까.

Strategy로 모은 나라별 차이

저자의 답은 나라별 차이 자체를 객체로 만드는 것이다. 먼저 Extract Class와 Replace Conditional with Polymorphism으로 interface 하나와 나라별 구현을 만든다.

interface PaymentStrategy {
  getRoundUpAmount(amount: number): number;
  getTip(amount: number): number;
}
 
class PaymentStrategyAU implements PaymentStrategy { /* 1달러 단위 */ }
class PaymentStrategyJP implements PaymentStrategy { /* 100엔 단위 */ }

만들고 보니 구현마다 다른 것은 통화 기호와 올림 함수 둘뿐이고, getTip 같은 나머지는 똑같다. 그래서 저자는 Inline Class로 구현들을 class 하나에 합치고, 다른 부분만 생성자로 받는다. 나라마다 subclass를 만들지 않고 올림 알고리즘을 함수로 받을 수 있는 것은 JavaScript에서 함수가 값이기 때문이다. 아래는 그 결과를 필자가 줄여 쓴 것이다.

class CountryPayment {
  constructor(readonly currencySign: string, private roundUp: (n: number) => number) {}
  getRoundUpAmount(n: number) { return this.roundUp(n); }
  getTip(n: number) { return parseFloat((this.getRoundUpAmount(n) - n).toPrecision(10)); }
}
 
const japan = new CountryPayment("¥", (n) => Math.floor(n / 100 + 1) * 100);
japan.getRoundUpAmount(3312); // 3400
japan.getTip(3312);           // 88

hook과 component는 이제 나라를 모른다. 이 객체 하나를 받아 strategy.getRoundUpAmount(amount)와 strategy.currencySign을 쓸 뿐이다. 나라를 하나 더하면 객체를 하나 더 만들면 끝나고, 고칠 파일은 없다.

interface를 거쳤다가 다시 합친 과정이 군더더기처럼 보일 수 있다. 필자는 이 부분이 원문에서 가장 배울 만한 대목이라고 본다. 다형성은 목적이 아니라 공통점과 차이점을 드러내는 도구였고, 차이가 함수 하나로 줄어든 것이 보이자 class 계층을 걷어 냈다. 패턴을 들여오는 것보다 그 패턴을 언제 다시 걷어 내는지가 더 어려운 판단이다.

fetch를 hook 밖으로

마지막으로 꺼내는 것은 usePaymentMethods 안의 fetch와 변환이다. hook은 React 개념이라 view 쪽에 남는다. error handling과 retry를 넣으면 hook이 금방 부풀고, 다른 view library로 옮기면 hook은 쓸 수 없다. 반면 일반 함수는 어디서든 쓸 수 있다.

const fetchPaymentMethods = async () => {
  const response = await fetch(`${API}/payment-methods?countryCode=AU`);
  return convertPaymentMethods(await response.json());
};
 
export const usePaymentMethods = () => {
  const [paymentMethods, setPaymentMethods] = useState<PaymentMethod[]>([]);
  useEffect(() => {
    fetchPaymentMethods().then(setPaymentMethods);
  }, []);
  return { paymentMethods };
};

저자는 이 함수가 Anti-Corruption Layer 또는 Gateway처럼 동작한다고 쓴다. 서버 응답 구조가 바뀌어도 고칠 곳이 이 함수 하나에 머문다는 뜻이다. 다만 두 이름은 같은 것이 아니다. Fowler의 Gateway는 외부 시스템 접근을 한곳에 감싸는 객체이고, Anti-Corruption Layer는 Eric Evans의 DDD에서 온 말로 의미 체계가 다른 외부 모델이 내 모델을 오염시키지 않게 번역하는 경계다. 이 예제의 서버 응답은 { name } 하나라 번역할 의미 차이가 거의 없으므로, 필자는 Gateway가 더 정확한 이름이라고 본다. 서버가 다른 팀 소유의 레거시라 결제 수단의 의미 자체가 다를 때 같은 자리가 Anti-Corruption Layer가 된다.

최종 구조는 이렇다. render는 component에, state는 hook에, 규칙은 domain object에, 네트워크 요청은 함수에 있다.

저자는 이렇게 나눈 결과로 다섯 가지 이점을 든다. 결함이 있는 자리를 찾기 쉬워진다. 코드를 재사용하고 조합하기 쉬워진다. 읽기 쉬워진다. 기능을 더해도 전체가 흔들리지 않는다. 그리고 domain logic이 view를 모르므로 view layer만 갈아 끼울 수 있다. 마지막 것에는 저자 스스로 대부분의 프로젝트에서는 매우 드문 일이라는 단서를 단다. 다섯 모두 측정치는 없다는 점도 같이 기억해 둘 만하다.

여기까지가 원문의 줄거리다. 그런데 이 코드를 실제로 돌려 보면 글에서는 보이지 않던 것이 나온다.

예제를 돌려 보면 보이는 것

필자는 저자의 예제 저장소(커밋 16개, 마지막 커밋 de186c5)를 받아 tsc --noEmit과 테스트 7개를 돌렸다. 둘 다 통과했고, 원문에 정의가 빠진 helper도 저장소의 src/utils.ts에 있었다. 그런데 구조를 들여다보니 옮겨 쓰기 전에 알아야 할 것이 셋 있었다.

매 render마다 새로 만드는 Strategy

결제 component는 Strategy를 prop으로 받고, 넘기지 않으면 기본값을 new로 만든다. 그리고 useRoundUp은 그 Strategy를 useMemo의 dependency에 넣는다.

export const Payment = ({
  amount,
  strategy = new PaymentStrategy("$", roundUpToNearestInteger),
}: { amount: number; strategy?: PaymentStrategy }) => {
  const { total, tip } = useRoundUp(amount, strategy); // 안에서 [agreeToDonate, amount, strategy]
  // ...
};

JavaScript의 default parameter는 호출할 때마다 평가된다. 그리고 useMemo는 dependency를 Object.is로 비교한다. 둘이 만나면 render마다 새 인스턴스가 생기고 memo는 매번 다시 계산한다. React 18에서 같은 구조를 네 번 render했더니 기본값을 쓸 때 계산이 4번, 같은 인스턴스를 넘길 때 1번 돌았다. 저장소의 App.tsx는 <Payment amount={19.9} />로 Strategy를 넘기지 않으므로 앱의 실행 경로가 정확히 기본값 쪽이다.

이 예제의 계산은 덧셈 몇 번이라 비용은 없다. 문제는 구조다. Strategy를 누가 어디서 만들어 넘기는지가 글에도 저장소에도 정해져 있지 않고, 테스트만 일본과 덴마크 인스턴스를 만든다. 필자라면 인스턴스를 module 수준 상수로 두고 나라 코드로 꺼내 넘기겠다.

const strategies = {
  AU: new CountryPayment("$", (n) => Math.floor(n + 1)),
  JP: new CountryPayment("¥", (n) => Math.floor(n / 100 + 1) * 100),
} as const;
 
<Payment amount={amount} strategy={strategies[countryCode]} />

저장소의 fetch에는 dependency 배열이 없다

원문 코드의 useEffect에는 []가 있지만, 저장소의 usePaymentMethods에는 첫 커밋부터 마지막 커밋까지 dependency 배열이 없다. 배열이 없는 effect는 render마다 다시 돈다. 응답이 오면 새 배열로 state를 바꾸고, 그것이 render를 일으키고, effect가 다시 fetch한다. convertPaymentMethods가 매번 새 배열을 돌려주므로 멈추지 않는다.

fetch를 바로 응답하는 mock으로 바꾸고 Jest에서 300ms 동안 호출 수를 세면 네 번 재서 152, 225, 231, 233번이 나왔다. []를 넣으면 1번이다. 저장소의 테스트는 화면에 문구가 뜨는지만 보므로 이 반복을 잡지 못하고 전부 통과한다. 원문을 따라 친 독자에게는 이 문제가 없고, 저장소를 그대로 받아 쓸 때만 걸린다.

국가 코드를 prop으로 받는 순간 생기는 race

원문 코드의 fetch effect에도 cleanup이 없다. React 공식 문서의 Synchronizing with Effects는 effect 안에서 fetch하면 늦게 도착한 이전 응답이 최신 응답을 덮을 수 있으므로 ignore 플래그로 이전 응답을 버리라고 한다. 원문은 mount 때 한 번만 fetch하므로 지금은 문제가 없다. 하지만 URL의 countryCode=AU를 prop으로 받는 순간 dependency가 생기고 race가 열린다. 필자는 이 구조를 옮길 때 처음부터 이렇게 쓰겠다.

useEffect(() => {
  let ignore = false;
  fetchPaymentMethods(countryCode).then((methods) => {
    if (!ignore) setPaymentMethods(methods);
  });
  return () => { ignore = true; };
}, [countryCode]);

하나 더 덧붙이면, 원문의 올림은 Math.floor(amount + 1)이라 금액이 이미 정수면 1을 더 올린다. 20달러 주문은 21달러가 된다. 원문은 19.80달러와 3312엔만 예로 들어 이것이 의도인지 알 수 없다. 실제 서비스에 옮긴다면 Math.ceil과 무엇이 다른지부터 정해야 한다.

이 구조는 언제 쓰는가

저자 스스로 나누는 것은 고정 규칙이 아니라고 말한다. 작고 응집된 component는 한 파일에 두는 편이 동작을 이해하기 쉽고, 경계할 것은 파일이 이해할 수 없을 만큼 커지는 것이다. Todo 앱이나 폼 하나짜리 앱은 전부 component에 넣어도 괜찮고, 예제는 패턴을 많이 보여 주려고 일부러 복잡하게 만들었다고 밝힌다. 다른 자료들도 같은 방향의 단서를 단다.

Fowler는 같은 layering 글에서 이 구분을 비교적 작은 단위에만 쓰라고 한다. view, model, data를 최상위 폴더로 두는 것은 작은 시스템에서는 괜찮지만, 어느 하나가 너무 커지면 최상위를 도메인 단위로 나누고 그 안을 layer로 나누라는 것이다. 앞에서 본 components/, hooks/, models/ 폴더를 큰 앱의 최상위 구조로 그대로 옮기면 Fowler가 피하라고 한 모양이 된다.

Dan Abramov도 비슷한 이력을 가지고 있다. 2015년에 presentational과 container component로 나누자고 했다가, 2019년에 글머리에 이제는 그렇게 나누기를 권하지 않는다는 갱신문을 붙였다. Hooks가 같은 일을 임의의 구분 없이 해 준다는 이유였고, 필요도 없이 교조적으로 강제되는 것을 너무 많이 봤다고 덧붙였다. 원문의 hook 추출은 이 갱신문이 말하는 방식에 가깝다. container라는 이름의 component를 따로 두지 않고, hook을 부르는 Payment가 그 역할을 겸한다.

fetch에 대해서는 React 공식 문서가 한 걸음 더 간다. You Might Not Need an Effect는 fetch logic을 custom hook으로 빼 두면 나중에 더 나은 전략으로 옮기기 쉽다고 하면서도, 1순위로는 framework의 내장 fetching이나 TanStack Query 같은 client cache를 권한다. 원문의 마지막 단계처럼 fetch를 일반 함수로 빼 두면 그 함수를 그대로 TanStack Query의 queryFn에 넘길 수 있고, 앞 절의 race와 반복 호출은 library가 맡는다. 필자는 이 점이 원문이 한 문장으로만 언급한 가장 실용적인 이득이라고 본다. 키와 함수를 묶는 방식은 queryKey에서 따로 다뤘다.

정리하면 필자의 판단은 이렇다. 원문의 순서(hook, pure component, domain object, Strategy, network client)는 그대로 따를 만하다. 단계마다 그 단계의 불편이 다음 단계의 이유가 되기 때문이다. 다만 끝까지 가야 하는 것은 아니고, 지금 겪는 불편이 어느 단계의 것인지 보고 거기서 멈추면 된다. render와 무관한 코드가 많으면 hook까지, 같은 판정이 흩어져 있으면 domain object까지, 변경 하나에 여러 파일을 고치고 있으면 Strategy까지다. 그리고 Strategy를 쓴다면 인스턴스를 만드는 자리를 먼저 정하고, fetch를 effect에 둔다면 cleanup과 dependency부터 쓴다. 원문이 생략한 이 두 가지가 실제로 옮겨 쓸 때 가장 먼저 깨지는 곳이었다.

정답은 없지만, 이 글을 읽는 독자 분들도 자기 코드가 지금 몇 번째 단계의 불편을 겪고 있는지 한 번 짚어 보기를 바란다.

가장 먼저 눈에 들어온 사용처는 브라우저 자동화였다. Browserbase가 Stagehand의 act()에 Jev를 붙이는 PR을 올렸다. 페이지의 접근성 트리를 state로 보내고 "다음에 클릭할 요소는 어느 것인가"를 선택지로 묻는 구조였다. 40개 과제에서 act() 중앙값이 1.97초에서 0.46초로 줄었고, 147번의 동작 중 LLM으로 되돌아간 것은 4번이었다. Playwright 스크립트가 selector 하나 바뀌면 깨지는 자리를, 확률 하나 돌려받는 호출로 메운 것이다. 이 글을 쓰는 시점에 PR은 아직 머지되지 않았다.

그 PR이 그은 선이 이 글의 질문이다. Jev의 답을 받아들이는 기준을 확률 0.7로 두고, 못 넘으면 LLM에게 넘긴다. 저 모델이 돌려주는 확률을 믿고 코드에서 선을 그어도 되는가.

남의 벤치마크만으로는 판단할 수 없어서 필자의 데이터로 검증해보려 한다. 이 블로그에는 음차 외래어를 막는 게이트가 있다. 피커가 아니라 picker로 쓰자는 규칙인데, 정규식은 확실한 절반만 잡고 멀티스레드나 콜 스택처럼 합성어이거나 이미 정착한 말은 필자가 매번 손으로 판단한다. 답은 "되돌린다"와 "둔다" 둘뿐이고, 아는 사람은 1초에 판단하고, 빌드 스크립트 안에서 사람 확인 없이 통과와 실패를 정해야 한다. Stagehand의 selector 판단과 모양이 같다.

그래서 순서를 이렇게 잡았다. Jev가 무엇을 돌려주는지, 그 확률이 어떤 학습에서 나오는지, 필자의 게이트에 넘기면 어떤 숫자가 나오는지, 그리고 그 숫자를 어디에 쓸 수 있는지다.

텍스트를 만들지 않는 모델

2026년 9월 15일에 공개되었다. TypeSafe에서 이것을 LLM이라고 부르지 않고 System One Model이라는 새 범주로 부른다. 이 글에서는 결정 모델이라고 부른다. 창업자 Diogo Almeida는 OpenAI에서 InstructGPT 논문의 네 번째 저자로 참여했던 사람이다. ChatGPT 만든 팀에 있었고, 지금은 그 방법의 한계를 지적하는 쪽에 서 있다.

Jev는 문장을 생성하지 않는다. 답의 모양을 미리 정해 주면 그중에서 고르고 확률을 함께 돌려준다. 질문 타입은 셋뿐이다.

endpoint도 하나다. POST /v1/systemone에 state(평가할 내용), model, questions(질문 맵)를 보내면 답이 온다. 같은 state에 대한 질문 여러 개를 한 요청에 담을 수 있고, 질문을 늘려도 응답 시간이 거의 안 늘어난다.

왜 빠른지는 토큰의 원리에서 정리한 prefill과 decode의 비대칭으로 설명된다. LLM이 느린 이유는 출력을 한 토큰씩 순차적으로 짜내기 때문인데, Jev는 그 decode 단계가 없다. 입력을 한 번 병렬로 읽고 확률을 바로 읽어낸다. 그래서 출력 토큰 요금이 아예 없고 입력만 백만 토큰당 $0.042다.

Archer Hume이라는 개발자가 API를 약 1만 번 호출해 바깥에서 동작을 복원한 분석이 있다. 입력 360토큰에 중앙값 57.5ms, 29,835토큰에 218ms, 질문을 1,500개 넣었을 때 610ms였다. 그중 가장 직접적인 증거는 선택지가 200개인 응답이 2개짜리와 같은 속도로 돌아왔다는 관찰이다. 답을 쓰는 데 시간이 안 걸린다는 뜻이다.

사람이 안 보는 판단

속도와 가격이 눈에 띄지만, Almeida가 공개 발표 글에서 던진 질문은 다른 쪽이었다. 모델이 몇 년째 대화에서 초인적인데 자동화는 다 어디 갔느냐는 것이다.

그의 답은 두 일의 종류가 다르다는 것이다. 챗봇과 copilot과 코딩 agent는 사람이 옆에서 보면서 만족하는 것이 목표다. 서버에서 조용히 돌면서 아무도 안 보는 판단은 그렇지 않다. 앞을 assistant, 뒤를 automation이라고 부른다면, 지금까지 나온 모델은 전부 앞쪽을 위해 만들어졌다.

harness 설계를 정리하면서도 비슷한 구분을 한 적이 있다. 에이전트 시스템 안에는 사람이 보지 않는 판단이 무수히 많다. 이 요청을 사람에게 넘길까. 이 명령을 실행해도 되나. 지금은 그것들을 전부 비싼 LLM에게 물어보고 있다. 필자의 정규식 게이트가 못 덮는 나머지 절반도 그런 판단이다.

RLHF가 남긴 자리

그런데 왜 새 학습법이 필요했을까. 기존 모델에게 예/아니오만 시키면 안 되는 걸까.

답의 실마리는 Calibration에 있다. 정확도가 몇 퍼센트 맞히느냐라면 calibration은 자기가 몇 퍼센트 맞힐지를 아느냐이고, 그 어긋남을 재는 지표가 ECE(expected calibration error)다. 확률 구간마다 말한 확률과 실제 적중률의 차이를 표본 비율로 가중해 평균한 값이라 0이 완벽이다. 그런데 사람의 선호를 최적화하는 RLHF(reinforcement learning from human feedback)를 거친 뒤 이 눈금이 어긋난 사례가 있다. GPT-4 기술 보고서의 Figure 8에서는 사전학습 모델의 ECE가 0.007이었는데 post-training을 거친 모델은 0.074로 열 배 넘게 나빠졌다. 보고서는 그 원인을 적지 않았고, 필자도 원인을 확정한 1차 근거는 찾지 못했다. 정의와 원인이 어디까지 밝혀졌는지는 LLM calibration과 overconfidence에 따로 정리해 두었다.

다만 ECE 하나로는 부족하다. 모든 입력에 0.6을 찍는 상수 예측기도 실제 적중률이 60%면 ECE가 0이다. 확률이 정직하기만 하고 사안마다 갈리지 않으면 선을 그을 자리가 없다. 그래서 calibration과 별개로 확률이 실제로 갈라지는지를 같이 봐야 하고, 뒤에서 쓸 "오차 예산 안에서 자동 처리할 수 있는 비율"이 그 둘을 한 숫자로 묶은 지표다.

소프트웨어 입장에서 중요한 것은 이 부분이다. 확률이 정직하고 갈라지면 선을 그을 수 있다. 0.95 넘으면 자동 처리하고 그 아래는 사람에게 넘기는 구조가 나온다.

TypeSafe는 그 자리를 겨냥해 세 번째 길을 냈다고 말한다. 사람의 선호를 최적화하는 RLHF, 기계가 채점할 수 있는 정답을 최적화하는 RLVR(reinforcement learning with verifiable rewards), 그리고 calibration된 결정을 최적화한다는 RLCD다.

다만 RLCD로 공개된 것은 출력 계약 세 줄이 전부다. 이 글을 쓰는 2026년 9월 23일 기준으로 TypeSafe의 문서와 발표 글 어디에도 논문이나 기술 보고서가 없다. 같은 약어를 쓰는 ICLR 2024 논문이 따로 있는데 그쪽은 reinforcement learning from contrastive distillation이라 다른 방법이다.

confidence의 정체

그래서 Jev가 돌려주는 숫자는 정직한가. 답하기 전에 먼저 볼 것이 있다. 돌려주는 숫자가 하나가 아니다.

Choice와 Score 응답에는 probabilities와 confidence가 같이 들어 있다. 앞은 선택지 전체에 걸친 확률 분포이고, 뒤는 0에서 1 사이 숫자 하나다. 코드에서 임계값을 걸 때 손이 먼저 가는 쪽은 confidence다.

이 값은 모델이 만든 것이 아니다. TypeSafe 조직이 공개한 system-one-adapter-python의 _utils/confidence_metrics.py의 Choice 부분은 아래와 같다.

def choice_confidence(probs: list[float]) -> float:
    """Scale peak choice probability from uniform to certainty."""
    if len(probs) == 1:
        return 1.0
 
    normalized_probs = _normalize(probs)
    uniform_probability = 1.0 / len(normalized_probs)
    return (max(normalized_probs) - uniform_probability) / (1.0 - uniform_probability)

모델 호출도 없고 학습된 파라미터도 없다. probabilities 벡터 하나가 들어가고 실수 하나가 나온다. 식으로 쓰면 c = (p_max − 1/K) / (1 − 1/K)이고, 선택지가 셋이고 최대 확률이 0.8이면 0.7이 된다.

이 저장소는 프로덕션 Jev 서버가 아니라 LLM으로 같은 API를 흉내 내는 대체 구현이다. 그러니 이것만으로 단정할 수는 없다. 그런데 같은 식을 가리키는 증거가 둘 더 있다. TypeSafe 공식 문서의 confidence 페이지가 이 값을 "a statistic computed from the probability distribution"이라고 적고, 데모 코드에는 세 선택지용 근사식이라며 (3 × largest probability − 1) / 2를 실었다. K가 3이면 위 식과 같다. 그리고 주장 감사 원장이 실제 API에서 둘 다 틀린 선택지 둘만 준 응답의 승자가 0.52일 때 confidence가 0.04로 왔다고 기록했다. K가 2면 (0.52 − 0.5) / (1 − 0.5) = 0.04다. 식과 맞는다.

같은 저장소에서 Score는 아예 다른 식을 쓴다. 최빈 수준으로부터의 평균 절대 거리를 균등 분포의 그것으로 나눈 뒤 1에서 뺀다. 문서는 Score의 식을 공개하지 않는다. 그러니까 confidence라는 한 이름 아래 산식이 둘 있고, 타입이 다르면 같은 숫자가 다른 뜻이다. Noul에 confidence가 없는 것도 같은 이유다. 접을 분포가 없다.

문서도 이것을 숨기지 않는다. 다른 계산을 쓰고 싶으면 probabilities 전체를 줄 테니 알아서 하라고까지 안내한다. 적혀 있는 내용이고, 읽지 않고 쓰는 쪽이 문제다.

그런데 공개 발표 글의 비교표는 둘을 붙여 쓴다. "Calibrated: higher confidence means higher accuracy"라고 적혀 있다. 읽는 사람은 confidence가 calibration된 값이라고 받아들이는데, calibration 주장이 실제로 걸려 있는 쪽은 probabilities다.

이 구분이 숫자로 얼마나 벌어지는지는 측정이 있다. scienthoon이라는 개발자가 공개한 독립 calibration 측정이 confidence를 "맞을 확률"로 읽었을 때의 ECE를 따로 쟀다. OpenBookQA에서 0.035, HellaSwag에서 0.078, 합성 집합에서 0.18이다. 같은 집합의 원본 확률은 각각 0.024, 0.029, 0.107이었다. 세 집합 전부에서 confidence 쪽이 나쁘다.

왜 나빠지는지는 식에 있다. K가 고정이면 c는 p_max의 순증가 변환이라 순서가 보존된다. 판별력은 그대로이고 임계값만 옮겨 적으면 된다. 망가지는 것은 정보가 아니라 눈금이다. K가 질문마다 다르면 문제가 하나 더 생긴다. 늘이는 배율도 달라진다. 같은 p_max 0.8이 선택지 둘에서는 0.6이 되고 다섯에서는 0.75가 된다. 선택지 수가 섞인 워크로드에서 임계값 하나를 쓰는 순간 그게 문제가 된다.

분포에 따라 달라지는 calibration

그렇다면 probabilities 쪽은 믿어도 될까.

Jev를 실제로 호출해 재본 기록이 공개되어 있다. Jared Palmer가 만든 오픈소스 재현 구현 Kev의 저장소에는 runs/jev-* directory가 있고, usage.json이 "model": "typesafe-ai/jev"로 Vercel AI Gateway를 거친 실호출임을 기록하고 있다. jev-* directory 여섯 개의 usage.json을 합치면 2026년 9월 18일과 20일에 걸쳐 5,364회를 불렀고 입력이 2,418,260토큰이다. 아래 일곱 집합 중 scienthoon은 그 개발자의 결과 파일을 변환해 들여온 것이라 이 합계에 들어 있지 않다.

가격이 실제로 입력만 과금된다는 것은 다른 곳에서 확인된다. 피싱 벤치마크 저자가 TypeSafe dashboard를 보고 적어 뒀다. 두 번 돌린 456만 토큰 중 입력이 366만, 출력이 90만이었는데 청구는 $0.15였고 그 값이 입력만 계산한 것과 맞았다.

같은 directory의 report.json에서 평가 집합 일곱 개의 지표를 꺼내 정리하면 이렇다. 아래에서 확신도는 confidence 필드가 아니라 probabilities의 최댓값이다. overconfidence는 평균 확신도 − 정확도이고 총 5,743건이다. 판단 근거를 지운 "알 수 없는" 항목은 정확도 채점에서 빼는 clean 블록의 값이다.

두 가지가 읽힌다.

첫째, ECE가 열 배 가까이 움직인다. 0.011에서 0.105다. 같은 채점기, 같은 모델이다. "calibration됐다"는 모델의 성질이 아니라 모델과 분포의 관계인 것이다. 분포가 바뀌면 calibration이 무너진다는 것 자체는 이미 알려진 결과다. 여기서 새로운 것은 calibration을 학습 목표로 내세운 모델에서도 같은 모양이 나온다는 점이다.

ECE가 가장 큰 집합의 0.105는 앞에서 본 post-RLHF GPT-4의 0.074보다도 크다. 다만 이 둘을 순위로 읽으면 안 된다. 과제가 다르고, ECE는 구간을 몇 개로 나누느냐와 표본이 어느 구간에 몰렸느냐에 따라 값이 움직이는 추정량이라 서로 다른 채점기에서 나온 숫자를 맞대면 비교가 성립하지 않는다.

둘째, 측정된 ECE가 overconfidence 하나로 거의 전부 설명된다. 두 열의 차이가 일곱 개 전부 0.002에서 0.011 사이다. ECE는 구간별 격차의 가중 평균이라 전체 overconfidence보다 작을 수 없는데, 그 차이가 거의 0이라는 것은 구간마다 어긋나는 부호가 한 방향으로 쏠려 있다는 뜻이다. 구간별로 엇갈려 상쇄되는 잡음이 아니다.

왜 그런지는 세로로 읽으면 보인다. 평균 확신도는 semif를 빼면 0.851에서 0.906 사이에 여섯 개가 붙어 있다. 같은 구간에서 정확도는 0.753에서 0.857로 두 배 넓게 움직인다. 확신도는 분포가 바뀌어도 잘 안 움직이고 정확도만 움직인다. 남는 차이가 그대로 ECE다.

이 성질이 실무에서 어떻게 나타나는지는 다른 벤치마크가 보여준다. 피싱 이메일 2,000건에 Claude Haiku 4.5를 대조군으로 세운 측정에서 Jev의 정확도는 62.6%였고 Haiku는 81.3%였다. 그런데 더 눈에 띄는 것은 ECE다. 리포가 보고한 ECE는 Jev 0.154, Haiku 0.097이고, 주장 감사 원장이 Jev의 P(phishing) 값을 0에서 1까지 10구간으로 다시 재면 0.170이다. 어느 쪽으로 읽어도 calibration을 학습 목표로 내세운 모델이 RLHF로 만든 LLM에게 calibration에서 졌다. 같은 저자가 링크 호스트 목록 규칙 하나만으로 91.6%를 냈다.

같은 지표를 여러 집합에서 보면 폭이 더 분명하다. 오차 예산 5%에서 자동 처리할 수 있는 비율이 scienthoon 집합에서 0.486, transfer-v9에서 0.695, semif에서 1.000이다. Kev의 채점기는 이 값을 표본 안에서 임계값을 고른 최댓값이라고 적어 두었고, 배포 후의 오차 보장이 아니다. 어느 하나를 모델의 스펙처럼 인용하면 안 된다.

음차 판별 게이트

남의 벤치마크를 읽는 것과 내 데이터에서 재보는 것은 다르다. 그래서 서두의 게이트를 실제로 넘겨 봤다.

필자는 앞서 언급한 Kev-9B를 로컬에서 돌렸다. Qwen3.5-9B-Base에 rank-16 LoRA와 pointer head를 얹은 재현 구현이고 Apache-2.0이다. 아래 숫자는 Jev의 숫자가 아니다. Kev의 학습 데이터는 영어 결정 과제이고, 같은 저자의 측정에서 Kev-9B는 영어 과제에서도 Jev에 뒤진다. 오차 예산 5%의 자동화 비율이 0.45에서 0.57인데 Jev가 0.70이고, MMLU-Pro는 0.52 대 0.84다. 그리고 TypeSafe 문서도 Jev에 대해 영어가 주 학습 언어이고 CJK는 동등하지 않다고 밝히고 있다.

평가 집합은 필자의 한국어 블로그 글 18편에서 뽑았다. 라벨의 정답 기준은 블로그에서 그 단어를 일관되게 어느 표기로 쓰는가다. 한국어 기술 문서 공동체의 합의가 아니라 이 블로그의 관습이라는 뜻이고, 둘이 갈리는 단어에서는 모델이 공동체 기준으로 맞고 이 기준으로 틀릴 수 있다.

• 게이트에 있는 단어, 102문장: 게이트가 이미 아는 단어다. 본문이 영어로 쓴 calendar, picker, adapter 같은 단어를 한글 음차로 바꿔 만든 문장, 즉 되돌릴 문장이 23개이고, write-post.md가 예외로 명시한 리렌더링이나 콜 스택이 실제로 쓰인 문장, 즉 그대로 둘 문장이 79개다. 여기서 현재 정규식 게이트는 정의상 100%를 맞힌다.
• 게이트에 없는 단어, 60문장: 게이트가 한 번도 본 적 없는 단어다. 머신러닝에서 held-out 이라고 부르는 쪽이다. 본문이 영어로만 쓰는 loader, mutation, prefill을 음차로 바꾼 되돌릴 문장이 30개, 본문이 한글로만 쓰는 리듀서, 스냅샷, 런타임이 실제로 쓰인 그대로 둘 문장이 30개다. 여기서 정규식은 되돌릴 문장을 하나도 못 잡는다.

되돌릴 문장은 필자가 만든 것이고 그대로 둘 문장은 실제 문장이라는 비대칭은 먼저 밝혀 둔다. 그리고 유효 표본은 문장 수가 아니라 단어 수다. 라벨이 단어 단위로 정해지므로 같은 단어가 나오는 문장들은 독립 관측이 아니다. 게이트에 있는 단어는 24종, 없는 단어는 13종이다.

아래 표는 "이 단어를 영어로 되돌려야 하는가"를 묻는 noul 질문 하나만 집계한 것이다. 같은 요청에 질문을 넷 담았지만 나머지 셋은 부정형과 Choice 변형, 그리고 라벨을 제대로 세우지 못한 합성어 판정이라 여기 섞지 않았다. 5% 예산 자동화 비율은 확신도가 높은 쪽부터 잘라 내려가며 그 위 구간의 오차가 5%를 넘지 않는 최대 비율이다.

다수 클래스 기준선은 문장을 안 읽고 많은 쪽 라벨만 찍었을 때의 점수다. 모델이 그 아래다.

마지막 줄이 이 실험의 답이다. 게이트에 없는 단어에서는 임계값을 아무리 높게 잡아도 5% 오차 안에서 자동 처리할 수 있는 결정이 한 건도 없었다.

예측 분포를 보면 무슨 일이 일어났는지 나온다. 모델은 162문장 전부에 "되돌려야 한다"고 답했다. 단어 37종 전부다. 되돌릴 문장은 전부 맞고 그대로 둘 문장은 전부 틀렸다. 그래서 게이트에 없는 단어의 0.500은 실력이 아니라 집합이 균형 잡혀 있어서 나온 숫자다.

그러면서 평균 확신도가 0.876이었다. 게이트에 있는 단어에서 확신도 0.9를 넘은 것이 49%인데 그 구간의 실제 적중은 0.240이다.

두 확률의 합이 1이 되는 관계도 성립하지 않았다. "되돌려야 하는가"와 "그대로 둬야 하는가"의 확률을 더하면 게이트에 있는 단어에서 평균 1.655가 나왔고, 102문장 전부가 1에서 0.1 넘게 벗어났다.

설계상 그렇다. 두 질문은 서로를 읽지 못하는 별개의 평가이고, TypeSafe도 jaggedness 페이지에 refund 0.72와 not_refund 0.47을 더해 1.19가 되는 예를 직접 실어 뒀다.

실무에서 걸리는 지점은 이것이다. Noul에 맞춰 조율한 임계값을 Choice로 옮기면 안 된다. 같은 판단인데 결론이 갈리는 문장이 14%에서 17%였다.

무엇을 물어도 예라고 하는 모델이면 이 결과는 무의미하다. 그것부터 확인했다.

한국어를 읽고, "아니오"를 말하고, 0.02와 0.98을 가른다. 전역적인 순응 편향은 아니다. 배제되는 것은 거기까지다. 게이트 질문의 문구 자체가 나쁠 가능성은 남는다.

규칙을 state에 넣은 결과

그렇다면 판별에 필요한 지식을 직접 주면 달라질까. TypeSafe 문서가 권하는 도메인 적응 방식이 이것이다. 가중치를 건드리지 않고 참고 자료를 state에 실어 보낸다.

write-post.md에 이미 적혀 있는 규칙 문단을 state에 함께 넣고 다시 돌렸다. 입력이 문장당 100토큰에서 450토큰으로 늘었다. 게이트에 있는 단어 쪽은 데이터 누출이다. 그 참고 자료가 게이트 단어와 예외 단어를 이름으로 나열하기 때문이다. 그래서 그쪽은 "참고 자료를 읽기는 하는가"를 보는 대조군이고, 진짜 시험은 게이트에 없는 단어다.

지연은 M2 Max에서 돌린 로컬 추론이라 앞에서 본 Jev의 API 지연과 같은 축이 아니다. 여기서 볼 것은 절대값이 아니라 참고 자료를 넣었을 때의 2.4배다.

균형 잡힌, 게이트에 없는 단어에서 문장 단위 정확도가 0.500에서 0.500으로, 전혀 움직이지 않았다. 단어 단위로는 7/13에서 5/13으로 오히려 내려갔다.

게이트에 있는 단어의 0.225에서 0.676은 실력 향상이 아니다. 전에는 102문장 전부에 "되돌린다"고 했고, 참고 자료를 주자 12문장에만 그렇게 답했다. 그대로 둘 문장이 0/79에서 68/79로 올랐지만 되돌릴 문장이 23/23에서 1/23으로 무너졌다. 그 집합은 그대로 둘 문장이 79대 23으로 많으니 "대체로 두라"는 상수가 자동으로 더 높은 점수를 받는다. 구별을 배운 것이 아니라 기울기를 바꾼 것이다.

그렇다고 모델이 문장을 읽지 않는 것은 아니다. 같은 단어의 같은 문장들인데 참고 자료를 주자 문장마다 예측이 흩어졌다. 로더의 표준편차가 0.096에서 0.217로, 뮤테이션이 0.042에서 0.236으로 늘었다. 읽기는 하는데 구별을 못 한다.

그리고 이 결과는 앞 절의 해석을 흔들기도 한다. state 텍스트 하나로 출력이 통째로 뒤집힌다면, 첫 실행의 "전부 되돌린다"도 모델의 한계가 아니라 질문 문구의 부족일 수 있다. 이 글은 그 가능성을 배제하지 못했다.

한 가지는 눈에 띄게 좋아졌다. "되돌린다"와 "그대로"의 확률 합이 게이트에 없는 단어에서 1.508에서 0.963으로 붙었고, 1에서 크게 벗어난 문장이 59개에서 18개로 줄었다. 그런데 정확도는 움직이지 않았다. 두 질문의 확률이 서로 맞아떨어지는 것과 그 확률이 맞는 것은 다른 일이다.

결정 모델의 자리

여기까지 보면 이 모델 범주 전체가 쓸모없다는 결론으로 기울기 쉬운데, 공개된 벤치마크를 나란히 놓으면 그렇지 않다.

rerank 행만 검색 순위 품질 지표라 다른 행의 정확도와 축이 다르다.

분포 안에서는 정규식이나 맞춰 놓은 분류기가 이기거나 비긴다. 필자의 게이트에 있는 단어에서 정규식이 1.000 대 0.225로 이긴 것과 같은 자리다. 라벨을 모을 수 있으면 작은 모델을 학습시키는 편이 더 싸고 더 빠르고 더 정확하다. 그건 예전부터 하던 일이다.

격차는 분포가 새롭고 라벨이 없을 때 벌어진다. 분포 밖 스팸에서 98.6% 대 73.0%다. 맞춰 놓은 분류기는 자기가 본 적 없는 모양 앞에서 무너지는데 이쪽은 버틴다. 결정 모델의 자리는 데이터를 모으고 라벨을 붙여 학습시킬 수 없는 판단이다. 매번 상황이 새로워 라벨을 못 모으는데 판단은 초 단위로 내려야 하는 곳이다.

필자의 음차 판별이 왜 실패했는지도 이 틀로 설명된다. 그 판단에 필요한 것은 일반적인 추론이 아니라 한국어 기술 문서에서 어떤 말이 정착했는가라는 특정 도메인 지식이고, 영어 결정 과제로 학습한 9B 재현 구현에게 그건 분포 밖이 아니라 그냥 없는 지식이다. 규칙을 글로 줘도 안 된 이유가 여기 있다.

TechCrunch 기사에서 Pi harness를 만드는 Earendil의 CTO Armin Ronacher가 이렇게 말했다.

At the end of the day, it delegates the hallucination problem a little bit to the user.

환각을 없앤 것이 아니라 판단을 개발자에게 넘긴 것이다. TypeSafe 문서도 calibration은 예측 묶음에 대해 성립하는 성질이지 개별 답이 맞는다는 보장이 아니라고 적고 있고, 공개 발표 글의 환각률 0% 막대 아래 Nuance 항목에는 "Our number is not empirical"이라고 적혀 있다. 형식은 보장되고 내용은 아니다.

jevable의 194개 프로젝트

필자의 데이터에서는 실패했으니 다른 사람들은 어디에 쓰는지 봤다. jevable.com은 Nikunj라는 개발자가 X에 올라온 Jev 프로젝트를 심사해 모은 독립 큐레이션이다. 2026년 9월 23일 기준 194개이고 등록일은 9월 16일부터 20일 사이에 몰려 있다. 152개가 9월 18일 하루에 들어왔다. 공개 사흘 뒤다.

카테고리보다 "무엇을 묻는가"로 다시 묶으면 세 모양이 나온다. 아래 수치는 전부 게시자가 자기 게시물에 적은 값이다.

첫째, 분류와 라우팅. 이메일 1,500건 분류, 세금 서류 분류, 경쟁사 광고 1,891건을 19초에 $0.12로 분류, PR diff 하나에 typed check 14개, Android 알림에서 광고 판별, 건설 도면 26장을 2.9초에 분류. 앞 절의 표가 말한 대로 라벨이 매일 쌓이는 자리라, 시간이 지나면 자기 라벨로 학습한 작은 분류기가 이기거나 비긴다. Jev의 이점은 라벨이 없는 첫날에 있다.

둘째, 행동 선택 루프. Browser Use에 붙여 항공권 검색을 7초에 $0.0039로 끝냈다는 browser agent, 음성으로 Mac을 조작하는 computer use, Mario가 죽을 때마다 VM을 네 갈래로 fork해 살아남는 쪽을 고르는 게임, 3D 캐릭터의 입과 눈썹과 시선 등 열 가지를 메시지마다 결정하는 표정 엔진. 매 스텝 action space가 바뀌므로 라벨을 모을 수 없고, 판단은 초 아래로 내려야 한다. 분포 밖 스팸에서 격차가 벌어진 것과 같은 자리다. Games가 39개로 가장 큰 카테고리인 이유도 여기 있다고 본다. 게임은 틀려도 되돌릴 수 있는 행동 선택 루프다.

셋째, 확률을 사용자에게 보여주는 UI. 답 대신 판정만 돌려주는 Ask Jev, 다음 질문을 확률로 고르는 분기 폼 JevForm, 기술 깊이와 드라마 같은 슬라이더 여섯 개로 Hacker News 첫 화면을 다시 정렬하는 Upweight. 임계값을 코드에 박지 않고 사람이 확률을 읽는 자리라, 이 글이 문제 삼은 calibration 요구가 가장 낮다.

한 가지가 눈에 띈다. 194개 설명문에서 비용을 적은 것이 30개, 속도를 적은 것이 53개인데, 정확도나 기준선을 적은 것은 7개다. 설명문이 원 게시물의 앞부분만 담으므로 하한이지만 방향은 분명하다. 빠르고 싸다는 것은 첫날 알 수 있고 맞는지는 재야 알 수 있는데, 재는 쪽이 드물다. 그 7개 중 하나가 jevcal이다. 다들 임계값을 감으로 고른다며, 자기 데이터와 목표 정확도를 넣으면 임계값과 자동 처리 비율을 돌려주는 도구다. 다음 절이 권하는 절차를 그대로 도구로 만든 것이다.

선을 긋는 절차

이 글의 결론은 이것이다. 모델이 돌려준 확률을 스펙처럼 읽지 말고, 자기 데이터에서 직접 재서 선을 그어야 한다.

재는 절차는 이렇다. 라벨이 있는 100건 남짓을 모아 확률 구간별 실제 적중률 표를 만들고, 임계값을 위에서부터 낮춰 가며 그 위 구간의 오차율을 본다. 오차 예산을 정했으면 그 예산을 지키는 최대 커버리지가 곧 자동화할 수 있는 비율이다. 필자의 실험에서 확신도 0.9 이상 구간의 실제 적중이 0.240이었다는 것은 102문장으로 드러났다.

눈금이 어긋난 것은 대개 고칠 수 있다. overconfidence가 전 구간에 고르게 깔려 있으면 온도 하나로 대부분 맞춰진다. Kev도 그렇게 해서 ECE를 0.106에서 0.042로 내렸다. 문제는 그 온도를 맞추려면 그 분포의 라벨이 필요하다는 것이고, 프로덕션에서 없는 것이 정확히 그것이다. 게다가 온도는 확률의 순서를 바꾸지 못하므로 자동화 가능 비율은 그만큼 안 올라간다. 그래서 눈금보다 순서가, ECE보다 오차 예산 커버리지가 더 실무적인 지표다.

문서가 예제에 쓴 0.9를 그대로 코드에 박았다면, 이 게이트는 조용히 38건을 잘못 고쳤을 것이다. 에러가 나지 않으므로 알아차리기 어려운 실패다. TypeSafe 문서도 그 예제 바로 아래에 자기 데이터로 시험해 보라고 적어 두었다. 코드에 박히는 것은 대개 그 아래 문장이 아니라 위의 숫자다.

키가 없어도 재는 것부터는 오늘 할 수 있다. Kev가 Apache-2.0으로 공개돼 있고 노트북에서 돈다.

지금 운영하는 서비스에서 큰 모델에게 예/아니오만 묻는 호출이 몇 개인지 세어 보면 좋겠다. 그 호출을 결정 모델로 옮기기 전에, 옮긴 다음 그어야 할 선이 어디인지를 먼저 재 보기를 권한다. 필자는 그 순서를 지켰기 때문에 게이트를 안 건드리기로 정할 수 있었다. Jev 키를 받으면 같은 집합을 다시 돌려 볼 생각이고, 그때 결론이 바뀌면 그것도 적겠다.

필자는 선언적인 코드를 좋아한다. 오버레이를 띄우고, 닫고, 그 안에서 비동기 처리를 하는 일련의 행위는 그 오버레이가 스스로 관리하는 편이 낫다고 생각한다. 호출하는 쪽이 isOpen을 들고 있다가 켜고 끄는 방식은 상태를 다루는 코드와 그 상태가 그려지는 컴포넌트를 서로 다른 자리에 떨어뜨려 놓는다.

그런데 필자가 회사에서 맡은 화면의 모달은 정확히 그 반대였다. 열림 여부를 전역 스토어에 담아 두고, 호출부가 열고 호출부가 닫았다. 모달을 닫는 코드와 결과를 받는 콜백까지 호출부가 직접 쓰고 있었다. 그래서 이것을 선언적인 방향으로 어떻게 옮길지 한참 고민했고, 결국 직접 갈아엎었다.

작업을 하면서 overlay-kit을 살펴보았다. 필자가 지향하는 인터페이스와 비슷했다. 이 글은 overlay-kit의 인터페이스의 선언적 인터페이스를 살펴보고, 어떻게 사내 modal 시스템을 설계했는지에 대해 기록해보겠다.

상태로 들고 있던 모달

필자는 상태 관리에 대한 글에서 모달의 열림 여부를 가장 단순한 로컬 상태의 예로 들었다. 한 컴포넌트 안에서만 쓰고 외부에서는 알 필요도 알 권리도 없는 상태라고 썼다. 그 말은 지금도 맞다고 생각한다. 다만 모달이 수십 종류가 되고, 서로 겹쳐 뜨고, 결과값을 호출부로 돌려줘야 하는 순간부터는 그 상태가 컴포넌트 안에 머물러 있지 않는다.

필자가 만난 코드는 열린 모달의 목록을 전역 스토어에 두고 있었다. 사내 코드라 아래 예시는 식별자를 바꿔 구조만 옮긴 것이다.

const [openPopup, closePopup] = useModalStore(
  useShallow((state) => [state.openPopup, state.closePopup]),
);
 
const handleAddNote = useCallback(() => {
  openPopup(PopupType.ADD_NOTE, {
    itemId,
    onClose: () => closePopup(PopupType.ADD_NOTE),
    onSubmit: (note) => {
      closePopup(PopupType.ADD_NOTE);
      saveNote(note);
    },
  });
}, [closePopup, openPopup, itemId]);

이 코드가 불편했던 자리는 셋이다.

첫째, 여는 함수를 훅으로 꺼내야 한다. openPopup과 closePopup은 스토어에서 선택해 와야 하는 값이라 컴포넌트 안에서만 얻을 수 있다. 그래서 모달을 여는 코드가 컴포넌트 밖으로 나가지 못한다. API 응답을 가로채는 자리나 라우터 가드처럼 훅을 쓸 수 없는 곳에서 모달을 띄우려면 그 함수를 인자로 받아 내려보내야 한다.

둘째, 결과가 콜백으로 돌아온다. 노트를 저장했는지, 사용자가 그냥 닫았는지를 onSubmit과 onClose 두 갈래로 받는다. 모달을 띄운 뒤에 할 일이 있으면 그 일이 콜백 안으로 들어간다. 모달을 두 개 연달아 띄워야 하면 콜백 안에 콜백이 생긴다.

셋째, 닫는 책임이 호출부에 있다. closePopup(PopupType.ADD_NOTE)를 호출부가 부른다. 모달이 자기 자신을 닫는 것이 아니라, 모달을 연 쪽이 그 모달의 종류를 기억하고 있다가 닫는다. 그래서 같은 상수가 한 함수 안에 세 번 나온다.

셋의 공통점은 모달 하나를 띄우는 데 호출부가 세 가지 코드를 써야 한다는 것이다. 여는 코드, 결과를 받는 콜백, 그리고 닫는 코드다.

무엇을 띄울지 정하는 데까지가 호출부의 몫이라고 보면, 그 뒤의 일까지 호출부가 떠안고 있었다. 특히 closePopup(PopupType.ADD_NOTE)는 닫을 대상을 문자열 상수로 지목한다. 다른 모달의 상수를 적어도 같은 열거형이라 타입 검사를 통과하고, 엉뚱한 모달이 닫힌다.

결과를 기다리는 인터페이스

그러면 이 셋 중 무엇을 덜어낼 수 있을까. 필자가 도달한 답은 모달을 여는 것을 함수 호출로 두고, 그 함수가 종료 결과를 담은 Promise를 돌려주게 하는 것이었다.

const result = await openModalAsync('ADD_NOTE', { itemId });
if (result.reason !== 'confirmed') return;
 
await saveNote(result.value);

바뀐 것은 세 가지다. 여는 함수가 훅이 아니라 모듈 함수가 되면서 컴포넌트 밖에서도 부를 수 있게 됐다. 결과가 콜백의 인자가 아니라 반환값이 되면서 후속 작업이 호출 함수의 흐름 안에 남았다. 그리고 닫는 일은 모달 컴포넌트가 직접 하게 됐다.

반환 타입이 Promise<ModalResult<V>>가 되면서 모달의 종료가 값 하나로 모였다.

Promise는 한 번만 끝난다. 이미 끝난 Promise를 다시 resolve해도 아무 일이 일어나지 않으므로, 종료 사유를 그 값 하나에 전부 담아야 한다. 그래서 reason을 다섯 가지로 나눴다. 사용자가 확정했는지, 명시적으로 취소했는지, 값 없이 닫혔는지, 같은 종류의 새 모달로 교체됐는지, 전체 정리로 강제 종료됐는지다. 불리언 하나로 두면 "취소"와 "화면이 통째로 정리됨"이 같은 값이 되는데, 뒤처리가 필요한 흐름에서는 그 둘을 구분해야 했다.

반대로 끝내지 않으면 호출부는 영원히 기다린다. 콜백은 부르지 않아도 아무 일이 없지만 await는 반환되지 않은 채로 남는다. 그래서 모달을 화면에서 걷어내는 경로가 늘어날 때마다 그 경로도 Promise를 끝내는지 확인해야 했다. 교체와 강제 종료가 각자 reason을 하나씩 가진 것이다.

overlay-kit의 호출부

toss overlay-kit 호출부는 이렇게 생겼다.

const confirmed = await overlay.openAsync<boolean>(({ isOpen, close }) => (
  <ConfirmDialog
    open={isOpen}
    onConfirm={() => close(true)}
    onCancel={() => close(false)}
  />
));

필자가 좋은 인터페이스라고 생각한 지점은 셋이다.

무엇이 열리는지가 호출부에 있다. 필자가 만든 쪽은 'ADD_NOTE'라는 문자열 key를 넘긴다. 그 key가 어느 컴포넌트인지는 registry 파일이 알고 있다. 문자열 key와 그 모달을 가져오는 import() 함수를 짝지어 둔 객체 하나가 들어 있는 파일이다.

export const modalImporters = {
  ADD_NOTE: () => import('.../add-note-modal'),
  CONFIRM: () => import('.../confirm-modal'),
  // 모달 종류만큼 이어진다
} as const;

overlay-kit은 JSX를 그 자리에 쓴다. 코드를 읽는 사람이 이 파일로 이동하지 않아도 무엇이 뜨는지 안다.

결과의 타입이 호출부에서 정해진다. openAsync<boolean>의 타입 인자가 곧 close의 인자 타입이고 await의 결과 타입이다. 모달마다 결과 타입을 따로 선언하고 표에 등록할 필요가 없다.

닫는 것과 지우는 것이 나뉘어 있다. 컨트롤러가 받는 props는 overlayId, isOpen, close, unmount 넷이다. close는 isOpen을 false로 만들고 컴포넌트는 그대로 둔다. unmount가 실제로 제거한다. 공식 문서의 오버레이 열고 닫기 안내는 이렇게 설명한다.

이러한 차이가 발생하는 이유는 close를 사용할 때 오버레이가 닫히는 애니메이션을 보여주기 위해서 메모리에 계속 남겨두기 때문이에요.

필자가 만든 쪽에는 이 구분이 없다. 닫으면 목록에서 바로 빠진다. 그래서 닫기 애니메이션을 라이브러리의 컴포넌트에 맡기고 있고, 그것이 가능한 화면만 다루고 있었다는 뜻이기도 하다.

overlay.open에서 렌더까지

인터페이스가 마음에 들면 그다음 궁금한 것은 안이다. 모듈 함수 하나가 React 트리 안에 컴포넌트를 그리려면 그 사이를 잇는 무언가가 있어야 한다.

이벤트와 리듀서

overlay.open은 상태를 바꾸지 않는다. 이벤트를 하나 쏜다.

// packages/src/event.ts
const open = (controller: OverlayControllerComponent, options?: OpenOverlayOptions) => {
  const overlayId = options?.overlayId ?? randomId();
  const componentKey = randomId();
  const dispatchOpenEvent = createEvent('open');
 
  dispatchOpenEvent({ controller, overlayId, componentKey });
  return overlayId;
};

받는 쪽은 OverlayProvider다. Provider는 useReducer를 들고 있고, 이벤트를 구독해서 리듀서에 ADD를 넣는다. 여기서 주의해서 볼 것은 isOpen이 false로 들어간다는 점이다.

// packages/src/context/provider/index.tsx
const [overlayState, overlayDispatch] = useReducer(overlayReducer, {
  current: null,
  overlayOrderList: [],
  overlayData: {},
});
 
const open: OverlayEvent['open'] = useCallback(({ controller, overlayId, componentKey }) => {
  overlayDispatch({
    type: 'ADD',
    overlay: { id: overlayId, componentKey, isOpen: false, isMounted: false, controller },
  });
}, []);

그리고 컨트롤러가 마운트된 다음 프레임에 OPEN을 넣어 isOpen을 true로 만든다.

// packages/src/context/provider/content-overlay-controller.tsx
useEffect(() => {
  requestAnimationFrame(() => {
    overlayDispatch({ type: 'OPEN', overlayId });
  });
}, [overlayDispatch, overlayId]);

여기서 필자가 예상과 달랐던 부분이 있다.

상태가 React 밖에 있지 않다. 모듈 함수로 여는 API라서 스토어도 모듈 수준에 있을 줄 알았는데, 실제로는 Provider 안의 useReducer다. React 밖에 있는 것은 이벤트 버스뿐이고, 그것은 상태를 들지 않는다. 오버레이는 Provider의 children 옆에 형제로 렌더된다. createPortal을 쓰지 않고, react-dom을 import하지도 않는다.

한 가지 더 눈에 띄는 것이 있다. 호출부에서 보면 overlay.open() 한 줄인데, 그 안은 이벤트를 쏘고, 리듀서에 ADD를 넣고, 한 프레임 기다렸다가 OPEN을 다시 넣는 순서가 정해진 절차다. 선언적인 인터페이스가 명령형 코드를 없앤 것이 아니라 경계 안쪽으로 옮긴 것이다.

여는 쪽과 닫는 쪽

앞에서 본 requestAnimationFrame과, 그 앞 절에서 본 close와 unmount의 분리는 얼핏 별개로 보인다. 실제로는 같은 제약의 양쪽 끝을 각각 막는 장치다.

그 제약은 CSS 트랜지션이 시작 상태와 끝 상태를 둘 다 실제로 렌더해야 돈다는 것이다. MDN의 CSS 트랜지션 문서가 DOM에 막 추가한 요소에 대해 이렇게 경고한다.

This is treated as if the initial state had never occurred and the element was always in its final state.

여기서 실패가 두 모양으로 나온다. 열 때는 시작 상태가 없어서 안 돌고, 닫을 때는 끝 상태가 그려지기 전에 요소가 사라져서 안 돈다.

닫는 쪽이 사용자 몫인 이유가 마지막 줄에 있다. 여는 쪽은 한 프레임이면 된다는 상수를 라이브러리가 안다. 닫는 쪽은 애니메이션이 200밀리초인지 400밀리초인지 라이브러리가 알 수 없다.

unmount로 넘긴 닫기

닫는 쪽이 성립하는 근거는 리듀서에 있다. CLOSE는 overlayData의 isOpen만 뒤집고 overlayOrderList는 건드리지 않는다. Provider가 그 목록을 순회해 렌더하므로, 목록에 남아 있는 동안 컴포넌트는 살아 있다. REMOVE가 목록에서 빼야 비로소 언마운트된다.

다만 rAF가 항상 필요한 것은 아니다. react-transition-group은 기본적으로 첫 마운트에서 enter 트랜지션을 실행하지 않는다. in이 이미 true여도 건너뛰고, appear를 켜야 한다. overlay-kit의 rAF는 isOpen을 마운트 이후에 false에서 true로 바꿔 주므로 이 경우를 덮는다.

Promise로 감싸는 20줄

openAsync는 별도의 구현이 아니라 open을 감싼 얇은 층이다.

// packages/src/event.ts
const openAsync = async <T>(controller: OverlayAsyncControllerComponent<T>, options?: OpenOverlayOptions) => {
  return new Promise<T>((_resolve, _reject) => {
    open((overlayProps, ...deprecatedLegacyContext) => {
      const close = (param: T) => {
        _resolve(param);
        overlayProps.close();
      };
      const reject = (reason?: unknown) => {
        _reject(reason);
        overlayProps.close();
      };
      const props: OverlayAsyncControllerProps<T> = { ...overlayProps, close, reject };
      return controller(props, ...deprecatedLegacyContext);
    }, options);
  });
};

컨트롤러에 넘어가는 close를 바꿔치기하는 것이 전부다. 원래 close는 인자를 받지 않는데, 여기서는 인자를 받아 Promise를 resolve한 뒤에 원래 close를 부른다. 결과 타입이 호출부에서 정해지는 이유도 여기에 있다. T가 close의 인자 타입이자 Promise의 타입이다.

다만 이 구조에는 구멍이 하나 있다. resolve는 close가 불릴 때만 일어난다. 그래서 오버레이를 unmount로만 제거하면 Promise는 영원히 pending으로 남는다. 이슈 #169에 올라와 있고 해결이 필요하다고 생각하지만 아직 이슈가 오픈되어있다.

resolve 시점이 close라는 점은 또 다른 의미도 갖는다. 닫기 애니메이션이 끝난 시점이 아니라 닫기 시작하는 시점이다. 확인을 받고 API를 호출하는 흐름이라면 문제가 없지만, 확인을 받고 다음 모달을 여는 흐름이라면 앞 모달이 사라지는 동안 뒤 모달이 올라온다.

설계가 한 바퀴 돈 자리

설계 과정을 탐색해보기 위해 커밋 기록을 따라가 보았다. 그리고 이 구조가 처음부터 이랬던 것은 아니라는 것을 알게 되었다. 1.0은 지금과 같은 이벤트와 리듀서 조합이었다. 1.2.0에서 상태를 모듈 수준 외부 스토어로 옮기고 useSyncExternalStore로 읽게 바꿨다가, 1.8.0에서 다시 리듀서로 되돌렸다.

되돌린 이유는 이슈 #148에 적혀 있다.

useSyncExternalStore resolves tearing issues, but it doesn't work well with suspense.

오버레이 안에서 데이터를 가져오다 suspend하면 동기 입력에 응답하는 중에 컴포넌트가 suspend했다는 React 경고가 떴다. 외부 스토어로 옮긴 원래 목적은 훅 없이도 오버레이 상태를 읽게 하는 것이었는데, 의도대로 해결하지 못했다는 것이 당시 PR 본문에 적혀 있다. 결국 목적은 훅으로 해결됐고 저장 방식만 제자리로 왔다.

필자가 이 기록에서 얻은 것은 결론이 아니라 기준이다. 상태를 React 밖에 두면 호출 지점이 자유로워지는 대신 React의 스케줄링과 어긋날 여지가 생긴다. overlay-kit은 호출 지점만 밖에 두고 상태는 안에 뒀다.

같은 id로 다시 열었을 때

리듀서를 읽다가 걸린 부분이 있었다. ADD의 맨 앞에 이런 분기가 있다.

// packages/src/context/reducer.ts
case 'ADD': {
  if (state.overlayData[action.overlay.id] != null && state.overlayData[action.overlay.id].isOpen === false) {
    const overlay = state.overlayData[action.overlay.id];
    if (overlay == null || overlay.isOpen) {
      return state;
    }
    return {
      ...state,
      current: action.overlay.id,
      overlayData: { ...state.overlayData, [action.overlay.id]: { ...overlay, isOpen: true } },
    };
  }
  // ...

overlayId를 지정해 연 오버레이를 close한 뒤 같은 id로 다시 열면 이 분기를 탄다. 그런데 반환값이 기존 overlay 객체를 그대로 쓴다.

새로 들어온 action.overlay의 controller는 어디에도 쓰이지 않는다.

읽은 것만으로는 확신이 서지 않아 라이브러리 저장소를 받아 테스트를 직접 붙여 봤다. 서로 다른 내용을 그리는 컴포넌트 둘을 준비하고 같은 id로 순서대로 열었다.

const ControllerA = ({ isOpen }: { isOpen: boolean }) => (isOpen ? <div data-testid="b">AAA</div> : null);
const ControllerB = ({ isOpen }: { isOpen: boolean }) => (isOpen ? <div data-testid="b">BBB</div> : null);
 
overlay.open(ControllerA, { overlayId: 'id-close' });
overlay.close('id-close');
overlay.open(ControllerB, { overlayId: 'id-close' });

결과는 이랬다. overlay-kit 1.9.0 시점의 main 브랜치에서 vitest로 돌렸다.

세 번째 줄은 문서가 기능으로 설명하는 동작이라 예상한 대로다. 문제는 첫 줄이다.

무시되는 새 JSX

여기서 하나를 더 확인했다. 같은 리듀서의 뒷부분에는 이런 주석이 달려 있다.

/**
 * @description Brings the overlay to the front when reopened after closing without unmounting.
 */
overlayOrderList: [...state.overlayOrderList.filter((item) => item !== action.overlay.id), action.overlay.id],

닫았다가 다시 열면 맨 앞으로 가져온다는 설명이다. 그런데 앞의 분기가 먼저 return하기 때문에 이 줄은 그 상황에서 실행되지 않는다. 오버레이 둘을 겹쳐 열고 뒤에 깔린 쪽을 close한 뒤 다시 열어 봤더니, DOM 순서가 바뀌지 않고 그대로였다.

주석과 다른 실제 동작

다만 이것이 화면에서 곧바로 문제로 보이는지는 확인하지 않았다. 테스트는 DOM 순서까지만 봤고, 대부분의 다이얼로그 라이브러리가 자체 z-index나 포털을 쓰므로 DOM 순서가 곧 시각적 순서는 아니다.

필자가 만든 쪽은 같은 상황을 옵션으로 노출한다. 같은 종류의 모달을 다시 열 때 기존 것을 유지할지 새 props로 교체할지 호출부가 고른다. 교체를 고르면 기존 Promise는 replaced로 종료된다. 앞에서 결과 타입을 다섯 갈래로 나눈 이유 중 하나가 이것이다.

여기서 두 설계의 차이가 드러난다. 필자의 방식은 모달을 데이터로 다룬다. 문자열 key와 props가 스토어에 있으니 나중에 교체하거나 갱신할 수 있다. overlay-kit은 모달을 함수로 다룬다. 컨트롤러가 클로저라 한 번 저장되면 바깥에서 그 내용을 바꿀 방법이 없다.

호출부 JSX의 대가

그러면 호출부에 JSX를 쓰는 방식은 문자열 key 방식보다 언제나 나은가. 필자는 그렇지 않다고 생각한다. 치르는 값이 셋 있다.

코드 분할이 기본값에서 빠진다. 호출부가 JSX를 쓴다는 것은 호출부가 그 컴포넌트를 import한다는 뜻이다. 모달이 무거운 편집 화면이고 그 버튼을 누르는 사용자가 소수라면, 그 무게가 목록 화면의 번들에 들어간다.

컨트롤러 안에서 React.lazy가 동작한다. 앞의 테스트와 같은 방식으로 재 봤더니 open 전에는 모듈이 로드되지 않았고, 열었을 때 Suspense fallback이 먼저 뜬 뒤 본문이 렌더됐다.

const Heavy = React.lazy(() => import('./HeavyModal'));
 
overlay.open(({ isOpen, close }) => isOpen ? (
  <Suspense fallback={<Spinner />}><Heavy onClose={close} /></Suspense>
) : null);

그러니 차이는 가능 여부가 아니라 기본값이다.

필자가 만든 쪽은 registry 파일의 값이 전부 import() 함수라 코드 분할이 구조상 강제된다. overlay-kit은 호출부마다 손으로 써야한다.

unmount를 부르는 자리를 사용자가 정해야 한다. close만 부르고 끝내면 오버레이 정보가 메모리에 남는다. 공식 문서도 이 점을 경고하면서, 디자인 시스템마다 어디에 unmount를 걸어야 하는지를 따로 안내한다. MUI와 Mantine은 전환이 끝나는 콜백이 있어서 거기에 걸면 되지만, 그런 콜백이 없는 라이브러리에서는 애니메이션 길이만큼 타이머를 두라고 안내한다. 안내 문서가 라이브러리별로 나뉘어 있다는 사실 자체가 이 결정의 비용이다.

오버레이가 Provider 자리에서 렌더된다. 포털을 쓰지 않기 때문에 React Native에서도 같은 코드가 도는 이점이 있다. 반대로 OverlayProvider 아래에서 제공한 컨텍스트는 오버레이 안에서 보이지 않는다. 라우터나 폼 컨텍스트에 기대는 모달을 열 때 이 지점을 먼저 확인해야 한다.

선언적이라는 말의 범위

여기까지 쓰고 나니 한 가지가 걸린다. 필자는 이 인터페이스를 선언적이라고 부르며 글을 시작했는데, overlay.openAsync(...)는 어느 모로 보나 함수 호출이다.

정의부터 놓고 보자. React 공식 문서는 두 가지를 이렇게 가른다.

In React, you don't directly manipulate the UI--meaning you don't enable, disable, show, or hide components directly. Instead, you declare what you want to show, and React figures out how to update the UI.

같은 문서가 드는 비유가 더 선명하다. 명령형은 차에 탄 사람에게 길을 하나하나 불러 주는 것이고, 선언적인 쪽은 택시에 타서 목적지만 말하는 것이다.

선언적인 인터페이스는 명령형 절차를 없애는 것이 아니라 경계 반대편으로 옮기고 그 경계에 이름을 붙이는 것이다. 앞에서 본 overlay-kit의 내부가 정확히 그렇다. 호출부는 한 줄인데 안에서는 이벤트를 쏘고 두 번 dispatch하는 절차가 돈다.

그러면 각 프로젝트가 이 단어를 어디에 쓰는지 보자. overlay-kit의 문서는 기존 방식을 명령형이라고 부른다. 그때 가리키는 것은 useState로 열림 여부를 들고 이벤트 핸들러에서 그 값을 뒤집는 코드다. 반대로 선언적이라고 부르는 것은 오버레이를 상태가 아니라 동작으로 다루는 쪽이다. 토스 기술 블로그의 선언적인 코드에 대한 글은 이 단어를 더 넓게 정의한다. 선언적인 코드란 추상화 레벨이 높아진 코드이고, 오버레이를 띄우는 동작을 추상화한 훅이 그 예라는 것이다.

그래서 필자는 이 단어를 이렇게 좁혀 쓰기로 했다. 호출부가 닫는 코드를 쓰지 않는 것. 언제 닫을지, 닫히는 동안 무엇이 남아 있을지는 오버레이 쪽이 정하고, 호출부는 무엇을 띄울지와 결과로 무엇을 받을지만 적는다.

이 기준으로 보면 useState로 isOpen을 들고 있는 코드와 전역 스토어에 열린 목록을 두고 호출부가 닫는 코드는 같은 편에 있다. 저장 위치만 다를 뿐 닫는 문장을 호출부가 쓴다는 점은 같기 때문이다.

마치며

필자가 회사 코드에서 고친 것은 결국 저장 위치가 아니었다. 닫는 코드를 누가 쓰는가였다.

전역 스토어를 쓰던 시절에도 상태는 이미 컴포넌트 밖에 있었지만, 열고 닫는 문장은 여전히 호출부에 있었다. await 한 줄로 바꾼 뒤에야 그 문장이 모달 안으로 들어갔다.

overlay-kit은 같은 자리에 도달한 뒤 한 걸음을 더 갔다. 무엇을 띄울지까지 호출부에 적게 한 것이다. 필자는 그 인터페이스가 읽기에 좋다고 생각한다. 그리고 쓰는 동안 그 한 걸음의 값이 무엇인지도 알게 됐다.

모달을 함수로 다룰지 데이터로 다룰지의 차이였다. 호출부에 JSX를 쓰면 컨트롤러가 클로저가 되고, 클로저는 한 번 저장되면 바깥에서 내용을 바꿀 수 없다. 같은 id로 다시 열었을 때 새 JSX가 무시되는 것이 그 구조에서 나온다. 문자열 key로 다루면 모달이 스토어에 담긴 값이 되어 교체하고 갱신하고 코드 분할할 수 있지만, 호출부는 이름만 알게 된다.

라이브러리를 고를 때 인터페이스가 마음에 든다는 감각은 꽤 믿을 만한 신호라고 생각한다. 다만 그 감각이 정확히 무엇을 가리키는지 한 번은 말로 옮겨 봐야 한다. 옮겨 보지 않으면 마음에 든 것이 인터페이스인지 그 라이브러리를 쓰는 사람들의 평판인지 구분되지 않는다. 이 글을 읽는 독자 분들도 지금 쓰고 있는 라이브러리에 대해 한 번쯤 그 작업을 해보기를 권한다.

필자는 TypeSafe AI가 공개한 결정 모델 Jev의 주장을 검증하면서 이 개념부터 정리해야 했다. Jev는 문장 대신 선택지마다 확률을 돌려주고, calibration을 학습 목표로 내세운다. 그 주장을 따지려면 calibration이 무엇이고 기존 모델에서 왜 어긋나는지부터 알아야 했다.

정확도와 calibration

먼저 정확도와 Calibration을 구분해야 한다. 정확도는 몇 퍼센트 맞히느냐이고, calibration은 자기가 몇 퍼센트 맞힐지를 아느냐다. 강수 확률 70%라고 한 날들만 모았을 때 실제로 열 번 중 일곱 번 비가 왔다면 그 예보는 calibration이 잘 된 것이다. 정확도가 높다는 뜻이 아니다. 자기 한계를 안다는 뜻이다. 60%만 맞히는 모델도 스스로 60%라고 말하면 calibration은 만점이다.

눈금이 어긋나는 방향은 둘이다. 모델이 말한 확률이 실제 적중률보다 높으면 overconfidence, 낮으면 underconfidence라고 한다. 말한 확률을 가로축에, 그 확률 구간의 실제 적중률을 세로축에 놓으면 둘이 갈리는 자리가 한눈에 보인다. 이렇게 그린 그림을 reliability diagram이라고 부른다.

곡선이 대각선에 붙어 있으면 말한 만큼 맞힌 것이다. 대각선 아래로 처질수록 말한 확률에 비해 덜 맞힌다.

그 어긋남을 재는 지표가 ECE(expected calibration error)다. Guo et al. 2017의 정의를 따르면 확률 구간마다 "말한 확률"과 "실제 적중률"의 차이를 그 구간의 표본 비율로 가중해 평균한 값이고, 0이 완벽이다. 아래는 그 식을 옮긴 코드다. 10문제 중 6문제를 맞히는 모델이 매번 0.6이라고 말할 때와 매번 0.95라고 말할 때를 비교한다.

// Guo et al. 2017 의 식 (3). 구간은 등간격 10개(논문 실험은 15개), 경계는 왼쪽 닫힘
function ece(preds, M = 10) {
  const bins = Array.from({ length: M }, () => ({ n: 0, hit: 0, conf: 0 }))
  for (const { p, correct } of preds) {
    const b = bins[Math.min(M - 1, Math.floor(p * M))]
    b.n++
    b.hit += correct ? 1 : 0
    b.conf += p
  }
  return bins.reduce(
    (sum, b) => (b.n ? sum + (b.n / preds.length) * Math.abs(b.hit / b.n - b.conf / b.n) : sum),
    0,
  )
}
 
// 10문제 중 6문제를 맞힌다
const answers = Array.from({ length: 10 }, (_, i) => ({ correct: i < 6 }))
console.log(ece(answers.map((a) => ({ ...a, p: 0.6 }))).toFixed(3)) // 매번 0.6 이라고 말할 때
console.log(ece(answers.map((a) => ({ ...a, p: 0.95 }))).toFixed(3)) // 매번 0.95 라고 말할 때

2026-10-08에 Node v24.16.0으로 돌린 결과다.

0.000
0.350

정확도는 둘 다 0.6이다. 말한 확률만 바뀌었는데 ECE는 0에서 0.35로 올라간다. 그런데 식에 절댓값이 들어 있어서 ECE는 어긋남의 크기만 재고 방향은 모른다. 매번 0.25라고 말하면서 6문제를 맞혀도 ECE는 똑같이 0.35다. overconfidence인지 underconfidence인지는 reliability diagram이나 평균 확신도에서 정확도를 뺀 값을 봐야 안다.

RLHF의 목표 함수

그렇다면 사람의 피드백으로 다듬은 모델은 왜 이 눈금이 어긋날까. 먼저 RLHF(reinforcement learning from human feedback)가 무엇을 최적화하는지 봐야 한다. 사람의 선호 비교로 보상 모델을 세우는 골격은 Christiano et al. 2017에서 나왔고, 이것을 언어 모델에 옮긴 초기 작업이 Ziegler et al. 2019이며, InstructGPT가 지시 따르기에 적용했다. 이때 끌어올리는 값은 사람의 선호를 흉내 낸 보상 모델의 점수다. 언어 모델 쪽 작업은 강화학습을 시작하기 전 모델에서 너무 멀어지지 않도록 KL penalty를 보상에 더하고, InstructGPT는 사전학습 데이터의 기울기도 섞었지만(PPO-ptx), 끌어올리는 대상은 여전히 그 점수다.

챗봇에는 사람의 선호가 맞는 목표다. 문제는 그 선호가 불확실성을 드러낸 말투를 피하는 쪽으로 기울어 있다는 것이다. Zhou et al. 2024는 네 개의 공개 선호 데이터셋에서 주석자가 "I'm not sure, maybe" 같은 약화 표현이 든 답을 덜 고른다는 것을 보였다. 차이는 작지만 유의했다. 다만 확신을 강조한 표현이 든 답을 더 고르지는 않았다. Leng et al. 2025는 보상 모델이 답의 실제 품질과 상관없이 높은 확신 점수를 적은 답에 점수를 더 준다는 것을 보였다. 둘 다 토큰 확률이 아니라 문장 속 확신 표현(verbalized confidence)에 대한 결과다. RLHF를 대신할 학습법을 내놓은 TypeSafe도 자사의 입문 문서에서 RLHF가 자신 있게 들리는 환각(confident-sounding hallucinations)을 보상할 수 있다고 적는다. 대안을 파는 쪽의 입장이다.

GPT-4의 calibration 곡선

토큰 확률에서도 같은 방향의 어긋남이 관측됐다. GPT-4 기술 보고서 본문의 Figure 8은 사전학습 모델과 post-training 모델의 reliability diagram을 나란히 놓는데, 캡션이 이렇다.

Right: Calibration plot of the post-trained GPT-4 model on the same subset of MMLU. The post-training hurts calibration significantly.

가로축은 MMLU 객관식 문제의 보기 A, B, C, D 각각에 모델이 매긴 확률(logprob)이고, 세로축은 그 구간의 실제 적중률이다. Figure 8에 찍힌 숫자로는 사전학습 모델의 ECE가 0.007이고 PPO(RLHF에서 보상 모델의 점수를 높이는 쪽으로 모델을 갱신할 때 쓰는 강화학습 알고리즘)를 거친 모델이 0.074다. 열 배 넘게 나빠졌다.

Figure 8의 오른쪽(PPO) 패널에서 0.4 이상 구간의 막대는 대각선 아래에 있지만 0.1에서 0.3 사이 구간은 오히려 대각선 위다. 0.1에서 0.9 사이 막대는 실제 적중률 약 0.3에서 0.5에 평평하게 몰려 있어서, 모델이 말하는 확률이 올라가도 적중률이 거의 따라 오르지 않는다. 0.074에는 이 underconfidence 구간도 섞여 있다. 그리고 Guo et al.이 지적했듯이 reliability diagram은 구간마다 표본이 몇 개인지 보여주지 않으므로, 막대가 대각선에서 떨어진 거리와 그 구간이 ECE에 보탠 몫은 비례한다고 볼 수 없다.

이 패널은 위 개념도와 두 가지가 다르다. 먼저 개념도의 곡선처럼 대각선 아래로만 처지지 않고, 대각선을 한 번 가로지른다. 또 보기 네 개의 확률을 전부 구간에 넣었으므로, 위 코드처럼 고른 답 하나의 확률로 재는 정의와도 다르다. 그래서 0.074와 위 코드의 0.35를 같은 눈금에 놓고 비교하지는 않는다.

그러면 왜 나빠졌을까. 보고서 본문은 사전학습 모델이 잘 calibration되어 있었고 post-training 뒤에 calibration이 줄었다고만 적고, 원인은 말하지 않는다. 단서는 Anthropic의 Kadavath et al. 2022에 있다. 이들이 자기 언어 모델로 학습한 RLHF 정책은 겉보기에 calibration이 매우 나빴다. 논문은 이것이 놀랍지 않다며, RL fine-tuning이 보상을 가장 많이 받는 행동 쪽으로 예측을 몰아주는 경향이 있기 때문이라고 적었다. 본론이 아니라 짧게 덧붙인 실험이다. 그런데 모든 평가에 같은 온도 T=2.5 하나를 적용하자 세 평가에서 calibration 문제가 대부분 풀렸다. 온도는 logit을 나누는 값이고, 1보다 크면 답의 순서는 그대로 둔 채 확률 분포만 평평하게 편다. 필자는 값 하나로 대부분 풀렸다는 결과를, 어긋남이 일부 구간에 몰린 것이 아니라 분포 전체가 한쪽으로 좁혀진 모양이라는 뜻으로 읽는다. 논문은 더 강한 RL 학습은 이렇게 고칠 수 없는 방식으로 calibration을 망가뜨릴 수 있다는 단서도 함께 달았다.

이것은 Anthropic 모델의 결과라서 Figure 8의 원인으로 바로 옮길 수는 없다. 앞 절의 연구들도 문장 속 확신 표현을 다뤘다. 사람이 불확실한 말투를 피한다는 결과와 토큰 확률의 어긋남을 직접 이어 주는 1차 근거는 필자가 찾지 못했다.

코드가 받는 확률

Figure 8의 확률은 토큰의 로그 확률이다. 같은 종류의 값을 받으려면 OpenAI API 명세대로 Chat Completions 요청에 logprobs를 true로 주고, top_logprobs로 토큰 위치마다 받을 후보 수를 0에서 20 사이로 정한다. 모델에게 답과 함께 확신도를 숫자로 말하게 해서 받는 값은 문장으로 말한 확신이고, 토큰 확률과는 다른 값이다.

두 값을 다룬 연구는 서로 다른 짝을 비교한다. Tian et al. 2023은 ChatGPT, GPT-4, Claude 같은 RLHF 모델 안에서 문장으로 말한 확신이 조건부 확률보다 대체로 calibration이 좋았고, 세 벤치마크에서 ECE를 상대적으로 50% 가량 줄인 경우가 많았다고 보고했다. 다만 이 비교에서 가중치가 공개되지 않은 모델의 조건부 확률은 API의 토큰 확률이 아니라 같은 질문을 10번 샘플링해 답이 나온 비율로 추정한 값이다. 앞서 본 Leng et al.은 RLHF 이전 모델과 견주어 RLHF 모델이 문장으로 말한 확신에서 더 overconfident하다고 보고했다. 두 결과는 함께 성립할 수 있다. 그리고 0.074는 2023년 GPT-4 post-training 모델이 MMLU 일부에서 낸 값이라, 지금 API로 부르는 모델에 그대로 옮길 수 없다.

마무리

정리하면, calibration은 몇 퍼센트 맞히느냐가 아니라 자기가 몇 퍼센트 맞힐지 아느냐의 문제이고, ECE는 그 어긋남의 크기를 재는 숫자다. 방향은 reliability diagram이나 평균 확신도에서 정확도를 뺀 값을 봐야 안다. RLHF는 사람의 선호를 흉내 낸 보상 모델의 점수를 끌어올린다. Kadavath et al.은 그 최적화가 보상을 많이 받는 쪽으로 예측을 좁히는 경향이 있다고 본다. 사람은 불확실성을 드러낸 답을 덜 고르고, 보상 모델은 품질과 상관없이 높은 확신 점수를 적은 답에 점수를 더 준다는 연구가 있다. GPT-4에서는 post-training 뒤 ECE가 0.007에서 0.074로 찍혔지만, OpenAI는 그 원인까지 적지는 않았다. 코드가 받는 확률이 토큰 확률인지 문장으로 말한 확신인지에 따라 calibration도 다르게 나오므로, 어느 쪽이든 자기 데이터에서 다시 재야 한다.

Calibration을 학습 목표로 내세운 결정 모델 Jev의 확률이 실제로 정직한지는 결정 모델, Jev와 Kev에서 다룬다.

이 글을 읽는 독자 분들도 모델이 돌려준 확률을 코드에 임계값으로 박기 전에, 그 모델이 무엇을 목표로 학습됐고 자기 데이터에서 눈금이 맞는지 한 번쯤 재 보시길 바란다.

개발을 하면서 필자가 코드를 작성하는만큼 시간을 많이 할애하는 것은 무엇을 만들어야 하는지 알아내는 일이다. 기획자와 요구사항을 주고받고, 디자이너와 화면을 맞추고, 도메인을 아는 사람과 용어에 대해 무엇을 뜻하는지 묻는다. 그리고 이 과정이 어긋났을 때의 비용이 코드를 잘못 쓴 비용보다 훨씬 크다는 것을 몇 번 겪었다.

최근에 James Samuel이 쓴 엔지니어링 리더의 일상 활동이라는 글을 읽었다. 저자는 리더의 업무를 여섯 가지로 나누는데, 가장 먼저 다루는 것이 정보 수집이었다. 모든 결정과 방향과 행동이 지금 무슨 일이 벌어지고 있는지에 대한 정확한 이해에 의존한다는 이유에서다.

필자는 언젠가 리더 역할을 하고 싶다는 생각을 갖고 있는데, 이 대목을 읽고 나서 든 생각은 조금 달랐다. 리더가 가장 먼저 다루는 일이 정보 수집이라면, 실무자에게 그 대응물은 요구사항 파악이다. 지금 요구사항을 다루는 방식이 나중에 조직의 정보를 다루는 방식이 될 것이다.

이 글에서 리더십에 관한 이야기를 하려는 것은 아니다. 지금 실무자로서 타직군과 소통할 때 무엇을 잘못하고 있었고 무엇을 도구로 쓸 수 있는지에 대한 이야기다. 결론부터 말하면 필자는 이 문제가 태도만의 문제가 아니라고 생각하게 됐다. 그 대신 쓸 수 있는 표현으로 공유 언어(ubiquitous language)라는 내용이 있는데, 무엇인지 알아보자.

같은 단어, 다른 뜻

Martin Fowler는 Bounded Context 글에서 전기 회사 사례를 든다. 필자가 겪은 어긋남의 상당 부분은 이 형태였다.

여기서 'meter'라는 단어는 조직의 서로 다른 부분에서 미묘하게 다른 뜻이었다. 전력망과 한 장소의 연결인지, 전력망과 한 고객의 연결인지, 아니면 물리적 계량기 자체인지.

here the word 'meter' meant subtly different things to different parts of the organization: was it the connection between the grid and a location, the grid and a customer, the physical meter itself

같은 "meter"라는 단어가 조직의 부서마다 미묘하게 다른 것을 뜻했다는 것이다. 그리고 Fowler는 이런 혼란이 특정 사례의 우연이 아니라고 덧붙인다. Customer나 Product 같은 다의어에서 같은 혼란이 계속 반복되는 것을 봐왔다는 것이다.

이건 회의 참가자들이 회의를 잘 못해서 생긴 일이 아니었다. 조직에 서로 다른 맥락이 있으면 같은 단어가 갈라지는 것이 자연스럽고, 그것을 방치하면 코드까지 갈라진다.

이 이야기의 기술적 배경에 대해서는 도메인 모델에서 한 번 다뤘다. 그때는 코드 안에서 모델을 어떻게 표현할지를 이야기했다. 이 글에서는 그 모델이 만들어지기 전, 사람들 사이의 대화 단계를 다룬다.

두가지 의미의 단어

그런데 왜 이런 일이 구조적으로 반복되는 걸까. 두 갈래의 설명이 있다.

하나는 조직 구조 쪽이다. Mel Conway가 1968년 Datamation에 실은 논문 How Do Committees Invent?는, 조직이 자신의 커뮤니케이션 구조를 유연하게 바꾸지 못하는 만큼 그 조직은 자기 이미지를 만들어내는 모든 설계물에 찍어낸다고 말한다. 흔히 Conway의 법칙으로 인용되는 한 문장은 사실 저자가 훗날 스스로 정식화한 표현인데, 1968년 본문의 이 서술이 더 직접적이라고 느껴진다.

필자가 이 문장에서 실무적으로 읽어낸 부분은 "찍어낸다"는 표현이다. 용어가 갈라지는 것이 대화에서 끝나지 않고 산출물에 그대로 남는다는 얘기이기 때문이다. 앞의 "meter"이 그렇다. "meter"의 범위를 서로 다르게 이해한 채로 각자 만들면, 그 차이는 회의록이 아니라 테이블 이름과 API 응답 필드와 화면의 문구에 남는다. 그리고 그때부터는 고치는 비용이 대화를 한 번 더 하는 비용과 비교가 안 되게 커진다.

여기서 실무자가 할 수 있는 일과 할 수 없는 일이 갈린다. 조직의 커뮤니케이션 구조를 바꾸는 것은 실무자의 손을 벗어난다. 그런데 용어의 경계를 눈에 보이게 만드는 것은 지금 자리에서 할 수 있다. 이 문서에서 말하는 단어의 뜻이 어느 범위인지 적어두고, 다른 팀이 쓰는 단어와 다르다면 다르다고 명시하는 일이다. 뒤에서 볼 도구들이 전부 그 일을 쉽게 만들어주는 장치다.

다른 하나는 조금 더 근본적이다. 인지과학 쪽에서 보면 협업은 애초에 공유된 배경 위에서만 성립한다. Herbert Clark과 Susan Brennan이 1991년에 쓴 Grounding in Communication은 피아노 듀엣을 예로 들며 시작한다. 두 연주자는 방대한 양의 공유 정보, 즉 common ground를 가정하지 않고는 내용을 맞추는 일조차 시작할 수 없다는 것이다. 여기서 common ground는 상호 지식과 상호 신념, 상호 가정을 뜻한다. 그리고 저자들은 모든 집단 행동이 common ground와 그것의 축적 위에 세워진다고 못 박는다.

필자가 이 두 갈래를 나란히 놓고 본 뒤에 얻은 관점은 이렇다. 용어가 어긋나는 것은 사고가 아니라 기본 상태다. 맞춰져 있는 상태가 오히려 유지 비용을 들여야 하는 예외다. 그러면 그 비용을 누가 어떻게 지불할 것인가가 실무의 질문이 된다.

적극적인 감시

Evans는 2003년에 낸 Domain-Driven Design에서 ubiquitous language, 우리말로 옮기면 편재하는 언어 혹은 공유 언어라는 패턴을 제시한다. 흔히 "개발자와 도메인 전문가가 같은 용어를 쓰자"는 정도로 요약되지만, 원서를 읽어보면 처방이 훨씬 구체적이다. 모델을 언어의 뼈대로 삼고, 팀 내 모든 커뮤니케이션과 코드에서 그 언어를 끈질기게 쓰기로 팀이 약속하라고 요구한다. 그리고 그다음에 이어지는 문장이 필자에게 가장 중요했다.

도메인 전문가는 도메인 이해를 전달하기에 어색하거나 부적절한 용어 또는 구조에 이의를 제기하고, 개발자는 설계에 문제를 일으킬 모호함이나 비일관성을 살핀다.

Domain experts object to terms or structures that are awkward or inadequate to convey domain understanding, while developers watch for ambiguity or inconsistency that will trip up design.

도메인 전문가는 도메인 이해를 전달하기에 어색하거나 부족한 용어와 구조에 이의를 제기하고, 개발자는 설계를 넘어뜨릴 모호함이나 비일관성을 감시한다는 것이다.

이 문장을 읽고 필자는 자기 역할에 대한 이해를 고쳤다. 그동안 필자는 요구사항 회의에서 스스로를 수신자로 여겼다. 기획이 정해지면 그것을 정확히 받아서 구현하는 것이 필자의 일이라고 생각했다. 그런데 Evans가 규정한 개발자의 몫은 수신이 아니었다. 모호함을 발견해서 되돌려주는 것이다. 이건 소극적 협조가 아니라 적극적 감시다.

(참고로 Fowler는 자신의 글에서 이 문장을 "Domain experts should object ... developers should watch" 로 옮겼다. 원서에는 조동사가 없다. 사소한 차이지만 원서 쪽이 더 단정적으로 읽힌다. 그렇게 하는 것이 좋다는 권고가 아니라, 그렇게 하는 것이 이 패턴의 정의라는 어조다.)

그렇다면 모호함은 어떻게 발견할까. Evans는 여기에도 답을 준다. 대화에서 반복해서 쓰면 용어 해석의 차이가 드러난다는 것이다. 필자는 이 문장을 이렇게 읽었다. 모호함은 문서를 정독해서 찾는 게 아니다. 기획서를 아무리 꼼꼼히 읽어도 "meter"이라는 단어가 여러 가지를 뜻한다는 사실은 드러나지 않는다. 그 단어를 실제 사례에 대고 반복해서 써봐야 갈라진다. "다른 분들은 meter 를 어떤 의미로 이해하고 계신가요?" 같은 질문이 나오는 순간이 그 지점이다.

최소 협력 노력의 원리

우리는 이 방법을 알고도 실천하지 못한 시기가 있을것이다. 그럼 왜 반복해서 물어보지 않았을까?

다시 Clark과 Brennan의 논문으로 돌아가보자. 저자들은 말한 것을 common ground의 일부로 만들어가는 과정에 grounding이라는 이름을 붙인다. 그리고 사람들이 이 과정에서 어떻게 행동하는지에 대해 원리 하나를 제시한다. 최소 협력 노력의 원리(the principle of least collaborative effort)다. 사람은 필요한 것보다 더 열심히 일하기를 좋아하지 않는다는 관찰에서 나온 원리다.

여기서 중요한 대목이 나온다.

최소 협력 노력의 원리에 따르면, 사람들은 필요한 만큼의 공동 노력만 들여 서로의 이해를 맞추려 해야 한다. 그러나 어떤 일에 노력이 드는지는 소통 매체에 따라 크게 달라진다.

By the principle of least collaborative effort, people should try to ground with as little combined effort as needed. But what takes effort changes dramatically with the communication medium.

노력이 드는 지점이 매체에 따라 극적으로 달라진다는 것이다. 어떤 매체에서 쓸 수 있는 확인 기법이 다른 매체에서는 아예 불가능하거나, 가능하더라도 비용이 훨씬 크다. 저자들은 특히 말하는 즉시 상대가 받지 못하는 매체에서는 남이 오해를 고쳐주기를 기대하는 비용이 매우 커지므로, 말하는 사람이 그걸 피하려 든다고 지적한다.

여기서 한 가지 짚고 갈 것이 있다. 이 논문은 1991년에 쓰였고, 저자들이 비교한 매체는 대면 대화와 전화, 편지, 자동응답기 같은 것들이다. 슬랙이나 노션을 다루지 않는다. 매체에 따라 grounding 비용이 달라진다는 틀은 저자들의 것이고, 그것을 지금의 비동기 업무 채널에 적용하는 것은 필자의 해석이다.

그렇게 적용해서 보면 필자가 왜 반복해서 묻지 않았는지가 설명된다. 기획서를 텍스트로 받아서 텍스트로 확인하는 환경에서, 애매한 지점마다 확인 메시지를 보내는 일은 비용이 크다. 답이 언제 올지 모르고, 여러 번 물으면 이해하지 못한 것처럼 보일까 걱정된다. 그러니 사람은 자연스럽게 자기 해석으로 넘어간다.

여기서 힘이 두 개라는 점을 구분해둘 필요가 있다. 하나는 매체가 확인 비용을 올린다는 것이고, 이건 Clark과 Brennan의 얘기다. 다른 하나는 여러 번 물으면 무능해 보일까 걱정하는 것인데, 이건 그들의 원리가 예측하는 바가 아니라 뒤에 나올 심리적 안전감 쪽 이야기다. 정확히 말하면 최소 협력 노력의 원리가 예측하는 것은 더 싼 확인 방법을 고른다이지 확인을 그만둔다가 아니다. 확인을 접고 추측으로 넘어가는 것은 원리의 작동이 아니라 grounding의 실패다. 그리고 그 해석이 틀렸다는 사실은 구현이 끝난 뒤에 드러난다.

충분한 수준까지의 도달

그러면 애매한 것마다 다 물어봐야 하는 걸까. 그건 현실적이지 않고, 필자는 그렇게 하는 사람도 본 적이 없다. 이 질문에 대해서도 논문이 기준을 제시한다. grounding criterion이다. 상대가 말한 사람의 뜻을 현재 목적에 충분한 수준까지 이해했다고 양쪽이 서로 믿는 상태를 가리킨다. 저자들은 그 앞에 완벽한 이해는 애초에 불가능하다는 문장을 덧붙여 둔다.

필자에게 이 기준이 실용적으로 느껴진 이유는 목표를 낮춰주기 때문이다. 요구사항을 완벽하게 이해할 필요는 없다. 지금 하려는 일에 충분한 만큼 서로 믿을 수 있으면 된다. 그리고 저자들은 목적이 바뀌면 기준도 바뀌어야 한다고 말한다.

이 부분이 실무에서는 확인의 강도를 조절하는 기준이 된다. 아직 방향을 탐색하는 자리에서 "여기서 meter은 어떤 의미로 해석되나요?"를 붙잡고 늘어지면 대화가 진도를 못 나간다. 그 단계에서 필요한 것은 무엇을 왜 하려는지에 대한 합의이지 경계값의 확정이 아니다. 반대로 구현에 들어가기 직전에는 그 질문이 반드시 나와야 한다. 이때는 "meter"이 어느 범위인지 서로 같은 것을 떠올리고 있다고 믿을 수 있어야 하고, 그렇지 않으면 잘못된 전제 위에 코드가 쌓인다.

그래서 필자는 같은 애매함을 만나도 지금이 어느 단계인지에 따라 다르게 처리한다. 탐색 단계에서는 목록에 적어두고 넘어가고, 구현 직전에는 그 목록을 열어 하나씩 닫는다. 확인을 미루는 것과 확인을 포기하는 것은 다른 일이다.

이 지점에서 함께 쓰기 좋은 도구가 하나 있다. Matthew Skelton과 Manuel Pais의 Team Topologies는 팀 사이의 상호작용을 세 모드로 구분한다. 정해진 기간 동안 함께 새로운 것을 발견하는 collaboration, 한쪽이 제공하고 한쪽이 소비하는 X-as-a-Service, 한쪽이 다른 쪽을 도와주고 멘토링하는 facilitation이다.

원래는 조직 설계 이야기지만, 필자는 이걸 회의 단위로 축소해서 쓰는 게 실용적이라고 느꼈다. 지금 이 대화가 어떤 모드인지 서로 다르게 알고 있으면 회의가 어긋난다. 기획자는 이미 정해진 것을 전달하는 자리라고 생각하는데 개발자는 함께 발견하는 자리라고 생각하면, 개발자의 질문은 협업이 아니라 딴지로 들린다. 반대 경우도 있다. 개발자가 확정된 스펙을 받으러 왔는데 기획자는 아직 탐색 중이었다면, 개발자는 스펙이 없다고 답답해한다.

그래서 필자는 요즘 회의 초반에 이걸 먼저 확인한다. "이건 아직 열려 있는 건가요, 아니면 정해진 걸 확인하는 자리인가요?" 이 질문 하나가 그 뒤의 대화 성격을 바꾼다. grounding criterion을 목적에 맞춰 조정하는 일과 같은 얘기다.

해상도가 맞지 않으면 대화가 겉돈다

모드를 맞췄다고 해도 남는 문제가 있다. 필자가 자주 겪은 또 다른 어긋남은 서로 다른 해상도로 말하고 있는 상황이었다.

기획자가 문장으로 준 요구사항은 대체로 너무 추상적이다. "사용자가 예약 내역을 편하게 확인할 수 있게" 같은 문장에서는 화면이 몇 개인지, 어디서 어디로 넘어가는지가 나오지 않는다. 반대로 디자이너가 준 시안은 너무 구체적이다. 버튼의 색과 여백까지 정해져 있어서, 정작 "이 흐름이 맞는가"를 논의하기 어렵다.

Basecamp의 Ryan Singer가 쓴 Shape Up이 이 문제를 정확히 짚는다. 와이어프레임이나 구체적인 시각 레이아웃부터 시작하면 불필요한 디테일에 갇혀서 필요한 만큼 넓게 탐색할 수 없게 된다는 것이다. 그래서 Shape Up이 제안하는 것은 그 사이의 표현이다. breadboarding이라고 부르는데, 전기공학에서 개념을 빌려왔다. 브레드보드는 실제 기기의 부품과 배선은 다 갖췄지만 산업 디자인은 없는 시제품이다. 그래서 그리는 것도 딱 세 가지다. 넘어갈 수 있는 장소(places), 사용자가 조작할 수 있는 것(affordances), 그리고 그 조작이 사용자를 어디로 데려가는지 보여주는 연결선(connection lines)이다.

필자가 이 기법을 좋게 본 이유는, 개발자가 만들 수 있는 산출물이기 때문이다. 기획자에게 더 자세히 써 달라고 요청하거나 디자이너에게 시안을 기다리지 않고, 지금 이해한 흐름을 그 자리에서 그려서 "이렇게 이해했는데 맞나요" 라고 되돌려줄 수 있다. Evans가 말한 감시(모호함을 되돌려주기)를 실행하는 구체적 방법인 셈이다. 그리고 앞 절의 관점에서 보면, 이건 grounding 비용을 낮추는 장치다. 그림 한 장이 텍스트로 주고받는 확인 여러 번을 대신한다.

그런데 이 해상도는 유지하기가 생각보다 어렵다. 흐름을 그리다 보면 자연스럽게 "여기 버튼은 오른쪽 아래에 두는 게 낫지 않나" 같은 이야기로 내려가게 된다. 필자도 몇 번 그랬다. 그렇게 한 번 내려가면 그 자리에서 논의되던 질문, 그러니까 이 흐름이 맞는가는 조용히 사라진다. 아직 흐름이 확정되지 않았는데 버튼 위치를 정하고 있으면, 나중에 흐름이 바뀔 때 그 논의는 통째로 버려진다.

그래서 필자는 이 단계에서 일부러 못 그린 그림을 유지하려고 한다. 네모와 화살표와 이름뿐인 그림이면 상대도 디테일을 지적할 생각을 하지 않고 흐름에만 반응한다. 그림의 완성도가 낮은 것이 이 도구에서는 기능인 셈이다. (예쁘게 그리고 싶은 마음을 누르는 게 생각보다 어렵다)

추상화 수준이라는 개념 자체가 협업의 도구가 될 수 있다는 점은 추상화에서 다뤘던 이야기와도 이어진다. 그때는 코드의 추상화 수준을 말했는데, 대화에도 같은 것이 있다.

규칙과 예시와 질문을 분리하기

해상도를 맞추는 또 하나의 방법은 논의 자체를 구조화하는 것이다.

Cucumber 프로젝트를 이끈 Matt Wynne이 2015년에 소개한 Example Mapping을 살펴보자. 그는 많은 팀이 요구사항 논의를 어려워하는 이유를 구조가 없어서 오래 걸리고 지루해지기 때문이라고 진단한다. 그래서 규칙적으로도, 일관되게도 하지 않게 된다는 것이다. 필자도 정확히 그랬다. 요구사항 회의가 길어지면 다음부터는 짧게 끝내려 하고, 짧게 끝내면 애매한 것들이 그대로 남는다.

Example Mapping은 네 색의 카드로 논의를 나눈다. 노란색은 지금 다루는 스토리, 파란색은 규칙 혹은 수용 기준, 초록색은 그 규칙을 설명하는 구체적 예시, 그리고 빨간색은 답을 모르는 질문이다.

필자는 이 중에서 빨간색 카드가 핵심이라고 생각한다. 나머지 셋은 정리 기법이지만, 빨간 카드는 "모르겠다"를 회의의 정식 산출물로 만드는 장치다. 모른다는 사실을 말하는 것이 회의를 지연시키는 행동이 아니라 회의가 생산해야 하는 결과물이 된다.

이게 왜 중요한지는 반대 경우를 떠올려보면 분명해진다. 빨간 카드가 없는 회의에서 애매한 지점을 만나면 선택지는 두 개다. 지금 붙잡고 늘어져서 회의를 늘리거나, 넘어가서 나중에 혼자 해석하는 것이다. 앞 절에서 본 대로 사람은 대체로 후자를 고른다. 그런데 카드가 한 장 있으면 세 번째 선택지가 생긴다. 적어두고 넘어가되 사라지지 않게 하는 것이다. 회의는 계속 진행되고, 애매함은 없어지지 않은 채로 목록에 남는다.

초록색 카드도 비슷한 역할을 한다. 규칙만 적으면 다들 동의하지만, 그 규칙을 설명하는 구체적 예시를 적으려는 순간 해석이 갈린다. Evans가 말한 "대화에서 반복해서 쓰면 차이가 드러난다"를 회의 양식으로 옮겨놓은 셈이다. 규칙 하나에 예시를 세 개씩 붙여보라고 하면, 그중 하나에서 대체로 "어? 이 경우는 어떻게 되죠?"가 나온다. (필자의 경험상 그 질문이 나오지 않는 회의는 다들 이해한 회의가 아니라 각자 다르게 이해한 회의였다)

비슷한 발상으로 BDD 쪽에서 오래 쓰인 Three Amigos도 있다. 비즈니스와 개발과 테스트라는 세 관점이 각각 다른 질문을 던진다는 것인데, Agile Alliance 용어집은 그 질문을 각각 무슨 문제를 풀려는 것인지, 그 문제를 풀 해법을 어떻게 만들 것인지, 그리고 이건 어떤가 무슨 일이 일어날 수 있는가로 정리한다. 세 번째 질문이 나오지 않는 회의가 어떻게 되는지는 굳이 설명하지 않아도 될 것 같다.

모르는것을 확인해보는 절차를 만들어보자.

그런데 왜 우리는 빨간 카드를 잘 꺼내지 못할까. 여기서 심리적 안전감 이야기를 하지 않을 수 없다.

Amy Edmondson이 1999년에 Administrative Science Quarterly에 실은 논문이 팀 심리적 안전감이라는 개념을 정식으로 세운 연구다. (논문 자신은 1965년 Schein과 Bennis의 연구를 뿌리로 밝히고 있다) 팀 심리적 안전감을 팀이 대인관계상의 위험을 감수해도 안전한 곳이라는 공유된 믿음으로 정의한다. 모른다고 말하는 것, 반대 의견을 내는 것, 실수를 인정하는 것이 여기 해당한다. 논문은 제조업 회사의 51개 팀을 조사해서, 심리적 안전감이 학습 행동과 연관되고 그 학습 행동이 심리적 안전감과 팀 성과 사이를 매개한다는 결과를 보였다.

그런데 필자가 이 논문에서 가장 실용적이라고 느낀 문장은 정의가 아니라 그 바로 다음이었다.

대부분 이 믿음은 암묵적인 경향이 있다. 개인이나 팀 전체가 당연하게 여기며 직접 주의를 기울이지 않는다.

For the most part, this belief tends to be tacit—taken for granted and not given direct attention either by individuals or by the team as a whole.

이 믿음은 대개 암묵적이고, 개인도 팀도 직접 주의를 기울이지 않는다는 것이다.

여기서부터는 필자의 추측이다. 논문이 말한 것은 이 믿음이 암묵적이라는 데까지이고, 그러니 양식을 만들면 된다는 처방은 논문에 없다. 다만 암묵적인 것이 선언으로 바뀌지 않는다는 것은 여러 번 봤다. "우리 팀은 모르는 걸 물어봐도 되는 팀이에요" 라고 말하는 것으로는 잘 바뀌지 않는다. 그래서 필자는 앞 절의 빨간 카드가 중요하다고 생각한다. 모르겠다는 말을 양식 안의 칸으로 만들어버리면, 그것을 채우는 일이 용기가 아니라 절차가 된다.

물론 반문이 가능하다. 안전하지 않은 팀에서는 빨간 카드 칸도 그냥 비어 있을 것이다. 맞는 지적이고, 이 도구가 안전감을 만들어낸다고 주장할 생각은 없다. 다만 칸이 있으면 최소한 비어 있다는 사실이 눈에 보인다. 아무도 모르는 게 없어서 비었는지, 말하기 어려워서 비었는지를 물어볼 자리가 생긴다.

같은 발상이 실제 문서 양식에도 들어가 있다. DDD 커뮤니티가 만든 Bounded Context Canvas를 보면, 하나의 컨텍스트를 설계하고 기록하는 협업 도구인데 칸 구성이 흥미롭다. 이름과 목적, 전략적 분류, 도메인 역할, 인바운드와 아웃바운드 커뮤니케이션, 그리고 Ubiquitous Language, 비즈니스 결정, Assumptions, 검증 지표, Open Questions 다.

공유 언어를 적는 칸과 가정을 적는 칸과 열린 질문을 적는 칸이 각각 따로 있다. 캔버스의 설명은 목적을 적는 행위 자체가 흐릿한 생각을 명확히 말하도록 강제하고 팀 전체를 같은 페이지에 놓는다고 말한다.

필자는 이 발상이 소통 문제에 대한 가장 현실적인 접근이라고 생각한다. 사람의 태도를 바꾸려 하는 대신, 말하기 어려운 것에 칸을 만들어주는 것이다. 좋은 구조는 사람이 잘하도록 요구하는 대신 잘하기 쉽게 만들어준다.

이게 취향의 문제가 아닌 이유

여기까지 읽으면 이런 반응이 나올 수 있다. 좋은 얘기지만 결국 커뮤니케이션을 열심히 하자는 것 아닌가. 그건 성향 아닌가.

필자도 한동안 그렇게 생각했다. 그런데 이 부분에 데이터가 있다.

DORA는 조직 문화를 다룰 때 사회학자 Ron Westrum의 분류를 가져온다. 권력 지향의 pathological, 규칙 지향의 bureaucratic, 성과 지향의 generative 세 가지다. 그리고 DORA의 공식 문서는 자신들의 연구 결과를 이렇게 요약한다.

신뢰가 높고 정보 흐름을 중시하는 조직 문화는 소프트웨어 배포 성과를 예측한다.

organizational culture that is high-trust and emphasizes information flow is predictive of software delivery performance

신뢰가 높고 정보 흐름을 중시하는 조직 문화가 소프트웨어 배포 성과를 예측한다는 것이다. 소통이 잘 되는 팀이 기분이 좋다는 얘기가 아니라 성과와 함께 움직이는 변수라는 얘기다.

다만 여기서 예측한다는 말을 인과로 읽으면 안 된다. DORA의 데이터는 같은 응답자가 문화와 성과를 함께 답한 설문이고, 조직 수준의 상관이다. 조직에 만족한 사람이 양쪽 다 후하게 답했을 가능성이 남아 있고, 조직 수준의 관계에서 개인이 이렇게 행동하라는 처방이 곧바로 나오지도 않는다. 그러니 이 자료로 말할 수 있는 것은 여기까지다. 정보 흐름은 취향의 영역에만 있는 것이 아니라 성과와 같이 움직이는 자리에 있다.

같은 문서는 Westrum이 말한 좋은 정보의 세 가지 성질도 정리해 두었다. 수신자가 필요로 하는 질문에 답을 주고, 시기가 적절하며, 수신자가 효과적으로 쓸 수 있는 방식으로 제시된다는 것이다. 세 가지 모두 기준이 수신자에 있다는 점을 눈여겨볼 만하다. 많이 공유하는 것이 좋은 정보 흐름이 아니다.

Google의 Project Aristotle도 자주 인용되는 자료다. reWork에 공개된 내용에 따르면 180개 팀을 조사하고 수백 개 변수에 35개 이상의 통계 모델을 돌렸으며, 팀 효과성에 영향을 주는 다섯 가지 요인으로 심리적 안전감, 신뢰성, 구조와 명확성, 의미, 영향력을 제시했다. 그리고 결론은 팀에 누가 있는지보다 그 팀이 어떻게 함께 일했는지가 중요했다는 것이었다.

다만 한 가지 짚어두고 싶다. 공식 페이지는 다섯 요인을 중요도 순으로 나열한다고 밝히고 있고 심리적 안전감을 맨 앞에 둔다. 그런데 이 연구를 인용한 글들에서 자주 보이는 "압도적으로 1위" 같은 크기 표현은 그 페이지에 없다. 순서가 있다는 것과 나머지를 압도한다는 것은 다른 얘기다. 그래서 이 글에서는 크기를 주장하지 않는다. 심리적 안전감의 중요성을 말하려면 앞 절의 Edmondson 원 논문에 기대는 것이 정확하다.

다시 리더 이야기로

처음에 인용한 글로 돌아가보자.

James Samuel은 정보 수집을 가장 먼저 다루면서, 실무자 시절의 방법이 통하지 않게 된다고 말한다. 개인 기여자일 때는 자기 일의 전체 그림을 갖고 있지만, 사람에 대한 책임을 지게 되면 예전 방법을 쓸 수 없다는 것이다. 그래서 필요한 역량으로 노이즈를 걸러내고 정보를 종합해 일관된 현실의 그림으로 만드는 능력을 꼽는다. 어떤 관리자도 모든 것을 처리할 수는 없기 때문이다.

필자는 이것이 앞서 본 Westrum의 좋은 정보 세 가지 성질과 같은 얘기라고 느꼈다. 많이 모으는 것이 아니라 쓸 수 있는 형태로 만드는 것이다. 그리고 그건 지금 요구사항을 다루면서 하고 있는 일과 다르지 않다. 기획서의 문장에서 애매한 부분을 골라내고, breadboard로 다시 그려서 확인하고, 모르는 것을 빨간 카드로 남기는 일이 바로 노이즈를 걸러 일관된 그림을 만드는 연습이다.

저자가 의사결정에 대해 남긴 말도 기억에 남는다. 확실성을 기다리는 것도 그 자체로 하나의 결정이고 비용을 수반한다는 것이다. 요구사항이 완전히 명확해질 때까지 기다리는 것도 마찬가지다. 그래서 완벽한 이해가 아니라 현재 목적에 충분한 수준이라는 grounding criterion이 실용적인 기준이 된다.

마치며

정리하면 이렇다.

타직군과의 소통 실패는 대개 태도만의 문제가 아니다. 조직에 서로 다른 맥락이 있으면 같은 단어가 갈라지는 것이 기본 상태이고, 맞춰진 상태가 오히려 비용을 들여 유지해야 하는 예외다. 그 비용을 지불하는 방식이 공유 언어이고, 그 안에서 개발자의 몫은 요구사항을 받아쓰는 것이 아니라 모호함을 감시해서 되돌려주는 것이다.

그런데 되돌려주는 일에는 노력이 들고, 사람은 그 노력을 최소화하려 한다. 그래서 필자는 의지에 기대는 대신 세 가지를 쓰기로 했다. 이 대화가 어떤 모드인지 먼저 확인하는 것, 말과 시안 사이의 해상도로 흐름을 그려서 되돌려주는 것, 그리고 모르는 것을 적는 칸을 회의 양식 안에 만들어두는 것이다. 셋 다 태도를 고치라고 요구하지 않고 하기 쉽게 만드는 쪽이다.

필자는 아직 리더가 아니고, 이 글에 적은 것들도 그 자리에서 검증해본 것이 아니다. 팀 규모나 조직 문화가 다르면 통하지 않는 것도 있을 것이다. 다만 하나는 지금 확신할 수 있을 것 같다. 나중에 정보를 다루는 방식은 새로 배우는 것이 아니라, 지금 요구사항을 다루는 습관이 그대로 커진 형태일 것이다. 그래서 필자는 요즘 회의에서 "그건 무슨 뜻인가요" 라고 묻는 일을 예전만큼 부끄러워하지 않으려 한다.

이 글을 읽는 독자 분들도 최근 회의에서 고개를 끄덕였지만 실은 확실하지 않았던 단어가 하나쯤 떠오른다면, 다음에는 그 단어를 한 번 더 써보시기를 권한다. 반복해서 쓰면 드러난다.

바로 앞 글인 토큰 절약법을 정리하면서 줄곧 머릿속을 떠나지 않던 질문이 하나 있었다. "개별적 프롬프팅에서 비우고 골라내는 기술(context engineering)로 무게중심이 옮겨가고 있다" 고 생각하는데, 글을 닫고 나니 자연스럽게 다음 질문이 따라왔다. 그러면 컨텍스트 다음은 무엇인가?

"앞으로의 방향" 을 말하는 글은 조심스럽다. 미래에 대한 수많은 선택지가 있을텐데 우리는 이미 공개된 1차 자료에서 읽히는 무게중심의 이동을 정리하는 데 초점을 둔다. 추측이 다소 섞일지라도 다양한 관점으로 글을 접해보면 좋겠다.

프롬프트에서 컨텍스트로

용어부터 정리하고 가자. 한동안 업계의 화두는 프롬프트 엔지니어링이었다. 모델에게 보내는 한 번의 지시를 어떻게 잘 쓰느냐, 즉 명확한 지시문과 좋은 예시, 출력 형식을 어떻게 설계하느냐의 문제였다.

그러다 일의 단위가 커졌다. 단발성 질문이 아니라 수십 턴을 도는 에이전트가 보편화되면서, 한 번의 프롬프트가 아니라 모델이 매 턴 보는 컨텍스트 전체(시스템 프롬프트 + 도구 정의 + 대화 기록 + 검색 결과 + 메모리)를 어떻게 구성하느냐가 더 중요해졌다. 이걸 컨텍스트 엔지니어링이라 부른다. Anthropic 이 2025년 9월 "Effective context engineering for AI agents" 글로 이 프레임을 정리했고, Chroma 연구팀(Hong et al.)이 같은 해 발표한 context rot 연구가 정량적 근거를 보탰다. 이들은 GPT-4.1, Claude 4, Gemini 2.5, Qwen3 등 18개 모델을 두고, 단어를 그대로 따라 적는 수준의 단순 과제에서조차 입력이 길어질수록 성능이 비균일하게 무너진다는 사실을 보였다. 모델이 100번째 토큰과 10,000번째 토큰을 똑같이 다룰 거라는 흔한 가정이 실제로는 깨진다는 것이다. "컨텍스트는 길수록 좋다" 가 아니라 "무엇이 들었느냐만큼 어떻게 놓였느냐가 중요하다" 는 이 결론이, 채우기에서 골라내기로의 전환에 힘을 실으면서 용어가 빠르게 자리 잡았다.

여기서 흔한 오해 하나를 짚어야겠다. 프롬프트 엔지니어링이 컨텍스트 엔지니어링으로 대체된 것이 아니다. 프롬프트를 잘 쓰는 일은 여전히 기본이고, 컨텍스트 엔지니어링은 그 위에 얹힌 상위 개념에 가깝다. (코드를 잘 짜는 법에서 시스템을 잘 설계하는 법으로 관심이 옮겨갔다고 해서 코딩이 필요 없어지지 않는 것과 같다.) 즉 정확한 서술은 "갈아탔다" 가 아니라 "포함하면서 넓어졌다" 이다.

그렇다면 다시, 그 넓어짐은 컨텍스트에서 멈췄을까? 그렇지 않아 보인다.

Anthropic 엔지니어링 블로그

방향을 점치는 가장 정직한 방법은, 이 분야를 실제로 끌고 가는 곳이 무엇을 쓰고 있는지를 시간순으로 읽는 것이라 생각한다. Anthropic 엔지니어링 블로그의 글 목록을 "Effective context engineering"(2025년 9월) 이후로 따라가 보면, 제목들만으로도 무게중심이 어디로 더 갔는지 윤곽이 잡힌다.

• 2025년 10월, Agent Skills 로 에이전트 무장하기
• 2025년 11월, Code execution with MCP: 더 효율적인 에이전트
• 2025년 11월, Effective harnesses for long-running agents
• 2026년 1월, Demystifying evals for AI agents
• 2026년 1월, AI 에 저항하는(AI-resistant) 기술 평가 설계
• 2026년 2월, 에이전틱 코딩 평가의 인프라 노이즈 정량화
• 2026년 3월, Harness design for long-running application development
• 2026년 4월, Scaling Managed Agents: 두뇌와 손을 분리하기
• 2026년 5월, 제품 전반에서 Claude 를 격리(contain)하는 법

목록을 한 발 물러서서 보면 키워드가 세 갈래로 뭉친다. harness, eval, 그리고 containment다. 컨텍스트를 잘 채우고 비우는 법에서 한 단계 더 올라가, 에이전트라는 시스템 전체를 설계하고, 측정하고, 통제하는 쪽으로 논의가 옮겨가고 있다는 뜻으로 읽힌다. (물론 이건 한 회사의 강조점이라는 한계가 있다. 다만 이 회사가 코딩 에이전트 생태계에서 차지하는 비중을 생각하면, 한 벤더의 관심사로만 치부하기는 어렵다.)

하나씩 풀어보자.

harness

harness 라는 단어가 조금 낯설 수 있다. 직역하면 마구(馬具), 즉 말에 씌워 힘을 원하는 방향으로 끌어내는 장치다. AI 에이전트에서 harness 는 모델 바깥에서 모델을 둘러싸 일을 시키는 골격 전체를 가리킨다. 어떤 도구를 어떤 순서로 쓸 수 있게 할지, 한 번 실패하면 어떻게 복구할지, 권한은 어디까지 줄지, 루프는 언제 멈출지 같은 것들이다.

컨텍스트 엔지니어링이 "모델에게 무엇을 보여줄까" 의 문제였다면, harness 설계는 "모델이 그 안에서 어떻게 움직이게 할까" 의 문제다. 한 칸 더 바깥이다. 모델을 똑똑한 신입에 비유하면, 컨텍스트가 그 신입에게 건네는 업무 자료라면 harness 는 그 신입이 일하는 작업 환경과 절차서에 가깝다. 같은 사람이라도 환경이 어수선하면 성과가 흔들리고, 잘 짜인 절차 위에서는 같은 능력으로 더 멀리 간다.

이게 왜 중요한지는 Anthropic 엔지니어링 팀이 직접 부딪힌 실패에서 또렷하게 드러난다. 이들은 최상위 코딩 모델인 Opus 4.5 를 Claude Agent SDK 위에 올려 "claude.ai 클론을 만들어줘" 같은 고수준 지시만 던지고 여러 세션을 돌려봤는데, 모델 자체가 똑똑한데도 프로덕션 수준의 앱은 나오지 않았다. 실패는 두 가지 모양으로 반복됐다. 하나는 한 방에 다 끝내려다 구현 도중 컨텍스트가 바닥나, 다음 세션이 반쯤 만들다 만 기능을 물려받는 경우다. 다른 하나는 뒤늦게 투입된 세션이 "이미 꽤 진행됐네" 하고는 멀쩡히 남은 일을 두고 완료를 선언해버리는 경우다. (긴 작업을 사람 여러 명이 교대 근무로 잇는데, 교대자마다 앞 사람의 기억이 전혀 없는 상황을 떠올리면 된다.)

해법은 모델을 더 똑똑하게 만드는 쪽이 아니라 골격을 바꾸는 쪽이었다. 첫 세션에는 환경을 까는 전용 프롬프트(initializer agent)를 주어 200개가 넘는 기능 명세를 feature_list.json 으로 펼치게 하고, 개발 서버를 띄우는 init.sh 와 진행 로그 파일(claude-progress.txt)을 만들게 했다. 이후 세션(coding agent)은 매번 기능을 딱 하나씩만 처리하고, git 커밋과 진행 노트로 깔끔한 상태를 남긴 뒤 끝낸다. 다음 세션은 그 progress 파일과 git 로그를 먼저 읽어 "앞 교대자가 어디까지 했는지" 를 파악하고 이어받는다. 똑같은 모델인데, 이 골격 위에 올리자 결과가 달라졌다. 모델이 아니라 harness 가 성패를 갈랐다는 뜻이다. (흥미롭게도 Anthropic 이 든 처방들은 새로운 게 아니다. 기능 목록, 작은 단위 커밋, 진행 노트, 매번 돌리는 스모크 테스트는 숙련된 개발자가 매일 하는 일 그대로다. 에이전트에게 좋은 골격이란 결국 좋은 엔지니어링 습관을 환경에 박아 넣는 일에 가깝다.)

이 흐름이 토큰 절약 논의와 닿는 지점도 분명하다. 앞 글에서 다룬 서브에이전트 격리, 도구 정의 다이어트, 모델 라우팅은 따로 보면 개별 절약 기법이지만, 묶어서 보면 결국 하나의 harness 를 어떻게 설계하느냐의 부분들이다. 어떤 작업을 어떤 모델 레인으로 보내고, 어떤 도구만 켜두고, verbose 한 탐색은 어디로 격리할지를 정하는 일 전체가 harness 설계다. 절약은 그 설계의 부산물에 가깝다.

그런데 harness 설계에는 묘한 함정이 하나 있다. 잘 짠 골격일수록 모델이 좋아지면 낡는다는 점이다. harness 는 본질적으로 "모델이 혼자서는 못 하는 것" 에 대한 가정의 집합인데, 모델이 그 일을 스스로 하게 되는 순간 그 가정은 군더더기가 된다. Anthropic 이 든 사례가 정확히 이렇다. Sonnet 4.5 는 컨텍스트 한도가 다가오면 작업을 서둘러 끝내버리는 버릇(context anxiety)이 있어서, 골격에 컨텍스트 리셋 장치를 넣어 대응했다. 그런데 같은 골격을 Opus 4.5 에 올리자 그 버릇 자체가 사라져 있었고, 애써 넣은 리셋은 죽은 무게가 됐다. 모델이 한 칸 똑똑해질 때마다 골격의 일부가 이렇게 유통기한을 맞는다.

그래서 한 발 더 나아간 발상이 등장한다. 특정 골격을 잘 짜는 대신, 골격이 바뀌어도 흔들리지 않는 인터페이스를 짜는 것이다. Anthropic 의 Managed Agents 가 이 방향인데, 발상의 뿌리는 의외로 운영체제다. OS 가 수십 년을 버틴 건 하드웨어를 프로세스·파일 같은 추상으로 가상화해, 아직 존재하지도 않는 프로그램까지 담을 그릇을 먼저 만들어뒀기 때문이다. read() 한 줄은 1970년대 디스크든 요즘 SSD든 똑같이 동작한다. 같은 사고로 에이전트를 세 조각으로 가른다. 판단하는 두뇌(Claude 와 harness), 실제로 손을 쓰는 손(코드 실행 샌드박스·도구), 그리고 일어난 모든 일을 append 로 쌓는 세션 로그다. 셋을 분리해두면 컨테이너가 죽어도 두뇌는 도구 호출 에러로 받아 넘기고, harness 가 죽어도 세션 로그에서 마지막 지점부터 다시 깨어난다. 부수 효과로 비용·지연도 줄었다. 컨테이너를 정말 필요할 때만 띄우게 되면서 첫 토큰까지의 지연(TTFT)이 중앙값 기준 약 60%, p95 기준 90% 넘게 떨어졌다고 보고한다. (이 지점이 토큰 절약 글과 다시 만난다. 앞 글에서 prompt caching 을 위해 정적인 부분을 앞에 모으라고 했는데, 그 "어떻게 캐시 적중률을 높이게 컨텍스트를 배치할까" 가 바로 이 두뇌 옆 harness 가 맡는 일이다.)

eval

두 번째 갈래가 개인적으로 가장 흥미로웠다. 2026년 초의 글들이 약속이라도 한 듯 평가(eval) 로 모인다.

이유를 생각해보면 자연스럽다. 컨텍스트를 잘 구성했는지, harness 를 잘 짰는지, 비용을 정말 아꼈는지를 무엇으로 확인할 것인가? 에이전트가 길고 복잡한 작업을 자율적으로 처리할수록, "그래서 이게 잘 돌아간 건가" 를 사람이 눈으로 일일이 확인하기 어려워진다. 결국 신뢰의 근거는 측정으로 옮겨간다. 그래서 "에이전트 평가를 어떻게 설계하나", "평가 자체의 노이즈를 어떻게 걷어내나", "모델이 평가를 눈치채고 행동을 바꾸는(eval awareness) 문제를 어떻게 다루나" 같은 주제가 전면에 나온 것이다.

에이전트 평가가 까다로운 건 단발성 질의응답과 결이 다르기 때문이다. 에이전트는 여러 턴에 걸쳐 도구를 부르고 상태를 바꾸며 진행하므로, 한 번의 실수가 뒤로 전파되며 누적된다. 게다가 똑같은 입력에도 매 실행 결과가 흔들린다. Anthropic 은 이 비결정성을 두 지표로 나눠 본다. pass@k 는 k 번 시도 중 한 번이라도 성공할 확률이라, 시도를 늘릴수록 올라간다. pass^k 는 k 번을 모두 성공할 확률이라, 시도를 늘릴수록 떨어진다. 한 번만 맞으면 되는 코드 생성은 pass@1 이 중요하고, 매번 안정적으로 동작해야 하는 고객 응대 에이전트는 pass^k 가 핵심이다. (per-trial 성공률이 75% 라면 세 번 연속 성공할 확률은 0.75³, 약 42% 로 뚝 떨어진다. "대체로 잘된다" 와 "매번 잘된다" 사이의 간극이 이렇게 크다.)

그렇다면 한 번의 시도는 무엇으로 채점하나? 같은 글은 채점기(grader)를 세 종류로 나눈다. 코드 기반(테스트 통과 여부, 정적 분석, 도구 호출 검증)은 빠르고 싸고 객관적이지만, 정답이 여럿인 열린 작업에는 약하다. 모델 기반(LLM-as-judge, 루브릭 채점)은 미묘한 품질까지 잡아내지만 비결정적이라 사람 채점과 주기적으로 보정해야 한다. 사람 기반은 가장 정확하지만 느리고 비싸다. 실무에서는 이 셋을 섞되, 가능하면 결정론적 채점을 기본으로 깔고 모델 채점을 거드는 식으로 조합한다. 또 하나 구분이 있다. capability eval 은 "이 에이전트가 무엇을 해낼 수 있나" 를 묻기에 낮은 점수에서 시작해 올라갈 언덕을 주고, regression eval 은 "예전에 되던 게 지금도 되나" 를 묻기에 거의 100% 를 유지해야 한다. 점수가 떨어지면 어딘가 망가졌다는 신호다.

여기서 의외로 자주 간과되는 함정이 있다. 점수가 낮은 게 에이전트가 아니라 평가 탓일 수 있다는 것이다. Anthropic 의 보고에 따르면 Opus 4.5 가 CORE-Bench 에서 처음 42% 를 받았는데, 파보니 "96.124991…" 를 기대하는데 "96.12" 를 틀렸다고 처리하는 식의 경직된 채점, 모호한 문제 명세, 재현 불가능한 확률적 과제가 원인이었다. 버그를 고치고 제약을 푼 스캐폴드로 다시 돌리자 점수는 95% 로 뛰었다. 그래서 이들은 한 가지 원칙을 강조한다. 점수를 액면 그대로 믿지 말고 트랜스크립트(실행 기록)를 직접 읽어라. 프런티어 모델이 100번 시도해 0% 가 나온다면 대개 모델이 무능한 게 아니라 문제가 깨진 것이다.

측정이 발전하면 기준선 자체가 빠르게 움직인다는 점도 흥미롭다. 대표적인 코딩 에이전트 벤치마크인 SWE-bench Verified(실제 GitHub 이슈를 주고 테스트 통과 여부로 채점) 에서 프런티어 모델들의 점수는 1년 만에 30% 대에서 80% 이상으로 올라섰다. 이쯤 되면 쉬운 문제는 다 풀려 점수가 천장(saturation)에 닿고, 큰 능력 향상이 작은 점수 차로만 보이는 역설이 생긴다. 실제로 어떤 코드 리뷰 스타트업은 처음에 단발성 평가만 보고 신형 모델을 시큰둥하게 여겼다가, 더 길고 복잡한 작업을 재는 에이전트형 평가로 갈아탄 뒤에야 향상을 제대로 봤다고 한다. 그래서 평가는 한 번 만들고 끝나는 게 아니라, 계속 어렵게 갈아 끼워야 하는 살아있는 자산이 된다. (Anthropic 은 이를 안전공학의 "스위스 치즈 모델" 에 빗댄다. 구멍 뚫린 치즈 한 장으로는 막을 수 없지만, 자동 평가와 프로덕션 모니터링, 사람의 트랜스크립트 검토를 겹겹이 쌓으면 한 층을 빠져나간 실패가 다음 층에 걸린다는 것이다.)

containment

세 번째는 결이 조금 다르다. 비용이나 성능이 아니라 안전과 통제의 문제다.

에이전트가 더 많은 도구를 쥐고 더 자율적으로 움직일수록, 한 번의 실수가 미치는 범위(blast radius)도 같이 커진다. 파일을 지우고, 외부에 요청을 보내고, 권한이 있는 작업을 대신 수행하는 에이전트라면, "얼마나 잘하나" 만큼이나 "잘못했을 때 피해를 어디서 막나" 가 중요해진다. 2026년 5월 Anthropic 이 제품 전반의 격리(containment)를 다룬 글을 전면에 내세운 것도 이 맥락으로 읽힌다. 이 글은 에이전트의 위험을 세 갈래로 나눈다. 사용자가 악의로든 부주의로든 해로운 일을 시키는 사용자 오용, 아무도 시키지 않은 행동을 모델이 스스로 하는 모델 오작동, 도구·파일·네트워크를 통해 바깥에서 들어오는 외부 공격이다. 흥미로운 지적은 모델이 똑똑해진다고 위험이 줄지만은 않는다는 것이다. 덜 똑똑한 모델은 상황을 오독해 빤한 실수를 하지만, 더 똑똑한 모델은 실수는 줄어드는 대신 아무도 적어두지 않은 제약을 우회하는 뜻밖의 경로를 더 잘 찾아낸다.

이들이 강조하는 핵심은 "사람이 매번 감독하는 방식"의 한계다. Claude Code 는 초기에 쓰기·실행·네트워크 접근마다 사용자에게 승인을 묻는 식으로 안전을 확보했는데, 텔레메트리를 보니 사용자들은 승인 요청의 약 93% 를 그냥 허락하고 있었다. 승인 창이 많아질수록 하나하나에 주의를 덜 기울이게 되는 승인 피로(approval fatigue) 가 생긴 것이다. 결국 감독을 사람의 클릭에 의존하는 확률적 방어에는 새는 구멍이 남는다. 그래서 무게중심이 "에이전트가 무엇을 하는지 감시" 에서 "에이전트가 애초에 무엇을 할 수 있는지를 제한" 으로 옮겨간다. 방어는 세 계층으로 겹쳐 쌓는다. 샌드박스·VM·egress 통제 같은 환경 계층, 시스템 프롬프트·분류기 같은 모델 계층, MCP·플러그인·검색 결과 같은 외부 콘텐츠 계층이다. 핵심 원칙은 결정론적으로 막아주는 환경 계층을 가장 먼저 깐다는 것이다. 모델 계층 방어가 약해서가 아니다. 실제로 prompt injection 을 테스트하는 Gray Swan 벤치마크에서 단발 공격 성공률은 약 0.1% 로 최상급이다. 다만 100번 적응형으로 두드리면 5~6% 까지 올라가고, 확률적 방어는 본질적으로 적중률이 100% 가 될 수 없다. 그래서 마지막으로 부딪히는 하드한 경계를 깔아두는 것이다. (OS 수준 샌드박스를 도입했을 때 승인 창이 84% 줄었다고 한다. 안전장치가 오히려 마찰을 줄인 셈이다.)

토큰 절약과는 멀어 보이지만, 실은 같은 뿌리를 공유한다. 둘 다 "에이전트에게 무엇을, 어디까지 쥐여줄 것인가" 의 문제다. Anthropic 에서 두가지 사례로 이 연결을 잘 보여준다. 하나는 내부 레드팀이 직원을 피싱해 악성 프롬프트로 Claude Code 를 실행시킨 일인데, 슬쩍 끼워둔 지시가 ~/.aws/credentials 를 읽어 외부로 POST 하게 만들었고 25번 중 24번 성공했다. 사용자가 직접 타이핑한 지시라 모델 분류기에는 수상할 게 없었다. 막아낸 건 똑똑한 모델이 아니라 자격증명을 애초에 샌드박스 밖에 둔 환경 경계와 egress 통제였다. 다른 하나는 더 미묘하다. egress 허용 목록이 api.anthropic.com 을 정상 통과시켰는데, 공격자가 심어둔 파일이 자기 API 키로 Anthropic 의 파일 업로드 API 를 호출하게 시켜 데이터가 공격자 계정으로 빠져나갔다. 샌드박스는 완벽히 동작했는데도 데이터가 샌 것이다. 허용 목록을 "목적지 필터" 가 아니라 "그 도메인으로 할 수 있는 모든 기능을 허용하는 권한" 으로 봐야 했다는 교훈이다. (Anthropic 이 반복해 강조하는 원칙이 이거다. 검증된 하이퍼바이저·시스콜 필터·컨테이너 런타임은 멀쩡히 버텼고, 정작 깨진 건 그 위에 자기들이 직접 만든 부품이었다.) 안 쓰는 MCP 도구를 떼는 일도 같은 맥락이다. 비용을 아끼는 동시에 공격 표면(attack surface)을 줄이는 일이기도 하다. 가볍게 유지하는 설계가 싸고 정확할 뿐 아니라, 더 안전하기도 하다는 뜻이다.

그래서, 정리하면

세 갈래를 한 줄로 줄이면 이렇다. 관심의 단위가 프롬프트(한 번의 지시)에서 컨텍스트(매 턴 보여줄 것)로, 다시 에이전트 시스템 전체(어떻게 굴리고 어떻게 측정하고 어떻게 가둘 것인가)로 한 칸씩 바깥으로 넓어지고 있다. harness 는 "어떻게 굴릴까", eval 은 "잘 굴렀는지 어떻게 알까", containment 는 "잘못 굴렀을 때 어떻게 막을까" 에 각각 대응한다.

다시 한번 못 박아두자면, 이 세 갈래는 필자가 이미 공개된 자료에서 읽어낸 무게중심의 이동이지, "2026년 하반기엔 이게 표준이 된다" 같은 예언이 아니다. 어떤 흐름은 더 커질 것이고 어떤 흐름은 다른 이름으로 흡수될 것이다. 다만 분명한 건, 프롬프트도 컨텍스트도 사라지지 않고 더 큰 틀의 부분으로 남는다는 점이다. 새 단어가 옛 단어를 지우는 게 아니라 그 위에 한 층을 더 쌓는 식으로 분야가 움직여 왔고, 앞으로도 그럴 가능성이 높다.

비용 이야기로 시작해 여기까지 왔다. 앞 글에서 토큰 가계부를 꺼내보길 권했는데, 이 글의 권유는 한 칸 더 나아간다. 절약한 비용을 무엇으로 확인하고(eval), 그 절약이 어떤 골격 위에서 반복 가능하며(harness), 그 골격이 어디까지 안전한지(containment)를 함께 들여다보면 좋겠다. 결국 가장 오래 가는 건 특정 절약 기법이 아니라, 자기 시스템을 측정하고 통제하는 습관일 것이라 생각한다.

이 글은 2026년 6월에 쓴 회고를 다시 쓴 것이다. 처음 글이 내세운 "일곱 picker를 하나의 API로, 경쟁 라이브러리의 calendar 하나보다 작게"는 다시 확인해 보니 절반은 틀렸고 절반은 차별점이 아니었다. 그래서 만든 이유, 기존 선택지와의 차이, 기술적 정의 순서로 다시 정리한다.

결론을 먼저 말하면 Kalyx의 차이는 컴포넌트 개수가 아니라 값 모델에 있다. 기준 버전은 @kalyx/react 1.4.7과 @kalyx/core 1.4.8(MIT, React 19 전용)이고, 코드 인용은 GitHub 저장소의 2026-09-16 main(0bb302e) 기준이다.

날짜 picker를 선언적으로 쓰고 싶었다

만든 이유는 두 가지였다. 복잡하고 쓰기 어려운 날짜 라이브러리를 더 선언적이고 단순하게 쓰고 싶었고, 그런 라이브러리가 안에서 어떻게 만들어지는지 공부하고 싶었다. "쓰기 어렵다"는 말은 막연하니, 필자가 걸렸던 지점이 지금 최신 버전에도 남아 있는지 각 라이브러리의 타입 정의로 다시 확인했다.

모드를 prop으로 켜는 API

react-datepicker는 시간 선택을 showTimeSelect, 월 선택을 showMonthYearPicker, 연 선택을 showYearPicker, 범위 선택을 selectsRange로 켠다. 한 컴포넌트가 prop 조합에 따라 다른 물건이 되는 구조다. 그 비용은 타입에서 보인다. 9.1.0의 타입 정의에서는 selectsRange 값에 따라 onChange 시그니처가 갈린다.

// react-datepicker/dist/index.d.ts (발췌)
    selectsRange?: true;
    selectsMultiple?: false | undefined;
    formatMultipleDates?: never;
    onChange?: (date: [Date | null, Date | null], event?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>) => void;

잘 만든 union이지만, 모드가 늘수록 분기가 곱해지고 사용하는 쪽은 prop 이름만 보고 지금 어떤 조합인지 떠올려야 한다. (필자가 추상화 글에서 다룬 "잘못 묶은 추상화는 결합도를 늘린다"와 같은 모양이다) 필자는 "입력 칸과 popover와 calendar"가 JSX 구조 자체로 읽히길 원했다.

값 타입과 timezone이 새는 자리

react-datepicker와 react-day-picker는 native Date를 주고받는다. 둘 다 IANA timeZone prop이 있기는 하다. react-datepicker는 optional peer로 date-fns-tz를 요구하고 react-day-picker의 것은 실험적인데, 어느 쪽이든 값 타입은 여전히 Date다. Date는 실행 환경의 로컬 timezone으로 해석되기 때문에 서울에서 new Date(2026, 3, 15)의 toISOString()은 2026-04-14T15:00:00.000Z다. 4월 15일을 골랐는데 서버에는 14일로 보이는 문제다. react-datepicker의 "Date Selected is One Day Off" 이슈는 2017년 9월에 열려 2025년 12월에 닫혔다.

반대편의 Ark UI와 React Aria는 @internationalized/date의 CalendarDate, ZonedDateTime 객체를 쓴다. 의미는 정확하지만 폼 상태와 서버 응답이 전부 문자열인 앱에서는 경계마다 변환 코드가 생긴다.

timezone 지원이 날짜 라이브러리 선택에 묶이기도 한다. MUI X Date Pickers 9.13.0의 adapter 코드를 보면 dayjs, Luxon, Moment adapter는 isTimezoneCompatible = true, date-fns 계열은 false다. date-fns를 쓰는 앱이 timezone prop을 쓰려면 날짜 라이브러리를 하나 더 들여야 한다.

모드는 prop 조합으로, 값은 해석이 실행 환경에 기대는 Date로, timezone 지원은 날짜 라이브러리 선택으로 흩어져 있다. 선언 하나로 의도를 적기 어려웠다.

만들며 배우기

날짜 picker는 작아 보이지만 달력 계산, locale, timezone과 DST, 키보드 탐색, SSR이 전부 들어 있다. 그래서 쓰는 쪽에서는 JSX만 보고 무엇을 만드는지 읽히게, 만드는 쪽에서는 값이 어디서 변환되는지 설명할 수 있을 만큼 좁히는 것을 목표로 잡았다.

그렇다면 이런 요구를 이미 풀어 둔 라이브러리는 정말 없었을까?

이미 있는 선택지와 무엇이 다른가

답부터 말하면 있다. 필자는 headless이면서 여러 picker를 갖춘 라이브러리가 없다고 믿고 시작했는데, 다시 조사해 보니 그 전제가 틀렸다.

선택지마다 고른 값 모델

2026-09-16에 npm 최신판을 설치해 타입 정의와 공식 문서로 확인한 내용이다. 크기 열은 아래에서 설명할 같은 방법으로 잰 값이다.

react-day-picker는 공식 가이드에서 "DayPicker does not include a built-in time picker"라고 밝힌다. MUI 크기는 @mui/material과 emotion을 포함한 값이라 이미 MUI 앱이라면 증가분이 훨씬 작다.

headless 완성형은 이미 있다

표에서 중요한 줄은 Ark UI와 React Aria다. Ark UI는 DatePicker.Root 같은 dot notation 합성 API로 단일, 다중, 범위 선택과 월, 연 단위 선택을 낸다. React Aria는 Adobe의 접근성 중심 구현이다. 그래서 Kalyx의 자리는 처음 생각보다 좁다.

headless 완성형은 이미 있다. 다만 Ark UI와 React Aria는 값을 @internationalized/date 객체로 주고받고 시간 입력은 세그먼트 필드로 낸다. Kalyx는 값을 JSON에 그대로 실리는 UTC 시점 문자열로 고정했고, 목록에서 고르는 TimePicker와 월, 연, 주 picker를 같은 합성 API에 넣었다.

다만 "값이 문자열이라 좋다"는 약한 주장이다. CalendarDate도 toString() 한 번이면 문자열이 된다. 차별점은 형식이 아니라 그 문자열이 항상 실제 순간(시점)이고 calendar 칸(좌표)과 섞이지 않는다는 계약, 그리고 그 계약을 지키는 테스트에 있다.

번들 크기를 같은 방법으로 다시 쟀다

README 배지의 번들 크기는 다른 라이브러리와 비교할 수 있는 양이 아니었다. 배지의 약 19.5KB는 @kalyx/react의 dist 파일 하나인데, 이 파일은 @kalyx/core, @kalyx/adapter-date-fns, @floating-ui/react를 외부 import로 남긴다. 그 숫자를 의존성이 포함된 남의 숫자 옆에 세워 둔 것이다.

그래서 "소비자 앱이 import 한 줄을 추가했을 때 번들이 얼마나 커지는가"로 모두 다시 쟀다.

echo "import { DatePicker } from '@kalyx/react'; export default DatePicker;" > entry.jsx
npx esbuild entry.jsx --bundle --minify --format=esm --platform=browser \
  --external:react --external:react-dom --external:react/jsx-runtime | gzip -6 | wc -c

esbuild 0.28.2, 2026-09-16 측정이고 KB는 바이트를 1024로 나눈 값이다. react-datepicker는 CSS를 뺐다. React Aria Components는 단일 DatePicker 조립에 필요한 export 12개(DatePicker, DateInput, Calendar, Popover, Dialog 등)와, 범위와 시간까지 넣은 14개(DateRangePicker, RangeCalendar, TimeField 포함)로 두 번 쟀다.

같은 조건에서 참인 문장은 하나다. DatePicker 하나(18.9KB)는 DayPicker(20.0KB)와 비슷한 크기이고, 일곱 종 전부(25.6KB)는 그보다 크다. (그마저 DayPicker는 calendar만, Kalyx DatePicker는 입력 칸과 popover까지 포함한다) 크기는 import 조합과 gzip 레벨에 민감하니 자릿수로 읽는 편이 맞고, 크기가 Kalyx를 고를 중심 이유는 아니다.

Kalyx를 기술적으로 정의하면

Kalyx는 모든 입출력을 UTC 시점 문자열로 고정하고, calendar 좌표와 시점 사이의 변환을 두 함수에만 두어 그 왕복을 런타임이 아는 모든 timezone에 대해 속성 테스트로 검사하는 headless React 날짜 picker다.

사용하는 쪽의 API는 이렇다. value와 onChange는 string | null이고 displayTimezone은 어느 존의 달력으로 보여줄지 정한다.

<DatePicker value={iso} onChange={setIso} displayTimezone="America/New_York">
  <DatePicker.Input />
  <DatePicker.Popover>
    <DatePicker.Calendar />
  </DatePicker.Popover>
</DatePicker>

값은 시점이고 calendar 칸은 좌표다

Kalyx 안에는 형식이 같은 두 종류의 ISO 문자열이 흐른다. 좌표는 calendar 그리드의 한 칸으로, YYYY-MM-DDT00:00:00.000Z로 적지만 timezone 개념이 없다. 그리드 계산이 UTC로만 돌아서 실행 환경과 무관하다. 시점은 onChange로 나가는 값으로, displayTimezone에서 그날 자정인 실제 순간이다. 같은 1월 15일이 뉴욕에서는 2026-01-15T05:00:00.000Z, 서울에서는 2026-01-14T15:00:00.000Z다.

둘을 잇는 함수는 @kalyx/core의 두 개뿐이다. 좌표를 시점으로 바꾸는 civilMidnightFromUtcDay와 그 반대인 calendarDayFromInstant다. 뒤쪽은 "그 시점이 이 존에서 며칠인가"를 읽어 UTC 자정 좌표로 다시 적는다.

// packages/core/src/utils/timezone.ts:187-190
export function calendarDayFromInstant(iso: ISODateString, timeZone: string): ISODateString {
  const p = partsInTimezone(new Date(iso), timeZone);
  return new Date(Date.UTC(p.year, p.month - 1, p.day)).toISOString();
}

규칙은 방향이다. 칸을 골라 값을 커밋할 때는 좌표를 시점으로, 저장값에서 보여줄 월과 포커스를 정할 때는 시점을 좌표로 바꾼다. DatePicker Root의 selectDate는 변환하고, 변환된 시점으로 제약을 검사하고, 통과하면 커밋한다.

// packages/react/src/components/DatePicker/Root.tsx:182-194
const normalized =
  coordinate && displayTimezone
    ? civilMidnightFromUtcDay(coordinate, displayTimezone)
    : coordinate;
 
if (normalized && isDateDisabled(normalized, disabledRules, adapter, displayTimezone)) {
  return;
}
 
if (!isControlled) {
  setUncontrolledValue(normalized);
}
onChange?.(normalized);

호출 자리는 여기만이 아니다. packages/react/src를 검색하면 두 함수가 DatePicker, RangePicker, DateTimePicker의 Root와 Calendar, Presets, 키보드 이동 유틸, headless 훅 여섯 개에 흩어져 있다. 그래도 날짜 칸을 커밋하거나 뷰를 정하는 경로는 전부 둘 중 하나를 지난다. 시각 커밋은 setTimeInTimezone이 맡는데, 안에서는 같은 내부 함수 resolveCivilDateTime으로 변환한다.

이 계약은 속성 테스트(property-based test)로 지킨다. 모든 좌표 c와 존 z에 대해 calendarDayFromInstant(civilMidnightFromUtcDay(c, z), z) === c여야 한다.

// packages/core/src/__tests__/timezone.property.test.ts:86-94
it('round-trips every UTC calendar coordinate through civil midnight', () => {
  fc.assert(
    fc.property(utcCalendarCoordinate(), zone(), (coordinate, timeZone) => {
      const instant = civilMidnightFromUtcDay(coordinate, timeZone);
      expect(calendarDayFromInstant(instant, timeZone)).toBe(coordinate);
    }),
    RUNS,
  );
});

fast-check가 2020년에서 2045년 사이의 날짜를 무작위로 만들어, +5:45 Kathmandu, +14 Kiritimati, -11 Niue 등 대표 존 14개와 조합해 300번 돈다. 바로 다음 테스트는 같은 왕복을 Intl.supportedValuesOf('timeZone')이 돌려주는 존 전부에 대해 존마다 12번씩 검사한다. 필자 로컬 Node 24.16에서 그 목록은 418개다. 1.4.8에서는 DST 전환마다 경계 시각의 변환 결과를 Temporal 구현과 대조하는 전수 테스트가 더해졌다.

그렇다면 사용자가 넘긴 "2026-01-15T00:00:00.000Z"를 라이브러리가 알아서 시점으로 정규화하면 되지 않을까? 문자열만 보고는 좌표인지 시점인지 알 수 없어서 이 길은 막혀 있다. 이미 시점인 서울 값 2026-01-14T15:00:00.000Z에 civilMidnightFromUtcDay를 다시 걸면 2026-01-13T15:00:00.000Z가 되고, 서울처럼 오프셋이 양수인 존에서는 렌더마다 하루씩 계속 밀린다. (뉴욕 값은 다시 걸어도 그대로다) 여러 번 적용해도 결과가 같은 startOfDayInTimezone으로 바꾸면 밀림은 없지만 좌표를 시점으로 바꾸는 원래 일을 못 한다.

그래서 정규화를 포기하고 계약을 문서로 고정했다. 소비자는 picker가 내보낸 값을 그대로 넘겨야 한다. 솔직히 소비자에게 떠넘긴 비용이고, ISODateString이 string의 별칭이라 컴파일러도 막아 주지 못한다.

Intl만으로 DST를 푸는 방법

좌표를 시점으로 바꾸려면 "그 존의 그날 00:00"이 UTC로 언제인지 알아야 하는데, 오프셋은 시점을 알아야 구할 수 있다. 게다가 DST 전환일에는 현지 시각이 없거나(spring forward) 두 번 있다(fall back).

Kalyx는 date-fns-tz 같은 라이브러리 없이 이것을 푼다. Intl.DateTimeFormat(...).formatToParts로 "이 UTC 순간이 그 존에서 몇 시인가"를 물어 오프셋을 재고, 그 오프셋을 요청 시각의 하루 전과 하루 뒤 두 지점에서 읽는다.

// packages/core/src/utils/timezone.ts:251-254, 259
const candidate = (probeEpoch: number) =>
  civilEpoch - getTimezoneOffsetMinutes(new Date(probeEpoch).toISOString(), timeZone) * 60_000;
const epochBefore = candidate(civilEpoch - 86_400_000);
const epochAfter = candidate(civilEpoch + 86_400_000);
 
if (epochBefore === epochAfter) return new Date(epochBefore).toISOString();

civilEpoch는 원하는 현지 시각을 UTC인 것처럼 읽은 값이다. 오프셋은 ±14시간 안이라 하루 전과 하루 뒤는 근처 전환의 앞과 뒤 오프셋을 하나씩 준다. 둘이 같으면 전환이 없으니 formatToParts 두 번으로 끝나고, 그리드 42칸마다 한 번씩 부르는 이 빠른 경로가 비용을 결정한다. (48시간 안에 전환이 하나라는 전제는 2020~2045년 모든 존에서 성립한다)

둘이 다르면 두 후보를 그 존에서 다시 읽어 요청한 시각과 맞는지 본다(timezone.ts:261-279). fall back의 겹침에서는 둘 다 맞아 전환 전 오프셋으로 만든 이른 쪽을 고르고, spring forward의 틈에서는 둘 다 맞지 않아 같은 쪽을 골라 틈 길이만큼 앞으로 민다. 실제로 돌린 결과는 이렇다.

"틈은 앞으로, 모호함은 이른 쪽"은 MDN의 Temporal.ZonedDateTime 문서가 설명하는 disambiguation 기본값 "compatible"과 같다. 1.4.7의 런던 행이 어긋난 이유는 뒤에서 다룬다.

adapter 경계는 문자열 메서드 21개다

timezone을 core가 계산한다면 date-fns나 dayjs는 무엇을 맡을까? 날짜 산술과 파싱이다. 그 경계인 DateAdapter는 메서드 21개이고 날짜 인자와 반환값이 전부 ISO 문자열이다.

// packages/core/src/types.ts:71-102 (발췌)
export interface DateAdapter {
  parse(value: string, format?: string): string;
  format(iso: string, formatStr: string, timezone?: string): string;
  addDays(iso: string, n: number): string;
  isSameDay(a: string, b: string, timezone?: string): boolean;
  startOfDay(iso: string, timezone?: string): string;
  today(timezone?: string): string;
  // addMonths, isBefore, startOfMonth, getYear 등 15개
}

timezone을 받는 메서드는 format, isSameDay, startOfDay, today 넷이고, 그 넷도 계산은 core로 넘긴다. date-fns adapter의 format은 timezone이 있으면 core의 formatInTimezone을 바로 부른다(packages/adapter-date-fns/src/index.ts:112-115). 그래서 어떤 adapter를 쓰든 timezone 답은 같은 코드에서 나오고, 세 adapter(date-fns, dayjs, luxon)는 @kalyx/core/test-helpers의 runAdapterConformanceTests를 각자 돌려 같은 답을 내는지 확인한다.

두 엔트리도 이 경계에서 갈린다. 기본 엔트리 @kalyx/react는 모듈 로드 시 setDefaultAdapter(DateFnsAdapter)를 호출해 설치하면 바로 동작한다(packages/react/src/index.ts:9-11). @kalyx/react/headless는 이 호출이 없고 번들이 분리돼 date-fns 코드가 들어가지 않는다.

이 경계 모양에는 대가가 있었다. 필자는 2026년 6월에 Temporal adapter를 접었다. Temporal의 가치는 PlainDate, ZonedDateTime처럼 타입이 의미를 들고 다니는 데 있는데, 경계가 문자열이면 그 의미가 통과하지 못한다. 감싸도 문자열로 평탄화될 뿐이라 정확성 이득이 없다고 판단했다. 돌아보면 앞 절의 "좌표와 시점이 같은 string" 문제는 Temporal이 PlainDate와 Instant로 타입에서 푸는 바로 그 문제다. 문자열 경계가 adapter 교체를 쉽게 만든 대신 타입으로 풀 길은 막은 셈이다.

일곱 picker는 컨텍스트 세 개의 조합이다

Kalyx의 picker는 DatePicker, RangePicker, TimePicker, DateTimePicker, MonthPicker, YearPicker, WeekPicker 일곱 종이다. 중요한 것은 개수보다 일곱 개가 독립 구현이 아니라는 점이다. 컨텍스트는 DatePickerContext, RangePickerContext, TimePickerContext 세 개뿐이다.

MonthPicker의 Root는 표시 형식 기본값을 yyyy-MM으로 바꾸고 DatePicker의 Root 구현에 selectionGranularity="month"를 넘길 뿐이다(MonthPicker/Root.tsx:11-20). DatePicker의 selectDate는 granularity가 month면 좌표를 그 달 1일로 접은 뒤 앞에서 본 변환과 제약 검사를 그대로 탄다. DateTimePicker는 두 컨텍스트를 겹쳐 제공한다.

// packages/react/src/components/DateTimePicker/Root.tsx:401-402
<DatePickerContext.Provider value={dateContext}>
  <TimePickerContext.Provider value={timeContext}>{children}</TimePickerContext.Provider>

그래서 DateTimePicker.Calendar는 DatePicker.Calendar와 같은 컴포넌트이고, 자기가 어느 picker 안에 있는지 모른다. 한 곳의 수정이 같은 컴포넌트를 쓰는 picker 전부에 닿고, 한 곳의 결함도 전부에 닿는다. 앞 도표에서 DatePicker 하나가 전부의 74% 였던 이유도 이 공유 기반이다.

계약을 지키는 데 든 비용

1.0 이후 석 달은 새 기능보다 이 계약을 확인하는 데 썼고, 예제 테스트로는 지나갔을 결함이 세 번 나왔다. 첫 번째는 속성 테스트가, 두 번째는 코드 교차 검토가, 세 번째는 이 글의 검증이 찾았다.

Sydney 10월 1일의 한 시간

첫 번째는 "startOfDayInTimezone의 결과를 그 존에서 읽으면 00:00:00 이다"는 속성이 Australia/Sydney에서 깨진 것이다. 당시 구현은 오프셋을 한 번만 쟀다. Sydney는 2034년 10월 1일 02:00에 +10에서 +11로 넘어가는데, 그날 00:00은 아직 +10이라 정답은 2034-09-30T14:00:00.000Z다. 그런데 "10월 1일 00:00을 UTC로 읽은 지점"은 전환 이후라 +11을 돌려줬고, 결과는 전날 23:00이었다. 이 반례는 회귀 테스트로 남아 있다(timezone.property.test.ts:276).

서울에서만 통과하던 테스트

두 번째는 2026년 8월 3일 교차 검토에서 나왔다. calendar에서 선택 표시할 칸을 정하는 코드가 변환을 두 번 하고 있었다. 칸은 이미 좌표인데 칸과 저장값을 둘 다 그 존의 날짜로 변환한 것이다. "1월 15일"을 고른 결과는 이랬다.

양수 오프셋 존에서는 두 번의 밀림이 상쇄돼 우연히 맞았고, 기존 테스트는 서울만 덮고 있었다. 같은 점검에서 반대 방향 위반도 나왔다. 보여줄 월을 정할 때 시점에 startOfMonth를 바로 걸어서, 서울에서 1월 1일을 값으로 주면 12월 달력이 열렸다.

기전은 달라도 어긴 규칙은 하나다. 변환은 방향마다 정해진 함수로 한 번만 한다.

이 사고로 core의 왕복 속성 테스트가 "대표 존 몇 개"에서 "런타임이 아는 존 전부"로 넓어졌다. (React 쪽 컴포넌트 테스트는 아직 America/New_York 같은 대표 존을 쓴다) 부호가 바뀌는 자리에서만 드러나는 결함은 표본으로 잡히지 않는다.

런던에서 늦게 잡히던 01:30

세 번째는 이 글의 DST 표를 다른 존으로 넓히다 나왔다. 1.4.7은 요청 시각을 UTC로 읽은 지점부터 오프셋을 쟀는데, 전환 뒤 오프셋이 0 이상인 존에서는 그 지점이 이미 전환 뒤라 늦은 오프셋으로 수렴했다. temporal-polyfill로 418개 존의 2020~2045년 전환을 전수 대조하니 겹침 전환 3,395건 중 1,908건에서 늦은 쪽을 골랐고 84개 존에 걸쳐 있었다. (틈 전환 3,394건은 모두 맞았고, 오프셋이 음수인 뉴욕은 우연히 맞았다)

#226에서 하루 전과 뒤를 읽도록 고쳐 @kalyx/core 1.4.8로 배포했고, 같은 대조를 timezone.dst-oracle.test.ts로 남겼다. (temporal-polyfill은 테스트에서만 쓴다) 'earlier'라고 잘못 적었던 소스 주석도 'compatible'로 고쳤다. 이번에도 표본이 한쪽 부호에 몰려 있었다.

정확성에 쓴 3KB

이 수정들에는 코드가 들었다. Kalyx는 기본 엔트리 번들에 CI 천장을 두고, 넘기는 PR은 필수 체크에서 실패한다. 12KB에서 시작해 기능이 들어올 때마다 1KB씩 올리던 그 천장을, 2026년 8월 timezone과 제약 정확성을 전면 수정하면서 17KB에서 20KB로 한 번에 올렸다.

크기는 README 배지에 나가 있던 셀링 포인트였다. 음수 오프셋 존에서 하루씩 밀리는 날짜 picker는 작든 크든 쓸 수 없다.

작다와 맞다 중 하나를 골라야 한다면 맞는 쪽이다. 지금 천장은 빠듯하다. 레포의 2026-09-11 번들 바이트 지도 문서에 따르면 dist/index.cjs를 Node 기본 gzip으로 잰 값이 20,259B, 천장이 20,480B로 여유가 221B다. (의존성을 외부로 남긴 자기 파일 크기라 앞 도표와는 다른 양이다) 다음 기능은 바이트를 먼저 회수해야 들어온다.

처음 생각과 달라진 결론

필자가 원한 것은 복잡한 날짜 라이브러리를 선언적으로 쓰는 것이었다. 만들고 나서 보니 선언적인 합성 API와 headless 완성형은 이미 있었다. 남은 차이는 더 안쪽에 있었다. 값을 시점 하나로 고정하고, 좌표와 시점 사이의 변환을 두 함수로 좁히고, 그 왕복을 모든 timezone에서 테스트로 지키는 것. Intl 기반 DST 처리, 문자열 adapter 경계, 컨텍스트 세 개로 만든 일곱 picker는 그 결정의 결과다.

공부라는 목표로 보면 가장 크게 배운 것은 "맞다"를 주장하는 방법이었다. 처음 글의 번들 비교는 다른 양을 재고 있었고, 서울에서 통과하던 테스트는 뉴욕에서 틀리고 있었다. 무엇을 쟀고 어떤 표본으로 확인했는지를 함께 적지 않으면 숫자는 쉽게 자랑이 된다.

한계도 분명하다. 메인테이너는 필자 한 명이고, React 19 전용이며, @kalyx/react의 npm 다운로드는 2026년 9월 5일부터 11일까지 200회였고 그중 156회가 1.4.7 배포일 하루에 몰려 있다. 좌표와 시점을 타입으로 가르지 못하는 문제는 문서로만 막고 있고, 스타일 접점인 classNames와 data-* 속성을 공개 API로 보장할지도 정하지 못했다. 접근성은 calendar grid, 입력 칸 combobox, 시간 목록 listbox 역할과 방향키, Home/End, PageUp/PageDown 탐색을 갖췄고 테스트 파일 8개의 jest-axe 검사를 CI에서 돌리지만, React Aria 만큼 검증됐다고 말할 근거는 아직 없다.

그래서 이미 MUI 앱이라면 MUI X를, 세그먼트 입력과 검증된 접근성이 우선이라면 React Aria를, calendar 하나면 react-day-picker를 먼저 보는 편이 맞다. 값이 JSON으로 오가는 폼에서 날짜가 하루씩 밀리는 문제를 겪어 봤다면 그때 Kalyx를 살펴봐 주시면 좋겠고, 더 좋은 풀이를 알고 있다면 GitHub Issue로 알려 주시면 감사하겠다.

pnpm add @kalyx/react

문서 사이트의 Playground에서 일곱 picker와 locale, timezone 설정을 직접 바꿔 볼 수 있다.

옛날에는 성능과 비용보다는 결과와 과정에 집중했다. AI가 산출한 결과물에 허점이 많다 보니 그것들을 검증해야 했고, 빠르게 결과물을 뽑아야 하다 보니 나를 비롯한 수많은 사람들이 토큰이 부족하면 결제하고 더 높은 구독제를 활용했다. 필자도 그랬다. (사실 처음 몇 달은 토큰 비용이 얼마나 들었는지조차 신경 쓰지 않았다.)

하지만 어느 시점이 지나가니 점점 토큰 사용에 대한 경각심이 생기게 되었다. 개인은 월 결제에 대한 부담감이 컸고, 기업은 인건비와 비용에 대한 고민이 깊어졌다. MCP와 function calling에서는 에이전트를 외부 시스템에 잇는 프로토콜을, Code intelligence의 네 계층에서는 코드 탐색 도구와 GitHub Trending을, Context file에서는 에이전트가 읽는 규칙 파일을 정리했다. 이렇게 지금까지의 글은 어떤 도구가 있고 그것을 어떻게 잘 활용할지에 더 집중해왔다. 필자도 그 방향이 필요하다고 생각하지만 시간이 지나면 결국 비용에 대한 이야기를 가장 궁금해할 것이라고 생각한다.

토큰이 정확히 무엇이고 어떻게 만들어지는지(BPE), prompt caching 이 단가를 깎는 트랜스포머 안쪽 동작은 무엇인지 같은 토큰의 동작 원리는 토큰의 원리 글에서 따로 정리해 두었다. 이 글은 그 토대 위에서, 비용이 어떻게 청구되고 어디서 비효율이 만들어지는지를 먼저 살펴본 뒤 검증된 절약 패턴을 정리한다. 주요 패턴에는 같은 작업을 여러 전략으로 호출해 직접 측정한 토큰 사용량을 붙였다.

토큰 비용은 어떻게 발생하는가?

토큰 비용이 어떻게 발생하는지, 어떤 원리로 청구되는지를 아주 가볍고 핵심적으로 살펴보자.

우리가 보낸 모든 텍스트(시스템 프롬프트, 도구 정의, 대화 기록, 사용자 메시지)가 입력 토큰이 되고, 모델이 만들어낸 응답이 출력 토큰이 된다. 모델 입장에서는 매번 호출이 처음 보는 입력이다. 우리가 어제 한 대화든 1분 전 호출이든, 새 호출에서는 같은 내용을 다시 통째로 입력으로 보낸다. (이 단순한 사실이 토큰 비용의 핵심이다. 모델은 기억이 없고, 우리가 매번 다시 들려준다.)

여기에 한 가지 변수가 더 붙는다. 같은 호출을 반복할 때 정적인 부분을 매번 새로 전송하는 비용이 너무 크다 보니, 주요 LLM 제공자들은 prompt caching 이라는 장치를 도입했다. 정적인 입력을 캐시에 한 번 저장해두고 다음 호출에서는 캐시에서 읽은 토큰만 훨씬 싼 가격으로 청구한다. (토큰이 BPE 로 어떻게 만들어지고, 캐시가 트랜스포머의 KV 캐시를 어떻게 재활용해 단가를 깎는지 같은 동작 원리는 토큰의 원리 글에서 따로 다뤘다. 여기서는 그 원리가 비용으로 어떻게 환산되는지에 집중한다.)

입력 토큰, 출력 토큰, 그리고 캐시 토큰

Anthropic SDK 가 응답으로 돌려주는 usage 객체에서 네 가지 필드를 살펴보자.

• input_tokens 보낸 입력 중 캐시 읽기를 제외한 부분
• output_tokens 모델이 생성한 응답
• cache_creation_input_tokens 이번 호출에서 처음 캐시에 저장된 토큰
• cache_read_input_tokens 기존 캐시에서 다시 읽은 토큰

이 네 필드에 각각 다른 단가가 곱해진다. 단가가 가장 비싼 것은 출력 토큰이고, 가장 싼 것은 캐시에서 읽은 토큰이다. Anthropic 공식 문서 기준으로 캐시 읽기는 기본 입력 단가의 0.1배, 즉 정확히 10% 수준이다. 캐시 쓰기는 5분 TTL(Time To Live, 캐시 유효 시간) 기준 1.25배, 1시간 TTL 기준 2배가 붙는다. 첫 호출에서 살짝 더 내고, 두 번째 호출부터 90%를 깎는 구조인 셈이다.

다만 캐시에는 잘 알려지지 않은 제약이 몇 가지 있다. 캐시 가능한 최소 토큰 수가 모델마다, 또 같은 패밀리 안에서도 버전마다 다르다. Anthropic 공식 문서 기준으로 Sonnet 4.6 과 Opus 4.8 은 1,024 토큰, Opus 4.7 은 2,048 토큰, Haiku 4.5 와 구세대 Opus 4.5/4.6 은 4,096 토큰이다. 그보다 짧은 프롬프트는 cache_control 을 걸어도 조용히 캐시되지 않는다. cache_control 브레이크포인트는 한 요청에 최대 4개까지만 둘 수 있고, 캐시는 tools → system → messages 순서의 계층으로 읽힌다. 그래서 앞쪽의 도구 정의 하나만 바뀌어도 그 뒤 캐시 전체가 무효화된다.

캐시가 어떻게 단가의 90% 를 깎는지는 트랜스포머의 KV 캐시를 호출 사이에서 재활용하는 구조에서 나오는데, 그 안쪽 동작은 토큰의 원리 글에서 자세히 다뤘다. 비용 관점에서 기억해 둘 핵심은 하나다. 캐시 적중은 프리픽스가 정확히 같을 때만 일어나므로, 정적인 부분은 앞에, 매번 바뀌는 동적인 부분은 뒤에 두어야 캐시가 깨지지 않는다. 타임스탬프 한 글자가 프롬프트 앞부분에 들어가도 그 뒤 캐시 전체가 무효화된다.

이쯤에서 자연스럽게 떠오르는 의문이 있다. "그런데 멀티턴 대화는 매 턴 입력이 달라지는데, 그럼 거의 매번 캐시가 깨지는 것 아닌가?" 결론부터 말하면 그렇지 않다. 대화의 입력은 매번 새로 쓰는 한 덩어리가 아니라, 앞에 쌓인 내용을 그대로 두고 뒤에 새 발화만 덧붙이는(append) 구조이기 때문이다. 시스템 프롬프트와 도구 정의, 그리고 지난 턴의 질문과 답변은 한번 확정되면 그대로 박제되고, 이번에 새로 친 질문만 맨 끝에 붙는다. 그래서 이번 턴 입력을 지난 턴 입력과 앞에서부터 비교하면, 처음 달라지는 지점은 늘 맨 끝의 새 질문이다. 전체로 보면 입력이 매번 다르지만, 프리픽스로 보면 앞쪽 대부분이 그대로라 캐시는 살아남는다. (캐시가 매 턴 깨지는 건 오히려 동적인 값을 프롬프트 앞쪽에 박아 넣는 잘못된 설계일 때뿐이다. 그래서 Claude Code 나 opencode 같은 도구는 앞쪽을 고정하고 뒤에만 덧붙이도록 설계되어 있고, 사용자가 캐시를 위해 따로 손댈 설정도 없다. 입력의 오타나 맞춤법이 캐시에 영향을 주지 않는 것도 같은 이유다. 그 변동은 늘 캐시 사정권 밖인 맨 뒤에서 일어난다.)

AI 비교

2026년 6월 기준 Anthropic, OpenAI, Google 의 공식 가격표를 한 표에 모아보면 흐름이 한눈에 들어온다. (단위는 백만 토큰당 USD. 코딩 워크플로에서 일상적으로 쓰는 모델 위주로 추렸다.)

세 프로바이더 모두 출력 단가가 입력의 5~6배다. 즉 출력이 길어지면 같은 답이라도 비용이 가파르게 오른다. 같은 티어 안에서도 모델 간 단가 차이가 3~6배 벌어진다. 단순 계산만 봐도, 출력을 짧게 받고, 같은 답이면 더 싼 모델을 쓰고, 정적인 입력은 캐시에 올린다 는 세 가지 원칙이 토큰 비용 절감의 큰 줄기다. (계산을 한 번 더 해보면 흥미롭다. 매 호출 1만 토큰짜리 정적 컨텍스트를 100번 재사용한다고 했을 때, GPT-5.5 기본 단가로는 $5, 캐시에서 읽은 토큰으로는 $0.50. 즉 한 컨텍스트를 100번 다시 쓸 때 캐시가 효과적으로 깎아주는 비용이 $4.5 인데, 첫 호출의 캐시 쓰기 부가비가 거의 없으니 두 번째 호출부터 바로 흑자다.)

캐시 메커니즘의 차이

비용 절감 비율이 비슷해도 안쪽 구조는 프로바이더마다 다르다. 어떤 차이가 왜 생기는지 알아두면 정책 결정이 쉬워진다.

세 모델의 설계 철학이 그대로 드러난다. Anthropic 은 캐시할 부분을 사용자가 명시적으로 잡아두는 대신, 첫 호출에서 약간의 프리미엄(1.25배)을 받고 그 뒤로는 깊이 깎아준다. 프리픽스 위치를 통제하기 쉬워 캐시 읽기율이 예측 가능하다. OpenAI 는 정반대로 모든 걸 자동에 맡긴다. 1,024 토큰 이상이면 자동으로 캐시되고 추가 비용도 없는 대신, 사용자가 캐시 동작에 개입할 여지가 적다. Google 은 두 방식을 동시에 제공하면서, 캐시를 사용자가 명시적으로 제어할 때 저장료를 따로 매긴다. 짧고 빈번한 캐시 사용이라면 암묵적 캐싱이 유리하고, 1시간 이상 보관되는 큰 컨텍스트라면 명시적 캐싱 + 저장료 모델이 적합하다는 식이다.

도구 정의와 토크나이저

여기에 의외로 큰 영향을 주는 변수가 두 가지 더 있다.

첫째는 도구 정의다. MCP 서버를 여러 개 붙이는 환경에서는 매 호출마다 도구 이름과 파라미터 스키마 전부가 입력에 함께 실리는데(이 비용을 실제로 얼마나 불어나게 하는지는 뒤에서 직접 측정해본다), 같은 도구를 그대로 쓰더라도 모델만 바꾸면 비용이 또 달라진다는 점은 여기서 짚어둘 만하다. Anthropic 공식 가격 문서를 보면 도구용 시스템 프롬프트의 길이 자체가 모델마다 다르다. Sonnet 4.6 과 Haiku 4.5 가 tool_choice: auto 기준 약 497 토큰인데, Opus 4.7 은 같은 자리에서 675 토큰을 쓰고 Opus 4.8 은 다시 290 토큰으로 내려와 있다. 모델 라우팅 전에 "현재 모델이 도구 정의를 얼마나 길게 풀어내는가" 부터 한번 확인해두면 의외로 큰 자릿수에서 차이가 난다.

둘째는 토크나이저(사람이 쓴 텍스트를 모델이 처리할 수 있는 토큰 단위로 잘게 쪼개는 도구) 자체의 효율이다. 토큰의 원리 글에서 짚었듯이 같은 텍스트라도 토크나이저에 따라 토큰 수가 달라진다. OpenAI 의 o200k_base 는 cl100k_base 대비 비영어권에서 토큰을 크게 절약하고, Anthropic 도 Opus 4.7 부터 새 토크나이저로 갈아타면서 같은 텍스트에 최대 35% 더 많은 토큰을 쓸 수 있다고 명시했다. 단가만 비교해 모델을 고르면 토크나이저 효율 차이에서 비용이 다시 새는 일이 생긴다. 모델 비교는 단가 × 예상 토큰 수의 곱으로 봐야 정직하다.

차이를 직접 확인해보면 한글에서 특히 두드러진다. OpenAI 의 두 토크나이저로 같은 문장을 토큰화해봤더니, 영어 기술 문장은 구버전과 신버전이 토큰 수가 똑같았지만 한글은 구버전(cl100k_base)이 신버전(o200k_base)보다 31~43% 더 많은 토큰을 썼다. 특히 눈여겨볼 것은 한글 문단이다. 167자짜리 한 문단이 구버전에서는 169토큰으로, 글자 수보다 토큰이 더 많게 나왔다. 한글 한 글자가 평균적으로 한 토큰을 넘게 잡아먹은 셈이다.

구버전이 한글을 바이트 단위로 잘게 부수는 반면, 신버전은 "개발", "입니다" 같은 자주 쓰이는 덩어리를 통째로 한 토큰으로 묶기 때문이다. 단가가 같아도 한글 위주의 작업이라면 토크나이저 효율만으로 청구액이 1.5배 이상 갈릴 수 있다는 뜻이다.

여기까지 보면 자연스럽게 떠오르는 질문이 하나 있다. "그러면 우리는 도대체 어디서 비효율을 만들어내고 있는 걸까?"

토큰을 낭비하는 흔한 패턴

AI 를 잘 쓴다고 생각하면서도 토큰이 비효율적으로 흘러나가는 상황은 의외로 흔하다. 필자 본인을 포함해 주변 개발자들의 패턴을 모아보면 몇 가지로 정리된다.

너무 많은 MCP 서버와 도구 정의

앞 절에서 짚었지만 다시 강조하고 싶다. MCP 서버(Linear, GitHub, Notion, Figma, Slack, Sentry)는 한 번 붙여두면 잘 떼지 않는다. 사용하지 않는 도구 스키마가 매 호출마다 입력 토큰으로 부풀어 올라간다. Claude Code 가 기본 활성화한 MCP Tool Search 가 이 문제를 대응하기 위해 세션 시작 시에는 도구 이름과 서버 설명만 올라가고, 전체 스키마는 그 도구를 실제로 호출할 때 그제야 로드된다.

이 차이가 얼마나 큰지 직접 재봤다. 필자가 작업 중인 Claude Code 세션의 MCP 도구 27개(serena 10, claude.ai OAuth 4세트 8, figma 2, agentmemory 7)를 두고, 같은 사용자 메시지를 두 설정으로 호출했다. 한 쪽은 MCP 가 하나도 안 깔린 상태, 다른 한 쪽은 27개가 다 attached 됐지만 모델이 호출할 수는 없는 상태이고 도구 호출 횟수는 양쪽 모두 0회로 맞췄다.

같은 질문, 같은 모델, 응답 의미도 동일한데, 입력 토큰만 41 → 10,335 (+10,294) 늘어났다 (Opus 4.7 기준). 1회 비용으로 환산하면 $0.0048 → $0.0563, 약 12배 비싸진다. 입력이 250배 부풀면서 prefill 부담이 함께 늘어 응답 시간도 +783ms 가 따라왔다. 액수 자체보다 와닿은 건, 사용자가 그 턴에 MCP 도구를 한 번도 부르지 않았는데도 매 호출마다 내는 비용 이라는 점이다. 앞 문단의 Tool Search 가 막아주는 게 이 비용이다. (필자는 이 측정 후로 평소 안 쓰는 MCP 서버를 지속적으로 관리중이다.)

컨텍스트 누적과 Lost in the Middle

긴 대화를 그대로 끌고 가면 호출당 입력 토큰만 늘어나는 게 아니라 모델의 정답률 자체가 떨어진다. Stanford 의 Liu 연구팀이 발표한 "Lost in the Middle" 논문은 핵심 정보가 컨텍스트의 시작이나 끝에 있을 때 가장 잘 찾고, 가운데에 묻혀 있을 때 성능이 눈에 띄게 떨어지는 U자형 곡선을 정량적으로 보였다. 토큰을 더 많이 쓰면서 답은 더 나빠지는 최악의 조합이 만들어지는 셈이다. 트랜스포머의 셀프 어텐션은 토큰 수의 제곱에 비례해 연산이 늘어나는 구조라, 컨텍스트가 길어질수록 한 토큰이 받는 어텐션의 절대량 자체가 묽어진다. 그리고 학습 분포상 시작과 끝에 중요한 정보가 몰려 있던 관성 때문에 가운데가 가장 먼저 약해진다.

좀 더 안쪽으로 들어가면, 모델이 토큰의 "위치" 를 다루는 방식 자체에 가운데를 묻는 두 가지 습성이 깔려 있다. 어렵게 들리지만 비유로 풀면 단순하다.

첫째, 모델은 가까이 있는 토큰에 더 귀를 기울인다. 요즘 공개 모델 대부분이 채택한 위치 표현 방식인 RoPE(Rotary Position Embedding, 회전 위치 임베딩)는 두 토큰이 멀리 떨어질수록 서로를 약하게 연결하도록 설계돼 있어서(거리가 멀수록 신호가 흐려지는 decay effect), 멀리 떨어진 토큰일수록 자연히 덜 주목받는다.

둘째, 모델은 맨 앞 토큰에 쓸데없이 많은 주의를 흘려보낸다. 모델은 매 순간 자기 주의력을 100% 로 꽉 채워 나눠 써야 한다는 제약(소프트맥스가 어텐션 총합을 1 로 강제한다)을 갖는데, 정작 지금 딱히 집중할 곳이 없을 때 남는 주의력을 어디론가 버려야 한다. 그 버리는 곳이 대개 문장 맨 앞의 첫 토큰이다. 이렇게 첫 토큰이 잉여 주의력을 빨아들이는 현상을 attention sink(어텐션 싱크, 주의력 배수구)라 부른다. (MIT 의 Xiao 연구팀이 StreamingLLM 논문에서 처음 정량적으로 분석한 구조인데, 첫 토큰에 중요한 정보가 있어서가 아니라 남는 주의력을 흘려보내는 배수구로 쓰이기 때문에 생기는 부산물에 가깝다.)

이 두 습성이 겹치면 주의력이 양 끝(가까운 최근 토큰 + 맨 앞 토큰)에 쏠리고, 정작 가운데에 묻힌 정보가 가장 약하게 다뤄진다. 중요한 건 이게 특정 모델의 버그가 아니라는 점이다. LLaMA, Mistral, Qwen 같은 공개 모델 대부분이 RoPE 계열을 쓰고 Claude·GPT 같은 비공개 모델도 비슷한 계열을 쓰는 것으로 알려져 있어, lost-in-the-middle 은 현대 트랜스포머 구조에 공통으로 깔린 편향에 가깝다.

최근에는 이 현상을 context rot 이라는 이름으로 부른다. Chroma 연구팀이 GPT-4.1, Claude 4, Gemini 2.5, Qwen3 를 포함한 18개 프론티어 모델을 같은 NIAH(needle in a haystack, 건초 더미에서 바늘 찾기) 과제에 던져본 분석은, 입력 토큰이 10k 에서 100k 이상으로 늘어났을 때 정확도가 모델에 따라 20~50% 까지 떨어지는 것을 정량적으로 보였다. 18개 모델 모두 길이가 늘면 성능이 떨어졌고, 가장 천천히 떨어진 것이 Claude 계열이었다. Anthropic 도 이를 트랜스포머의 n² 어텐션에서 비롯된 "어텐션 예산" 이 토큰마다 소진되는 문제로 설명한다. 결국 컨텍스트를 가볍게 유지하는 일은 비용 절감인 동시에 정답률을 지키는 일이기도 하다.

무지성 서브에이전트 호출

서브에이전트가 좋다고 모든 작업을 위임하는 것도 함정이다. 서브에이전트는 부모와 별도의 컨텍스트에서 시작하므로 시스템 프롬프트와 도구 정의를 처음부터 다시 싣는 고정 비용이 든다. 짧은 셸 명령이나 단순 git 조회처럼 가벼운 작업을 서브에이전트에 위임하면, 본문 정리 효과보다 시작 비용이 더 커지는 손해 구조가 된다. Anthropic 의 multi-agent research system 공개 보고에 따르면 일반 채팅 대비 단일 에이전트가 약 4배, 멀티 에이전트 시스템이 약 15배의 토큰을 쓴다. 이 4배에서 15배의 추가 비용을 정당화할 만한 정답률 향상이 있을 때만 위임이 의미가 있다는 뜻이다.

같은 함정이 MCP 도구 부착에도 똑같이 적용된다. 도구 하나가 켜질 때마다 그 스키마가 매 턴 시스템 프롬프트에 실리고, 모델이 그 도구를 안 쓰는 턴에도 비용은 동일하게 청구된다. "안 쓸지도 모르니 다 켜두자" 가 직관적으로 안전해 보이지만, 실제 측정해보면 그렇지 않다.

필자가 facebook/react v19 의 reconciler 소스에 대해 같은 질문 배치를 아래 3가지 유형으로 분리해 정답률과 비용을 측정해봤다.

• 도구 없이
• 단일 도구로 (CodeGraph, Serena, ripgrep, bare grep)
• 네 도구를 동시에 부착

세 가지가 그대로 드러난다. (여기서 재현율은 정답을 얼마나 빠뜨리지 않고 찾았는가를 의미한다.)

• 도구 없음 은 평균 재현율 0.31 에 그쳤다. 도구의 가치 자체는 분명하다는 것을 확인했다.
• Serena (LSP) 단독 이 재현율 1.00, 비용 $0.38 로 모든 단독 전략 중 가장 효율적이었다.
• 네 도구를 전부 부착 했을 때 재현율은 오히려 0.89 로 떨어지고 비용은 $0.47 로 늘었다. 특히 다중 hop 질문에서 전부 부착의 점수가 CodeGraph 단독의 점수 (0.78 / 0.88) 와 소수점 둘째 자리까지 똑같이 나왔다. 모델이 네 도구 중 하나에 쏠려 그 도구의 약점을 그대로 받은 결과다.

서브에이전트와 도구 부착에 공통으로 작동하는 원칙은 하나다. 추가 비용이 정답률 향상으로 정당화될 때만 의미가 있다는 것이다. 작업 도메인에 맞는 도구 하나를 정확히 고르는 게, 안 쓸지도 모르니 다 켜두는 것보다 더 싸고 더 정확하다.

그래서, 검증된 절약법은 무엇일까? 절약할 수 있는 방법이 정말로 존재할까?

검증된 토큰 절약법

각 절약 패턴은 서로 다른 비용 축을 공격한다. 어떤 건 입력을 줄이고, 어떤 건 같은 입력의 단가를 떨어뜨리며, 어떤 건 같은 작업을 더 싼 모델에 맡긴다. 하나씩 살펴보자.

Prompt caching

가장 즉각적인 효과를 내는 방법이다. 앞에서 본 대로 캐시 읽기는 기본 입력 단가의 0.1배라, 첫 호출에서 약간의 쓰기 프리미엄(1.25배)을 내고 나면 두 번째 호출부터는 같은 정적 부분을 1/10 가격으로 다시 쓸 수 있다.

절약법 관점에서 다시 강조하고 싶은 건 한 가지다. 어느 방식이든 호출마다 거의 같은 부분(도구 정의, 코드 스니펫, RAG 컨텍스트)이 정확히 캐시의 사정권이고, 그 정적 블록을 동적인 내용(이번 차례의 질문, 방금 받은 도구 결과)과 섞지만 않으면 효과가 그대로 나온다는 점이다. 직접 API 를 다룬다면 정적 블록을 앞에 모으고 동적인 부분을 그 뒤로 빼는 것만으로 절약의 대부분이 실현되고, Claude Code 나 opencode 같은 완성된 도구를 쓴다면 이 배치를 도구가 알아서 처리한다.

Batch API 로 비동기 작업 모으기

호출이 즉시 끝나야 하는 작업이 아니라면 Batch API 는 단가 자체를 깎는 가장 단순한 장치다. Anthropic, OpenAI, Google 모두 입력과 출력 토큰에 똑같이 50% 할인을 적용하고 그 대가로 결과는 최대 24시간 안에 받기로 한다. Anthropic 의 경우 실측상 대부분의 배치가 한 시간 안에 끝나지만 SLA 자체는 24시간이라는 의미다. 같은 호출을 그대로 둔 채 단가만 절반으로 내려가는 셈이라 적용 비용 자체가 거의 없다.

이 50% 가 흥미로운 건 다른 절약 장치와 곱셈으로 쌓인다는 점이다. Anthropic 공식 문서는 캐싱과 배치의 할인이 서로 곱해진다고 명시한다(stack). 정적 입력 단가로 따지면 표준 × 0.5(배치) × 0.1(캐시 읽기) = 0.05배, 즉 정적 부분만 보면 표준의 5% 수준까지 떨어질 수 있다. 두 할인이 더해지는 게 아니라 곱해진다는 게 핵심이다.

얼마나 차이가 나는지 직접 계산해봤다. 정적 컨텍스트 1만 토큰 + 동적 입력 500토큰 + 출력 1,000토큰짜리 작업을 100건 처리한다고 가정하고, Opus 4.8 의 단가로 네 전략의 비용을 비교했다.

캐싱만 쓰면 57%, 배치만 쓰면 50% 가 빠지는데, 둘을 함께 쓰면 79% 까지 떨어진다. 두 할인이 단순히 더해진 게 아니라 정적 입력 구간에서 곱해졌기 때문이다. (출력 토큰은 캐시 대상이 아니라 배치 50% 할인만 받으므로, 출력 비중이 큰 작업일수록 전체 절감폭은 79% 보다 완만해진다. 정적 입력 비중이 클수록 곱셈 효과가 더 크게 나타난다.) 야간 코드베이스 색인, 발행 전 글 평가, 데이터 추출, 정기 리포트처럼 사람이 화면 앞에서 결과를 기다리지 않아도 되는 영역이 의외로 넓다.

다만 모든 작업이 비동기로 미뤄지지는 않는다. 사용자가 답을 보면서 다음 액션을 결정해야 하는 코딩 에이전트 본 세션이나 대화형 챗 UI 처럼 응답 시간 자체가 가치인 영역에서는 Batch 가 어울리지 않는다. 작업을 "결과를 곧장 봐야 한다"와 "다음 출근까지 받으면 된다" 두 줄로 분류해두는 것만으로도 청구액의 절반이 빠진다.

Subagent 로 verbose 작업 격리하기

Claude Code 공식 문서 표현을 그대로 옮기면, 서브에이전트는 "자신의 격리된 컨텍스트 윈도우에서 실행되며, 중간 도구 호출과 결과는 서브에이전트 안에 머물고 최종 메시지만 부모로 돌아간다." 즉 verbose 한 작업을 통째로 위임해두면 부모 컨텍스트에는 깔끔한 요약만 들어온다. Anthropic 의 context engineering 글에 따르면 서브에이전트는 수만 토큰을 쓰며 탐색하더라도 부모에게는 보통 1,000~2,000 토큰의 압축된 요약만 돌려준다. 부모 컨텍스트를 가볍게 유지하는 효과는 분명하다.

verbose 한 작업은 정답 한 줄 얻으려고 그 과정에 수많은 토큰을 토해내는 종류의 작업을 의미하는데, 테스트 실행/문서 검색/로그 분석등의 작업이 여기에 속한다.

다만 한 가지 오해를 짚어둘 필요가 있다. 서브에이전트가 곧 총비용 절감인 것은 아니다. Anthropic 자체 보고에 따르면 에이전트는 일반 채팅 대비 약 4배, 멀티 에이전트 시스템은 약 15배의 토큰을 쓴다. 서브에이전트는 비싼 장기 컨텍스트에서 verbose 한 출력을 빼내 정답률과 부모 비용을 지키는 장치이지, 전체 토큰 지출을 무조건 깎아주는 마법은 아니라는 것이다. 그래서 앞서 짚은 대로 "절약된 본문 정리 비용이 시작 비용보다 클 때만" 위임한다는 원칙이 필요하다. 짧은 작업은 그냥 부모가 직접 처리하는 편이 싸다.

여기에 적용 도메인에 대한 한 가지 더 있다. Anthropic 의 multi-agent research system 보고는 자신들의 내부 평가에서 Opus 4 단일 에이전트 대비 Opus 4(리더) + Sonnet 4(서브에이전트들) 구성이 90.2% 의 성능 향상을 보였다고 밝혔다. 다만 이 향상은 모든 도메인에서 동일하지 않다. 같은 글에서 Anthropic 은 "에이전트들이 같은 컨텍스트를 공유해야 하거나 에이전트 간 의존성이 많은 도메인은 멀티 에이전트에 적합하지 않다" 고 명시했고, 코딩 작업이 정확히 그런 경우라고 못 박았다. 리서치는 독립적인 방향으로 병렬 탐색이 가능하지만, 코드는 한 함수의 변경이 다른 함수에 영향을 주는 의존성 그래프 위에서 움직이기 때문이다. (그래서 본인이 코딩 작업에 멀티 에이전트 구성을 쓰고 있다면, 정말 그 워크플로가 병렬 탐색에 가까운지 한 번 돌아볼 가치가 있다. 단일 에이전트 + 격리된 탐색 서브에이전트 하나 정도가 코딩 도메인에는 더 안전한 기본값일 수 있다.)

compact 와 progressive disclosure

Claude Code 의 /compact 는 현재까지의 대화 전체를 요약본으로 압축해 새 컨텍스트로 재시작하는 명령이다. Anthropic 의 공식 설명에 따르면 압축은 단순한 토막내기가 아니라 의미 단위의 요약이라, 진행 중인 작업 맥락과 최근 변경 사항은 남고 반복적인 도구 출력처럼 다시 참조할 필요가 적은 부분은 버려진다. /clear 가 모든 것을 날린다면 /compact 는 요약을 남긴다는 점이 다르고, 컨텍스트 윈도우가 95% 가까이 차면 auto-compact 가 자동으로 같은 일을 한다. 길어진 세션을 일정 지점에서 정리해주면 입력 토큰 누적이 끊긴다.

좀 더 안쪽을 들여다보면, /compact 는 사용자가 명시적으로 부르는 마지막 단계일 뿐 그 앞에 자동으로 동작하는 4단계의 컨텍스트 압축 파이프라인이 더 있다. Claude Code 의 내부 동작을 분석한 외부 연구("Dive into Claude Code") 에 따르면 모든 호출 직전에 query.ts 가 다음 다섯 단계를 차례로 점검한다.

• Budget Reduction 은 개별 도구 출력의 크기 한도를 넘은 부분을 잘라낸다.
• Snip 은 시간 축에서 오래된 히스토리를 끊는다.
• Microcompact 는 캐시 인식을 유지한 채 미세 압축을 수행한다.
• Context Collapse 는 매우 긴 히스토리를 read-time 으로 다시 투영해 차원을 줄인다.
• Auto-Compact 는 의미 단위의 압축을 95% 시점에 마지막 수단으로 발동한다.

위로 갈수록 가볍고 싸며, 아래로 갈수록 무겁지만 효과가 크다. 단일 압축 전략으로 모든 컨텍스트 압력을 해소할 수 없다는 인식이 이 5단 구조의 설계 근거다. 사용자가 /compact 를 명시적으로 부르는 건 이 자동 파이프라인의 마지막 칸을 앞당겨 발동하는 행위에 가깝다.

비슷한 사고방식이 Claude Code 의 Skills 구조에도 들어 있다. /compact 가 이미 쌓인 컨텍스트를 사후에 줄이는 장치라면 /skills 의 3단 로딩은 애초에 안 쌓이게 하는 장치이다.

Anthropic 문서 기준으로 스킬은 세 단계로 로드된다. 이름과 한 줄 설명(약 100 토큰)만 세션 시작 시 컨텍스트에 들어가고, 본문(SKILL.md, 5천 토큰 미만)은 그 스킬이 발동되어야 그제야 로드되며, 번들된 스크립트나 리소스는 bash 로 실행될 때 출력만 돌아올 뿐 코드 자체는 컨텍스트에 들어오지 않는다. 그래서 수십 개의 스킬을 설치해도 시작 컨텍스트는 거의 늘지 않는다.

모델 라우팅, 같은 답이면 더 싼 모델로

Opus 4.8 와 Haiku 4.5 의 입력 단가 차이는 5배다. 단순 검색, 탐색, 짧은 요약 같은 작업까지 무조건 가장 큰 모델로 처리하는 것은 비용 면에서 큰 손해다. 작업의 난이도에 따라 Haiku → Sonnet → Opus 순으로 라우팅하고, 정말 추론이 무거운 단계에서만 Opus 를 부르는 패턴이 점점 표준이 되어 가고 있다. LMSYS 의 RouteLLM 연구는 GPT-4 품질의 95% 를 유지하면서 강한 모델 호출을 14% 로 줄이는 라우터를 보였다(벤치마크는 코딩 특화가 아닌 일반 추론 기준이라는 점은 감안해야 한다).

도구 지형도도 빠르게 정착했다. 상용 게이트웨이로는 OpenRouter, Martian, NotDiamond 가 있고, 오픈소스 셀프호스트 진영에는 LMSYS 의 RouteLLM 과 LiteLLM·Bifrost 같은 비용 가시화 레이어가 자리 잡았다. Anthropic 생태계 안에서는 Agent SDK 의 모델 선택 인자, Claude Code 서브에이전트의 model 필드(Explore 는 기본이 Haiku 다), /model 슬래시 명령이 모두 이 라우팅을 위한 장치다. 다만 여기서 한 가지 짚어야 할 부분이 있다. API 를 직접 호출하면 입력 난이도를 보고 모델을 자동으로 골라주는 일은 일어나지 않는다. Anthropic·OpenAI·Google API 모두 사용자가 모델 이름을 명시한 그대로 도는 것이 기본이고, 자동 라우팅은 제품(Cursor 의 Auto, ChatGPT 의 auto 모드, OpenRouter 의 openrouter/auto)에서만 켜져 있는 옵션이다. 라우팅으로 비용을 줄이고 싶다면, 게이트웨이를 붙이든 분류기를 깔든 어쨌든 직접 구축해야 한다는 뜻이다.

그렇다고 외부 자동 라우터를 무작정 붙이는 것이 답이냐 하면 또 그렇지 않다. OpenRouter 의 Auto Router 처럼 호출마다 모델을 동적으로 바꿔주는 라우터는 앞에서 본 prompt caching 과 정면으로 충돌한다. Anthropic 의 ephemeral cache 는 같은 모델 + 같은 프리픽스가 일치할 때만 적중하기 때문에, 호출마다 모델 키가 바뀌면 캐시 키 자체가 매번 어긋난다. 캐시 읽기로 단가를 9할 깎던 효과를 그대로 잃는다는 뜻이고, 라우팅으로 절반 가까이 아끼다가 캐시 미스로 다시 토해내는 경우도 흔하다. OpenRouter 가 이를 인지하고 session_id 기반 스티키니스 옵션을 권장하는 것도 같은 이유다.

그래서 실무가 결국 합의한 형태는 의외로 단순하다. 호출마다 동적으로 분류하지 말고, 작업 타입별로 정적으로 분기하라는 쪽이다. 앞에서 본 서브에이전트의 model 필드가 이 패턴이다. Explore 서브에이전트는 늘 Haiku 로 도는 코드 탐색 레인을 가지고, 코드 리뷰 서브에이전트는 늘 Opus 로 도는 리뷰 레인을 가진다. 각 레인 안에서는 같은 모델·같은 시스템 프롬프트·같은 도구 정의가 반복되니 각 모델마다 자기만의 캐시가 따로 누적되며 적중한다. 결국 "라우팅이 표준이 되어 가고 있다" 는 말은, 호출마다 분류기가 돌아가는 동적 라우팅이 아니라 "코디네이터 + 실행자" 형태의 작업 타입별 정적 분기가 표준이 되었다는 의미에 가깝다. 라우팅과 캐싱이 같은 글에 모순 없이 공존할 수 있는 이유도 거기에 있다.

Cursor Composer 2.5

조금 결이 다른 절약법이지만 Cursor 와 같은 에이전트를 활용할 수 있다. Cursor 가 2026년 5월 18일 공개한 자체 모델 Composer 2.5 는 Moonshot AI 의 오픈소스 체크포인트 Kimi K2.5 를 기반으로 코딩 작업에 특화 파인튜닝된 모델이다. Cursor 팀은 자체 벤치마크에서 Claude Opus 4.7 과 비등한 코딩 성능을 약 1/10 가격으로 낸다고 밝혔다. 공개된 가격을 보면 기본 단가가 입력 $0.50 / 출력 $2.50 로, Opus 4.8 의 입력 $5.00 / 출력 $25.00 과 비교하면 정확히 자릿수가 하나 다르다.

특화 모델의 벤치마크 수치는 Cursor 가 자체 측정한 것이라 절대값을 그대로 옮기기보다, "코딩 전용으로 학습한 작은 모델이 범용 프론티어 모델과 같은 작업에서 비등하게 쓸 만한 성능을 내면서 비용은 자릿수 단위로 떨어진다" 는 흐름으로 읽는 편이 안전하다. 이 흐름은 2026년 들어 가장 뚜렷한 절약 트렌드 중 하나다.

이 흐름이 흥미로운 진짜 이유는 단가만 깎는 게 아니라 IDE 와 같이 설계되었을 때 입력 토큰 자체도 줄어든다는 점이다. Composer 나 Cascade 같은 모델은 IDE 가 보내는 코드베이스 컨텍스트(현재 파일, 인접 파일, 인덱스된 심볼)를 효율적으로 소비하도록 학습돼 있어, 같은 작업을 시켜도 범용 모델이 "관련 파일을 더 보여달라" 며 grep·read 를 더 자주 도는 만큼의 입력 토큰 부풀음이 줄어든다. 단가가 자릿수 단위로 떨어진 위에 토큰 수까지 살짝 깎이는 셈이라 실제 비용 절감폭은 단가 차이 그 이상이 된다.

컨텍스트를 컨텍스트 밖으로

2026년 들어 가장 흥미로운 흐름은 "필요한 것만, 필요할 때" 컨텍스트에 올리는 방향이다. Anthropic 은 이를 just in time(JIT) 컨텍스트라고 부른다. 모든 자료를 미리 컨텍스트에 박아두는 대신, 파일 경로나 쿼리 같은 가벼운 참조만 들고 있다가 실제로 필요할 때 도구로 끌어오는 방식이다. Claude Code 가 코드베이스 전체를 인덱싱해 통째로 싣지 않고 glob/grep 으로 그때그때 파일을 읽어 들이는 것이 바로 이 패턴이다.

Anthropic 이 Sonnet 4.5 와 함께 공개한 memory tool 과 context editing 도 같은 철학에서 나왔다. 여기서 한 가지 짚고 갈 것이 있다. memory tool 의 "메모리" 는 흔히 떠올리는 것들과 다르다. 세션 안에서 쌓이는 대화 기록(컨텍스트 윈도우 안에 있다가 세션이 끝나면 사라지는)도 아니고, CLAUDE.md 처럼 사람이 미리 작성해 시작할 때 자동으로 실리는 설정 파일도 아니다. memory tool 은 모델이 직접 파일을 쓰고 읽는 도구다.

좀 더 깊이 들여다보면 두 도구의 설계는 의외로 단순한 인터페이스다. memory tool 은 Claude 가 사용자 인프라에 마련된 전용 메모리 디렉토리에 대해 파일을 생성·읽기·갱신·삭제하는 네 가지 작업을 수행하는 식이다. 즉 모델은 "텍스트 어딘가에 적어두라" 가 아니라 일반적인 파일 시스템처럼 메모를 다룬다. 저장 위치를 사용자 인프라에 두는 설계가 핵심인데, 이로써 Claude 가 컨텍스트 윈도우 밖에 영구적으로 들고 다닐 수 있는 메모리가 생기는 동시에 그 데이터의 저장과 보관 방식은 사용자가 통제한다. 세션 메모리가 컨텍스트 안에서 휘발된다면, 이 메모리는 컨텍스트 밖에 남아 다음 세션까지 이어진다. context editing 은 반대 방향에서 같은 일을 한다. 토큰 한도에 다가가면 오래되어 더는 참조되지 않는 도구 호출 결과를 자동으로 비워 대화 흐름은 유지하면서 에이전트가 더 오래 돌 수 있게 한다.

Anthropic 자체 평가에서는 이 둘을 함께 적용했을 때 기준선 대비 39%, context editing 단독으로는 29% 의 성능 향상이 있었고, 100턴짜리 웹 검색 평가에서는 토큰 소비가 84% 줄었다고 보고한다. (벤더 자체 벤치마크라는 점은 감안하되, 방향성만큼은 분명하다. 컨텍스트는 채우는 것보다 비우는 설계가 중요해지고 있다.) 이 흐름은 Claude Code 의 /compact 5단 파이프라인과도 결이 같다. 다른 점은 /compact 가 컨텍스트 내부에서 줄이는 일이고, memory tool 은 컨텍스트 바깥에 별도 저장소를 두는 일이라는 것. 둘은 충돌하지 않고 보완한다.

마무리

여기까지 정리하고 보면, 토큰 절약은 결국 세 가지 축으로 환원된다. 같은 일이면 더 적게 보내기, 같은 입력이면 더 싸게 보내기, 같은 답이면 더 싼 모델에 맡기기. Prompt caching, Batch API, subagent 격리, /compact, memory tool 과 context editing, 모델 라우팅, 특화 모델 같은 패턴들은 결국 이 세 축 중 어디를 공격하느냐의 차이일 뿐이다. 그리고 2026년의 흐름을 한마디로 줄이면, 컨텍스트는 채우는 기술에서 비우고 골라내는 기술(context engineering)로 무게중심이 옮겨가고 있다. context rot 이 보여주듯 가벼운 컨텍스트는 비용뿐 아니라 정답률에도 이로운 쪽이기 때문이다.

물론 정답은 없다. 팀마다 작업 패턴이 다르고, 같은 사람 안에서도 글을 쓸 때와 코드를 짤 때 비용 구조는 달라진다. 다만 한 가지 확실한 건, 생태계가 빠르게 움직이는 만큼 "어제 맞았던 절약 패턴이 오늘도 맞을 거라는 가정" 만큼은 점점 위험해지고 있다는 점이다. 새로 나오는 모델·도구·가격표를 꾸준히 따라가면서 각자의 작업 위에서 작은 POC 로 검증해보는 습관이, 결국 가장 비싸 보이지 않으면서도 가장 오래 가는 절약법이 될 것이라 생각한다. 이 글을 읽는 독자분들도 자기만의 토큰 가계부를 한 번쯤 꺼내보시길 권하고 싶다. (절약 전략들이 왜 그렇게 동작하는지 그 뿌리가 궁금하다면, 토큰의 원리 글에서 BPE 와 KV 캐시 이야기를 함께 읽어보면 좋겠다.)

그리고 한 가지 질문이 남는다. 컨텍스트를 비우고 골라내는 기술까지 왔다면, 그 다음은 어디일까. 이미 공개된 자료들을 따라가 보면 무게중심은 컨텍스트에서 한 칸 더 바깥으로, 에이전트라는 시스템 전체를 어떻게 굴리고(harness 설계) · 잘 굴렀는지 어떻게 측정하며(eval) · 잘못 굴렀을 때 어떻게 가둘지(containment)로 넓어지고 있다. 흥미롭게도 이 글이 줄곧 강조한 "직접 POC 로 측정하라" 는 태도가 시스템 단위로 커지면 정확히 eval 이 된다. 이 다음 방향에 대한 이야기는 컨텍스트 다음 글에서 따로 자세히 다뤄보려고 한다.

필자는 그동안 AI 도구를 어떻게 잘 쓸지, 어떤 도구가 유행이고 왜 유행하는지를 주로 다뤄왔다. 그러다 토큰 절약법 글을 정리하면서 한 가지를 새삼 느꼈다. 비용을 줄이는 방법을 이야기하려면 결국 "토큰이 무엇이고 어떻게 청구되는가"를 먼저 알아야 하는데, 정작 그 토대를 제대로 짚고 넘어간 적이 없었다는 점이다. (절약법을 쓰다 보니 토큰 동작 원리만 따로 떼어 한 편으로 다룰 분량이 나왔다.)

그래서 이 글은 절약법으로 들어가기 전의 토대에 해당한다. 토큰이 단어도 글자도 아니라면 정확히 무엇인지(BPE), 토큰이 어떤 모습으로 모델에 들어가는지(임베딩), 입력보다 출력이 왜 비싼지(prefill/decode), prompt caching 이 단가를 깎는 이유가 트랜스포머(신경망 설계도) 안쪽 어디에서 나오는지(KV 캐시), 그리고 컨텍스트가 길어질수록 왜 비싸지는지(어텐션의 제곱 비용)까지를 차례로 정리한다. 절약의 실천법이 궁금하다면 이 글 다음에 토큰 절약법으로 이어 읽으면 된다.

토큰은 단어도 글자도 아니다

먼저 가장 기본이 되는 사실부터 짚는다. 토큰은 단어도 아니고 글자도 아니다. 모델이 학습 데이터에서 자주 등장한 문자 시퀀스를 압축해 만든 어휘의 단위다.

우리가 흔히 "이 문장은 몇 단어야?" 라고 세는 직관과 모델이 텍스트를 쪼개는 방식은 다르다. 모델은 자주 같이 등장하는 글자 조합을 하나의 단위로 묶어 두고, 텍스트가 들어오면 그 어휘 사전에 맞춰 잘게 나눈다. 그래서 같은 한 단어라도 어떤 건 토큰 하나로, 어떤 건 토큰 여러 개로 쪼개진다.

이 어휘 사전을 만드는 알고리즘이 거의 모든 현대 LLM 의 공통 토대인 BPE 다.

BPE 알고리즘

BPE(Byte Pair Encoding, 바이트 쌍 부호화)는 자주 같이 등장하는 인접 심볼 쌍을 반복적으로 하나의 새 심볼로 병합해서 어휘를 키워가는 알고리즘이다.

흥미로운 건 이게 원래 자연어 처리용으로 태어난 알고리즘이 아니라는 점이다. BPE 는 1994년 Philip Gage 가 데이터 압축 기법으로 처음 제안했다. 데이터에서 가장 자주 등장하는 바이트 쌍을, 데이터에 쓰이지 않은 바이트 하나로 치환하고 그 치환 규칙을 따로 표로 저장하는 압축 방식이었다.

이걸 신경망 번역의 어휘 문제에 끌어온 것이 에든버러 대학의 Sennrich 연구팀이다. 2015년에 공개되고 ACL 2016 에서 발표된 "Neural Machine Translation of Rare Words with Subword Units" 논문에서, 이들은 고정된 어휘 사전으로는 희귀어나 처음 보는 단어를 다룰 수 없다는 한계를 BPE 로 풀었다. 단어를 통째로 외우는 대신 더 작은 부분단어(subword) 조각의 조합으로 표현하면, 사전에 없던 단어도 조각들로 인코딩할 수 있다는 발상이다.

작동 과정 자체는 의외로 단순하다.

1. 처음에는 글자 하나하나가 토큰 하나다.
2. 말뭉치에서 가장 자주 인접해 등장하는 토큰 쌍을 찾는다.
3. 그 쌍을 하나의 새 토큰으로 병합하고, 말뭉치 전체에서 해당 쌍을 새 토큰으로 치환한다.
4. 어휘 크기 한도에 도달할 때까지 2~3 을 반복한다.

그래서 처음엔 글자 하나가 토큰 하나지만, "th", "the", "tion" 처럼 자주 등장하는 조합이 점점 하나의 토큰으로 합쳐진다. 자주 쓰이는 패턴일수록 더 큰 덩어리로 묶이는 셈이다.

GPT 계열은 여기서 한 단계 더 들어간 byte-level BPE 를 쓴다. 텍스트를 글자가 아니라 UTF-8 바이트 스트림으로 먼저 변환한 뒤 BPE 를 적용하는 방식이다. 이렇게 하면 기본 어휘가 256개(바이트의 가짓수)로 작게 출발하면서도, UTF-8 로 표현 가능한 모든 텍스트를 처음 보는 문자(unknown token) 없이 인코딩할 수 있다. 이모지든 한자든 특수문자든, 최소한 바이트 단위로는 무조건 표현 가능하다는 보장이 생기는 것이다.

같은 텍스트, 다른 토큰 수

이 구조 때문에 같은 텍스트라도 토크나이저(사람이 쓴 텍스트를 모델이 다룰 수 있는 토큰 단위로 쪼개는 도구)에 따라 토큰 수가 크게 달라진다. 어휘 사전이 어떻게 학습됐느냐에 따라 같은 문장이 더 잘게도, 더 큰 덩어리로도 쪼개지기 때문이다.

OpenAI 가 GPT-4o 와 함께 공개한 자료를 보면 이 차이가 잘 드러난다. GPT-4o 계열의 새 토크나이저 o200k_base 는 GPT-4 계열의 cl100k_base 대비 같은 텍스트를 더 적은 토큰으로 표현한다. 영어는 약 1.1배 효율적인 정도지만, 비영어권으로 갈수록 격차가 벌어진다. 공개된 짧은 예문 기준으로 중국어와 일본어는 약 1.4배, 한국어는 약 1.7배, 힌디어는 약 2.9배까지 토큰이 줄어든다. (한국어 사용자 입장에서 토크나이저 세대 차이가 영어보다 더 크게 체감된다는 게 흥미로운 지점이다.)

조금 더 넓게 보면 언어 자체에 따른 격차도 있다. cl100k_base 를 기준으로 여러 언어를 비교한 Yennie Jun 의 분석을 보면, 같은 의미의 문장도 영어가 거의 항상 최소 토큰이고 고유 문자 체계를 쓰는 언어일수록 토큰이 길어진다. 힌디어나 벵골어는 영어의 5배, 버마어는 10배가 넘는 토큰을 쓰기도 한다. 한국어나 중국어도 영어보다는 길게 토큰화되지만, 그 극단적인 언어들만큼은 아니다.

여기서 실무적으로 중요한 함의가 하나 나온다. Anthropic 도 Opus 4.7 부터 새 토크나이저를 도입하면서 공식 가격 문서에 "같은 텍스트가 이전 모델 대비 최대 35% 더 많은 토큰으로 청구될 수 있다" 고 명시했다. 단가가 같아도 토큰 수가 늘면 청구액은 그대로 늘어난다는 것이다. 모델 비교는 단가만 볼 게 아니라 단가 × 예상 토큰 수의 곱으로 봐야 정직하다.

그런데 이렇게 쪼개진 토큰이 모델 안으로 들어갈 때, 글자나 단어 그대로 들어가는 건 아니다. 그렇다면 토큰은 어떤 모습으로 모델에 입력되는 걸까?

토큰이 모델에 들어가기까지

신경망은 텍스트를 직접 다루지 못한다. 모델이 계산할 수 있는 건 결국 숫자, 정확히는 벡터(여러 숫자를 늘어놓은 배열)뿐이다. 그래서 토큰은 모델에 들어가기 전에 몇 단계를 거쳐 숫자로 바뀐다.

순서대로 정리하면 이렇다.

1. 텍스트 → 토큰: BPE 토크나이저가 텍스트를 토큰 조각으로 쪼갠다.
2. 토큰 → 토큰 ID: 각 토큰은 어휘 사전에서 자기 자리를 가리키는 정수 ID 하나로 매핑된다. 예를 들어 " the" 가 사전의 1,234번째 토큰이라면 그 토큰은 ID 1234 가 된다.
3. 토큰 ID → 임베딩 벡터: 이 ID 로 임베딩 행렬(embedding matrix)의 해당 행을 꺼내 온다. 임베딩 행렬은 vocabulary size × model dimension (d_model) 크기의 거대한 표인데, 토큰 ID 하나가 그 표의 한 행, 즉 벡터 하나에 대응된다. 이 벡터가 토큰의 "의미" 를 담은 좌표라고 보면 된다.
4. 위치 정보 더하기: 셀프 어텐션은 그 자체로는 토큰의 순서를 모른다. "나는 너를 좋아해" 와 "너를 나는 좋아해" 를 똑같이 본다는 뜻이다. 그래서 각 토큰 벡터에 위치 정보를 주입해 순서를 알려준다.

말로만 보면 추상적이니, 이 네 단계를 직접 만져볼 수 있는 위젯을 하나 붙여둔다. 입력 문장을 바꾸거나 토큰을 클릭하면, 그 토큰이 ID 를 거쳐 임베딩 벡터가 되고 위치 정보가 더해져 최종 입력 벡터가 되기까지의 흐름을 따라갈 수 있다. (표시 차원 수를 줄여놨을 뿐 실제 GPT-4 의 벡터는 12,288 차원이라는 점을 떠올리며 보면 좋다.)

여기서 모델 차원(d_model)은 토큰 하나를 표현하는 벡터의 길이다. 원조 트랜스포머 논문에서는 이 값이 512였지만, 요즘 LLM 은 훨씬 크다. (Llama 2 의 7B 모델만 해도 4,096 차원이다.) 모델 차원이 클수록 토큰의 미묘한 의미 차이를 더 풍부하게 표현할 수 있는 대신, 그만큼 계산량과 메모리도 함께 늘어난다.

위치 정보를 주입하는 방식도 세대에 따라 다르다. 원조 트랜스포머는 사인/코사인 함수로 만든 위치 벡터를 임베딩에 그대로 더했지만, 요즘 공개 LLM 들이 사실상 표준으로 쓰는 RoPE(Rotary Position Embedding, 회전 위치 임베딩)는 Query/Key 벡터를 회전시키는 방식으로 어텐션 계산 단계에서 상대 위치를 주입한다. (방식은 달라도 "트랜스포머에 순서 감각을 심어준다" 는 목적은 같다.)

정리하면, 텍스트 → 토큰 → 토큰 ID → 임베딩 벡터(+위치 정보) → 트랜스포머 입력 이라는 흐름이다. 우리가 청구서에서 보는 "토큰 수" 는 이 파이프라인의 두 번째 칸, 즉 텍스트가 몇 개의 토큰으로 쪼개졌는가의 개수인 셈이다.

여기까지 오면 토큰이 어떻게 만들어지고 어떤 모습으로 모델에 들어가는지가 정리된다. 그렇다면 이 토큰들이 모델 안에서 처리될 때, 입력과 출력의 비용은 왜 그렇게 차이가 나고, 같은 입력을 반복해서 보내는 비용은 어떻게 깎을 수 있는 걸까?

입력은 싸고 출력은 비싼 이유

토큰을 다뤄본 사람이라면 한 번쯤 의아했을 지점이 있다. 가격표를 보면 출력 토큰이 입력 토큰보다 몇 배씩 비싸다. Anthropic 의 경우 모든 모델에서 출력 단가가 입력 단가의 정확히 5배다. (Opus 는 입력 $5 / 출력 $25, Haiku 는 입력 $1 / 출력 $5 식이다.) 똑같은 토큰 하나인데 왜 들어올 때와 나갈 때의 값이 다른 걸까?

답은 모델이 토큰을 처리하는 방식이 입력과 출력에서 완전히 다르기 때문이다. LLM 추론은 두 단계로 나뉜다.

• prefill (입력 처리): 프롬프트로 들어온 모든 토큰을 한꺼번에 병렬로 처리한다. 1,000개 토큰이든 1만개 토큰이든, GPU 가 한 번에 쭉 훑어서 각 토큰의 K/V(Key/Value) 를 계산한다. 연산량은 많지만 병렬로 처리되니 토큰당 효율이 좋다.
• decode (출력 생성): 응답 토큰은 한 번에 하나씩 순차적으로 만든다. 토큰 하나를 생성하면 그걸 다시 입력에 붙이고, 또 그다음 토큰을 만든다. 이걸 응답이 끝날 때까지 반복한다.

이 비대칭으로 비용 차이가 발생한다. Databricks 의 추론 성능 분석에 따르면, prefill 은 연산이 병목인 compute-bound 단계이고 decode 는 메모리 대역폭이 병목인 memory-bound 단계다. decode 에서는 토큰 하나를 만들 때마다 모델 가중치 전체를 GPU 메모리에서 다시 읽어 와야 하는데, 정작 그 한 번에 토큰은 딱 하나만 나온다. GPU 의 막대한 연산 능력이 거의 놀고 있는 셈이다. (Databricks 의 표현을 빌리면, 돈을 내고 GPU 를 켜두지만 가용 연산을 못 쓰고 있는 상황이다.)

즉 입력 토큰은 병렬 prefill 로 한 번에 효율적으로 처리되는 반면, 출력 토큰은 한 토큰씩 비효율적으로 짜내야 한다. 출력이 비싸게 책정되는 데에는 수요나 마진 같은 상업적 요인도 섞여 있겠지만, 적어도 기술적으로는 decode 단계의 이런 비효율이 그 배경에 깔려 있다. 그래서 "출력을 짧게 받는다" 는 절약 원칙은 단순한 절약 팁이 아니라 가장 비싼 단계를 줄이는 일인 것이다.

그렇다면 이 비효율적인 decode 단계를 조금이라도 덜 비효율적으로 만들 방법은 없을까? 바로 그 지점에서 KV 캐시가 등장한다.

캐시가 단가를 깎는 원리

prompt caching 은 정적인 입력을 캐시에 한 번 저장해두고 다음 호출에서는 훨씬 싼 가격으로 다시 읽는 장치다. Anthropic 공식 문서 기준으로 캐시 읽기는 기본 입력 단가의 0.1배, 즉 정확히 10% 수준이다. 캐시 쓰기는 5분 TTL(Time To Live, 캐시 유효 시간) 기준 1.25배, 1시간 TTL 기준 2배가 붙는다. 첫 호출에서 살짝 더 내고, 두 번째 호출부터 90% 를 깎는 구조인 셈이다.

그런데 어떻게 단가의 90% 가 깎이는 걸까? 그리고 왜 "프리픽스가 정확히 같아야 한다" 는 조건이 그렇게 까다로운 걸까? 이 두 질문의 답은 트랜스포머의 안쪽 동작을 한 번 들여다보면 분명해진다.

KV 캐시

모델은 입력 토큰을 처리할 때 각 토큰에 대응되는 Query/Key/Value(Q/K/V) 벡터를 만든다. 셀프 어텐션은 Query 와 Key 의 내적으로 어텐션 점수를 계산하고, 그 점수로 Value 의 가중합을 만들어 출력을 낸다. 한 토큰이 다른 토큰들을 "얼마나 참고할지" 를 정하는 계산이라고 보면 된다.

앞서 본 decode 단계가 바로 이 지점에서 문제가 된다. 새 토큰을 하나 만들 때마다 그 앞의 모든 토큰에 대한 K/V 가 필요한데, 매번 처음부터 다시 계산하면 같은 K/V 를 끝없이 중복 계산하게 된다.

KV 캐시는 바로 이 중복을 없애려고 도입된 구조다. 한 번 계산한 K/V 를 저장해두고, 새 토큰을 생성할 때 앞 토큰들의 K/V 는 다시 계산하지 않고 캐시에서 읽어 재사용한다. 덕분에 한 시퀀스 안에서 토큰을 하나 더 생성하는 비용이, 매 스텝 전체를 다시 계산하는 O(n²) 에서 캐시를 읽기만 하는 O(n) 으로 떨어진다. (엄밀히는 스텝당 비용 기준의 이야기지만, 핵심은 "이미 계산한 건 다시 계산하지 않는다" 는 단순한 발상이다.) decode 가 memory-bound 인 이유도 여기에 있다. 매 스텝 이 KV 캐시를 메모리에서 다시 읽어 와야 하기 때문이다.

호출 사이의 재사용

KV 캐시가 원래 한 번의 응답 생성 안에서 디코딩을 가속하려고 만들어진 구조라면, prompt caching 은 이 메모리 구조를 하나의 호출 안이 아니라 호출과 호출 사이에서도 재활용하자 는 발상이다.

정적인 프리픽스(시스템 프롬프트, 도구 정의, 코드 스니펫처럼 매번 거의 같은 앞부분)의 K/V 를 5분 또는 1시간 TTL 동안 GPU 메모리에 들고 있다가, 다음 호출이 같은 프리픽스로 시작하면 그 부분의 K/V 계산을 통째로 건너뛰고 캐시에서 곧장 읽어 쓴다. 그래서 정확히 말하면, 입력 토큰의 단가가 마법처럼 깎이는 게 아니라 그 토큰을 계산하는 GPU 일 자체가 사라지는 것이다. 단가의 90% 인하는 그 절약된 연산을 가격에 반영한 결과다.

이 메커니즘을 이해하면 "프리픽스가 정확히 같아야 한다" 는 조건이 왜 그렇게 엄격한지도 자연스럽게 풀린다. 캐시 적중 여부는 프리픽스를 누적적으로 해싱한 값이 일치하는지로 판정되는데, 셀프 어텐션은 인과적(causal)이라 앞 토큰이 하나라도 바뀌면 그 뒤 토큰들의 K/V 가 전부 달라진다. 그래서 프롬프트 맨 앞에 타임스탬프 한 줄만 들어가 있어도, 매 호출마다 그 값이 달라지면서 프리픽스 해시가 어긋나 그 뒤 캐시 전체가 무효화된다.

Anthropic 의 캐시는 tools → system → messages 순서의 계층으로 읽힌다. 그래서 앞쪽의 도구 정의 하나만 바뀌어도 그 뒤 캐시 전체가 무효화된다. 결론은 단순하다. 정적인 것은 앞에, 매번 바뀌는 동적인 것은 뒤에 두어야 캐시가 산다.

캐시에는 잘 알려지지 않은 제약도 몇 가지 있다. 캐시 가능한 최소 토큰 수가 모델마다, 또 같은 패밀리 안에서도 버전마다 다르다. 그보다 짧은 프롬프트는 캐시 설정을 걸어도 조용히 캐시되지 않는다. (이 최소 토큰 수와 프로바이더별 캐시 정책 차이는 비용 설계와 직결되는 부분이라, 토큰 절약법 글에서 가격표와 함께 자세히 다뤘다.)

컨텍스트 윈도우가 토큰 한도를 만드는 이유

마지막으로 토큰을 이야기할 때 빠질 수 없는 개념이 컨텍스트 윈도우(context window)다. 모델이 한 번에 받아들일 수 있는 토큰 수의 한도를 가리키는 말인데, 왜 이런 한도가 존재하는지를 알면 "컨텍스트가 길어질수록 비싸진다" 는 흔한 경고의 정체도 분명해진다.

핵심은 셀프 어텐션의 연산 구조에 있다. 어텐션은 모든 토큰이 다른 모든 토큰을 한 번씩 참고하는 계산이다. 토큰이 n개라면 토큰 쌍의 수는 n × n, 즉 셀프 어텐션의 연산량과 메모리가 시퀀스 길이 n의 제곱에 비례해 늘어난다. 토큰이 2배가 되면 어텐션 비용은 4배가 되는 식이다. (모델 전체가 O(n²)인 건 아니고, 어텐션 단계가 그렇다는 점은 짚어둘 필요가 있다.)

이 제곱 증가가 얼마나 가파른지 HuggingFace 의 추정 수치가 잘 보여준다. 최적화 없는 표준 어텐션 기준으로, 어텐션 점수 행렬을 저장하는 데만 입력이 1,000 토큰일 때는 약 50MB 면 충분하지만, 16,000 토큰에서는 약 19GB, 10만 토큰에서는 거의 1TB 가 필요하다.

여기에 앞서 본 KV 캐시도 토큰 수에 비례해 메모리를 차지한다. 컨텍스트가 길어질수록 들고 있어야 할 K/V 가 선형으로 쌓이는 것이다. 결국 컨텍스트 윈도우 한도는 "이보다 길어지면 메모리와 연산이 감당이 안 된다" 는 물리적 한계를 모델이 정해둔 선인 셈이다.

그래서 긴 대화를 그대로 끌고 가는 게 단순히 입력 토큰 수만 늘리는 문제가 아니라는 점이 중요하다. 어텐션 비용이 제곱으로 붙고, 토큰이 한도에 가까워질수록 모델이 정보를 다루는 정확도까지 떨어진다. (이 정확도 저하 현상은 절약법 글에서 다룬 context rot 과 직결되는데, 컨텍스트를 가볍게 유지하는 일이 비용과 정답률 양쪽에 이로운 이유가 바로 여기에 있다.)

마무리

여기까지 정리하고 보면, 토큰의 동작 원리는 몇 개의 단순한 사실로 압축된다. 토큰은 BPE 가 자주 쓰이는 패턴을 묶어 만든 어휘의 단위이고, 토큰 ID 를 거쳐 임베딩 벡터로 바뀌어 모델에 들어간다. 입력은 병렬 prefill 로 한 번에 처리되지만 출력은 한 토큰씩 짜내야 해서 더 비싸고, 그 비효율을 덜어주는 게 K/V 를 재사용하는 KV 캐시다. 캐시가 단가를 깎는 건 마법이 아니라 트랜스포머가 이미 계산해 둔 K/V 를 다시 계산하지 않기 때문이며, 프리픽스가 정확히 같아야 한다는 까다로운 조건도 이 구조에서 곧장 따라 나온다. 그리고 컨텍스트가 길어질수록 비싸지는 건 어텐션 비용이 토큰 수의 제곱으로 붙기 때문이다.

이 토대를 알고 나면 비용 이야기가 훨씬 또렷하게 보인다. 출력이 왜 비싼지, 캐시를 깨지 않으려면 프롬프트를 어떻게 배치해야 하는지, 컨텍스트를 왜 가볍게 유지해야 하는지, 같은 답이면 왜 더 싼 모델로 옮겨야 하는지 같은 절약 전략들이 전부 이 원리 위에 서 있기 때문이다. 동작 원리가 궁금해서 여기까지 읽은 독자라면, 이어서 토큰 절약법 에서 그 원리들이 실제 비용을 어떻게 깎는지 확인해보시길 권하고 싶다.

한 프로젝트에 CLAUDE.md, AGENTS.md, SKILL.md, .cursor/rules가 함께 쌓여 있는데, 각각 언제 읽히고 무엇을 적어야 하는지 헷갈리는 개발자를 위한 글이다. 끝까지 읽으면 파일별 차이와 에이전트가 그 파일을 읽어 들이는 방식, 그리고 ETH Zurich 연구를 근거로 한 "추론할 수 없는 정보만 적는다"는 판단 기준을 얻을 수 있다.

필자는 프론트엔드 개발자로 일하면서 일상적으로 Claude를 활용한다. 그러다 보니 어느 순간부터 프로젝트 루트에 CLAUDE.md가 생기고, 옆에 누가 만들어둔 AGENTS.md가 있고, .cursorrules도 한쪽에 남아있고, 어디선가 본 글을 따라 .claude/skills/ 폴더를 만들기도 했다. (정신을 차려보니 비슷한 내용을 적어둔 파일이 다섯 개쯤 되어 있었다.)

지속 메모리가 없는 에이전트

AI 코딩 에이전트에는 지속 메모리가 없다는 근본적인 한계가 있다. 모든 세션은 빈 상태로 시작되고, 어제 합의한 컨벤션이나 한 시간 전에 알려준 폴더 구조 같은 것을 다음 대화에서는 기억하지 못한다. Context file은 이 문제를 해결하기 위한 가장 단순한 장치다. 세션이 시작될 때마다 자동으로 읽히는 파일을 프로젝트에 두면, 매번 같은 설명을 반복할 필요가 없다.

문제는 같은 발상에서 출발한 파일이 도구마다 따로 만들어졌다는 점이다. Claude Code는 CLAUDE.md를, Cursor는 .cursorrules(현재는 depreacted가 되어 .cursor/rules 사용을 권장하고있다)를, GitHub Copilot은 .github/copilot-instructions.md를, OpenAI Codex는 AGENTS.md를 읽는다. 한 팀이 여러 도구를 쓰면 같은 내용을 네 군데에 복사해 두어야 하는 상황이 벌어지는 것이다.

CLAUDE.md

CLAUDE.md는 Claude Code가 세션 시작 시 자동으로 읽어 들이는 파일이다. Anthropic 공식 문서(code.claude.com/docs/en/memory)에 따르면, Claude Code는 다음 세 계층에서 CLAUDE.md를 찾는다.

• 사용자 메모리 (~/.claude/CLAUDE.md): 머신의 모든 프로젝트에 적용되는 전역 기본값
• 프로젝트 메모리 (프로젝트 루트의 CLAUDE.md): 깃에 커밋되어 팀 전체가 공유
• 로컬 메모리 (서브디렉토리의 CLAUDE.md): 해당 디렉토리에서 작업할 때만 추가로 로딩

세 계층이 모두 존재하면 Claude는 모두 읽어 연결(concatenate) 한다. 우선순위에 따라 하나만 선택되는 게 아니라, CSS의 cascade처럼 더 구체적인 것이 추가로 얹히는 구조다. (오버라이드가 아니라 병합이다.) 따라서 같은 주제의 규칙을 여러 계층에 흩어두면 충돌이 날 수 있다.(Anthropic 공식 문서는 충돌 시 동작이 보장되지 않는다고 명시하고있다.)

여기서 한 가지 자주 놓치는 부분이 있다. 현재 작업 디렉토리에서 레포 루트까지 거슬러 올라가며 만나는 모든 CLAUDE.md를 읽는다는 점이다. 그래서 모노레포에서 packages/ui/에 들어가서 작업하면 루트의 CLAUDE.md와 packages/ui/CLAUDE.md가 둘 다 로딩된다. (이건 강력하지만 동시에 컨텍스트가 부지불식간에 부풀 수 있다는 뜻이기도 하다.)

AGENTS.md

AGENTS.md는 위에서 말한 도구별 파일 난립을 풀기 위해 만들어진 표준이다. 2025년 12월, OpenAI는 이 표준을 Linux Foundation 산하 Agentic AI Foundation(AAIF) 에 기증했다. Linux Foundation의 발표에 따르면 AAIF는 Anthropic·Block·OpenAI가 공동 창립했고, 창립 프로젝트는 Anthropic의 MCP(에이전트를 외부 시스템에 연결하는 프로토콜), Block의 goose, OpenAI의 AGENTS.md 셋이다. 공식 사이트(agents.md)에서 6만 개 이상의 오픈소스 저장소가 이 파일을 채택하고 있다고 명시하고 있다.

지원하는 도구 목록을 보면 더 분명해진다. OpenAI Codex, Google Jules, VS Code, GitHub Copilot, Cursor, JetBrains Junie, Aider, Devin, Zed, Factory, Warp, goose, opencode, Amp, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, Ona, Windsurf, Augment Code 까지 수많은 도구들을 지원한다. GitHub Copilot은 2025년 8월부터 AGENTS.md를 네이티브로 지원하기 시작했다. 한 가지 흥미로운 점은 Claude Code의 네이티브 AGENTS.md 지원은 아직 active feature request 상태라는 것이다. Claude Code는 여전히 CLAUDE.md를 1차 파일로 본다.

표준이라고는 하지만 정말 채택되고 있는지 의심스러울 수도 있다. 가장 강력한 증거는 dogfooding(자신이 만든 표준을 자신이 직접 쓴다는 의미)이다.

• Vercel/Next.js의 canary 브랜치 루트에는 AGENTS.md가 있다. 사실은 CLAUDE.md를 가리키는 심볼릭 링크인데, 그 안에 모노레포 구조, pnpm --filter=next dev로 1-2초 단위 반복, Turbopack/Webpack 양쪽 테스트 가이드, pr-status 스크립트, 환경 변수·시크릿 처리 규칙까지 들어 있다. create-next-app이 신규 프로젝트에 AGENTS.md와 CLAUDE.md를 함께 생성하도록 바뀐 것도 같은 흐름이다.
• OpenAI/codex 레포 자체가 자신의 AGENTS.md를 운영한다.

전략적으로는 이렇게 운용하는 게 정석으로 굳어지고 있다. AGENTS.md를 단일 정보 출처(single source of truth)로 두고, CLAUDE.md는 최소화해서 AGENTS.md를 참조하는 한 줄과 Claude Code 전용 지시만 적어두는 방식이다. 이렇게 하면 중복이 사라지고, Claude Code는 두 파일을 모두 읽기 때문에 잃는 것이 없다.

SKILL.md

SKILL.md는 위 두 파일과는 결이 다르다. CLAUDE.md와 AGENTS.md가 항상 컨텍스트에 존재하는 영속적 지시라면, 스킬(Skill)은 필요할 때만 호출되는 온디맨드 능력이다.

스킬은 폴더 단위로 구성된다. 폴더 안에 SKILL.md 한 개와 그 스킬이 실행할 스크립트, 추가 마크다운 문서들이 들어있다. Claude는 현재 태스크가 스킬의 description과 매칭될 때만 그 폴더를 로딩한다. 이걸 progressive disclosure(점진적 노출) 라고 부르는데, 1995년 UX 분야의 Jakob Nielsen이 정립한 개념으로 고급·드물게 쓰이는 기능을 보조 화면으로 미뤄두고 사용자가 한 번에 하나의 작업에만 집중하게 해서 인지 부하와 에러를 줄이는 기법이다. Claude Skills 맥락에서는 "필요할 때만 그 스킬의 본문을 컨텍스트로 가져오는" 메커니즘을 가리킨다. 결과적으로 컨텍스트 윈도우 비용을 극적으로 아낄 수 있다.

SKILL.md의 frontmatter에는 몇 가지 고유한 필드가 있다.

• description: 어떤 상황에서 이 스킬이 필요한지 설명. 모델이 호출 여부를 판단하는 트리거가 된다
• allowed-tools: 스킬 안에서 사용 가능한 도구를 제한 (예: "Read, Glob, Grep, Bash(python:*)")
• disable-model-invocation: true: 모델은 호출 불가, 사용자만 슬래시 명령으로 트리거 가능하다. 부작용 있는 작업(배포·커밋 등)에 사용한다
• user-invocable: false: 사용자에게는 슬래시 메뉴에서 안 보이고 Claude만 자율 호출하여 배경 지식용에 사용한다.

Claude Skills는 2025년 10월 16일 Claude.ai, Claude Code, API, Agent SDK에 동시 출시되었다. 그리고 2025년 12월 18일, Anthropic은 Skills 사양 자체를 오픈 표준(agentskills.io)으로 발표했다. Simon Willison은 "Skills are awesome, maybe a bigger deal than MCP"라는 평가를 내놓기도 했는데, 그 이유는 형식이 MCP보다 극적으로 단순하면서 컨텍스트 윈도우 비용 문제를 progressive disclosure로 해결한다는 점에 있었다.

여기서 Skills와 비교된 MCP(Model Context Protocol)는 에이전트가 Slack, GitHub, DB 같은 외부 시스템을 호출할 수 있게 연결하는 표준 프로토콜이다. Context file이 에이전트에게 무엇을 알려줄지의 문제라면, MCP는 무엇을 할 수 있게 해줄지의 문제다. MCP가 function calling과 무엇이 다른지는 MCP와 function calling에 따로 정리해 두었다.

에이전트가 관련 코드를 찾는 비용을 줄이는 도구들(Repomix, Aider, CodeGraph, Serena)은 코드를 얼마나 깊이 이해하느냐에 따라 줄이는 비용이 다르다. 그 비교는 Code intelligence의 네 계층에 따로 정리해 두었다.

다른 도구들의 파일

Cursor의 .cursorrules는 0.43 버전부터 deprecated 되었다. 현재 공식 권장은 .cursor/rules/ 디렉토리 안에 여러 .mdc 파일을 두는 것이다. 각 .mdc 파일은 YAML frontmatter를 가진다.

• description: 에이전트가 이 룰의 관련성을 판단할 때 참고
• globs: 매칭되는 파일이 대화에 포함될 때 자동 첨부(auto-attach)
• alwaysApply: true면 모든 대화에 무조건 포함 (이 경우 globs는 무시)

GitHub Copilot도 비슷한 방향으로 진화했다. 저장소 전역 지시는 .github/copilot-instructions.md에 두고, 경로별 스코프가 필요한 지시는 .github/instructions/*.instructions.md 파일을 만들어 frontmatter의 applyTo: 키로 glob을 지정한다. (Copilot code review는 2025년 9월부터 path-scoped instructions를 공식 지원한다.)

Cursor·Copilot 외의 도구들도 모두 비슷한 패턴으로 수렴하고 있다. 표로 정리하면 이렇다.

특히 Aider의 CONVENTIONS.md가 흥미롭다. 공식 문서는 매 요청마다 이 파일을 통째로 컨텍스트에 포함하기 때문에 "200줄 이내로 유지하라" 고 명시한다. (Aider는 이 한계를 일찍 인지하고 사용자에게 명시적으로 알려주는 셈이다.)

MEMORY.md

위 파일들과는 별개로, 점점 자주 보이는 패턴이 하나 더 있다. MEMORY.md다. 공식 표준은 아니지만 커뮤니티에서 자생적으로 생겨난 컨벤션인데, 시간이 흐르는 동안의 의사결정과 실수를 기록하는 용도다.

## 2026-04-10
Pages Router에서 App Router로 이전. 신규 라우트는 App Router 컨벤션 사용.
 
## 2026-04-22
Prisma 쿼리 결과에 optional chaining 쓰지 말 것 — null은 if-check로 명시적 처리.
(이전에 옵셔널 체이닝으로 null을 흘려보내 프로덕션 이슈 발생.)

CLAUDE.md나 AGENTS.md가 현재 시점의 규칙을 적는 곳이라면, MEMORY.md는 그 규칙이 왜 만들어졌는지의 역사를 적는 곳이다. (둘은 보완 관계지 대체 관계가 아니다.)

에이전트는 이 파일들을 어떻게 읽는가

지금까지 어떤 파일이 있는지를 정리했다. 그런데 의외로 자주 빠지는 질문이 하나 있다. 이 파일들을 에이전트는 정확히 어디로, 어떻게 읽어들이는 걸까? 사실 이 메커니즘을 알면 뒤에 이어질 ETH Zurich 결과(context file이 잘 안 따라진다는 결과)가 왜 나왔는지가 좀 더 깔끔하게 이해된다.

가장 먼저 짚어둘 사실 하나. CLAUDE.md는 system prompt가 아니라 user message로 주입된다. Anthropic 공식 문서가 아래와 같이 명시한다

CLAUDE.md 콘텐츠는 시스템 프롬프트의 일부가 아니라 시스템 프롬프트 뒤에 사용자 메시지로 전달된다. Claude는 이를 읽고 따르려 하지만, 엄격히 준수한다는 보장은 없다.

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance.

즉 강제 규칙이 아니라 "참고용 컨텍스트"인 셈이다. 정확히 어떤 동작을 강제하고 싶다면 PreToolUse 훅 같은 별도 장치를 써야 한다고 공식 가이드도 권장한다.

로드 순서는 broad → specific 으로 쌓인다. 구체적으로는 managed policy(조직 차원의 설정) → 사용자 글로벌(~/.claude/CLAUDE.md) → 프로젝트(./CLAUDE.md) → 로컬(./CLAUDE.local.md) 순이다. 같은 디렉토리에서는 CLAUDE.md 다음 CLAUDE.local.md 순. 가장 가까운 곳의 지시가 가장 나중에 읽힌다는 점을 활용하면 (LLM의 recency bias 덕에) 더 구체적인 규칙이 더 강하게 작용하는 효과를 노릴 수 있다.

여기서 흥미로운 게 @import 문법이다. CLAUDE.md 본문 어디에 @path/to/file을 적으면 그 파일이 자리에 그대로 펼쳐져서 같이 로드된다. 최대 재귀 깊이는 4 hops까지 허용되고, 상대경로는 import문이 적힌 파일 기준으로 풀린다. 그래서 공식 권장이 @AGENTS.md로 브리지하는 방식이다. CLAUDE.md는 거의 비워두고 @AGENTS.md 한 줄만 쓰면 Claude Code도 자연스럽게 AGENTS.md를 읽는다. (CLAUDE.md가 아직 AGENTS.md를 네이티브 지원하지 않는 현 상황에서 가장 깔끔한 우회다.)

토큰 측면도 짚고 가자. CLAUDE.md 자체에는 명시적 토큰 한도가 없어서 있으면 전부 로드된다. 다만 공식 권고는 파일당 200줄 이내다. 200줄을 넘기면 "consume more context and may reduce adherence"라고 명시되어 있다. 흥미롭게도 Claude 4.x에서는 tool use를 활성화하는 것만으로 special system prompt가 자동 +346토큰(tool_choice: auto 기준) 추가된다. 컨텍스트는 알게 모르게 새고 있는 셈이다.

Cursor는 또 다른 방식이다. .cursor/rules/*.mdc의 룰은 네 가지 타입으로 작동한다.

• Always Apply: 모든 채팅에 무조건 포함. globs/description 무시
• Apply Intelligently(Agent Requested): 에이전트가 description을 읽고 관련성을 판단해 끌어다 씀
• Apply to Specific Files(Auto Attached): glob 패턴 매칭 파일이 컨텍스트에 들어왔을 때 활성화
• Apply Manually: @rule-name으로 사용자가 명시 호출

다른 도구들은 또 다르다. OpenAI Codex는 git 레포 루트에서 cwd 방향으로 walk하며 모든 AGENTS.md를 수집해 사용자 프롬프트 직전에 주입하고, GitHub Copilot은 .github/copilot-instructions.md를 "edit context와 explicit references 다음, loosely related open files보다는 앞"이라는 컨텍스트 윈도우의 중간 우선순위로 끼워 넣는다. 같은 AGENTS.md 파일이라도 로드 시점, 우선순위, 머지 규칙이 도구마다 다르기 때문에 세 도구가 정확히 같은 방식으로 그 파일을 본다는 보장은 없다.

그런데 여기서 한 가지 근본적인 질문이 남는다. 왜 모델은 컨텍스트에 있는 지시를 일부만 따르는 걸까? 단순히 "지시가 길어서"라는 설명은 충분하지 않다. 이 현상의 밑에는 LLM의 구조적 한계가 있다.

환각과 context 망각

AI 에이전트가 대화 맥락을 혼동하거나 앞에서 분명히 말한 내용을 뒤에서 잊어버리는 경험을 해본 적이 있다면, 그게 바로 환각(Hallucination) 의 한 형태다. 일반적으로 환각이라고 하면 "없는 사실을 지어내는 것"을 먼저 떠올리지만, 학술적으로는 세 가지로 구분한다. Yue Zhang 외 연구팀의 2023년 설문("Siren's Song in the AI Ocean")은 이를 입력 충돌형(사용자가 명시한 내용과 다르게 생성), 맥락 충돌형(이전에 자신이 생성한 내용과 모순), 사실 충돌형(세계 지식과 불일치)으로 나눈다. Context file 지시를 무시하는 현상은 세 번째가 아니라 첫 번째 유형이다. 모델이 입력을 처리하면서 그 안의 정보 일부를 "없던 것처럼" 다루는 것이다.

더 근본적인 문제는 이 환각이 원천적으로 제거 불가능하다는 점이다. 싱가포르 국립대학교 연구팀은 학습 이론을 이용해 이를 수학적으로 증명했다. 어떤 LLM도 모든 계산 가능한 함수를 학습할 수 없고, 따라서 일반 문제 해결기로 쓰이는 한 반드시 어느 지점에서 환각이 발생한다는 것이다.

위치 효과도 중요하다. Stanford 연구팀은 관련 정보가 컨텍스트 윈도우의 앞이나 끝에 위치할 때 모델이 가장 잘 참조하고, 중간에 묻혔을 때 성능이 크게 떨어진다는 것을 실험으로 보였다. 이게 context file에 직접 연결된다. CLAUDE.md가 로드 순서상 중간 어딘가에 끼어 들어가고, 그 뒤로 대화가 길어질수록 파일의 지시는 점점 컨텍스트의 "중간"으로 밀려난다. 앞서 언급한 recency bias(최근 것을 더 잘 따르는 경향)의 반대편, 즉 primacy-recency 효과의 중간 구간이 가장 취약하다는 사실과도 맞닿아 있다.

결국 이 현상들을 한데 놓으면 하나의 그림이 된다. Context file은 LLM의 첫 user 턴 이전에 시스템 외부에서 추가로 끼어 들어가는 텍스트일 뿐이다. 모델의 결정을 강제하는 메커니즘이 아니라 그저 컨텍스트 윈도우에 떨어지는 또 하나의 토큰 덩어리인 것이다. 길수록, 그리고 대화가 길어질수록 그 지시는 점점 "중간"으로 밀려나며 참조율이 떨어진다. ETH Zurich 결과는 이 구조적 한계를 정량적으로 확인한 셈이다.

ETH Zurich의 연구

많은 사람들은 "그럼 이 파일들에 최대한 많이 적어두면 좋겠네?" 하는 생각을 했을 것이다. 그런데 이 직관을 정면으로 반박하는 연구가 최근에 나왔다. 바로 앞에서 계속 이야기한 ETH Zurich 연구이다.

ETH Zurich 연구팀이 2026년 2월에 발표한 논문("Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?")이다. 138개의 실제 Python 소프트웨어 엔지니어링 태스크 벤치마크(AGENTBENCH)와 SWE-bench Lite에서 Claude Code(Sonnet-4.5), Codex(GPT-5.2 / GPT-5.1 mini), Qwen Code 네 가지 에이전트로 측정했는데, 결과가 의외였다.

• LLM이 자동 생성한 context file은 SWE-bench Lite에서 0.5%, AGENTBENCH에서 2% 가량 태스크 성공률을 오히려 낮췄다
• 사람이 직접 작성한 파일조차 평균 4% 정도의 마이너 개선에 그쳤다
• Context file을 추가했을 때 추론 비용이 인스턴스당 20% 이상 증가했다
• 더 강력한 모델(GPT-5.2)에서는 context file의 효과가 더 미미했다 (강력한 모델일수록 파라메트릭 지식이 충분해서 추가 컨텍스트가 노이즈로 작용)

다만 한 가지 예외가 있었다. 비표준 도구를 명시했을 때다. 예를 들어 Python 패키지 매니저인 uv를 컨텍스트에 명시하니, 에이전트가 uv를 사용하는 빈도가 인스턴스당 0.01회 => 1.6회로 약 160배 증가했다

앞서 다룬 Aider의 "200줄 권고", "매번 컨텍스트에 들어가니까 짧게 유지하라"라는 실용성을 안내한 거고, ETH Zurich 연구는 "긴 context file이 통계적으로 성능을 떨어뜨린다"는 걸 정량적으로 보여줬다. 필자가 생각하는 이 연구의 실천적 함의는 아래와같다.

• 자동 생성된 거대한 context file은 도움보다 해가 될 수 있다. 300줄짜리 CLAUDE.md에 코딩 표준·아키텍처·워크플로우를 다 욱여넣으면, 에이전트는 일부만 따르고 나머지를 무시한다. 그 불일관성은 차라리 컨텍스트가 없는 것보다 나쁜 결과로 이어진다.
• 반드시 적어야 하는 것은 "추론할 수 없는 정보" 다. 비표준 도구, 프로젝트 고유의 컨벤션, 과거 실패 사례 같은 것들이 여기에 속한다. 일반적인 코딩 베스트 프랙티스는 모델이 이미 안다.
• AGENTS.md를 단일 출처로, CLAUDE.md는 도구 전용 짧은 지시만, 세한 워크플로우는 Skill로 분리한다.

그래서

Context file은 도구마다 이름도, 놓이는 위치도, 읽히는 시점도 다르다. 이 글에서 본 것만 해도 CLAUDE.md, AGENTS.md, SKILL.md, Cursor rules, copilot-instructions.md, MEMORY.md가 있고, 어떤 도구가 어떤 파일을 지원하는지도 계속 바뀐다. 파일 목록을 외워 두는 것만으로는 금세 낡는다.

그래서 필자가 이 글에서 하려 했던 것은 특정 파일 형식을 추천하는 것이 아니라, 파일이 에이전트에게 어떻게 읽히는지 보는 눈을 만드는 것이었다. CLAUDE.md가 왜 user message로 주입되는지, 같은 AGENTS.md를 도구마다 왜 다르게 읽는지, 지시가 왜 컨텍스트 중간에서 약해지는지를 알고 나면, 새로운 context file 형식이 등장했을 때 "이건 언제 로드되고 얼마나 강하게 작용하는구나"가 빠르게 읽힌다.

결국 남는 건 ETH Zurich 연구가 건넨 한 가지 직관이다. 모델은 이미 많은 것을 안다. context file에 온갖 것을 욱여넣는다고 에이전트가 더 잘 따르지 않는다. 모델이 모를 가능성이 높은 것, 즉 프로젝트 고유의 컨벤션·비표준 도구·과거의 실수만 남기고 나머지는 걷어내는 것이 오히려 낫다. Context file을 길게 쓰는 것과 잘 쓰는 것은 다른 문제다.

이 글을 읽는 독자들도 지금 당장 CLAUDE.md를 수백 줄로 늘리기보다는, 지금 쓰고 있는 도구가 그 파일을 언제, 어느 자리에, 얼마나 강하게 읽어 들이는지 한 번쯤 파고들어 보기를 권한다. 그게 파일 형식이 어떻게 바뀌든 흔들리지 않는 기반이 된다고 생각한다.

큰 코드베이스에서 에이전트가 grep과 파일 읽기를 되풀이하며 토큰을 쓰는 것을 보고, Repomix나 CodeGraph, Serena 같은 도구 중 무엇을 붙여야 할지 고민하는 개발자를 위한 글이다. 이 도구들은 코드를 얼마나 깊이 이해하는지에 따라 context packing, tree-sitter repo map, 지식 그래프, LSP의 네 계층으로 갈리고, 계층마다 탐색 비용을 줄이는 지점이 다르다. 지식 그래프는 제작사의 벤치마크를, 나머지 세 계층은 이 블로그 리포에서 잰 결과를 싣는다.

codegraph가 GitHub Trending에 오른 걸 보고 따라 설치해 본 뒤로, 필자는 새 도구를 볼 때마다 그것이 어떤 원리로 토큰을 아끼는지가 궁금했다. 이 글에 나오는 도구 상당수도 필자가 보통 weekly 기준으로 TypeScript와 Python을 골라 훑는 GitHub Trending에서 처음 알게 됐다.

Code intelligence 도구

에이전트는 코드를 고치기 전에 관련 코드가 어디 있는지부터 찾는다. grep으로 찾고, 파일을 읽고, 걸러내고, 다시 grep 하는 루프다. 뒤에서 볼 CodeGraph 벤치마크에서 도구 없이 답한 쪽은 질문 하나에 tool call을 최대 43번 썼다. Code intelligence 도구는 이 탐색 비용을 줄이려는 시도들이다.

다만 비용이라는 말이 가리키는 것이 하나가 아니다. 모델이 처리한 토큰, tool call 횟수, 그리고 작업이 끝난 뒤에도 context window에 남아 있는 토큰은 따로 움직인다. 이 글은 계층마다 이 셋 중 무엇을 줄이는지를 본다.

필자는 도구가 코드를 얼마나 깊이 이해하는지를 기준으로 이 시도들을 아래 네 개의 계층(tier)으로 나눠 본다. 업계에 정해진 분류는 없고, 이 구분은 필자가 정리한 것이다. 이 글의 실측값은 전부 이 리포의 커밋 36e5cfa 에서 2026-10-08 에 얻었고, 토큰은 tiktoken의 o200k_base 로 셌다. Claude의 tokenizer와는 값이 다르므로 절대값보다 비교에 쓴다.

Context packing

가장 단순한 해법은 "전부 다 한 context window에 넣어버리자"는 발상이다. 그래프도 안 만들고, 인덱싱도 안 한다. 그냥 리포 전체를 텍스트 덩어리로 직렬화해서 모델에게 통째로 던진다.

대표 도구가 Repomix다. 기본 출력 형식이 XML이고, README는 Anthropic의 XML 태그 문서를 함께 링크한다. CLI, 웹, 브라우저 확장, MCP 서버를 다 갖췄다.

GitIngest는 설치 없이 쓸 수 있다는 점이 강점이다. GitHub URL의 github.com을 gitingest.com으로 바꾸면 리포 전체가 한 텍스트 페이지가 된다. Rust CLI인 code2prompt(Mufeed VH 제작)는 템플릿으로 출력 형식을 바꿀 수 있다.

rtk(rtk-ai/rtk)는 방향이 조금 다르다. 위 도구들이 리포 전체를 한 번에 패킹한다면, rtk는 에이전트가 실행한 CLI 명령의 출력을 압축한다. Rust로 만든 단일 바이너리이고, Claude Code, Cursor, Copilot, Gemini CLI, Codex 등 여러 에이전트의 hook에 등록되어 에이전트가 git status를 호출하면 rtk git status로 바꿔 실행한다. 100개 이상의 명령에 filtering, grouping, truncation, deduplication을 적용한다. rtk의 hook은 Bash tool call만 대상으로 잡는다. Claude Code의 Read, Grep, Glob 은 그대로 지나간다.

줄어드는 양은 조심해서 읽어야 한다. rtk README는 Bash 출력을 최대 90% 줄인다고 쓰면서, 그것이 청구액을 90% 줄인다는 뜻은 아니라고 바로 덧붙인다. 명령 출력은 모델 입장에서 입력 토큰의 일부이고, 입력 토큰은 청구액의 일부라서 단계마다 희석된다. 공식 사이트가 내세우는 숫자는 rtk가 바꿔 실행한 명령 기준 평균 56%다. 위 도구들이 들어가는 텍스트를 줄인다면, rtk는 tool call 결과로 돌아오는 텍스트를 줄인다.

이 계층의 한계는 대형 리포가 토큰 한도에 걸린다는 것이다. 이 블로그의 src/ 파일 109개만 패킹해도 94,596 tokens다. 이 정도는 창에 들어가지만, 파일이 수천 개인 리포라면 한도에 바로 닿는다. Repomix는 이 문제에 --compress 로 답한다. README에 따르면 Tree-sitter로 함수와 클래스 시그니처를 남기고 구현 본문을 버린다.

# repomix 1.18.1, 이 리포 커밋 36e5cfa, 2026-10-08
npx -y repomix@1.18.1 src -o out.xml              # Total Tokens: 94,596 tokens
npx -y repomix@1.18.1 src --compress -o out.xml   # Total Tokens: 30,320 tokens

68%가 줄었다. 주석은 그대로 남기 때문에, JSDoc이 긴 visit-counter.ts 는 1,642에서 약 1,220 tokens로 26%만 줄었다. 압축본에는 import 문과 시그니처가 남지만 함수 본문 안의 호출은 사라진다. 어느 파일이 무엇을 가져오는지는 텍스트로 보이지만, 누가 누구를 부르는지는 물을 수 없다. 그래서 이 계층과 다음 계층의 경계는 구문을 보느냐보다 관계를 물을 수 있느냐에 있다.

tree-sitter repo map

다음 계층은 tree-sitter를 활용해 코드의 구조를 분석하되, 별도의 인덱스 서버를 띄우진 않는 방식이다.

이 계층의 도구들이 쓰는 tree-sitter가 만드는 것은 소스 코드의 구조를 트리로 표현한 CST(Concrete Syntax Tree) 다. tree-sitter 공식 문서도 concrete syntax tree를 만든다고 쓴다. 괄호와 구두점까지 노드로 남긴 트리이고, 아래 도구들이 다루는 것도 이 트리다.

tree-sitter는 오픈소스 파서 생성기이자 증분(incremental) 파싱 라이브러리다. GitHub의 code navigation이 tree-sitter를 쓴다. 편집된 부분만 다시 파싱하므로, 에디터에서 한 줄을 고쳐도 파일 전체를 다시 파싱하지 않고 바뀐 트리만 고친다. 이 이점은 편집이 계속 일어나는 에디터의 것이다. 아래의 Aider는 파일 수정 시각으로 캐시를 두어 바뀌지 않은 파일을 다시 파싱하지 않는다.

터미널에서 쓰는 AI 페어 프로그래밍 도구 Aider가 이 접근의 대표 사례다. Aider는 tree-sitter로 파일마다 함수, 클래스, 메서드의 정의와 참조를 뽑는다. 그리고 파일을 노드로 하는 그래프를 만든다. A 파일이 B 파일에 정의된 식별자를 참조하면 A에서 B로 엣지가 생긴다.

이 그래프에서 중요한 파일을 고를 때 Aider는 PageRank를 쓴다. PageRank는 링크를 많이, 그리고 무겁게 받는 노드일수록 높은 점수를 주는 알고리즘이다. Aider가 쓰는 것은 그 변형인 personalized PageRank로, 지정한 노드 쪽으로 점수를 기울인다. 그렇게 순위가 높은 파일부터 정의와 시그니처를 토큰 예산만큼 넣는다.

무엇이 예산 안에 들어갈지는 지금의 대화에 따라 바뀐다. Aider의 repomap.py에서 엣지 가중치는 참조 횟수의 제곱근에 배수를 곱한 값이다. 대화에 나온 식별자는 10배, 8자 이상인 camelCase, snake_case, kebab-case 식별자도 10배다. _ 로 시작하는 식별자와 5개를 넘는 파일에서 정의된 식별자는 각각 0.1배이고, 지금 채팅에 올린 파일에서 나가는 엣지는 50배다. 채팅에 올린 파일, 대화에서 언급한 파일, 그리고 경로나 파일 이름이 대화 속 식별자와 겹치는 파일은 PageRank의 personalization 점수도 받는다.

예산도 고정값이 아니다. Aider 문서는 --map-tokens 기본값을 1k로 적지만, 코드는 모델 입력 한도의 1/8을 1,024에서 4,096 사이로 자른다. 그리고 채팅에 파일이 없으면 --map-multiplier-no-files(기본 2)배까지 키운다. 이 리포의 src/ 로 확인했다. 실행한 0.86.1과 위에 링크한 커밋은 랭킹 코드가 같다. 출력된 map은 Aider가 붙이는 안내 문구 세 줄을 포함해 o200k_base로 셌다.

# aider-chat 0.86.1, 리포 루트에서 시작한다, 2026-10-08
mkdir /tmp/aidermap && cp -R src /tmp/aidermap/ && cd /tmp/aidermap && git init -q && git add -A && git commit -qm init
# 키는 더미 값이다. --show-repo-map 은 map 만 출력하고 LLM 을 부르지 않는다
export OPENAI_API_KEY=dummy
aider_map() { uvx --python 3.12 --from aider-chat==0.86.1 aider --no-check-update --analytics-disable --no-gitignore --model gpt-4o "$@"; }
aider_map --show-repo-map                                              # Repo-map: using 4096 tokens
aider_map --map-tokens 1024 --show-repo-map                            # Repo-map: using 1024 tokens
aider_map --map-tokens 1024 --show-repo-map src/lib/filter-posts.ts    # 이 파일을 채팅에 올린 상태

gpt-4o의 입력 한도는 128k라서 1/8이 4,096으로 잘렸고, 채팅이 비어 있으니 그 두 배 안에서 map이 나왔다. 파일 하나를 채팅에 올리자 map은 예산 안으로 줄었고, 앞의 27개 중 10개만 남은 자리에 PostList.tsx 와 SearchModal.tsx 가 새로 들어왔다. repo map은 리포의 고정된 요약이 아니라 그 순간의 대화에 맞춘 발췌다.

같은 계층에서 짚을 만한 도구가 하나 더 있다. ast-grep(ast-grep/ast-grep)이다. tree-sitter 기반 구조 검색과 rewrite를 하는 CLI인데, 텍스트 대신 구문 트리의 노드를 매칭한다. 예를 들어 console.log($A) 패턴은 줄바꿈이나 공백이 어떻게 생겼든 인자 하나로 console.log 를 부르는 호출을 모두 잡는다. 잡는 것은 같은 구문 구조다. $A 의 타입이나 console 이 어디서 온 이름인지는 모른다. ast-grep-mcp 서버도 있어서 에이전트가 텍스트 grep 대신 구조 검색을 쓰게 만들 수 있다.

지식 그래프

세 번째 계층은 한 발 더 나아간다. 사전에 코드베이스 전체를 파싱해서 지식 그래프를 만들어 디스크에 저장해두고, 에이전트는 저장해둔 그래프에 쿼리를 던지는 방식이다. 가장 화제가 되는 사례가 CodeGraph 라는 도구이다.

CodeGraph README가 설명하는 구조는 단순하다. tree-sitter로 코드를 파싱해 심볼, 엣지, 파일 정보를 뽑고, 이것을 로컬 SQLite 데이터베이스에 저장한다. 이름 검색은 SQLite의 FTS5 인덱스로 한다. 에이전트는 MCP를 통해 이 그래프에 묻는다. README가 설명하는 단계에는 LLM이 등장하지 않는다. 그래서 필자는 이 추출이 결정론적(deterministic), 즉 같은 코드에서 늘 같은 결과가 나온다고 본다.

LLM이 코드를 요약해서 그래프를 만들면 같은 코드에서도 결과가 달라질 수 있고 환각이 섞일 위험이 있다. 반면 구문 트리를 직접 파싱하면 언어 문법이 정한 규칙대로만 심볼 관계를 뽑으므로 그런 해석이 끼어들 틈이 없다.

여기 등장하는 FTS5(SQLite Full-Text Search 5) 는 SQLite의 가상 테이블 형태로 제공되는 전문 검색 확장이다. SQLite 문서에 따르면 3.9.0(2015-10-14)부터 amalgamation에 포함됐고, CREATE VIRTUAL TABLE ... USING fts5(...) 로 테이블을 만들어 MATCH 연산자로 질의한다. Elasticsearch 같은 별도 검색 엔진을 띄우지 않고도 SQLite 파일 하나로 전문 검색 인덱스를 둘 수 있다.

다만 결정론적인 것과 빠짐없는 것은 다르다. 같은 README는 관례와 reflection에 기대는 프레임워크의 route 인식률을 Django 74.1%에서 ASP.NET 83.9%까지로 적고, 이를 정적 분석의 한계(honest static-analysis ceiling)라고 부른다. 같은 코드에서 같은 결과가 나오지만, 그 결과에서 빠진 엣지가 있을 수 있다.

벤치마크는 CodeGraph가 직접 잰 것이다. 같은 README의 2026-08-05 재측정은 Claude Opus 4.8을 headless로 돌려 7개 오픈소스 리포에 아키텍처 질문을 하나씩 던졌다. CodeGraph MCP를 켠 쪽이 평균 비용 44%, 처리 토큰 62%, tool call 88%를 줄였다. 이 재측정은 양쪽 모두 Bash로 codegraph CLI를 부르지 못하게 막았다. 막지 않은 측정 환경에서는 도구 없는 쪽이 28회 중 26회 CLI를 찾아 썼고, README는 이전에 발표한 수치가 이 차단 없이 나왔다고 밝힌다.

절감 폭은 리포 크기를 따르지 않았다. 도구 없는 쪽이 tool call을 28~43번 쓴 질문에서는 비용이 57~78% 줄었고, 7번으로 끝난 Gin에서는 거의 같았다. 파일이 약 11k개인 VS Code가 71%, 약 640개인 Excalidraw가 78%였다. README는 이를 질문이 요구한 탐색량으로 설명한다. 리포마다 질문이 하나뿐이라 필자는 방향만 읽는다.

README는 반대 방향의 숫자도 적는다. 처리한 토큰은 줄지만, 여러 턴짜리 세션이 끝났을 때 context window에 남아 있는 retrieval 결과는 7개 리포를 통틀어 CodeGraph 쪽이 약 80% 많다. 리포마다 차이가 커서, VS Code 한 곳에서는 67k 대 18k tokens로 약 3.7배였다. 한 번에 원문을 촘촘히 돌려주고 그것이 창에 그대로 남기 때문이다. CodeGraph는 tool call과 처리 토큰을 줄이는 대신 창에 남는 양을 늘렸다.

Cursor는 다른 길로 갔다가 방향을 바꿨다. 2026년 1월 Cursor 블로그가 설명한 인덱싱은 구문 그래프가 아니라 벡터 임베딩 기반 의미 검색이었다. 로컬에서 파일을 chunk로 나누고, Merkle tree 해시로 서버와 동기화하고, chunk를 임베딩으로 바꿔 의미 검색에 썼다. 2026년 7월 Cursor의 Community Support Engineer는 포럼에서 "Semantic/embeddings indexing is being turned down in favor of grep-based retrieval" 이라고 답했다. 같은 스레드에서 다른 직원은 모델이 grep을 잘 쓰게 되면서 예전 의미 검색 경로가 더는 의미 있게 돕지 못했다고 썼다. 지금 Cursor 문서는 Instant Grep이 인덱스를 로컬에서 만들고 질의하며, 검색용으로 코드베이스의 임베딩을 저장하지 않는다고 적는다.

LSP

마지막 계층은 언어 서버에 직접 의존하는 방식이다. tree-sitter가 "심볼이 존재한다는 것"을 안다면, LSP는 "그 심볼이 무엇인지"를 안다.

LSP(Language Server Protocol) 는 에디터와 언어 분석 도구(코드 완성, 정의로 이동, 참조 찾기, 리팩토링 등) 사이의 통신을 표준화한 JSON-RPC 기반 개방형 프로토콜이다. 2016년 Microsoft, Red Hat, Codenvy가 협력을 발표했다. 핵심 아이디어는 "에디터마다 언어 분석기를 재구현하지 말고, 언어별 서버 하나를 두고 모든 에디터가 그 서버에 질의하자"는 것이다. rust-analyzer와 Python의 pyright가 LSP 서버이고, TypeScript는 자체 프로토콜을 쓰는 tsserver 를 LSP로 감싼 typescript-language-server를 쓴다.

Serena(oraios/serena)가 이 계층에 속하는 MCP 서버다. 2026-10-08 기준 30,093 stars이고, 저장소는 2025년 3월에 만들어졌다. Serena의 핵심 아이디어는 한 줄로 요약된다. 에이전트에게 코드를 심볼 단위로 보여주자. 핵심 도구는 find_symbol, find_referencing_symbols, get_symbols_overview 등이다. 백엔드는 두 가지 중 하나를 선택할 수 있다. 기본값은 LSP를 구현한 언어 서버(무료/오픈소스), 다른 옵션은 JetBrains IDE의 코드 분석을 활용하는 유료 플러그인(무료 체험 제공)이다.

이 리포에서 재 보면 차이가 어디서 나는지 보인다. 비공개 글을 거르는 isHiddenPost(src/lib/filter-posts.ts:12)의 사용처를 두 방식으로 찾았다. 텍스트 쪽은 grep이다.

# 커밋 36e5cfa, 2026-10-08. 이 글도 같은 이름을 담고 있어 content/ 는 뺐다
git grep -n isHiddenPost -- ':!content'   # 16줄, 파일 9개
git grep -n -C1 isHiddenPost -- ':!content'   # 같은 16곳을 앞뒤 1줄과 함께

LSP 쪽은 Serena의 find_referencing_symbols를 불렀다. LSP의 참조 찾기는 이름이 아니라 위치(파일과 줄, 열)로 묻기 때문에, 이 도구도 심볼 이름인 name_path 와 정의가 있는 파일인 relative_path 를 함께 받는다. Serena를 MCP 서버로 띄우지 않고 같은 커밋에서 Python으로 도구를 바로 호출했다.

# serena 3b99f8b, 커밋 36e5cfa, 2026-10-08. 리포 루트에서 실행한다
# uvx --python 3.12 --from git+https://github.com/oraios/serena@3b99f8b024dafd58c962ea6e74f37c8a730ef532 python refs.py
from serena.agent import SerenaAgent
from serena.config.serena_config import SerenaConfig
from serena.tools.symbol_tools import FindReferencingSymbolsTool
agent = SerenaAgent(project=".", serena_config=SerenaConfig().with_headless_mode_overrides())
agent.execute_task(lambda: None)  # 언어 서버가 뜰 때까지 기다린다
tool = agent.get_tool(FindReferencingSymbolsTool)
print(agent.execute_task(lambda: tool.apply(name_path="isHiddenPost", relative_path="src/lib/filter-posts.ts")))

출력은 JSON 한 줄이다. 첫 항목만 옮기면 이렇다. 줄 번호는 0부터 센다.

{"src/lib/filter-posts.ts": {"Function": [{"name_path": "filterPublishedPosts", "body_location": {"start_line": 22, "end_line": 24}, "content_around_reference": "...  22:export function filterPublishedPosts(posts: Post[]): Post[] {\n  >  23:  return posts.filter(post => !isHiddenPost(post))\n...  24:}"}]}, ...

Serena는 참조 10곳을 돌려줬다. 정의가 있는 filter-posts.ts:12 는 빼고, 세 파일의 import 줄은 그 파일 자체를 심볼(File)로 삼아 돌려준다. grep이 잡은 코드 위치 11곳은 이 10곳에 정의 한 줄을 더한 것과 같다. 이 이름은 리포에 하나뿐이라 grep도 코드 위치를 놓치거나 더 잡지 않았다. grep이 더 잡은 5곳은 이 함수를 설명하는 문서 속 문장이었다. 루트의 CLAUDE.md, .claude/commands/ 의 audit.md 와 write-post.md, 그리고 docs/research/snapshot-20260816/ 에 남은 CLAUDE.md 와 write-post.md 사본이다.

Serena는 참조마다 앞뒤 1줄을 붙여 돌려준다. 그래서 grep은 줄 번호만 받는 git grep -n 과 앞뒤 1줄을 함께 받는 git grep -n -C1 두 가지로 돌리고, 세 출력 전체를 o200k_base 로 셌다.

앞뒤 1줄을 함께 받는 grep과 견주면 Serena가 683 tokens 적다. 차이는 문서 5곳을 돌려주지 않는 데서 나온다. 다만 Serena는 참조마다 심볼 이름과 위치 정보를 JSON으로 붙이므로 코드 쪽만 보면 오히려 159 tokens 많다. 줄 번호만 돌려주는 git grep -n 의 703 tokens보다는 Serena의 892 tokens가 크다. 이 리포에서 LSP 계층이 아끼는 것은 검색 결과가 아니라, grep 결과를 보고 주변 줄이나 파일을 더 읽는 다음 단계다.

다음 단계에서 에이전트가 grep에 걸린 파일 9개를 통째로 읽는다면 읽는 양은 47,034 tokens이고, 코드 4개가 3,716, 문서 5개가 43,318이다. 이것은 상한이다. CLAUDE.md 는 실제 세션에서 이미 context에 올라 있어 다시 읽지 않을 가능성이 높다. isLocale 처럼 흔한 이름이라면 코드 위치에서도 결과가 갈릴 수 있다.

마무리

정리하면, 네 계층은 코드를 얼마나 깊이 이해하느냐에 따라 갈리고 줄이는 비용도 다르다. Context packing은 코드를 텍스트로 넘기고, --compress 를 줘도 구문까지만 남겨 들어가는 토큰을 줄인다. tree-sitter repo map은 심볼이 있다는 것까지 알고, 들어가는 토큰에 예산으로 상한을 두고, 그 안을 무엇으로 채울지는 그 순간의 대화가 정한다. 지식 그래프는 관계를 미리 저장해 tool call과 처리 토큰을 줄이지만, 제작사 측정으로는 창에 남는 양이 오히려 늘었다. LSP는 심볼이 무엇인지까지 알고, 이 리포에서는 문서 속 같은 이름을 돌려주지 않는 대신 결과마다 메타데이터를 붙였다. 아끼는 지점은 검색 결과가 아니라 그 뒤의 읽기다.

그래서 필자는 도구를 고를 때 계층의 깊이보다 지금 어떤 비용이 문제인지를 먼저 본다. 창이 작고 세션이 길면 남는 양을, 왕복이 느리면 tool call 수를, 문서와 코드가 같은 이름을 공유하는 리포라면 grep 결과를 보고 더 읽게 되는 파일의 양을 본다. Cursor가 임베딩 의미 검색을 걷어내고 로컬 텍스트 인덱스(Instant Grep)로 옮긴 것도, 비싼 인덱스가 모델의 탐색 능력보다 늘 낫지는 않다는 신호로 읽힌다.

이 도구들이 에이전트가 코드를 찾는 비용을 줄인다면, 에이전트가 처음부터 알아야 할 프로젝트 규칙을 어떤 파일에 얼마나 적을지는 또 다른 문제다. 그 이야기는 Context file에서 다룬다.

Claude Code나 Cursor에 MCP 서버를 붙여 쓰고는 있지만, 그것이 LLM API의 function calling과 어디서 갈리는지 설명하기 어려웠던 개발자를 위한 글이다. 답부터 적으면 MCP는 function calling을 대체하지 않는다. 호스트 애플리케이션이 MCP 서버에서 받은 도구 목록을 function calling의 tools 파라미터로 바꿔 넣고, 모델이 고른 호출을 다시 MCP 서버로 넘긴다. 끝까지 읽으면 그 위에서 MCP가 더하는 네 가지 차이가 프로토콜의 어느 부분에서 나오는지, 2026-07-28 개정판 이후에도 남는 차이가 무엇인지, 그리고 그 구조가 어떤 공격면을 여는지 알 수 있다.

필자는 프론트엔드 개발자로 일하면서 일상적으로 Claude를 활용하는데, MCP 서버를 하나씩 추가할 때마다 이 도구들이 어떤 원리로 모델의 시야에 들어오는지가 매번 가물가물했다.

MCP(Model Context Protocol)

MCP(Model Context Protocol)는 "에이전트에게 무엇을 할 수 있게 해줄까"의 문제를 푼다.

조금 풀어쓰면 이렇다. AI 에이전트가 Slack에 메시지를 보내려면 Slack API를 호출할 수 있어야 한다. GitHub 이슈를 만들려면 GitHub API를 호출할 수 있어야 한다. Postgres에 쿼리하려면 DB 연결을 다룰 수 있어야 한다. 이 모든 외부 시스템과의 통합을 하나의 표준 프로토콜로 묶은 것이 MCP다. (클라이언트와 서버가 같은 규격으로 연결된다는 뜻이다)

MCP는 Anthropic이 2024년 11월 25일에 처음 공개한 개방형 표준이다. 그리고 2025년 12월 9일, Anthropic은 MCP를 Linux Foundation 산하 Agentic AI Foundation(AAIF)에 기증했다. AAIF는 Anthropic·Block·OpenAI가 공동 창립했다.

MCP는 JSON-RPC 위에 만들어진 프로토콜이다. JSON-RPC 2.0은 JSON을 와이어 포맷으로 쓰는 stateless·경량 RPC(Remote Procedure Call) 프로토콜이다. 전송 계층에 독립적이어서 HTTP·TCP·표준 입출력 무엇이든 위에서 동작한다. 이 글은 2025-11-25 개정판을 기준으로 설명하고, 이 판에서 MCP는 연결마다 세션을 맺는 stateful 프로토콜이다. 그 뒤에 나온 개정판에서 무엇이 바뀌었는지는 호출 흐름을 본 다음에 다룬다.

여섯 가지 primitive

2025-11-25 명세의 개요는 서버가 제공하는 기능 셋과 클라이언트가 제공하는 기능 셋을 든다. 이 글은 이 여섯을 primitive라고 부른다. 여기서 primitive는 JavaScript의 원시 타입(string, number 같은 것)과는 관계가 없고, 프로토콜이 정의해 둔 기본 상호작용 유형을 가리킨다.

서버측 primitive

• Tool (model-controlled): 모델이 호출 여부를 스스로 판단해 실행하는 동작이다. 이런 동작은 부작용(side effect)을 가질 수 있다
• Resource (application-controlled): URI로 식별되는 데이터다. 스펙에는 내용을 읽어 오는 resources/read 만 있고 쓰는 메서드는 없다. 그 리소스를 context에 어떻게 넣을지는 호스트 애플리케이션이 결정한다.
• Prompt (user-controlled): 사용자가 슬래시 명령 등으로 명시적으로 트리거하는 재사용 가능한 템플릿이다.

클라이언트측 primitive

• Sampling: 서버가 거꾸로 클라이언트의 LLM에게 completion을 요청할 수 있게 해주는 메커니즘으로 클라이언트와 서버를 양방향 구조로 만든다. 서버가 도구를 실행하다 문장 생성이 필요할 때 자기 API 키 없이 클라이언트가 쓰는 모델을 빌리는 용도다. 2026-07-28 개정판에서는 제거 예정인 deprecated 상태가 되었다.
• Roots: 클라이언트가 서버에게 "여기까지가 작업 가능한 범위"라고 알려주는 워크스페이스 경계 정보
• Elicitation: 서버가 도구를 실행하는 도중에 사용자에게 추가 입력을 구조화된 형태로 요청할 수 있게 해주는 기능

이 구분이 중요한 이유는 누가 호출이나 제공을 결정하는가가 다르기 때문이다. Tool은 모델이 판단해 실행하니 잘못된 호출의 리스크가 있고, Prompt는 사용자가 명시적으로 고른다. Resource는 앱이 고르는 것이 기본이지만, 스펙은 heuristic이나 모델의 선택으로 자동 포함하는 구현도 허용한다. 클라이언트측 세 가지는 방향이 반대다. 서버가 요청하고, 응할지는 클라이언트가 정한다.

두 가지 전송 방식

표준 전송 방식은 두 가지이고, 스펙은 그 밖의 커스텀 전송도 허용한다(MAY). 하나는 stdio로, MCP 서버를 로컬 서브프로세스로 실행하고 표준 입출력으로 통신하는 방식이다. 파일시스템이나 깃처럼 로컬에서 동작하는 도구에 적합하다. 다른 하나는 Streamable HTTP인데, HTTP POST와 GET에 SSE(Server-Sent Events) 스트리밍을 얹어서 양방향에 가까운 통신을 만들어내는 방식이다. SSE는 HTTP 연결 위에서 서버가 클라이언트로 데이터를 한 방향으로 밀어 보내는 방식이다. 원격 서버, OAuth 인증, 다중 클라이언트 연결, 클라우드 배포처럼 네트워크 너머에서 일어나는 시나리오에 적합하다.

LLM이 MCP 도구를 호출하는 흐름

primitive와 전송 방식까지 봤으니, 이제 실제로 LLM이 MCP 도구를 어떻게 발견하고 호출하는지의 흐름을 따라가보자.

2025-11-25 개정판에서 연결이 시작되면 다음 순서의 handshake가 일어난다. 2026-10-08 현재 TypeScript SDK의 1.32.1과 v2 계열 2.3.1도 기본 설정에서는 이 순서로 움직인다.

• 클라이언트 → 서버: initialize 요청 (지원하는 프로토콜 버전, 클라이언트 capabilities 전달)
• 서버 → 클라이언트: initialize 응답 (서버 capabilities + 선택적으로 instructions 필드)
• 클라이언트 → 서버: notifications/initialized 알림
• 클라이언트 → 서버: tools/list 요청 → 사용 가능한 도구 목록 수신
• (이후) LLM이 도구를 호출하기로 결정 → 클라이언트가 tools/call 발송 → 결과 수신

initialize 응답의 instructions 필드는 서버가 도구를 어떻게 써야 하는지 텍스트로 적어 보내는 자리다. 아래 데모 출력의 instructions 줄이 이 값이다.

그러면 tool 정의 자체는 어떻게 LLM의 시야에 들어갈까. MCP의 tool 정의는 다음과 같은 JSON Schema 형태다.

{
  "name": "get_weather",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": { "location": { "type": "string" } },
    "required": ["location"]
  }
}

호스트는 tools/list 로 받은 이 목록을 Anthropic Messages API의 tools 파라미터 또는 OpenAI function calling의 tools 파라미터로 변환해서 LLM API 호출에 같이 넣는다. Anthropic의 경우, tool 파라미터가 들어오면 special system prompt가 자동으로 추가되어 모델이 tool 호출 방식을 이해하도록 만든다. 그 길이는 모델마다 다르다. 2026-10-08 에 본 문서 표에서 tool_choice: auto 기준 현행 모델은 286~675토큰이었다.

LLM이 도구를 호출해야 한다고 판단하면 응답 안에 tool_use 블록({"type": "tool_use", "name": ..., "input": ...})이 끼어 있고, 응답의 stop_reason이 tool_use로 끝난다. 호스트는 이걸 받아 실제 MCP 서버로 tools/call을 발송하고, 결과를 받아서 다음 user 메시지의 tool_result 블록에 담아 다시 LLM에 보낸다. stop_reason이 tool_use가 아닌 값(end_turn, max_tokens 등)으로 바뀔 때까지 이 루프가 반복된다. 우리가 흔히 "에이전트가 일한다"고 부르는 동작은 사실 이 호출-결과-호출 루프의 연속에 가깝다.

그림으로 놓으면 모델과 MCP 서버 사이에는 선이 없다. 모델은 tools 로 받은 정의만 보고, MCP 서버는 모델이 아니라 호스트의 요청을 받는다. 두 프로토콜을 잇는 것은 가운데의 호스트다.

이 변환이 실제로 얼마나 짧은지 돌려 봤다. 2026-10-08 에 Node v24.16.0, @modelcontextprotocol/sdk 1.32.1, zod 4.6.5로 실행했다. 전송은 stdio 대신 같은 프로세스 안에서 서버와 클라이언트를 잇는 InMemoryTransport 이고, LLM은 호출하지 않았다. tool_use 블록은 Anthropic 문서의 모양대로 손으로 만들었다.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { z } from "zod";
 
// MCP 서버: 도구 하나와 instructions 를 둔다
const server = new McpServer(
  { name: "weather", version: "1.0.0" },
  { instructions: "Use get_weather for current conditions only." }
);
server.registerTool(
  "get_weather",
  { description: "Get current weather information for a location", inputSchema: { location: z.string() } },
  async ({ location }) => ({ content: [{ type: "text", text: `${location}: 15C, partly cloudy` }] })
);
 
// 호스트: 같은 프로세스 안에서 서버와 잇고, 클라이언트가 보내는 메서드 이름을 찍는다
const [clientT, serverT] = InMemoryTransport.createLinkedPair();
const send = clientT.send.bind(clientT);
clientT.send = (m) => { console.log("C->S", m.method, m.params?.protocolVersion ?? ""); return send(m); };
await server.connect(serverT);
const client = new Client({ name: "demo-host", version: "1.0.0" });
await client.connect(clientT);
console.log("instructions:", client.getInstructions());
 
// 1. tools/list 결과를 LLM API 의 tools 파라미터 모양으로 바꾼다
const { tools } = await client.listTools();
const anthropicTools = tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.inputSchema }));
const openaiTools = tools.map((t) => ({ type: "function", name: t.name, description: t.description, parameters: t.inputSchema }));
console.log("anthropic:", JSON.stringify(anthropicTools[0]));
console.log("openai:", JSON.stringify(openaiTools[0]));
 
// 2. 모델이 이런 tool_use 블록을 돌려줬다고 가정한다. input 이 그대로 tools/call 의 arguments 가 된다
const toolUse = { type: "tool_use", id: "toolu_demo", name: "get_weather", input: { location: "Seoul" } };
const result = await client.callTool({ name: toolUse.name, arguments: toolUse.input });
console.log("tool_result:", JSON.stringify({ type: "tool_result", tool_use_id: toolUse.id, content: result.content }));
await client.close();

node post-demo.mjs 의 출력은 이렇다.

C->S initialize 2025-11-25
C->S notifications/initialized 
instructions: Use get_weather for current conditions only.
C->S tools/list 
anthropic: {"name":"get_weather","description":"Get current weather information for a location","input_schema":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"],"$schema":"http://json-schema.org/draft-07/schema#"}}
openai: {"type":"function","name":"get_weather","description":"Get current weather information for a location","parameters":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"],"$schema":"http://json-schema.org/draft-07/schema#"}}
C->S tools/call 
tool_result: {"type":"tool_result","tool_use_id":"toolu_demo","content":[{"type":"text","text":"Seoul: 15C, partly cloudy"}]}

도구 정의의 변환은 필드 이름을 바꾸는 것이 전부다. MCP의 inputSchema 가 Anthropic에서는 input_schema, OpenAI에서는 parameters 가 된다. SDK가 schema에 $schema 를 덧붙인다는 점도 출력에서 보인다. 반대 방향도 짧다. Anthropic의 tool_use.input 은 객체라서 그대로 tools/call 의 arguments 가 된다. 결과 쪽도 text 블록은 모양이 같아 그대로 넘어가지만, 이미지나 에러 결과는 모양이 달라 Anthropic SDK의 MCP helper가 따로 변환한다. 위 OpenAI 쪽 모양은 Responses API의 형식이다. OpenAI가 돌려주는 호출의 arguments 는 JSON 문자열이라서 넘기기 전에 JSON.parse 를 한 번 거쳐야 한다. 위 코드는 Anthropic 모양의 tool_use 블록만 만들었으므로 이 parse 단계는 출력에 나오지 않는다.

MCP가 더하는 네 가지

그렇다면 MCP는 function calling에 무엇을 더하는가? 2025-11-25 개정판 기준으로 네 가지다.

• 동적 발견: 빌드 타임에 도구 목록을 모르고 런타임에 tools/list 로 가져온다. 서버는 notifications/tools/list_changed 로 연결 도중 목록이 바뀌었다고 알릴 수 있다
• Stateful session: initialize 로 연결을 맺고 그 안에서 요청이 오간다. 종료용 JSON-RPC 메시지는 따로 없고 전송을 닫는 것으로 끝낸다
• Tool 외 primitive: Resource·Prompt·Sampling·Roots·Elicitation을 capability negotiation으로 노출한다. capability negotiation은 initialize 에서 양쪽이 지원하는 기능을 서로 알리는 단계다
• 양방향성: 서버가 Sampling으로 클라이언트의 LLM에게 completion을 거꾸로 요청할 수 있다(2026-07-28 개정판에서 deprecated)

2026-07-28 개정판 이후

2026-10-08 현재 공식 사이트에서 latest로 열리는 것은 2026-07-28 개정판이고, 여기서 이 목록의 절반이 바뀌었다. 먼저 initialize 와 notifications/initialized 로 이루어진 handshake와 프로토콜 수준의 세션이 사라졌다. 대신 매 요청이 _meta 에 프로토콜 버전과 클라이언트 capabilities를 싣는다. 이 필드는 메시지의 본래 인자와 별도로 메타데이터를 붙이도록 MCP가 예약해 둔 자리다. 서버는 server/discover 를 반드시 구현해야 한다(MUST). 서버가 지원하는 프로토콜 버전, capabilities, 서버 정보를 돌려주는 RPC로, 클라이언트는 다른 요청보다 먼저 이것을 불러 지원 버전과 capabilities를 미리 확인할 수 있다.

서버가 먼저 보내던 요청은 Multi Round-Trip Requests(MRTR)라는 패턴으로 바뀌었다. 서버가 요청을 따로 보내는 대신 추가 입력이 필요하다는 중간 결과(input_required)를 돌려주고, 클라이언트가 그 입력을 채워 원래 요청을 다시 보내는 방식이다.

Sampling과 Roots는 Logging과 함께 deprecated 되었다. 명세에 남아 동작은 하지만 새 구현은 채택하지 말라는 뜻이고, 스펙은 Sampling 대신 LLM provider API에 직접 붙으라고 권한다.

다만 SDK의 기본 동작은 아직 옛 방식이다. TypeScript SDK 1.32.1은 최신 버전 상수가 2025-11-25 라서 2026-07-28 개정판을 모르고, 2.3.1은 이 개정판을 지원하지만 버전 협상 기본값이 legacy 다. 위 출력의 첫 줄 initialize 2025-11-25 가 그 결과다.

그러면 네 가지 중 남는 것은 동적 발견과 Tool 외 primitive(Resource, Prompt, Elicitation)다. 동적 발견도 모양이 조금 바뀌어서, 목록 변경 알림은 subscriptions/listen stream에 opt-in 한 클라이언트만 받는다. 결국 MCP가 function calling과 갈리는 지점은 세션이나 양방향성보다 도구 목록과 context를 런타임에 주고받는 계약에 있다.

API가 MCP 클라이언트가 될 때

이 계약 중 어디까지가 모델에게 닿는지는 Anthropic의 MCP connector(beta)가 보여 준다. Messages API가 원격 MCP 서버에 직접 붙는 기능인데, 문서의 Limitations는 MCP 명세의 기능 가운데 "only tool calls are currently supported" 라고 적고, "Local STDIO servers cannot be connected directly" 라고 적는다. 같은 문서는 로컬 서버나 MCP prompt, resource가 필요하면 MCP SDK로 연결을 직접 관리하면서 Anthropic SDK의 변환 helper를 쓰라고 안내한다.

즉 function calling layer에서 MCP를 소비하면 Tool만 남는다. Resource와 Prompt는 그것을 화면이나 context로 옮겨 줄 호스트가 있어야 의미를 갖는다. OpenAI도 function calling 가이드에서 MCP 서버의 기능을 built-in tool로 쓰는 길을 소개한다. OpenAI의 MCP servers 가이드는 도구 목록을 가져오고 호출하는 방법만 설명하고, Resource나 Prompt를 지원하는지는 적지 않는다.

동적 발견이 여는 공격면

도구의 description과 도구 호출 결과는 호스트를 거쳐 모델의 context에 들어간다. 그러니 서버가 그 자리에 무엇을 쓰든 모델은 그것을 읽는다. 대표적인 공격 두 가지가 모두 여기서 나온다.

• Tool Poisoning Attack(TPA): Invariant Labs가 2025년 4월에 명명하고 PoC를 공개한 공격이다. MCP 서버의 도구 설명(description)에 악의적 지시사항을 숨겨 두면, 모델은 사용자에게 보이지 않는 그 텍스트를 읽고 사용자 모르게 따를 수 있다.

• Rug Pull: Invariant Labs가 같은 글에서 설명한 공격으로, 사용자가 승인한 뒤에 서버가 도구 정의를 바꾼다. Simon Willison이 인용한 Elena Cross의 예처럼, 1일 차에 안전해 보이는 도구를 승인했는데 7일 차에는 그 도구가 API 키를 공격자에게 보내도록 바뀌어 있는 식이고, 도구 정의를 설치 시점이 아니라 런타임에 서버에서 받아 오는 구조라서 생긴다. tool 명세는 어떤 도구가 모델에 노출되는지 보여 주는 UI를 권할(SHOULD) 뿐 바뀐 정의를 다시 승인받으라고 요구하지는 않으므로, 재승인은 호스트의 몫이다.

마무리

정리하면, MCP는 function calling을 대체하는 것이 아니라 그 위에 얹힌 표준이다. 모델이 도구를 부르는 방식은 여전히 tools 파라미터와 tool_use 루프이고, 두 프로토콜 사이는 호스트가 번역한다. 2025-11-25 개정판에서 MCP가 더한 것은 동적 발견, stateful session, Tool 밖의 primitive, 서버에서 클라이언트로 향하는 호출이었다. 2026-07-28 개정판에서 세션이 사라지고 Sampling이 deprecated 되면서 남는 것은 도구 목록과 context를 런타임에 주고받는 계약이다. 그 계약 때문에 도구 정의를 오염시키거나 몰래 바꾸는 공격도 같은 자리에서 생긴다. MCP 서버를 하나 더 붙일 때는 그 서버가 무엇을 할 수 있는지와 함께, 정의가 바뀌었을 때 호스트가 알려 주는지도 확인해 보길 권한다.

MCP가 에이전트에게 무엇을 할 수 있게 해줄지의 문제라면, 무엇을 알려줄지는 CLAUDE.md나 AGENTS.md 같은 context file의 문제다. 그 파일들이 에이전트에게 어떻게 읽히고 어디까지 지켜지는지는 Context file에서 다룬다.

요즘 AI 도구들(Claude, ChatGPT, Cursor, Gemini, Copilot)이 우리 옆에 깊숙이 자리잡았다. 개발 속도는 기하급수적으로 빨라졌는데, 솔직히 말하면 서비스의 완성도는 그만큼 따라오지 못하고 있다는 인상을 받는다. 늘어난 기능만큼 늘어난 버그를 마주하는 일이 잦아졌고, "이거 왜 이렇게 됐는지 모르겠어요"라는 말도 자주 듣게 된다.

빠르게 개발하는 만큼 코드 한 줄 한 줄을 세밀하게 들여다보지는 않게 된다. 그렇기에 더더욱 AI에게 옳은 방향을 가이드할 수 있는 기본 실력이 필요하다고 필자는 생각한다. AI가 짜준 코드의 문제를 알아채고, 원하는 방향으로 다시 가이드할 수 있어야 결과물의 품질이 유지된다. 그 기본 실력에는 도메인 관점의 개발, 추상화, TDD(Test-Driven Development, 테스트 주도 개발), 라이브러리 활용, 성능 우위 확보 등 여러 가지가 있을 것이다.

그런데 필자가 프론트엔드 동료들에게, 그리고 다른 IT 직군의 동료들에게 "프론트엔드 개발에서 제일 까다로운 작업이 뭐예요?"라고 물어볼 때마다 가장 많이 듣는 대답은 한결같았다. "상태 흐름 관리요."

이 글에서는 왜 상태 흐름 관리가 그렇게 까다로운지, 그리고 그것을 잘 다루기 위해 어떤 안목과 느낌을 키워야 하는지를 정리해보려 한다.

상태(State)란 무엇인가

본격적인 이야기에 들어가기 전에, 가장 기초적인 질문부터 짚고 가자. 우리가 말하는 "상태"란 정확히 무엇일까?

프론트엔드 개발 공부하며 hoseung.me님의 글을 종종 읽었다. 여기서는 상태를 "UI에 영향을 줄 수 있는 모든 데이터" 라고 이야기한다. 좋아요 수, 장바구니 목록, 모달의 열림 여부, 입력값, 로그인된 사용자 정보, 현재 선택된 탭, 검색 결과, 로딩 여부. 이 모든 것이 상태이다.

React 공식 문서는 좀 더 형식적으로 정의한다. 페이지 제목이 그대로 "State: A Component's Memory"인데, 풀어보면 "컴포넌트가 렌더 사이에 데이터를 기억하고(retain), 갱신될 때 React에게 리렌더링을 트리거하는 메커니즘" 정도이다. 즉 시간이 지나도 사라지지 않고, 어떤 이벤트에 의해 갱신되며, 갱신될 때 UI를 다시 그리게 만드는 데이터이다. 한 가지 더 짚자면 상태는 컴포넌트 인스턴스마다 고립된다. 같은 컴포넌트가 페이지에 열 개 있어도 각자 독립된 상태를 갖는다. 이 사실은 뒤에 다룰 "상태를 어디에 둘 것인가" 논의와 직접 연결된다.

두 정의 모두 한 곳을 가리킨다. "렌더에 영향을 주면서 시간에 따라 변하는 값" 이 상태이다. 변하지 않는 상수(constant)는 상태가 아니다. 빌드 타임에 박혀버린 원시 디자인 토큰은 상태가 아니지만, 사용자가 토글하는 다크 모드는 상태이다. (엄밀히 말하면 값 자체가 다크/라이트 테마라는 상태에 따라 resolve되는 것이라, "테마 선택"이 상태이고 토큰은 그 상태가 비추는 거울이라고 보는 게 정확하다)

여기서 한 가지 짚고 갈 점이 있다. 모든 상태가 컴포넌트에 사는 것은 아니다. 쿠키에 사는 상태도 있고, localStorage·sessionStorage·IndexedDB에 사는 상태도 있고, URL에 사는 상태도 있다. 서버에 사는 데이터를 클라이언트로 들고 와서 캐시하면 그것도 일종의 상태가 된다. 브라우저 자체가 들고 있는 스크롤 위치나 히스토리 스택도, 우리 앱의 행동을 결정한다는 점에서 상태처럼 다뤄야 할 때가 있다.

왜 그렇게 까다로운가

상태를 다루는 게 왜 어려운지를 일단 단순하게 생각해보자. 필요한 상태를 만들고, 필요한 곳까지 전달하고, 갱신과 초기화만 잘 핸들링하면 되는 거 아닐까?

이 질문을 머릿속에 띄워둔 채로, 지금 일하고 있는 서비스의 한 페이지를 열어보자.

그 페이지에 컴포넌트가 몇 개나 있을까? 단순한 페이지라도 적게는 수십 개, 많게는 수백 개의 컴포넌트가 트리를 이루고 있을 것이다. 각 컴포넌트는 자기만의 상태를 들고 있을 수도 있고, 형제 컴포넌트와 상태를 공유할 수도 있으며, 부모로부터 상태를 내려받기도 한다. 페이지 간에도 상태가 전이되고, 새로고침을 해도 살아남아야 하는 상태가 있고, 탭을 닫으면 사라져야 하는 상태가 있다.

상태가 관리하기 어려운 진짜 이유는 이것이다. 수많은 상태들이 어디서 선언되고, 어떻게 갱신되고, 언제 소멸되는지를 우리는 한눈에 파악할 수 없다. 비슷한 역할의 컴포넌트가 늘어날수록 상태의 이름을 짓는 것도, 상태를 변경하는 코드를 추적하는 것도 까다로워진다.

그래서 보이지 않는 거미줄이 생긴다. A 컴포넌트의 어떤 클릭이 B의 데이터를 무효화시키고, B의 무효화가 C의 UI를 닫히게 만들고, C가 닫히면서 폼 입력이 사라진다. 이런 연쇄가 코드 어디에도 명시되어 있지 않으면, 버그를 디버깅할 때 우리는 머릿속에서 이 거미줄을 다시 그려야 한다.

그렇다면 우리는 이 거미줄을 어떻게 정돈해야 할까? 필자가 생각하는 첫 단추는 "상태에는 종류가 있다" 는 것을 인지하는 것이다.

모든 상태가 똑같은 상태가 아니다

Kent C. Dodds는 상태를 Server Cache (서버에 존재하는 정보를 클라이언트가 빠른 접근을 위해 들고 있는 것)와 UI State (인터페이스 동작을 제어하기 위해 UI에만 존재하는 것)로 나눈다. 우리는 종종 이 둘을 한데 묶을 때 실수를 한다.

TanStack Query 공식 문서는 서버-상태(server-state) 라이브러리로, 서버와 클라이언트 사이의 비동기 작업을 관리하고, Redux, MobX, Zustand 같은 도구들은 클라이언트-상태(client-state) 라이브러리라고 정의한다. (비동기 데이터를 저장할 수는 있지만, 그것은 비효율적이다)

핵심은 분명하다. 서버 상태와 클라이언트 상태는 다른 문제이다. 서버 상태는 비동기적이고, 다른 사용자가 바꿀 수 있으며, 시간이 지나면 stale(오래된) 상태가 된다. 클라이언트 상태는 동기적이고, 우리가 통제할 수 있으며, 새로고침하면 사라진다.(정확히는 페이지가 unload되면서 JavaScript 런타임이 재시작되고, heap 메모리에 올라가 있던 컴포넌트 트리와 그 안의 상태가 함께 회수된다. 그래서 새로 마운트될 때는 useState의 초기값부터 다시 시작한다) 이 둘을 같은 도구로 묶으려고 하면 캐시 무효화, 백그라운드 갱신, 낙관적 업데이트 같은 패턴을 다 직접 짜야 한다.

필자는 여기서 한 발 더 나아가, 프론트엔드의 상태를 일곱 가지 범주로 구분해서 본다. 미리 짚어두자면, 이 일곱 가지는 단일 축으로 깔끔하게 나뉘지 않는다. 저장 위치·출처·생애주기·역할이 섞여 있어 한 상태가 여러 범주에 동시에 속할 수도 있다. 완벽한 분류표가 아니라 상태를 어떻게 관리할지 결정할 때 던지는 질문들이라고 봐주면 좋겠다.

• 지역 상태(Local State): 한 컴포넌트, 또는 좁은 트리 안에서만 쓰는 상태
• 전역 상태(Global State): 앱 전체가 공유해야 하는 상태
• 서버 상태(Server State): 서버가 진실의 출처이고, 클라이언트는 캐시인 상태
• 폼 상태(Form State): 사용자 입력 중 일시적으로 존재하는 상태
• URL 상태(URL State): 주소창에 사는, 공유 가능하고 새로고침에도 살아남는 상태
• 외부 상태(External State): 쿠키, localStorage, sessionStorage, IndexedDB 등 React 외부에 사는 상태
• 상태 가드(State Guard): 상태 자체가 아닌, 상태의 조합으로 접근/실행을 막거나 검증하는 로직

이 분류 외에도 상태머신으로 정교화해야 하는 워크플로우 상태, WebSocket·CRDT 기반의 실시간 협업 상태가 있다.

각각이 왜 다른 도구를 필요로 하는지, 그리고 어떤 안목으로 접근해야 하는지를 하나씩 풀어보자.

지역 상태(Local State)

가장 단순한 상태이다. 한 컴포넌트 안에서만 사용하고, 외부에서는 알 필요도 알 권리도 없는 상태. 모달의 열림 여부, 토글 버튼의 on/off, 호버 상태, 입력 중인 검색어 같은 것이다.

function SearchBox() {
  const [query, setQuery] = useState("");
  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

이 정도는 익숙할 것이다. 그런데 지역 상태에서 진짜로 까다로운 건 "이 상태를 어디에 두어야 하는가" 라는 위치 결정의 문제이다.

Kent C. Dodds의 State Colocation 글에서 사람들은 상태를 "끌어올리는(lift up)" 것에는 익숙하지만, 코드가 바뀌었을 때 상태를 다시 "가까이 두는(colocate)" 것은 잘 하지 않는다. 라고 이야기를 한다.

상태를 끌어올리는 것은 형제 컴포넌트들이 같은 상태를 공유해야 할 때 우리가 자연스럽게 하는 행동이다. 두 형제가 같은 데이터를 봐야 하니, 공통 부모로 상태를 올려서 props로 내려준다.

문제는 그 상태가 더 이상 형제들에게 필요 없게 되었을 때이다. 우리는 그 상태를 다시 자식 쪽으로 끌어내리는 일을 잘 하지 않는다. 그 결과 부모 컴포넌트에는 사실 자기와 무관한 상태가 잔뜩 쌓이고, 부모가 리렌더링될 때마다 자식 트리 전체가 함께 리렌더링되는 일이 벌어진다.

그렇기에 지역 상태의 첫 번째 안목은 더 빠르고 ,단순해지는 것을 위해 상태를 그 상태를 쓰는 코드에 최대한 가까이 둬라 이다. 한 컴포넌트의 자식 하나에서만 쓰이는 상태라면, 부모가 들고 있을 이유가 없다. 그 자식 내부로 옮기자. 부모는 그만큼 가벼워진다.

전역 상태(Global State)

전역 상태는 앱 어디서나 접근 가능해야 하는 상태이다. 로그인 정보, 테마, 언어, 알림(토스트) 같은 것들이 후보가 된다.

지역 상태와 전역 상태의 차이는 단순히 "어디에 사느냐"가 아니다. 참조의 약속이 다르다. 지역 상태는 "이 컴포넌트 내부에서만 의미가 있다" 는 약속을, 전역 상태는 "앱 어디서든 이 이름으로 이 값을 참조할 수 있다" 는 약속을 코드 전체에 발행한다. 그 약속이 비싸다는 것이 전역 상태의 본질이다.

전역 상태를 하나 만든다는 것은, 사실 앱 전역에 걸친 암묵적 의존성을 하나 추가하는 일이다.

서버 상태(Server State)

API로 받아온 데이터를 클라이언트 상태에 넣고, 직접 로딩과 에러를 boolean으로 관리하다가, "왜 이렇게 매번 똑같은 보일러플레이트를 짜고 있지?" 라는 의문에 도달한다.

Tanstack 메인 관리자인 Tanner Linsley는 "클라이언트 상태는 동기적이고 예측 가능하다. 서버 상태는 비동기적이고, 여러 컴포넌트에 걸쳐 공유되며, 캐싱·백그라운드 갱신·에러 상태를 신중히 다루어야 한다." 라고 한다. 즉 서버 상태는 클라이언트 상태와 본질적으로 다른 종(種) 이다. 같은 도구로 다루면 안 된다.

서버 상태가 까다로운 것은 도구의 문제가 아니라 데이터의 본질 때문이다.

클라이언트가 보고 있는 데이터는 서버의 것이다. 클라이언트가 가진 데이터는 어느 시점의 스냅샷 일 뿐이다. 이 데이터는 시간이 지날수록 staleness가 발생한다. 또한 비동기적이고 실패할 수 있으며 pending, error, success 등의 상태를 가진다.

제일 중요한 본질은 응답이 보낸 순서대로 돌아온다는 보장이 없다는 점이다. 검색창에서 "react"를 빠르게 타이핑한다고 해보자. r → re → rea → reac → react 요청이 순서대로 나가지만, "react"의 응답이 먼저 도착하고 그 뒤에 "rea"의 응답이 도착하면, 화면에는 "rea"의 결과가 표시된다. 이런 문제를 막으려면 AbortController나 요청 ID 추적을 매번 손으로 짜야 하는 동시성 위험 (race conditions) 을 신경써야한다.

폼 상태(Form State)

폼은 묘한 상태이다. 사용자가 입력하는 동안에는 격렬하게 변하지만, 제출되고 나면 보통 사라진다. 다른 어디에도 공유되지 않고, 저장될 곳도 (대부분은) 없다.

문제는 이 "격렬한 변화"가 비싸다는 점이다. 모든 키 입력이 React의 리렌더링을 일으키면, 큰 폼에서는 입력 지연이 눈에 띌 정도가 된다. 그리고 폼은 단순히 "값을 들고 있는" 것이 아니다. 검증, dirty check, 제출 상태, 에러 메시지, 다단계 흐름까지 한 폼 안에서 여러 종류의 상태가 동시에 살아 움직인다.

3단계 결제 플로우 같은 다단계 폼은 "중간에 새로고침해도 진행 상태가 살아남기를 기대" 받는다. 이때 폼 값을 useState로만 들고 있으면 새로고침에 모두 날아간다. sessionStorage(탭 단위 임시 보관)나 URL(공유 가능한 단계)에 보관하는 것이 자연스럽다. 즉 폼 상태는 라이프사이클 요구에 따라 외부 상태나 URL 상태와 결합한다.

URL 상태(URL State)

검색 페이지에서 카테고리·정렬·페이지 번호를 필터링하고 있다고 해보자. 이 상태들을 useState로 들고 있으면 세 가지 문제가 동시에 생긴다.

• 새로고침하면 모든 필터가 초기화된다
• URL을 친구에게 공유해도 친구는 필터가 적용되지 않은 페이지를 본다
• 뒤로 가기를 눌러도 이전 필터로 돌아가지 않는다

이런 문제를 해결하는 방법으로 상태를 URL에 넣는게 자연스럽다. URL은 그 자체로 새로고침·공유·히스토리에 대응되는 공짜로 얻는 영구 저장소이다.

/products?category=shoes&sort=price-desc&page=2

이 URL 한 줄에 "신발 카테고리를 가격 내림차순으로 정렬한 2페이지" 라는 완전한 상태가 들어 있다. useState로 따로 들고 있을 필요가 없다.

그러면 언제 URL에서 상태를 다루는게 적합할까? URL은 공개 인터페이스이다. 비밀번호, 인증 토큰, 사용자가 누군가에게 보여주기 싫을 일시 메모 같은 것은 URL에 들어가면 안 된다. 또한 너무 자주 바뀌는 값(입력마다 갱신되는 검색어)을 그대로 URL에 박으면 히스토리 스택이 쓰레기로 가득 찬다. 이런 경우엔 debounce 후 반영하거나, push 대신 replace로 히스토리를 더럽히지 않게 해야 한다.

URL의 값은 항상 문자열이다. 숫자, boolean, 배열, 객체는 직렬화·역직렬화 단계를 거쳐야 한다. 게다가 URL은 퍼센트 인코딩(percent-encoding) 규칙을 따라야 해서 &, =, 한글, 공백 등이 특수 처리된다. 이걸 매번 손으로 짜면 곧 버그의 온상이 된다.

const params = new URLSearchParams(location.search);
const page = Number(params.get("page") ?? "1");
params.set("page", String(page + 1));
navigate(`?${params.toString()}`);
 
const [page, setPage] = useQueryState("page", parseAsInteger.withDefault(1));

nuqs 같은 라이브러리는 파서(parser) 개념으로 이 두 가지를 해결한다. parseAsInteger, parseAsBoolean, parseAsJson 같은 파서가 직렬화·역직렬화·타입을 한 번에 책임진다. Next.js (App/Pages Router 모두), React Router v6/v7, TanStack Router, Remix 등 대부분의 환경을 지원한다.

그러면 URL에 상태를 얼마든지 박아 넣어도 괜찮을까? 직렬화·타입 문제와는 별개로, 마지막으로 신경 써야 할 제약이 하나 남아 있다. RFC 7230은 정확한 한계를 정하지는 않지만, "서버가 최소 8,000 옥텟(네트워크나 데이터 통신에서 8개의 Bit가 모인 1Byte를 명확하게 지칭할 때 사용하는 단위)은 지원해야 한다"고 권장한다. 브라우저별 한계도 제각각이어서, 모던 브라우저는 대체로 8KB에서 수만 자까지 허용하지만 검색엔진·소셜 미디어의 OG/공유 처리, 일부 게이트웨이는 2KB 근처에서 잘리기도 한다. 그래서 URL에 무한정 박아 넣지는 말자. 공유 가능한 핵심 필터만 두고, 나머지는 sessionStorage나 서버 측 저장에 맡기는 것이 안전하다.

외부 상태(External State)

React는 자기 안의 상태만 안다. 그런데 우리 앱은 React 바깥의 세계와도 끊임없이 대화한다. 그 세계에 사는 상태들은 React의 생명주기와 무관하게 살아남고, 또 변한다. 여기서 의미하는 외부 상태에는 Cookie, localStorage,sessionStorage,IndexedDB가 있다.

저장소 선택을 어떻게 하는게 적합할까? 필자는 흔히 수명·용량·동기성·보안 네 가지 관점에서 생각해본다.

인증 토큰에 대한 OWASP 권고는 HttpOnly + Secure 쿠키가 1순위이다. localStorage는 JavaScript에서 접근 가능하므로 XSS에 노출되는 순간 토큰이 그대로 털린다. 일부 보안 가이드는 액세스 토큰은 메모리에, 리프레시 토큰은 HttpOnly 쿠키에 두는 하이브리드 패턴을 권장한다. 영속적이고 민감하지 않아 자주 바뀌지 않으면 localStorage, 탭과 함께 소멸되는 데이터를 다루면 sessionStorage를 활용한다. 흔히 오프라인 캐시·대용량 데이터·파일을 다룰 때 IndexedDB를 활용한다.

Cookie와 Web Storage(local/session)는 문자열만 저장한다. 그래서 객체를 넣으려면 JSON.stringify/JSON.parse를 거쳐야 한다. 그런데 JSON에는 한계가 있다.

JSON.stringify({ when: new Date() });
// → { "when": "2026-05-19T..." } — Date becomes a string
 
JSON.stringify({ map: new Map([["a", 1]]) });
// → { "map": {} } — Map is lost entirely
 
JSON.stringify({ value: undefined });
// → "{}" — the undefined field is omitted

Date는 JSON 왕복 과정에서 문자열이 되고, Map, Set, undefined는 데이터가 사라질 수 있다. BigInt는 기본 설정에서 JSON.stringify가 TypeError를 던져 직렬화 자체가 실패한다. 외부 저장소에 객체를 넣을 때는 어떤 타입이 사라지거나 변하거나 직렬화를 실패하게 하는지를 항상 의식하고, 필요하면 직렬화 adapter를 둬야 한다.

외부 상태의 진짜 어려움은 React가 그 변화를 자동으로 감지하지 못한다는 점이다. localStorage에 값을 써도 React 컴포넌트는 리렌더링되지 않는다. 이걸 해결하는 패턴은 보통 세 가지이다.

• 커스텀 훅(useLocalStorage)으로 한 겹 감싸 외부 상태를 React state로 동기화한다. 가볍지만 직접 짜면 다중 탭·SSR·tearing 같은 모서리들을 다 다뤄야 한다.
• React 18에서 도입된 useSyncExternalStore 훅을 사용해 "React 외부 상태와 동기화할 수 있다." 이를 통해 동시성 렌더링에서 tearing이 일어나지 않도록 보장할 수 있다. localStorage·브라우저 API·외부 스토어를 잇는 표준 도구이다.
• Zustand의 persist 미들웨어, Jotai의 atomWithStorage처럼 상태 라이브러리들이 외부 저장소 연동을 1급 기능으로 제공하기에 이미 만들어진 라이브러리를 활용할 수 있다.

여기서 한 가지 안목을 더하자. 외부 상태를 React로 가져오는 순간, 동기화의 책임은 우리에게 떨어진다. 다른 탭에서 갱신되면? 서버에서 쿠키를 바꾸면? 사용자가 브라우저 개발자 도구로 localStorage를 직접 만지면? 이런 것들이 종종 가장 큰 버그의 온상이 된다.

상태 가드(State Guard)

마지막 범주는 결이 조금 다르다. 상태 자체가 아니라, 상태의 조합으로 어떤 흐름을 막거나 허용하는 로직이다.

가장 흔한 예가 인증 가드(Auth Guard) 이다.

function ProtectedRoute({ children }) {
  const { isAuthenticated, isLoading } = useAuth();
 
  if (isLoading) return <Spinner />;
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  return children;
}

여기서 isAuthenticated라는 상태가 라우팅 흐름을 통제한다. 이런 것이 바로 가드 로직이다. 인증 가드(인증된), 권한 가드(특정 역할, 권한), 플로우 가드(진입 분기), 검증 가드(단계 활성화) 등 여러 종류의 가드가 있다.

가드 로직은 한 곳에 몰리기 쉽다. 한 컴포넌트에 "로그인 안 했으면 로그인 페이지, 권한 없으면 403, 장바구니 비었으면 상품 페이지, 사용자 정지면 정지 안내" 가 다 들어가는 일이 흔하다. 가드가 비대해질수록 어떤 조건이 어디서 막혔는지를 디버깅하기 어려워진다.

좋은 가드는 한 가지만 검사한다. 결합은 Composition 형태로 한다.

<AuthGuard>
  <RoleGuard role="admin">
    <FlowGuard require={["cartHasItems"]}>
      <CheckoutPage />
    </FlowGuard>
  </RoleGuard>
</AuthGuard>

각 가드는 한 가지 결정만 내리고, 합성은 트리 구조가 책임진다. 새 가드를 추가할 때 기존 가드를 건드릴 필요가 없다.

가드를 다룰 때 막는 것보다 더 많이 생각해야할 부분은 어디로 보낼지/이후 어떻게 다룰지를 결정하는 것이다. 막기만 하고 폴백이 없는 가드는 흰 화면이나 무한 스피너로 끝난다.

가장 흔한 버그가 "가드의 비동기 검사가 끝나기 전에 보호된 콘텐츠가 잠깐 깜빡이는" 것이다. 인증 토큰 검증, 권한 조회는 대부분 비동기이고, 그 사이 isAuthenticated가 undefined나 false로 잠시 잡혀 있는 시점이 있다. 로딩 상태를 명시적으로 다루지 않으면 그 틈에 보호된 화면이 노출되거나, 로그인 페이지로 잘못 리다이렉트되거나 한다.

// Ignores loading and handles only missing data => incorrect
if (!user) return <Navigate to="/login" />;
 
// Treat loading as a first-class state (early return) => correct
if (isLoading) return <Spinner />;
if (!user) return <Navigate to="/login" replace />;
return children;

권한 가드를 짤 때 두 가지 모델이 흔히 쓰인다.

• RBAC(Role-Based Access Control): 역할 단위로 권한을 부여한다. "admin은 모든 사용자 정보를 볼 수 있다" 처럼. 단순하고 빠르지만, 역할이 세분화될수록 역할의 수가 폭발한다
• ABAC(Attribute-Based Access Control): 속성 조합으로 권한을 결정한다. "사용자가 그 게시글의 작성자이거나, 같은 팀이거나, admin인 경우" 처럼. 표현력이 크지만 구현·디버깅이 어렵다

TanStack Router의 RBAC 가이드처럼 라우터 레벨에서 beforeLoad에 가드를 박는 패턴이 권장된다. 핵심은 권한 검사를 코드에 흩뿌리지 않고 데이터(역할/권한 목록)로 표현 가능해야 한다는 것이다. 그래야 권한 정책 변경이 데이터 변경으로 끝난다.

마무리

정리해보자. 상태 관리가 어려운 이유는 라이브러리가 어려워서가 아니다. 상태에 종류가 있다는 사실을 자주 잊기 때문이고, 종류마다 다른 도구와 다른 사고방식이 필요하다는 점을 놓치기 쉽기 때문이다.

지역 상태는 가장 가까이, 전역 상태는 정말 전역인지 한 번 더 의심하고, 서버 상태는 캐시로 다루고, 폼은 도메인과 분리하고, URL은 더 적극적으로 활용하고, 외부 저장소는 책임을 의식하고, 가드는 얇게 나누어 합성하는 것. 이것이 일곱 가지 범주를 다루는 기본기이다.

그리고 그 위에서 작동하는 안목은 결국 네 가지 질문으로 압축된다.

• 이 데이터의 진실의 출처는 어디인가?
• 이건 계산할 수 있는 값인가, 정말로 저장해야 하는 값인가?
• 이 상태의 조합 중 불가능한 조합이 있는가?
• 이 상태는 정말로 이 위치에 있어야 하는가?

이 질문들을 새 화면을 짤 때마다, PR을 리뷰할 때마다, AI가 만들어준 코드를 받아볼 때마다 한 번씩 던지는 것. 그것이 안목과 느낌을 키우는 가장 확실한 길이라고 필자는 믿는다.

서두에서 말했듯, AI는 우리 옆에 오랫동안 머무를 것이다. 우리가 한 줄 한 줄 들여다보는 시간은 점점 줄어들 것이다. 그러나 그럴수록 "이 상태는 어디에 있어야 할까?" 같은 작은 질문에 답할 수 있는 감각은 더 비싸진다. AI에게 "여기에 useState 하나 더 만들어줘"라고 시키는 것은 쉽다. 그런데 그 한 줄이 우리 앱의 거미줄에 어떤 가닥을 더하는지를 아는 것은, 오직 그 코드를 읽는 사람의 안목에 달려 있다.

정답은 없다. 하지만 적어도 "상태가 뭔지 모르고 상태를 만드는 것" 과 "상태의 종류와 위치를 의식하면서 만드는 것" 사이에는 명백한 차이가 있다. 이 글을 읽는 독자 분들도 다음에 useState를 한 줄 적기 전에 한 번쯤 멈추고, "이건 어느 범주의 상태일까?"라고 물어봐 주시기를 바란다.

세금 계산이나 신고 상태 판단 같은 비즈니스 규칙이 컴포넌트와 훅, utils 에 흩어져 있어서, 규칙 하나가 바뀔 때마다 여러 파일을 찾아 고치고 있는 프론트엔드 개발자를 위한 글이다. 끝까지 읽으면 그 규칙을 React 에 의존하지 않는 순수 함수로 옮기는 방법과, 그 분리를 어디서 멈출지 판단하는 기준을 얻을 수 있다.

예시는 모두 종합소득세 계산으로 든다. 필자가 관심을 두고 있는 도메인이다.

프론트엔드에서 도메인 로직은 어디에 있어야 하는가?

답하기 전에 용어 하나를 맞춰 둔다. 이 글에서 도메인 모델은 비즈니스 개념과 그 위에서 작동하는 규칙을 함께 담은 것을 말한다. API 응답 타입처럼 데이터가 어떤 모양으로 오가는지만 정의하는 데이터 모델과는 다르다. 컴포넌트가 응답 구조에 직접 기대면 백엔드 스키마가 바뀔 때마다 프론트엔드 전체가 흔들리는 것도 이 차이 때문이다. 도메인, 도메인 모델, 도메인 오브젝트, 도메인 오브젝트 모델 네 용어가 어떻게 다른지는 도메인 용어에 따로 정리해 두었다.

소프트웨어 설계에 깊은 관심을 가지고 있는 Khalil Stemmler는 처음에 "비즈니스 로직은 프론트엔드에 속하지 않는다"고 주장했다가, 이후 입장을 "백엔드에서 아키텍처적으로 하고 있는 거의 모든 것을, 프론트엔드에서도 할 수 있고 해야 한다." 라고 수정하며 말했다.

필자도 이 입장에 동의한다. 물론 프론트엔드가 비즈니스 로직의 단일 진실 공급원(Single Source of Truth) 이 되어서는 안 된다. 그것은 백엔드의 역할이다. 하지만 프론트엔드에도 프론트엔드만의 도메인 로직이 분명히 존재한다.

"사용자가 입력한 정보에 따라 실시간으로 예상 환급액을 보여줘야 하는" 경우를 생각해보자. 이런 계산 로직이 백엔드에만 존재하게 되면, 사용자가 소득 금액을 한 글자 고칠 때마다 API를 호출해야 한다. 네트워크 왕복 시간만큼 UI가 멈추고, 입력이 빠른 사용자라면 불필요한 요청이 폭발적으로 늘어난다. debounce를 건다 해도 수백 밀리초의 지연은 "실시간 미리보기"라는 경험을 깨뜨리기에 충분하다. 결국 즉각적인 피드백이 필요한 계산은 프론트엔드가 직접 수행할 수밖에 없고, 프론트엔드에서만 수행할 수 있는 로직이 존재하게된다.

도메인 로직이 컴포넌트에 섞인 경우

종합소득세 미리보기 화면을 예로 들어보자. 사용자가 소득 정보를 입력하면 예상 세액을 실시간으로 보여주는 기능이다. 아래는 흔히 볼 수 있는, 도메인 로직과 UI 로직이 뒤섞인 코드이다

function TaxPreviewPage() {
  const [총수입, set총수입] = useState(0);
  const [경비율, set경비율] = useState(0.641); 
  const [인적공제대상인원, set인적공제대상인원] = useState(1); 
 
  const 종합소득금액 = 총수입 - 총수입 * 경비율;
 
  const 소득공제합계 = 인적공제대상인원 * 1_500_000;
  const 과세표준 = Math.max(0, 종합소득금액 - 소득공제합계);
 
  let calculatedTax = 0;
  if (과세표준 <= 14_000_000) {
    calculatedTax = 과세표준 * 0.06;
  } else if (과세표준 <= 50_000_000) {
    calculatedTax = 과세표준 * 0.15 - 1_260_000;
  } else if (과세표준 <= 88_000_000) {
    calculatedTax = 과세표준 * 0.24 - 5_760_000;
  } else if (과세표준 <= 150_000_000) {
    calculatedTax = 과세표준 * 0.35 - 15_440_000;
  } else {
    calculatedTax = 과세표준 * 0.38 - 19_940_000;
  }
 
  const 기납부세액 = 총수입 * 0.033;
  const refundOrPayment = 기납부세액 - calculatedTax;
 
  return <div>...</div>;
}

이 코드의 문제가 보이는가? "인적공제 1인당 150만원", "8단계 누진세율", "3.3% 원천징수"라는 세법에 의해 정해진 비즈니스 규칙이 React 컴포넌트 안에 직접 박혀 있다. 세법이 매년 개정되는데, 이런 규칙이 컴포넌트에 흩어져 있으면 개정 시 수정해야 할 곳을 찾아 헤매게 된다. 개발자뿐 아니라 QA팀이 다루는 E2E 시나리오가 존재한다면 테스트 비용도 만만하지 않을 것이다.

결국 이게 뷰 로직인지 비즈니스 로직인지 구분하기 어려워지고, 수많은 조건문과 커스텀 훅으로 엉키게 된다.

도메인 로직을 분리해보자.

Alex Bespoyasov의 Clean Architecture 접근법에서 핵심 원칙을 빌려오자. 도메인 로직을 프레임워크에 의존하지 않는 순수 함수로 분리하는 것이다.

도메인은 하나의 애플리케이션을 다른 애플리케이션과 구별하는 핵심이다. React에서 Angular로 옮겨도 변하지 않는 것으로 생각할 수 있다.

The domain is the core that distinguishes one application from another. You can think of the domain as something that won't change if we move from React to Angular.

위의 세금 계산 예시를 리팩토링해보자.

먼저 도메인 타입과 규칙을 정의하여 관련한 정보를 응집한다.

export interface Income {
  grossAmount: number;
  expenseRate: number;
}
 
export interface Deductions {
  personalCount: number;
  pensionPaid: number;
  additionalDeductions: number;
}
 
const PERSONAL_DEDUCTION_PER_PERSON = 1_500_000;
const WITHHOLDING_RATE = 0.033;
const TAX_BRACKETS = [
  { limit: 14_000_000, rate: 0.06, progressiveDeduction: 0 },
  /** ...구간들... **/
] as const;

그리고 도메인 로직을 순수 함수로 분리한다

앞서 소득 계산, 공제, 과세표준, 세액, 환급액 계산등의 로직을 computeFullTax 함수로 분리한다. 각 단계는 다시 작은 순수 함수로 쪼갠다. 결과 타입은 ReturnType<typeof computeFullTax>로 추론시키면 별도 인터페이스 선언이 필요 없다.

이후 컴포넌트는 도메인 로직을 "사용"만 한다

import { computeFullTax } from "../domain/tax";
 
function TaxPreviewPage() {
  const [income, setIncome] = useState<Income>({
    grossAmount: 0,
    expenseRate: 0.641,
  });
  const [deductions, setDeductions] = useState<Deductions>({
    personalCount: 1,
    pensionPaid: 0,
    additionalDeductions: 0,
  });
 
  const result = computeFullTax(income, deductions);
 
  return (
    <div>
      <IncomeForm value={income} onChange={setIncome} />
      <DeductionForm value={deductions} onChange={setDeductions} />
      <TaxResultSummary result={result} />
    </div>
  );
}

무엇이 달라졌는가?

• 8단계 누진세율 테이블(TAX_BRACKETS)이 한 곳에 모여 있어 세법 개정 시 domain/tax.ts만 수정하면 된다
• 계산 파이프라인이 computeFullTax 한 함수로 응집되어, 전체 흐름이 한눈에 보인다. (예시의 단순함을 위해 하나로 묶었지만, 실제 프로젝트에서는 소득 계산·공제 계산·세액 산출 등 목적별로 더 세분화하는 것이 적합하다.)
• 컴포넌트는 "어떻게 보여줄까"에만 집중한다. 세율이 바뀌어도 컴포넌트를 수정할 필요가 없다
• React에서 다른 프레임워크로 마이그레이션한다 해도, domain/tax.ts는 바뀌지 않는다

도메인 로직이 분리되면 테스트는 놀랍도록 단순해진다. 세금 도메인에서는 계산의 정확성이 곧 사용자의 돈이기 때문에 이 점이 특히 중요하다.

세금 관련한 계산 로직을 담은 순수 함수에는 React Testing Library도, render도, screen.getByText도 필요 없다. 입력을 넣고 출력을 확인하면 끝이다. "1,400만원 이하는 6% 세율", "과세표준 0원이면 세액도 0원", "프리랜서 3,000만원 소득의 환급액" 같은 케이스가 한 줄짜리 it으로 표현된다. 도메인 단위 테스트가 컴포넌트 분리 기준을 자연스럽게 잡아주고, 테스트 코드가 문서 역할까지 한다.

빈약한 도메인 모델(Anemic Domain Model)

앞 절에서는 계산 로직을 분리했다. 그런데 도메인 로직에는 계산 외에도 상태 전이 규칙과 권한 판단이 있다. "이 신고서를 지금 수정할 수 있나?", "제출은 가능한가?", "청구방식을 전환할 수 있는가?" 같은 질문이 그것이다. 이런 규칙을 분리하다 보면 빠지기 쉬운 함정이 하나 있는데, Martin Fowler가 이름 붙인 빈약한 도메인 모델(Anemic Domain Model) 이다.

빈약한 도메인 모델은 타입은 도메인 언어로 잘 정의해뒀는데, 그 위에서 작동하는 규칙은 도메인 바깥으로 흩어져버린 상태를 말한다. 세금 신고(Filing) 도메인을 예로 들어보자. 타입은 깔끔하다.

// types/filing.ts
export interface TaxFiling {
  id: string;
  status: "draft" | "submitted" | "reviewing" | "completed" | "amended";
  taxYear: number;
  filingType: "regular" | "late" | "amendment";
  determinedTax: number;
}

그런데 이 타입에 대한 판단·전이 규칙은 다른 곳에 박혀 있다.

// utils/filingHelpers.ts
export function canAmendFiling(filing: TaxFiling) {
  return filing.status === "completed" && filing.filingType !== "amendment";
}
 
// components/FilingDetail.tsx
function FilingDetail({ filing }: { filing: TaxFiling }) {
  // 같은 도메인 규칙을 컴포넌트 안에 다시 작성한다
  const canEdit = filing.status === "draft" || filing.status === "reviewing";
  // ...
}
 
// hooks/useSubmitFiling.ts
export function handleSubmitFiling(filing: TaxFiling) {
  if (filing.status !== "draft") return;
  // ...
}

같은 도메인 규칙이 utils, 컴포넌트, 훅 세 곳에 각자 다른 모습으로 존재한다. 이 상태에서 "청구 가능 조건이 변경됩니다"라는 요구사항이 들어오면 수정해야 할 곳을 찾아 다녀야 하고, 빠뜨린 한 곳은 사이트 어딘가에서 잘못된 판단을 내린다. Fowler는 이런 코드를 두고 "객체지향의 외피만 두른 절차적 코드와 다를 바 없다" 고 비판했다.

해법은 앞 절에서 계산 로직에 적용한 것과 동일하다. 규칙을 타입 옆에 둔다.

export interface TaxFiling {
  id: string;
  status: FilingStatus;
  taxYear: number;
  filingType: FilingType;
  determinedTax: number;
}
 
export type FilingStatus =
  | "draft"
  | "submitted"
  | "reviewing"
  | "completed"
  | "amended";
 
export type FilingType = "regular" | "late" | "amendment";
 
// 도메인 규칙은 도메인 옆에 둔다
export function canEdit(filing: TaxFiling): boolean {
  return filing.status === "draft";
}
 
export function canSubmit(filing: TaxFiling): boolean {
  return filing.status === "draft" && filing.determinedTax >= 0;
}
 
export function canAmend(filing: TaxFiling): boolean {
  return filing.status === "completed" && filing.filingType !== "amendment";
}

이제 신고 관련 규칙은 domain/filing.ts 한 곳에서 관리된다. 어떤 컴포넌트에서든 canAmend(filing)을 호출하면 되고, 규칙이 바뀌면 이 파일 하나만 수정하면 된다. 핵심은 타입과 그 위의 규칙은 한 묶음으로 인지하는 것이다. 타입만 도메인 폴더에 두고 규칙은 utils로 빼는 부분 분리는, 외양은 깔끔해 보여도 여전히 빈약한 상태다.

API 응답과 도메인 모델 사이의 변환 계층

실무에서 한 가지 더 고려해야 할 것이 있다. 백엔드 API 응답 구조와 프론트엔드의 도메인 모델이 항상 일치하지는 않는다는 점이다. 국가 기관과 연동되는 세금 서비스라면 더욱 그렇다. 국세청 홈택스 연동 데이터는 약어와 코드값으로 가득 차 있어, 프론트엔드 도메인 모델과 같은 형태로 내려올 가능성이 낮다.

이때 필요한 것이 변환 계층(Mapper) 이다. API 응답 타입을 그대로 컴포넌트까지 흘려보내는 대신, 도메인 타입으로 한 번 정제하고 나서 사용한다. 순수 함수 하나로 충분하다.

import type { Income } from "../domain/tax";
 
interface HometaxIncomeResponse {
  총수입금액: number;
  경비율: number;
  소득유형코드: string;
  // ... 나머지 약어 필드들
}
 
export function toIncome(response: HometaxIncomeResponse): Income {
  return {
    총수입_금액: response.총수입금액,
    경비_비율: response.경비율,
  };
}

이렇게 하면 API 응답의 총수입금액, 경비율 같은 약어와 코드값 기반 분류를 프론트엔드 도메인에 맞게 한 곳에서 변환한다. 소득유형코드처럼 enum으로 풀어야 하는 값은 mapper 안에 작은 lookup table을 두면 된다. 홈택스 API의 필드명이 바뀌어도 mapper 하나만 수정하면 된다.

유틸 함수와 도메인 로직

도메인 로직을 분리하다 보면 반드시 부딪히는 질문이 있다. "이거 유틸 함수 아닌가?"

예를 들어 아래 두 함수를 보자.

function formatCurrency(amount: number): string {
  return `${amount.toLocaleString()}원`;
}
 
function calculateTax(taxableBase: number): number {
  const bracket = TAX_BRACKETS.find((bracket) => taxableBase <= bracket.limit);
  return Math.floor(taxableBase * bracket.rate - bracket.progressiveDeduction);
}

formatCurrency는 숫자를 문자열로 바꾸는 순수한 표현(Presentation) 로직이다. "원"이라는 단위를 붙이고 천 단위 콤마를 찍는 것은 비즈니스 규칙이 아니라, 사용자에게 어떻게 보여줄지에 관한 것이다. 반면 calculateTax는 "8단계 누진세율 적용"이라는 세법에 근거한 비즈니스 규칙을 담고 있다. 이것은 UI가 없어도 동일하게 적용되어야 하는 도메인의 규칙이다.

필자가 실무에서 사용하는 판단 기준은 이것이다.

이 로직이 사라지면 비즈니스가 깨지는가, 화면만 깨지는가?

비즈니스가 깨진다면 도메인 로직이고, 화면만 깨진다면 표현 로직이다. 이 질문 하나로 대부분의 경계는 구분할 수 있다.

하지만 현실은 이렇게 깔끔하지 않다. 가장 까다로운 것은 도메인 로직처럼 생겼는데 실은 표현 로직인 경우이다.

아래 코드를 살펴보자. FilingStatus라는 도메인 개념을 인자로 받아 처리하기 때문에 도메인 로직으로 분류해두었다. 그런데 정말 이것이 도메인 로직일까?

// domain/filing.ts
function getStatusBadgeColor(status: FilingStatus): string {
  const colors: Record<FilingStatus, string> = {
    draft: "gray",
    submitted: "blue",
    reviewing: "yellow",
    completed: "green",
    amended: "purple",
  };
  return colors[status];
}
 
function getStatusDisplayText(status: FilingStatus): string {
  const labels: Record<FilingStatus, string> = {
    draft: "작성 중",
    submitted: "제출 완료",
    reviewing: "검토 중",
    completed: "신고 완료",
    amended: "경정청구",
  };
  return labels[status];
}

getStatusBadgeColor와 getStatusDisplayText는 FilingStatus라는 도메인 개념을 사용하지만, 하는 일은 화면 표현이다. 배지 색상이 바뀌어도 비즈니스는 전혀 깨지지 않는다. 이런 함수를 domain/filing.ts에 넣으면 도메인 모듈이 점점 비대해지고, 진짜 도메인 로직과 표현 로직이 뒤섞이게 된다.

도메인 모델과 ViewModel의 분리

이 문제를 해결하는 실용적인 방법이 있다. 같은 도메인 폴더 안에 ViewModel을 별도 파일로 분리하는 것이다. .ui.ts보다 .viewModel.ts라는 네이밍을 쓰면, MVVM 패턴의 ViewModel 개념과 자연스럽게 연결된다. "도메인 데이터를 화면에 맞게 변환하는 계층"이라는 역할이 이름에서 바로 드러나기 때문이다.

domains/
└── filing/
    ├── filing.ts              # 순수 도메인 모델 + 도메인 로직
    ├── filing.viewModel.ts    # ViewModel (표현 변환 계층)
    ├── filing.test.ts         # 도메인 로직 테스트
    └── filingMapper.ts        # API ↔ 도메인 변환

앞서 본 getStatusBadgeColor, getStatusDisplayText를 그대로 filing.viewModel.ts로 옮긴다. 추가로 getFilingTypeLabel(type: FilingType): string 처럼 신고 유형을 한국어 라벨로 풀어주는 변환들도 여기에 모인다. filing.ts는 비즈니스 규칙만, filing.viewModel.ts는 화면 표현만 책임진다.

핵심은 의존 방향이다. filing.viewModel.ts는 filing.ts를 import하지만, filing.ts는 filing.viewModel.ts를 절대 import하지 않는다. 도메인은 표현을 모르고, 표현이 도메인을 알고 있는 구조이다. 이것이 Robert C. Martin이 말한 의존성 규칙(Dependency Rule)의 축소판이라고 볼 수 있다.

필자는 함께 변경되는 파일을 같은 디렉토리에 배치해야 한다고 생각해 같은 폴더에 두었다. FilingStatus 타입에 새로운 값(예: 'rejected')이 추가되면 filing.ts와 filing.viewModel.ts 모두 수정해야 한다. 같은 폴더에 있으니 수정 범위가 한눈에 보인다.

경계와 응집

도메인 로직을 분리하는 것만큼 중요한 것이 경계를 어디에 그을 것인가이다. 필자가 실무에서 자주 마주치는 경계 판단 문제를 몇 가지 정리해보겠다.

프론트엔드에서 다루는 데이터는 대략 네 가지 출처에서 온다.

• 서버 데이터: API 응답으로 받은 것
• 파생 데이터: 서버 데이터로부터 계산된 것
• UI 상태: 화면 제어를 위한 것, 유저의 인터렉션
• 사용자 입력: 폼에서 입력 중인 것

이 네 가지를 하나의 타입에 섞으면 도메인 모델이 오염된다.

// 안티패턴: 모든 것이 섞인 타입
interface TaxFiling {
  // 서버 데이터 (도메인)
  id: string;
  status: FilingStatus;
  determinedTax: number;
 
  // 파생 데이터 (도메인)
  refundAmount: number;
  canAmend: boolean;
 
  // UI 상태 (표현)
  isExpanded: boolean;
  activeStep: number;
 
  // 임시 상태
  editingDeductions: Deduction[];
}

이 타입은 도메인 개념과 UI 상태와 임시 데이터가 한 바구니에 담겨 있다. activeStep이 바뀔 때마다 신고 도메인이 갱신되는 셈이다. (폼 단계가 바뀌는 것은 비즈니스 이벤트가 아니다)

개선 방향은 경계에 따라 타입을 분리하는 것이다. 도메인 모델은 id, status, determinedTax 같은 비즈니스 개념만, UI 상태(FilingFormViewState)는 isExpanded, activeStep 같은 화면 제어만, 폼 상태(DeductionEditForm)는 입력 중인 임시 데이터만 담는다.

이렇게 하면 각 타입이 하나의 변경 이유만 가진다. 도메인 타입은 세법이 바뀔 때만, UI 상태는 화면 설계가 바뀔 때만, 폼 상태는 입력 UX가 바뀔 때만 수정된다.

함께 변하는 것을 함께 두자

Eric Evans의 DDD에서 Aggregate(집합체) 라는 개념이 있다. "관련된 객체들의 클러스터를 하나의 단위로 다루는 것"이다. 프론트엔드에서 이 개념을 그대로 적용할 필요는 없지만, 함께 변하는 데이터와 규칙은 함께 둔다. 는 핵심 원칙은 빌려올 만하다.

세금 서비스를 예로 들면, Income(소득)과 ExpenseRate(경비율)는 항상 함께 변한다. 소득 유형이 바뀌면 적용 경비율도 바뀌고, 종합소득금액 계산도 영향을 받는다. 따라서 이것들은 하나의 파일 domain/tax.ts에 응집시킨다.

반면, TaxFiling(신고서)은 세액 계산과 별개로 변할 수 있다. 신고서의 상태 전이 규칙이 바뀌어도 세율 계산 로직은 영향을 받지 않는다. 따라서 domain/filing.ts로 분리하는 것이 맞다.

이렇게 묻자: "A가 변할 때 B도 반드시 변해야 하는가?"
  → Yes: 같은 모듈에 둔다 (Income + ExpenseRate + TaxBracket)
  → No: 분리한다 (Tax 계산 ↔ Filing 상태관리)

Class vs 함수형

여기까지 읽으면 한 가지 근본적인 질문이 떠오를 수 있다. 지금까지의 예시는 모두 interface + 순수 함수 조합이었는데, Class로 도메인을 표현하면 응집이 더 자연스럽지 않을까?

맞는 말이다. Class 기반으로 도메인을 표현하면 데이터와 행위가 하나의 객체에 묶이기 때문에, 응집이 코드 구조에서 바로 드러난다.

class TaxFilingModel {
  constructor(
    public readonly id: string,
    public readonly status: FilingStatus,
    public readonly taxYear: number,
    public readonly filingType: FilingType,
    public readonly determinedTax: number,
  ) {}
 
  canEdit(): boolean {
    return this.status === "draft";
  }
 
  canAmend(): boolean {
    return this.status === "completed" && this.filingType !== "amendment";
  }
 
  canSubmit(): boolean {
    return this.status === "draft" && this.determinedTax >= 0;
  }
}
 
const filing = new TaxFilingModel(
  "F-001",
  "completed",
  2025,
  "regular",
  547200,
);
 
filing.canAmend();

Class 기반으로 작성하면 행위가 데이터 귀속된다. 그리고 사용처에서 주어가 명확하다. filing.canAmend()는 마치 자연어를 읽는 것처럼 직관적이다. 주어(filing)와 동사(canAmend)가 명확하게 결합되어 있다. 마치 jihoon.eat('감자탕')이라고 쓰면 "지훈이가 감자탕을 먹는다"가 바로 읽히는 것과 같다.

반면 함수형 스타일에서는 이렇게 된다.

canAmend(filing);
eat("jihoon", "감자탕");

함수형은 데이터가 밖에 존재한다. 위 두가지 코드는 filing이라는 데이터를 인자로 받아서 어떤 동작을 수행한다. eat 함수는 jihoon과 감자탕이라는 데이터를 인자로 받아서 수행한다.

결과적으로 주어와 동사의 결합이 느슨해진다. canAmend라는 함수가 TaxFiling과 관련된다는 것은 파일을 열어보거나 타입 시그니처를 확인해야 알 수 있다. 같은 파일에 canAmend(filing), canEdit(filing), calculateTax(taxableBase) 같은 함수들이 섞여 있으면, 어떤 함수가 어떤 도메인에 속하는지 한눈에 파악하기 어려워질 수 있다.

그렇다면 Class를 써야 하는가?

솔직히 말하면, 답은 "상황에 따라 다르다" 이다. 하지만 필자의 경험상 React + TypeScript 환경에서는 Class가 만능이 아닌 현실적 이유들이 있다.

React 상태 관리와의 마찰

React의 상태 관리는 기본적으로 Plain Object와 가장 자연스럽게 맞물린다. useState나 useReducer는 기술적으로 어떤 값이든 담을 수 있고 Redux DevTools도 Class 인스턴스의 프로토타입을 직접 제거하지는 않는다. 하지만 Redux/Zustand의 영속화 미들웨어가 JSON으로 상태를 저장했다가 복원하면 Class 인스턴스는 JSON.stringify → JSON.parse 사이클에서 메서드와 프로토타입을 잃은 plain object가 된다. 한편 React Server Component에서 Client Component로 props를 전달하는 경계는 직렬화 가능한(serializable) 값만 지원하므로, 임의의 Class 인스턴스는 애초에 전달할 수 없다.

아래 코드를 살펴보자.

const [filing, setFiling] = useState(
  new TaxFilingModel("F-001", "draft", 2025, "regular", 0),
);

React 상태를 업데이트하는 것만으로는 filing이 TaxFilingModel 인스턴스라는 사실이 사라지지 않는다. 다만 Redux/Zustand 영속화가 JSON으로 저장·복원한 값은 메서드 없는 plain object가 될 수 있어, 무심코 호출한 filing.canAmend()가 런타임 에러로 터질 수 있다. React Server Component에서 Client Component로 넘길 때는 Class 인스턴스가 지원되는 직렬화 형식이 아니므로 전달 단계에서 막힌다.

불변성 보장의 어려움

React는 상태 변경을 참조 비교(referential equality) 를 기반으로 감지한다. Class 인스턴스의 메서드가 this.items.push(...) 같은 내부 변경을 하면 참조가 그대로라 React가 리렌더링을 트리거하지 않는다. 그래서 결국 addDeduction(item)이 return new DeductionList([...this.items, item]) 처럼 매번 새 인스턴스를 반환하도록 짜야 하는데, 이러면 Class의 이점인 "캡슐화된 상태 변경"이 무색해진다. 함수형 갱신과 별로 다르지 않은 코드가 된다.

함수형에서 응집을 확보하는 전략

그렇다면 함수형 스타일에서 eat('jihoon', '감자탕') 같은 느슨한 응집 문제를 어떻게 개선할 수 있을까? 필자가 효과적이라고 느낀 방법 세 가지를 소개한다.

모듈 네임스페이스로 응집하기

가장 직관적인 방법이다. 파일(모듈) 자체를 도메인 단위로 만들고, import 시 네임스페이스를 활용한다. 앞서 정의한 domain/filing.ts를 그대로 가져다 쓰면 된다.