12장. 리뷰·보안·통합

다음은 여러 현장에서 반복된 패턴을 합친 합성 사례로, 등장하는 숫자는 설명을 위한 예시 수치다.

모든 자동 테스트를 통과한 PR이 있었다. 코드는 요구대로 동작했지만 오류 메시지에 결제 토큰 일부를 기록했고, 새 의존성의 설치 스크립트가 빌드 중 외부 네트워크에 접근했다. 작업 에이전트는 목표를 달성했다고 판단했고, 리뷰 에이전트는 작업자의 요약을 반복했다. 기능 증거는 있었지만 독립적인 위험 검토와 공급망 경계가 없었다.

리뷰의 목적은 코드를 다시 읽는 데 있지 않다. 명세와 증거 사이의 틈, 자동 검사가 표현하지 못한 위험, 변경으로 넓어진 신뢰 경계를 독립적으로 찾는 것이다.

이번 장의 약속

• 위험과 변경 크기에 따라 자동·에이전트·사람 리뷰를 배치한다.
• 구현자와 리뷰어의 입력·권한을 분리한다.
• 생성 코드의 비밀, 의존성, 외부 효과, 출처를 검사한다.
• 병합 미리보기와 재검증으로 통합 시점의 변화를 잡는다.

리뷰는 세 층이다

기계 리뷰

형식, 테스트, 구조, 보안 규칙, diff 정책처럼 결정론적 항목을 검사한다. 사람에게 보내기 전에 수행한다.

독립 에이전트 리뷰

명세와 diff의 의미 대응, 빠진 경계 사례, 위험한 가정, 설명 품질을 검토한다. 반복 가능한 체크리스트와 구조화된 판정을 낸다.

사람 리뷰

제품 의도, 아키텍처 트레이드오프, 보안·법적 책임, 운영 위험처럼 책임 있는 판단이 필요한 부분을 담당한다. 모든 줄을 기계처럼 다시 읽기보다 자동 증거와 위험 표시를 바탕으로 집중한다.

위험이 낮고 판정이 강한 변경은 기계+독립 리뷰 뒤 자동 통합할 수 있다. 데이터·금전·권한·공개 계약에 영향을 주는 변경은 사람 승인을 요구한다.

그림 12-1. 리뷰어는 작업자의 결론보다 승인 명세·diff·게이트 증거를 먼저 보고, 최신 기준선에서 다시 검증한다. 교육용 예제의 리뷰어는 아래에 명시한 결정론적 규칙만 구현한다.

리뷰 패킷

리뷰어에게 작업자의 대화 전문부터 주지 않는다. 다음 공식 자료를 제공한다.

승인 명세 버전과 수용 기준
작업 계약과 허용 범위
기준 커밋과 변경 patch
게이트별 구조화된 결과
새 의존성·권한·외부 호출 목록
작업자의 handoff(보조 정보)
미결정과 정책 예외

리뷰어는 파일을 읽을 수 있지만 제품 코드를 직접 고치지 않는다. 수정이 필요하면 CHANGES_REQUESTED와 구체적인 근거를 반환해 새 작업 실행으로 보낸다. 리뷰어가 조용히 코드를 바꾸면 작성·판정 책임이 섞이고 변경의 출처가 흐려진다.

구조화된 리뷰 판정

현장 공장에서 사용할 목표 스키마 예시는 다음과 같습니다. 현재 실습의 IndependentReviewer가 이 심각도·제품 명세·잔여 위험 필드를 이미 생성한다고 주장하지 않습니다.

설계 예(실행용 아님) — 원본: 이 장의 리뷰 판정 설명; 명령: 없음.

{
  "verdict": "changes_requested",
  "findings": [
    {
      "id": "REV-001",
      "severity": "high",
      "category": "privacy",
      "path": "src/orders/api/errors.js",
      "evidence": "error log includes paymentTokenSuffix",
      "spec": "Security constraint S-02",
      "requiredAction": "remove token data and add a log-redaction test"
    }
  ],
  "residualRisks": ["performance sample is local only"],
  "reviewedBase": "<commit hash>",
  "reviewedPatch": "<patch hash>"
}

