여러 차례의 코드 리뷰 과정에서 다룬 Python 패턴과 설계 판단을 주제별로 정리했다. 단순 문법 설명이 아니라, "왜 이렇게 바꿨는가"라는 근거 중심으로 기록한다. 각 패턴마다 배경 지식부터 차근차근 설명하므로, Python 기초 문법을 아는 분이라면 누구나 따라올 수 있다.

1. 타입 안전성과 Pydantic 활용​

1.1 dict → dict[str, Any] + Field(default_factory=dict)​

# 변경 전
details: dict = {}

# 변경 후
from typing import Any
from pydantic import Field
details: dict[str, Any] = Field(default_factory=dict)

무엇이 달라졌나?

두 가지가 바뀌었다.

첫 번째, dict → dict[str, Any]

dict만 쓰면 "이 안에 뭐가 들어가는지" 아무 정보가 없다. 열쇠(key)가 숫자인지 문자인지, 값(value)이 뭔지 전혀 모른다. dict[str, Any]로 바꾸면 "열쇠는 반드시 문자열(str)이고, 값은 뭐든 될 수 있다(Any)"라는 계약을 명시하는 것이다.

이렇게 하면 IDE(코드 편집기)가 자동완성을 더 잘 해주고, 타입 체커(코드의 타입 실수를 자동으로 찾아주는 도구)가 잘못된 사용을 미리 잡아낸다.

두 번째, = {} → Field(default_factory=dict)

이건 Python의 유명한 함정과 관련된다. 아래 예시를 보자:

# ⚠️ 위험한 패턴 (순수 Python 클래스에서)
class Student:
    def __init__(self, scores = []):
        self.scores = scores

a = Student()
b = Student()
a.scores.append(100)
print(b.scores)  # [100] — b도 같이 바뀐다!

= []로 기본값을 쓰면, Python은 이 리스트를 딱 한 번만 만들고 모든 인스턴스가 같은 리스트를 공유한다. A 학생의 점수를 추가했는데 B 학생의 점수도 바뀌는 버그가 생긴다.

Field(default_factory=dict)는 "새 인스턴스를 만들 때마다 새로운 빈 dict를 만들어라"는 뜻이다. Pydantic은 내부적으로 이 문제를 처리해주지만, default_factory를 명시하면 의도가 더 명확해지고, 순수 Python에서의 나쁜 습관을 방지하는 방어적 코딩이 된다.

1.2 @field_serializer — 무거운 필드 JSON 직렬화 제외​

@field_serializer("raw_data", "cached_binary", "thumbnail_bytes")
def serialize_heavy_fields(self, v: bytes | None) -> None:
    return None

왜 이렇게 했을까?

bytes는 이미지, 파일 내용 등 바이너리 데이터(0과 1의 나열)를 담는 타입이다. 이걸 JSON으로 변환하면 base64라는 형식으로 바뀌는데, 원래 크기보다 약 33% 커진다. 10MB 파일이 13MB짜리 텍스트가 되는 셈이다.

@field_serializer를 써서 return None을 하면, .model_dump_json()(모델을 JSON 텍스트로 바꾸는 메서드)을 호출할 때 해당 필드들이 null로 처리된다. 즉, 무거운 데이터는 JSON에 포함시키지 않겠다는 뜻이다.

"그러면 Field(exclude=True)를 쓰면 안 되나?"

쓸 수 있지만, 차이가 있다:

• Field(exclude=True) → 항상 제외된다. Python 코드에서 item.raw_data로 접근하는 것도 안 된다.
• @field_serializer → JSON으로 변환할 때만 개입한다. Python 코드에서는 정상적으로 item.raw_data로 접근할 수 있다.

프로그램 내부에서는 데이터를 쓰되, 외부로 보낼 때만 제외하고 싶으므로 @field_serializer가 맞다.

1.3 내부 캐시 필드까지 serializer 확장​

이후 리뷰에서 내부 캐시용 bool 필드들(is_processed, is_validated 같은)을 추가했다. bool은 true/false뿐이니 JSON으로 변환하는 데 문제가 없다. 하지만 여기서 중요한 깨달음이 있었다:

"기술적으로 직렬화가 되느냐"와 "JSON 출력에 포함돼야 하느냐"는 다른 질문이다.

이 필드들은 프로그램 내부에서만 쓰는 값이다. 외부에 보내는 JSON에 포함될 이유가 없다. 그래서 serializer를 확장했다:

@field_serializer(
    "raw_data", "cached_binary", "thumbnail_bytes",
    "is_processed", "is_validated", "is_cached",
)
def _exclude_internal_from_json(self, _v: object) -> None:
    return None

메서드 이름도 serialize_heavy_fields(무거운 필드 직렬화) → _exclude_internal_from_json(내부 필드를 JSON에서 제외)으로 바꿨다. 이름이 실제 역할을 정확히 설명해야 다른 개발자가 읽을 때 혼란이 없다.

인자 타입도 bytes | None → object로 바꿨다. 이제 bytes뿐 아니라 bool 필드도 처리하므로, 모든 타입을 받을 수 있는 object가 더 정확하다.

1.4 @field_validator — details 값 타입 제한​

@field_validator("details")
@classmethod
def _validate_details(cls, v: dict) -> dict:
    for key, value in v.items():
        if not isinstance(value, (str, int, float, bool, type(None))):
            raise ValueError(
                f"details['{key}'] 값은 str/int/float/bool/None만 허용: "
                f"{type(value).__name__}"
            )
    return v

배경: details는 dict[str, Any]로 선언했다. Any는 "아무거나 다 됨"이라는 뜻이므로, 리스트, 중첩 dict, 커스텀 객체 등 뭐든 들어갈 수 있다.

문제: 아무거나 다 넣을 수 있으면 JSON으로 변환할 때 에러가 날 수 있다. 예를 들어 커스텀 클래스의 인스턴스는 JSON으로 어떻게 바꿔야 하는지 알 수 없다. 또 데이터 구조가 중첩되면 읽는 쪽에서 파싱(해석)이 복잡해진다.

해결: @field_validator로 값의 타입을 원시 타입(문자열, 숫자, 불리언, None)으로 제한한다. 이렇게 하면:

• JSON 직렬화가 항상 안전하다 (원시 타입은 모든 JSON 라이브러리가 처리 가능)
• 데이터 구조가 flat(1단계 깊이)하게 유지되어, 모듈 간 데이터 교환이 단순해진다

1.5 model_copy — 불변 객체 업데이트 패턴​

updated_config = self.config.model_copy(update={"is_valid": is_valid})
return self.model_copy(update={"config": updated_config})

불변(Immutable) 객체란? 한번 만들면 내용을 바꿀 수 없는 객체다. 바꾸고 싶으면 새로운 복사본을 만들어야 한다. 마치 종이에 적은 글을 수정할 때, 원본에 줄 긋고 고치는 게 아니라 새 종이에 다시 쓰는 것과 같다.

model_copy(update={...})는 원본을 그대로 두고, 특정 필드만 바뀐 새 인스턴스를 만든다. 여러 모듈이 같은 모델을 공유할 때 한쪽이 수정해도 다른 쪽에 영향이 없으니 안전하다.

그런데 이 패턴이 폐기됐다!

이후 리뷰에서 메모리 최적화가 필요해졌다. 큰 바이너리 데이터(raw_data)를 빨리 메모리에서 해제해야 하는 상황이었다. 불변 패턴은 "원본은 그대로 두고 새 복사본을 만든다"이므로, 원본의 raw_data가 메모리에 계속 남아있게 된다. 즉시 raw_data = None으로 설정해서 메모리를 확보해야 하는데, 불변 패턴이 오히려 방해가 된 것이다.

결국 frozen=True(수정 불가 설정) 없이 mutable하게 쓰고 있던 모델에서 불변성을 강제하는 것은, 복잡성과 메모리 낭비만 만든 사례가 됐다.

교훈: 설계 원칙(불변성)은 좋지만, 실제 제약 조건(메모리 한계)이 우선한다. "교과서적으로 좋은 방법"이 항상 "현실에서 최선"인 것은 아니다.

2. Python 데코레이터 심화​

2.1 @property — 메서드를 속성처럼​

class AnalysisAgent(BaseAgent):
    @property
    def name(self) -> str:
        return "analysis"

agent = AnalysisAgent()
agent.name      # "analysis" — 괄호 없이 접근 가능!
agent.name()    # ❌ TypeError — 이미 property이므로 함수처럼 호출하면 에러
agent.name = "x"  # ❌ AttributeError — setter가 없으므로 변경 불가

왜 쓸까?

보통 객체의 값을 읽을 때 agent.name처럼 괄호 없이 접근한다. 그런데 이 값이 단순한 변수가 아니라 계산이 필요하거나 보호가 필요하다면?

@property를 쓰면 메서드(함수)인데 마치 일반 변수처럼 접근할 수 있다. 그리고 setter(값 변경 메서드)를 안 만들면 읽기 전용이 된다. 외부에서 agent.name = "해커"처럼 바꾸려 하면 에러가 나므로, 중요한 값을 보호할 수 있다.

2.2 @staticmethod — 클래스에 소속되지만 인스턴스 상태 무관​

# 변경 전: 모듈 레벨 함수 (파일 어딘가에 떠돌아다님)
def _validate_format(data: bytes) -> bool: ...

# 변경 후: 클래스 안에 넣음
class DataValidator:
    @staticmethod
    def _validate_format(data: bytes) -> bool: ...

self가 없다는 게 핵심이다.

보통 클래스의 메서드는 첫 번째 인자로 self(자기 자신)를 받는다. self를 통해 인스턴스의 데이터(예: self.name, self.age)에 접근한다.

@staticmethod는 self를 받지 않는다. 즉, 인스턴스의 데이터를 전혀 쓰지 않는 함수다. 그렇다면 굳이 클래스 안에 넣는 이유가 뭘까?

소속을 명확히 하기 위해서다. 모듈 레벨(파일의 최상단)에 두면 "이 함수가 누구의 것인지, 어디서 쓰이는지" 파일을 뒤져야 한다. 클래스 안에 넣으면 DataValidator._validate_format(...)처럼 소속이 코드 자체에서 드러난다.

2.3 @classmethod — 클래스 자체를 인자로​

class DataModel:
    @classmethod
    def from_path(cls, path: Path) -> "DataModel":
        return cls(file_path=str(path), file_name=path.name)

# 사용할 때
model = DataModel.from_path(Path("/data/sample.csv"))

self vs cls의 차이:

• self → 인스턴스(이미 만들어진 객체)를 가리킴
• cls → 클래스 자체를 가리킴

@classmethod는 인스턴스가 아직 없을 때, 클래스를 통해 직접 호출하는 메서드다. 위 예시에서 cls(...)는 DataModel(...)과 같다. 이런 패턴을 **팩토리 메서드(factory method)**라고 부른다 — "경로를 받아서 DataModel을 만들어주는 공장"인 셈이다.

Pydantic v2의 @field_validator에서 @classmethod가 필수인 이유도 이것이다. validator는 인스턴스가 생성되기 전에 실행되므로, self가 아직 존재하지 않는다. 그래서 cls를 받아야 한다.

2.4 @lru_cache(maxsize=1) → @cache​

from functools import cache

@cache
def get_settings() -> Settings:
    return Settings()

# 첫 호출: Settings()를 실제로 실행하고 결과를 저장
settings1 = get_settings()

# 두 번째 호출: 저장해둔 결과를 바로 반환 (Settings()를 다시 실행하지 않음)
settings2 = get_settings()

# settings1 is settings2 → True (완전히 같은 객체)

캐시(Cache)란? 한 번 계산한 결과를 저장해두고, 같은 요청이 오면 다시 계산하지 않고 저장된 결과를 돌려주는 것이다. 자주 검색하는 웹페이지를 브라우저가 저장해두는 것과 같은 원리다.

@lru_cache(maxsize=1)은 "결과 1개만 캐시한다"는 뜻이다. 그런데 get_settings()처럼 인자가 없는 함수는 결과가 항상 1개뿐이다. maxsize 제한이 무의미하므로, Python 3.9+에서 추가된 @cache(제한 없는 캐시)가 더 깔끔하다.

모듈 레벨에 settings = get_settings()를 둔 것은, 기존에 from config import settings로 사용하던 코드와의 호환성을 유지하면서도, FastAPI의 Depends(get_settings) 같은 함수형 패턴도 지원하기 위해서다.

3. 테스트 패턴: pytest & Mock​

3.1 @pytest.fixture — 테스트 준비물 자동 주입​

@pytest.fixture
def mock_parser() -> MagicMock:
    """가짜 DataParser를 만들어준다."""
    return MagicMock(spec=DataParser)

@pytest.fixture
def agent(mock_parser, mock_validator) -> AnalysisAgent:
    """가짜 의존성을 주입한 AnalysisAgent를 만들어준다."""
    return AnalysisAgent(parser=mock_parser, validator=mock_validator)

def test_analyze(agent, mock_parser):
    # pytest가 fixture 체인을 자동으로 해결한다:
    # 1. mock_parser 생성
    # 2. mock_validator 생성
    # 3. 둘을 이용해 agent 생성
    # 4. test_analyze에 agent와 mock_parser 주입
    ...

어떻게 동작하나?

