AI 에이전트 UI 디자인 가드레일 문서 원본 보기

'''AI 에이전트 UI 디자인 가드레일'''은 코딩 에이전트가 제품 맥락과 디자인 원칙을 공유하고, 반복 가능한 명령·정적 검사·브라우저 검토를 통해 프런트엔드 품질을 일정 범위 안에 유지하게 하는 작업 체계이다.

== 개요 ==

코딩 에이전트는 화면을 빠르게 만들 수 있지만, 명시적인 맥락이 없으면 학습 자료에서 자주 본 서체, 그라디언트, 카드 배치와 장식 요소를 반복하기 쉽다. [https://github.com/pbakaus/impeccable pbakaus/impeccable]은 이 문제를 디자인 지침만으로 다루지 않고, 프로젝트 설정과 작업 명령, 결정론적 탐지 규칙, 브라우저 기반 반복 검토를 한 묶음으로 제공한다. 이 문서에서 말하는 가드레일은 디자인을 자동으로 확정하는 규칙이라기보다 에이전트가 제품의 대상 사용자·브랜드 방향·목소리·색·서체·컴포넌트를 계속 참조하게 만드는 운영 장치에 가깝다.

프로젝트 README 기준으로 Impeccable은 하나의 스킬 아래 23개 명령과 59개 결정론적 탐지 규칙을 제공한다. 결정론적 검사는 LLM이나 API 키 없이 CLI와 브라우저 확장에서 실행할 수 있고, 의미와 정서적 인상을 다루는 평가는 별도의 LLM 기반 비평 항목으로 보완한다. 수량과 지원 도구는 빠르게 바뀔 수 있으므로 여기의 설명은 2026년 8월 16일 확인한 README를 기준으로 한다.

== 핵심 구조/작동 방식 ==

=== 디자인 맥락의 고정 ===

첫 단계인 <code>/impeccable init</code>은 만들 화면이 마케팅·포트폴리오 같은 브랜드 표면인지, 앱·대시보드 같은 제품 표면인지 구분한다. 이어 <code>PRODUCT.md</code>를 작성하고 <code>DESIGN.md</code> 작성을 제안한다. 이후 명령은 이 파일에 기록된 사용자, 제품 분야, 문체, 피해야 할 참고 사례, 색상, 타이포그래피와 컴포넌트를 읽는다. 기존 코드에서 디자인 체계를 문서화하는 <code>document</code>, 반복 요소와 토큰을 추출하는 <code>extract</code>도 이 맥락층을 보강한다.

=== 작업 명령과 검토 루프 ===

명령은 목적별로 나뉜다. <code>shape</code>와 <code>craft</code>는 구현 전 구조화와 전체 제작을, <code>critique</code>는 위계·명료성·정서적 인상을, <code>audit</code>는 접근성·성능·반응형 품질을 다룬다. <code>polish</code>는 출하 전 정리, <code>harden</code>은 오류 처리·국제화·텍스트 넘침·경계 조건, <code>adapt</code>는 기기별 조정을 담당한다. <code>typeset</code>, <code>layout</code>, <code>colorize</code>, <code>animate</code>처럼 수정 의도를 명시하는 명령도 있어 “더 좋게”라는 모호한 지시를 공통 어휘로 바꾼다.

<code>live</code> 모드는 브라우저에서 요소별 시각 변형을 비교하며 반복하는 경로를 제공한다. 새 화면은 먼저 고해상도 시안을 만든 뒤 코드로 맞추는 comp 경로와, 코드에서 바로 시작하는 경로 가운데 선택할 수 있다. 선택은 프로젝트 설정에 기본값으로 기록되지만 세션에서 바꿀 수 있다. 이미지 생성 기능이 없는 환경에서는 이 선택 자체가 나타나지 않는다고 README가 설명한다.

=== 자동 탐지와 예외 관리 ===

탐지기는 과도하게 쓰인 서체, 보라색 계열 그라디언트, 중첩 카드, 작은 터치 대상, 건너뛴 제목 단계, 지나치게 긴 행 등 코드에서 판별할 수 있는 패턴을 찾는다. 디렉터리·파일·URL을 검사하고 JSON 결과도 출력하므로 로컬 점검이나 CI에 연결할 수 있다. 프로젝트 설정에서 규칙·파일·값을 제외하거나, 사유가 적힌 인라인 주석으로 파일 또는 줄 단위 예외를 둘 수 있다. 여러 코딩 도구용 훅은 UI 파일 편집 뒤 탐지 결과를 에이전트 흐름에 돌려주며, 도구에 따라 별도 신뢰 또는 훅 승인이 필요하다.

== 활용 ==

새 제품에서는 요구를 <code>shape</code>로 정리하고 <code>craft</code>로 구현한 뒤 <code>audit</code>와 <code>polish</code>를 통과시키는 흐름을 만들 수 있다. 이미 운영 중인 서비스에서는 <code>document</code>로 현재 규칙을 복원하고, <code>extract</code>로 토큰과 컴포넌트를 정리한 다음 특정 화면만 점진적으로 개선할 수 있다. 긴 다국어 문구, 비어 있는 데이터, 오류 상태가 많은 업무용 UI에는 <code>harden</code>이 유용하다. 팀에서는 공유 설정과 <code>DESIGN.md</code>를 버전 관리해 서로 다른 에이전트와 개발자가 같은 기준을 읽게 할 수 있다.

== 한계 및 주의점 ==

59개 규칙은 코드에서 안정적으로 찾을 수 있는 징후에 한정된다. 사용자가 실제로 과업을 끝낼 수 있는지, 정보 구조가 업무와 맞는지, 브랜드가 적절한 감정을 전달하는지는 탐지 결과만으로 확정할 수 없다. 접근성 역시 자동 검사만으로 완결되지 않으므로 키보드 조작, 보조 기술, 실제 기기와 사용자 검증이 따로 필요하다.

README의 금지 예시는 기본 방향이지 모든 제품에 적용되는 절대 규칙이 아니다. 브랜드 서체나 의도된 모션처럼 타당한 예외는 근거와 함께 설정에 남겨야 한다. 자동 훅이 직접 코드를 고치거나 검사를 차단하는 방식은 제공자마다 다르므로, 설치 후 생성된 훅 정의와 수정 범위를 검토해야 한다. 또한 프로젝트의 명령 수, 탐지 규칙과 지원 도구는 업데이트될 수 있으므로 재현 가능한 팀 운영에는 사용 버전과 확인 날짜를 기록하는 편이 안전하다.

== 함께 보기 ==

* [[최근 GitHub Star 연구 주제]]
* [[에이전트 전용 브라우저]]
* [[에이전트 기반 비디오 편집]]
* [[멀티모달 에이전트 플러그인]]

== 출처 ==

* [https://github.com/pbakaus/impeccable pbakaus/impeccable README] — 기능, 명령, 탐지기, 설치·훅 구조. 2026년 8월 16일 확인.
* [https://impeccable.style/docs/detector Impeccable Detector 문서] — README가 연결하는 공식 탐지기 문서. 2026년 8월 16일 확인.

[[분류:인공지능 에이전트]]
[[분류:사용자 인터페이스]]
[[분류:소프트웨어 품질]]
[[분류:오픈 소스]]
[[분류:GitHub Star 연구]]