
AI 접근성 점검, 위반 0건이면 믿어도 될까요? agent-skills 스킬 2026 기준
무료 자료
PDF · 무료
AI 접근성 점검, 위반 0건을 그대로 믿으면 안 되는 이유
긴 글을 다 읽기 전에, 실무 가이드부터 먼저 챙겨가세요.
AI 접근성 점검, 위반 0건이면 믿어도 될까요? agent-skills 스킬 2026 기준
AI 코딩 에이전트에게 웹 접근성 점검을 맡기는 스킬이 agent-skills 0.6.17에 추가됐어요. 자동 점검이 위반 0건을 내도 사람 몫 점검은 남습니다.
AI가 만든 화면의 접근성, 어디까지 맡겨도 될까요?
한 줄 답: 자동 점검은 1차 확인(smoke test)일 뿐이고, 스크린리더가 실제로 읽는 내용은 사람이 따로 확인해야 해요.
AI 접근성 점검은 도구 몇 개를 돌리는 것으로 끝나지 않아요. "AI가 만든 화면이니 접근성도 알아서 챙기겠지?" 이런 생각, 해 보신 적 있을 거예요. 자연스러운 마음입니다. 도구가 숫자를 내주면 일이 끝난 것처럼 보이니까요. 이 글은 0.6.17에 들어온 accessibility-engineering 스킬이 점검을 어떻게 나누는지, 위반 0건을 왜 그대로 믿으면 안 되는지, Claude Code에서 어떻게 써 보는지 차례로 짚어 봅니다.
웹 접근성은 눈이 안 보이거나 마우스를 못 쓰는 사람도 웹을 쓸 수 있게 만드는 일입니다. WCAG는 W3C가 만든 웹 콘텐츠 접근성 지침이고 A, AA, AAA 세 등급이 있어요. 스크린리더는 화면 글자를 소리로 읽어 주는 프로그램(macOS VoiceOver, Windows NVDA)입니다. 이 스킬은 WCAG 2.2 AA를 기준으로 삼아요.
0.6.17에는 무엇이 추가됐나요?
agent-skills 저장소는 2026-02-16 05:20 KST에 만들어진 기존 저장소입니다. 0.6.17에 추가된 것은 접근성 점검 스킬이에요. 저장소 전체 구성은 관련 글 Addy Osmani의 agent-skills: AI 코딩 에이전트 스킬 24개 완전 정리에서 다뤘으니 여기서는 접근성 스킬만 봅니다.
GitHub 릴리스 노트에 따르면 0.6.17은 2026-11-19 05:06 KST에 공개됐고 다섯 가지가 들어왔어요.
- accessibility-engineering 스킬
- accessibility-auditor 페르소나: 접근성 전담 감사 역할이고 점검 범위 6개 절, 심각도 5단계, 규칙 9개를 갖춰요
/a11y명령: Claude Code, Gemini CLI, Antigravity용audit-a11y.sh감사 스크립트: 고정 버전 axe-core CLI와 pa11y 결과를 JSON 하나로 묶어요- 공용 체크리스트(WCAG 2.2 AA 기준으로 고침): 목표 크기는 24×24 CSS px가 AA(SC 2.5.8), 44×44 CSS px는 AAA(SC 2.5.5)로 나눠 적었어요
스킬 설명문 첫 줄은 이미 만든 화면을 WCAG 2.2 AA 기준으로 점검하고 찾은 위반을 고친다는 뜻입니다. 새 화면을 처음 만드는 일은 맡지 않아요. 릴리스 노트도 "Building new UI stays with frontend-ui-engineering."이라고 적었습니다.
원 PR #261은 Chukwuebuka-2003가 2026-06-12 20:24 KST에 열었고 저장소 주인 addyosmani가 승인하고 2026-11-19 05:05 KST에 병합했어요. PR 본문에 따르면 이번 추가로 스킬은 26개, 명령은 10개가 됐어요. 병합까지 159일이 걸렸습니다.
점검은 어떤 순서로 나뉘나요?
SKILL.md에 따르면 일은 네 Phase로 나뉩니다.
accessibility-engineering 스킬의 점검 네 Phase 흐름: 새 화면 넘기기, 자동 점검, 사람이 하는 수동 점검, 위반 수정
자동 점검 결과는 1차 확인이고, 키보드·스크린리더·시각 점검은 사람이 따로 해요
자료: agent-skills SKILL.md·audit-a11y.sh(GitHub) · QJC 재구성
- Route New UI Work: 새 화면 제작은 frontend-ui-engineering으로 넘기고 화면이 생긴 뒤에 이 스킬로 돌아와요.
- Run Automated Audit: axe-core CLI 4.13.0과 pa11y 9.1.1을 고정 버전으로 돌려요. 위반마다 브라우저에서 요소를 직접 열어 오탐인지 확인하라고 적었습니다.
- Manual Testing: 키보드, 스크린리더, 시각 점검을 사람이 직접 해요.
- Fix Violations: 근본 원인을 고치고 네이티브 HTML로 안 될 때만 ARIA를 다리처럼 더한 뒤 자동·수동 점검을 다시 돌려요.
심각도 이름은 스킬이 Critical, Serious, Moderate, Minor의 4단계이고 페르소나는 Critical, High, Medium, Low, Info의 5단계예요. 같은 저장소 안인데 이름이 달라서 보고서를 읽을 때 헷갈릴 수 있습니다.
수정 순서에서 눈여겨볼 문장은 "ARIA is a bridge, not a foundation. Semantic HTML first."입니다. 기본 HTML 요소로 해결하고 ARIA는 그다음에 쓰라는 뜻이에요. <div>를 <button>으로 바꾸는 식이죠.
페르소나는 AI가 만든 화면에서 따로 볼 안티패턴 10개도 적었어요. div를 버튼처럼 쓰기, 이미지 alt 누락, 색으로만 상태 표시, outline: none으로 포커스 테두리 지우기 같은 것들입니다. 규칙 9의 "AI models consistently produce these issues."는 페르소나 문서의 주장일 뿐 연구 결과로 제시된 것은 아니에요.
왜 키보드와 스크린리더 점검을 따로 두나요?
스킬 Phase 3의 첫 문장은 "Automated checks are a smoke test, not proof of conformance."입니다. 자동 점검은 1차 확인이지 적합성의 증명이 아니라는 말이에요. 수동 점검 항목도 키보드 5개, 스크린리더 5개, 시각 5개로 따로 나뉘어 있습니다.
- 키보드 5개: Tab으로 돌며 현재 위치가 보이는지, Enter와 Space로 버튼과 링크가 작동하는지, Escape로 모달이 닫히는지, 화살표 키로 목록을 오갈 수 있는지, 키보드 함정이 없는지
- 스크린리더 5개(VoiceOver, NVDA): 제목 단위 이동, 랜드마크 이동, 링크 이동(링크 문구가 맥락 없이도 통하는지), 폼 레이블과 오류 메시지 읽힘, 동적 갱신 안내
- 시각 5개: 대비(본문 4.5:1, 큰 글자 3:1, UI 구성요소 3:1), 200% 확대, 강제 색상과 고대비 모드, 동작 줄이기(prefers-reduced-motion), 포커스 표시
W3C 평가 도구 선택 안내에 따르면 "Tools cannot check all accessibility aspects automatically. Human judgement is required."입니다. 도구는 접근성을 판정하는 게 아니라 사람의 판단을 돕는 쪽이라는 설명이에요.
스크린리더가 실제로 무엇을 읽는지는 코드를 읽는 것만으로 알 수 없어요. 페르소나 규칙 2는 해 보지 않은 점검을 확인된 것처럼 적지 말라고 못 박습니다. 원문은 "never report it as verified unless that test was actually performed"이고 직접 하지 않았다면 manual로 표시하라는 거예요. 이 스킬이 스크린리더 점검을 대신해 주는 것은 아닙니다.
위반 0건이면 접근성이 통과된 건가요?
아니요. 0건은 도구가 잡는 범위에서 0건이라는 뜻입니다. 이유는 다섯 가지예요.
- W3C는 도구가 틀리거나 오해를 부르는 결과를 낼 때도 있다고 적었어요.
- Deque가 axe-core README에 적은 수치에 따르면 WCAG 이슈 중 axe-core가 자동으로 찾는 평균 비율은 57%입니다. 원문 표현은 "on average 57% of WCAG issues automatically"예요. Deque 자체 수치이고 산출 방법은 확인하지 못했어요. 확신이 없는 요소는 incomplete(사람 확인 필요)로 따로 돌려줘요.
- 감사 스크립트는 axe 결과에서 violations만 세고 incomplete는 합계에 넣지 않아요(스크립트 코드 기준). 합계가 0건이어도 사람이 볼 항목이 남아 있을 수 있어요.
- 두 도구 중 하나라도 제대로 못 돌면 총계를 내지 않고 "incomplete audit; refusing to report a violation total"을 출력한 뒤 실패로 끝나요. 릴리스 노트가 적은 대로 "an audit script that fails a partial run instead of reporting zero violations"입니다. 도구가 안 돌았는데 0건처럼 보이는 일을 막는 장치예요. 두 도구가 정상으로 돌아 0건을 냈을 때도 그 범위는 도구 규칙이 잡는 데까지입니다. file 모드는 axe를 돌리지 않고 pa11y만 쓰니 그 0건은 pa11y 하나가 본 범위예요.
- 페르소나 규칙 8은 "a page can pass axe-core and still be unusable by screen readers"라고 적었어요. 점검을 통과한 화면도 스크린리더로는 쓰기 어려울 수 있다는 뜻입니다.
스킬 문서는 접근성이 여러 관할에서 법적 요구라고 적지만 도구 통과나 이 스킬 사용이 법적 준수나 인증을 뜻한다는 문장은 원문 어디에도 없어요.
Claude Code에서는 어떻게 써 보나요?
아래는 README와 명령 문서에 적힌 내용이고 직접 설치해 실행한 결과는 아니에요. 설치는 두 줄입니다.
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
다른 에이전트용은 npx skills add addyosmani/agent-skills로 26개 전체를 설치해요. 주의할 점도 있어요. README에 따르면 --skill <이름>으로 하나만 설치하면 저장소 공용 references 폴더가 복사되지 않습니다(이슈 #361). 접근성 체크리스트도 그 폴더에 있으니 전체 설치나 저장소 복제를 권해요.
설치 뒤 /a11y를 부르면 accessibility-auditor 서브에이전트가 떠서 성적표, 심각도 순 지적, 잘한 점, 수정 예시 코드를 돌려줘요. 모드는 둘입니다.
- Quick: 기본값이에요. 도구 출력이 없으면 소스 코드에서 레이블 누락, div 버튼, alt 없음, 제목 단계 건너뜀 같은 구조 문제만 훑어요.
- Deep: axe-core나 pa11y의 JSON 보고서, 실행 중인 URL, Chrome DevTools MCP 중 하나가 있을 때 켜져요. Chrome DevTools MCP는 Chrome DevTools MCP 소개에서 따로 설명했어요.
감사 스크립트는 이렇게 돌려요. 필요한 것은 npx와 node예요. 두 도구를 다 쓰려면 URL 모드여야 하고 로컬에서는 개발 서버가 떠 있어야 합니다. 두 도구는 실행 때 고정 버전으로 내려받아요.
bash skills/accessibility-engineering/scripts/audit-a11y.sh url http://localhost:3000 --json
/a11y는 WCAG를 통과시켜 주는 명령이 아니라 점검과 수정을 돕는 도구로 쓰세요.
한계는 무엇인가요?
- 고정 버전이 npm 최신판보다 낮아요(2026-11-19 조회). @axe-core/cli는 4.13.0 고정에 최신 4.14.0이고 pa11y는 9.1.1 고정에 최신 10.0.0입니다. 체크리스트 주석에 따르면 고정 이유는 브라우저 드라이버 동작을 반복 가능하게 하려는 것이에요.
- README의 화면 제작 스킬 frontend-ui-engineering 설명은 아직 WCAG 2.1 AA로 적혀 있어요. 점검 스킬과 체크리스트는 2.2 AA라서 문서끼리 기준이 어긋나요.
- pa11y에는 영향도 등급이 없어서 스크립트가 오류를 serious로 매겨요. 이 등급은 스크립트의 대응표예요.
- 2026-11-19 조회 기준으로 이 스킬을 다룬 커뮤니티 글은 확인되지 않았어요.
자주 묻는 질문
자동 점검에서 위반이 0건이면 배포해도 되나요?
그것만으로는 안 돼요. 0건은 도구가 잡는 범위의 결과입니다. 스킬의 Verification 목록 10항목에 따르면 스크린리더 항목은 브라우저와 보조기술 조합을 밝혀 확인하고 안 했다면 manual로 적어야 해요.
스크린리더 점검도 AI 에이전트가 해 주나요?
아니요. 스킬과 페르소나 모두 직접 해 보지 않은 결과는 manual로 표시하라고 적었어요. 스크린리더가 실제로 무엇을 읽는지는 사람이 브라우저에서 VoiceOver나 NVDA로 확인해야 합니다.
마무리
AI 접근성 점검은 1차 확인을 빠르게 해 주고, 판단은 여전히 사람 몫이에요. 우리 화면에 맞는지부터 따져보셔도 충분해요. 먼저 내 개발 서버 주소 하나로 점검을 돌려 보고 위반 0건이 나와도 Tab 키로 화면을 한 바퀴 직접 돌아보세요.