@pytest.fixture는 "이 함수의 결과물을 테스트에서 재사용할 준비물로 등록하라"는 뜻이다. 테스트 함수의 매개변수 이름과 fixture 함수 이름이 같으면 pytest가 자동으로 연결해준다.

위 예시에서 test_analyze(agent, mock_parser):

• agent → agent fixture를 찾아서 실행
• agent fixture는 mock_parser와 mock_validator가 필요 → 이것들도 자동 실행
• 이 **체인(연쇄)**을 pytest가 알아서 해결해준다

추가 기능:

• scope="module" → 모듈 전체에서 1번만 생성 (기본은 매 테스트마다 새로 생성)
• yield를 쓰면 테스트 후 정리(teardown) 코드를 작성할 수 있다:

@pytest.fixture
def temp_file():
    f = open("test.tmp", "w")
    yield f              # 여기까지가 setup, 여기서 테스트 실행
    f.close()            # 테스트 끝나면 이 코드가 자동 실행 (teardown)
    os.remove("test.tmp")

3.2 MagicMock(spec=...) — 인터페이스 동기화​

# spec 없이 — 무법지대
mock = MagicMock()
mock.prse_data()        # ✅ 에러 없음! (parse_data의 오타인데 통과됨)
mock.아무거나()          # ✅ 이것도 통과됨 (존재하지 않는 메서드)
mock.xyz.abc.defg()     # ✅ 이것마저 통과됨

# spec 있으면 — 실제 클래스의 메서드만 허용
mock = MagicMock(spec=DataParser)
mock.parse_data()       # ✅ DataParser에 실제로 있는 메서드
mock.prse_data()        # ❌ AttributeError! (오타 즉시 발견)

왜 spec이 중요한가?

MagicMock()은 기본적으로 어떤 메서드를 호출해도 에러 없이 통과시킨다. 편리하지만 위험하다. 메서드 이름에 오타가 있어도 테스트가 통과해버린다.

spec=DataParser를 지정하면 mock이 DataParser 클래스의 인터페이스(어떤 메서드를 갖고 있는지)를 복제한다. 실제로 존재하지 않는 메서드를 호출하면 에러가 난다. 나중에 DataParser의 메서드 이름이 바뀌면 mock 테스트도 함께 깨지므로, 테스트와 실제 코드가 항상 동기화된다.

비슷한 create_autospec(DataParser) 대신 MagicMock(spec=DataParser)를 쓴 이유:

create_autospec은 클래스 자체를 모킹한다 (인스턴스가 아니라). 우리 코드에서는 이미 만들어진 인스턴스를 주입받는 구조이므로, 인스턴스를 흉내내는 MagicMock(spec=...)이 맞다.

3.3 assert_called_once() — 호출 검증​

# "validate 메서드가 정확히 1번 호출됐는가?"
mock_validator.validate.assert_called_once()

# "parse 메서드가 한 번도 호출되지 않았는가?"
mock_parser.parse.assert_not_called()

MagicMock은 모든 호출을 내부적으로 기록한다. 마치 CCTV처럼, 누가 언제 어떤 메서드를 호출했는지 다 알고 있다.

실전 활용 예시: 캐시에 결과가 이미 있으면 파서를 호출하지 않아야 한다. 이때 assert_not_called()로 "파서가 정말 호출되지 않았는지" 검증하면, 캐시 로직이 제대로 동작하는지 확인할 수 있다.

3.4 caplog — 로그 캡처 및 검증​

with caplog.at_level(logging.WARNING, logger="myapp.core.processor"):
    result = agent.analyze(data)

assert "파싱 실패" in caplog.text

caplog는 pytest가 기본 제공하는 fixture로, 프로그램이 남기는 로그를 캡처한다.

caplog.at_level(logging.WARNING, logger="myapp.core.processor")는 "myapp.core.processor 로거의 WARNING 레벨 이상 로그를 잡아라"는 뜻이다.

이게 왜 필요할까? 어떤 에러는 프로그램을 멈추지 않고, 로그만 남기고 계속 진행한다. 이때 "로그가 정말 남았는가?"를 테스트할 수 있어야 한다. 예를 들어 "손상된 데이터를 처리할 때 WARNING 로그가 남는가?"를 검증할 수 있다.

3.5 Pre-computed 결과 테스트 — 분기 경로 검증​

성능 최적화를 위해 "미리 계산된 결과를 bool로 저장하고, 이후 단계에서 이 결과를 재활용하는" 구조를 만들었다. 이때 분기 로직이 네 갈래로 나뉘는데, 각각을 빠짐없이 테스트해야 한다:

None은 "아직 계산되지 않았다"는 뜻이므로, 이때만 실제 처리기를 호출해야 한다. assert_not_called()와 assert_called_once()로 각 경로에서 처리기가 호출됐는지/안 됐는지를 정확히 구분한다.

4. 에러 처리 전략​

4.1 Python 예외 계층과 except Exception​

Python의 모든 예외(에러)는 나무처럼 계층 구조를 이루고 있다:

BaseException           ← 모든 예외의 최상위 부모
├── KeyboardInterrupt   ← 사용자가 Ctrl+C를 누름
├── SystemExit          ← 프로그램 종료 요청 (sys.exit())
└── Exception           ← "일반적인" 예외들의 부모
    ├── ValueError      ← 값이 잘못됨
    ├── TypeError       ← 타입이 잘못됨
    ├── FileNotFoundError ← 파일을 찾을 수 없음
    └── ...

except Exception이라고 쓰면 Exception과 그 아래 자식들만 잡는다. KeyboardInterrupt(Ctrl+C)와 SystemExit(프로그램 종료)는 잡지 않는다.

왜 이게 중요할까? 사용자가 Ctrl+C로 프로그램을 멈추려 하는데, except BaseException으로 모든 예외를 잡아버리면 프로그램이 멈추지 않는다. except Exception은 "프로그래밍 에러는 잡되, 사용자의 의도적 중단은 존중한다"는 뜻이다.

주석으로 "BaseException은 잡지 않음"을 명시하면, 미래 개발자가 "더 안전하게 하려고" BaseException으로 바꾸는 실수를 방지할 수 있다.

4.2 에러 타입 포맷팅​

# 변경 전
error=str(e)                        # "No such file or directory"

# 변경 후
error=f"{type(e).__name__}: {e}"    # "FileNotFoundError: No such file or directory"

"No such file or directory"만 보면 어떤 종류의 에러인지 바로 알기 어렵다. 네트워크 문제? 파일 시스템 문제? 권한 문제?

type(e).__name__은 에러 클래스의 이름(예: FileNotFoundError, PermissionError)을 반환한다. 이것을 에러 메시지 앞에 붙이면 에러의 종류와 상세 내용을 한 번에 볼 수 있다.

4.3 예외 타입별 분리 — 로그 기반 운영​

이 패턴은 3단계에 걸쳐 진화했다:

1단계: 뭉뚱그려 처리

except (FileNotFoundError, json.JSONDecodeError) as e:
    logger.error("DB 로드 실패: %s", e)

문제: "파일이 없는 건지, 파일은 있는데 내용이 깨진 건지" 구분이 안 된다.

2단계: logger.exception으로 변경

except (FileNotFoundError, json.JSONDecodeError) as e:
    logger.exception("DB 로드 실패")  # 스택 트레이스 포함

개선: 에러의 전체 경로(스택 트레이스)가 보이지만, 여전히 예외 종류를 구분하기 어렵다.

3단계: 타입별 분리 (최종)

except FileNotFoundError:
    logger.error(
        "DB 파일 없음 (경로: %s) — 해당 기능이 비활성화됩니다.",
        self._db_path,
    )
    return {}
except json.JSONDecodeError:
    logger.error(
        "DB JSON 파싱 오류 (경로: %s) — 데이터 파일 손상 가능",
        self._db_path,
        exc_info=True,
    )
    return {}

왜 이게 좋은가?

• "파일 없음"인지 "파일 손상"인지 로그 한 줄로 즉시 구분
• 각 에러별로 영향 범위(비활성화됩니다, 손상 가능)를 명시
• exc_info=True는 FileNotFoundError에는 불필요(원인이 명확)하고, JSONDecodeError에는 필요(어디서 파싱이 깨졌는지 보려면 스택 트레이스가 필요)

4.4 FAIL_FAST 모드 — 환경별 동작 전환​

_FAIL_FAST = os.getenv("APP_FAIL_FAST", "false").lower() == "true"

try:
    result = process(data)
except Exception as e:
    if _FAIL_FAST:
        raise  # 예외 재전파 — 프로그램 즉시 크래시
    logger.error("처리 실패: %s", e)
    result = default_value  # 프로덕션: 에러 기록 후 계속 진행

딜레마가 있다:

• 프로덕션(실제 운영): 하나의 모듈이 실패해도 나머지는 계속 돌아야 한다. 에러를 기록하고 넘어간다.
• 개발 환경: 버그를 즉시 발견해야 한다. 에러가 나면 바로 크래시시켜서 개발자 눈에 띄게 해야 한다.

환경변수 APP_FAIL_FAST를 true로 설정하면 개발 모드, false(또는 미설정)면 프로덕션 모드다. 코드를 전혀 수정하지 않고 환경변수 하나로 동작을 전환할 수 있다.

4.5 에러 reason 구체화​

# 변경 전
reason="처리 결과 없음 (워크플로우 오류)"

# 변경 후
reason="처리 결과 없음 (이전 단계 실패 후 잘못된 호출 또는 워크플로우 버그)"

변경 전 메시지를 보면 "오류가 났구나"만 알 수 있다. 변경 후 메시지를 보면 "이전 단계가 실패한 뒤 이 함수가 호출됐거나, 워크플로우 자체에 버그가 있다"는 두 가지 가능한 원인을 즉시 파악할 수 있다.

운영 환경에서 새벽 3시에 알람이 울렸을 때, "오류입니다"와 "A가 잘못됐거나 B가 잘못됐습니다"의 차이는 디버깅 시간에서 크게 드러난다.

5. 메모리 최적화와 안전성​

5.1 방어적 복사 — list(items)​

# 변경 전
result = Result(items=items)   # items 리스트를 그대로 전달

# 변경 후
result = Result(items=list(items))   # items의 복사본을 전달

핵심 개념: Python에서 리스트를 변수에 넣으면 복사가 아니라 "같은 물건을 가리키는 이름표"가 하나 더 생기는 것이다.

original = [1, 2, 3]
shared = original      # 복사가 아님! 같은 리스트를 가리킴

original.append(4)
print(shared)          # [1, 2, 3, 4] — shared도 바뀌었다!

이건 마치 같은 구글 문서를 두 사람이 공유하는 것과 같다. 한 사람이 수정하면 다른 사람에게도 바뀐 내용이 보인다.

list(items)를 하면 내용이 같은 새 리스트를 만든다. 원본과 복사본은 독립적이므로, 한쪽을 수정해도 다른 쪽에 영향이 없다. 이를 **방어적 복사(defensive copy)**라고 한다.

5.2 Lambda late binding 버그 (Critical)​

# 변경 전
fallback=(lambda: processor.process(data.raw_content))

# 변경 후
raw_content = data.raw_content  # 이 시점의 값을 로컬 변수에 저장
fallback=(lambda: processor.process(raw_content))

무슨 일이 벌어지는가?

Python의 lambda(그리고 일반 함수도)는 변수의 **값(value)**이 아니라 **이름(참조, reference)**을 캡처한다. 쉽게 말하면:

x = 10
f = lambda: print(x)  # x의 "값 10"을 저장하는 게 아니라, "x라는 이름"을 기억함

x = 20  # x의 값을 바꿈
f()     # 20 출력! (10이 아님)

lambda는 f가 만들어질 때의 x 값(10)을 기억하는 게 아니라, 실행될 때 x를 찾아가서 그때의 값(20)을 읽는다.

실전에서의 문제:

메모리 최적화를 위해 data.raw_content = None으로 큰 데이터를 해제한 뒤, 나중에 lambda가 실행되면 data.raw_content가 이미 None이 되어 있다. 프로세서에 None이 전달되면서 에러가 발생한다.

해결: lambda를 만들기 전에 raw_content = data.raw_content로 로컬 변수에 값을 미리 담아둔다. 이후 data.raw_content가 None이 되어도, 로컬 변수 raw_content는 원래 값을 그대로 갖고 있다.

5.3 원자적 초기화 — 부분 초기화 방지​

# 변경 전: 하나씩 바로 전역 변수에 할당
_parser = DataParser()        # 성공
_matcher = PatternMatcher()   # 💥 여기서 실패!
_validator = DataValidator()  # 실행 안 됨

# → 결과: _parser만 있고 _matcher, _validator는 None인 "반쪽짜리" 상태

이 상태에서 프로그램이 계속 돌면, _matcher를 쓰려는 코드에서 None을 접근하며 또 다른 에러가 발생한다. 원인 추적이 매우 어렵다.

# 변경 후: 로컬 변수에서 모두 생성한 뒤 일괄 할당
parser = DataParser()        # 성공
matcher = PatternMatcher()   # 💥 여기서 실패하면...
validator = DataValidator()  # 실행 안 됨

# → 전역 변수 _parser, _matcher, _validator는 모두 이전 값(None) 그대로
# → "전부 성공 또는 전부 실패" — 원자성 확보

_parser = parser       # 모두 성공했을 때만 여기까지 도달
_matcher = matcher
_validator = validator

