Kimi·Qwen·GLM 중국 AI 에이전트 실전

1장 중국 AI 에이전트 쇼크를 과장 없이 읽는다

2026년 7월 16일 Moonshot AI는 Kimi K3를 공개했다. “GPT-5.6과 Fable을 이겼다”는 문장은 일부는 맞고 전체로는 틀리다. 공개 당일 Arena 발표를 인용한 보도에 따르면 K3는 Frontend Code Arena에서 1,679점을 기록해 GPT-5.6 Sol과 Claude Fable 5보다 높았다. 이 평가는 정답률 시험이 아니라 블라인드 결과에 대한 사람의 선호를 Elo 방식으로 집계한 라이브 순위다. 표본과 순위는 계속 변한다. Moonshot의 기술 블로그도 종합 성능은 두 폐쇄형 모델보다 뒤진다고 적었다. Artificial Analysis의 2026년 7월 19일 화면에서 K3의 지능 지수는 57점이었다. 결론은 세계 1등 선언이 아니라 “작업별 강점이 달라 라우팅과 재검증이 중요해졌다”이다.

모델, 에이전트, 하니스, 제품도 구별해야 한다. Kimi K3는 기반 모델이다. Kimi Agent는 계획과 도구를 묶은 제품, Kimi Code는 저장소·셸·테스트를 다루는 코딩 하니스다. 같은 모델도 하니스가 파일을 어떻게 읽고, 권한을 언제 묻고, 오류를 어떻게 회복하는지에 따라 결과가 달라진다.

“오픈”이라는 단어도 기준일을 붙인다. Moonshot은 K3를 open 3T-class 모델로 소개했지만 전체 가중치는 2026년 7월 27일까지 공개하겠다고 예고했다. 7월 19일 Artificial Analysis 페이지는 가중치 미공개 상태를 반영해 proprietary로 분류했다. 따라서 이 초판은 K3를 공개 가중치를 예고한 모델이라고 쓴다. 실제 파일, 라이선스, 상업 이용 조건을 확인하기 전에는 “누구나 자유롭게 자체 호스팅할 수 있다”고 확대하지 않는다.

실습: 한 문장을 세 층으로 분해하기

claims/kimi-k3-verdict.md를 만들고 다음 표를 채운다.

모든 기록에 observedAt, 원문 URL, 평가 조건을 붙인다. “능가”에는 반드시 “어떤 평가에서”를 붙인다. 가중치 공개 예정처럼 미래형 발표는 완료 사실로 쓰지 않는다.

체크포인트

• 회사 발표와 독립 평가를 한 열에 섞지 않았는가?
• 순위의 날짜와 과업을 적었는가?
• 모델과 실제 제품을 구별했는가?

근거: Kimi K3 공식 블로그, Kimi Agent 개요, Artificial Analysis K3, Arena 발표를 인용한 2026-07-17 보도, 신화통신 공개 보도.

↑ 목차로 돌아가기

2장 ChatGPT로 만들 문제를 결정한다

에이전트에게 “중국 진출 도구를 만들어 줘”라고 하면 멋있지만 검증할 수 없는 화면이 나온다. 먼저 ChatGPT와 문제 인터뷰를 한다. 답을 요구하기보다 질문을 생산하게 한다.

당신은 B2B SaaS 제품 전략가다. 한국 고객지원 분석 SaaS가 중국 시장의
제한된 파일럿을 검토한다. 해결책을 제시하지 말고 먼저 다음을 질문하라.
1) 결정권자와 사용자는 누구인가 2) 어떤 결정을 언제 내려야 하는가
3) 틀린 결론의 비용은 무엇인가 4) 반드시 원문 근거가 필요한 주장은 무엇인가
답변 뒤 문제 문장, 비범위, 성공 지표, 위험 질문을 표로 정리하라.

BridgePilot의 문제 문장은 “시장 조사 자료가 부족하다”가 아니다. “제품 리드가 여러 언어의 출처와 AI 요약 사이를 오가느라 결론을 감사할 수 없고, 출시 회의에서 어떤 근거를 사람이 승인했는지 설명하지 못한다”이다.

비범위도 제품을 지킨다. 법률 자문을 하지 않고, 웹사이트에 자동 가입하거나 구매하지 않으며, 승인 없이 고객 데이터를 외부 모델에 보내지 않는다. 성공 기준은 ‘좋아 보임’ 대신 다음처럼 측정한다.

• 결론마다 최소 한 개 공식 근거로 돌아갈 수 있다.
• 원문, 번역, 요약을 구분한다.
• 사람이 판정 사유를 네 글자 이상 남겨야 승인된다.
• 공급자를 바꿔도 같은 결과 계약을 검사한다.
• API 키 없이 전체 사용자 여정을 재현한다.

실습 산출물

workbook/PRODUCT-BRIEF.md에 문제·사용자·비범위·성공 지표를, workbook/USER-JOURNEYS.md에 “프로젝트 생성 → 조사 → 근거 검토 → 사람 승인 → 보고서”를 쓴다. 각 단계에는 정상 상태뿐 아니라 빈 상태, 지연, 출처 없음, 잘못된 번역을 넣는다. ChatGPT가 초안을 만들 수 있지만 제품 책임자가 문장을 승인한다.

↑ 목차로 돌아가기

3장 Codex가 읽는 저장소를 설계한다

ChatGPT의 대화는 설계 재료이고 저장소 파일이 정본이다. Codex가 매번 같은 규칙을 따르려면 루트 AGENTS.md에 목표, 디렉터리, 실행 명령, 완료 조건, 금지 행동을 짧게 적는다.

# BridgePilot 작업 규칙
- 정본 데이터는 fixtures/bridgepilot.json이다.
- 외부 에이전트 결과는 fixtures/inbox에서만 읽는다.
- 변경 후 npm test를 실행한다.
- 출처 URL 없는 claim은 UI에 표시하지 않는다.
- 비밀값, 고객 데이터, 법률 결론을 커밋하지 않는다.

