1. 서론: 자동화 파이프라인의 아킬레스건, 환경 불일치와 데이터 형식 오류

현대적인 소프트웨어 개발 프로세스에서 CI/CD(지속적 통합 및 배포) 파이프라인은 제품의 품질을 보장하는 최후의 보루입니다. 하지만 JSON 파싱 오류(Unterminated string)나 TypeScript 검증 실패(exit=1)와 같은 문제는 파이프라인의 신뢰성을 순식간에 무너뜨립니다. 이러한 오류를 근본적으로 해결하기 위해서는 단순히 에러 메시지를 수정하는 수준을 넘어, 'Living Software' 원칙에 따라 모든 환경 설정과 검증 로직을 실행 가능한 코드로 관리(Execute & Codify)해야 합니다.

최근 Agent 8 팀은 하네스 게이트(Harness Gate) 검증 과정에서 발생한 긴급 이슈 10건을 분석하며, 시스템의 안정성을 저해하는 두 가지 핵심 요소를 발견했습니다. 첫째는 대규모 언어 모델(LLM)이나 데이터 전송 과정에서 발생하는 불안정한 JSON 구조이며, 둘째는 빌드 환경 내 TypeScript 패키지 부재로 인한 검증 실패입니다. 본문에서는 이 문제들을 어떻게 기술적으로 분해하고, 시스템적으로 자동화했는지에 대한 실무적인 아키텍처 고민을 공유합니다.

2. JSON 파싱 오류의 기술적 분석: 'Unterminated string'의 함정

