AI 코딩 에이전트가 만든 PR을 받은 리뷰어는 변경된 코드만 읽지 않습니다. 이 코드가 어느 요구에서 출발했는지, 에이전트가 어떤 접근을 버렸는지, 테스트는 무엇을 어느 시점에 실행했는지, 그리고 아무도 확인하지 않은 부분은 어디인지까지 짧은 시간 안에 판단해야 합니다.
에이전트가 더 많은 코드를 더 빨리 만들수록 이 판단 비용은 커집니다. 운영 중인 서비스를 가진 팀이라면 통제의 중심을 “AI가 작성한 코드인가”에 두기보다, 각 커밋이 무엇을 시도했고 무엇으로 검증됐으며 어디가 비어 있는지를 보여 주는 증거 기록을 갖고 있는가로 옮길 필요가 있습니다.
여기서 증거 기록은 안전을 보증하는 문서가 아닙니다. 리뷰어가 확인된 범위와 미확인 범위를 구분하고, 제한된 시간을 위험한 변경에 먼저 쓰게 하는 운영 장치입니다.
증거 기록은 네 가지 질문에 답해야 한다
로그를 많이 남긴다고 리뷰가 좋아지지는 않습니다. 도입 전에 CTO와 개발 리드는 각 커밋의 기록이 아래 질문에 답해야 한다는 요구사항부터 정하는 편이 좋습니다.
| 검토 질문 | 기록할 내용 | 사용하는 장면 |
|---|---|---|
| 왜 바꿨는가 | 작업 티켓, 요청 요약, 구현 의도 | 리뷰, 장애 분석 |
| 무엇을 시도했는가 | 편집 경로, 폐기한 접근, 실패한 검사 | 설계 검토, 재발 방지 |
| 무엇이 확인했는가 | 실행 명령, 종료 결과, 테스트·분석 산출물 식별자 | CI, 릴리스 판단 |
| 무엇이 비어 있는가 | 증거 없는 변경 영역, 미실행 검사, 사람 검토 미기록 | 리뷰 우선순위, 예외 승인 |
특히 마지막 질문이 중요합니다. 테스트가 통과했다는 사실만으로 변경이 충분히 검증됐다고 볼 수는 없습니다. 해당 테스트가 바뀐 인증 경로를 실행하지 않았을 수 있고, 통합 환경이나 권한 조건, 데이터 마이그레이션 검사가 빠졌을 수도 있습니다.
에이전트가 남긴 작업 의도와 설명은 구현 맥락을 찾는 데 유용합니다. 다만 그것은 에이전트의 자기 보고입니다. 테스트 결과 파일, 빌드 산출물 해시, 정적 분석 결과처럼 나중에 대조하거나 재실행할 수 있는 정보와 같은 신뢰 수준으로 다루면 안 됩니다. 기록의 필드를 처음부터 설명과 검증 결과로 분리해야 하는 이유입니다.
첫 도입은 병합 차단이 아니라 관찰 모드로 시작한다
처음부터 모든 저장소와 모든 AI 생성 커밋에 게이트를 걸면 개발 흐름이 흔들릴 수 있습니다. 에이전트 사용량이 높고, 테스트 명령과 PR 절차가 비교적 정리된 저장소 하나를 골라 관찰 모드로 시작하는 것이 현실적입니다.
이 파일럿에서 먼저 만들 산출물은 세 가지입니다.
-
증거 스키마 v1
작업 식별자, 작성 경로, 변경 의도, 실행 명령, 결과, 산출물 위치 또는 해시, 미검토 표시, 기록 생성 시각을 정의합니다. 프롬프트 원문, 비밀값, 고객 정보, 운영 토큰처럼 저장하면 안 되는 필드도 명시해야 합니다. -
커밋 결속 규칙
레코드는 대상 커밋 SHA, 트리 또는 diff 식별자와 검증 가능하게 연결합니다. 커밋 메시지 트레일러에는 레코드를 가리키는 식별자를 남길 수 있습니다. 예를 들어 일부 구현은 커밋 메시지에 전체 SHA-256 다이제스트를 기록하고, 서명된 레코드 자체는 저장소의 별도 ref에 보관합니다. 중요한 점은 식별자의 길이가 아니라, 해당 레코드가 현재 커밋 내용과 맞는지 다시 검사할 수 있어야 한다는 데 있습니다. -
PR 요약 화면
에이전트 대화 전체를 PR에 붙이지 않습니다. 파일 또는 hunk 단위로검증 증거 있음,실패 이력 있음,증거 없음,사람 검토 미기록정도를 보여 주고, 원본 기록은 필요할 때 펼쳐 보게 합니다.
관찰 기간에는 병합을 막지 않는 편이 낫습니다. 기존 PR에 기록을 붙여 본 뒤, 리뷰어가 실제로 열어 보는 필드와 형식적으로 채워지는 필드를 구분해야 합니다. 이 단계에서 유용하지 않은 필드를 없애지 않으면, 이후 자동화는 더 많은 잡음만 만들 수 있습니다.
수집 주체를 분리해야 기록을 믿을 수 있다
증거 기록이 약해지는 대표적 이유는 에이전트의 보고와 독립 검증 결과를 한 줄의 로그로 섞는 데 있습니다. 에이전트가 테스트를 실행했다고 남겨도, 어느 작업 디렉터리에서 실행했는지, 종료 코드는 무엇인지, 결과 파일이 남았는지는 별도로 확인해야 합니다.
수집 경로는 역할별로 나누는 편이 좋습니다.
- 에이전트 하네스는 편집 대상, 작업 의도, 실행하려 한 명령, 수정 후 되돌린 접근을 관찰합니다.
- 로컬 개발 환경은 Git 훅이나 래퍼를 통해 커밋 직전의 관찰 정보를 묶고, 커밋 후 레코드를 저장합니다.
- CI는 빌드, 단위 테스트, 통합 테스트, 정적 분석, 배포 전 검사의 결과를 커밋 기준으로 연결합니다.
- 코드 리뷰 시스템은 승인자, 검토 시점, 논의된 파일과 스레드 같은 사람의 검토 흔적을 남깁니다.
- 감사 로그 또는 보존 저장소는 레코드의 해시와 서명 검증 결과, 접근 이력, 보존 정책을 관리합니다.
이렇게 나누면 각 기록이 말할 수 있는 범위도 분명해집니다. 에이전트 이벤트는 “무엇을 했다고 보고했는가”를, CI는 “어떤 자동 검사가 무엇을 확인했는가”를, 리뷰 시스템은 “누가 어느 변경을 검토했는가”를 보여 줍니다. 세 기록이 모두 있다고 해서 보안성이나 요구사항 충족이 자동으로 보장되지는 않습니다. 대신 장애나 감사 시점에 어느 단계가 비었는지는 빠르게 확인할 수 있습니다.
PR 검토 순서를 위험 신호 중심으로 바꾼다
증거 기록을 도입해도 리뷰어가 diff를 위에서 아래로만 읽으면 효과가 제한됩니다. PR 템플릿과 봇 요약은 검토 순서 자체를 바꿔야 합니다.
권장하는 검토 순서는 다음과 같습니다.
- 기록이 없거나 커밋 결속 검증에 실패한 hunk를 먼저 확인합니다.
- 실패한 시도나 되돌린 접근이 있었던 영역을 봅니다. 실패 원인이 요구사항 오해인지, 구현 결함인지, 검사 부족인지 구분합니다.
- 테스트는 실행됐지만 바뀐 줄을 실행하지 못한 영역을 확인합니다.
- 자동 검증과 사람 검토가 함께 기록된 반복적·저위험 변경은 접어 두고 필요할 때 열어 봅니다.
- 인증, 권한, 결제, 데이터 변경, 외부 연동처럼 배포 위험이 큰 영역은 증거가 충분해 보여도 담당자가 별도로 검토합니다.
증거 밀도나 줄 단위 커버리지는 병합 여부를 자동으로 결정하는 점수가 아닙니다. 커버리지가 높아도 요구사항을 만족한다는 뜻은 아니고, 사람이 파일을 열어 봤다는 기록도 설계 판단의 품질을 증명하지 않습니다. 이런 지표는 리뷰 대기열을 정렬하는 보조 신호로 제한하는 편이 안전합니다.
CI 게이트는 기록의 존재보다 결속과 재검증을 확인한다
파일럿이 안정되면 CI에 최소 게이트를 추가할 수 있습니다. 이때 “증거 레코드가 있으면 통과”로 만들면 팀은 기록의 품질보다 기록 생성 자체를 최적화하게 됩니다. 게이트는 적어도 아래를 따로 검사해야 합니다.
- 레코드가 대상 커밋의 트리 또는 diff와 연결되는가
- 레코드의 다이제스트와 서명이 검증되는가
- 테스트 결과와 분석 산출물이 같은 커밋에서 생성됐는가
- 레코드에 설명되지 않은 파일 변경이 있는가
- amend, rebase, cherry-pick 뒤에 이전 커밋용 기록이 남아 있지 않은가
- 민감 경로 변경에 필요한 검사와 사람 승인이 빠지지 않았는가
초기에는 레코드 누락, 커밋 결속 실패, 서명 검증 실패처럼 위조 또는 오연결 위험이 있는 항목만 병합 차단 조건으로 두는 방식을 검토할 수 있습니다. 테스트 범위 부족이나 사람 검토 미기록은 우선 경고로 보여 주고, 팀이 예외 승인 절차를 정한 뒤 강화하는 편이 낫습니다.
긴급 수정도 고려해야 합니다. 운영 장애 대응 중에는 모든 증거를 커밋 전에 갖추기 어려울 수 있습니다. 이 경우에는 책임자 승인, 사후 검증 기록 보완 기한, 후속 PR 연결 규칙을 별도로 두어야 합니다. 긴급 변경을 예외로 허용하는 것과 기록 없이 사라지게 하는 것은 다른 문제입니다.
운영 중에는 기록량보다 빈칸의 패턴을 본다
도입 효과는 레코드 개수로 판단하기 어렵습니다. 아래 신호가 반복되면 스키마나 수집 경로를 조정할 시점입니다.
- 작업 의도가 거의 같은 문장으로 반복됩니다. 에이전트 서술보다 티켓, 변경 요청, diff 연결을 강화해야 합니다.
- CI 결과는 많지만 변경 코드와 이어지지 않습니다. 산출물의 커밋 결속 방식이 약할 수 있습니다.
- 리뷰어가 증거 요약을 열지 않습니다. 화면이 복잡하거나 위험 우선순위가 실제 검토 흐름과 맞지 않을 수 있습니다.
- rebase와 cherry-pick 후 검증 상태가 자주 혼란스러워집니다. SHA 연결만 보지 말고 레코드 재발급과 재검증 정책을 점검해야 합니다.
- 명령 출력이나 대화 내용에 민감 정보가 쌓입니다. 수집 단계의 마스킹, 접근 권한, 보존 기간을 다시 정해야 합니다.
다음 스프린트에는 저장소 하나를 선택해 최근 AI 생성 PR 몇 건에 증거 스키마를 수동 적용해 보는 편이 좋습니다. 리뷰어가 “이 변경을 더 봐야 하는 이유”를 판단할 때 실제로 사용한 필드만 남기십시오. 그 결과를 바탕으로 자동 수집, PR 표시, CI 게이트, 감사 보존의 순서를 정하면 전사 규칙을 먼저 선언하는 것보다 시행착오를 줄일 수 있습니다.
