일본의 로쿠요(Rokuyo) 달력을 직접 코딩하지 마세요: LLM이 생성한 음력 로직은 조용히 오류를 일으킵니다

원래 Qiita에 일본어로 게시되었습니다. 이것은 영어판입니다.

요약 (TL;DR)

LLM 시대에는 결혼 날짜 선택기, 이사 날짜 점수 산정기, 운세 챗봇 등 일본의 로쿠요 (Rokuyo) 달력과 관련된 비즈니스 요구사항이 급증하고 있습니다.
하지만 로쿠요를 직접 계산하려고 하면, 특정 날짜에서 조용히 오계산되는 유형의 버그가 발생합니다.
근본 원인은 로쿠요 공식이 아닙니다. 그 전 단계인 그레고리력(Gregorian date)을 일본 음력으로 변환하는 과정에서 천문학적 정밀도가 필요하기 때문입니다.
해결책은 그 앞에 AI 에이전트 지향적인 일본 달력 API(예: Shirabe Calendar API)를 두는 것입니다. 단 3줄의 curl / fetch / requests만으로 가능합니다.

로쿠요(Rokuyo)란 무엇인가, 간략히

**로쿠요 (Rokuyo, 六曜)**는 결혼, 장례, 착공, 개업 등 길일을 결정하기 위해 일본 전역에서 여전히 사용되는 6일 주기(대안(Taian) / 토모비키(Tomobiki) / 센쇼(Sensho) / 센부(Senbu) / 부츠메츠(Butsumetsu) / 샤코(Shakko))입니다. 만약 _날짜_를 추천하거나 점수를 매기는 일본 시장용 서비스를 만든다면, 결국 이것이 필요하게 될 것입니다. 사소해 보이지만

29.5일 주기를 사용하여 지난 신월 (New Moon)로부터 날짜를 계산하는 방식. 실제 삭망월 (Synodic month)은 29.27일에서 29.84일 사이를 오갑니다. 평균값인 29.5306일을 사용하더라도, 1년 동안 실행하면 며칠씩 오차가 발생합니다.
온라인에서 찾은 음력 변환 표를 임베딩하는 방식. 표의 종료 연도를 지나면 조용히 오차가 발생하며, 윤달 (Leap month) 처리 방식도 표마다 다릅니다.
lunar-javascript와 같은 중국 음력 (农历) 라이브러리를 재사용하는 방식. 일본의 천포력 (Tenpō calendar)과 중국 달력은 신월의 기준 시간대 (UTC+8 vs UTC+9)와 윤달 배치 방식이 다르기 때문에, 연간 몇몇 날짜가 어긋나게 됩니다.
LLM이 작성한 30~50줄짜리 공식. 태양/태음 황도 경도 (Solar/lunar ecliptic-longitude) 근사치가 어딘가에서 한 자리 숫자만큼 부정확하며, 신월 날짜의 경계에 걸치는 날짜들이 하루 차이로 잘못 계산됩니다.

오차가 무서운 이유

절대 에러를 던지지 않습니다. 타입은 통과하고, 예외 (Exception)도 발생하지 않으며, 항상 로쿠요(Rokuyo)처럼 보이는 문자열을 반환합니다.
테스트가 놓칩니다. 단 2~3일의 특정 날짜만 틀리기 때문에, 샘플링 테스트는 통과합니다.
결혼식 당일에 알게 됩니다. "대안 (Taian)"이라고 광고했던 날이 알고 보니 "부츠메츠 (Butsumetsu)"인 상황이 벌어집니다.

이것이 바로 침묵하는 실패 (Silent-failure) 유형입니다. LLM에게 코드를 맡기는 시대에 가장 흔하게 발생하는 버그 종류입니다.

근본 원인: 음력 변환에는 천문학이 필요합니다

로쿠요 규칙인 (음력 월 + 음력 일) mod 6은 결정론적이며, 음력 날짜만 정확하다면 항상 옳습니다. 어려운 부분은 바로 음력 날짜를 구하는 것입니다. 일본의 옛 달력 (천포력)은 다음을 요구합니다:

동경 135도, 일본 표준시 (JST) 기준의 신월 (Saku, 朔) 시점을 계산합니다.
신월이 있는 날이 음력 1일입니다.
**주요 절기 (Chūki)**를 포함하지 않는 달은 **윤달 (Leap month)**입니다.
윤달의 배치는 해마다 달라집니다 (약 19년 주기인 메톤 주기 (Metonic cycle) 동안 7번 발생).

이를 제대로 수행하려면 천문학적 정밀도로 태양 및 달의 황도 경도를 계산해야 합니다 (VSOP87 등). 근사치를 사용하고, 음력 신월이 자정 근처에 발생하는 날에는 하루씩 이동하며 — 그 해의 모든 후속 음력 날짜가 하루씩 연쇄적으로 밀리게 됩니다.

널리 인용되는 레퍼런스 구현체는 Hideaki Takano이 만든 QREKI입니다. 이 코드는 시리즈 전개(series expansion)를 통해 가시 황도 경도를 계산하는 수백 줄의 AWK로 이루어져 있습니다. 이를 직접 포팅하는 것은 양적으로나 원리적으로나, LLM에게 맡겨서는 안 되는 작업 유형입니다.

해결책: 일본 달력 API 호출하기

직접 구현을 포기하고 AI 에이전트를 위해 설계된 API에 맡기세요. 정확성, 유지보수 비용, 그리고 AI 통합 용이성 면에서 이득을 얻게 됩니다. 아래 예제들은 Shirabe Calendar API를 사용합니다. 무료 티어는 월 10,000회 호출이며, API 키 없이도 시도해 볼 수 있습니다. 아래의 fetch / requests 예제들에서도 X-API-Key가 포함되어 있지만, 이는 선택 사항이며 사용량 추적 및 제한 설정에 사용됩니다.

작동하는 세 줄 코드

# 하나의 날짜 -> 로쿠요(Rokuyo), 레키츠(rekichu) (길일), 칸시(kanshi), 절기(solar term) 등 모든 정보를 한 번의 응답으로 받습니다.
curl https://shirabe.dev/api/v1/calendar/2026-04-15

JSON 형식은 다음과 같습니다:

{
  "date": "2026-04-15",
  "rokuyo": {
...

핵심 필드는 **context와 summary**입니다. 단순히

best-days는 AI 에이전트가 스스로 _판단(judgment)_을 외부화할 수 있도록 설계되었습니다. 날짜 범위와 목적(wedding (결혼) / moving (이사) / business (비즈니스) 등 총 8개 카테고리)을 전달하면, 이유(예: Taian × Tensha-bi)와 함께 점수가 가장 높은 날들의 순위 목록을 얻을 수 있습니다.

AI 에이전트와의 통합

**OpenAPI 3.1 명세(spec)**를 공개함으로써, 이러한 종류의 API는 ChatGPT GPTs Actions, Claude tool use, Gemini function calling, LangChain 또는 LlamaIndex에서 한 번에 호출될 수 있습니다. Shirabe는 https://shirabe.dev/openapi.yaml에서 이를 직접 제공합니다.

ChatGPT GPTs Actions

GPT Builder에서

샘플 코드 또한 https://shirabe.dev/openapi.yaml의 examples 항목 아래에 수집되어 있습니다. 동일한 URL은 ChatGPT GPTs Actions, Claude tool use, 또는 Gemini function calling(함수 호출) 중 무엇을 사용하더라도 작동합니다.