들어가며
최근 소속 단체(SCG)에서 운영하는 레거시 시스템에 에러가 발생했고, Claude Code를 활용해 문제를 해결했다. 해결 과정의 전체 내용은 SCG 팀 블로그 글에 정리해두었으니, 이 글에서는 AI를 활용하면서 느낀 점에 집중해보려 한다.
그동안 Claude Code를 토이 프로젝트에서 몇 번 써본 적은 있었다. 하지만 실제로 사용자가 있는 운영 서비스에 적용해본 것은 이번이 처음이었고, 토이 프로젝트와는 근본적으로 다른 경험이었다.
문제를 해결하는 내내, 얼마 전 읽었던 에반문 님의 글 AI가 코드를 쓰는 시대, 개발자의 진짜 역량이 드러난다가 계속 떠올랐다. 그 글에서 이야기하는 것들이 머릿속 개념이 아니라 눈앞의 현실로 다가온 경험이었다.
상황 요약
8년 된 Node.js/Express 시스템을 Kubernetes로 마이그레이션한 직후, 관리자 페이지에서 파일 업로드 시 500 에러가 발생했다. 로그에는 URL만 남아 있었고, 관리자 페이지에 직접 접근할 수도 없는 상황이었다. 나는 주로 Java/Spring 기반으로 개발해왔기 때문에, Node.js/Express 코드베이스는 익숙하지 않았다. 이 상황에서 Claude Code를 적극적으로 활용했다.
AI가 틀렸던 순간들
첫 번째 가설은 빗나갔다
에러 현상과 환경 정보를 제공하자, Claude Code는 MinIO SDK의 HTTPS 설정 불일치를 1순위 원인으로 지목했다. K8s 환경에서 MinIO 엔드포인트에 scheme이 없으면 https://가 자동 부여되어 TLS 핸드셰이크가 무한 대기한다는 분석이었다.
그럴듯했지만, 나는 한 가지 사실을 알고 있었다. 같은 클러스터의 다른 서비스들은 동일한 MinIO에 정상적으로 연결되고 있다는 것. 이 정보를 제공하자 AI는 분석 방향을 전환했다.
에반문 님의 글에서 이런 대목이 있다. AI는 코드 안에서 최선의 답을 찾지만, 코드 바깥의 맥락까지 고려하여 판단하는 것은 어려워한다고. 정확히 그 상황이었다. "다른 서비스에서는 잘 된다"는 한마디는 코드 어디에도 적혀 있지 않은 정보였고, 이 한마디가 분석의 방향을 완전히 바꿨다.
해결책도 최선이 아니었다
원인이 multer 필드명 불일치로 확정된 후, AI는 upload.any()로 서버 설정을 변경하는 방안을 제시했다. 어떤 필드명이든 다 받겠다는 것이다. 동작은 한다. 하지만 좋은 수정은 아니라고 판단했다. 실제로 잘못된 것은 폼의 필드명이었으니, 그쪽을 고치는 게 맞다. 서버를 느슨하게 만드는 것보다 원인을 직접 수정하는 것이 더 명확한 해결이다.
에반문 님의 표현을 빌리면, 이것이 "작동하는 코드"와 "오래 살아남는 코드"의 차이다. upload.any()는 지금 당장 동작하지만, 미래의 유지보수자가 "왜 모든 필드를 허용하도록 해놨지?"라고 의문을 가질 코드다. 반면 폼 필드명을 통일하는 수정은 원인과 해결이 직관적으로 연결된다.
AI에게 학생 쪽 구현과 어드민 쪽 구현의 구조 차이를 분석하게 한 뒤, 어드민 뷰의 7개 파일 필드명을 통일하는 방향으로 확정했다.
토이 프로젝트와의 차이
토이 프로젝트에서 AI를 쓸 때는 "된다/안 된다"가 판단 기준이었다. 코드가 동작하면 그만이었고, AI가 제시한 방법을 그대로 적용해도 문제가 없었다.
이번에는 달랐다.
책임의 무게가 달랐다. 이 시스템은 학생들의 졸업평가 서류가 오가는 서비스다. 행정실 담당자가 업무 시간에 테스트를 해주고 있었고, 수정할 때마다 메일로 재시도를 요청해야 했다. "일단 돌아가니까 괜찮겠지"는 선택지가 아니었다.
에반문 님의 글에서 가장 인상 깊었던 부분이 "코드에 대한 책임을 질 사람이 필요하다"는 대목이었는데, 이번에 그 말이 체감으로 와닿았다. AI가 upload.any()를 제시했을 때, 그것을 그대로 머지할지 다른 방향을 잡을지를 결정하는 것은 결국 나였다. 그리고 그 수정으로 인해 문제가 생기면 책임을 지는 것도 나였다.
AI가 모르는 맥락이 존재했다. 조직의 운영 구조, 다른 서비스의 상태, 보안 정책 같은 것들은 코드에 드러나지 않는다. AI는 코드 안에서 최선의 답을 찾지만, 코드 바깥의 맥락은 사람만이 제공할 수 있다.
"왜"를 설명할 수 있어야 했다. "폼 필드명을 통일하는 게 낫다"는 판단을 내리려면, multer의 동작 방식, 학생/어드민 라우트의 구조 차이, 그리고 미래의 유지보수 부담까지 고려해야 했다. 에반문 님이 말한 "암묵지를 명시화하는 역량"이 바로 이런 것이 아닐까 싶다. "뭔가 이상한데"라는 직감을 "이 수정은 원인을 우회하는 것이지 해결하는 것이 아니다"라는 언어로 바꿀 수 있어야 AI에게 올바른 방향을 제시할 수 있다.
AI는 도구이고, 판단은 사람의 몫이다
이번 경험을 통해 AI 코딩 도구의 활용 패턴이 정리되었다.
- AI 가설 제시
- 사람이 검증/반박
- AI 재분석
- 사람이 방향 결정
- AI 실행
AI가 잘한 것은 속도였다. 익숙하지 않은 Node.js 코드베이스의 구조를 빠르게 파악하고, 라우트의 실패 지점을 분석하고, PR을 생성하는 작업은 AI 없이는 훨씬 오래 걸렸을 것이다.
AI가 못한 것은 판단이었다. 어떤 가설이 현실과 맞는지, 어떤 수정 방향이 더 적절한지, 이 수정이 미래의 유지보수자에게 어떤 영향을 미칠지. 이런 결정은 끝까지 사람의 몫이었다.
'개발 > AI' 카테고리의 다른 글
| CodeRabbit 설정하기 AtoZ (6) | 2025.08.01 |
|---|