로컬 변수에서 먼저 생성하므로, 중간에 실패하면 전역 변수는 건드리지 않는다.

5.4 Mutable과 In-place의 차이​

이 두 용어는 자주 혼동되지만, 다른 개념이다:

Mutable(변경 가능) — 객체의 속성이다. "이 객체는 생성 후에 내부를 바꿀 수 있는가?"

• Mutable: list, dict, set — 생성 후 추가/삭제 가능
• Immutable: tuple, str, int — 생성 후 변경 불가

In-place(제자리 연산) — 연산의 방식이다. "새 객체를 만드는가, 기존 객체를 직접 수정하는가?"

• In-place: my_list.sort() — 원본 리스트 자체를 정렬
• Not in-place: sorted(my_list) — 정렬된 새 리스트를 반환, 원본은 그대로

numbers = [3, 1, 2]

# In-place 연산
numbers.sort()         # numbers가 [1, 2, 3]으로 직접 변경됨

# Not in-place 연산
new_numbers = sorted(numbers)  # new_numbers는 [1, 2, 3], numbers는 그대로

관계: In-place 연산은 mutable 객체에서만 가능하다 (immutable은 수정 자체가 안 되니까). 하지만 mutable이라고 해서 모든 연산이 in-place인 것은 아니다 (sorted(my_list)는 mutable 리스트를 받지만, in-place가 아니다).

6. Python 관용 패턴​

6.1 bool(matches) — Pythonic 진위값 변환​

# 변경 전
return len(matches) > 0

# 변경 후
return bool(matches)

Python의 Truthiness(진위값) 규칙:

Python에서 모든 값은 True 또는 False로 평가될 수 있다:

• Falsy (거짓으로 취급): 0, "", [], {}, None, False
• Truthy (참으로 취급): 위를 제외한 모든 것

빈 리스트 []는 falsy이고, 요소가 있는 리스트 [1, 2]는 truthy다. 따라서 len(matches) > 0은 bool(matches)와 같은 의미다.

다만, 이것이 항상 좋은 것은 아니다. bool(matches)는 Python을 잘 아는 사람에게는 자연스럽지만, 조건이 복잡해지면 len(matches) > 0이 더 읽기 쉬울 수 있다. **"읽는 사람이 바로 이해하는가?"**가 기준이다.

6.2 next() — 첫 번째 매칭 요소 찾기​

# 변경 전: for 루프로 하나씩 확인
def _find_item(results, name):
    for item in results.items:
        if item.name == name:
            return item
    return None

# 변경 후: next()로 한 줄로 표현
def _find_item(results, name):
    return next((item for item in results.items if item.name == name), None)

next()는 어떻게 동작할까?

next(이터레이터, 기본값) — 이터레이터의 첫 번째 요소를 반환한다. 요소가 없으면 기본값을 반환한다.

안쪽의 (item for item in results.items if item.name == name)는 제너레이터 표현식이다. 조건에 맞는 요소를 하나씩 생성하지만, next()가 첫 번째만 가져가므로 나머지는 생성되지 않는다 (효율적).

두 번째 인자 None은 조건에 맞는 요소가 없을 때 반환할 기본값이다. 이게 없으면 StopIteration 에러가 발생한다.

결론: "컬렉션에서 조건에 맞는 첫 요소 찾기"를 표현하는 Python 관용 패턴이다. for 루프 4줄을 1줄로 줄인다.

6.3 dict 기반 O(1) 조회​

# 변경 전: 리스트에서 하나씩 찾기 — O(n)
result = _get_result(results, TaskType.VALIDATION)

# 변경 후: dict로 변환 후 키로 바로 찾기 — O(1)
result_map = {r.task_type: r for r in results}
result = result_map.get(TaskType.VALIDATION)

{r.task_type: r for r in results}는 딕셔너리 컴프리헨션이다. 리스트의 각 요소를 {키: 값} 쌍으로 변환하여 dict를 만든다.

성능 외에도 중요한 이유: 병렬로 실행된 작업의 결과 순서는 보장되지 않는다. 리스트 기반 조회는 순서에 의존할 수 있지만, dict 기반 조회는 키(task_type)로 찾으므로 순서가 바뀌어도 상관없다. 코드 구조 자체에서 "순서에 의존하지 않는다"는 의도가 드러난다.

6.4 getattr vs hasattr​

# 변경 전: 속성을 2번 조회 (있는지 확인 1번 + 실제 접근 1번)
if hasattr(obj, "resource_entries"):
    for entry in obj.resource_entries.entries:

# 변경 후: 속성을 1번만 조회
resource = getattr(obj, "resource_entries", None)
if resource is not None:
    for entry in resource.entries:

hasattr(obj, "name")은 "obj에 name이라는 속성이 있는가?"를 True/False로 반환한다. 이후 obj.name으로 다시 접근하면, 같은 속성을 2번 조회하는 셈이다.

getattr(obj, "name", None)은 "obj에서 name을 가져오되, 없으면 None을 반환하라"이다. 확인과 획득을 동시에 처리한다.

추가 이점: resource라는 짧은 변수에 담으므로, 이후 코드에서 obj.resource_entries.entries 같은 긴 이름을 반복하지 않아도 된다.

6.5 Logging에서 %s 포맷팅​

# ✅ 권장 — 로그 레벨이 꺼져 있으면 포맷팅을 건너뜀
logger.debug("파싱 실패: %s", e)

# ❌ 비효율 — 로그 레벨과 무관하게 항상 f-string을 평가함
logger.debug(f"파싱 실패: {e}")

차이점을 자세히 살펴보자:

f-string 방식(f"...")은 logger.debug()가 호출되기 전에 문자열이 먼저 완성된다. 즉, 로그 레벨이 DEBUG가 아니라서 실제로 출력되지 않을 때도 문자열 조합 작업이 수행된다.

%s 방식은 logger.debug()가 "이 로그를 출력해야 하나?" 판단한 뒤에 문자열을 조합한다. 출력하지 않을 거라면 포맷팅 자체를 건너뛴다.

한 번의 차이는 미미하지만, 반복문 안에서 수천~수만 번 호출되는 DEBUG 로그에서는 성능 차이가 누적된다.

7. 설계 판단과 match/case 동작​

7.1 룰 컴파일 실패 — 전체 중단 vs 부분 비활성화​

# 변경 전: 하나 실패하면 전체 시스템 중단
except CompilationError as e:
    raise RuntimeError(...) from e

# 변경 후: 실패한 룰만 비활성화하고 나머지는 계속 가동
except CompilationError as e:
    logger.error(
        "룰 컴파일 실패 (%s) — 해당 룰 비활성화 후 계속 진행",
        rule_type.value,
    )
    self._rules[rule_type] = None

비유: 보안 검색대에 X-ray 기계, 금속 탐지기, 폭발물 탐지기가 있다고 하자.

• 변경 전 방식: 금속 탐지기가 고장나면 → 보안 검색대 전체를 폐쇄한다. 모든 승객이 발이 묶인다.
• 변경 후 방식: 금속 탐지기가 고장나면 → 금속 탐지만 건너뛰고, X-ray와 폭발물 탐지는 계속한다. 완벽하지는 않지만 최소한의 보안은 유지된다.

여러 검증 룰을 운용하는 시스템에서는, 하나의 룰 문제로 전체가 멈추는 것보다 부분 가동이 운영상 더 합리적이다. 물론 이 판단은 도메인에 따라 다를 수 있다 — 금융 거래처럼 하나라도 검증이 빠지면 안 되는 경우에는 전체 중단이 맞다.

7.2 match/case 와일드카드 _의 함정​

match (check_a, check_b, check_c):
    case (PASS, PASS, _):     # 패턴 1: a=PASS, b=PASS, c=무엇이든
        verdict = "정상"
    case (PASS, FAIL, _):     # 패턴 2: a=PASS, b=FAIL, c=무엇이든
        verdict = "비정상"
    case _:                    # 기본 케이스: 위 패턴에 안 맞으면
        verdict = "추가 검토 필요"

와일드카드 _는 "무엇이든 매칭"이다. None도 포함한다.

이게 왜 함정일까? 두 가지 시나리오를 비교해보자:

시나리오 1: check_c가 누락됨(None)

(PASS, PASS, None) → 패턴 1의 _가 None을 매칭 → "정상" 판정

check_c를 검사하지 않았는데도 "정상"으로 판정됐다. _가 None을 잡아먹었기 때문이다.

시나리오 2: check_b가 누락됨(None)

(PASS, None, None) → 패턴 1의 b자리는 PASS여야 하는데 None → 매칭 실패
                   → 패턴 2의 b자리는 FAIL이어야 하는데 None → 매칭 실패
                   → 기본 케이스 → "추가 검토 필요"

같은 None(누락)인데, 위치에 따라 결과가 완전히 다르다. _ 자리에 있으면 조용히 넘어가고, 구체적 값이 필요한 자리에 있으면 매칭 실패가 된다.

이 발견은 실제 테스트 실행 중 기대값과 실제값이 달라서 발견됐고, 두 케이스의 동작 차이를 테스트로 문서화했다.

7.3 assert를 활용한 타입 내로잉​

if both_failed:
    assert result_a is not None and result_b is not None
    errors = [f"A: {result_a.error}", f"B: {result_b.error}"]

배경: result_a와 result_b는 타입이 Result | None이다 (결과가 있거나, 없으면 None). both_failed=True이면 논리적으로 두 결과가 모두 존재해야 한다 — 결과가 없는데 실패할 수는 없으니까.

문제: 하지만 타입 체커(mypy, pyright 같은 도구)는 이 논리를 이해하지 못한다. both_failed라는 변수가 True라고 해서 result_a가 None이 아니라는 보장은 타입 체커의 분석 범위 밖이다. 그래서 result_a.error에 "result_a가 None일 수 있다"는 경고를 띄운다.

해결: assert result_a is not None을 쓰면:

1. 타입 체커에게: "이 시점 이후로 result_a는 None이 아니다"라고 알려준다 (타입 내로잉)
2. 런타임에서: 만약 누군가 코드를 리팩토링해서 both_failed의 의미가 바뀌었는데 이 부분을 수정하지 않았다면, assert가 즉시 실패하여 버그를 잡아준다

7.4 docstring으로 오용 방지​

def compute_overall_verdict(items: list[CheckResult]) -> Verdict:
    """CheckResult 목록에서 종합 판정을 계산한다.

    overall_verdict는 로깅/디버깅/감사 목적으로 사용되며,
    최종 판정 로직은 이 값을 사용하지 않고 개별 CheckResult를 직접 조회한다.
    """

왜 이런 docstring이 필요할까?

compute_overall_verdict라는 함수 이름을 보면, "아, 이게 최종 판정을 내리는 함수구나"라고 오해하기 쉽다. 하지만 실제로 최종 판정은 다른 곳에서 개별 CheckResult를 직접 보고 내린다. 이 함수의 결과는 로그에 기록하거나 디버깅할 때만 쓴다.

docstring에 이 사실을 명시하지 않으면, 새 모듈을 만드는 개발자가 이 함수의 결과를 최종 판정 근거로 잘못 사용할 수 있다. 주석 한 줄이 미래의 버그를 예방한다.

8. ABC(추상 기본 클래스)와 에이전트 계약​

from abc import ABC, abstractmethod

class BaseAgent(ABC):
    @property
    @abstractmethod
    def name(self) -> str:
        """Agent 식별자. 반드시 구현해야 한다."""
        ...

    @abstractmethod
    def analyze(self, data) -> AnalysisResult:
        """데이터를 분석한다. 반드시 구현해야 한다."""
        ...

동작 방식:

1. ABC를 상속하면 이 클래스는 직접 인스턴스를 만들 수 없다:

agent = BaseAgent()  # ❌ TypeError: Can't instantiate abstract class

2. @abstractmethod가 붙은 메서드를 하위 클래스에서 반드시 구현해야 한다:

class SearchAgent(BaseAgent):
    # name과 analyze를 구현하지 않으면...
    pass

agent = SearchAgent()  # ❌ TypeError: Can't instantiate abstract class
                        # SearchAgent with abstract methods analyze, name

3. 모든 추상 메서드를 구현하면 정상 작동:

class SearchAgent(BaseAgent):
    @property
    def name(self) -> str:
        return "search"

    def analyze(self, data) -> AnalysisResult:
        # 실제 분석 로직
        ...

agent = SearchAgent()  # ✅ 정상 생성

@property와 @abstractmethod를 함께 쓴 이유:

@property만 쓰면 "이 값은 읽기 전용이다"이고, @abstractmethod만 쓰면 "이 메서드를 반드시 구현하라"이다. 둘을 합치면 **"이 읽기 전용 속성을 반드시 제공하라"**는 계약이 된다. 모든 Agent가 고유한 name을 반드시 갖도록 강제할 수 있다.

마무리​

여러 차례의 코드 리뷰에서 다룬 패턴들은 크게 세 가지 원칙으로 수렴한다:

1. 명시적으로 표현하라 — 타입 어노테이션, 주석, docstring, 환경변수 네이밍 모두 "왜 이렇게 했는가"를 코드에 남기는 행위다. dict보다 dict[str, Any]가, str(e)보다 f"{type(e).__name__}: {e}"가 더 많은 정보를 전달한다.