Codex 공식 문서의 중요한 점은 모델 이름보다 실행 경계다. SDK로 프로그래밍 가능한 코딩 스레드를 만들고, MCP 서버 모드에서는 codex와 후속 대화 도구로 저장소 작업을 연결할 수 있다. 샌드박스는 읽기 전용, 작업공간 쓰기, 전체 접근처럼 위험에 맞게 선택한다. 이 책은 기본을 작업공간 쓰기로 두고 외부 네트워크와 파괴적 명령은 별도 승인 대상으로 본다.

공식 멀티에이전트 예제도 PM·디자인·프런트엔드·백엔드·테스트 산출물을 게이트로 연결한다. 핵심은 에이전트 수가 아니라 앞 단계 산출물이 검사에 통과해야 다음 단계가 시작되는 구조다.

첫 GREEN

cd 03-labs
npm run verify

이 명령은 문법과 계약, 저장소, HTTP 요청 핸들러를 검사한다. 포트가 금지된 CI에서도 요청 핸들러를 직접 호출하므로 테스트할 수 있다. 첫 GREEN을 만든 뒤 기능을 추가하면 실패의 원인을 좁힐 수 있다.

근거: Codex SDK, Codex MCP server, 공식 멀티에이전트 워크플로 예제.

↑ 목차로 돌아가기

4장 여러 에이전트가 공유할 작업 봉투를 만든다

긴 대화를 다른 에이전트에게 복사하면 목표, 제한, 완료 조건이 흐려진다. 대신 입력 AgentTask와 출력 AgentResult를 JSON 계약으로 고정한다.

{
  "taskId": "BP-01",
  "role": "research",
  "objective": "중국 개인정보 처리 고지의 공식 근거 3개를 수집한다.",
  "allowedTools": ["web"],
  "constraints": ["정부·법령 원문 우선", "법률 자문 금지"],
  "outputSchema": "evidence-card.v1.json",
  "acceptanceCriteria": ["URL", "원문 인용", "한국어 요약", "확인일"]
}

결과에는 provider, runId, artifacts, errors가 반드시 있다. 실패도 결과다. 조용히 빈 배열을 반환하는 것이 가장 위험하다. src/contracts.mjs의 assertAgentTask와 assertAgentResult는 형식이 다른 산출물을 통합 전에 막는다.

실패를 직접 보라

objective를 조사로 줄이고 테스트를 실행한다. TASK_OBJECTIVE_INVALID가 나와야 한다. 이어 provider를 지우면 RESULT_PROVENANCE_MISSING이어야 한다. 계약은 좋은 답을 보장하지 않지만, 누가 어떤 조건에서 만든 답인지 모르는 상태를 막는다.

2부 TODO 앱이 아닌 실제 서비스를 만든다

↑ 목차로 돌아가기

5장 BridgePilot 사용자 경험을 설계한다

대시보드의 목적은 숫자를 많이 보여 주는 것이 아니라 “지금 무엇을 믿어도 되는가”를 답하는 것이다. 상단에는 진출 준비도와 의사결정 신호, 중간에는 작업 흐름, 하단에는 근거와 전문 작업자를 둔다. 사람의 시선은 결론 → 근거 → 원문 → 판정 순으로 움직인다.

화면 계약은 데이터 계약처럼 쓴다. 로딩 중에는 프로젝트명 자리에 상태를 표시하고, 출처가 없으면 빈 카드가 아니라 필요한 조치를 설명한다. 신뢰도 92%는 정답 확률이 아니라 에이전트가 반환한 보조 신호임을 툴팁에서 밝힌다. 채택 버튼은 사유 입력 대화상자를 연다. 모바일에서는 사이드바를 숨기고 작업 여섯 개를 한 열로 쌓는다.

public/index.html, styles.css, app.js를 함께 읽는다. HTML은 의미 구조와 접근성, CSS는 반응형 계약, JavaScript는 fixture를 화면에 매핑한다. 외부 UI 라이브러리가 없어 설치 실패가 없고, 독자는 브라우저 개발자 도구에서 모든 흐름을 추적할 수 있다.

실습

브라우저 너비를 1440px, 768px, 390px로 바꾼다. 가로 스크롤이 없어야 한다. 다음 근거를 눌렀을 때 ID·원문·요약·출처가 한 묶음으로 바뀌는지 확인한다. 판정하기를 누르고 사유 없이 채택하면 브라우저와 서버 양쪽에서 거부해야 한다.

↑ 목차로 돌아가기

6장 근거가 사라지지 않는 데이터 모델

BridgePilot의 최소 개체는 project, task, run, source, evidence, decision이다. claim만 저장하면 나중에 문장이 어디서 왔는지 알 수 없다. evidence는 quote, summaryKo, url, language, observedAt, runId를 가진다. 번역은 원문을 덮어쓰지 않는다.

URL 중복은 흔하다. evidenceKey는 fragment와 utm_, ref, source 추적 변수를 제거하고 정규화한 URL과 인용문을 결합한다. 같은 페이지라도 다른 문장을 인용하면 다른 근거다. 반대로 동일 인용문과 페이지라면 에이전트가 달라도 하나로 묶고 provenance 목록을 합쳐야 한다.

실전 DB에서는 원문 해시와 수집 시각을 둔다. 페이지가 바뀌면 기존 결론을 자동 수정하지 말고 stale로 표시해 재검토한다. 법령·가격·모델 지원 범위처럼 변동성이 높은 정보에는 reviewAfter를 둔다.

실습

원본 fixture를 직접 고치지 말고 node lab/06-evidence-dedupe.mjs를 실행한다. ?utm_source=test가 붙은 URL은 같은 근거가 되고, 인용문이 바뀌면 별도 근거가 됨을 확인한다. source=law처럼 콘텐츠를 구분할 수 있는 일반 매개변수는 제거하지 않는다. 정규화는 무조건 합치기가 아니라 비교 가능한 단위를 만드는 일이다.

