3줄 요약

1. AI 에이전트는 그럴듯하게 틀려요. 테스트가 통과해도, 설명이 논리적이어도요.
2. 그래서 사고가 날 때마다 그날 규칙을 남겼어요.
3. 규칙은 문서보다 자동 검사로 지킬 때 오래가요.

무엇을 했나

보장플러스는 보험 보장분석 웹 서비스예요. 자바로 만든 옛 화면을 Next.js로 하나씩 옮기고 있고, 2026년 6월부터 11월까지 5개월 동안 커밋 609건이 쌓였어요. 그중 94%가 AI 에이전트(Claude Code)와 함께한 작업이에요.

[embed: node/2afe4d22-324d]

회사 전체의 AI 전환(AX)이나 서비스에 AI 기능을 넣은 이야기는 아니에요. 한 팀이 AI와 일하는 방식을 만든 이야기예요.

AI가 틀린 다섯 번

대부분 코드 자체보다 환경과 확인 과정에서 틀렸어요. 그리고 틀릴 때마다 규칙이 하나씩 늘었어요.

1. 사람과 AI가 같은 작업 폴더를 썼어요

개발자가 화면을 띄워 둔 채로 자동 테스트를 돌리자, 둘이 같은 폴더에 결과물을 쓰면서 서로를 망가뜨렸어요. AI는 다른 누군가 그 폴더를 쓰고 있다는 걸 알 길이 없었어요.

→ 남긴 규칙: 자동 테스트와 AI의 빌드는 각자 다른 폴더를 쓴다.

2. 아무것도 잡지 못하는 테스트

AI는 버그를 고치면 같은 버그가 다시 생기는지 확인하는 테스트도 함께 만들어요. 그런데 그 테스트가 고치기 전에도 통과하는 경우가 세 번 있었어요. 카드를 재야 할 테스트가 상단 로고를 재고 있던 식이에요.

→ 남긴 규칙: 테스트를 만들면 고친 코드를 잠깐 되돌려서, 테스트가 정말 실패하는지 본다.

3. 가짜 데이터만 보고 내린 판단

개발은 실제 서버 대신 가짜 응답(목업)으로 해요. 8월 말 한 세션에서 나온 버그 6건 중 5건이 가짜 응답과 실제 응답이 달라서 생겼어요. 가짜에서 고쳐졌다고 진짜에서도 고쳐진 건 아니었죠.

→ 남긴 규칙: 버그인지 아닌지는 실제 서버 응답으로 판단한다.

4. 논리적이지만 틀린 진단

코드를 올리면 도는 서버 검사에서만 표가 1px 넘치는 문제가 났어요. AI는 "소수점 반올림 문제"라고 진단하고 고친 코드를 두 번 올렸지만, 둘 다 실패했어요. 진짜 원인은 Windows와 Linux에서만 폭을 차지하는 스크롤바였어요. Windows 사용자도 똑같이 겪었을 문제라, 검사가 제대로 잡은 거였죠.

→ 남긴 규칙: 서버 검사에서만 실패하면 반올림보다 스크롤바부터 의심한다.

5. 한 번 받은 승인을 넓게 읽었어요

"커밋해"라는 말을 한 번 듣고, 그 뒤의 작업 전체에 대한 허락으로 받아들여 아직 논의 중이던 문서까지 올렸어요.

→ 남긴 규칙: 승인은 그 작업 한 건에만 유효하다.

나머지 사례는 원본 탭의 부록에 모아 두었어요.

규칙을 지키게 만든 방법

AI는 대화가 끝나면 그날 있었던 일을 잊어요. 그래서 다음 대화에서도 읽을 수 있는 곳에 남겨야 했어요.

• 규칙 파일에 적기. AI가 작업을 시작할 때마다 읽는 파일(CLAUDE.md)에 이유와 함께 적었어요. 이유가 있어야 비슷한 상황에서도 스스로 판단할 수 있거든요.
• 자동 검사로 막기. 적어 둔 규칙도 읽어야 지켜져요. 그래서 막을 수 있는 건 기계로 막았어요. AI가 "끝났다"고 하려면 규칙 검사, 타입 검사, 테스트, 빌드를 모두 통과해야 해요.
• 개인 메모에만 두지 않기. 처음에는 일부 규칙이 한 사람의 AI 메모에만 있어서, 다른 팀원의 AI는 몰랐어요. 그래서 이 글을 정리하면서 팀이 함께 쓰는 규칙 파일로 옮겼어요.

사람이 하는 일은 어떻게 바뀌었나

사람의 일은 코드를 쓰는 것에서 무엇을 할지 정하고, 결과를 확인하고, 규칙을 쓰는 것으로 옮겨 갔어요.

AI는 직접 재 보고 비교하는 일에 강했어요. 7분 넘게 걸리던 자동 테스트를 여러 방법으로 돌려 보고 비교해서, 약 1분으로 줄였어요(빌드를 다시 하지 않을 때 기준). 하지만 "왜 이렇게 해야 하는지"라는 맥락은 사람이 알려 줘야 했어요. 예를 들어 "자바 원본과 줄 단위로 대조하며 옮기는 중이니 코드를 한꺼번에 재정렬하지 말 것" 같은 건 코드만 봐서는 알 수 없거든요.

개발자만의 변화도 아니었어요. 디자인 작업을 주로 맡은 팀원도 커밋 146건 중 117건을 AI와 함께 만들었어요.

다른 팀에 권하는 다섯 가지

1. 맡기기 전에 자동 검사부터 깔기. 통과해야 "끝"이에요.
2. 사고가 난 날 규칙 남기기. 이유와 함께, 팀이 같이 보는 곳에요.
3. 지킬 수 있는 규칙은 자동 검사로. 문서보다 오래가요.
4. 통과한 테스트도 되돌려서 확인하기. 초록불이 곧 안전은 아니에요.
5. 승인은 작게, 한 건씩. 커밋과 푸시는 매번 사람이 확인해요.

마치며

AI가 코드를 써 주는 건 시작일 뿐이었어요. 정말 공을 들인 건 그 코드를 믿을 수 있게 만드는 울타리였어요.

돌아보면 가장 쓸모 있었던 건 AI가 틀린 순간들이었어요. 틀릴 때마다 규칙이 하나씩 늘었고, 그 규칙이 다음 대화의 AI와 다른 팀원을 같은 실수에서 지켜 줬거든요. 5개월 동안 쌓인 건 코드만이 아니라, 우리 팀이 AI와 일하는 방식 그 자체였어요.

AI 도입을 고민하는 팀에 드리고 싶은 말은 하나예요. AI가 틀리는 걸 두려워하지 말고, 틀린 자리를 기록하세요. 그 기록이 쌓이면 곧 팀의 개발 방식이 돼요.