5장 AI 에이전트와 함께 일하기
Leysys는 코드의 대부분을 AI 에이전트가 쓴다는 전제로 디자인 시스템과 작업 방식을 설계합니다. 사람은 결정하고, 에이전트는 글로 정한 규칙 안에서 실행하고 검증합니다.
왜 필요한가
leysys-design의 목표는 AI 에이전트 개발 환경에 맞춘 범용 디자인 시스템입니다. 팀 전원이 AI 에이전트를 쓰고, 코드의 대부분을 AI가 생성합니다. 개발자가 「이런 화면을 만들어 달라」고 하면 AI가 디자인 시스템의 클래스만으로 일관된 화면을 만들어야 합니다. 에이전트는 빠르지만 실패하는 방식이 일정합니다.
- 그럴듯한 이름을 발명합니다. 2026-08-09 KST 한 제품 저장소를 시작할 때 정본에 없는 DS 클래스 10개가 코드에 들어갔습니다.
- 학습한 외부 관행으로 돌아갑니다. 학습 자료에는 shadcn/ui·Nuxt UI·DaisyUI·Bootstrap 어휘가 대부분을 차지해서, Leysys 규칙과 외부 관행이 부딪히는 지점에서 외부 쪽으로 미끄러집니다. EDS의 핵심 동작 버튼은
e-button-primary-bold인데 Nuxt UI 식의e-button-primary-solid를 쓰는 식입니다. - 있는 클래스를 없는 조합으로 씁니다. Leyve Console의 한 표에서 AI가 텍스트 입력용 클래스를 native
<select>에 붙였습니다. 클래스는 모두 실재했지만 EDS가 정의한 적 없는 조합이어서 펼침 화살표가 어긋났습니다. 근본 원인은 EDS에 native select 컴포넌트가 없었던 것이었고, 정본에 그 컨테이너(현재.e-select)를 만들었습니다. - 의도된 설계를 결함으로 봅니다. AI 감사가 비슷한 이름의 축을 헷갈려 의도된 결정 4건을 결함으로 보고한 일이 있었습니다.
원칙
예측할 수 있게 만듭니다
예외와 특수 사례를 줄이고 이름·구조·토큰 패턴을 일관되게 둡니다. 색과 크기는 공식에서 도출하므로 규칙을 알면 같은 값에 도달합니다. 쌍을 이루는 클래스는 기본값과 상관없이 양쪽을 모두 정의합니다. -horizontal과 -vertical을 모두 두면 에이전트가 어느 쪽을 써도 동작합니다.
저장소마다 에이전트 계약을 둡니다
저장소마다 에이전트가 먼저 읽는 규칙 파일 AGENTS.md를 둡니다. CLAUDE.md는 제목만 다른 같은 내용이고, 검사 스크립트가 제목을 뺀 전체가 같은지 확인합니다. 에이전트 도구가 달라도 운영 규칙은 하나입니다.
제품 저장소의 AGENTS.md 맨 위에는 디자인 정본이 정한 기본 블록 아홉 항목을 그대로 복사합니다. 정본에서 고치고 채택은 저장소가 소유한다는 원칙, Foundation/Token → Component → Pattern → (선택) Template → Page/Product 작업 순서, 게시된 classes.json에 없는 클래스를 잡는 존재 검사, 채택 PR의 출처 기록, 공통 역할 체계 등이 들어 있습니다. 지침만으로 부족한 곳은 권한으로도 막습니다. 새 제품 저장소는 에이전트 권한 설정으로 DS 복사본 경로의 직접 편집을 거부하고, 정본 item은 파일 복사로 채택합니다. 블록의 정본은 leysys-design이고, 각 제품은 다음 유지보수 때 자체 PR로 최신 블록을 채택합니다.
범위를 먼저 고정하고, 결과는 짧게 남깁니다
에이전트는 파일을 고치기 전에 변경 수준, 바꿀 공개 계약, 영향 경로, 실행할 검사, 작업을 끝낼 권한 범위를 먼저 정합니다. 같은 내용에 같은 검사를 반복하지 않습니다(4장). 성공 로그는 명령·PASS/FAIL·테스트 수·소요 시간만 남기고, CI는 요약 상태만 확인합니다. 작은 수정 하나를 배포하는 동안 반복된 CI 감시와 세 번의 push 검사가 5만 token이 넘는 출력을 만든 일이 있었습니다. 완료 보고에는 바뀐 것, 근본 원인과 확정한 계약, 실제로 실행한 검증과 수치, commit·push·PR·release 결과, 남은 위험과 일부러 실행하지 않은 검사를 적습니다.
헷갈리는 축을 한 곳에 모읍니다
docs/specs/DS-GOTCHAS.md는 헷갈리기 쉬운 축과 어휘를 모은 주의사항 문서입니다. 출발점은 「AI가 헷갈리면 사람은 더 헷갈린다」입니다.
| 헷갈리는 쌍 | 구분 |
|---|---|
bold · solid | bold는 강조 위계(weight), solid는 시각 형태(form)입니다. EDS Button 한 인스턴스에서 두 축을 섞지 않습니다 |
outline · outlined | 명사 outline은 버튼·배지 같은 동작·라벨의 형태, 형용사 outlined는 카드·입력 같은 컨테이너의 외형입니다 |
Content · Body | Content는 Root와 구분되는 별도 경계, Body는 머리글·본문·바닥글의 가운데 절입니다 |
감사 전에는 세 가지를 지킵니다. 축이 헷갈리면 이 문서를 먼저 봅니다. 결함이라고 판단하기 전에 결정 기록에서 의도된 결정인지 확인합니다. 비슷한 이름의 값이 둘이면 다른 축일 가능성부터 의심합니다.
에이전트가 읽는 입구와 역할 정의
Leysys Docs는 AI가 사이트를 탐색할 때 먼저 읽는 llms.txt와, 문서 소유권과 실행 경계를 요약한 llms-full.txt를 둡니다. 제품 저장소가 AGENTS.md에 연결할 공통 블록은 AI 에이전트 지침에 있습니다. 디자인 시스템 문서 사이트의 llms.txt도 한 페이지 한 DS 규칙, registry 주소, 작업 순서, 결함 판단 전에 읽을 문서를 맨 앞에 둡니다.
leysys-design에는 역할별 에이전트 정의 일곱 개가 있습니다. 디자인 시스템 아키텍트, 컴포넌트 아키텍트, UI 비평, 접근성 전문가, UI 카피라이터, 브라우저 자동 검증, EDS/MDS 분리 감시입니다. 각 정의는 맨 위에 맡는 범위를 적고, 브라우저 자동 검증을 뺀 여섯 정의는 다른 역할로 넘길 일도 적습니다. UI 비평은 디자인 시스템 규칙 준수를 판단하고 접근성 세부 점검은 접근성 전문가에게 넘깁니다. 판단 기준도 한 문장으로 둡니다. 카피라이터의 기준은 「30대 경리가 바쁜 업무 중에 읽고 바로 행동할 수 있는가?」입니다.
실제 예 — 독립 설계안 둘과 반론 검토
2026-10-03 KST 전 제품 공통 접근 역할 체계는 다음 순서로 정했습니다.
- 조사 — 조사 에이전트 여섯 개가 대상을 나눠 같은 질문으로 조사했습니다. 다섯 개는 제품 저장소 17곳을 읽기 전용으로 파일과 행 번호 근거와 함께, 한 개는 외부 공식 문서를 조사했습니다.
- 독립 설계안 — 설계 에이전트 두 개가 같은 과제와 조사 결과를 받아 서로 모른 채 설계했습니다. 백지 정답을 먼저 쓰고 이행 비용을 따로 쓰게 했습니다.
- 조정 — 두 안이 같은 결론을 낸 곳은 그대로 쓰고, 갈린 곳은 근거를 다시 확인해 골랐습니다.
- 반론 검토 — 반론 검토 에이전트가 결정 초안의 사실 오류, 모순, 권한 상승 경로, 빠진 규칙, 문구를 찾았습니다. 지적 24건 중 22건을 받아들이고 1건은 일부만, 1건은 유지했습니다. 조직 관리자가 자기에게 없는 소유자 전용 권한을 담은 추가 역할을 부여할 수 있는 경로도 여기서 막았습니다.
- 직접 확인 — 결론을 좌우하는 사실은 원본에서 다시 확인했습니다.
결정은 오너가 했고, 결정마다 검토한 다른 선택지를 함께 기록했습니다. 과제·조사·두 설계안·반론 검토의 원문은 고치지 않고 근거 폴더에 보존했습니다. 두 안의 일치가 정답을 보장하지는 않았습니다. 뒤에 오너의 질문으로 원본을 다시 보다가 두 안이 함께 낸 주장 하나가 틀렸음을 발견해 정정을 기록했습니다(3장).
경계와 예외
- 결정과 범위는 사람이 정합니다. 에이전트는 명시된 범위만 구현하고 선택지를 임의로 늘리지 않습니다. 허가 없이 파일을 고치지 않고 변경 계획을 먼저 공유하며, 대량 치환·파일 삭제·디렉터리 이동·git commit·push는 미리 허가를 받습니다.
- 배포 권한은 그 작업의 요청과 맥락에서 판단합니다. 배포까지 승인된 작업은 로컬 수정으로 끝내지 않고 검증·PR·병합· 배포·운영 확인까지 마칩니다.
- 제품 안에서 AI 에이전트는 명시적인 역할 부여나 확인된 위임으로만 접근을 얻고, 행위 주체로 기록된다는 사실만으로는 접근을 얻지 않습니다. AI가 제안하고 사람이 저장하면 사람이 편집 주체입니다(접근 역할 체계).
정리
- 디자인 시스템은 AI가 예측할 수 있도록 예외를 줄이고 이름·구조·토큰을 일관되게 둡니다.
- 저장소마다
AGENTS.md(같은 내용의CLAUDE.md)를 두고, 제품 저장소는 공통 기본 블록을 맨 위에 복사합니다. - 헷갈리는 축은 주의사항 문서에 모으고, 결함 판단 전에 결정 기록을 확인합니다.
- 큰 결정은 독립 설계안 둘과 반론 검토와 원본 확인을 거치고, 마지막 결정은 사람이 합니다.
정본
leysys-designAGENTS.md「프로젝트 핵심 목표」, 「행동 규칙」 — AI 최적화 목표와 작업 절차leysys-designdocs/process/PRODUCT-REPO-CLAUDE-BASELINE.md— 제품 저장소 기본 블록leysys-designdocs/process/AGENT-WORK-EFFICIENCY-STANDARD.md— 작업 효율 표준leysys-designdocs/specs/DS-GOTCHAS.md— 헷갈리기 쉬운 축·어휘leysys-designdocs/decisions/EDS-SELECT-NATIVE-2026-07-11.md— 없는 조합을 계기로 컴포넌트를 만든 결정leysys-designdocs/reviews/ACCESS-ROLE-SYSTEM-DESIGN-REVIEW-2026-10-03.md— 조사·독립 설계안·반론 검토 기록- AI 에이전트 지침 — 제품 저장소에 연결할 공통 지침
- 접근 역할 체계 — 인증 주체와 행위 주체 규칙