토큰 효율성(Token Efficiency)

토큰 효율성이란?

토큰 효율성은 AI 코딩 도구를 활용할 때 최소한의 컨텍스트로 최대한 정확한 결과를 얻기 위한 원칙
AI가 코드를 이해하고 수정하는 데 필요한 정보를 최적화하여 생산성을 향상가능

토큰 효율성이 필요한 이유

1. Context Window 한계
   AI 모델은 한 번에 처리할 수 있는 토큰 수가 제한됨 (128K, 200K 등)
   더 많은 파일을 읽을수록 중요한 정보가 희석됨
   집중된 컨텍스트 = 더 정확한 이해

2. 응답 속도
   적은 토큰 = 빠른 처리
   개발 사이클 단축

3. 비용 효율성
   API 기반 AI 도구는 토큰당 과금
   불필요한 컨텍스트 = 불필요한 비용
   효율적인 구조 = 장기적 비용 절감

즉 AI 토큰 사용량이 많다 ≠ AI를 많이 혹은 잘 활용하고 있다

토큰 효율적인 코드 구조

파일당 단일 책임

하나의 파일 = 하나의 개념 = AI가 파일 하나만 읽어도 맥락 파악

적정 파일 크기

• 너무 작음: 50 LOC 이하
  컨텍스트 분산, 파일 간 이동 빈번, AI가 여러 파일 읽어야 함

• 적정 크기: 200-400 LOC
  단일 개념 완전 표현, AI 컨텍스트 윈도우에 적합, 이해와 수정이 용이

• 너무 큼: 500 LOC 이상
  여러 책임 혼재, 토큰 낭비, AI가 관련 없는 코드도 처리

관련 자료

• Single Responsibility Principle

• Command Pattern

• Writing a good CLAUDE.md

잘못된 예

• 하나의 기능 수정 시 전체 파일(6개 기능)을 읽어야 함 → 토큰 낭비

OrderUtils.ts
├── createOrder()
├── calculateDiscount()
├── formatOrderDate()
├── validatePayment()
├── sendOrderEmail()
└── generateInvoice()

올바른 예

• AI가 필요한 파일만 읽으면 됨

• 수정 범위가 명확

• 개별적으로 테스트 가능

├── CreateOrderUseCase.ts    # 주문 생성
├── DiscountCalculator.ts    # 할인 계산
├── DateFormatter.ts         # 날짜 포맷
├── PaymentValidator.ts      # 결제 검증
├── OrderNotifier.ts         # 알림 발송
└── InvoiceGenerator.ts      # 인보이스 생성

명시적 의존성

의존성을 명확하게 선언

잘못된 예

• 숨겨진 의존성 추적을 위해 전체 코드베이스 탐색 필요 → 대량 토큰 소모

• 테스트 시 모킹 어려움, 순환 의존성 발생 가능, 코드 재사용성 저하

class OrderService {
  createOrder() {
    const config = globalConfig;  // 어디서 왔는지 불명확
    const db = DatabaseSingleton.getInstance();  // 숨겨진 의존성
  }
}

올바른 예

• AI가 파일 상단만 보고 의존성 파악

• 필요한 인터페이스만 추가로 조회

• 수정 영향 범위 즉시 파악

import { OrderRepository } from './OrderRepository';
import { PaymentGateway } from './PaymentGateway';
import { Config } from '../config/Config';

class OrderService {
  constructor(
    private readonly orderRepository: OrderRepository,
    private readonly paymentGateway: PaymentGateway,
    private readonly config: Config
  ) {}
}

자기 설명적 코드

네이밍으로 의도를 전달, 불필요한 주석 제거

관련 자료

• Intention-Revealing Names

• Primitive Obsession

잘못된 예

• AI 관점: 암호화된 변수명(u, t, p) 해독을 위해 주석 토큰까지 읽어야 함

• 주석-코드 동기화 실패 위험

// 사용자가 프리미엄 회원인지 확인하고,
// 프리미엄이면 20% 할인을 적용
function check(u) {
  if (u.t === 'P') {
    return u.p * 0.8;
  }
  return u.p;
}

올바른 예

• 주석 토큰 절약

• AI가 함수명만으로 동작 이해

• 코드 자체가 문서 역할

function calculatePriceWithMemberDiscount(user: User): Money {
  if (user.membershipType === MembershipType.PREMIUM) {
    return user.cartTotal.applyDiscount(Percentage.of(20));
  }
  return user.cartTotal;
}

토큰 효율적인 디렉토리 구조

AI 작업 범위를 제한할 수 있는 구조
특정 디렉토리만 참고해서 작업 (e.g: admin/ 디렉토리에서 claude 실행)

예1: 도메인별 분리

서비스 확장 시 폴더 수가 증가하고, 개별 폴더 크기는 제한됨
특정 도메인에서만 작업시 다른 도메인은 확인 불필요

src/
├── employee/        # employee 작업 시 이 폴더만
│   ├── entity/
│   ├── service/
│   └── controller/
├── organization/    # organization 작업 시 이 폴더만
├── transfer/        # 새 도메인 추가 시 폴더만 증가
└── contracts/       # 도메인 간 인터페이스 (필요시만)

예2: Vertical Slice Architecture, Feature-Sliced Design

기능별로 모든 관련 코드(UI, 비즈니스 로직, 데이터 접근)를 한 폴더에
기능 하나 = 폴더 하나, 다른 기능 확인 불필요, 기능 추가 = 폴더 추가

참고: Vertical Slice Architecture Feature-Sliced Design

레퍼런스

• MIT: Legible Modular Software

• AI-Optimizing Codebase Architecture

• Simon Willison: Using LLMs for Code

• writing-a-good-claude-md