Claude Code 날짜 계산 오류 해결: Rules와 Hooks 완벽 설정법

"오늘이 무슨 요일이야?"라는 단순한 질문에 AI가 틀린 답을 한다면 믿을 수 있을까요? 실제로 Claude Code를 포함한 LLM은 날짜 계산에서 구조적으로 취약합니다. 연구에 따르면 요일 정확도가 26.3%에 불과하다는 결과도 있습니다. 하지만 Claude Code의 Rules 시스템과 Hooks를 활용하면 이 문제를 근본적으로 해결할 수 있습니다.

이 글에서는 Claude Code 날짜 오류의 원인부터 Rules 파일 작성법, SessionStart 훅 설정까지 실전에 바로 적용할 수 있는 방법을 단계별로 안내합니다.

LLM은 왜 날짜 계산을 틀릴까?

LLM은 왜 날짜 계산을 틀릴까?

많은 개발자가 Claude Code에게 날짜 관련 질문을 했다가 당황한 경험이 있을 겁니다. AI 피트니스 트레이너가 금요일을 월요일로 착각하거나, 콘텐츠 생성 시 날짜와 요일이 엉뚱하게 짝지어지는 사례가 끊이지 않습니다.

이런 오류의 근본 원인은 LLM의 작동 방식에 있습니다.

토큰화와 확률 예측의 한계

LLM은 계산기가 아니라 확률적 텍스트 생성 모델입니다. 숫자 "87439"가 내부적으로 "874"+"39" 또는 "87"+"439"로 쪼개질 수 있고, 자릿수 구조가 보존되지 않습니다. 모델은 "정확한" 답이 아니라 훈련 데이터에서 가장 자주 등장했던 "그럴듯한" 답을 선택합니다.

시간 인식 자체가 없다

LLM에는 달력이나 시계 개념이 존재하지 않습니다. 월별 일수, 윤년 규칙, 요일 순서를 "이해"하는 것이 아니라 텍스트 패턴에서 추론할 뿐입니다. 크리스마스 요일처럼 자주 등장하는 날짜는 맞추지만, 임의 날짜의 요일은 높은 확률로 틀립니다.

LLM의 날짜 계산 한계: LLM은 토큰화 기반 확률 예측 모델이므로 정확한 날짜 산술이 불가능합니다. 연구에 따르면 요일 계산 정확도는 26.3%이며, 도구(Bash/Python)를 사용하면 오답률이 88%에서 16%로 감소합니다.

Claude Code Rules로 날짜 도구 사용 강제하기

Claude Code Rules로 날짜 도구 사용 강제하기

해결책은 명확합니다. Claude Code가 날짜를 "추측"하지 못하게 하고, 반드시 시스템 도구를 사용하도록 강제하는 것입니다. Claude Code의 Rules 시스템이 이를 가능하게 합니다.

Rules 시스템이란?

Claude Code는 계층적 메모리 구조를 통해 행동 규칙을 관리합니다. ~/.claude/rules/ 디렉토리에 .md 파일을 생성하면 모든 프로젝트에 자동으로 규칙이 적용됩니다.

프로젝트 규칙이 글로벌 규칙보다 높은 우선순위를 가지므로, 글로벌에 기본 날짜 규칙을 두고 프로젝트별로 필요한 부분만 재정의할 수 있습니다.

날짜 규칙 파일 작성하기

~/.claude/rules/date-calculation.md 파일을 만들어 Claude Code에게 날짜 관련 행동 지침을 부여합니다.

# Date & Time Calculation (CRITICAL)

## 절대 규칙

날짜/시간 계산은 절대 머리로 하지 마라. 반드시 시스템 도구를 사용하라.

## 기본 타임존

Asia/Seoul (KST, UTC+9)

## 필수 사용 패턴

### 현재 날짜/시간 확인
date '+%Y-%m-%d %A %H:%M:%S %Z'

### 요일 계산 (macOS)
date -j -f '%Y-%m-%d' '2026-03-15' '+%A'