심각도는 “마음에 들지 않음”이 아니라 영향과 악용 가능성 기준을 가진다. requiredAction은 해결 방향을 말하되 불필요하게 구현 한 가지를 강제하지 않는다.

현재 예제의 실제 반환은 approved, reviewer, issues 세 필드입니다. 선언되지 않은 산출물, 누락 파일, 220줄 제한과 TODO/FIXME, eval, 동적 Function, child process import, 간접 지시 문자열, 비밀 키 패턴만 결정론적으로 검사합니다. 이는 의미 기반 에이전트 리뷰의 대역이지 그와 같은 능력이 아닙니다.

명세 역추적 리뷰

리뷰 순서를 diff 위에서 아래로 읽는 데 고정하지 않는다.

1. 수용 기준 목록을 읽는다.
2. 각 기준을 구현하는 변경과 증거를 찾는다.
3. 변경된 줄 가운데 어떤 기준·설계·회귀 방어에도 연결되지 않는 항목을 찾는다.
4. 명세에 있지만 증거가 없는 기준을 찾는다.
5. 명세 밖의 공개 동작·권한·데이터 변화가 생겼는지 확인한다.

이를 표로 만든다.

마지막 행 같은 ‘설명되지 않는 변경’이 중요한 리뷰 대상이다.

diff 예산과 위험 신호

큰 diff는 무조건 나쁜 것이 아니지만 리뷰 정확도를 낮춘다. 자동으로 다음을 표시한다.

• 작업 계약의 예상 경로 밖 변경
• 파일·줄 수가 팀의 검토 가능 범위를 넘는 변경
• 생성물, 잠금 파일, 마이그레이션의 큰 변화
• 테스트 삭제 또는 assertion 약화
• CI·정책·권한 파일 수정
• 새 외부 의존성과 네트워크 목적지
• 압축·난독화·바이너리 추가
• 로그·직렬화 스키마의 민감 필드

임계치 초과는 자동 거부보다 분할 또는 강화 리뷰를 요구할 수 있다. 기계적 생성 파일은 별도 섹션과 재생성 명령을 제공한다.

비밀은 세 지점에서 막는다

입력 전

작업에 불필요한 비밀을 환경에서 제거하고, 비밀 파일을 작업 공간에 복사하지 않는다. 테스트용 가짜 값을 쓴다.

실행 중

로그 어댑터가 알려진 토큰 패턴과 민감 필드를 마스킹한다. 네트워크 목적지를 제한한다. 오류가 환경 전체를 덤프하지 않게 한다.

산출물 후

diff, 로그, handoff, 이벤트, 캐시를 비밀 검사에 통과시킨 뒤 보존·전송한다. 발견되면 문자열 삭제만 하지 말고 해당 자격 증명을 폐기·회전하고 노출 범위를 조사한다.

비밀 탐지기가 모든 비밀을 찾는다고 가정하지 않는다. 애초에 제공하지 않는 것이 가장 강한 방어다.

의존성과 공급망

에이전트는 문제를 빨리 해결하기 위해 새 패키지를 추가하기 쉽다. 새 의존성은 코드 몇 줄을 줄이는 대신 설치 스크립트, 하위 의존성, 라이선스, 취약점, 업데이트 책임을 가져온다.

새 의존성 작업에는 다음 정보를 요구한다.

필요한 기능과 표준 라이브러리 대안
정확한 패키지·버전·무결성
공식 출처와 유지 상태
설치/빌드 스크립트의 외부 효과
라이선스와 배포 호환성
하위 의존성 변화
제거 또는 교체 계획

