a11y-audit-until-clean

접근성 감사 클린까지 (A11y Audit Until Clean)

변경된 라우트에 접근성 자동 검사를 돌리고, 위반을 고치고, 감사가 깨끗해질 때까지 반복합니다.

이 루프는 언제 쓰나

UI를 손본 뒤 "이 화면 접근성 다 챙겼나?"를 일일이 손으로 확인하기 번거로울 때 씁니다. 한 번 시작하면 에이전트가 감사 실행 → 위반 분석 → 수정 → 재실행을 스스로 반복하며 위반 0으로 수렴시킵니다. 검사 대상은 바뀐 페이지/라우트로 좁혀, 멀쩡한 화면까지 들쑤시지 않고 새로 들어온 위반만 빠르게 잡습니다. 핵심은 aria 속성으로 덮어쓰는 꼼수 대신 시맨틱 HTML로 근본을 고치는 것입니다.

루프 흐름

수동 시작 → a11y 감사 실행 → 위반 수정 → 재실행 →〔피드백 게이트〕위반 0?
                ↑                                         │ 아니오
                └─────────────────────────────────────────┘
                                                          │ 예
                                                        종료

매 반복(pass)마다 하는 일

1. a11y 감사 실행 — 변경된 페이지에 axe, pa11y, 또는 eslint-plugin-jsx-a11y를 돌립니다. 위반을 셀렉터와 함께 나열합니다.

   npm run test:a11y
   

2. 위반 수정 — 라벨, 색 대비, 포커스 순서, ARIA 역할을 고칩니다. aria 꼼수보다 시맨틱 HTML을 우선하세요.

가드레일 (점수 조작 방지 규칙)

종료 조건을 "가짜로" 통과시키지 못하게 막는 규칙입니다. 반드시 지키세요.

• 체크 명령이나 종료 기준을 고쳐서 억지로 성공시키지 않는다.
• 체크를 건너뛰거나 비활성화·우회해서 종료 조건을 통과시키지 않는다.
• 여러 번 반복해도 막히면, 지표를 조작하지 말고 멈추고 블로커를 보고한다.

Claude Code에서 실행하기

가장 간단합니다. 아래 kickoff 프롬프트를 그대로 붙여넣으면 에이전트가 스스로 반복합니다.

"접근성 감사 클린까지(A11y Audit Until Clean)" 루프를 시작합니다.

목표: 변경된 UI에 심각한 접근성 위반 0건
최대 반복: 8
매 반복 사이 실행: npm run test:a11y
종료 조건: 접근성 감사가 종료 코드 0으로 끝날 때

1단계: 변경된 라우트에 접근성 감사를 실행한다. 각 위반을 고치되, 키보드·스크린리더 관련 문제를 우선한다.

이 루프를 스스로 페이싱(self-pace)하라. 매 반복 후 체크 명령을 실행하고 출력을 읽어, 종료
조건이 충족되지 않았을 때만 계속한다. 종료 조건이 통과하거나 최대 반복에 도달하면 멈춘다.
매 회차마다 한 줄 상태 업데이트를 남긴다.

팁: npm run test:a11y는 예시입니다. 프로젝트에 맞게 axe-core CLI(axe <url>), pa11y <url>, npx eslint --plugin jsx-a11y . 등으로 바꾸세요.

팁 / 변형

• 체크 명령 교체: 런타임 검사는 Playwright + @axe-core/playwright, 정적 검사는 eslint-plugin-jsx-a11y, CLI 단발 검사는 pa11y <url>이 편합니다. 프로젝트 스택에 맞는 하나로 npm run test:a11y 스크립트를 정의해 두면 깔끔합니다.
• 막힐 때: 같은 위반이 2회 반복되면 가드레일대로 멈추고, aria로 덮어쓰는 대신 시맨틱 마크업으로 근본 수정하도록 보고하게 하세요.
• 범위 좁히기: 변경된 라우트/파일 목록만 검사 대상으로 넘기면 한 회차가 훨씬 빠릅니다.
• 연관 루프: 시각적 픽셀 회귀는 looping:visual-regression-until-match, lint·타입 정리는 looping:lint-typecheck-fix, E2E UI 통합은 looping:e2e-until-green.

Start the "A11y Audit Until Clean" loop.

Goal: zero serious accessibility violations on changed UI
Max iterations: 8
Between iterations run: npm run test:a11y
Exit when: a11y audit exits 0

Step 1: Run the a11y audit on changed routes. Fix each violation, prioritizing keyboard and screen reader issues.

Self-pace this loop. After each iteration, run the check command, read the output, and only continue if the exit condition is not met. Stop when the exit condition passes or max iterations is reached. Give a short status update each pass.