↑ 목차로 돌아가기

7장 조사 작업 API와 상태 기계

에이전트 작업은 요청 한 번으로 끝나지 않는다. queued → running → completed가 정상 경로이고 blocked, failed, cancelled가 옆에 있다. blocked는 입력이나 승인을 기다리는 상태, failed는 같은 입력으로 실행을 끝내지 못한 상태다. 둘을 섞으면 자동 재시도가 사람의 결정을 우회한다.

현재 실습 서버는 Node 표준 http만 사용한다. GET /api/snapshot, GET /api/evidence, POST /api/decisions가 있다. 작은 코어부터 검증한 뒤 실제 배포에서 Fastify나 프레임워크 어댑터로 옮긴다. 핵심 규칙은 프레임워크가 아니라 도메인 함수에 둔다.

const record = store.decide({
  evidenceId: 'EV-001',
  decision: 'accepted',
  reason: '정부 원문과 적용 범위를 대조함'
});

결정 API는 멱등 키를 확장 과제로 둔다. 네트워크 재시도로 같은 판정이 두 번 저장되지 않게 decisionRequestId에 고유 제약을 둔다. 늦게 도착한 에이전트 결과는 현재 작업 버전과 비교하고, 버전이 다르면 자동 채택하지 않는다.

↑ 목차로 돌아가기

8장 실제 대시보드와 근거 비교 UI

app.js의 상태는 작다. snapshot과 현재 evidenceIndex만 가진다. render()는 프로젝트·지표·작업자 목록을, renderEvidence()는 현재 근거를 그린다. 작은 구조 덕분에 독자가 네트워크 응답에서 DOM까지 한 번에 따라갈 수 있다.

중국어 원문에는 lang="zh"를 유지하고 한국어 요약은 별도 문단에 둔다. 링크는 새 탭으로 열되 rel="noreferrer"를 붙인다. 기본 구현은 safe-html.js로 외부 문자열을 escape하고 링크 프로토콜을 HTTP(S)로 제한한다. 더 복잡한 HTML을 허용해야 할 때만 검증된 sanitizer를 추가한다. 안전하지 않은 원문 HTML을 템플릿에 직접 넣지 않는다. 이 경계가 프롬프트 주입과 XSS의 접점이다.

실습: 실패 상태 추가

fixture의 BP-04 상태를 failed로 바꾸고 errors 요약을 화면에 표시한다. 빨간색만 쓰지 말고 “원문 URL 2개가 403을 반환함, 공식 미러 필요”처럼 다음 행동을 적는다. 접근성을 위해 아이콘·텍스트를 함께 쓴다.

↑ 목차로 돌아가기

9장 보고서 생성과 브라우저 검증

보고서는 대시보드의 스크린샷이 아니다. 각 결론에 evidenceIds, 판정자, 판정 시각, 한계를 붙인 오프라인 HTML이다. 링크를 누르면 같은 파일의 근거 절로 이동하고, 원문 URL도 남는다. 외부 스크립트 없이 열려야 고객 보안망에서도 읽을 수 있다.

브라우저 검증은 다음 사용자 여정을 자동화한다. 대시보드 로드, 지표 확인, 다음 근거 이동, 판정 대화상자 열기, 짧은 사유 거부, 정상 사유 채택, 모바일 오버플로 확인이다. 관리형 출간 환경처럼 포트나 Chrome 실행이 금지될 수 있으므로 단위·요청 핸들러 테스트를 기본 게이트로 두고, 실제 브라우저 캡처는 독자 환경과 CI의 선택 게이트로 분리한다.

npm run verify
# 실제 로컬 환경
npm start

본문의 기대 화면은 fixture와 동일한 고정 값으로 제작했다. 독자는 값이 다르면 코드가 아니라 먼저 fixture 버전을 확인한다.

3부 중국 AI 에이전트를 전문 작업자로 투입한다

↑ 목차로 돌아가기

10장 Kimi Agent와 Kimi K3를 해부한다

Kimi 계열을 한 제품처럼 말하면 실습이 꼬인다. K3는 모델, Kimi Agent는 범용 실행 제품, Kimi Work는 문서·표 같은 업무 산출물, Kimi Code는 코딩 하니스다. 공식 발표 기준 K3는 대규모 MoE, 네이티브 비전, 최대 100만 토큰 문맥을 내세웠다. 이 숫자는 장문 입력 가능성을 뜻할 뿐 백만 토큰을 넣으면 정확하다는 보증은 아니다.

Kimi의 좋은 역할은 중국어 원문 탐색과 장문 자료의 후보 추출이다. 최종 법률 판단을 맡기지 않는다. 다음 작업 봉투를 Kimi Agent에 넣는다.

목표: 중국 개인정보보호법의 개인정보 처리 원칙 근거를 찾는다.
허용 출처: 정부·법령 원문, 공식 해설.
출력: URL, 문서명, 중국어 원문 1~3문장, 한국어 직역,
적용 범위, 확인일. 찾지 못하면 missing으로 반환한다.
금지: 법률 자문, 블로그만으로 결론, 인용문 창작.

결과를 fixtures/inbox/kimi-BP-01.json으로 저장하고 스키마 검사 후 가져온다. 원문에서 실제 문장을 검색해 일치 여부를 사람이 확인한다. 긴 문맥에서는 페이지 단위 후보를 먼저 좁힌 뒤 최종 근거를 추출하는 2단계가 더 재현 가능하다.

K3의 벤치마크는 역할 선택의 힌트일 뿐 채택 판정이 아니다. Frontend Code Arena 강점은 UI 후보 생성 실험을 정당화하지만, 보안·백엔드·법규 해석까지 우수하다는 증거는 아니다.

↑ 목차로 돌아가기

11장 Kimi Code로 구현 후보를 만든다

