interfaces: 코딩 에이전트가 UI를 도메인별로 검토하게 만드는 8개 스킬

9bow · 8월 11, 2026, 9:30오후

interfaces 소개

코딩 에이전트에게 화면 하나를 보여주고 "UI를 다듬어줘"라고 시키면 대체로 비슷한 결과가 돌아옵니다. 모서리를 둥글리고, 그림자를 조금 넣고, 전환 애니메이션을 붙이는 식입니다. 아이콘만 있는 버튼에 접근 가능한 이름이 없다거나 키보드로는 닿지 않는 경로가 있다는 지적은 그 목록에 잘 오르지 않습니다. 모델이 그 규칙을 모르기 때문은 아닙니다. 무엇을 어떤 순서로 볼지 정해 두지 않으면 눈에 먼저 띄는 표면부터 손대게 되고, 프롬프트 한 줄에는 그 순서가 담기지 않습니다. interfaces 는 그 순서를 스킬 파일에 고정해 둔 에이전트 스킬(Agent Skills) 모음입니다.

interfaces가 택한 방법은 규칙을 늘리는 대신 소유권을 쪼개는 것 입니다. 접근성, 레이아웃, 인터페이스 문구, 타이포그래피, 색, 시각적 마무리를 여섯 개의 독립된 스킬로 나누고, 규칙 하나가 정확히 한 스킬에만 존재하도록 못 박았습니다. 대비 검사를 예로 들면, 대비가 필요한지와 그 쌍이 기준을 통과하는지는 better-accessibility 가 판단하고, 실제로 렌더된 색 쌍을 측정하고 색을 바꾸는 일은 better-colors 가 맡습니다. 같은 문제를 두 스킬이 각자 보고하는 상황을 구조로 막아 둔 셈입니다. 여기에 여섯 도메인을 순서대로 돌리고 최종 판정을 내리는 better-interface, 브랜치나 Pull Request 같은 변경 을 리뷰 대상으로 삼는 interface-review 가 더해져 모두 8개가 됩니다.

만든 사람은 디자인 엔지니어 Jakub Krehel입니다. OKLCH 색 공간을 실험해 볼 수 있는 oklch.fyi 를 만들었고, 인터페이스 제작을 다루는 온라인 매거진 Interfaces 를 운영하고 있습니다. 저장소는 코드가 아니라 마크다운 문서로만 이루어져 있어서 빌드나 테스트 도구가 없고, Claude Code 플러그인과 skills CLI 두 경로로 배포됩니다. 이 글에서는 8개 스킬이 어떻게 나뉘어 있는지, 리뷰가 어떤 순서와 형식으로 진행되는지, 그리고 어떤 팀에 맞고 어떤 팀에는 과할지를 정리합니다.

기존 코드 리뷰와 interfaces의 차이

일반적인 코드 리뷰 도구는 정확성, 테스트, 보안, 성능을 봅니다. interfaces는 그 영역을 의도적으로 비워 두고 인터페이스 품질만 다룹니다. interface-review 는 리뷰 중 정확성이나 보안 문제가 보이면 "한 번 언급하고 프로젝트의 일반 코드 리뷰로 넘기라"고 명시하고 있습니다. 겹치는 영역을 줄여야 리포트가 짧아지고, 짧은 리포트라야 실제로 읽히기 때문입니다.

프롬프트 한 줄로 리뷰를 시키는 방식과 비교하면 차이는 세 곳에서 드러납니다.

항목	프롬프트 한 줄 리뷰	interfaces
검토 범위	매번 달라짐	6개 도메인을 고정된 순서로 전부 검토, 못 본 도메인은 `Not reviewed` 로 표시
지적 개수	제한 없음	`quick` 5개, `full` 15개 상한
근거	서술로 대체되는 경우가 많음	모든 지적이 `path/to/file:line` 과 현재 구현을 인용
심각도	모델이 그때그때 판단	HIGH·MEDIUM·LOW 3단계 + 즉시 HIGH로 올리는 8가지 조건

검토 순서도 임의가 아닙니다. 접근성 → 레이아웃 → 문구 → 타이포그래피 → 색 → 시각적 마무리 순으로 도는데, 저자는 그 이유를 "근본적인 결함이 표면 마무리에 가려지지 않도록" 이라고 적어 두었습니다. 그림자 두께를 논하기 전에 그 버튼에 키보드로 닿는지를 먼저 확인하자는 배치입니다.

interfaces의 8개 스킬 구성

여덟 개 중 이름을 직접 불러 실행하는 것은 better-interface 와 interface-review 둘뿐입니다. 나머지 여섯 개는 작업 문맥에 따라 자동으로 불려 옵니다. 소유 범위는 저장소의 AGENTS.md 에 표로 정리되어 있는데, 경계가 애매해지기 쉬운 지점을 특히 세밀하게 갈라 둔 점이 눈에 띕니다. 의미 기반 제목 구조(h1~h6)는 접근성이 소유하고 제목 단계가 화면에 어떻게 보일지는 타이포그래피가 소유하며, 텍스트 잘림 처리 자체는 타이포그래피가, 잘리지 않을 만큼 자리가 있는지는 레이아웃이, 그 문구 자체는 인터페이스 문구 스킬이 맡는 식입니다.