2. 실제 제약 조건이 설계 원칙보다 우선한다 — 불변성 패턴은 좋지만, 메모리 최적화가 필요하면 in-place 변경으로 전환한다. 교과서적 방법이 현실의 요구와 충돌하면, 현실이 이긴다.

3. 테스트는 문서다 — match/case 와일드카드의 None 매칭, pre-computed 결과의 분기 동작 같은 엣지 케이스를 테스트로 기록하면, 미래 개발자에게 코드가 직접 설명한다. "왜 이렇게 동작하는가?"에 대한 답이 테스트 코드에 있다.

AI 코딩 도구가 하나만 있으면 좋겠지만, 현실에서는 세 가지 도구를 적재적소에 배치해야 최고의 결과를 얻을 수 있습니다. 이 글은 Claude Code, Codex, Gemini CLI를 오케스트라처럼 조율하는 실전 전략을 다룹니다.

TL;DR (한 줄 요약)​

• Claude Code = 팀장. 설계하고, 판단하고, 중요한 코드를 직접 쓴다
• Codex = 실행력 좋은 팀원. 여러 작업을 동시에 처리하고, 코드 리뷰도 잘한다
• Gemini CLI = 분석가. 방대한 자료를 읽고 정리해서 보고서를 만든다
• 핵심: "뭐가 더 좋냐"가 아니라 "이 작업에는 뭐가 맞냐"

들어가며: 왜 AI 도구를 여러 개 써야 할까?​

프로그래밍을 도와주는 AI 도구가 정말 많아졌습니다. Anthropic의 Claude Code, OpenAI의 Codex, Google의 Gemini CLI... 각각 "최고의 AI 코딩 도구"를 자처합니다.

그런데 한 가지 도구만 쓰면 안 되는 걸까요?

비유로 설명하면 이렇습니다.

축구팀을 생각해보세요. 메시가 아무리 뛰어나도 혼자서 골키퍼, 수비수, 미드필더, 공격수를 다 할 수는 없습니다. 각 포지션에 맞는 선수가 있어야 팀이 잘 굴러갑니다.

AI 코딩 도구도 마찬가지입니다:

• Claude Code는 메시 같은 존재입니다. 가장 똑똑하고, 복잡한 판단을 잘 합니다. 팀의 핵심이지만, 모든 걸 혼자 하면 비효율적입니다.
• Codex는 체력 좋은 미드필더입니다. 여러 군데를 동시에 뛰어다니며 일을 처리합니다.
• Gemini CLI는 데이터 분석관입니다. 상대팀 경기 영상 100개를 밤새 분석해서 보고서를 만들어줍니다.

이 세 도구를 각각의 강점에 맞게 배치하면, 혼자 쓸 때보다 훨씬 빠르고 정확하게 일할 수 있습니다.

이 글에서는 어떤 상황에서 어떤 도구를 쓸지, 그리고 도구 사이에 어떻게 일을 넘길지를 구체적으로 알려드리겠습니다.

이 글의 약속: 사실과 의견을 구분합니다​

이 글에서는 세 가지 태그를 사용합니다:

왜 이렇게 구분할까요? AI 도구 세계는 변화가 빠르기 때문입니다. "이 도구가 이걸 할 수 있다"는 말이 다음 달에는 틀릴 수 있습니다. 그래서 확실한 사실과 변할 수 있는 정보를 명확히 나누는 것이 중요합니다.

Part 1: 세 도구 소개 — 각각 뭘 잘하나?​

Claude Code (Anthropic) — "가장 똑똑한 팀장"​

Claude Code는 Anthropic이 만든 AI 코딩 도구입니다. 생각하는 능력이 가장 뛰어나서, 복잡한 설계 결정이나 보안 관련 코드를 맡기기에 적합합니다.

어디서 쓸 수 있나? (서피스)​

[FACT] Claude Code는 정말 다양한 곳에서 쓸 수 있습니다:

• 터미널(CLI): 명령어로 직접 대화
• VS Code / JetBrains: 에디터 안에서 바로 사용
• 데스크톱 앱: 독립 앱으로 실행
• 웹(claude.ai/code): 브라우저에서 사용
• 모바일(iOS): 출퇴근 중에도 확인
• Slack: 팀 채팅에서 @Claude로 호출
• GitHub Actions: CI/CD 파이프라인에서 자동 실행 — Overview

[REC] 이렇게 서피스가 넓다는 건 큰 장점입니다. 예를 들어 "Slack에서 코드 리뷰 요청을 던지고, 출퇴근길에 모바일로 결과를 확인하고, GitHub Actions에서 자동으로 품질 검사를 돌리는" 워크플로우가 가능합니다.

프로젝트 설정: CLAUDE.md​

[FACT] 프로젝트 폴더에 CLAUDE.md 파일을 만들어두면, Claude Code가 세션을 시작할 때마다 자동으로 읽습니다. /init 명령어로 자동 생성할 수도 있습니다. — Overview

쉽게 말해 **"이 프로젝트는 이렇게 생겼고, 이런 규칙을 따라야 해"**라고 적어놓는 설명서입니다. 매번 "우리 프로젝트는 Python으로..."라고 반복할 필요가 없어집니다.

Skills — "전문 기술 카드"​

[FACT] .claude/skills/ 폴더에 스킬 파일을 만들어두면, Claude Code가 특정 상황에서 자동으로 또는 수동으로 꺼내 쓸 수 있습니다. — Skills

RPG 게임에서 캐릭터에게 기술을 장착하는 것과 비슷합니다. "코드 리뷰 스킬", "테스트 생성 스킬", "배포 스킬" 같은 것들을 미리 만들어두고, 필요할 때 호출하는 거죠.

[FACT] 주요 옵션:

• context: fork → 메인 작업을 방해하지 않고 따로 실행 (독립된 작업 공간)
• agent → 어떤 종류의 AI 에이전트가 실행할지 지정 (탐색용, 계획용, 범용 등)
• allowed-tools → 이 스킬이 사용할 수 있는 도구를 제한 (안전장치) — Skills

Sub-agents — "전문가 팀 구성"​

[FACT] .claude/agents/ 폴더에 에이전트를 정의하면, 메인 Claude Code가 전문가를 고용해서 일을 시키는 것처럼 작동합니다. — Sub-agents

예를 들어:

• 탐색 에이전트 (model: haiku) — 저렴하고 빠른 모델로 코드베이스를 탐색
• 코드 리뷰 에이전트 (model: sonnet) — 중간 성능의 모델로 코드 리뷰
• 메인 세션 (Opus) — 가장 똑똑한 모델로 복잡한 판단

이렇게 하면 비싼 Opus 모델을 아끼면서도 효율적으로 일할 수 있습니다.

[FACT] Sub-agent는 독립된 공간에서 실행되고, 완료되면 요약만 메인에 돌려줍니다. 그래서 메인 대화가 지저분해지지 않습니다. — Sub-agents

Hooks — "자동 품질 검사 장치"​

Hooks는 **"어떤 일이 일어나면 자동으로 이것을 실행해라"**라는 규칙입니다.

[FACT] 주요 이벤트:

• 세션 시작/종료 시: 환경 점검, 정리 작업
• 도구 사용 전/후: 코드를 쓰기 전에 린트 검사, 쓴 후에 테스트 실행
• 작업 완료 시: 빌드 결과물 확인 — Hooks reference

[FACT] 가장 강력한 포인트: PreToolUse 훅이 권한 시스템보다 우선합니다. 즉, "이 코드는 절대 쓰지 마"라는 규칙을 걸어놓으면, Claude Code가 아무리 쓰려고 해도 차단됩니다. — Hooks guide

이건 공장의 안전장치와 같습니다. 기계가 아무리 빨리 돌아가도, 위험한 상황에서는 자동으로 멈추는 거죠.

그 밖의 기능들​

• [FACT] Plugins: 스킬 + 에이전트 + 훅을 하나로 묶어서 claude plugin install로 설치. 마켓플레이스도 있습니다. — Plugins
• [FACT] Agent SDK: 프로그램에서 Claude Code를 호출할 수 있는 도구. CI/CD 파이프라인에 통합 가능. — Agent SDK
• [FACT] 자동 메모리: 작업하면서 배운 것을 자동으로 기록하고, 다음에 다시 떠올립니다. — Changelog
• [VAR] Agent Teams: Lead + Teammates 구조로 여러 에이전트가 협업. 아직 연구 프리뷰 단계라 정식 기능은 아닙니다. — Agent Teams

Codex (OpenAI) — "체력 좋은 만능 실행자"​

Codex는 OpenAI가 만든 AI 코딩 도구입니다. 여러 작업을 동시에 처리하는 능력과 end-to-end로 작업을 완수하는 능력이 뛰어납니다.

핵심 모델: GPT-5.3-Codex​

[FACT] GPT-5.3-Codex (2026년 2월 5일 출시)는 단순한 "코딩 모델"이 아니라 **"범용 에이전트 모델"**입니다. 코드 작성뿐 아니라 터미널 명령어 실행, 문서 작성, 배포 파이프라인 관리까지 처음부터 끝까지(end-to-end) 혼자 해냅니다. — Introducing GPT-5.3-Codex

이전 버전(5.2)과 비교하면:

[FACT] 이 모든 걸 이전보다 더 적은 토큰(= 더 적은 비용)으로 달성합니다. — Introducing GPT-5.3-Codex

핵심 변화: 오케스트레이션에서 Codex의 역할이 "시킨 것만 하는 일꾼"에서 **"독립적으로 판단하고 실행하는 엔지니어"**로 격상되었습니다.

[FACT] 또한 실시간 스티어링 기능이 추가되었습니다. 작업이 끝날 때까지 기다리지 않고, 진행 중인 작업에 실시간으로 질문하거나 방향을 바꿀 수 있습니다. — Introducing GPT-5.3-Codex

이건 마치 택시를 탔을 때 "가던 길 말고 여기서 우회전해주세요"라고 말할 수 있는 것과 같습니다. 예전에는 목적지까지 가서야 "아 여기 말고요..."라고 말할 수 있었는데, 이제는 중간에 경로를 바꿀 수 있는 거죠.

모델 라인업​

Codex에는 여러 모델이 있고, 용도에 따라 골라 쓸 수 있습니다:

GPT-5.3-Codex       → "메인 엔진". 복잡한 구현, 터미널 작업, 장시간 태스크
GPT-5.3-Codex-Spark → "경량 엔진". 실시간 프로토타이핑, 일상 편집. 1000+ tokens/sec [VAR: 연구 프리뷰]
GPT-5.2-Codex       → "리뷰 전문가". 코드 리뷰에 특화된 훈련을 받은 모델

[FACT] GPT-5.3-Codex-Spark는 Cerebras 하드웨어에서 초당 1000개 이상의 토큰을 생성합니다. 정말 빠릅니다. — Introducing GPT-5.3-Codex-Spark

Codex의 킬러 기능: Worktree & Cloud​

Worktree는 Codex의 가장 독특한 기능입니다.

[FACT] Git worktree를 기반으로 완전히 독립된 작업 공간을 만듭니다. 한 에이전트가 A 기능을 만드는 동안, 다른 에이전트는 B 기능을 만들 수 있습니다. 서로 간섭하지 않습니다. — Worktrees

이건 마치 평행 우주 같은 겁니다. 같은 코드에서 출발하지만, 각각 다른 세계에서 작업하다가 나중에 합칩니다.

[FACT] Cloud 모드에서는 GitHub 연동 클라우드 환경에서 백그라운드로 작업이 돌아갑니다. --attempts 1-4 옵션을 쓰면 같은 문제를 최대 4가지 방법으로 풀어보고 비교할 수 있습니다(best-of-N). — Cloud environments, CLI features

코드 리뷰: Codex의 숨은 강점​

[FACT] GPT-5.2-Codex는 코드 리뷰에 특화된 훈련을 받았습니다. 일반적인 코딩 모델과는 다르게, "이 코드에서 뭐가 잘못됐는지" 찾는 능력이 특별히 강화되어 있습니다. — Introducing GPT-5.2-Codex

리뷰 방법도 여러 가지입니다:

• [FACT] CLI에서: /review 명령어로 로컬에서 바로 리뷰 (코드를 수정하지 않고 읽기만 함) — CLI features
• [FACT] GitHub PR에서: @codex review를 댓글에 쓰면 PR을 자동 리뷰. P0(심각)/P1(중요) 등급으로 이슈를 분류합니다. — Code Review
• [FACT] 포커스 리뷰: @codex review for security regressions처럼 특정 관점을 지정할 수 있습니다. — Code Review

자동화 기능​

• [FACT] Automations: 반복 태스크를 스케줄링해서 백그라운드에서 자동 실행 — App features
• [FACT] Autofix CI: CI가 실패하면 자동으로 수정 시도 — Codex home
• [FACT] @codex 멘션: GitHub 이슈에 @codex를 태그하면 자동으로 Cloud 태스크가 생성됩니다 — Changelog

어디서 쓸 수 있나?​

[FACT] Codex App (macOS), CLI, VS Code/Cursor/Windsurf, 웹(Codex Cloud), iOS, Slack, Linear, GitHub. — Codex home

프로젝트 설정: AGENTS.md​

Claude Code의 CLAUDE.md와 비슷하게, Codex는 AGENTS.md를 읽습니다.