Kimi Code에는 정본 브랜치를 주지 않는다. 별도 worktree나 복제 디렉터리에서 “근거 카드 비교 컴포넌트”처럼 경계가 선명한 작업을 맡긴다. 입력에는 관련 파일, 수용 기준, 테스트 명령, 수정 금지 경로를 적는다.

public/index.html, styles.css, app.js만 수정할 수 있다.
중국어 원문과 한국어 요약을 나란히 비교하는 2열 모드를 추가하라.
390px에서는 1열이어야 하며 기존 판정 흐름을 보존하라.
npm test 결과와 변경 파일 목록을 AgentResult JSON으로 반환하라.

시각적으로 그럴듯한 결과가 가장 위험하다. 테스트 결과가 없다면 completed가 아니라 blocked로 분류한다. Codex는 diff를 읽고 HTML injection, 모바일 overflow, 기존 ID 변경을 검사한다. 후보가 실패하면 프롬프트를 길게 고치기 전에 작업 범위와 수용 기준이 모호했는지 확인한다.

↑ 목차로 돌아가기

12장 Qwen Code와 SubAgent를 사용한다

Qwen Code 공식 문서는 터미널 기반 파일·셸·웹·MCP 사용과 전문 subagent 작업을 설명한다. 2026년 7월 문서의 Agent Tool은 독립 문맥의 하위 작업과 isolation: "worktree"를 지원한다. 이 격리는 이름 있는 subagent_type을 함께 지정하는 경로를 사용한다. 부모 문맥을 공유하는 fork형 하위 에이전트는 작업 디렉터리도 공유할 수 있으므로 둘을 혼동하지 않는다. 장점은 역할 분리지만, 하위 에이전트 수를 늘리면 중복 조사와 비용도 늘어난다.

BridgePilot에서는 두 작업으로 나눈다. localizer는 중국어 UI 용어를 검토하고 validator는 evidence JSON을 검사한다. 두 작업은 서로의 파일을 수정하지 않는다. 결과는 각각 qwen-localizer.json, qwen-validator.json으로 반환한다. 상위 작업자는 요약만 하고 정본 병합은 Codex가 한다.

병렬화 조건은 입력이 고정되고 출력 경로가 겹치지 않는가이다. validator가 localizer 결과를 필요로 하면 순차 작업이다. worktree는 충돌을 줄이지만 논리 충돌까지 없애지는 않는다.

근거(2026-07-19 확인): Qwen Code 개요, Agent Tool, Subagents.

↑ 목차로 돌아가기

13장 Qwen-Agent로 도구형 작업자를 만든다

Qwen-Agent는 Qwen 모델에 도구 호출, 계획, 메모리, 애플리케이션 연결을 제공하는 프레임워크다. 제품 UI와 달리 코드에서 허용 도구와 결과 형식을 통제할 수 있다. 이 책의 도구는 normalize_source 하나로 시작한다.

입력은 URL·문서명·인용문이고 출력은 정규 URL·언어·해시다. 도구는 웹을 다시 탐색하지 않으며 주어진 값을 결정론적으로 변환한다. 모델은 도구를 “호출할지” 정하고, 실제 정규화 규칙은 코드가 소유한다. 이 분리가 중요한 이유는 URL 중복 제거를 모델의 문장 감각에 맡기면 실행마다 달라지기 때문이다.

API가 없으면 fixture provider가 같은 AgentResult를 반환한다. live 어댑터가 추가되어도 도메인 코드는 공급자 응답을 직접 읽지 않는다. 근거: Qwen-Agent 가이드.

↑ 목차로 돌아가기

14장 GLM·AutoGLM·Manus·DeepSeek·MiniMax를 비교한다

이름보다 제품 계층으로 비교한다. Z.ai의 GLM은 기반 모델이고 ZCode는 코딩 에이전트 제품이다. 화면 조작형 에이전트는 코딩 에이전트보다 클릭·전송·구매 권한 위험이 크다. Manus는 공식 문서가 “작업을 완료하고 결과를 전달하는 자율 범용 에이전트”로 설명하는 제품이며 API는 에이전트 작업 생성·관리를 제공한다. DeepSeek은 이 책에서 독립 에이전트 제품이 아니라 다른 하니스에 연결하는 모델/API 후보로 분류한다. MiniMax 역시 공식 API가 코딩·에이전트 워크플로용 모델과 MCP 구현을 제공하므로 모델/도구 계층으로 다룬다. 이름만 보고 같은 종류라고 가정하지 않는다.

동일 작업 봉투를 블라인드 평가한다. 평가자는 공급자 이름을 보지 않고 출처 정확성 40, 누락 20, 스키마 준수 15, 실행 시간 10, 비용 10, 설명 가능성 5점으로 채점한다. GUI 에이전트에는 결제·전송·게시를 금지하고 읽기 전용 샌드박스 사이트만 준다.

가격, 모델 ID, 한국 가입 가능성은 자주 바뀐다. 본문 표에 영구 사실처럼 박제하지 말고 observedAt, 지역, 계정 유형을 함께 보존한다. 핵심 완주 경로는 어떤 중국 계정도 요구하지 않는다.

공식 시작점: Z.ai 개발 문서, ZCode 문서, Manus 문서, Manus API v2, DeepSeek API, MiniMax API.

4부 한 팀처럼 일하게 만들고 출시한다

↑ 목차로 돌아가기

15장 Codex가 결과를 검토하고 합친다

Codex 통합 게이트는 네 단계다. 먼저 계약 검사, 다음 diff·출처 리뷰, 자동 테스트, 마지막 사람 승인이다. Kimi와 Qwen 후보를 A/B로 바꾸어 공급자 이름을 숨긴다. 더 많은 코드를 만든 후보가 아니라 수용 기준을 더 적게 깨뜨린 후보를 고른다.

리뷰에는 결론과 증거를 분리한다.