여섯 도메인 스킬 중 better-colors 는 규칙이 가장 수치화되어 있어 살펴볼 만합니다. 색을 oklch(L C H / alpha) 표기로 다루면서 밝기 L은 0~1, 채도 C는 0~0.4 근처, 색상 H는 0~360도 범위로 두고, 다음과 같은 판정 기준을 표로 못 박았습니다.

기준	값
밝은 배경과 어두운 배경의 경계	L > 0.73이면 밝은 배경으로 보고 어두운 글자 사용
밝은 배경에서의 밝기 격차	배경 L > 0.9일 때 전경 L < 0.35
팔레트 색상 흔들림	단계별 색상 각도 차이가 10도를 넘으면 눈에 보이는 흔들림
본문 텍스트 대비 (APCA)	절댓값 Lc 75 이상 필수, 90 이상 권장
본문 외 텍스트 대비 (APCA)	절댓값 Lc 60 이상
WCAG 2 일반 텍스트	AA 4.5:1, AAA 7:1

다만 이 스킬은 색 표기를 바꾸는 일에 보수적입니다. 프로젝트가 이미 hex나 RGB 토큰 체계를 쓰고 있다면 "일관된 hex 또는 RGB 토큰 체계가 고립된 수정 하나를 위해 두 번째 색 표현을 들이는 것보다 낫다" 는 이유로 기존 표기를 유지하라고 지시합니다. 스킬을 불러왔다는 사실 자체가 마이그레이션의 근거는 아니라는 것입니다.

interfaces의 리뷰 오케스트레이션

better-interface 는 도메인 규칙을 하나도 갖지 않고 진행 방식만 소유합니다. 호출 형식은 [quick|full] [범위] 이고, 첫 토큰이 정확히 quick 또는 full 일 때만 모드로 해석하며 그 외에는 전부 범위로 넘깁니다. quick 은 주 경로와 거기서 실제로 도달하는 상태만 보고 HIGH와 MEDIUM만 보고하며 5개까지, full 은 빈 상태·로딩·오류·좁은 화면 폭까지 포함해 15개까지 보고합니다.

심각도를 평균으로 뭉개지 않기 위한 장치도 있습니다. 다음 조건 중 하나가 도메인 스킬에서 확인되면 그 지적은 화면이 아무리 사소해도 즉시 HIGH가 되고, quick 모드에서도 빠지지 않습니다.

접근 가능한 이름이 없는 상호작용 컨트롤
키보드로 도달하지만 포커스 표시가 보이지 않는 컨트롤
포인터로는 닿지만 키보드로는 닿지 않는 경로
prefers-reduced-motion 을 무시하는 모션이나 자동 재생 콘텐츠
320px 폭이나 200% 확대에서 잘리거나 가려져 닿을 수 없는 콘텐츠
렌더된 대비 쌍이 요구 비율에 미달하는 본문·컨트롤 텍스트
색만으로 전달되는 상태나 의미
확인 절차도 되돌리기도 구분되는 처리도 없는 파괴적 동작

상한선 때문에 이런 항목이 잘려 나가지 않도록, 상한을 넘으면 이들을 먼저 나열하고 몇 개가 제외됐는지 밝히도록 되어 있습니다. 저자의 표현으로는 "상한이 리포트를 짧게 만들 수는 있어도, 차단 수준의 문제가 보고되지 않은 이유가 될 수는 없다" 입니다.

출력 형식에서 눈에 띄는 것은 검토했지만 지적하지 않기로 한 후보 를 따로 적게 한 부분입니다. quick 은 1~3개, full 은 2~5개를 요구하고, 왜 넘겼는지까지 적습니다. 무엇을 봤는지 드러나야 "지적이 없다"와 "안 봤다"가 구분되기 때문입니다. 마지막에는 Block(HIGH 잔존), Needs changes(MEDIUM·LOW만 잔존), Approve(잔여 없음) 중 하나로 끝납니다. 리뷰 요청은 기본적으로 읽기 전용이라, 함께 고쳐 달라고 하지 않는 한 코드를 수정하지 않습니다.

interfaces의 변경 범위 리뷰

interface-review 는 화면이 아니라 변경 을 리뷰합니다. 대상을 지정하지 않으면 세 단계로 범위를 정하는데, 순서가 중요합니다. 먼저 git merge-base origin/<기본브랜치> HEAD 보다 HEAD가 앞서 있으면 그 구간과 미커밋 변경을 함께 보고, 아니면 더러운 작업 트리를, 그것도 아니면 HEAD~1..HEAD 를 폴백으로 씁니다. 작업 트리를 먼저 확인하면 포맷팅 수정 하나가 열두 개 커밋짜리 브랜치를 가려 버리는데도 리포트는 전체를 봤다고 주장하게 된다는 것이 그 이유입니다.

