한 번의 출생 정보로 세 가지 점성술 시스템을 계산하고 에이전트 호출이 가능하도록 만든 오프라인 CLI 개발기

저는 점성술 앱 주변에서 많은 시간을 보냅니다. 제가 점성술을 진심으로 믿기 때문이 아니라, 그 뒤에 숨겨진 _엔지니어링 (engineering)_이 거의 항상 형편없기 때문입니다. 웹 양식에 출생 데이터를 입력하면, 어딘가에 있는 블랙박스 (black box)가 작동하고, 재현할 수 없고, 감사 (audit)할 수 없으며, 동일한 수학적 계산을 두 번 수행했을 때 같은 결과가 나올 것이라고 신뢰할 수 없는 차트가 결과로 나옵니다. 서버 측 라이브러리 하나만 바뀌어도 당신의 "운명"은 소리 없이 변해버립니다. 이는 그 어떤 별자리 운세보다 저를 더 괴롭혔습니다.

그래서 저는 life-chart-engine을 만들었습니다. 이는 하나의 출생 기록을 입력받아 단 한 번의 실행으로 세 가지 독립적인 시스템을 계산하는 오프라인, AGPL-3.0 CLI입니다. 세 가지 시스템은 다음과 같습니다: 서양 점성술 (Western natal: Tropical zodiac, Placidus houses, Swiss Ephemeris 활용), 人類圖 Human Design (타입, 권위, 프로필, 정의, 인카네이션 크로스, 64개 게이트 전체), 그리고 紫微斗數 Zi Wei Dou Shu (12궁, 별의 밝기, 四化 변환, 오행국, py-iztro 활용)입니다.

점성술은 도메인 (domain)이고, 이야기는 결정론 (determinism)입니다.

재현성 문제 (The reproducibility problem)

기계적으로 볼 때 출생 차트는 단순한 좌표 변환 (coordinate transform)입니다. 특정 시점과 지구상의 한 지점이 주어졌을 때, 행성들이 어디에 있었는지를 묻는 것입니다. 이것은 해결된 천문학의 영역입니다. 전문 소프트웨어가 사용하는 것과 동일한 DE431 기반의 에페메리스 (ephemeris)인 Swiss Ephemeris는 초각 (sub-arcsecond) 단위의 행성 위치를 제공합니다. 여기에는 _정답_이 존재하며, 이는 당신이 어떤 스타트업의 API를 호출하느냐에 따라 달라지지 않습니다.

블랙박스 형태의 웹 앱들은 이를 버립니다. 두 번의 실행 결과를 비교 (diff)할 수 없고, 버전을 고정할 수 없으며, 누군가에게 입력값을 전달하여 동일한 출력값을 재계산하게 할 수도 없습니다. life-chart-engine은 그 반대로 구축되었습니다. 웹 서비스도, API도, 계정도, 텔레메트리 (telemetry)도 없습니다. 이 프로그램은 네트워크에 절대 접속하지 않습니다. 동일한 출생 기록을 넣으면, 어떤 기기에서든 매번 바이트 단위로 동일한 차트가 출력됩니다. 이것이 핵심입니다. 즉, 감사 (audit) 가능한 출처 (provenance)를 제공하는 것입니다.

설치 (Install)

curl -fsSL https://raw.githubusercontent.com/zhenheco/life-chart-engine/main/install.sh | bash

설치 프로그램은 **CPython 3.12 가상 환경 (virtualenv)**을 고정하며, 이 고정은 매우 중요한 역할을 합니다. py-iztro (자미두수 엔진)는 제가 이 프로젝트를 작성할 당시 최신 CPython에서 깔끔하게 빌드되지 않는 네이티브 의존성 (native dependencies)을 포함하고 있었습니다. 따라서 사용자가 배포판에서 제공하는 어떤 인터프리터를 사용하든 컴파일러 오류라는 벽에 부딪히게 하는 대신, 설치 프로그램이 격리된 3.12 환경을 준비하도록 했습니다. 이것이 네이티브 코드 (native code)를 다룰 때 마주하는 화려하지 않은 현실입니다. 실제로 테스트한 인터프리터를 고정하고, _그 이유_를 문서화하며, "최신 버전"이 공짜인 것처럼 행동하는 것을 멈추는 것입니다.

--json 엔벨로프 (envelope)

사람이 읽기 좋은 출력도 좋지만, 흥미로운 모드는 --json입니다. 매 실행마다 구조화된 엔벨로프 (envelope)가 생성됩니다. 입력값이 다시 에코(echo)된 후, 세 가지 시스템이 각각 라벨이 붙은 블록으로 출력됩니다.

life-chart --date 1990-06-15 --time 08:30 --tz 8 \
  --lat 25.0330 --lon 121.5654 --json