[FACT] 글로벌 설정(~/.codex/AGENTS.md)과 프로젝트 설정(repo root)을 병합하며, 더 구체적인 쪽(하위 디렉토리)이 우선합니다. — AGENTS.md guide

Gemini CLI (Google) — "방대한 자료를 소화하는 분석가"​

Gemini CLI는 Google이 만든 AI 코딩 도구입니다. 엄청나게 긴 문서를 한 번에 읽고 분석하는 능력이 최고입니다.

핵심 모델: Gemini 3 Pro​

[FACT] Gemini 3 Pro는 1M(100만) 토큰 컨텍스트를 지원합니다. 64K 출력. — Vertex AI docs

"100만 토큰"이 얼마나 큰지 감이 안 올 수 있는데, 대략 책 10권 분량입니다. 프로젝트의 소스 코드 수백 개 파일을 한 번에 읽고 분석할 수 있다는 뜻입니다.

비교하면:

• Claude Code: 최대 1M (베타, 조건부) [VAR]
• Codex(GPT-5.2): 400K [FACT]
• Gemini 3 Pro: 1M (안정적) [FACT]

모델 라인업​

Gemini 3 Pro   → "대용량 분석기". 1M 컨텍스트, 대규모 분석/리서치
Gemini 3 Flash → "빠른 스캐너". 200K 컨텍스트, 빠른 탐색/요약/CI 파이프라인

[VAR] 현재 3 Pro/Flash 모두 preview 상태입니다. GA(정식 출시)되면 모델 ID가 바뀔 수 있습니다.

킬러 기능: Headless Mode​

이것이 Gemini CLI의 가장 독특한 강점입니다.

[FACT] --output-format text/json/jsonl 옵션으로 프로그래밍 가능한 출력을 생성합니다. — Headless

무슨 말이냐면, 다른 AI 도구들은 "사람이 읽기 좋은" 형태로 결과를 주는데, Gemini CLI는 "다른 프로그램이 바로 처리할 수 있는" 형태로 줄 수 있다는 겁니다.

실전 예시:

# 코드 변경사항을 자동 요약
git diff | gemini -p "이 변경사항을 한국어로 요약해줘" --output-format json

# 릴리스 노트 자동 생성
git log --since="2026-02-01" | gemini -p "릴리스 노트로 정리해줘" --output-format text

# 대규모 코드베이스 분석
gemini --model gemini-3-pro -p "전체 코드의 의존성 구조와 순환 참조를 분석해줘" --output-format text > report.md

CI/CD 파이프라인에 넣으면, 커밋할 때마다 자동으로 변경사항 요약을 만들거나, 릴리스할 때마다 릴리스 노트를 생성할 수 있습니다.

어디서 쓸 수 있나?​

[FACT] CLI, VS Code, JetBrains, Positron IDE. — Docs

[REC] Claude Code나 Codex에 비해 서피스가 좁습니다 (웹/모바일/Slack/데스크톱 앱 없음). 그래서 "대규모 분석 + 파이프라인 자동화" 역할에 집중시키는 게 좋습니다.

그 밖의 기능들​

• [FACT] 오픈소스: 전체 소스 코드가 공개되어 있습니다. — GitHub
• [FACT] Google Search 내장: 웹 검색 결과를 바로 활용할 수 있습니다.
• [FACT] Extensions: 스킬 + MCP + 훅 + 에이전트를 하나로 묶은 번들. GitHub URL로 설치. — Extensions
• [FACT] Token caching: 같은 컨텍스트를 반복 사용할 때 비용을 절약합니다.

프로젝트 설정: GEMINI.md​

[FACT] 프로젝트 루트에 GEMINI.md를 놓으면 됩니다. .geminiignore로 특정 파일을 제외할 수도 있습니다. — Docs

Part 2: 한눈에 비교 — 누가 뭘 잘하나?​

병렬 실행 (여러 작업을 동시에)​

승자: Codex. Worktree 기반 격리가 가장 성숙하고, Cloud에서 백그라운드 실행 + best-of-N까지 지원합니다.

자동화 (알아서 검사하고 처리하기)​

승자: 용도에 따라 다름. 품질 게이트는 Claude Code, 워크플로우 자동화는 Codex, CI/CD 파이프라인은 Gemini CLI.

코드 리뷰​

승자: Codex. GPT-5.2-Codex가 코드 리뷰에 특화 훈련을 받았고, CLI/GitHub PR 양쪽에서 모두 쓸 수 있습니다.

확장성/커스터마이징​

승자: Claude Code. 커스터마이징할 수 있는 요소가 가장 많습니다.

Part 3: 라우팅 룰 — "이 작업은 누구한테 맡길까?"​

이제 핵심입니다. 어떤 작업이 왔을 때 어떤 도구에 맡길지 결정하는 규칙입니다.

4가지 기준(축)으로 판단하며, 위에 있는 축이 우선합니다.

축 1: Risk (위험도) → Claude Code​

"이거 잘못하면 큰일나는 작업"은 Claude Code에게.

이런 작업이 해당됩니다:

• 아키텍처 설계 결정 (시스템 구조를 바꾸는 것)
• 보안 민감 구현 (로그인, 결제, 비밀키 관리)
• 복잡한 멀티파일 리팩토링 (파일 여러 개를 동시에 바꾸는 것)
• 미묘한 논리 버그 디버깅 (재현이 어려운 버그)
• 새 기능의 핵심 인터페이스 설계

왜 Claude Code?

두 가지 이유입니다:

1. [FACT] Hooks로 위험한 행동에 자동 제동을 걸 수 있습니다. 예를 들어 "production 데이터베이스에 접근하는 코드를 쓰면 무조건 차단"같은 규칙을 강제할 수 있습니다. — Hooks guide

2. [FACT] Sub-agent에 모델/도구/권한을 분리할 수 있어서, 보안 감사 에이전트에는 "코드 읽기만 가능, 수정 불가"같은 제한을 걸 수 있습니다. — Sub-agents

비유하면, 중요한 수술은 가장 숙련된 의사에게 맡기고, 수술실에 안전장치(Hooks)를 최대로 가동하는 것과 같습니다.

축 2: Input Size (분석할 양) → Gemini CLI​

"읽어야 할 게 산더미인 작업"은 Gemini CLI에게.

이런 작업이 해당됩니다:

• 파일 50개 이상을 동시에 분석
• 대용량 로그 파일 요약
• 전체 코드베이스의 의존성/패턴/순환 참조 스캔
• 기술 옵션 비교 리서치 (Google Search 활용)

왜 Gemini CLI?

• [FACT] Gemini 3 Pro의 1M 컨텍스트는 현재 가장 안정적인 대용량 입력 지원입니다. — Vertex AI docs
• [FACT] Headless 모드의 JSON/JSONL 출력으로, 분석 결과를 다른 도구가 바로 사용할 수 있습니다. — Headless

비유하면, 서류 1000장을 분석해야 할 때, 속독 능력이 가장 뛰어난 분석가에게 맡기는 것과 같습니다.

[REC] 분석 결과는 항상 파일로 저장합니다:

저장 위치: .ai/notes/10_analysis.md
포맷: TL;DR / Findings / Evidence(file:line) / Recommendations / Next actions

축 3: Parallelism (동시 실행) → Codex​

"동시에 여러 개를 해야 하는 작업"은 Codex에게.

이런 작업이 해당됩니다:

• 같은 패턴을 3개 이상의 파일에 반복 적용
• 독립적인 작업 2개 이상을 동시 진행
• Cloud 백그라운드 실행 (장시간 마이그레이션)
• 여러 가지 풀이를 비교하고 싶을 때 (--attempts로 best-of-N)
• 터미널/OS 작업이 포함된 end-to-end 태스크 (배포, 환경 설정)
• 빠른 프로토타이핑 (실시간 스티어링 활용)

왜 Codex?

• [FACT] Worktree로 Git 기반 완전 격리가 가능합니다. — Worktrees
• [FACT] Cloud에서 백그라운드로 병렬 실행하며, best-of-N(최대 4)을 지원합니다. — CLI features
• [FACT] GPT-5.3-Codex는 Terminal-Bench 2.0에서 77.3%를 달성했습니다. 터미널/OS 작업을 처음부터 끝까지 혼자 완수하는 능력이 최고입니다. — Introducing GPT-5.3-Codex

비유하면, 공사 현장에서 여러 팀이 동시에 각각의 구역을 작업하는 것과 같습니다. A팀은 1층, B팀은 2층, C팀은 3층을 동시에 짓되, 서로 간섭하지 않습니다.

축 4: Repetition (반복) → Codex + Gemini​

"같은 종류의 일을 반복하는 작업"은 Codex와 Gemini에게.

Codex가 담당하는 반복:

• PR 코드 리뷰: /review (로컬) 또는 @codex review (GitHub)
• 반복 태스크: Automations (매일 에러 분석, 변경 리포트)
• CI 실패 자동 수정: Autofix CI
• 이슈에서 자동 작업: @codex 멘션 → Cloud 태스크

Gemini가 담당하는 반복:

• CI/CD 파이프라인 내 자동 분석 (headless)
• 커밋마다 변경사항 자동 요약
• 릴리스마다 릴리스 노트 자동 생성

라우팅 요약 다이어그램​

새 작업이 도착하면 이 순서대로 판단합니다:

새 작업 도착
    │
    ├─ 설계/보안/복잡한 판단이 필요? ──→ Claude Code (메인)
    │
    ├─ 파일 50개+ 분석이 필요? ────────→ Gemini CLI (Headless)
    │                                     → .ai/notes/ 에 저장
    │                                     → Claude Code가 읽고 활용
    │
    ├─ 여러 작업을 동시에? ────────────→ Codex (Worktree/Cloud)
    │
    ├─ 터미널/OS 작업 end-to-end? ─────→ Codex (GPT-5.3)
    │
    ├─ 빠른 프로토타이핑? ─────────────→ Codex (Spark, 실시간 스티어링)
    │
    ├─ 코드 리뷰? ─────────────────────→ Codex (GPT-5.2, 리뷰 특화)
    │                                     + Claude Code (아키텍처 리뷰)
    │
    ├─ 반복 자동화? ───────────────────→ Codex Automations
    │                                     + Gemini Headless (CI/CD)
    │
    └─ 위에 해당하지 않는 나머지 전부? ──→ Claude Code (기본값)

우선순위: Risk > Input Size > Parallelism > Repetition

축이 겹치면 위에 있는 축이 우선합니다. 예를 들어, "보안 관련 대규모 리팩토링"은 Risk(축 1)에 해당하므로 Claude Code가 맡습니다.

Part 4: 라우팅 브리핑 — "누가 뭘 할지 먼저 정하기"​

언제 브리핑이 필요한가?​

모든 작업에 브리핑이 필요한 건 아닙니다.

브리핑 필요 없음 (그냥 시작):
  - 파일 하나 버그 수정
  - 작은 기능 추가
  - 단순한 코드 리뷰
  - 일상적인 디버깅
  → Claude Code에서 바로 시작하면 됨

브리핑 필요 (먼저 계획 세우기):
  - 도구 2개 이상이 관여할 것 같을 때
  - 작업이 반나절 이상 걸릴 것 같을 때
  - 도구 사이에 일을 넘기는 과정(핸드오프)이 있을 때
  - 처음 해보는 유형의 작업일 때

브리핑은 어떻게 하나?​

**코디네이터는 Claude Code(Opus)**가 담당합니다. 가장 똑똑한 모델이 라우팅 결정을 주도합니다.

① 작업 쪼개기
   "이 작업을 완수하려면 어떤 하위 작업들이 필요한가?"

② 각 작업을 4축에 대입
   - 위험한 작업? → Claude Code
   - 분석할 양이 많은 작업? → Gemini CLI
   - 동시 실행 가능한 작업? → Codex
   - 반복 작업? → Codex + Gemini

③ 각 도구 안에서 모델 선택
   - Claude: Opus (복잡) / Sonnet (일상) / Haiku (탐색)
   - Codex: 5.3 (복잡) / 5.3-Spark (빠른) / 5.2 (리뷰)
   - Gemini: 3 Pro (대규모) / 3 Flash (경량)

④ 실행 순서와 넘기는 조건 정하기
   "누가 먼저 하고, 결과물은 뭐고, 다음 도구가 시작하려면 뭐가 준비돼야 하나?"

⑤ 기록
   → .ai/notes/00_routing-decision.md 에 저장

실제 예시: OAuth2 인증 기능 추가​

# Routing Decision — OAuth2 인증 추가
Date: 2026-02-13

## 하위 작업 & 라우팅

| # | 하위 작업 | 도구 | 모델 | 이유 |
|---|-----------|------|------|------|
| 1 | 코드베이스 영향 분석 | Gemini CLI | 3 Pro | 파일 80개 이상 분석 필요 (축 2) |
| 2 | 인터페이스 설계 | Claude Code | Opus | 아키텍처 결정 (축 1) |
| 3 | 병렬 구현 (3 모듈) | Codex | 5.3 | 독립적인 3개 작업 동시 (축 3) |
| 4 | 코드 리뷰 | Codex | 5.2 | 리뷰 특화 모델 (축 4) |
| 5 | 최종 통합 리뷰 | Claude Code | Opus | 보안/확장성 검증 (축 1) |

