Naly 엔지니어링 노트: Codex CLI, 구조화 JSON, 그리고 Cron-안전 AI 워커

요약

Naly는 Cron 워크로드용 AI 작업의 제어면으로 Codex CLI를 사용합니다. 각 Cron 항목은 웹 검색과 엄격한 출력 계약을 가진 범위 제한 보조 작업을 시작하는 체크인된 스크립트를 실행하고, 이후 하류 발행·재생성·재시도를 위해 검증된 JSON 아티팩트를 기록합니다. 이는 모델 작업이 가변적인 대화형 워크플로가 아닌 운영 파이프라인처럼 동작하게 합니다. 즉 동일한 명령, 명시적 스키마, 명시적 아티팩트가 보장됩니다. 2026-06-25 기준으로 이 구분은 성장 핵심 콘텐츠 인프라에서 신뢰성 우위를 만듭니다.

Naly에서의 위치

Naly는 이미 발견, 유지, 유통 워크플로를 중심으로 GST 우선순위를 운영하고 있습니다. 이 패턴은 실행 계층과 바로 맞습니다.

Cron 작업은 단일 tsx 각 사용 사례당 하나의 스크립트를 호출해, 즉석 셸 스니펫이 아니라 버전 관리된 코드 안에서만 실행되도록 합니다.
Codex CLI가 추론 및 검색 작업을 수행하고, Naly는 오케스트레이션 제어를 담당합니다. 즉 스케줄링, 재시도, 잠금, 영구 아티팩트 관리입니다.
구조화된 출력은 Next.js, React, Drizzle ORM, Neon 기반 하류 시스템에 스키마 추론 없이 직접 연결됩니다.
외부 로그와 실행 메타데이터는 NALY_LOG_ROOT에 기록되어 프로세스 출력 버퍼링과 무관하게 사후 분석이 재현 가능해집니다.

핵심 가설은 다음과 같습니다. 운영 환경에서는 LLM 품질이 시스템의 절반일 뿐이며, 그 LLM을 둘러싼 결정론적 경계가 나머지 절반입니다.

기술적 메커니즘

1) 계약 우선 워커 엔트리포인트

각 작업은 세 가지 불변 입력으로 시작합니다.

정의된 프롬프트 템플릿과 작업 의도입니다.
검증해야 하는 응답 스키마입니다.
실행 컨테이너(run_id, source_query, attempt, env), API 호출 전에 영속화합니다.

Naly는 대화형 모드가 아닌 배치 모드로 Cron에서 Codex CLI를 호출합니다. Codex는 로컬 코딩 에이전트로 문서화되어 있으며 오픈 소스 배포와 활성 릴리스를 갖춘 독립형 CLI로 제공되어, 스크립트 환경에서 실행할 수 있습니다. Codex CLI, OpenAI Codex repository.

2) 구조화 출력이 반드시 필요한 이유

OpenAI 구조화 출력 가이드는 파서 지원 스키마 추출과 머신 파이프라인에 필요한 strict 모드 동작을 설명합니다. Naly에서는 모델 출력이 최종 진실이 아니라 중간 산출물이므로 JSON 계약이 신뢰성을 적용하는 지점입니다.

필수 필드(헤드라인, 근거 목록, 신뢰도, 인용, 실패 사유)
기본값이 있는 선택 필드
수치 신뢰도 및 제한된 열거형
파서 실패를 조용히 자동 수정하는 대신 실행 오류로 명시적으로 노출합니다.

3) 동시성 제어가 포함된 Cron-to-agent 생명주기

Cron은 표준 5개 필드 타이밍 형식에 따라 스케줄된 라인을 실행하며, 필드가 일치할 때 명령을 실행합니다. crontab. 운영 안전성 확보를 위해 Naly는 다음을 추가합니다.

잠금 가드(작업당 단일 활성 실행)
멱등성 있는 실행 키
지터가 적용된 제한된 재시도 정책
모든 단계의 외부 로그 수집
Drizzle/Neon으로 관리되는 데이터베이스 테이블에서 실행 후 상태 업데이트

flock 이 패턴에 맞게 설계된 가드레일은 잠금을 획득하고 핵심 구간을 실행한 뒤, 이미 잠금 중이면 정상적으로 종료하는 방식입니다. flock. 잠금 상태가 파일 디스크립터를 따르므로, 겹치는 Cron 윈도우가 상태를 망가뜨리는 대신 명시적으로 거부됩니다.

4) 이 패턴에서 MCP가 중요한 이유

모델 컨텍스트 프로토콜은 JSON-RPC, 기능 협상, 구조화된 도구 호출을 통해 호스트/클라이언트/서버의 도구 계약을 형식화합니다. MCP. Naly에서 MCP 스타일 경계는 암묵적 결합도를 낮춥니다. 웹 검색을 임의 셸 동작이 아닌 명시적 기능을 가진 제어된 도구 인터페이스로 표현할 수 있기 때문입니다.