{
  "ok": true,
  "schema_version": "1.0",
...

(가독성을 위해 생략됨 — planets, gates, palaces와 같은 배열은 실제 실행 시 더 상세하며, 사인(sign)과 별(star)의 이름은 중국어로 출력됩니다. --tz는 IANA 이름이 아닌 숫자 형태의 UTC 오프셋(offset)임에 유의하세요.)

제가 조용히 자랑스럽게 생각하는 것 중 하나는 휴먼 디자인 (Human Design)의 **88° 솔버 (solver)**입니다. 휴먼 디자인은 태양이 출생 위치의 태양 위치로부터 정확히 호도법(arc)으로 88도 _이전_이었던 순간에 생성된 두 번째 "디자인" 차트가 필요합니다. 대략 3개월 전이지만, 태양의 겉보기 속도는 연중 변하기 때문에 단순히 88일을 빼는 방식으로는 안 됩니다. 따라서 이는 근 찾기 문제 (root-finding problem)입니다. sun_longitude(birth) − sun_longitude(t) = 88°를 만족하는 타임스탬프 t를 검색한 다음, 그 순간의 게이트(gate) 활성화를 다시 계산합니다. 이는 천체력 (ephemeris)을 감싸고 있는 아주 작은 수치 솔버 (numerical solver)이며, 블랙박스 앱들이 숨겨두어 사용자가 결코 검증할 수 없는 바로 그런 종류의 기능입니다. 여기서는 소스 코드에 공개되어 있습니다.

AGENTS.md를 통한 AI 에이전트 연결

이 지점에서 결정론(determinism)은 AI 빌더들에게 큰 보상을 제공합니다. 언어 모델에게 "내 출생 차트를 계산해줘"라고 요청하면, 모델은 실제 계산 과정 없이 그럴듯하게 들리는 행성 위치를 만들어내는 환각 (hallucination) 현상을 일으킬 것입니다. 이는 무용지물인 것보다 더 나쁩니다. 확신에 차서 틀리는 것이기 때문입니다.

해결책은 차트를 생성 작업(generation task)이 아닌 **연산 기본 단위 (compute primitive)**로 취급하는 것입니다. life-chart-engine은 에이전트에게 CLI를 호출하고 --json 봉투(envelope)를 파싱하는 방법을 정확히 알려주는 AGENTS.md 도구 계약(tool contract)을 제공합니다. 이를 저장소에 넣으면 Claude Code(또는 AGENTS.md를 인식하는 모든 에이전트)는 추측을 멈추고 _호출 (calling)_을 시작합니다:

## Tool: life-chart-engine

사용자가 점성술/Human Design/자미두수 차트를 요청하면,
...

이제 에이전트는 결정론적인 숫자에 대한 얇은 해석기(thin interpreter) 역할을 수행합니다. 수학적 계산은 감사(auditable) 가능하며, LLM은 자신이 잘하는 부분인 '설명'에만 집중합니다.

교차 시스템 삼각 측량 (그리고 정직성 조항)

왜 세 가지 시스템일까요? 동일한 출생 시점에 대해 세 가지의 독립적인 계산을 수행하면 저렴한 비용으로 신뢰 신호(confidence signal)를 얻을 수 있기 때문입니다. 서양 점성술, Human Design, 그리고 자미두수가 독립적으로 동일한 테마를 가리킬 때, 그것은 강력한 신호가 됩니다. 반면 단 하나의 시스템만이 특정 세부 사항을 드러낸다면, 그것은 절대적인 진리가 아닌 참고 자료로 취급해야 합니다.

이 도구의 정체성을 명확히 하자면, 이것은 숙명론적인 예측이 아니라 **해석적 자기 인식 도구 (interpretive self-awareness tool)**입니다. 의료, 법률 또는 금융 조언을 제공하지 않습니다. README에도 명시되어 있으며, 저는 이를 엄격히 준수합니다. 엔진은 계산할 뿐이며, 의미를 부여하는 것은 사용자의 몫입니다.

문서는 19개 언어로 제공되며, 전체 라이선스는 AGPL-3.0이고, Wi-Fi가 꺼진 비행기 안에서도 작동합니다. 만약 여러분이 AI 에이전트를 구축한다면, 여기서 얻을 수 있는 교훈은 점성술을 넘어 일반화될 수 있습니다: 정답이 존재하는 경우, 모델에게 즉흥적으로 임기응변을 하라는 프롬프트를 주는 대신 호출할 수 있는 결정론적인 기본 단위 (deterministic primitive)를 제공하십시오. 이것이 진짜 교훈입니다. 근거(ground truth)가 있는 도메인은 확신에 찬 추측이 아니라 감사 가능한 연산을 필요로 합니다.

Repo: https://github.com/zhenheco/life-chart-engine — 이슈와 PR을 환영합니다.