AGENTS.md에 넣은 한 줄이 PR 증거 기준을 비디오로 바꿨습니다

공용 AGENTS.md에 한 줄을 추가했더니, 에이전트가 만드는 PR 전체의 증거 기준이 달라졌습니다.

OpenClaw 창시자 Peter Steinberger(@steipete)의 트윗이 좋아요 665개, 리트윗 40회, 조회 7만 6천 회를 기록했어요. 원문은 이렇죠. "Added a short instruction to our shared AGENTS MD file to upload videos to each PR that changes UI state." UI 상태를 바꾸는 풀 리퀘스트(PR)마다 비디오를 올리라는 규칙입니다.

트윗에 함께 링크된 PR #124013은 새 규칙이 그대로 적용된 첫 사례였고, 트윗 게시 76분 뒤에 머지됐어요.

AGENTS.md 한 줄이 어떻게 정책이 되나요?

AGENTS.md는 AI 코딩 에이전트용 지침 파일입니다. 저장소 루트에 두면 Codex, Cursor, Copilot 같은 에이전트가 작업을 시작할 때 자동으로 읽죠. 6만 개가 넘는 공개 저장소가 채택했고, Claude Code처럼 자체 파일(CLAUDE.md)을 쓰는 도구도 임포트 한 줄로 끌어다 씁니다.

OpenClaw의 루트 AGENTS.md 첫머리는 단호해요. "Telegraph style. Root rules only." 전보체, 루트 규칙만. 이어서 "Skills own workflows; root owns hard policy and routing"이라고 못박습니다. 스킬은 세부 작업 흐름을, 루트 파일은 강제 정책을 맡죠.

PR 상당수를 에이전트가 만드는 저장소에서, 텍스트 지침은 권고가 아니라 실행 명령입니다. 한 줄을 추가하면 곧 정책이 바뀌는 구조예요.

규칙의 실제 문구는 무엇인가요?

새 규칙은 Validation 섹션에 들어갔습니다.

"UI-visible change (Control UI, native app, or user-visible chat/session behavior): before/after screenshots or a short video are mandatory PR evidence, captured from a real running surface and sanitized."

사용자에게 보이는 UI 변경에는 수정 전/후 스크린샷이나 짧은 비디오가 필수 PR 증거라는 뜻이에요. 실제 실행 화면에서 캡처하고, 민감 정보는 지운 상태로 첨부합니다.

트윗에서는 "비디오를 올려라"로 말했고 파일에는 "스크린샷 또는 짧은 비디오"로 정착했어요. 방향은 같습니다. 정지 화면 한 장이 아니라 시간축을 담은 증거를 기본값으로 삼는 쪽이죠.

예외 조항도 있습니다. 채널에서 보이는 채팅 동작은 모의 게이트웨이 하네스 판정으로 갈음할 수 있어요. UI 증거 캡처가 원천적으로 불가능하면, 불가능한 정확한 사유를 PR에 적어야 합니다.

증거 없이 UI 변경을 남기지 않는 규칙이지, 비디오가 만능이라는 규칙은 아니에요.

이 규칙은 어디서 나왔나요?

갑자기 나온 규칙이 아닙니다. 4주 전 사건의 일반화예요.

7월의 PR #110989(승인 UX 개편)에는 수정 전/후 스크린샷 네 장이 첨부됐습니다. 자동 리뷰 봇 ClawSweeper의 답은 이랬어요. 스크린샷은 유용하지만 모의 게이트웨이 하네스에서 찍은 것이라는 점, 그리고 "add redacted live Control UI evidence of a real approval arriving, being decided, and resolving"이라는 요구.

실제 승인이 도착하고 처리되고 종료되는 라이브 증거를 추가하라는 뜻입니다. 증거가 없는 PR이 아니라, 실환경 증거가 없는 PR이 추가 증거를 요구받았어요.

새 규칙은 그 요구를 일반화한 겁니다. 스크린샷에서 비디오로, 모의 환경에서 실제 실행 화면으로.

왜 정지 화면이 아니라 비디오인가요?

왜 비디오인지는 PR #124013이 보여줍니다. 제목은 "fix(ui): keep the chat transcript anchored while the pane resizes"예요. 채팅 창 크기를 바꿔도 읽던 위치가 고정되도록 하는 수정이죠.

문제는 창 크기 조절 시 채팅 기록이 위아래로 튀는 것이었습니다. 창을 줄이거나 사이드바를 드래그하면, 읽던 사람이 갑자기 다른 메시지로 이동했어요. 실사용 환경에서 제보된 문제였죠.

정지 화면으로는 증명할 수 없는 유형의 버그입니다. 행 측정값이 프레임마다 뒤늦게 들어오면서 화면이 여러 프레임에 걸쳐 움직였거든요. 튐은 상태가 아니라 과정입니다.

원인은 폭 변경 경로에서 가상화 컴포넌트의 측정 캐시를 통째로 지운 데 있었어요. 화면 밖 행이 전부 기본 추정값 120px로 붕괴합니다. 스크롤 위치는 고정인데 위쪽 콘텐츠 높이가 통째로 바뀌니, 보이는 영역이 다른 행을 가리키게 되는 구조죠.

수정은 캐시 삭제 자체를 제거하는 방향이었습니다. 기존의 동기 보정 경로를 재사용해 기준 행(앵커 행)이 제자리를 지키고, 화면 밖 행은 연결될 때 지연 보정돼요. 생산 코드는 4줄 추가·4줄 삭제로 순증 0줄, 테스트는 152줄 늘었습니다.