판정: 후보 B 채택
근거: 모바일 390px 통과, 기존 decision API 보존, 새 의존성 없음
반려 사유 A: 원문을 innerHTML에 삽입해 XSS 위험, 실패 상태 누락
남은 위험: 중국어 줄바꿈을 실제 기기에서 재확인

에이전트가 작성한 테스트만 통과했다고 충분하지 않다. 구현과 독립된 회귀 테스트가 있어야 한다. 이 프로젝트에서 마스킹 테스트는 실제로 $1이 출력되는 버그를 발견했다. 작은 계약 테스트가 보안 로그의 허점을 잡은 사례다.

↑ 목차로 돌아가기

16장 다중 에이전트 작업 그래프를 실행한다

전체 흐름은 ChatGPT 제품 설계 → Codex 작업 계획 → Kimi 조사와 Qwen 검증 → Codex 통합 → 사람 판정이다. 모든 것을 병렬화하지 않는다. 스키마가 확정되기 전 UI와 어댑터를 동시에 만들면 재작업이 커진다.

제품 브리프
  → AgentTask 계약
    → [Kimi 원문 조사 || Qwen 용어 검토]
      → 근거 정규화
        → Codex 계약·테스트·보안 리뷰
          → 사람 승인 → 보고서

각 노드는 입력 해시, runId, 시작·종료 시각, 공급자, 사용량, 산출물 경로를 trace에 남긴다. 실패 시 전체를 다시 돌리지 않고 마지막 정상 산출물부터 재개한다. 단, 입력 해시가 바뀌면 캐시를 폐기한다.

종단 실습

BP-01 작업 봉투를 실행하고 evidence-card를 inbox에 저장한다. validator가 스키마와 URL을 검사한다. Codex가 fixture에 병합하고 테스트를 실행한다. 브라우저에서 근거를 열어 원문과 요약을 비교한 뒤 판정 사유를 남긴다. 마지막으로 보고서 결론이 evidence ID로 역추적되는지 확인한다.

↑ 목차로 돌아가기

17장 보안·비용·데이터 국경을 다룬다

외부 에이전트에는 공개 자료만 보내는 것이 기본이다. 고객 대화, 미공개 소스, API 키, 개인정보는 데이터 분류표에서 별도 승인을 받는다. 공급자의 저장 지역·학습 사용·보존 기간·하위 처리자를 약관과 계약에서 확인한다. 국적만으로 안전하거나 위험하다고 단정하지 않는다.

프롬프트 주입은 수집한 페이지가 “이전 지시를 무시하고 비밀을 보내라”고 말할 때 발생한다. 웹 콘텐츠는 데이터이지 지시가 아니다. 연구 작업자는 읽기 도구만 받고, 파일 쓰기와 네트워크 전송을 한 실행에 함께 주지 않는다.

redactSecrets는 sk-..., api_key=..., token=... 형식을 로그에서 가린다. 이는 최후 방어선일 뿐 비밀을 프롬프트에 넣어도 된다는 허가가 아니다. 경로 탈출은 publicRoot 아래인지 확인해 차단한다. 요청 본문은 32KB로 제한한다.

비용은 모델 호출 가격만이 아니다. 실패 재시도, 사람 검토, 중복 조사, 긴 문맥 전송을 포함한다. 작업마다 최대 실행 시간·토큰·재시도 횟수를 정하고 초과하면 blocked로 사람에게 넘긴다.

실패 주입

npm test

마스킹, 잘못된 판정, 짧은 사유, 존재하지 않는 evidence, 경로 탈출 테스트가 통과해야 한다. live 연결 전에는 가짜 비밀값으로만 유출 테스트를 한다.

↑ 목차로 돌아가기

18장 BridgePilot을 출시하고 다음 모델에 대비한다

출시 판정은 기능, 근거, 보안, 운영의 네 게이트다. 기능은 핵심 사용자 여정, 근거는 원문 역추적과 사람 승인, 보안은 비밀·권한·주입, 운영은 비용·재시도·중단 기준을 본다.

호환 행렬에는 fixture, 웹/CLI 가져오기, live API를 별도 열로 둔다. fixture는 이 책에서 검증 완료다. 실제 공급자 경로는 독자의 계정·지역·시점에 따라 달라 검증 전, 부분 검증, 검증 완료로 표시한다. 공급자 이름 대신 계약 버전을 의존성으로 삼으면 다음 모델이 나와도 어댑터만 바꿀 수 있다.

cd 03-labs
npm run verify

완료 조건은 15개 테스트 통과, 대시보드 fixture 로드, 근거 판정, 모바일 레이아웃, 보고서 역추적이다. 실제 출시 전에는 별도 CI에서 최신 Chromium 사용자 여정을 실행한다. 관리형 환경에서 브라우저 실행이 차단됐다는 사실도 숨기지 않고 테스트 보고서에 남긴다.

마지막 원칙은 간단하다. ChatGPT는 더 좋은 문제를 정의하고, Codex는 저장소와 품질 게이트를 지키고, 중국 AI는 언어·장문·구현 같은 전문 작업에서 경쟁한다. 사람은 어떤 근거를 받아들이고 어떤 위험을 감수할지 결정한다. 강한 모델 한 개보다 이 책임 구조가 더 오래간다.

부록

부록 A 처음 막혔을 때

Node 버전은 node -v로 확인한다. npm test가 실패하면 첫 번째 실패만 해결한 뒤 다시 실행한다. 4176 포트가 사용 중이면 PORT=4180 npm start로 바꾼다. 화면에 “불러오지 못했습니다”가 보이면 터미널에 표시된 HTTP 주소로 접속했는지 확인한다. HTML 파일을 file://로 직접 열면 브라우저 보안 정책 때문에 fixture 요청이 차단될 수 있으므로 지원 경로로 보지 않는다.

부록 B 계정과 지역 접근성