문헌은 다음을 말합니다

최신 연구는 신뢰성이 단순한 원천 역량과 같지 않다고 보여줍니다. AI Agent Reliability 논문은 작업 정확도와 실행 일관성 사이의 큰 격차를 보고하고, 운영 평가를 위해 일관성·강건성·예측가능성·안전성 같은 명시적 신뢰성 차원을 제안합니다. Towards a Science of AI Agent Reliability이것은 Naly의 실행 상태 우선 설계를 지지합니다. 실행이 성공했더라도 명확한 아티팩트로 반복 재현할 수 없으면 운영 품질이 아닙니다.

구조화된 출력의 경우 ToolPRM은 구조화된 도구 호출 동작이 명시적 감독을 필요로 하며, 특히 최종 결과만 다루는 접근보다 내부 함수 호출 과정을 모델링할 때 성능 개선 효과가 더 크다는 점을 보여줍니다. ToolPRM: Fine-Grained Inference Scaling of Structured Outputs for Function Calling. 이는 Naly의 스키마 우선 러너 루프와 일치합니다. 품질 게이트는 콘텐츠 유창성 자체가 아니라 인터페이스 경계에 있습니다.

같은 영역의 세 번째 논문인 SLOT은 LLM 위에 모델 비의존 출력 형성 계층을 추가해 실용적인 대안 경로를 제시합니다. SLOT: Structuring the Output of Large Language Models. 이는 같은 원칙을 강화합니다. 기본 모델 품질이 높더라도 구조적 신뢰성은 여전히 엔지니어링 문제입니다.

설계 트레이드오프

엄격한 스키마 vs 모델 이식성: 엄격한 스키마는 하류 모호성을 줄이지만, 제공자가 제약을 다르게 해석하면 파싱 변경이 간헐적으로 증가할 수 있습니다.
Cron 단순성 vs 큐 탄력성: Cron은 단순하고 가시적이지만, 급증하는 워크로드에서는 잠금 인지 백오프 또는 큐 계층이 없으면 겹치는 실행과 놓친 창을 피하기 어렵습니다.
작업 내 웹 검색 vs 결정론적 재실행: 최신 웹 검색은 신선도를 높이지만 소스 변동성을 유발하므로, Naly는 쿼리 텍스트·소스 목록·원본 참조를 실행 아티팩트에 저장합니다.
외부 로그 vs DB 전용 로그: 파일시스템 로그는 프로세스 재시작 후에도 남고 수집 비용이 낮지만, DB 로그는 쿼리 사용성이 좋으나 파티셔닝을 잘못하면 열린 루프 실패를 유발할 수 있습니다.

실패 모드

스키마 드리프트: 제공자 출력이 스키마를 위반합니다. 완화 방법은 엄격한 유효성 검사 fail-fast, 스키마 버전 고정, 데드 레터 실행입니다.
Cron 중복 실행: 중복 쓰기 또는 중복 외부 동작; 완화 방법은 advisory lock와 프로세스 종료 가드입니다.
검색 불안정: 시도마다 상위 도구 응답이 바뀝니다. 완화 방법은 재시도 상한, 지수 백오프, 저장된 상위 참조 유지입니다.
시간 관련 이슈: DST와 호스트 타임존 차이로 일정 해석이 달라질 수 있습니다. 완화 방법은 UTC 스케줄 정책과 명시적 환경 점검입니다.
침묵적 부분 쓰기: 파싱은 성공했지만 하류 쓰기가 실패합니다. 완화 방법은 트랜잭션 영속성 순서 제어와 멱등적 upsert입니다.
보안/컨텍스트 유출: 도구를 실행할 수 있는 에이전트 경로는 범위를 벗어날 수 있으므로 MCP 스타일 최소 권한 경계와 명시적 동의/인증 가정이 필요합니다. 특히 도구 실행 경로가 네트워크 자원에 닿는 경우 더 중요합니다. MCP 보안 노트.

구현 노트

비즈니스 작업당 하나의 워커 명령을 scripts/ 보관하고 cron은 해당 엔트리포인트만 호출하세요.
모델 업그레이드 후에도 파서 기대치를 감사할 수 있도록 스키마 파일 해시를 실행 메타데이터에 저장합니다.
래퍼 스크립트에서 set -euo pipefailset -e 스타일 동작을 설정하고 로그 이름에 항상 run ID를 포함합니다.
로그에 세 가지 체크포인트를 기록합니다. started, codex_result_parsed, artifact_persisted.
사용하여 NALY_LOG_ROOT 런타임 추적 데이터가 저장소 상태를 오염시키지 않고 재시작 컨텍스트에서도 유지되도록 합니다.
영속화하고 attempt, exit_code, retry_reason, 및 validation_errors 하여 GST 및 감사 대시보드가 불안정한 인프라 이슈와 실제 모델 회귀를 분리하도록 합니다.