## 실행 순서
Gemini (분석) → Claude (설계) → Codex (병렬 구현) → Codex (리뷰) → Claude (최종 리뷰)

## 넘기는 조건
- 1→2: 분석 보고서 완성 + 근거(file:line) 포함
- 2→3: 인터페이스 확정 + 완료 조건 명시
- 3→4: PR 생성 + 테스트 통과
- 4→5: 심각한 이슈(P0) 없음

[REC] 브리핑이 작업보다 무거우면 안 됩니다. 5분 이내에 결정하세요. 자주 나오는 패턴이면 "패턴 A 적용"이라고만 적어도 충분합니다.

Part 5: 실전 워크플로우 패턴 4가지​

패턴 A: 새 기능 개발 (풀 사이클)​

가장 일반적인 패턴입니다. 분석 → 설계 → 구현 → 리뷰의 전체 사이클을 거칩니다.

① Gemini CLI — 코드베이스 전체 분석
   "현재 인증 시스템의 구조, 확장 포인트, 리스크를 분석해줘"
   → .ai/notes/10_analysis.md 에 저장

② Claude Code — 설계 + 핵심 구현
   분석 보고서를 참조해서 OAuth2 모듈을 설계하고 핵심 코드를 구현
   Hooks로 자동 린트/테스트/권한 검사

③ Codex (Worktree) — 병렬 구현
   Thread 1: 테스트 작성
   Thread 2: 기존 엔드포인트에 미들웨어 적용
   Thread 3: 데이터베이스 마이그레이션 스크립트
   (세 작업이 동시에 진행!)

④ Codex — 코드 리뷰 (GPT-5.2 리뷰 특화)
   GitHub PR에서 @codex review for security regressions

⑤ Claude Code — 최종 아키텍처 리뷰
   "이 PR이 확장성/보안 관점에서 적절한지 검토해줘"

패턴 B: 대규모 리팩토링​

코드 구조를 크게 바꿔야 할 때 사용합니다.

① Gemini CLI — 영향 범위 분석
   1M 컨텍스트로 전체 코드베이스를 읽고, 어디가 영향받는지 분석

② Claude Code — 전략 수립 + 핵심 인터페이스 변경
   가장 중요하고 위험한 부분을 직접 처리

③ Codex Cloud — 나머지 파일 마이그레이션
   best-of-3로 여러 방법을 시도하고, 가장 좋은 것을 선택

④ Gemini CLI — 크로스 검증
   변경된 전체 코드를 다시 읽어서 동시성 문제나 엣지케이스 확인

패턴 C: 크로스 검증 (관점 분리)​

중요한 코드 변경을 여러 관점에서 검증할 때 사용합니다.

[REC] 핵심은 **"같은 질문을 2개 모델에"가 아니라 "각자 다른 관점으로"**입니다:

Codex:  diff 기반으로 버그/보안 취약점/테스트 누락 확인 (/review)
Gemini: 엣지케이스/성능 문제/의존성 충돌/운영 리스크 확인 (headless 스캔)
Claude: 아키텍처 일관성/설계 의도 부합/향후 리팩터 방향 검토 (subagent)

같은 코드를 보지만 각자 다른 안경을 끼고 보는 겁니다.

패턴 D: 반복 자동화​

매일/매 커밋/매 PR마다 자동으로 돌아가는 루틴입니다.

Codex Automations:
  - 매일: 에러 로그 분석 → 수정 PR 자동 생성
  - PR마다: @codex review 자동 트리거
  - 이슈 생성 시: @codex → Cloud 태스크 자동 생성

Gemini Headless (CI/CD 파이프라인):
  - 커밋마다: git diff를 읽어서 변경사항 자동 요약
  - 릴리스마다: git log를 읽어서 릴리스 노트 자동 생성

Claude Code Hooks:
  - 코드 수정 후: 자동 포매팅 + 린트 (command hook)
  - 작업 완료 시: 테스트 통과 여부 자동 검증 (agent hook)
  - 배포 완료 시: 빌드 결과물 존재 확인 (command hook)

Part 6: 모델이 업데이트되면 어떻게 하나?​

AI 모델은 계속 발전합니다. 지금은 "Claude가 추론 최강"이지만, 내일 GPT-6가 나오면 달라질 수 있습니다. 그래서 정기적으로 라우팅 규칙을 재검토하는 프로세스가 필요합니다.

언제 재검토하나?​

즉시 재검토 (새 모델 출시 시):
  - Anthropic: Claude 새 모델 (예: Opus 5)
  - OpenAI: Codex 새 모델 (예: GPT-5.4-Codex)
  - Google: Gemini 새 모델 (예: Gemini 3.5 Pro)

정기 재검토 (3개월마다):
  - 모델이 안 바뀌어도, 실제 사용 경험을 바탕으로 재평가

재검토 프로세스 (약 반나절)​

① 스펙/벤치마크 수집 (1시간)
   공식 발표와 벤치마크를 비교

② 라우팅 근거 검증 (30분)
   - 축 1: Claude가 여전히 추론 최강?
   - 축 2: Gemini가 여전히 대용량 컨텍스트 최고?
   - 축 3: Codex가 여전히 병렬/end-to-end 최고?
   - 축 4: 리뷰/자동화 최적 도구는?

③ 실제 태스크로 비교 (2-4시간)
   같은 작업을 새/구 모델로 실행해서 비교

④ 문서 업데이트 (30분)
   라우팅 룰 변경 여부를 결정하고, 이 문서를 갱신

라우팅이 뒤집히는 시나리오​

지금의 라우팅은 4가지 핵심 가정 위에 세워져 있습니다. 이 가정이 무너지면 라우팅도 바뀌어야 합니다:

가정 1: "Claude가 추론 최강"
  → 무너지는 조건: 경쟁 모델이 주요 벤치마크에서 Opus를 확실히 초월
  → 대응: Risk 축의 기본 도구를 재평가

가정 2: "Gemini가 대용량 컨텍스트 최적"
  → 무너지는 조건: Claude/Codex가 1M+ 컨텍스트를 안정적으로 지원
  → 대응: Input 축에서 Gemini의 독점 근거가 사라짐

가정 3: "Codex가 병렬/end-to-end 최강"
  → 무너지는 조건: Claude Agent Teams가 정식 출시 + Worktree급 격리 지원
  → 대응: Parallel 축에서 Claude가 Codex를 대체할 수 있는지 평가

가정 4: "도구 사이의 연결은 파일로"
  → 무너지는 조건: MCP/A2A로 도구 간 실시간 연동이 안정화
  → 대응: 파일 기반 핸드오프에서 실시간 연동으로 전환

Part 7: 프로젝트 설정하기​

추천 폴더 구조​

project-root/
├── CLAUDE.md          ← 프로젝트의 "헌법". 모든 규칙의 원본
├── AGENTS.md          ← Codex용 설정 (CLAUDE.md를 참조)
├── GEMINI.md          ← Gemini용 설정 (CLAUDE.md를 참조)
│
├── .claude/
│   ├── agents/        ← Claude Code 전문가 팀
│   │   ├── code-reviewer.md   (model: sonnet)
│   │   ├── security-auditor.md (읽기전용 도구만)
│   │   └── explorer.md        (model: haiku, 저비용 탐색)
│   └── skills/        ← Claude Code 기술 카드
│       ├── repo-scout/SKILL.md  (코드베이스 스캔)
│       ├── test-gen/SKILL.md    (테스트 생성)
│       └── deploy/SKILL.md      (배포 워크플로우)
│
├── .gemini/
│   └── settings.json
│
├── .ai/               ← 도구 사이의 "공유 게시판"
│   ├── routing.md     ← 라우팅 룰 요약 (A4 한 장)
│   ├── handoff.md     ← 일 넘기기 템플릿
│   └── notes/         ← 분석/결정/태스크 기록 (.gitignore에 추가)
│       ├── 00_routing-decision.md
│       ├── 10_analysis.md
│       ├── 20_decisions.md
│       └── 90_handoff.md
│
└── .gitignore         ← .ai/notes/ 포함

핵심 규칙: **CLAUDE.md가 Single Source of Truth(유일한 진실의 원천)**입니다. AGENTS.md와 GEMINI.md는 "CLAUDE.md를 참조하라"고만 적고, 규칙을 복사하지 않습니다. 복사하면 나중에 불일치가 생기기 때문입니다.

각 설정 파일 예시​

CLAUDE.md (프로젝트의 "헌법")​

# Project: 내 서비스

## Tech Stack
- Python 3.12, FastAPI, SQLAlchemy 2.0
- uv + ruff + ty + pytest
- PostgreSQL, Redis

## Conventions
- src/ 레이아웃
- Type hints 필수
- 함수 20-50줄, 단일 책임
- Explicit over Clever (영리한 코드보다 명확한 코드)
- 에러 처리: 구체적 예외, 절대 bare except 금지
- 시크릿 하드코딩 금지

## Commands
- Format: `uv run ruff format .`
- Lint:   `uv run ruff check .`
- Type:   `uv run ty check`
- Test:   `uv run pytest`

## Do NOT
- print() 디버깅 금지 (logging 사용)
- Any 타입 금지
- 테스트 없는 기능 금지

AGENTS.md (Codex용)​

# Instructions

CLAUDE.md의 컨벤션을 따른다.

## Working agreements
- 파일 수정 후 반드시 린트 + 타입체크 + 테스트 실행
- 새 의존성 추가 전 확인 요청
- 커밋 메시지: conventional commits (feat/fix/refactor/test/docs)

## Review guidelines
- 보안 취약점 (SQL injection, 인증 우회, 시크릿 노출): P0 (치명적)
- 타입 힌트 누락: P1 (중요)
- bare except: P1
- 테스트 누락 (핵심 로직): P1

GEMINI.md (Gemini용)​

# Context

이 프로젝트의 컨벤션과 아키텍처는 CLAUDE.md를 참조하라.
중복 복사 금지 — CLAUDE.md가 Single Source of Truth.

## Model Policy
- 대규모 분석/리서치: Gemini 3 Pro (1M 컨텍스트)
- CI/CD 파이프라인/빠른 요약: Gemini 3 Flash (200K)

## Output Format (분석 작업 시)
### TL;DR → Findings → Evidence(file:line) → Recommendations → Next Actions

## Save Location
분석 결과는 `.ai/notes/` 에 마크다운으로 저장.

.ai/handoff.md (일 넘기기 템플릿)​

도구 사이에 일을 넘길 때 이 형식을 씁니다:

# Handoff Template

## Goal
(한 줄: 무엇을 달성해야 하는가)

## Context
- Source tool: (이전에 누가 했나)
- Source artifacts: (이전 도구가 만든 파일 경로)
- Related files: (소스 코드 경로)
- Constraints: (제약 조건)

## Deliverables
- [ ] (산출물 1)
- [ ] (산출물 2)

## Acceptance Criteria
- [ ] 린트 통과
- [ ] 타입체크 통과
- [ ] 테스트 통과

## Non-goals
- (명시적으로 하지 말 것)

Part 8: 비용 관리 — 똑똑하게 돈 쓰기​

AI 도구는 사용량에 따라 비용이 발생합니다. 모델이 비쌀수록 좋은 결과를 내지만, 모든 작업에 가장 비싼 모델을 쓸 필요는 없습니다.

[REC] 가격은 수시로 변하므로 "얼마"라고 단정하지 않고, 정책으로 관리합니다.

정책 1: 작업 난이도에 따라 모델을 나누자​

쉬운 작업 (탐색/요약/스캔)
  → 가장 저렴한 모델
  → Gemini 3 Flash, Claude Haiku, GPT-5.3-Codex-Spark

보통 작업 (일상 구현/디버깅)
  → 중간 모델
  → Claude Sonnet, GPT-5.3-Codex, Gemini 3 Pro

어려운 작업 (복잡한 설계/판단)
  → 최고 모델 (여기에만 투자!)
  → Claude Opus, GPT-5.3-Codex (장시간 에이전틱)

이건 마치 이동할 때 교통수단을 고르는 것과 같습니다. 옆 편의점 갈 때는 걸어가고(Haiku), 시내 출퇴근은 지하철(Sonnet), 해외 출장은 비행기(Opus)를 타는 거죠.

정책 2: Claude Code에서 Sub-agent 모델 분리​

[FACT] Claude Code 서브에이전트에 model: 필드로 모델을 지정할 수 있습니다. — Sub-agents

탐색 에이전트 (explorer.md)      → model: haiku   (저렴하고 빠름)
코드 리뷰 에이전트 (reviewer.md) → model: sonnet  (균형)
메인 세션                         → Opus           (복잡한 판단만)

[REC] 이 분리만으로 Opus 토큰 소비를 50% 이상 줄일 수 있습니다. 코드베이스 탐색 같은 단순 작업을 Haiku에게 맡기면, Opus는 진짜 중요한 판단에만 집중할 수 있습니다.

정책 3: Codex 모델도 용도별로​

GPT-5.3-Codex       → 복잡한 구현, 장시간 태스크, 터미널/OS 작업
GPT-5.3-Codex-Spark → 빠른 반복, 프로토타이핑, 일상 디버깅 [VAR: 연구 프리뷰]
GPT-5.2-Codex       → 코드 리뷰 전용

[FACT] GPT-5.3-Codex는 이전 모델 대비 25% 빠르고, 더 적은 토큰으로 동일 성과를 달성합니다. — Introducing GPT-5.3-Codex