ChatGPT, Codex, Kimi, Qwen, GLM 계정·가격·지원 지역은 출간 후에도 변한다. 가입 전에 공식 서비스의 국가, 결제, 데이터 정책을 확인한다. 중국 전화번호나 기업 인증이 필요한 경로는 핵심 실습에서 제외한다. 접근 불가하면 A 경로 fixture를 사용하고 결과 봉투 구조만 연습한다.

부록 C 공급자 어댑터 체크리스트

• 모델 ID와 확인일을 기록한다.
• 입력·출력을 AgentTask/AgentResult로 변환한다.
• timeout, retry, rate limit을 명시한다.
• 스트리밍 중단을 실패로 기록한다.
• 원문 citation을 모델 문장과 분리한다.
• 비밀값과 고객 데이터를 로그에서 제거한다.
• live 결과를 fixture로 자동 승격하지 않는다.

부록 D 작업·리뷰 템플릿

## 작업
- 목표:
- 입력 산출물:
- 허용 도구:
- 수정 가능 경로:
- 금지 행동:
- 출력 스키마:
- 수용 기준:
- 시간·비용 한도:

## 리뷰
- 계약 검사:
- 자동 테스트:
- 출처 대조:
- 보안 위험:
- 채택/반려와 이유:
- 남은 불확실성:

부록 E 중국어 AI 용어

부록 F 벤치마크 판독 카드

평가 이름, 과업, 날짜, 표본 수, 도구 허용 여부, 하니스, 비용, 독립 재현, 회사 발표 여부를 한 카드에 적는다. “1위”는 이 칸을 모두 채운 뒤에만 쓴다. Arena 선호도와 정답형 평가, 장기 에이전트 평가를 같은 점수처럼 비교하지 않는다.

부록 G 출처·권리·개인정보 체크리스트

짧은 인용만 사용하고 나머지는 요약한다. 원문 URL·문서명·확인일을 남긴다. 자동 수집 허용 범위와 robots/약관을 확인한다. 개인정보가 포함된 원문은 수집 목적과 보유 기간을 정한다. 법률·의료·금융 결론은 전문가 검토 없이 출시 판단으로 사용하지 않는다.

부록 H 기대 화면과 문제 해결

대시보드에는 프로젝트 K-Flow 중국 시장 진출 검토, 준비도 83%, 출처 12, 근거 8, 채택 5, 비용 $3.84가 보여야 한다. 다르면 fixtures/bridgepilot.json이 책 버전과 같은지 확인한다. 판정 저장 후 새로고침하면 실행 중 메모리 저장소가 유지되는 동안 상태가 보인다. 서버 재시작 시 fixture 상태로 돌아오는 것은 의도된 교육용 동작이다.

참고 자료

• OpenAI, Codex SDK, 확인 2026-07-19.
• OpenAI, Run Codex as an MCP server, 확인 2026-07-19.
• OpenAI, Building Consistent Workflows with Codex CLI & Agents SDK, 확인 2026-07-19.
• Moonshot AI, Kimi K3 technical blog, 2026-07-16.
• Moonshot AI, Kimi Agent overview, 확인 2026-07-19.
• Moonshot AI, Kimi Code models, 확인 2026-07-19.
• Artificial Analysis, Kimi K3 model analysis, 확인 2026-07-19.
• Qwen, Qwen Code documentation, 확인 2026-07-19.
• Qwen, Qwen Code Agent Tool, 확인 2026-07-19.
• Qwen, Qwen-Agent guide, 확인 2026-07-19.
• Arena 발표 인용 보도, Kimi K3 Frontend Code Arena, 2026-07-17.
• Z.ai, Developer overview, 확인 2026-07-19.
• Manus, Documentation, 확인 2026-07-19.
• DeepSeek, API documentation, 확인 2026-07-19.
• MiniMax, API overview, 확인 2026-07-19.

에필로그: 모델 순위보다 오래가는 것

이 책을 다 읽은 독자는 중국 AI를 맹신하지도 무시하지도 않는다. 강한 작업에 투입하고, 결과의 출처와 실행 기록을 요구하고, 다른 에이전트와 같은 기준으로 비교한다. 새로운 Kimi와 Qwen이 나오거나 이름이 바뀌어도 작업 봉투와 테스트는 그대로다. 소프트웨어를 만드는 주체가 늘어날수록 최종 결정의 책임은 더 선명해야 한다. 그것이 에이전트 시대의 개발 실력이다.

실습 워크북: BridgePilot 완주 지도

이 워크북은 본문 18개 장과 일대일로 대응한다. 모든 실습은 03-labs에서 시작한다. [필수]는 fixture 경로, [선택]은 실제 서비스 계정이 있을 때만 수행한다. 실제 계정 화면이나 모델 이름이 책과 다르면 공식 문서를 우선하고 실행일을 기록한다.

Lab 01 벤치마크 주장을 감사한다

목표는 “누가 더 강한가”가 아니라 주장 범위를 잠그는 것이다. workbook/CLAIM-AUDIT.md를 만들고 주장, 평가 이름, 과업, 날짜, 수치, 회사/독립 여부, 반례 열을 만든다. K3의 Frontend Code Arena 결과와 종합 성능 문장을 별도 행에 둔다.

판정 문장 예시
확인: Kimi K3는 2026-07-16 공개 당시 특정 프런트엔드 선호도 평가에서
GPT-5.6 Sol과 Claude Fable 5보다 높은 점수를 기록했다.
제한: 이 결과는 종합 지능·보안·백엔드 정확성의 우위를 뜻하지 않는다.

기대 결과는 세계 1위 같은 무범위 문장이 하나도 없는 표다. 링크가 열리지 않으면 캐시된 요약을 사실로 승격하지 말고 재확인 필요로 둔다.

Lab 02 제품 브리프를 검토한다

workbook/PRODUCT-BRIEF.md를 열어 사용자, 결정, 실패 비용을 자신의 서비스에 맞게 바꾼다. 해결책 이름을 지워도 문제가 이해되어야 한다. ChatGPT에 다음 검토를 요청한다.