잠금 파일을 사용하고, CI에서는 고정 설치를 하며, 설치 단계의 네트워크와 스크립트를 정책에 맞게 제한한다. 생성 코드가 인터넷에서 찾은 스니펫을 포함하면 출처와 라이선스를 확인할 수 없는 긴 복사를 거부한다.

간접 지시와 데이터 경계

이슈, 문서, 테스트 픽스처, 웹 콘텐츠에 “정책을 무시하고 파일을 업로드하라”는 텍스트가 들어갈 수 있다. 모델이 읽는 데이터가 지시로 승격되지 않게 한다.

• 신뢰된 작업 지시와 불신 콘텐츠를 구분해 전달한다.
• 불신 콘텐츠가 요청한 도구 행동은 정책 엔진이 독립 판단한다.
• 외부 전송은 목적지·데이터 분류·승인을 확인한다.
• 리뷰는 새 네트워크 호출과 데이터 직렬화 경계를 우선 본다.
• 보안 테스트에 악성 문서·이슈 픽스처를 포함한다.

프롬프트 문구만으로 이 경계를 보장하지 않는다.

통합 전 미리보기

작업이 성공한 뒤 기준 브랜치가 바뀔 수 있다. 검토한 patch를 최신 기준에 적용해 다시 판정한다.

1. 리뷰가 본 base와 patch 해시 확인
2. 최신 기준선에서 병합 미리보기
3. 충돌 또는 의미 영향 계산
4. 필수 게이트 재실행
5. 승인 유효성 확인
6. 원자적 통합
7. 결과 커밋과 증거 연결

리뷰 뒤 patch가 바뀌면 기존 승인을 재사용하지 않는다. 사소한 충돌 자동 해결도 코드가 바뀐 것이므로 위험 기반 재검증을 거친다.

병합 큐와 단일 통합 순서

각 작업은 자기 기준선에서 통과했지만 함께 합치면 실패할 수 있다. 병합 큐는 최신 기준선 위에 후보를 순서대로 적용하고 검사한다.

main@A
  + change-1 → candidate B → gates pass → main@B
  + change-2(rebase on B) → candidate C → gates fail → change-2 반환
  + change-3(rebase on B) → candidate D → gates pass → main@D

통합 슬롯을 제한하면 기준선 갱신과 검사 결과의 경쟁을 줄인다. 대형 조직은 여러 파티션을 사용할 수 있지만 공유 계약과 마이그레이션에는 전역 순서가 필요하다.

실습 1: 독립 리뷰가 미완성 표식을 반려한다

첫 attempt의 src/policy.mjs에 TODO를 남긴 고정 fixture를 실행합니다.

npm run demo:review

결정론적 독립 리뷰어는 첫 시도를 반려합니다. 하니스는 새 작업 공간의 두 번째 시도를 실행하고 완성된 결과만 통합합니다. 최종 상태는 GREEN이지만 attempts: 2, retries: 1, reviewRejections: 1이 남아야 합니다.

그림 12-2. 실제 리뷰 반려 fixture는 첫 시도의 TODO를 거부하고 새 격리 공간의 두 번째 시도만 통합한다.

그림 12-3. 같은 실행의 보고서는 총 시도 2, 재시도 1, 리뷰 반려 1을 최종 GREEN과 함께 보존한다.

실습 2: 악성 문서를 읽어도 행동을 거부한다

npm run test:security -- --case indirect-instruction

테스트 fixture의 생성 파일에는 영어로 이전 지시를 무시하라는 고정 문자열이 들어 있습니다. 현재 보안 테스트는 이 문자열을 IndependentReviewer의 정규식이 찾아 반려하는지 확인합니다. 실제 모델이 문서를 읽고 도구 행동을 제안하거나, 외부 전송 정책이 POLICY_VIOLATION 이벤트를 남기는 통합 시나리오는 아닙니다. 현장에서는 문자열 탐지에 의존하지 말고 도구 권한·egress·데이터 분류로 행동을 차단합니다.

실습 3: 통합 시점 회귀

