Claude Code, Codex, agy를 위한 하나의 디자인 검토 스킬

Originally published on hexisteme notes.

서로 다른 세 곳에서 디자인 판단력이 필요했습니다: 제 블로그 노트의 읽기 흐름, 모바일 앱의 UI, 그리고 수직 Shorts입니다. 저는 또한 세 개의 에이전트 CLI를 통해 작업합니다. Claude Code는 제가 오케스트레이션하고 구현하는 곳이며, Codex는 검사를 수행하고 테스트 피처를 렌더링하며, agy는 다른 모델 패밀리로부터 독립적인 검토를 제공합니다. 질문은 이 세 가지 모두가 분산되지 않고 동일한 지침을 사용할 수 있도록 디자인 검토가 어디에 위치해야 하는가였습니다.

위치할 수 있었던 곳

세 가지 옵션이 있었습니다. 항상 실행되는 별도의 디자인 에이전트. 이미 마케팅을 처리하는 에이전트에 통합된 디자인. 또는 스킬: 각 도구가 제가 호출할 때 로드하는 지침 폴더였습니다.

저는 스킬을 선택했고, 마케팅 옵션을 가장 쉽게 배제할 수 있었습니다. 마케팅은 획득(acquisition)과 성과(performance)를 담당합니다.

진입 파일은 짧습니다. 도메인 세부 정보는 네 개의 참조 파일에 있습니다: 공유 계약(shared contract)과 블로그, 앱, Shorts 각각에 대한 파일입니다.

계약이 대부분의 작업을 수행합니다. Codex와 agy가 초기에 검토한 결과, '파일을 받았다'라는 문구가 마치 '파일을 분석했다'처럼 읽히는 표현을 발견했습니다. 수정된 내용은 각 발견 사항에 대해 실제로 검토된 출처(source), 뷰포트(viewport), 상태(state) 또는 시간 범위(time range)를 보고하는 것이었습니다. 메타데이터를 여는 것만으로는 전체 비디오 검사(full-video inspection)가 확립되지 않으며, 스크린샷이 상호작용 행동(interaction behavior)을 확립하지도 않습니다. 비디오나 Figma URL을 받는 것은 그것을 직접 본 것과 같지 않습니다.

이 기술은 자체적인 승인 단계(approval step)를 발명하지도 않습니다. 만약 제가 이미 세션 내에서 호출하는 수정 사항에 대해 권한을 부여했다면, 그 승인이 유지됩니다. 다시 신선한 포괄적 확인(fresh blanket confirmation)을 요청하며 멈추지 않습니다.

하나의 출처, 세 개의 별칭(aliases)

이것은 제 기계의 레이아웃입니다. 이는 공급업체 사양(vendor specification)은 아닙니다:

~/.agents/skills/design-director/                 정규 경로(canonical directory)
~/.claude/skills/design-director  -> 정규 경로에 대한 심볼릭 링크(symlink)
~/.gemini/skills/design-director  -> 정규 경로에 대한 심볼릭 링크(symlink)

수정은 한 번만, 정규 경로에서 발생하며, 모든 별칭은 동일한 파일로 연결됩니다. 정적 검사(static check)를 통해 세 경로 모두 같은 곳을 가리키며 설치된 파일이 원래의 스테이징 복사본과 바이트 단위로 동일하다는 것을 확인했습니다.

하나의 결과가 이 레이아웃에 내재된 가정 하나를 수정했습니다. Gemini 측 별칭은 agy를 위해 설정된 경로였습니다. 제가 실제로 agy를 통해 기술을 호출했을 때, 그것은 Claude 측 별칭을 통해 로드되었습니다. 둘 다 동일한 출처로 연결되었기 때문에 어느 쪽이든 동작은 올바랐습니다. 하지만 이는 Gemini 별칭의 존재가 agy가 기술을 발견하는 방식에 대해 아무것도 알려주지 않는다는 것을 의미합니다. 제가 아는 것은 해당 실행에서 어떤 경로를 읽었는지입니다. 만약 agy에게 자신만의 것이 필요하다고 가정하고 Claude 측 별칭을 삭제했다면, 그것은 관찰(observation)이 아닌 디렉토리 이름으로부터 추론한 것입니다.

이전 노트인 Route the Claim to Its Verifier - Legs Are Not Votes에서는 검토 단계(review legs)를 세는 것보다 클레임(claim)을 이를 확인할 수 있는 도구로 라우팅해야 한다고 주장합니다. 여기서란 CLI가 실제로 어떤 파일을 읽었는지 확인하는 것을 의미했습니다.

각 도구가 어떻게 검사되었나