이 브리프에서 해결책을 미리 가정한 문장, 측정할 수 없는 성공 기준,
법률 판단을 제품 기능처럼 약속한 문장을 각각 찾아라. 고치지 말고 질문으로 반환하라.

답변을 그대로 붙이지 말고 제품 책임자가 수정한다. 완료 표시는 비범위가 세 개 이상이고 각 성공 기준을 테스트하거나 사람이 판정할 수 있을 때만 한다.

Lab 03 저장소 첫 GREEN을 만든다

node -v
cd 03-labs
npm run verify

Node.js 20 이상과 15개 통과를 확인한다. 실패하면 마지막 줄보다 첫 번째 not ok을 읽는다. AGENTS.md에서 정본 fixture, 금지 데이터, 완료 정의를 확인한다. 자신의 운영체제에서 포트가 허용되면 npm start 후 대시보드를 연다.

기대 출력은 BridgePilot 검증 완료다. 포트가 금지돼도 테스트는 요청 핸들러를 직접 호출하므로 통과해야 한다. 이 차이는 “서버 로직 검증”과 “실제 브라우저 검증”을 분리하기 위한 설계다.

Lab 04 작업 봉투를 깨뜨려 본다

먼저 제공 스크립트를 실행한다. 원본 fixture를 바꾸지 않고 정상 작업과 목표가 모호한 작업을 차례로 검사한다.

node lab/04-contract-failure.mjs

정상 계약의 BP-01: PASS 다음에 TASK_OBJECTIVE_INVALID와 TASK_TOOLS_INVALID가 기대 출력이다. 에러 문구가 달라졌다면 책보다 현재 테스트를 기준으로 계약 변경 이유를 기록한다. 에이전트별 프롬프트가 달라도 봉투 계약은 같아야 한다.

Lab 05 동일 화면을 확인한다

대시보드의 기준 값은 프로젝트 K-Flow 중국 시장 진출 검토, 준비도 83%, 출처 12, 근거 8, 채택 5, 비용 $3.84다. 브라우저 개발자 도구의 반응형 모드에서 1440px, 768px, 390px를 차례로 확인한다.

390px에서는 사이드바가 화면 밖에 있고 메뉴 버튼으로 열린다. 지표는 두 열, 작업은 한 열이다. 근거 출처와 판정 버튼이 겹치면 CSS를 고치기 전에 실제 viewport가 390 CSS px인지 확인한다. 확대 배율 100%로 캡처하고 파일명에 viewport를 남긴다.

Lab 06 근거 중복을 재현한다

node lab/06-evidence-dedupe.mjs를 실행한다. 스크립트는 fixture를 수정하지 않고 첫 근거의 URL에 ?utm_source=lab을 붙여 key를 비교한다. 추적 URL 중복 제거: PASS가 나와야 한다.

스크립트가 quote에 문장을 추가한 두 번째 비교에서는 다른 인용문 분리: PASS가 나와야 한다. 이는 의도적 보수성이다. 의미가 비슷하다는 이유로 자동 병합하면 서로 다른 법령 문구가 사라질 수 있다.

Lab 07 판정 API의 실패를 본다

서버를 실행한 터미널과 요청 터미널을 나눈다.

curl -i -X POST http://127.0.0.1:4176/api/decisions \
  -H 'content-type: application/json' \
  -d '{"evidenceId":"EV-001","decision":"accepted","reason":"짧음"}'

Windows PowerShell에서는 다음을 사용한다.

Invoke-RestMethod -Method Post -Uri http://127.0.0.1:4176/api/decisions -ContentType 'application/json' -Body '{"evidenceId":"EV-001","decision":"accepted","reason":"짧음"}'

400과 DECISION_REASON_REQUIRED가 기대 결과다. 사유를 정부 원문과 인용 범위를 대조함으로 바꾸면 201과 DEC-... 레코드가 나온다. 새로고침 후 review 상태를 확인한다. 서버를 재시작하면 fixture로 돌아가는 것은 현재 메모리 저장소의 의도된 제한이다.

Lab 08 외부 문자열 경계를 표시한다

현재 앱은 safe-html.js의 escaping과 URL scheme 검사로 외부 문자열 경계를 방어한다. 먼저 quote에 <img src=x onerror=alert(1)>을 넣고 태그가 실행되지 않고 글자로 표시되는지 확인한다. 이어 javascript: 링크가 거부되고 정상 중국어와 https: 링크는 유지되는지 테스트한다.

방어가 왜 필요한지 배우려면 정본이 아닌 격리 브랜치에서만 escaping 한 줄을 잠시 제거해 실패 테스트가 실제로 RED가 되는지 본 뒤 즉시 되돌린다. 수용 기준은 원문 태그가 글자로 보이고, 정상 중국어가 유지되며, 링크 URL은 http: 또는 https:만 허용되고, 회귀 테스트가 이 계약을 고정하는 것이다. 프로덕션 코드에 고의 취약 버전을 커밋하지 않는다.

Lab 09 오프라인 보고서 구조를 쓴다

workbook/REPORT-OUTLINE.md를 만들고 요약, 조건, 결론, 근거 색인, 판정 기록, 한계 절을 둔다. 각 결론 끝에 [EV-001]처럼 ID를 붙인다. Evidence 절의 같은 ID로 내부 링크가 이동해야 한다.

네트워크를 끈 상태에서도 보고서 본문과 도해가 보여야 한다. 외부 원문 링크는 연결이 있을 때만 열린다는 설명을 넣는다. PDF만 제공하면 링크와 원문 확인이 어려우므로 단일 HTML을 정본으로, PDF를 배포 사본으로 둔다.

Lab 10 Kimi에 원문 조사만 맡긴다

task-BP-01.json 내용을 Kimi Agent에 전달한다. 시스템 전체 구현이나 법률 결론을 요구하지 않는다. 결과는 원문 그대로 JSON 파일에 저장하되, 수동 편집했다면 transformedBy를 기록한다.