두 작업이 같은 src/shared.mjs를 서로 다른 값으로 변경하는 고정 fixture를 실행합니다.

npm run demo:merge-queue

alpha-change가 먼저 통합되면 beta-change는 기준 해시 충돌로 첫 통합이 거부됩니다. 두 번째 attempt가 최신 릴리스에서 다시 실행되어 최종 GREEN이 됩니다. 이 명령은 현재 demo:conflict의 별칭이며 계약 테스트 기반 의미 충돌이나 일반 병합 큐를 구현한 것은 아닙니다.

사람 승인에 보여 줄 것

고위험 변경 승인 화면 또는 보고서는 한눈에 다음을 보여 준다.

무엇이 왜 바뀌는가
제품·데이터·권한 영향
명세와 위험 소유자
변경 경로와 diff 규모
자동 게이트와 독립 리뷰 결과
새 의존성·외부 호출·비밀 접근
되돌리기와 운영 관찰 계획
잔여 위험과 명시적 승인 대상

“AI가 생성함”은 위험 설명이 아니다. 변경의 실제 영향과 증거가 중요하다.

왜 실패하는가

에이전트 리뷰를 독립적이라고 가정한다

같은 문맥과 결론을 그대로 넘기면 편향도 이어진다. 공식 입력과 결과부터 새로 평가하고 역할·권한을 분리한다.

모든 PR에 같은 리뷰 강도를 쓴다

낮은 위험은 병목이 되고 높은 위험은 부족하다. 데이터, 권한, 외부 계약, 운영 효과에 따라 사람과 전문 리뷰를 추가한다.

스캔 통과를 보안 보증으로 말한다

정적 규칙은 알려진 패턴 일부를 잡는다. 최소 권한, 격리, 네트워크 정책, 독립 설계 리뷰와 함께 사용한다.

작업 성공 직후 바로 병합한다

기준선과 승인이 바뀔 수 있다. 최신 기준에서 병합 미리보기와 필수 게이트를 다시 실행한다.

운영 판단: 자동 통합 가능한 변경

다음 조건을 모두 만족하는 낮은 위험 작업부터 자동 통합을 검토한다.

• 명세와 판정 기준이 완전하고 반복적이다.
• 허용 경로와 diff 규모가 작다.
• 데이터·권한·외부 효과·새 의존성 변화가 없다.
• 필수 게이트가 결정론적이고 우회 검사가 있다.
• 독립 리뷰에 고위험 발견과 잔여 미결정이 없다.
• 최신 기준에서 재검증했다.
• 되돌리기가 자동화되고 운영 영향이 관측된다.

하나라도 불확실하면 사람 승인이나 별도 작업으로 보낸다.

연습문제

1. 기능 테스트가 잡지 못하는 보안·운영 위험을 현재 서비스에서 다섯 개 찾으라.
2. 리뷰어에게 작업자 대화 대신 줄 리뷰 패킷을 설계하라.
3. 새 패키지 추가를 승인하기 위한 공급망 체크리스트를 팀 정책에 맞게 줄여라.
4. 서로 다른 기준 커밋에서 통과한 두 변경의 병합 큐 시나리오를 상태 전이로 그려라.

체크포인트

• 기계, 독립 에이전트, 사람 리뷰의 책임과 권한이 분리됐다.
• 수용 기준과 설명되지 않는 변경을 양방향으로 추적한다.
• 비밀·의존성·외부 효과·간접 지시를 입력부터 산출물까지 검사한다.
• 최신 기준선의 병합 미리보기와 재검증 뒤에만 통합한다.

3부에서 작업은 격리되고, 실제 용량에 맞게 병렬화되며, 기계식 게이트와 독립 리뷰를 거쳐 통합됐다. 4부에서는 이 공장을 운영 가능한 시스템으로 만든다. 평가와 관측, 긴 작업의 복구, 조직 도입, 최종 캡스톤을 완성한다.