증거는 두 갈래입니다. 첫째, 수정 전/후 비디오 두 개예요. 창 폭을 1280→1100→960→820px로 줄였다 되돌리는 같은 시나리오에서, 수정 전에는 앵커 행이 화면 밖으로 사라지고 수정 후에는 제자리를 지킵니다.

둘째, 엔드투엔드 회귀 테스트입니다. 폭이 다른 메시지 120개를 만들고 중간 지점까지 스크롤한 뒤 1280→1000→820→1280px로 리사이즈해요. 수정 전에는 스크롤 위치가 7021에서 7278로 257px 밀렸죠. 수정 후에는 1000px 구간에서 0px, 820px 구간에서 42px(앵커 행 자체가 접힘선에 걸려 줄바꿈되는 정당한 이동), 1280px 복귀 시 시작값과 바이트 단위로 완전히 일치합니다. 테스트의 허용 경계는 60px 이하예요.

비디오는 사람 리뷰어만 위한 증거가 아닙니다. ClawSweeper가 모든 PR을 자동 채점하는데, 채점 기준 자체가 루트 AGENTS.md에서 나오거든요. 지침 파일이 작성자와 심사자를 동시에 규율하는 셈이죠.

PR #124013에는 "proof: video" 라벨이 붙었고, 증거 신뢰도는 6점 만점에 5점(등급명 diamond lobster)에 "미디어 증거 보너스"까지 붙었습니다. 비디오는 사람이 읽고 봇이 채점하는, 두 독자를 위한 증거예요.

비디오는 누가 만드나요?

비디오 증거의 흔한 반론은 비용입니다. 개발자가 화면 녹화를 켜고 시나리오를 연기해야 한다면, 규칙이 숙제가 되죠.

OpenClaw의 경우 다릅니다. AGENTS.md에 기본 녹화 수단까지 지정돼 있어요. Playwright의 recordVideo로 대시보드 URL에 대해 녹화하고, 구동 스크립트는 슬립이 아니라 UI 상태 단언을 기다리게 합니다. 비디오는 테스트 하네스가 자동으로 찍죠. 한계 비용은 0에 가깝습니다.

리뷰 시간으로도 이어집니다. PR #124013은 04:39에 생성돼 06:00에 머지됐어요. 81분. 리뷰어가 로컬에서 창 크기와 도킹 상태를 재현하지 않아도 동작 변화를 눈으로 확인할 수 있었던 점이 시간을 압축한 요인으로 볼 수 있습니다.

다만 비디오만으로 머지된 것은 아니에요. 수치 회귀 테스트와 형제 테스트 스위트가 함께 녹색이었고, 봇의 리뷰 사이클 네 차례를 거치며 지적 사항을 해결한 뒤에야 통과했습니다. 비디오는 리뷰 시간을 줄이는 증거이지, 다른 검증을 대체하는 증거는 아니죠.

한 가지 짚어 둘 점이 있습니다. AGENTS.md는 시스템이 강제하는 검증 장치가 아니라 모델이 읽고 따르는 지침이에요. 규칙이 실제로 지켜지려면 리뷰 봇이나 CI가 증거를 확인하는 절차가 함께 있어야 합니다. OpenClaw에서는 ClawSweeper의 채점이 그 역할을 맡죠.

내 저장소에는 어떻게 가져가나요?

첫째, 규칙 문구는 한 줄이면 됩니다. "UI 상태나 레이아웃을 바꾸는 PR에는 수정 전/후 비디오를 첨부한다. 실제 실행 화면에서 캡처한다." AGENTS.md에 넣는 순간, 그 파일을 읽는 모든 에이전트의 PR 작성 방식이 달라져요.

둘째, 적용 범위 판별 기준을 함께 적어둡니다. UI 상태·레이아웃·애니메이션·스크롤 변화는 비디오가 필요하고, 순수 로직이나 API 변경은 수치 테스트로 충분하죠. 기준이 한 문장으로 명시돼 있으면 에이전트가 매번 묻지 않습니다.

셋째, 예외 처리 방법을 정해둡니다. 캡처가 불가능하면 정확한 차단 사유를 PR에 남겨요. 증거가 없을 때 "증거 없음"이 아니라 "왜 없는지"가 남아야 리뷰가 진행됩니다.

남는 생각

저는 이 한 줄을 코드리뷰의 증거 기준이 바뀌는 신호로 읽습니다. 코드와 테스트라는 읽는 증거에 더해, 동작을 보여주는 보는 증거가 필수 항목으로 들어오는 국면이에요.

강제하는 비용은 작습니다. 파일에 한 줄. 나머지는 AGENTS.md를 읽는 에이전트들이 알아서 따릅니다.

사람 리뷰어의 역할도 그에 맞춰 이동하죠. 코드를 읽고 버그를 찾는 일에서, 증거를 보고 판정을 내리는 일로.

---

원문·소스

• steipete 트윗: https://x.com/steipete/status/2088486859244741020
• PR #124013: https://github.com/openclaw/openclaw/pull/124013
• OpenClaw AGENTS.md: https://github.com/openclaw/openclaw/blob/main/AGENTS.md
• 트윗 이미지: https://pbs.twimg.com/media/HPvLqZjbUAATN-0.jpg?name=orig