### N일 후/전 계산 (macOS)
date -j -v+30d '+%Y-%m-%d %A'    # 30일 후
date -j -v-7d '+%Y-%m-%d %A'     # 7일 전

### 복잡한 계산은 Python 사용
python3 -c "
from datetime import datetime, timedelta
d1 = datetime(2026, 2, 6)
d2 = datetime(2026, 12, 31)
print(f'{(d2-d1).days}일')
"

## 금지 사항

- 날짜를 암산으로 계산
- 요일을 추측으로 답변
- 영업일 계산을 머리로 시도

## 허용 사항

- 항상 date 명령어 또는 python3 사용

핵심은 "CRITICAL" 표기, 구체적인 명령어 스니펫, 그리고 금지/허용 사항의 명확한 구분입니다. Claude Code 공식 문서에 따르면 "IMPORTANT", "YOU MUST", "CRITICAL" 같은 강조 표현을 사용하면 규칙 준수율이 향상됩니다.

SessionStart 훅으로 날짜 자동 주입하기

SessionStart 훅으로 날짜 자동 주입하기

Rules만으로 부족한 경우가 있습니다. Claude Code에는 UTC가 아닌 타임존에서 날짜가 잘못 표시되는 알려진 버그(GitHub Issue #4514)가 존재합니다. 한국(KST, UTC+9) 사용자는 매일 자정부터 오전 9시 사이에 전날 날짜를 보게 될 수 있습니다.

이 문제를 해결하려면 SessionStart 훅을 활용합니다.

훅 스크립트 작성

~/.claude/hooks/inject-date.sh 파일을 생성합니다.

#!/bin/bash
TZ=${TZ:-Asia/Seoul}
CURRENT_DATE=$(TZ=$TZ date '+%Y-%m-%d %A %H:%M:%S %Z')
ISO_DATE=$(TZ=$TZ date '+%Y-%m-%dT%H:%M:%S%z')

echo "{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"[CONTEXT] Current date/time: $CURRENT_DATE | ISO: $ISO_DATE | Timezone: $TZ\"}}"

settings.json에 훅 등록

~/.claude/settings.json에 다음을 추가합니다.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/inject-date.sh"
          }
        ]
      }
    ]
  }
}

이 설정을 적용하면 Claude Code 세션이 시작될 때마다 정확한 날짜, 시각, 타임존 정보가 자동으로 컨텍스트에 주입됩니다. 별도의 질문 없이도 Claude는 현재 날짜를 정확히 인식합니다.

환경 변수로 타임존 고정하기

더 확실한 방법도 있습니다. SessionStart 훅에서 CLAUDE_ENV_FILE에 타임존을 기록하면 이후 모든 Bash 명령어에 KST가 적용됩니다.

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export TZ=Asia/Seoul' >> "$CLAUDE_ENV_FILE"
fi

macOS와 Linux에서 날짜 명령어 차이 이해하기

macOS와 Linux에서 날짜 명령어 차이 이해하기

Claude Code 날짜 설정을 적용할 때 한 가지 주의할 점이 있습니다. macOS와 Linux의 date 명령어는 호환되지 않습니다. macOS는 BSD date, Linux는 GNU date를 사용하기 때문입니다.

플랫폼별 명령어 비교

Python이 최선의 크로스 플랫폼 대안

팀원들이 다양한 운영체제를 사용한다면 Python을 기본 도구로 지정하는 것이 가장 안전합니다.

# 두 날짜 사이 일수
python3 -c "
from datetime import datetime
d1 = datetime(2026, 2, 6)
d2 = datetime(2026, 12, 31)
print(f'{(d2-d1).days}일')
"

# KST 기준 현재 시각
python3 -c "
from datetime import datetime, timezone, timedelta
kst = timezone(timedelta(hours=9))
now = datetime.now(kst)
print(now.strftime('%Y-%m-%d %A %H:%M:%S KST'))
"

