일본 육요 달력 수작업 코딩을 그만: LLM이 만든 달력 로

출처: Dev.to

원래는 일본어로 Qiita에 게시되었습니다. 이 글은 영어 번역본입니다.

TL;DR

• LLM 시대에 일본 六曜(록요) 달력을 활용해야 하는 비즈니스 요구가 급증하고 있습니다 — 결혼식 날짜 선택기, 이사일 점수 매기기, 운세 챗봇 등.
• 하지만 록요를 직접 계산하면 특정 날짜에서 조용히 잘못된 결과를 내는 버그가 발생합니다.
• 근본 원인은 록요 공식 자체가 아니라 그 이전 단계인 그레고리오 달력을 일본 음력으로 변환하는 과정에 천문학적 정밀도가 필요하기 때문입니다.
• 해결책은 AI 에이전트용 일본 달력 API(예: Shirabe Calendar API)를 앞에 두는 것입니다. curl / fetch / requests 로 3줄이면 충분합니다.

록요가 무엇인지 간단히

Rokuyo (六曜) 은 여섯 날 주기(대안 / 친구비 / 선소 / 선부 / 불멸 / 작고) 로, 일본 전역에서 결혼식, 장례식, 착공, 매장 오픈 등 길일을 정할 때 사용됩니다. 일본 시장을 대상으로 날짜를 추천하거나 점수 매기는 서비스를 만들면 결국 이 정보를 필요로 하게 됩니다. 겉보기엔 간단해 보이지만, 그렇지 않습니다.

대상 독자

• LLM 에이전트 / AI SaaS 를 구축하는 풀스택 엔지니어
• “록요? 내가 직접 구현할 수 있어.” 라고 생각했던 사람
• LLM이 생성한 날짜 로직을 프로덕션에 배포한 사람

문제: AI에게 “록요를 계산해 달라”고 요청하면 어떻게 될까

코딩 어시스턴트에게 “주어진 날짜가 대안인지 알려주는 함수”를 달라고 하면 보통 다음과 같은 형태의 코드를 얻습니다:

// LLM이 흔히 제안하는 “순진한 록요” 구현
function getRokuyo(gregorianDate: Date): string {
  // (1) 그레고리오 → 음력 (년 / 월 / 일) 변환
  const lunar = convertToLunar(gregorianDate);   //  록요, 렛키추(길일), 간시, 절기 등을 한 번에 반환
curl https://shirabe.dev/api/v1/calendar/2026-04-15

JSON 예시는 다음과 같습니다:

{
  "date": "2026-04-15",
  "rokuyo": {
    "name": "大安",
    "reading": "Taian",
    "timeSlots": { "morning": "good", "noon": "good", "afternoon": "good", "evening": "good" }
  },
  "rekichu": [
    { "name": "一粒万倍日", "type": "auspicious" }
  ],
  "context": {
    "wedding": { "judgment": "excellent", "score": 9,
      "note": "Taian x Ichiryu-manbai-bi. An excellent day for a wedding." }
  },
  "summary": "Reiwa 8 (2026)-04-15 (Wed) Taian / Ichiryu-manbai-bi. Excellent for weddings and openings."
}

핵심 필드는 context와 summary 입니다. 단순히 “대안”이라는 라벨 대신, 목적별 판단(8가지 카테고리, 1‑10점)과 한 줄 요약을 제공합니다. AI 에이전트는 이 summary를 그대로 사용자에게 전달할 수 있습니다.

TypeScript

const res = await fetch(
  "https://shirabe.dev/api/v1/calendar/2026-04-15",
  { headers: { "X-API-Key": process.env.SHIRABE_API_KEY! } }
);
const data = await res.json();
console.log(data.rokuyo.name);   // "大安" (Taian)
console.log(data.summary);       // "Reiwa 8 (2026)-04-15 (Wed) Taian ..."

Python

import os, requests

r = requests.get(
    "https://shirabe.dev/api/v1/calendar/2026-04-15",
    headers={"X-API-Key": os.environ["SHIRABE_API_KEY"]},
    timeout=10,
)
print(r.json()["rokuyo"]["name"])

범위 조회 및 최적일 검색

하나의 날짜에 국한되지 않습니다.

# 4월 전체 대안/친구비 날짜 (최대 93일)
curl "https://shirabe.dev/api/v1/calendar/range?start=2026-04-01&end=2026-04-30&filter_rokuyo=大安,友引"

# 4월부터 12월까지 결혼식에 가장 좋은 날 5개 (점수 기준)
curl "https://shirabe.dev/api/v1/calendar/best-days?purpose=wedding&start=2026-04-01&end=2026-12-31&limit=5"

best-days 엔드포인트는 AI 에이전트가 판단 자체를 외부화할 수 있도록 설계되었습니다. 날짜 범위와 목적(wedding / moving / business 등 8가지 카테고리)을 전달하면, 이유와 함께 상위 점수 일자를 순위별로 반환합니다(예: 대안 × 천사일).

AI 에이전트와 통합

OpenAPI 3.1 스펙을 공개하면 ChatGPT GPTs Actions, Claude 툴 사용, Gemini 함수 호출, LangChain, LlamaIndex 등에서 한 번에 호출할 수 있습니다. Shirabe API는 바로 https://shirabe.dev/openapi.yaml 에서 확인할 수 있습니다.

ChatGPT GPTs Actions

GPT Builder에서 “Create new action” → Import URL에 OpenAPI URL을 붙여넣기:

https://shirabe.dev/openapi.yaml

API Key 인증(header 이름 X-API-Key)을 선택하면 끝입니다. 커스텀 GPT가 자동으로 Shirabe를 호출하게 됩니다.

LangChain / LlamaIndex / Dify

같은 URL을 OpenAPI 로더에 넘기면 도구로 변환됩니다. operationId가 함수 이름이 되도록 설계돼 있어 별도 glue code가 필요 없습니다.

자체 구현 vs API

“직접 만들었으니 무료다”는 겉보기에만 무료입니다. 비즈니스 위험을 고려한 가격을 생각하면 이 영역에서는 보통 비용 효율이 떨어집니다.

정리

• 록요 공식 자체는 간단합니다. 어려운 부분은 천문학적 정밀도가 요구되는 음력 변환입니다.
• LLM이 자체 구현하도록 하면 새벽 달 경계 날짜에서 정확히 하루씩 빗나가는 조용한 실패가 발생합니다.
• 결혼식, 장례식, 이사, 계약일 등 날짜 자체가 중요한 도메인에서는 자체 구현을 피하는 것이 비용 절감에 도움이 됩니다.
• AI 에이전트를 위해 설계된 일본 달력 API(OpenAPI 공개, 무료 티어)를 사용하면 fetch 3줄이면 끝납니다.

예제 코드는 https://shirabe.dev/openapi.yaml 의 examples 섹션에도 모아두었습니다. 같은 URL을 ChatGPT GPTs Actions, Claude 툴 사용, Gemini 함수 호출 어디서든 그대로 사용할 수 있습니다.

링크

• Shirabe Calendar API (공식)
• OpenAPI 3.1 스펙 (한·영 이중 설명)
• Rokuyo API 가이드
• Rekichu(길일) API 가이드
• GitHub 저장소

일본어 원본: 六曜APIを自前実装するな (Qiita)