AI 코딩 도구의 한국어 문맥 오류 5가지와 프롬프트 우회법: 바이브 코더 필독

한국어로 요청하면 미묘하게 어긋난다

AI 코딩 도구에 한국어로 요구사항을 적으면 결과가 살짝씩 빗나갈 때가 있습니다. 문법을 못 알아듣는 게 아니라, 한국어 요구사항에 생략된 맥락을 채우지 못해서입니다. 우리는 "중복 로그인 방지"라고 쓰면 무엇을 뜻하는지 서로 알지만, 그 문장 자체에는 구현 정보가 거의 없습니다.

자주 겪는 다섯 가지 패턴과, 각각을 어떻게 다시 써서 요청하면 되는지 정리합니다.

1. 압축된 요구사항이 그대로 전달된다

"로그인 기능 개선해줘. 중복 로그인 방지하고 세션 타임아웃 처리해야 해."

이 문장에는 두 개의 큰 기능이 각각 한 단어로 압축돼 있습니다. 결과물이 단순 폼 검증에 그치는 일이 흔한 이유입니다.

압축을 푸는 건 사람이 해야 합니다.

로그인 기능을 개선해줘. 각 항목은 아래를 뜻해:

- 중복 로그인 방지: 한 계정에 활성 세션 1개만 유지.
  새 로그인 성공 시 기존 세션 토큰을 무효화한다.
- 세션 타임아웃: 액세스 토큰 30분 만료 + 리프레시 토큰 회전.
  만료 시 401 을 반환하고 클라이언트가 자동 갱신을 시도한다.

구현 전에 어떤 파일을 수정할 계획인지 먼저 알려줘.

마지막 줄이 의외로 효과가 큽니다. 계획을 먼저 받으면 방향이 어긋났을 때 코드가 생성되기 전에 잡을 수 있습니다.

2. 프로젝트의 관례를 모른다

팀마다 쓰는 스택과 폴더 구조가 다릅니다. 도구는 일반적으로 가장 흔한 선택지를 제시하므로, 팀의 관례와 어긋나면 결과물을 통째로 다시 써야 합니다.

매번 프롬프트에 적는 대신 프로젝트 규칙 파일에 한 번 적어두는 편이 낫습니다. 요즘 나오는 코딩 도구는 대부분 저장소 안의 규칙 파일을 자동으로 읽습니다.

- 스타일링: styled-components (Tailwind 사용 금지)
- 상태·서버데이터: React Query
- 폴더: src/components, src/hooks, src/types, src/api
- 네이밍: 변수 camelCase, 컴포넌트 PascalCase, 상수 UPPER_SNAKE_CASE
- 새 의존성 추가 전 반드시 물어볼 것

마지막 줄이 특히 중요합니다. 이게 없으면 요청하지 않은 라이브러리가 조용히 추가됩니다.

3. "간단히"가 사람마다 다르다

"검색 기능 간단히 만들어줘"에서 간단히는 두 가지 정반대 의미로 쓰입니다. 기술 부채를 감수하고 빨리 붙이자는 뜻일 수도, 과한 기능을 빼고 핵심만 남기자는 뜻일 수도 있습니다.

정도를 나타내는 부사는 조건으로 바꿔서 전달해야 합니다.

검색 기능을 만들어줘. "간단히"의 기준은 이거야:

- 포함: 제목·본문 부분 일치, 페이지네이션, 최신순 정렬
- 제외: 자동완성, 검색 히스토리, 고급 검색 문법
- 데이터 규모: 1만 건 기준으로 응답 1초 이내
- 검색 인덱스 도입은 하지 말고 기존 DB 쿼리로 처리

4. 국내 서비스 규칙은 별도로 알려줘야 한다

배송비, 휴무일, 환불 기한처럼 국내 서비스에서 통용되는 규칙은 코드로 표현되기 전까지는 도구가 알 방법이 없습니다. 게다가 이런 규칙은 회사마다 다르고 자주 바뀌므로, 도구가 알아서 채워 넣는 쪽이 오히려 위험합니다.

규칙은 값까지 명시해서 넘기고, 각 규칙을 주석으로 남기게 하세요.

배송비 계산 함수를 만들어줘. 규칙은 아래가 전부야:

- 3만원 이상: 무료
- 3만원 미만: 3,000원
- 제주·도서산간: 위 금액에 3,000원 추가
- 부피(가로+세로+높이) 100cm 초과: 5,000원 추가

각 규칙을 주석으로 명시하고, 규칙별 단위 테스트도 함께 작성해줘.

테스트를 함께 요청하면 규칙을 잘못 이해했는지 곧바로 드러납니다.

5. 사용자 메시지와 개발자 로그가 섞인다

한국어 에러 메시지를 요청하면 사용자에게 보여줄 문장과 디버깅용 로그가 뒤섞이는 경우가 많습니다. console.log('에러 발생') 같은 로그는 남아 있어도 아무 도움이 되지 않습니다.

둘은 목적이 다르니 분리해서 요청하세요. 사용자 메시지는 무엇을 할 수 있는지 알려주는 한국어 문장이어야 하고, 로그는 검색 가능한 식별자와 값을 담아야 합니다.

// 사용자에게 보여줄 문장은 한곳에 모아 재사용
const USER_MESSAGES = {
  USER_NOT_FOUND: '회원 정보를 찾을 수 없습니다.',
  INVALID_EMAIL: '이메일 형식이 올바르지 않습니다.',
};

// 로그에는 찾을 수 있는 값을 남긴다
logger.error('UserService: user not found', { userId, requestId });

참고로 한국어가 깨지는 문제를 인코딩 주석으로 해결하려는 시도를 종종 보는데, 이건 언어를 잘못 짚은 것입니다. JavaScript 파일에는 그런 주석 규칙이 없습니다. 한글이 깨진다면 대개 파일 저장 인코딩, HTTP 응답의 charset, 또는 데이터베이스 컬럼 인코딩 중 하나가 원인입니다.

영어로 요청하면 더 정확한가요?

용어를 정확히 쓴다는 조건이라면 영어가 유리한 면이 있습니다. 기술 문서 대부분이 영어로 쓰여 있기 때문입니다. 다만 실제 차이는 언어보다 구체성에서 훨씬 크게 납니다. 애매한 영어 요청보다 구체적인 한국어 요청이 결과가 낫습니다. 요구사항은 한국어로 쓰되 기술 용어만 영어로 병기하는 방식이 실용적입니다.

매번 이렇게 길게 써야 하나요?

아닙니다. 스택·컨벤션처럼 매번 같은 내용은 프로젝트 규칙 파일에 한 번만 적어두면 됩니다. 매 요청에서 길게 쓸 부분은 그 작업에만 해당하는 조건뿐입니다.

결과가 계속 어긋나면 어떻게 하나요?

같은 요청을 반복해서 다시 던지는 건 대체로 효과가 없습니다. 대신 코드를 요청하기 전에 계획을 먼저 물어보세요. 계획 단계에서 어긋난 지점이 보이면 그 부분만 바로잡아 진행하면 됩니다.

프롬프트보다 확인이 중요하다

프롬프트를 아무리 다듬어도 생성된 코드가 실제로 의도대로 도는지는 돌려봐야 압니다. 특히 위의 4번 같은 규칙은 실제 값을 넣어보기 전까지 틀린 걸 알아채기 어렵습니다.

만든 결과물이 어느 정도 형태를 갖췄다면 Vibeollio에 프로젝트 등록해서 공개해보세요. 다른 사람이 실제로 눌러보고 남기는 댓글에서, 혼자 테스트할 때는 안 보이던 문제가 드러나는 경우가 많습니다.