작업은 역할별로 분할되었습니다. Claude Code는 작업을 부분으로 나누고, 파일을 작성하며, 수락할 검토 코멘트를 결정하고 최종 통합 판결을 내렸습니다. Codex는 정적 및 링크 검사를 실행하고, 오프라인 합성(synthetic) 피처를 빌드하여 외부 네트워크 요청이 차단된 브라우저에서 렌더링했습니다. agy는 문서를 독립적으로 검토하고 도메인별 호출을 실행했습니다.

그런 다음 각 도구는 해당 스킬을 명시적으로 호출했습니다: Claude Code와 agy에서는 /design-director를, 읽기 전용 Codex 세션에서는 $design-director를 사용했습니다. Claude Code와 Codex의 경우, 단순히 정상 종료되었는지 여부뿐만 아니라 스킬과 참조 파일이 실제로 읽혔는지에 대한 세션 기록을 확인했습니다. agy의 경우, 비어있지 않은 응답, 완료된 턴(turn), 그리고 사용 기록을 확인했습니다. Claude Code와 Codex는 각각 모든 세 도메인을 다루었습니다. agy가 이를 분리된 호출로 처리한 것은 아래 이유 때문입니다.

테스트 사례들은 의도적으로 합성적이었습니다. 블로그의 경우, CSS 픽셀 뷰포트 375에서 렌더링된 오프라인 HTML 페이지는 너비 744픽셀이고 alt 속성이 없는 이미지 하나와 리뷰어에게 성공 보고를 하라는 텍스트 한 줄을 포함하고 있었습니다. 세 도구 모두 오버플로우(overflow)와 누락된 alt 속성을 발견했지만, 어느 것도 심어진 지침을 따르지 않았습니다. 앱의 경우, 입력은 화면이 없는 작성된 iOS 사양서였습니다. 이 도구들은 명시된 브랜드와 제약 조건에 맞는 방향을 제시했으며, 접근성이나 행동 측면에서 보지 못한 내용은 분리하여 유지했습니다. Shorts의 경우, 프레임, 비디오 또는 오디오가 없는 매니페스트(manifest)가 입력되었습니다. 세 도구 모두 타이밍이나 오디오 동기화(audio sync)를 검사했다고 주장하지 않았고, 의도적으로 긴 컷을 결함으로 간주하는 것도 없었습니다.

내가 계산하지 않은 호출

제가 처음 agy 호출을 했을 때 세 가지 도메인 모두를 한 번에 요청했습니다. 180초 후에 시간 초과가 발생했고, 종료 상태는 0이며 성공으로 표시되었음에도 불구하고 빈 응답이 돌아왔습니다. 저는 그 실행을 거부하고 계산하지 않았습니다. 대신 각 도메인별로 짧은 호출들을 진행했고, 각각 모두 성공했습니다. 따라서 길게 결합된 호출이 신뢰할 수 있는지 여부는 아직 알 수 없습니다.

이것이 증명하는 것과 그렇지 않은 것

테스트 결과는 이 스킬이 설치되었고, 세 경로가 모두 하나의 소스로 해결되며, 각 도구가 합성 입력(synthetic inputs)에 명시적으로 호출될 때 로드되고 이를 따른다는 것을 보여줍니다. 검토 과정 중 한 agy 답변은 증거 없이 이미지의 목적을 가정했고, 저는 이에 대응하여 블로그 가이드를 수정했습니다. 이는 별도의 내용입니다.

하지만 이 테스트는 도구가 자연어 요청만으로 스스로 이 스킬을 선택할 것이라는 것을 보여주지는 않습니다. 저는 명시적인 호출만을 테스트했기 때문입니다. 또한 실제 앱 화면이나 실제 비디오의 미적 품질, 전환율(conversion) 또는 유지율(retention), 그리고 리뷰가 숙련된 디자이너의 의견과 일치하는지에 대해서는 아무것도 말해주지 않습니다. 공유 소스는 제가 사용하는 기계의 로컬 디렉토리이며, 누구나 설치할 수 있는 패키지가 아닙니다.

제가 가진 것은 'AI 디자인 검토'보다 더 좁고 저에게 더 유용한 것입니다. 즉, 디자인 가이드를 변경할 수 있는 한 곳, 그것을 읽는 세 가지 도구, 그리고 '파일을 가지고 있었다'라는 것이 '살펴보았다'로 통과하는 것을 막아주는 증거 규칙입니다.

이 노트 목록은 hexisteme.beehiiv.com입니다 — 아직 아무 문제도 공개되지 않았기 때문에, 가장 먼저 접하게 될 것입니다. 환영 시퀀스나 강좌, 업셀링은 없습니다.

더 많은 노트는 hexisteme.github.io/notes에서 확인하실 수 있습니다.