블랙박스 위에 팀을 올리지 마라
AI 도구를 도입할 때 팀 리드가 가장 먼저 하는 실수가 있다. 도구가 작동하면 내부는 몰라도 된다고 생각하는 것이다. Claude Code가 코드를 잘 짜주고, LangChain이 에이전트 파이프라인을 돌려주면 그걸로 충분하다고. 하지만 이번 주 두 편의 기술 분석이 그 가정을 정면으로 뒤집는다. 하나는 Claude Code의 프롬프트 구성 메커니즘을 해부한 소스 분석 시리즈(dev.to)고, 다른 하나는 LangChain·LangGraph·OpenAI Python SDK에서 실제로 터진 프로덕션 버그 다섯 가지를 파헤친 디버깅 리포트(dev.to)다. 두 글을 겹쳐 읽으면 하나의 결론이 나온다. 도구 내부를 이해하지 못하면 리스크를 설계할 수 없다.
Claude Code는 프롬프트를 '실행할 때마다 새로 조립'한다
많은 팀이 Claude Code를 쓸 때 이렇게 가정한다. '좋은 시스템 프롬프트 하나면 된다.' 틀린 말은 아니지만, 표면만 긁은 것이다. Claude Code 소스 분석에 따르면, 이 도구는 모델을 호출할 때마다 프롬프트를 정적 템플릿에서 꺼내는 게 아니라 런타임에 매번 새로 어셈블한다.
구체적으로는 여섯 개 레이어가 순서대로 합산된다. 베이스 시스템 룰, 현재 모드와 프로젝트 메모리(CLAUDE.md), Git 상태 같은 런타임 컨텍스트, 사용 가능한 도구 스키마와 MCP 캐퍼빌리티, 이전 대화 히스토리와 툴 호출 결과, 그리고 사용자의 최신 입력. 이 여섯 가지가 우선순위 체인에 따라 충돌을 해소하며 조합된다.
우선순위 체인은 이렇게 생겼다. overrideSystemPrompt(루프·포크 모드에서 모든 것을 덮어씀) → Coordinator 프롬프트 → Agent 프롬프트 → customSystemPrompt(CLI --system-prompt) → defaultSystemPrompt → appendSystemPrompt. 단순 이어붙이기가 아니라 어느 소스가 어느 소스를 이기는가를 명시적으로 결정하는 구조다.
이게 팀 리드에게 왜 중요한가? 팀원이 --system-prompt로 커스텀 룰을 주입하거나, CLAUDE.md를 프로젝트별로 다르게 설정하거나, MCP 도구를 붙였을 때 실제로 모델이 어떤 컨텍스트를 받게 되는지 예측할 수 없으면 에이전트 행동의 일관성을 보장할 수 없다. '프롬프트를 잘 썼으니 됐겠지'가 아니라, 런타임에 어떤 레이어가 어떤 순서로 결합되는지를 팀이 공유된 모델로 이해하고 있어야 한다.
프로덕션 버그는 경계(Boundary)에서 터진다
이번 주 디버깅 리포트는 70개 이상의 오픈 이슈를 뒤진 결과물이다. 다섯 가지 버그를 관통하는 패턴이 하나 있다. 모든 버그는 코드와 외부 시스템의 경계에서 발생했다.
대표적인 사례 두 가지만 짚는다. 첫째, LangChain의 _create_usage_metadata는 cached_tokens가 없을 때 딕셔너리에 None을 명시적으로 저장하고, 이후 .get(key, 0)이 키가 있다고 판단해 None을 반환한다. 이 버그는 캐시드 토큰을 활성화하고 서비스 티어를 쓸 때만 터진다. 정확히 비용 최적화를 시도할 때, 즉 프로덕션 트래픽에서만 발생하는 버그다. 개발 환경에서는 절대 안 보인다.
둘째, SSRF 취약점이다. LANGCHAIN_ENV=local_test로 환경변수를 설정하면 URL 검증 로직이 통째로 스킵된다. 로컬 허용 범위를 넓히는 게 아니라 검증 자체를 건너뛰는 구조다. 컨테이너 설정 실수나 dev-staging 프로모션 오류로 이 환경변수가 그대로 올라가면 CVE급 공격 경로가 열린다.
나머지 세 버그도 같은 패턴이다. LangGraph create_agent는 이전 턴의 structured_response를 초기화하지 않아 다음 턴에 에이전트가 LLM 호출 없이 바로 종료된다. OpenAI Python SDK 스트리밍 어큐뮬레이터는 item=None 이벤트에 하드 크래시한다. AWS Bedrock Converse 변환기는 빈 텍스트 블록 처리에서 예외를 던진다. LLM 프로바이더가 돌려주는 ambiguous null, 스트리밍 이벤트의 스키마 불일치, 환경변수로 제어되는 보안 분기, 체크포인트 상태의 턴 간 오염—이 네 영역이 AI 앱 프로덕션 버그의 80%가 사는 곳이다.
팀 리드가 설계해야 할 것
두 분석을 합치면 실전 시사점이 명확해진다.
첫째, 컨텍스트 어셈블리를 팀의 공유 지식으로 만들어라. Claude Code가 런타임에 어떤 레이어를 어떤 순서로 결합하는지, CLAUDE.md와 MCP 도구가 충돌할 때 어느 쪽이 이기는지를 팀원 모두가 이해해야 에이전트 행동의 일관성을 설계할 수 있다. 이건 프롬프트 엔지니어링 문제가 아니라 아키텍처 이해의 문제다.
둘째, 경계 코드(boundary code)를 별도 감사 대상으로 분리해라. LLM 프로바이더 응답 파싱, 스트리밍 이벤트 처리, 체크포인트 상태 초기화, 환경변수 게이트 분기—이 네 영역은 AI 라이브러리 버그가 집중되는 곳이다. CI에서 이 경계 레이어를 집중적으로 테스트하는 전략이 필요하다.
셋째, 라이브러리 버전을 고정하고, 버그 트래킹을 팀 루틴에 넣어라. LangChain·LangGraph·OpenAI SDK는 빠르게 변한다. 위에서 언급한 버그들은 모두 지금도 열려 있는 GitHub 이슈다. 팀에서 사용 중인 라이브러리의 오픈 이슈를 주기적으로 리뷰하는 것이 선택이 아닌 운영 루틴이 되어야 한다.
도구를 이해하는 팀이 리스크를 통제한다
AI-First 워크플로우에서 도구 내부를 이해하는 것은 선택적 심화 학습이 아니다. Claude Code의 프롬프트 어셈블리 구조를 모르면 에이전트가 왜 그 행동을 했는지 설명할 수 없고, AI 라이브러리의 경계 버그 패턴을 모르면 프로덕션에서 터지기 전까지 위험을 감지할 수 없다.
팀 리드의 역할은 도구를 빠르게 도입하는 것만이 아니다. 도구가 어떻게 작동하는지 이해하고, 그 이해를 팀의 설계 언어로 번역하는 것이다. 블랙박스 위에 올린 시스템은 블랙박스가 흔들릴 때 같이 흔들린다.