에이전트는 그럴듯한(plausible) 금액 코드를 작성합니다. '그럴듯하다'는 것이 문제입니다. 데모에서는 통과하고, 내용을 훑어보는 사람의 코드 리뷰에서도 통과하지만, 실제 규모에서 돈을 손해 보게 만들고 추적하는 데 이틀이 걸리는 방식으로 실패합니다.
제가 가장 자주 보는 버그들이며, 현재 모든 프로젝트 메모리 파일에 넣은 세 가지 규칙입니다.
버그 1: 금액 계산 시 부동 소수점(floats) 사용
const total = price * qty와 같이 가격이 19.99인 경우를 가정해 봅시다. 여기에 할인, 백분율 적용, 그리고 수백 줄의 합산 과정이 있습니다. 장부(ledger)에서 볼 때 0.1 + 0.2 !== 0.3은 단순한 호기심거리가 아닙니다.
규칙: 금액은 최소 단위로 정수여야 합니다. 통화는 모든 금액에 명시되어야 합니다. 어떠한 경우에도 parseFloat, toFixed를 사용하거나, 부동 소수를 생성하는 나눗셈을 해서는 안 됩니다.
버그 2: 트랜잭션 내부의 부작용(Side Effects)
에이전트는 '주문 생성 → 카드 청구 → 이메일 전송' 과정을 하나의 트랜잭션으로 묶습니다. 이는 원자적(atomic)이라고 읽히기 때문입니다. 하지만 그렇지 않습니다. 카드 청구는 이미 다른 사람의 데이터베이스에서 즉시 커밋됩니다. 따라서 당신의 트랜잭션이 롤백되더라도 고객은 아무것도 받지 못한 대가를 지불하게 됩니다.
규칙: 트랜잭션은 데이터베이스 쓰기 작업만 감싸야 합니다. 외부 호출(External calls)은 보상 경로(compensation path)나 아웃박스 패턴(outbox)을 사용하여 트랜잭션 외부에 위치해야 합니다.
버그 3: 멱등성(Idempotency) 부재
웹훅 핸들러, 재시도 로직, 더블 클릭, 메시지 큐 재전송 등에서 발생합니다. 에이전트는 각 이벤트가 정확히 한 번 도착하는 것처럼 핸들러를 작성하는데, 이는 프롬프트가 그렇게 읽히기 때문입니다.
규칙: 재시도가 가능한 모든 쓰기 작업에는 고유성 제약 조건(uniqueness constraint)을 가진 멱등성 키(idempotency key)가 포함되어야 하며, 이 키는 diff에 나타나야 합니다.
버그 4: 시간대 오차로 인한 시간 오류
new Date('2026-10-28')은 UTC 자정입니다. 당신의 서버는 UTC이고, 사용자는 UTC+8에 있습니다. '28일에 만료되는' 구독이 잘못된 날짜의 8시간 시점에 만료되어 버리고, 지원 대기열에는 기술적으로는 맞는 말을 하는 사람들이 가득 차게 됩니다.
규칙: UTC로 저장하고, 표시 경계(display boundary)에서 변환하며, 명시적인 시간대 정보 없이 날짜 문자열을 절대 파싱해서는 안 됩니다.
버그 5: 잘못된 방향의 반올림(Rounding)
적은 금액에 대해 올림 처리된 수수료는 테스트 환경에서는 아무것도 아닌 것처럼 보이지만, 만 건의 주문에서는 과다 청구처럼 보이게 됩니다.
규칙: 메모리 파일에서 각 돈 관련 작업(money operation)에 대한 반올림 방향을 명시해야 합니다. “고객에게 유리하게 반올림(Round half up on the customer's favour)”은 누군가가 명시적으로 결정해야 하는 사항입니다.
에이전트가 이렇게 작동하는 이유
이는 악의적인 것이 아니며, 단순히 돈을 '이해하지 못하는' 모델도 아닙니다. 이는 일반적으로 돈이 부동 소수점(float)이고, 트랜잭션은 튜토리얼에서 원자적(atomic)이며, 웹훅(webhook)은 보통 한 번 호출되는 코퍼스 상의 패턴 완성 과정입니다. 귀하의 리포지토리가 그렇지 않다고 말하는 유일한 곳입니다.
가장 큰 비중을 차지하는 세 가지 규칙
- 돈은 정수형 소단위 단위(integer minor units)이며, 통화가 명시적이어야 합니다.
- 트랜잭션은 DB 쓰기만을 감싸고, 외부 호출은 제외해야 합니다.
- 재시도 안전한 쓰기는 가시적인 Idempotency Key를 포함해야 합니다.
이 규칙들을 프로젝트 메모리 파일에 넣고, 돈 관련 섹션을 병합 전 체크리스트(pre-merge checklist)에 포함시켜야 합니다. 그래야 환불 요청 이후가 아니라 병합 전에 이를 위반하는 diff가 플래그 지정될 수 있습니다.
저는 이 내용을 파일 및 라인 증거 요구 사항과 메모리 파일 템플릿을 갖춘 체크리스트로 유지하고 있습니다: AI Agent Engineering Kit — free starter included.