2.6구성 관리

모델 식별자를 어떻게 적느냐가 첫 갈림길입니다. 별칭처럼 넓은 이름을 쓰면 갱신을 자동으로 따라가고, 구체적인 버전을 적으면 그 자리에 머무릅니다.

운영 환경에서는 버전을 고정하는 편이 기본입니다. 갱신은 대체로 개선이지만, 개선도 우리 프롬프트에는 변화입니다. 출력 길이나 형식 준수 경향이 달라져 소비자 쪽이 깨질 수 있습니다.

# 설정에서 읽어 한 곳에서만 정의한다
MODEL = os.environ["CLAUDE_MODEL"]     # 배포 단위로 고정된 값

resp = client.messages.create(model=MODEL, ...)

고정한 뒤에는 옮기는 절차가 필요합니다. 새 버전으로 평가 세트를 돌려 점수를 비교하고, 차이가 나는 사례를 확인한 뒤 옮깁니다. 이 절차가 없으면 고정의 의미가 없습니다. 영영 옛 버전에 남는 것도 좋은 상태가 아닙니다.

응답에 어느 버전이 답했는지 정보가 함께 오므로, 로그에 남겨 두면 나중에 "언제부터 달라졌는가"를 추적할 수 있습니다.

Claude Code를 쓰는 저장소에서는 파일 두 종류가 동작에 영향을 줍니다.

CLAUDE.md — 모델에게 주는 프로젝트 규칙입니다. 코딩 규약, 자주 쓰는 명령, 피해야 할 것을 적습니다. 상위 디렉터리와 하위 디렉터리에 각각 둘 수 있고, 하위가 그 폴더 작업에 더 가까운 규칙을 담습니다.

settings.json — 도구 권한, 훅, 환경 설정처럼 동작을 통제하는 값입니다. 규칙 파일이 "이렇게 해 주세요"라면 설정 파일은 "이건 못 합니다"에 가깝습니다.

이 차이가 시험에 나옵니다. 지침은 모델이 참고하는 것이고 설정의 거부 규칙은 강제됩니다. 막아야 하는 것을 CLAUDE.md에만 적어 두는 것은 방어가 아닙니다.

두 파일 모두 저장소에 커밋되어야 팀 전체가 같은 환경에서 일합니다. 개인 설정을 팀 설정과 섞지 않는 것도 중요합니다. 개인 취향이 팀 규칙으로 들어가면 다른 사람의 작업이 이상하게 동작합니다.

프롬프트가 코드 안에 문자열로 흩어져 있으면 무엇이 언제 바뀌었는지 추적할 수 없습니다. 파일로 모아 두면 관리가 쉬워집니다.

# prompts/classify_v3.txt 를 읽어 쓰고, 버전을 로그에 남긴다
PROMPT_VERSION = "classify_v3"
SYSTEM_PROMPT = read_prompt(PROMPT_VERSION)

log.info("request", extra={"prompt_version": PROMPT_VERSION, "model": MODEL})

버전 표시를 로그에 남기는 것이 핵심입니다. 나중에 품질 문제가 생겼을 때 그 응답이 어떤 프롬프트와 어떤 모델로 나왔는지 알 수 있습니다. 이것이 없으면 재현조차 어렵습니다.

프롬프트를 바꿀 때는 평가 세트 점수를 함께 기록합니다. 되돌릴 근거가 되고, 여러 후보를 비교할 때도 기준이 됩니다.

MCP 서버나 스킬 같은 확장을 붙이면, 그것들도 구성의 일부가 됩니다. 그런데 이들은 우리 저장소 밖에서 바뀔 수 있습니다.

챙길 것이 셋입니다.

• 무엇이 붙어 있는지 목록으로 관리한다. 어떤 확장이 어떤 도구를 제공하는지 적어 둡니다.
• 버전을 고정할 수 있으면 고정한다. 외부 서버가 도구 스키마를 바꾸면 우리 프롬프트가 기대하던 것과 어긋납니다.
• 필요한 것만 붙인다. 확장이 늘면 도구 목록이 길어지고, 컨텍스트를 먹고 모델의 선택도 흐려집니다.

도구가 늘어날 때의 부작용은 과소평가되기 쉽습니다. 쓰지 않는 도구 열 개가 목록에 있으면 매 요청에 그 정의가 실려 나가고, 모델은 매번 그 중에서 고릅니다. 정기적으로 목록을 훑어 안 쓰는 것을 떼는 일이 실제 운영 작업의 일부입니다.