본문으로 건너뛰기
블로그로 돌아가기
AI 접근성 점검, 위반 0건이면 믿어도 될까요? agent-skills 스킬 2026 기준
[TUTORIAL]

AI 접근성 점검, 위반 0건이면 믿어도 될까요? agent-skills 스킬 2026 기준

퀀텀점프클럽 정상록퀀텀점프클럽 정상록12분 읽기12 views

무료 자료

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 흐름: 새 화면 넘기기, 자동 점검, 사람이 하는 수동 점검, 위반 수정accessibility-engineering 스킬의 점검 네 Phase 흐름: 새 화면 넘기기, 자동 점검, 사람이 하는 수동 점검, 위반 수정

자동 점검 결과는 1차 확인이고, 키보드·스크린리더·시각 점검은 사람이 따로 해요

자료: agent-skills SKILL.md·audit-a11y.sh(GitHub) · QJC 재구성

  1. Route New UI Work: 새 화면 제작은 frontend-ui-engineering으로 넘기고 화면이 생긴 뒤에 이 스킬로 돌아와요.
  2. Run Automated Audit: axe-core CLI 4.13.0과 pa11y 9.1.1을 고정 버전으로 돌려요. 위반마다 브라우저에서 요소를 직접 열어 오탐인지 확인하라고 적었습니다.
  3. Manual Testing: 키보드, 스크린리더, 시각 점검을 사람이 직접 해요.
  4. 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건이라는 뜻입니다. 이유는 다섯 가지예요.

  1. W3C는 도구가 틀리거나 오해를 부르는 결과를 낼 때도 있다고 적었어요.
  2. Deque가 axe-core README에 적은 수치에 따르면 WCAG 이슈 중 axe-core가 자동으로 찾는 평균 비율은 57%입니다. 원문 표현은 "on average 57% of WCAG issues automatically"예요. Deque 자체 수치이고 산출 방법은 확인하지 못했어요. 확신이 없는 요소는 incomplete(사람 확인 필요)로 따로 돌려줘요.
  3. 감사 스크립트는 axe 결과에서 violations만 세고 incomplete는 합계에 넣지 않아요(스크립트 코드 기준). 합계가 0건이어도 사람이 볼 항목이 남아 있을 수 있어요.
  4. 두 도구 중 하나라도 제대로 못 돌면 총계를 내지 않고 "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 하나가 본 범위예요.
  5. 페르소나 규칙 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 키로 화면을 한 바퀴 직접 돌아보세요.


참고 자료