CI 게이트가 AI 생성 PR(Pull Request)에 플래그를 표시할 때, 중요한 질문은 단지 "무엇을 플래그로 표시했는가?"만이 아닙니다.

또한 다음과 같은 질문도 중요합니다:

"나중에 다른 사람이 돌아와서 왜 이 결과가 발생했는지 재유도(re-derive)할 수 있는가?"

이것이 제가 Agent Gate v0.2.1에 증거 스냅샷(evidence snapshots)을 추가한 이유입니다.

Agent Gate란 무엇인가

Agent Gate는 AI 생성 Pull Request를 위한 GitHub Action입니다.

이 도구는 LLM(Large Language Model)으로 코드를 리뷰하지 않습니다. 대신 CI에서 결정론적인 병합 증거(deterministic merge evidence)를 확인합니다:

• PR 범위 이탈 (PR scope escapes)
• GitHub Actions 권한 상승 (GitHub Actions permission escalation)
• AGENTS.md / .mcp.json 드리프트 (drift)
• 테스트 파일 증거 누락 (missing test-file evidence)
• 고위험 경로 변경 (high-risk path changes)

이 Action은 PR 코드를 체크아웃하거나, 런타임에 LLM을 호출하거나, 저장소 스크립트를 실행하지 않습니다.

탐지 ID(finding IDs)만으로는 부족했던 이유

v0.2.0에서 Agent Gate는 안정적인 탐지 ID(finding IDs)를 추가했습니다.

이를 통해 모든 탐지 결과에 다음과 같은 짧은 감사 핸들(audit handle)이 부여되었습니다:

agf_987ab9ddb8c1b299

이는 참조, 댓글, 향후 오버라이드(override) 워크플로 및 로그 기반 디버깅에 유용합니다.

하지만 ID 자체는 증거가 아닙니다. 나중에 누군가 해당 ID를 보더라도, 어떤 기록된 자료가 그 ID를 생성했는지 여전히 알아야 합니다.

v0.2.1에서 추가된 사항

v0.2.1은 공개 탐지 결과에 evidenceSnapshot을 추가합니다.

구조는 다음과 같습니다:

findingId = 짧은 감사 핸들 (short audit handle)
evidenceSnapshot = 해당 핸들을 유도하는 데 사용된 정전적 자료 (canonical material)

스냅샷은 의도적으로 단순하게 설계되었습니다. 여기에는 다음과 같은 안정적인 규칙 자료가 포함됩니다:

• 규칙 ID (rule id)
• 심각도 (severity)
• 경로 또는 라인 (존재하는 경우)
• 정규화된 증거 레이블/값 쌍 (normalized evidence label/value pairs)

타임스탬프, 보고 순서, 위험 점수(risk score), 버전, 커밋 SHA 또는 변경 가능한 표시 텍스트는 포함하지 않습니다.

실제 보고서 형태

압축된 로그 출력 예시:

Agent Gate: NEEDS HUMAN DECISION
Decision: warn
Risk score: 49 / 100
...

압축된 로그는 짧게 유지되지만, JSON 및 Markdown 보고서에는 더 완전한 증거가 담깁니다.

JSON 형태 예시:

{
  "findingId": "agf_987ab9ddb8c1b299",
  "ruleId": "risk/high-risk-path",
...

이것이 중요한 이유

저에게 있어, 탐지 결과를 경고(warning)에서 차단(blocking)으로 격상시키기 위한 기준은 다음과 같습니다:

제3자가 기록된 증거(evidence)로부터 해당 탐지 결과(finding)를 재유도(re-derive)할 수 있어야 합니다.

그것이 해당 검사(check)가 마법처럼 정확하다는 것을 의미하지는 않습니다.

그것은 실패 모드(failure mode)가 가시적이고, 재현 가능하며, 조정 가능하다(tunable)는 것을 의미합니다.

저장소(repo)는 경고(warn) 모드로 시작하여 어떤 탐지 결과가 유용한지 관찰한 다음, 나중에 노이즈가 적은 탐지 결과만을 병합 게이트(merge gates)로 격상시킬 수 있습니다.

이것이 아직 해결하지 못하는 것

Agent Gate는 여전히 의미론적 정확성(semantic correctness)을 증명하지는 못합니다.

테스트 파일 증거(test-file evidence)를 일치시키는 것이 테스트가 동작을 커버한다는 증거는 아닙니다. 그것은 변경 증거(change evidence) 또는 자기 일관성 증거(self-consistency evidence)입니다.

유지 관리자 재정의(Maintainer override) 저장 기능도 아직 구현되지 않았습니다. 이는 아마도 다음의 어려운 설계 질문이 될 것입니다: 만약 누군가 탐지 결과를 우회(bypass)한다면, 나중에 검사할 수 있을 만큼 내구성을 갖추기 위해 그 재정의(override) 정보가 어디에 저장되어야 하는가?

CODEOWNERS / 리뷰어 증거(reviewer evidence) 및 패키지 의존성 드리프트(package dependency drift) 또한 향후 과제입니다.

시도해 보세요

코딩 에이전트(coding agents)가 PR을 생성하는 저장소를 운영 중이시라면, 이러한 종류의 증거가 관찰(observe) 모드에서 유용한지 아니면 노이즈가 너무 많은지에 대한 피드백을 받고 싶습니다.

저장소:

https://github.com/sjh9714/Agent-Gate

공개 사항: 저는 Agent Gate를 유지 관리합니다. v0.2.1은 아직 프리릴리스(prerelease) 단계입니다. 어떤 탐지 결과라도 병합 게이트(merge gate)로 취급하기 전에 경고(warn) 모드로 시작하시길 권장합니다.