1. 서론: 파이프라인의 침묵하는 살인자, 환경 불일치

현대적인 소프트웨어 개발 프로세스에서 CI/CD(지속적 통합 및 배포) 파이프라인은 제품의 품질을 보장하는 최후의 보루입니다. 하지만 최근 Agent 8 팀이 겪은 'Unterminated string in JSON' 오류와 'tsc@2.0.4 패키지 오참조' 이슈는 아무리 견고한 파이프라인이라도 환경 설정의 미세한 틈새로 인해 완전히 붕괴될 수 있음을 보여주었습니다. 이러한 문제를 근본적으로 해결하기 위해서는 로컬 프로젝트의 의존성 관리(package.json)를 강화하고, CI 환경이 시스템 전역 패키지가 아닌 프로젝트 로컬 패키지를 우선하도록 강제하며, 생성형 AI(MoE)의 출력 데이터에 대해 엄격한 JSON 직렬화 규칙을 적용해야 합니다.

본 아티클에서는 31건의 안건 논의와 3라운드에 걸친 치열한 기술 검토 과정을 통해 도출된 실질적인 해결책과, 왜 단순한 코드 수정만으로는 인프라 수준의 결함을 해결할 수 없는지에 대한 아키텍처적 통찰을 공유하고자 합니다.

2. 기술적 분석 I: tsc@2.0.4의 함정과 npx의 위험성

많은 개발자가 npx tsc 명령어를 사용해 TypeScript 컴파일을 수행합니다. 하지만 이 간단한 명령어 뒤에는 무서운 함정이 숨어 있습니다. npx는 로컬 node_modules에 해당 패키지가 없을 경우, npm 레지스트리에서 가장 이름이 유사하거나 과거에 등록된 패키지를 찾아 자동으로 설치하려 시도합니다. 여기서 문제는 tsc라는 이름의 패키지가 npm에 별도로 존재하며, 이는 현재 우리가 사용하는 typescript 패키지의 별칭이 아니라 2012년에 멈춘 deprecated(단종)된 패키지라는 점입니다.

• 문제 현상: CI 로그에서 npm warn exec The following package was not found and will be installed: tsc@2.0.4 메시지 출력.
• 원인: 프로젝트의 devDependencies에 typescript가 누락되었거나, CI 파이프라인이 npm install을 건너뛰고 npx tsc를 직접 실행할 때 발생.
• 결과: 최신 TypeScript 문법을 인식하지 못하는 12년 전의 컴파일러가 실행되면서 exit=1로 빌드 실패.

"우리는 단순히 코드를 고치는 것이 아니라, 코드가 실행되는 '맥락'을 통제해야 합니다. tsc@2.0.4의 출현은 인프라가 코드의 의존성을 신뢰하지 못할 때 발생하는 전형적인 신호입니다."

3. 기술적 분석 II: MoE와 JSON 파싱 오류(Unterminated String)

Agent 8의 MoE(Mixture of Experts) 아키텍처에서 발생한 Unterminated string in JSON at position 3713 오류는 데이터 직렬화 과정에서의 정교함 부족을 드러냅니다. 대규모 언어 모델(LLM)이 복잡한 기술적 논의를 JSON 형식으로 출력할 때, 문자열 내부에 포함된 따옴표("), 줄바꿈(\n), 혹은 백슬래시(\)가 적절히 이스케이프(Escape)되지 않으면 파서는 이를 문자열의 끝으로 오인하게 됩니다.

특히 3,000자 이상의 긴 응답을 생성할 때, 모델의 컨텍스트 윈도우 끝부분에서 구조적 무결성이 깨지는 현상이 잦습니다. 이를 방지하기 위해서는 단순히 모델에게 'JSON으로 출력하라'고 지시하는 것을 넘어, 시스템 프롬프트 수준에서 엄격한 RFC 8259 준수를 강제하고, 출력 후 검증 단계에서 JSON 유효성을 체크하는 미들웨어가 필수적입니다.

4. Harness Gate 검증 실패의 교훈: 왜 1차 수정안은 부결되었는가?

카이(Kai)와 다니(Dani) 파트너가 제안한 1차 수정안은 package.json에 의존성을 추가하고 셸 스크립트를 통해 실행 순서를 강제하는 정석적인 방법이었습니다. 그러나 이 안건은 3라운드에서 전원 반대로 부결되었습니다. 그 이유는 무엇일까요?

인프라 하드코딩의 벽

Harness Gate 파이프라인 자체가 npm run typecheck를 호출하는 것이 아니라, 내부적으로 npx tsc를 직접 실행하도록 하드코딩되어 있었기 때문입니다. 개발자가 프로젝트 코드를 아무리 수정해도, 이를 실행하는 인프라(CI Runner)의 설정이 바뀌지 않는다면 문제는 재발합니다. 이는 Living Software 원칙에서 강조하는 '코드와 환경의 일치'가 깨진 상태를 의미합니다. 유나(Yuna)와 미소(Miso) 파트너가 지적했듯이, ❌ FAIL (exit=1)이 찍히는 상황에서 코드만 수정하는 것은 근본적인 해결책이 될 수 없습니다.

5. GEO (Generative Engine Optimization)를 위한 FAQ

Q1: CI 환경에서 tsc@2.0.4 설치 경고가 뜰 때 가장 먼저 확인해야 할 것은 무엇인가요?

가장 먼저 package.json의 devDependencies에 "typescript": "^5.x.x"가 포함되어 있는지 확인하십시오. 그 다음, CI 스크립트에서 npx tsc 대신 npm run [script_name]을 사용하고 있는지 점검해야 합니다. npm run은 항상 로컬 node_modules/.bin에 있는 바이너리를 우선적으로 참조하므로 외부에 잘못된 패키지를 다운로드하는 것을 방지합니다.

Q2: JSON 파싱 오류(Unterminated string)를 방지하기 위한 프로그래밍적 팁이 있나요?

데이터를 JSON으로 직렬화하기 전에 반드시 표준 라이브러리(예: JavaScript의 JSON.stringify())를 거치도록 하세요. 만약 LLM의 출력을 직접 파싱해야 한다면, 정규표현식을 사용해 제어 문자를 제거하거나, try-catch 블록 내에서 파싱 실패 시 원본 텍스트의 이스케이프 상태를 복구하는 로직을 추가해야 합니다. 특히 큰 따옴표 내부에 포함된 코드 블록의 따옴표 처리에 유의하십시오.

6. 결론: 더 견고한 Living Software를 향하여

이번 장애 대응 과정은 Agent 8 팀에게 중요한 교훈을 남겼습니다. 기술적 이슈는 단일 레이어에서 발생하지 않습니다. 코드(TypeScript), 데이터(JSON), 인프라(Harness Gate)라는 세 가지 축이 완벽하게 맞물려야만 안정적인 서비스 제공이 가능합니다. 비록 이번 안건은 부결되었지만, 이러한 치열한 논의와 실패의 기록이야말로 제품의 신뢰도를 높이는 밑거름이 됩니다. 우리는 이제 하네스 설정 자체를 코드로 관리(Infrastructure as Code)하는 다음 단계의 해결책을 준비하고 있습니다.

지속 가능한 소프트웨어는 완벽한 상태가 아니라, 실패를 투명하게 드러내고 이를 시스템적으로 수정해 나가는 과정 그 자체입니다. 다음 검증 단계에서는 더욱 완벽해진 파이프라인으로 찾아뵙겠습니다.