변경된 파일을 그대로 리뷰 대상으로 삼지 않는 점도 특징입니다. 파일은 증거일 뿐이므로 그 파일이 렌더되는 화면까지 한 단계 확장하고, 디자인 토큰이나 공유 프리미티브처럼 한 줄이 제품 전체에 닿는 경우에만 두 단계까지 갑니다. 확장은 최대 5개 소비자까지만 하고, 확장하지 않은 개수를 리포트에 밝힙니다.

그리고 diff의 - 쪽을 읽습니다. 회귀는 변경 후 상태만 봐서는 보이지 않기 때문입니다. 제거된 aria-label, 사라진 포커스 스타일처럼 무언가가 빠졌는데 대체된 것이 없으면 그 지적에는 Regression 상태가 붙습니다. 모든 지적은 Introduced(이번 변경이 만듦), Regression(멀쩡하던 것을 약화시킴), Pre-existing(건드린 코드에 원래 있던 문제) 셋 중 하나로 분류되고, 판단이 애매하면 기준 커밋에 대고 git blame 으로 확인합니다.

git blame -L <line>,<line> "$BASE" -- path/to/file

Pre-existing 은 상한에도 판정에도 포함되지 않습니다. 오래된 파일을 하나 건드렸다는 이유로 그 파일 전체 감사가 시작되지 않게 하려는 장치이고, 기존 문제만 남은 변경은 Approve 로 끝납니다. 작업 트리 보호도 명시되어 있습니다. Pull Request는 ref만 가져와서 그 자리에서 읽고, gh pr checkout · git checkout · git switch · git stash 는 어떤 모드에서도 허용되지 않습니다. 렌더링 확인이 필요하면 격리된 워크트리를 쓰고 끝나면 지웁니다.

git worktree add /tmp/review-482 refs/remotes/pr/482

interfaces 설치 및 사용법

Claude Code 플러그인으로 설치하면 8개 스킬이 한꺼번에 들어오고 이후 업데이트도 그 자리에서 반영됩니다. Claude Code 안에서 실행합니다.

/plugin marketplace add jakubkrehel/skills
/plugin install interfaces@interfaces

skills CLI를 쓰면 Claude Code 외에 Codex 등 다른 에이전트에서도 사용할 수 있고, 설치할 스킬을 골라 담을 수 있습니다.

npx skills add jakubkrehel/skills
npx skills add jakubkrehel/skills --skill '*'

better-interface 는 여섯 도메인 스킬을 조율하고 interface-review 는 그 위에 변경 범위 해석을 얹는 구조라, 부분 설치보다 전체 설치가 의도한 동작에 가깝습니다. 호출은 모드와 대상을 뒤에 붙이는 형태이며, 플러그인으로 설치하면 이름 앞에 interfaces: 가 붙습니다.

/interfaces:better-interface full checkout flow
/interfaces:interface-review quick pr 482

skills CLI로 설치했다면 접두사 없이 /better-interface, Codex에서는 $better-interface 형태로 부릅니다. 접두사는 이름을 불러 실행하는 두 스킬에만 영향을 주고, 여섯 도메인 스킬은 어느 쪽이든 문맥에서 자동으로 불려 옵니다.

interfaces는 누구에게 유용한가

웹 프론트엔드를 코딩 에이전트와 함께 만들고 있고, 리뷰 결과가 매번 다른 기준으로 돌아와 곤란했다면 잘 맞습니다. 특히 접근성 점검을 사람이 계속 챙기기 어려운 소규모 팀이라면, 즉시 HIGH로 올라가는 8가지 조건만으로도 얻는 것이 있습니다. 반대로 이미 자체 디자인 시스템 문서와 리뷰 체크리스트가 자리 잡은 팀이라면 새 규칙을 들이는 것보다 기존 문서를 스킬 형태로 옮기는 편이 나을 수 있습니다. 스킬 자체가 프로젝트의 관례 문서를 먼저 읽도록 되어 있긴 하지만, "스타일 가이드에 있다"는 사실이 지적을 무르게 하지는 않는다 는 입장이라 기존 관례와 부딪힐 여지는 남아 있습니다.

적용 범위도 확인이 필요합니다. 규칙 대부분이 CSS, ARIA, prefers-reduced-motion, OKLCH처럼 웹 플랫폼을 전제로 쓰여 있어서, 네이티브 모바일이나 게임 UI에는 그대로 옮겨 붙지 않습니다. 저장소가 문서만으로 이루어져 있다는 점도 양면입니다. 설치 부담이 거의 없고 내용을 직접 읽어 팀 사정에 맞게 고치기 쉬운 대신, 검사를 자동으로 실행해 주는 도구가 아니라 에이전트가 참조할 기준일 뿐이라 결과 품질은 사용하는 모델에 따라 달라집니다.

interfaces의 라이선스

interfaces는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

interfaces 스킬 안내 페이지

interfaces 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 도구를 직접 설치해 사용해보셨다면, 파이토치 한국 사용자 모임 회원들을 위해 경험이나 팁을 댓글로 남겨주세요!