정책 4: 주간 비용 리뷰​

• [REC] 매주 모델별 사용량을 확인합니다
• [REC] Opus 사용이 과도하면 Sonnet으로 전환할 수 있는지 검토합니다
• [REC] 저렴한 모델(Gemini 3 Flash, Haiku 등)로 처리 가능한 작업에 고급 모델을 쓰고 있지 않은지 확인합니다

Part 9: 최종 정리​

세 줄 요약​

5가지 핵심 원칙​

1. 파일이 API — 도구 사이에 일을 넘길 때는 .ai/notes/에 마크다운이나 JSON을 쓴다. 도구끼리 직접 대화하지 않고, 파일을 통해 소통한다.

2. CLAUDE.md = Single Source of Truth — 프로젝트 규칙은 CLAUDE.md에 한 번만 쓴다. AGENTS.md와 GEMINI.md는 "CLAUDE.md를 참조하라"고만 적는다.

3. [FACT]와 [VAR]을 엄격히 구분 — 베타/프리뷰 기능에 의존할 때는 반드시 대안을 준비한다.

4. 비용은 정책으로 관리 — 금액을 단정하지 말고, "이 난이도면 이 등급 모델"이라는 정책을 세운다.

5. 강점 극대화 — 세 도구의 약점을 보완하려 하지 말고, 각자의 강점을 극대화하는 방향으로 조합한다.

Last updated: 2026-02-13 Primary sources: code.claude.com/docs, developers.openai.com/codex, geminicli.com/docs

노트북 덮었는데 3시간짜리 작업이 날아간 적 있나요? SSH 연결이 끊겼는데 서버에서 돌리던 스크립트가 중단된 적은요? tmux를 쓰면 이런 일은 다시는 일어나지 않습니다.

TL;DR​

• tmux는 터미널을 "저장"할 수 있게 해주는 도구
• 노트북을 덮어도, SSH가 끊겨도, 작업이 그대로 살아있음
• 화면 분할로 여러 작업을 동시에 볼 수 있음
• AI 코딩 도구(Claude Code 등)와 함께 쓰면 생산성이 크게 올라감

tmux가 뭔가요?​

tmux는 "Terminal Multiplexer"의 줄임말입니다.

이름이 어렵게 느껴지지만, 하는 일은 단순합니다:

터미널 창을 "저장"하고, 나중에 다시 열 수 있게 해주는 도구

비유로 설명해볼게요.

게임 세이브 포인트​

게임을 하다가 저녁밥 먹으러 가야 할 때, 세이브하고 나가죠? 나중에 돌아오면 정확히 그 지점부터 다시 할 수 있습니다.

tmux는 터미널의 세이브 포인트입니다:

• tmux 없이: 터미널을 닫으면 → 하던 작업 다 사라짐 (세이브 없이 게임 끈 것)
• tmux 있으면: 터미널에서 나가도 → 작업이 계속 돌아감 → 돌아오면 이어서 할 수 있음

언제 쓰면 좋을까?​

설치하기​

# macOS (Homebrew가 설치되어 있다면)
brew install tmux

# Ubuntu / Debian
sudo apt install tmux

# 설치 확인
tmux -V

핵심 개념: 세션, 윈도우, 패인​

tmux에는 세 가지 개념이 있습니다. 건물에 비유하면 이해하기 쉽습니다:

건물(Session)
├── 방 1(Window) "코딩"
│   ├── 책상 왼쪽(Pane): 에디터
│   └── 책상 오른쪽(Pane): 터미널
└── 방 2(Window) "서버"
    └── 책상(Pane): 서버 로그

가장 중요한 포인트: 세션은 내가 보고 있지 않아도 계속 존재합니다. 게임을 세이브하고 나간 것과 같아요.

5분 만에 배우는 기본 사용법​

Step 1: 세션 만들기​

# "dev"라는 이름의 세션 만들기
tmux new -s dev

이렇게 하면 tmux 세션 안으로 들어갑니다. 화면 아래에 초록색 상태바가 보이면 성공!

Step 2: 화면 분할하기​

tmux의 모든 단축키는 prefix 키를 먼저 누르고, 그 다음에 명령 키를 누릅니다.

기본 prefix는 Ctrl+b입니다.

Ctrl+b 누르고 손 떼고 → % 누르기 = 좌우 분할
Ctrl+b 누르고 손 떼고 → " 누르기 = 상하 분할

좌우 분할하면 이렇게 됩니다:

┌──────────────────┬──────────────────┐
│                  │                  │
│  왼쪽 패인        │  오른쪽 패인      │
│  (원래 터미널)     │  (새로 생긴 터미널) │
│                  │                  │
└──────────────────┴──────────────────┘

Step 3: 패인 사이 이동​

Ctrl+b → 방향키(←→↑↓)

왼쪽 패인에서 오른쪽 패인으로 가려면: Ctrl+b → →

Step 4: 세션에서 나가기 (Detach)​

Ctrl+b → d

이게 핵심입니다! 세션에서 나가도 안에서 돌리던 작업은 계속 실행됩니다.

노트북을 덮어도, WiFi가 끊겨도, 세션은 살아있어요.

Step 5: 세션에 다시 붙기 (Attach)​

# 세션 목록 보기
tmux ls

# "dev" 세션에 다시 붙기
tmux a -t dev

나갔던 그 화면, 그 상태 그대로 돌아옵니다!

전체 흐름 예시​

# 1. 세션 만들고
tmux new -s dev

# 2. 화면 분할하고 코딩 중...
# (Ctrl+b → %)

# 3. 점심 먹으러 감
# (Ctrl+b → d)

# 4. 점심 먹고 돌아와서
tmux a -t dev
# → 점심 전 화면 그대로!

필수 단축키 모음​

모든 단축키는 Ctrl+b(prefix)를 먼저 누르고, 그 다음 키를 누릅니다.

세션 관련​

윈도우 (탭) 관련​

패인 (화면 분할) 관련​

스크롤 (복사 모드)​

설정 파일로 더 편하게 쓰기​

tmux의 기본 설정은 좀 불편합니다. ~/.tmux.conf 파일을 만들어서 개선할 수 있어요.

아래는 제가 추천하는 설정입니다:

# ===========================================
# 기본 설정
# ===========================================

# 마우스 지원 (클릭, 스크롤, 크기 조절 모두 가능!)
set -g mouse on

# 256 컬러 (색상이 제대로 나오게)
set -g default-terminal "screen-256color"
set -sa terminal-overrides ",xterm-256color:RGB"

# 스크롤 버퍼 늘리기 (기본 2000줄 → 50000줄)
set -g history-limit 50000

# ESC 키 딜레이 제거 (vim 사용자 필수)
set -sg escape-time 0

# 윈도우/패인 번호를 1부터 시작 (0은 키보드 왼쪽 끝이라 불편)
set -g base-index 1
setw -g pane-base-index 1

# 윈도우 닫으면 번호 자동 재정렬
set -g renumber-windows on

# ===========================================
# 키 바인딩
# ===========================================

# 설정 파일 다시 불러오기 (prefix + r)
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# 직관적인 화면 분할 (| 좌우, - 상하)
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# 새 윈도우도 현재 경로에서 열기
bind c new-window -c "#{pane_current_path}"

# vim 스타일 패인 이동 (hjkl)
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# 패인 크기 조절 (대문자 HJKL)
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

# ===========================================
# 보기 좋은 상태바
# ===========================================

set -g status-position bottom
set -g status-style "bg=#1a1b26,fg=#a9b1d6"
set -g status-left "#[fg=#7aa2f7,bold] #S "
set -g status-right "#[fg=#565f89] %H:%M #[fg=#7aa2f7] #h "
set -g status-left-length 30
set -g status-right-length 50

# 활성 윈도우 강조
setw -g window-status-current-style "fg=#7aa2f7,bold"
setw -g window-status-current-format " #I:#W "
setw -g window-status-format " #I:#W "

# 패인 테두리 색상
set -g pane-border-style "fg=#3b4261"
set -g pane-active-border-style "fg=#7aa2f7"

# ===========================================
# 복사 모드 (vi 스타일)
# ===========================================

setw -g mode-keys vi

# macOS 클립보드 연동 (tmux 3.2+)
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"
bind -T copy-mode-vi Enter send -X copy-pipe-and-cancel "pbcopy"

# Linux라면 아래 주석 해제 (xclip 필요)
# bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard"

설정 적용 방법:

# 파일 저장 후, tmux 안에서
tmux source-file ~/.tmux.conf

# 또는 위 설정을 적용했다면 prefix + r

AI 코딩에 tmux 활용하기​

AI 코딩 도구(Claude Code 등)를 쓸 때 tmux는 특히 강력합니다.

기본 레이아웃: 2패인​

# 한 줄로 세팅 완료
tmux new -s dev \; \
  split-window -h -p 50 \; \
  send-keys -t 1 'claude' Enter \; \
  select-pane -t 0

┌──────────────────┬──────────────────┐
│ 왼쪽              │ 오른쪽            │
│                  │                  │
│ 일반 터미널       │ Claude Code      │
│ (git, 테스트 등)  │ (AI 대화)        │
│                  │                  │
└──────────────────┴──────────────────┘

왼쪽에서 git이나 테스트를 돌리면서, 오른쪽에서 Claude Code와 대화하는 구조입니다.

확장 레이아웃: 3패인​

tmux new -s dev \; \
  split-window -h -p 60 \; \
  split-window -v -p 30 \; \
  send-keys -t 1 'claude' Enter \; \
  select-pane -t 0

┌──────────────────┬──────────────────┐
│                  │ Claude Code      │
│ 메인 터미널       │ (AI 대화)        │
│                  │                  │
│ (코딩, git 등)   ├──────────────────┤
│                  │ 로그/테스트 출력   │
│                  │ (실시간 모니터링)  │
└──────────────────┴──────────────────┘

셸 함수로 자동화하기​

매번 저 긴 명령어를 칠 필요 없이, 함수를 만들어두면 됩니다.

~/.zshrc 또는 ~/.bashrc에 추가하세요:

# AI 코딩 세션을 한 방에 시작
aidev() {
  local session="${1:-dev}"

  # 이미 세션이 있으면 그냥 붙기
  if tmux has-session -t "$session" 2>/dev/null; then
    tmux attach -t "$session"
    return
  fi

  # 새 세션 생성 (왼쪽 40%, 오른쪽 60% Claude)
  tmux new-session -d -s "$session" -n code
  tmux split-window -h -p 60 -t "$session:code"
  tmux send-keys -t "$session:code.1" 'claude' Enter

  # 로그용 두 번째 윈도우
  tmux new-window -t "$session" -n logs

  # 코드 윈도우의 왼쪽 패인 선택
  tmux select-window -t "$session:code"
  tmux select-pane -t 0

  tmux attach -t "$session"
}

이제 터미널에서 이렇게만 치면 됩니다:

aidev                  # "dev" 세션 시작
aidev stock-screener   # 프로젝트별 세션

SSH + tmux: 원격 작업의 핵심​

tmux가 가장 빛나는 순간은 SSH로 원격 서버에 접속할 때입니다.

문제 상황​

나 (노트북) --SSH--> 서버 (작업 중)

         WiFi 끊김!

나 (노트북) --X--> 서버 (작업 중단됨!)

SSH 연결이 끊기면 서버에서 돌리던 프로세스도 같이 죽습니다. 6시간짜리 모델 학습이 WiFi 때문에 날아갈 수 있어요.

해결: tmux​

나 (노트북) --SSH--> 서버의 tmux 세션 (작업 중)

         WiFi 끊김!

나 (노트북) --X      서버의 tmux 세션 (혼자 잘 돌아감!)

         WiFi 복구!

나 (노트북) --SSH--> 서버의 tmux 세션 (아까 이어서!)

실전 사용법​

# 1. SSH 접속
ssh myserver

# 2. tmux 세션 만들기
tmux new -s work

# 3. 오래 걸리는 작업 시작 (모델 학습, 빌드 등)
python train.py

# 4. 집에 갈 시간! 세션에서 나가기
# Ctrl+b → d

# 5. 다음 날 출근해서 다시 접속
ssh myserver
tmux a -t work
# → 학습이 잘 돌아가고 있음!

SSH 한 줄로 tmux 세션 붙기​

# -A 옵션: 세션이 있으면 붙고, 없으면 새로 만듦
ssh -t myserver "tmux new-session -A -s dev"

SSH 설정 최적화​

~/.ssh/config에 이 설정을 추가하면 연결이 더 안정적입니다:

Host myserver
    HostName 123.456.789.0
    User leo
    # 30초마다 "나 살아있어" 신호 보내기
    ServerAliveInterval 30
    ServerAliveCountMax 3
    # SSH 연결 재사용 (재접속이 빨라짐)
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600

# 모든 호스트에 기본 적용
Host *
    ServerAliveInterval 30
    ServerAliveCountMax 3

# 소켓 디렉토리 만들기 (한 번만)
mkdir -p ~/.ssh/sockets

알아두면 좋은 고급 기능​

프로젝트마다 세션 분리​

# 프로젝트별로 세션을 만들면 깔끔합니다
tmux new -s stock-screener
tmux new -s blog
tmux new -s side-project

# Ctrl+b → s 로 세션 간 전환 (트리 뷰)