# D-day 계산
python3 -c "
from datetime import datetime
target = datetime(2026, 12, 25)
today = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
delta = (target - today).days
print(f'D-{delta}' if delta > 0 else 'D-Day!')
"

Python datetime 라이브러리는 윤년, 월말, 타임존을 모두 정확하게 처리하므로 Claude Code의 날짜 계산 도구로 가장 적합합니다.

실전 적용: 3단계 설정 요약

실전 적용: 3단계 설정 요약

지금까지 살펴본 내용을 정리하면, Claude Code 날짜 문제 해결은 세 단계로 완성됩니다.

1단계 - Rules 파일 생성: ~/.claude/rules/date-calculation.md에 "CRITICAL" 표기와 함께 도구 사용 강제 규칙을 작성합니다.

2단계 - SessionStart 훅 설정: ~/.claude/hooks/inject-date.sh 스크립트를 만들고 settings.json에 등록하여 세션마다 정확한 날짜를 주입합니다.

3단계 - 크로스 플랫폼 대응: macOS/Linux 차이를 고려해 Python 기반 날짜 계산 패턴을 Rules에 포함합니다.

이 세 단계를 적용하면 Claude Code가 날짜를 추측하는 일은 사라지고, 매번 시스템 도구를 통해 정확한 결과를 반환하게 됩니다.

마무리

Claude Code 날짜 계산 오류는 LLM의 구조적 한계에서 비롯되지만, Rules와 Hooks라는 강력한 도구로 완전히 해결할 수 있습니다. 핵심은 간단합니다. Claude에게 날짜를 "생각"하게 하지 말고, "계산"하게 만드세요.

오늘 소개한 설정은 5분이면 완료됩니다. ~/.claude/rules/ 디렉토리에 날짜 규칙 파일 하나만 추가해도 즉시 효과를 볼 수 있습니다. 날짜 관련 작업이 많은 프로젝트라면 SessionStart 훅까지 설정해두시길 권장합니다.

더 궁금한 점이 있으시면 댓글로 남겨주세요.

자주 묻는 질문 (FAQ)

Q: Rules 파일은 모든 프로젝트에 자동 적용되나요?

~/.claude/rules/ 디렉토리의 파일은 글로벌 규칙으로, 모든 프로젝트에서 자동 로드됩니다. 특정 프로젝트에만 적용하려면 프로젝트 루트의 .claude/rules/ 디렉토리에 파일을 생성하세요.

Q: SessionStart 훅 없이 Rules만으로도 효과가 있나요?

Rules만으로도 Claude Code가 date 명령어나 python3를 사용하도록 유도할 수 있습니다. 다만 타임존 버그(Issue #4514)가 발생하는 환경에서는 SessionStart 훅을 병행하는 것이 더 안정적입니다.

Q: macOS와 Linux 양쪽을 모두 지원하려면 어떻게 해야 하나요?

Rules 파일에 두 플랫폼의 명령어를 모두 포함하거나, Python datetime을 기본 도구로 지정하세요. Python은 운영체제에 관계없이 동일하게 동작하므로 팀 환경에서 가장 안전한 선택입니다.

Q: "CRITICAL" 같은 강조 표현이 실제로 효과가 있나요?

Claude Code 공식 Best Practices 문서에서 권장하는 방법입니다. "IMPORTANT", "YOU MUST", "CRITICAL" 등의 표현을 사용하면 Claude의 규칙 준수율이 실제로 향상됩니다. 단, CLAUDE.md 전체가 강조 표현으로 가득하면 오히려 효과가 떨어지므로 핵심 규칙에만 사용하세요.

참고 자료

• Claude Code Memory 관리 - 공식 문서
• Claude Code Hooks 레퍼런스 - 공식 문서
• Claude Code Best Practices - 공식 문서
• 타임존 날짜 버그 - GitHub Issue #4514
• The Claude Code Date Bug Fix - Nathan Onn
• LLMs Can't Calculate: Why You Should Use Tools for Math - Medium
• Mathematical Reasoning in LLMs - arXiv