OpenClaw는 AGENTS.md 한 줄로 PR 증거 기준을 비디오로 바꿨습니다

OpenClaw 팀은 공용 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분 뒤에 이 PR을 머지했어요.

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 증거라는 뜻이에요. 실제 실행 화면에서 캡처하고, 민감 정보는 지운 상태로 첨부합니다.

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

예외 조항도 있습니다. 채널에서 보이는 채팅 동작은 모의 게이트웨이 하네스 판정으로 갈음할 수 있어요. 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 #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에서 가져오거든요. 팀은 지침 파일 하나로 작성자와 심사자를 함께 규율하는 셈이죠.

ClawSweeper는 PR #124013에 증거 신뢰도 6점 만점에 5점(등급명 diamond lobster)과 "미디어 증거 보너스"를 줬고, PR에서는 "proof: video" 라벨도 볼 수 있어요. 비디오는 사람이 읽고 봇이 채점하는, 두 독자를 위한 증거예요.

비디오는 누가 만드나요?

사람들이 비디오 증거에 흔히 드는 반론은 비용입니다. 개발자가 화면 녹화를 켜고 시나리오를 연기해야 한다면, 개발자는 숙제를 하나 더 떠안죠.

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를 읽는 에이전트들이 알아서 따릅니다.

사람 리뷰어도 그에 맞춰 코드를 읽고 버그를 찾는 일에서, 증거를 보고 판정을 내리는 일로 옮겨 가죠.

---