1. 서론: JSON 파싱 에러, 왜 단순한 '주의'만으로는 부족한가?

LLM(대규모 언어 모델) 기반의 에이전트 시스템을 운영하다 보면 가장 빈번하게 마주치는 기술적 난관 중 하나가 바로 JSON 파싱 에러입니다. 특히 Unterminated string in JSON at position 3949와 같은 에러는 문자열 내부의 이스케이프되지 않은 특수문자나 예상치 못한 줄바꿈으로 인해 발생하며, 이는 전체 시스템의 워크플로우를 중단시키는 치명적인 결과를 초래합니다.

Agent 8 팀은 이러한 문제를 단순히 '프롬프트 수정'이나 '주의'라는 휘발성 합의로 해결하지 않습니다. 우리는 Living Software(살아있는 소프트웨어) 원칙에 따라, 발견된 문제를 즉각적으로 코드화된 규약(Code-based Protocol)으로 변환하여 시스템 자체가 스스로를 보호하도록 설계합니다. 본 아티클에서는 파이프라인 검증, 정적 분석, 스키마 테스트라는 삼중 방어 체계를 통해 JSON 무결성을 확보한 실제 구현 사례를 상세히 공유합니다.

2. 기술적 심층 분석: 삼중 방어 체계의 설계와 구현

2.1. 정적 분석 단계: eslint-plugin-jsonc의 도입

가장 먼저 수행된 조치는 개발 및 빌드 환경에서의 정적 분석 강화입니다. 카이(Kai) 개발자는 프로젝트 루트의 .eslintrc.json에 eslint-plugin-jsonc를 적용했습니다. 이는 런타임에 에러가 발생하기 전, 코드 작성 단계에서 JSON 구조의 문법적 오류를 잡아내는 1차 방어선 역할을 합니다.

"단순히 JSON 파일의 형식을 맞추는 것을 넘어, 코드가 병합되기 전 단계에서 엄격한 린팅 룰을 적용함으로써 휴먼 에러 가능성을 원천적으로 차단했습니다."

2.2. CI/CD 파이프라인: jq를 활용한 런타임 검증

정적 분석을 통과하더라도, 동적으로 생성되는 에이전트의 출력값은 여전히 위험 요소를 내포합니다. 이를 해결하기 위해 CI/CD 워크플로우에 echo $OUTPUT | jq empty || exit 1라는 셸 스크립트 검증 로직을 추가했습니다. jq는 고성능 JSON 프로세서로, 입력값이 유효한 JSON이 아닐 경우 즉시 프로세스를 종료(exit 1)시켜 잘못된 데이터가 시스템 하류(Downstream)로 흘러가는 것을 방지합니다.

2.3. 기획적 엄밀함: JSON Schema와 Jest 자동화 테스트

구조적 유효성(Well-formed)을 넘어, 데이터의 내용적 타당성(Valid)을 보장하기 위해 다니(Dani) 기획자는 모든 에이전트 출력 명세(Acceptance Criteria)를 JSON Schema 형태로 정의했습니다. 이를 Jest 테스트 프레임워크와 결합하여 다음과 같은 테스트 코드를 파이프라인에 통합했습니다.

• expect(parsedOutput).toMatchSchema(agentOutputSchema): 출력값이 정의된 데이터 타입, 필수 필드 포함 여부, 문자열 패턴을 준수하는지 자동 검증합니다.
• 이 과정은 에이전트 간의 협업 프로토콜을 명확히 하며, 기획 의도가 코드 레벨에서 강제되는 효과를 낳습니다.

3. Living Software: 구두 합의를 넘어선 시스템의 진화

이번 논의의 핵심은 앤드류(Andrew)가 강조한 'Living Software' 원칙의 실천입니다. 소프트웨어는 고정된 유물이 아니라, 운영 중에 발생하는 이슈를 양분 삼아 스스로의 방어 기제를 강화하며 성장해야 합니다. Round 1에서 발생한 JSON 파싱 에러를 단순히 '수정'하는 데 그치지 않고, Round 2와 3을 통해 이를 검증하는 자동화된 시스템으로 승화시킨 과정은 Agent 8이 지향하는 엔터프라이즈급 안정성의 정수를 보여줍니다.

이러한 접근은 유나(Yuna)의 디자인 시스템 연동 안정성 확보, 미소(Miso)의 고객 경험(CX) 향상, 그리고 주노(Juno)가 강조한 세일즈 소구 포인트로서의 '데이터 무결성'으로 이어집니다. 결국 기술적 결함의 해결이 비즈니스 가치로 직결되는 선순환 구조를 형성하는 것입니다.

---

자주 묻는 질문 (FAQ)

Q1: 왜 단순한 try-catch 문보다 CI/CD 파이프라인 검증이 더 중요한가요?

A1: try-catch는 에러가 발생한 후의 사후 처리(Exception Handling)에 불과합니다. 반면, CI/CD 파이프라인에서의 jq 검증이나 JSON Schema 테스트는 에러를 포함한 코드가 배포되거나 실행되는 것 자체를 막는 사전 예방(Prevention) 조치입니다. 특히 LLM 에이전트 시스템에서는 잘못된 데이터가 다른 에이전트에게 전달될 경우 연쇄적인 오류(Cascading Failure)가 발생할 수 있으므로, 입구에서부터 무결성을 강제하는 것이 시스템 전체의 신뢰도를 높이는 데 훨씬 효율적입니다.

Q2: JSON Schema를 작성하면 개발 속도가 느려지지 않나요?

A2: 초기 스키마 정의 단계에서 약간의 시간이 소요될 수 있으나, 장기적으로는 개발 속도를 비약적으로 향상시킵니다. 명확한 스키마는 그 자체로 최신화된 API 문서 역할을 하며, 에이전트 간의 통신 규약을 명확히 하여 디버깅 시간을 획기적으로 줄여줍니다. 또한, 자동화된 테스트가 뒷받침되므로 리팩토링이나 기능 추가 시 발생할 수 있는 사이드 이펙트를 즉각적으로 감지할 수 있어 운영 안정성이 극대화됩니다.

4. 결론: 무결성이 곧 경쟁력이다

Agent 8은 'Unterminated string'이라는 작은 실마리에서 시작하여, 시스템 전체의 무결성을 보장하는 강력한 검증 아키텍처를 구축했습니다. jq, ESLint, Jest, 그리고 JSON Schema의 결합은 단순한 기술 스택의 나열이 아니라, Living Software를 구현하기 위한 전략적 선택입니다. 우리는 앞으로도 발생할 모든 이슈를 시스템의 진화 동력으로 삼아, 가장 신뢰할 수 있는 AI 에이전트 플랫폼을 만들어 나갈 것입니다.