여러 서버에 같은 명령 동시 실행​

여러 패인을 열어놓고 동시에 같은 명령을 칠 수 있습니다:

# tmux 명령 모드에서 (Ctrl+b → :)
:setw synchronize-panes on     # 동시 입력 켜기
:setw synchronize-panes off    # 끄기

배포할 때 여러 서버에 같은 명령을 실행하는 데 유용합니다.

패인을 새 윈도우로 분리​

작업하다 보면 패인을 독립된 윈도우로 빼고 싶을 때가 있습니다:

Ctrl+b → !    # 현재 패인을 새 윈도우로 분리

로그 캡처​

패인에 출력된 내용을 파일로 저장할 수 있습니다:

# Ctrl+b → : 로 명령 모드 진입 후
:capture-pane -S -3000         # 최근 3000줄 캡처
:save-buffer ~/tmux-log.txt    # 파일로 저장

자주 겪는 문제와 해결법​

"sessions should be nested" 에러​

tmux 안에서 다시 tmux를 실행하려 할 때 나오는 에러입니다.

# 해결: 다른 세션으로 전환
tmux switch-client -t other-session

마우스 스크롤이 안 될 때​

~/.tmux.conf에 마우스 설정이 있는지 확인하세요:

set -g mouse on

색상이 이상할 때​

# ~/.tmux.conf에 추가
set -g default-terminal "screen-256color"
set -sa terminal-overrides ",xterm-256color:RGB"

macOS에서 클립보드 복사가 안 될 때​

tmux 3.2 이상이면 기본적으로 동작합니다. 안 되면:

# ~/.tmux.conf에 추가
set -s set-clipboard on

매일 쓰는 tmux 워크플로우​

하루 전체 흐름을 정리하면 이렇습니다:

# 아침: 세션 시작 (기존 세션이 있으면 그대로 붙음)
aidev                           # 또는 tmux a -t dev

# 작업 중
Ctrl+b → 방향키                  # 패인 간 이동
Ctrl+b → z                      # 패인 확대/축소
Ctrl+b → c                      # 새 윈도우 (새 탭)
Ctrl+b → 0-9                    # 윈도우 전환

# 점심: 세션 나가기 (작업은 계속 돌아감)
Ctrl+b → d

# 오후: 다시 붙기
tmux a -t dev

# SSH 원격 작업
ssh -t server "tmux a -t work"

# 퇴근: detach만 하면 됨 (세션 죽이지 않음!)
Ctrl+b → d

빠른 참조 카드​

가장 많이 쓰는 것들만 모았습니다. 이것만 외우면 tmux의 80%를 쓸 수 있습니다:

세션:  tmux new -s NAME   세션 만들기
       tmux a -t NAME     세션 붙기
       tmux ls            세션 목록
       Ctrl+b → d         세션 나가기 (detach)

윈도우: Ctrl+b → c         새 윈도우
       Ctrl+b → 0-9       윈도우 전환
       Ctrl+b → ,         이름 변경

패인:  Ctrl+b → %         좌우 분할
       Ctrl+b → "         상하 분할
       Ctrl+b → 방향키     패인 이동
       Ctrl+b → z         패인 확대/복원
       Ctrl+b → x         패인 닫기

스크롤: Ctrl+b → [         스크롤 모드
       q                  스크롤 나가기

tmux는 처음에 단축키가 많아 어렵게 느껴지지만, 위의 10개 정도만 외우면 충분합니다. 나머지는 쓰다 보면 자연스럽게 외워져요.

가장 중요한 세 가지만 기억하세요:

1. tmux new -s 이름 — 세션 만들기
2. Ctrl+b → d — 나가기 (세션은 살아있음!)
3. tmux a -t 이름 — 다시 붙기

이 글은 Claude Code Plugin 만들기 시리즈의 첫 번째 편입니다. Plugin이 무엇인지, 왜 필요한지, 그리고 어떤 구성 요소로 이루어져 있는지 알아봅니다.

TL;DR​

• Plugin은 Claude Code에 커스텀 기능을 추가하는 확장 시스템
• Skills(배경 지식), Commands/Skills(슬래시 명령어), Hooks(자동 규칙), Agents(전문가 팀) 4가지로 구성
• plugin.json 매니페스트 하나로 패키징하여 팀과 공유 가능
• 프로젝트별 .claude/ 설정과 달리, Plugin은 여러 프로젝트에서 재사용 가능

들어가며: 반복 설명이 이렇게 싫다고?​

Claude Code를 쓰다 보면 정말 좋은 AI 비서를 얻은 것 같은 기분이 듭니다. 코드 리뷰도 해주고, 버그도 찾아주고, 심지어 리팩토링까지 도와줍니다.

그런데 한 가지 문제가 있습니다. 매번 같은 설명을 반복해야 한다는 것입니다.

"우리 프로젝트는 Python으로, 들여쓰기는 4칸으로, 변수명은 snake_case로..."

이런 말을 매번 반복하다 보면 지칩니다. 마치 새로 온 팀원에게 매일 같은 컨벤션을 설명하는 것처럼요.

그렇다면 이렇게 하면 어떨까요? 처음 한 번만 매뉴얼을 작성해놓고, 그 다음부터는 매뉴얼을 참고하게 하는 겁니다. Claude Code Plugin은 바로 이 역할을 합니다.

Plugin이란? AI에게 주는 업무 매뉴얼​

새로 온 팀원이 첫 날부터 일을 잘할 리가 없습니다.

• "코드 스타일은 뭐야?"
• "테스트는 어떻게 돌려?"
• "커밋 메시지 규칙이 있어?"
• "위험한 작업은 뭐야?"

이 모든 걸 매번 설명하는 건 비효율적입니다. 하지만 매뉴얼이 있다면?

Claude도 똑같습니다. 우리가 미리 알려줄 게 있으면, Claude는 훨씬 똑똑하게 일할 수 있습니다. Plugin은 이 매뉴얼을 체계적으로 만들어서 패키징한 것입니다.

Plugin vs 프로젝트 설정​

".claude/ 디렉토리에 직접 설정하면 되는 거 아니야?" 맞는 말입니다. 하지만 차이가 있습니다.

하나의 프로젝트에서만 쓸 거라면 .claude/로 충분합니다. 하지만 여러 프로젝트에 같은 규칙을 적용하고 싶다면? Plugin으로 만들어야 합니다.

4가지 핵심 구성 요소​

Plugin을 구성하는 네 가지 요소가 있습니다. 각각이 무엇을 하는지 알아봅시다.

Skills = 배경 지식​

Skills는 Claude에게 미리 알려주는 배경 지식입니다. SKILL.md 파일에 규칙을 작성하면, Claude가 관련 상황에서 자동으로 참고합니다.

예를 들어 Python 프로젝트를 다룰 때:

• "패키지 매니저는 uv를 사용해"
• "린터는 ruff를 써"
• "테스트는 pytest로 돌려"

이런 규칙을 SKILL.md에 적어두면, Claude는 Python 파일을 볼 때 자동으로 이 규칙들을 따릅니다.

Commands (= 호출 가능한 Skills)​

공식 문서에서는 Commands와 Skills가 통합되었습니다. .claude/commands/review.md든 .claude/skills/review/SKILL.md든, 둘 다 /review로 호출할 수 있습니다.

Commands는 사용자가 직접 호출하는 Skills입니다. /code-review라고 입력하면 코드 리뷰 모드로 들어가고, /reflect라고 하면 세션 회고를 시작합니다.

/code-review     → 현재 변경사항 코드 리뷰
/reflect         → 세션 회고 및 교훈 기록
/init-project    → 새 프로젝트 초기화

Hooks = 자동 규칙​

Hooks는 특정 이벤트가 발생하면 자동으로 실행되는 규칙입니다. hooks.json 파일에 한 번만 정의해두면, 조건이 맞을 때 자동으로 동작합니다.

예를 들어:

• 파일을 저장할 때마다 → 자동으로 코드 포맷팅
• 위험한 명령어를 실행하려 할 때 → 자동으로 차단
• 커밋하기 직전 → 자동으로 린트 검사

내가 "해줘"라고 말할 필요가 없습니다. 조건만 맞으면 알아서 실행됩니다.

Agents = 전문가 팀​

Agents는 특정 역할에 특화된 AI 분신입니다. 각 Agent는 자신만의 컨텍스트 윈도우, 시스템 프롬프트, 도구 접근 권한을 갖습니다.

예를 들어:

• code-reviewer: 코드 품질, 보안, 성능 관점에서 리뷰
• refactor-assistant: SOLID 원칙에 따른 리팩토링 제안
• reflector: 세션 회고 및 실수 패턴 분석

코드가 복잡해 보이면 리팩토링 전문가를 부르고, 코드가 완성되면 리뷰 전문가를 부르는 식으로 역할을 분담합니다.

실제 Plugin 구조​

실제로 Plugin 디렉토리가 어떻게 구성되는지 봅시다.

my-plugin/
├── .claude-plugin/
│   └── plugin.json           # Plugin 매니페스트 (필수)
├── skills/                   # 배경 지식 & 슬래시 명령어
│   ├── python-standards/
│   │   └── SKILL.md
│   ├── typescript-standards/
│   │   └── SKILL.md
│   └── git-workflow/
│       ├── SKILL.md
│       └── references/       # 부가 참고 자료
├── agents/                   # 전문가 팀
│   ├── code-reviewer.md
│   └── refactor-assistant.md
├── commands/                 # 슬래시 명령어 (skills/와 병행 가능)
│   ├── code-review.md
│   └── reflect.md
├── hooks/                    # 자동 규칙
│   └── hooks.json
├── scripts/                  # 유틸리티 스크립트
│   └── validate.sh
└── templates/                # 프로젝트 초기화 템플릿
    └── project/

plugin.json: 매니페스트 파일​

Plugin의 핵심은 .claude-plugin/plugin.json입니다. 이 파일이 있어야 Claude Code가 Plugin으로 인식합니다.

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "팀 개발 표준 및 워크플로우 자동화",
  "author": {
    "name": "Your Name"
  },
  "repository": "https://github.com/you/my-plugin",
  "license": "MIT"
}

필수 필드는 name 하나뿐입니다. 나머지는 선택사항이지만, 공유할 Plugin이라면 version과 description은 채워두는 게 좋습니다.

Plugin 설치와 관리​

설치​

# GitHub 저장소에서 설치
claude plugin install github:namyoungkim/leo-claude-plugin

# 로컬 개발 중인 플러그인 테스트
claude --plugin-dir ./my-plugin

설치 범위​

관리 명령어​

claude plugin enable my-plugin     # 활성화
claude plugin disable my-plugin    # 비활성화
claude plugin update my-plugin     # 업데이트
claude plugin uninstall my-plugin  # 제거

환경 변수: ${CLAUDE_PLUGIN_ROOT}​

Plugin 개발에서 가장 중요한 환경 변수가 하나 있습니다.

${CLAUDE_PLUGIN_ROOT} 는 Plugin 디렉토리의 절대 경로를 담고 있습니다. hooks.json이나 스크립트에서 Plugin 내부 파일을 참조할 때 사용합니다.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
      }]
    }]
  }
}

정리: Plugin은 AI와의 계약서​

Plugin이 무엇인지 정리하면:

이 다섯 가지가 모여서 하나의 Plugin이 됩니다. 한 번 만들어두면 여러 프로젝트에서 재사용할 수 있고, 팀원들과 공유할 수 있습니다.

다음 편 예고​

다음 편에서는 Skills과 Commands를 직접 만드는 방법을 다룹니다. SKILL.md의 frontmatter 옵션, 호출 제어 방식, 그리고 실제로 만들면서 겪었던 실수들까지 이야기합니다.

Claude Code Plugin 만들기 시리즈

• 1편: Plugin 입문 ← 지금 읽는 글
• 2편: 스킬과 커맨드
• 3편: 훅으로 자동화
• 4편: 자기 개선 루프

이 글은 Claude Code Plugin 만들기 시리즈의 두 번째 편입니다. Skill과 Command를 직접 만드는 방법, SKILL.md frontmatter 옵션, 그리고 실수 사례를 다룹니다.

TL;DR​

• Skill = SKILL.md 파일 하나로 Claude에게 배경 지식을 가르치는 것
• Command와 Skill은 공식적으로 통합됨 — 둘 다 /skill-name으로 호출
• frontmatter의 user-invocable, disable-model-invocation으로 호출 방식 제어
• references/ 패턴으로 긴 내용을 분리하여 컨텍스트 효율 극대화

Skill 만들기: AI의 참고서​

Skill은 Claude Code가 자동으로 참고하는 참고서입니다. 특정 상황에서 "이 규칙이 있었지"라고 Claude가 알아서 떠올리게 만듭니다.

SKILL.md 기본 구조​

모든 Skill은 디렉토리 안의 SKILL.md 파일로 정의됩니다.

skills/
└── python-standards/
    └── SKILL.md          # 필수

SKILL.md는 YAML frontmatter로 시작합니다.

---
name: python-standards
description: "Python 프로젝트 감지 시 uv + ruff + pytest 규칙 적용"
user-invocable: false
---

Python 프로젝트를 다룰 때는 항상:
- uv를 패키지 매니저로 사용합니다.
- ruff로 코드 스타일을 검사합니다.
- pytest를 테스트 프레임워크로 사용합니다.