URL을 브라우저에서 열고 quote 일부를 검색한다. 문장이 없거나 문맥이 다른 경우 rejected로 두고 이유를 남긴다. 중국어를 몰라도 브라우저 찾기 기능으로 문자 일치를 검사하고, 번역의 적용 범위는 별도 검토한다. 계정이 없으면 result-kimi-BP-01.example.json으로 같은 과정을 수행한다.

Lab 11 Kimi Code 후보를 격리한다

정본과 다른 worktree에서만 실행한다.

git worktree add ../bridgepilot-kimi -b lab/kimi-evidence-compare

수정 가능 파일을 public/ 세 개로 제한하고 390px 1열, 기존 ID 보존, 새 의존성 없음이라는 수용 기준을 전달한다. 종료 후 git diff --stat, git diff, npm test 순서로 본다. 테스트 로그가 결과 봉투에 없으면 완료로 인정하지 않는다. worktree 삭제는 필요한 diff를 보존한 뒤에만 한다.

Lab 12 Qwen SubAgent 경계를 만든다

localizer의 출력은 artifacts/qwen-terms.json, validator의 출력은 artifacts/qwen-validation.json으로 분리한다. 두 작업 모두 bridgepilot.json을 수정하지 못하게 한다. 실행 전 입력 파일의 해시를 기록한다.

병렬 결과가 끝나면 용어 제안과 스키마 오류를 사람이 따로 읽는다. 상위 에이전트가 두 파일을 한 문단으로 요약해 세부 오류를 숨기지 않게 원본 링크를 보존한다. 계정이 없으면 두 역할을 사람이 순서대로 수행해 경계 설계만 익힌다.

Lab 13 결정론적 도구를 만든다

normalize_source의 입력과 출력을 표로 먼저 정의한다. https://EXAMPLE.com/a/?utm_source=x#top은 host 소문자화, 추적 변수와 fragment 제거 후 https://eroke.kr/a가 되어야 한다. 인용문은 임의 번역하거나 고치지 않는다.

모델이 정규 URL을 직접 작성하게 하지 말고 도구를 호출하게 한다. 같은 입력을 100번 실행해 결과가 같은지 테스트한다. Qwen-Agent 연결은 선택이고, 핵심 합격 기준은 공급자 없이 도구 함수 테스트가 통과하는 것이다.

Lab 14 블라인드 비교표를 채운다

Kimi, Qwen, GLM 또는 사용 가능한 두 공급자에 동일 task를 준다. 결과 파일을 A, B로 바꾸고 공급자 필드를 가린 복사본을 평가자에게 준다. 출처 정확성 40, 누락 20, 스키마 15, 시간 10, 비용 10, 설명 가능성 5점이다.

점수가 같으면 더 적은 권한과 더 낮은 재현 비용을 요구한 후보를 고른다. 결과가 하나뿐이면 우승을 선언하지 말고 단일 실행 사례로 표기한다. GUI 조작 제품에는 읽기 전용 테스트 사이트 외의 로그인 계정을 주지 않는다.

Lab 15 실제 통합 리뷰를 쓴다

workbook/REVIEW-BP-01.md를 템플릿으로 새 후보를 리뷰한다. “좋음” 대신 수용 기준별 통과·실패와 증거를 쓴다. 보안 리뷰에는 외부 입력 렌더링, 경로, 로그, 네트워크 권한을 포함한다.

구현자가 만든 테스트 외에 반대 사례 하나를 추가한다. 예를 들어 secret redaction에 token=과 api_key: 두 형태를 함께 넣는다. 테스트가 실제 결함을 발견하면 수정 전 실패 로그와 수정 후 통과 로그를 리뷰 산출물로 보존한다.

Lab 16 한 기능을 종단 실행한다

작업 ID를 하나 정하고 다음 체크박스를 순서대로 완료한다.

• [ ] Product brief의 결정과 연결
• [ ] AgentTask 계약 통과
• [ ] 격리된 전문 작업자 실행 또는 fixture 사용
• [ ] AgentResult 계약 통과
• [ ] 출처 원문 대조
• [ ] 정본 병합과 자동 테스트
• [ ] UI에서 사람 판정
• [ ] 보고서에서 근거 역추적

중간 산출물을 삭제하지 않는다. 마지막 화면만 남기면 실패를 재현할 수 없다. 입력이 바뀐 재실행은 새 runId를 쓴다.

Lab 17 공격자처럼 실패를 넣는다

가짜 비밀 sk-abcdefghijklmnop, api_key:abc123, token=hello-secret을 마스킹 함수에 넣는다. 출력에는 키 이름만 남고 값은 모두 [REDACTED]여야 한다. 다음으로 /..%2Ffixtures%2Fbridgepilot.json 경로를 요청해 403을 확인한다.

프롬프트 주입 문장을 evidence quote에 넣고 연구 에이전트가 지시로 실행하지 않는지 확인한다. 공격 문자열은 교육용 가짜 데이터만 사용한다. 실패 결과를 숨기지 말고 위협, 기대 방어, 실제 결과, 수정, 회귀 테스트로 기록한다.

Lab 18 출시 판정 회의를 연다

기능·근거·보안·운영 네 열의 표를 만든다. 각 열에 통과 증거 파일을 링크한다. live provider가 없더라도 fixture 제품은 출시 후보가 될 수 있지만, 실제 시장 결론 서비스라고 홍보할 수는 없다. 법률 감수와 실제 공급자 정책 확인을 HOLD로 둔다.

최종 명령은 다음과 같다.

cd ../..
npm run qa

18개 장, 출처, 도해, 코드 펜스, 이미지 경로와 15개 실습 테스트가 통과해야 한다. 실패가 하나라도 있으면 버전을 올리지 않는다. 통과 로그, 실행일, Node 버전, 아직 검증하지 못한 브라우저/계정 조건을 production/STATUS.md에 남기면 완주다.

워크북 제출물 목록

↑ 목차로 돌아가기