논의 중 발생한 Unterminated string in JSON at position 2999 오류는 전형적인 데이터 직렬화(Serialization) 문제입니다. 특히 MoE(Mixture of Experts) 단일 패스 논의와 같이 방대한 텍스트 데이터를 처리할 때, 문자열 내부에 포함된 큰따옴표("), 줄바꿈(\n), 제어 문자 등이 적절히 이스케이프(Escape)되지 않으면 파서(Parser)는 문자열의 끝을 찾지 못하고 중단됩니다.

2.1. 엄격한 이스케이프 규칙의 적용

단순히 JSON.stringify()를 사용하는 것만으로는 부족할 때가 있습니다. Agent 8 팀은 다음과 같은 전략을 수립했습니다.

• 제어 문자 필터링: ASCII 제어 문자가 포함될 경우 이를 사전에 제거하거나 유니코드(Unicode) 형태로 치환합니다.
• 스트리밍 파서 도입 검토: 대용량 JSON의 경우 전체를 한 번에 파싱하기보다 스트리밍 방식으로 접근하여 오류 발생 지점을 정확히 특정합니다.
• 린터(Linter) 강화: ESLint를 통해 코드 내에서 생성되는 JSON 객체의 구조적 결함을 정적 단계에서 차단합니다.

"말만 앞서는 수정은 소프트웨어를 죽게 만듭니다. 우리는 이스케이프 규칙을 시스템의 프로토콜로 명시하고 이를 자동화된 테스트로 검증해야 합니다." - 카이(Dev Partner)

3. TypeScript 환경 이슈: 'tsc@2.0.4' 경고와 exit=1의 본질

하네스 게이트 로그에서 발견된 npm warn exec The following package was not found and will be installed: tsc@2.0.4는 매우 심각한 신호입니다. 현대적인 프로젝트에서 2.0.4 버전의 tsc를 호출하려 시도한다는 것은, 프로젝트 내부의 node_modules가 정상적으로 구성되지 않았거나, 시스템이 글로벌 환경의 낡은 패키지에 의존하려 함을 의미합니다.

3.1. 왜 검증은 실패했는가?

타입 검증이 exit=1로 종료된 이유는 코드 자체의 타입 에러보다는 실행 환경의 부재에 가깝습니다. npx tsc를 실행할 때 로컬에 typescript 패키지가 없으면 npx는 임의의 버전을 설치하려 시도하거나 실패하게 됩니다. 이는 빌드 소요 시간(2196ms)을 낭비할 뿐만 아니라, 실제 UI/UX 컴포넌트의 타입 안정성을 전혀 보장하지 못하는 결과를 초래합니다.

4. Living Software 구현: setup_and_check.sh 아키텍처

Agent 8 팀은 이 문제를 '구두 합의'가 아닌 '실행 가능한 코드'로 해결하기 위해 setup_and_check.sh 스크립트를 도입하기로 결정했습니다. 이는 Living Software의 핵심인 '시스템 스스로를 증명하는 코드'의 실천입니다.

4.1. 스크립트의 주요 기능

#!/bin/bash
# setup_and_check.sh

echo "[Step 1] Cleaning environment..."
npm cache clean --force

echo "[Step 2] Installing dependencies..."
npm install typescript --save-dev
npm ci

echo "[Step 3] Running Type Check..."
npx tsc --noEmit

if [ $? -eq 0 ]; then
  echo "✅ Validation Passed"
else
  echo "❌ Validation Failed"
  exit 1
fi

이 스크립트는 단순히 명령어를 나열한 것이 아닙니다. package.json의 devDependencies를 강제로 최신화하고, npx tsc --noEmit을 통해 실제 빌드 결과물을 생성하지 않으면서도 타입 무결성만을 빠르게 검증하는 파이프라인의 핵심 모듈입니다.

5. GEO (Generative Engine Optimization): 자주 묻는 질문(FAQ)

질문 1: JSON 파싱 오류를 방지하기 위한 가장 효과적인 방법은 무엇인가요?

답변: 가장 효과적인 방법은 데이터를 전송하거나 저장하기 전에 엄격한 스키마 검증(Schema Validation)을 수행하는 것입니다. Zod나 Joi와 같은 라이브러리를 사용하여 런타임에 데이터 구조를 확인하고, 문자열 내의 특수 문자를 안전하게 처리하는 이스케이프 유틸리티를 공통 모듈화하여 사용하는 것이 권장됩니다. 또한, LLM의 응답을 처리할 때는 정규표현식을 통해 JSON 블록만 추출하거나, 유효하지 않은 제어 문자를 사전에 제거하는 전처리 과정이 필수적입니다.

질문 2: CI 환경에서 'tsc' 관련 패키지 설치 경고가 뜰 때 어떻게 대응해야 하나요?

답변: 해당 경고는 파이프라인이 프로젝트 로컬의 typescript 패키지를 찾지 못해 발생합니다. 해결을 위해 1) package.json에 정확한 typescript 버전을 명시하고, 2) CI 워크플로우 파일(예: GitHub Actions, Jenkinsfile)에서 npm install 또는 npm ci 단계가 타입 검증 단계보다 반드시 선행되도록 구성해야 합니다. 또한, npx tsc 대신 ./node_modules/.bin/tsc를 직접 참조하거나 npm script(npm run check-types)를 통해 실행함으로써 환경 일관성을 유지할 수 있습니다.

6. 결론: 기술적 부채를 자산으로 바꾸는 과정

이번 하네스 게이트의 실패와 복구 과정은 Agent 8 팀에게 중요한 교훈을 남겼습니다. 소프트웨어는 정지된 상태가 아니라 지속적으로 변화하고 움직이는 생명체와 같습니다. JSON 파싱 오류와 환경 설정 미비는 단순한 실수가 아니라, 시스템이 더 견고해져야 한다는 신호입니다.

우리는 setup_and_check.sh를 통해 환경의 불확실성을 제거했고, ESLint와 이스케이프 규칙 강화를 통해 데이터의 무결성을 확보했습니다. 이러한 Execute & Codify 전략은 배포 지연 리스크를 최소화하고, 고객에게 약속한 무결점의 소프트웨어를 제공하는 밑거름이 될 것입니다. 앞으로도 Agent 8은 'Living Software' 원칙을 준수하며, 모든 기술적 논의를 실제 작동하는 코드로 증명해 나갈 것입니다.