PM을 위한 AI 실무 사전 6편 — 죽은 API와 의존성 함정
누구나법률 6장(완성 그 이후)에서 나온 개념: 안 쓰이는 코드의 위험성, 버전 고정의 함정, 인코딩 문제.
"완성"의 함정 — 안 불러본 코드는 검증된 적이 없다
서비스에 기능이 100개 있다고 해서, 그 100개가 다 검증됐다는 뜻은 아니다. 실제로 사용자가 눌러본 경로만 검증된 것이다. 6장의 /api/config/status 500 에러가 정확히 이 경우였다 — 코드는 있었지만, 아무도 그 엔드포인트를 실제로 호출하지 않았기 때문에 NameError(존재하지 않는 함수/변수를 부르는 오류)가 배포 이후 계속 방치돼 있었다.
실무에서 이걸 막는 방법은 결국 두 가지다.
- 모든 엔드포인트를 최소 한 번씩 직접 호출해보는 점검(smoke test) — 복잡한 테스트 코드가 아니어도, 배포 후 "이 API들 다 응답은 하나"를 확인하는 목록을 만들어두는 것만으로도 이런 사고를 줄인다.
- 안 쓰는 코드는 지운다 — "혹시 나중에 쓸까 봐" 남겨둔 코드는 그대로 방치되면 검증되지 않은 채 위험만 쌓인다.
버전 고정(pinning)의 양면성
requirements.txt에 pydantic==2.9.0처럼 버전을 정확히 고정해두는 건, "언제 설치하든 항상 똑같이 동작하게 하려는" 좋은 습관이다. 문제는 시간이 지나면 그 "정확한 버전"이 새로운 환경(새 파이썬 버전, 새 OS)과 안 맞을 수 있다는 것. 6장에서 겪은 게 정확히 이거였다 — 오래된 pydantic 버전은 최신 파이썬용 사전빌드 파일이 없어서, 설치할 때마다 소스 코드를 직접 컴파일해야 했고 그 컴파일에 필요한 도구가 없어서 실패했다.
실무 판단 기준:
- **정확한 고정(==)**은 "이 정확한 버전에서만 나오는 버그를 재현/디버깅해야 할 때"처럼 특별한 이유가 있을 때 쓴다.
- 그 외엔 **범위 고정(>=2.9.0,<3.0.0)**이 낫다. 하위 호환을 지키는 범위 안에서 최신 버전을 쓰게 해서, 이런 환경 충돌을 자연스럽게 피해간다.
인코딩 문제 — 파일은 하나인데 읽는 방식이 다르면 깨진다
컴퓨터에서 텍스트 파일은 결국 바이트(숫자)의 나열이다. 이 바이트를 사람이 읽는 글자로 바꾸는 규칙을 "인코딩"이라 부른다. 전 세계적으로 표준으로 쓰이는 게 UTF-8이고, 한국 윈도우는 예전부터 쓰던 cp949(EUC-KR 계열)라는 다른 규칙을 시스템 기본값으로 쓴다.
같은 파일이라도 UTF-8로 저장된 파일을 cp949로 읽으려 하면, 한글이 포함된 부분에서 깨지거나 아예 에러가 난다. 6장의 사례는 한 라이브러리가 파일을 열 때 인코딩을 명시하지 않아서, 운영체제 기본값(이 경우 cp949)으로 읽으려다 벌어진 일이었다.
실무 팁: 파일을 여는 코드를 짤 때는 항상 인코딩을 명시적으로 지정하는 습관을 들이는 게 좋다. open(path, encoding="utf-8")처럼. 명시하지 않으면 "내 컴퓨터에서는 됐는데 다른 사람 컴퓨터(다른 언어 환경)에서는 안 되는" 문제가 생긴다 — 이게 바로 6장에서 겪은 문제였다.
다음 실무 사전 편은 누구나법률 7장(기업형 계약 분석 엔진 만들기)이 발행된 후, 그 안에 나오는 개념들을 정리해서 이어간다.