Community-Access/accessibility-agents

AI와 자동화 도구는 완벽하지 않습니다. 이들은 무언가를 놓치거나 실수를 저지르며, 실제 스크린 리더 (Screen Reader) 및 보조 기술 (Assistive Technology)을 통한 테스트를 대체할 수 없습니다. 항상 VoiceOver, NVDA, JAWS 및 키보드 전용 탐색 (Keyboard-only navigation)을 통해 검증하십시오. 이 도구는 유용한 시작점일 뿐, 실제 접근성 테스트의 대체재가 아닙니다.

AI 기반 에이전트 (Agents), 기술 (Skills), 사용자 정의 지침 (Custom instructions) 및 프롬프트 (Prompts)를 통해 접근성, 효율성 및 생산성을 자동화하는 커뮤니티 주도 오픈 소스 프로젝트입니다.

이 커뮤니티 프로젝트를 구축하는 데 앞장서 준 Taylor Arndt와 Jeff Bishop에게 진심으로 감사를 표합니다. 이 프로젝트는 LLM (Large Language Models)이 접근성을 지속적으로 망각하기 때문에 시작되었습니다. 기술이 무시되고, 지침이 문맥에서 벗어나며, ARIA가 오용되고, 초점 관리 (Focus management)가 누락되며, 색상 대비 (Color contrast)가 조용히 실패하곤 합니다. 그들은 이러한 문제와 싸우는 것에 지쳐, 이를 그냥 넘기지 않을 에이전트 팀을 구축했습니다. 이제 우리는 함께 더 많은 마법을 만들어 나가고자 합니다.

우리는 더 많은 기여자 (Contributors)를 원합니다! 시각 장애 및 저시력 사용자를 위한 소프트웨어를 접근 가능하게 만드는 데 관심이 있다면 PR (Pull Request) 제출을 고려해 주세요. 이 에이전트들에 대한 모든 개선은 개발자들이 가장 필요한 사람들을 위해 더 포용적인 소프트웨어를 출시하는 데 도움이 됩니다.

워크숍 및 에이전트 생태계 전반에 걸친 문제 해결, 질의응답(Q&A) 및 커뮤니티 지원을 위해서는 Community Access 지원 저장소 (Support repository)를 사용하십시오:

• 홈: https://github.com/Community-Access/support
• 토론 (Discussions): https://github.com/Community-Access/support/discussions
• 이슈 (Issues): https://github.com/Community-Access/support/issues

관련 저장소:

• 워크숍 커리큘럼: https://github.com/Community-Access/git-going-with-github
• Accessibility Agents 소스: https://github.com/Community-Access/accessibility-agents

AI 코딩 도구는 기본적으로 접근 불가능한 코드를 생성합니다. 이들은 ARIA 규칙을 잊고, 키보드 탐색을 건너뛰며, 대비 비율을 무시하고, 스크린 리더 사용자를 가두는 모달 (Modals)을 생성합니다. 기술 (Skills)과 CLAUDE.md 지침이 있더라도, 접근성 문맥 (Accessibility context)은 우선순위가 밀리거나 완전히 누락됩니다.

Accessibility Agents는 8개의 팀과 5개의 플랫폼에 걸쳐 79개의 특화된 에이전트(agents)를 제공합니다:

Web Accessibility team (웹 접근성 팀) - i18n/RTL, WCAG AAA 커버리지, 데이터 시각화, 이메일, 미디어, 웹 컴포넌트 및 성능 접근성을 포함하여 웹 코드에 대한 WCAG AA 표준을 강제하는 에이전트들
Document Accessibility team (문서 접근성 팀) - Office (DOCX, XLSX, PPTX), PDF, EPUB 및 Markdown 접근성 스캐닝(scanning)과 교정(remediation)을 위한 에이전트들
GitHub Workflow team (GitHub 워크플로 팀) - 리포지토리(repositories) 관리, 이슈(issues) 분류, PR(Pull Requests) 리뷰, 프로젝트 보드 관리, CI/CD 워크플로, 보안 경고, 릴리스, 알림 및 위키(wiki) 페이지를 관리하는 20개의 에이전트들
Developer Tools team (개발자 도구 팀) - Python, wxPython, 데스크톱 접근성, NVDA 애드온 개발 및 접근성 도구 구축을 위한 에이전트들
Education & Standards (교육 및 표준) - 스크린 리더 시뮬레이션, WCAG 3.0 프리뷰, WCAG AAA 감사(auditing)
Cross-cutting (교차 기능) - CI/CD 접근성 파이프라인, 컴플라이언스 매핑(compliance mapping), 접근성 성명서(accessibility statements), 회귀 탐지(regression detection) 및 팀 간 작업을 라우팅하는 오케스트레이터(orchestrators)

모든 에이전트는 다음 환경에서 실행됩니다:

Claude Code - 접근성 평가를 위해 사용자가 직접 호출하는 에이전트
GitHub Copilot (VS Code 및 CLI) - 모든 대화에서 접근성 가이드를 보장하는 에이전트 및 워크스페이스 지침(workspace instructions)
Gemini CLI - GEMINI.md를 통해 항상 켜져 있는 WCAG AA 문맥(context)을 제공하는 스킬 기반 확장 기능
Codex CLI - 직접적인 Accessibility Agents 스킬 팩과 집중적인 접근성 검사를 위한 선택적 실험적 TOML 기반 역할(roles)
MCP Server - 모든 MCP 호환 클라이언트(Claude Desktop, VS Code, CI/CD 파이프라인)에 24개의 접근성 스캐닝 도구를 제공하는 HTTP 기반 서버

⚠️ 중요: Accessibility Agents의 최신 상태를 유지하고 적절한 기능을 보장하려면, 반드시 모든 도구를 최신 버전으로 업데이트해야 합니다. 새로운 플랫폼 기능, API 변경, 접근성 기능 및 버그 수정은 에이전트의 동작에 직접적인 영향을 미칩니다.

GitHub Copilot (VS Code)의 경우:

VS Code: 최신 안정 버전 및/또는 VS Code Insiders (다운로드)
GitHub Copilot Extension: VS Code Marketplace의 최신 버전
GitHub Copilot Chat Extension: VS Code Marketplace의 최신 버전
Node.js: v18.0.0 이상 (axe-core와 같은 CLI 도구용)

Claude Code의 경우:

Claude Code CLI: 최신 버전 (설치)
Claude Subscription: Pro, Max 또는 Team 플랜

Gemini CLI의 경우:

Gemini CLI: 최신 버전 (설치)
Google AI Studio API Key: 활성 키 (시작하기)

운영 체제 (Operating Systems):

macOS: 10.15 (Catalina) 이상
Windows: PowerShell 5.1 이상이 설치된 Windows 10/11

플랫폼 API 변경 사항 (Platform API Changes)

• VS Code Copilot, Claude Code 및 기타 플랫폼은 에이전트가 의존하는 새로운 기능(도구 사용 (tool use), 컨텍스트 창 (context windows), 모델 선택 (model selection))을 추가합니다.
  접근성 기능 (Accessibility Features)
• 새로운 플랫폼 기능은 에이전트의 효과를 직접적으로 향상시킵니다 (브라우저 도구 (browser tools), 스크린샷 분석 (screenshot analysis), DOM 검사 (DOM inspection)).
  버그 수정 (Bug Fixes)
• 도구 호출 (tool invocation), 컨텍스트 처리 (context handling), 에이전트 오케스트레이션 (agent orchestration)에 대한 중요한 수정 사항.
  보안 업데이트 (Security Updates)
• API 액세스, 인증 (authentication) 및 데이터 처리에 대한 중요한 보안 패치.
  WCAG 진화 (WCAG Evolution)
• 표준이 진화함에 따라 (WCAG 2.2, 3.0), 에이전트는 현재의 모범 사례를 반영하도록 업데이트됩니다.

자동 업데이트 (권장):

# 스킬 자체를 업데이트
gh extension upgrade gh-skill
# 소스에서 작업할 때 최신 리포지토리 변경 사항을 가져옴
...

수동 업데이트:

# Accessibility Agents 업데이트
cd accessibility-agents
git pull origin main
...

버전 확인:

# 현재 버전 확인
code --version # VS Code
claude code --version # Claude Code CLI
...

Accessibility Agents는 지원되는 모든 플랫폼의 **최신 안정 버전 (latest stable releases)**을 기준으로 테스트됩니다. 이전 버전에서도 작동할 수 있지만, 오래된 도구로 인해 발생하는 호환성이나 지원 문제를 보장할 수 없습니다. 예상치 못한 동작이 발생할 경우, 문제를 보고하기 전에 모든 도구를 업데이트하십시오.

VS Code 1.113은 현재 이 저장소(repo)의 GitHub Copilot 사용자들에게 가장 관련성이 높은 베이스라인(baseline)입니다. 이번 릴리스에서는 Accessibility Agents 워크플로우를 직접적으로 개선하는 몇 가지 변경 사항이 추가되었습니다:

에이전트 유형 전반에 걸친 MCP (MCP across agent types)- VS Code에서 구성된 MCP 서버가 이제 Copilot CLI 및 Claude 에이전트로 연결되어, 로컬, CLI, Claude 워크플로우 전반에서 이 저장소의 MCP 가이드가 더욱 일관성을 갖게 됩니다.

채팅 커스터마이징 에디터 (Chat Customizations editor)- Chat: Open Chat Customizations 명령을 통해 지침(instructions), 프롬프트 파일(prompt files), 에이전트(agents), 기술(skills), MCP 서버 및 플러그인을 한곳에서 검사하고 관리할 수 있습니다.

더 넓은 에이전트 디버그 범위 (Broader Agent Debug coverage)- 에이전트 디버그 로그(Agent Debug Logs)가 이제 로컬 세션뿐만 아니라 Copilot CLI 및 Claude 에이전트 세션까지 포함합니다.

통합 브라우저 개선 사항 (Integrated browser improvements)- 자체 서명된 인증서를 사용한 로컬 HTTPS 테스트가 더 쉬워졌으며, 접근성 테스트 워크플로우를 위한 브라우저 탭 관리가 개선되었습니다.

중첩된 서브에이전트 (Nested subagents)- VS Code는 이제 중첩된 서브에이전트 위임(nested subagent delegation)을 지원합니다. 이 저장소의 경우, 이는 기본 아키텍처 선택이 아닌 선택적인 플랫폼 기능으로 취급됩니다. 우리는 명시적인 코디네이터-워커(coordinator-worker) 흐름을 선호하며, 중첩된 서브에이전트는 기본적으로 비활성화 상태로 유지합니다.

이 저장소에 대한 서브에이전트 입장(Subagent stance):

보상 (Reward): 제한된 서브에이전트는 전문화, 병렬 분석 및 감사 구조(audit structure)를 향상시킵니다.
리스크 (Risk): 제한이 없거나 중첩된 서브에이전트는 중복된 결과 발견, 잘못된 에이전트 선택, 토큰 비용 및 디버깅 복잡성을 증가시킬 수 있습니다.
권장 사항 (Recommendation): 명시적이고 허용 목록(allowlisted)에 등록된 전문가 위임을 사용하십시오. 워크플로우가 의도적으로 설계되지 않은 한 재귀적인 서브에이전트 체인(recursive subagent chains)은 피하십시오.

공식적인 세부 사항은 VS Code 1.113 릴리스 노트를 참조하십시오: https://code.visualstudio.com/updates/v1_113

이 프로젝트는 플랫폼별 가이드를 2차 요약본이 아닌 공식 벤더 문서 및 릴리스 노트를 기반으로 작성합니다.

주요 참조 문헌:

• VS Code 릴리스 노트:
  https://code.visualstudio.com/updates

• VS Code Copilot 커스터마이징 문서:
  https://code.visualstudio.com/docs/copilot/customization/custom-instructions

• VS Code 커스텀 에이전트 (custom agents) 문서:
  https://code.visualstudio.com/docs/copilot/customization/custom-agents

• VS Code 프롬프트 파일 (prompt files) 문서:
  https://code.visualstudio.com/docs/copilot/customization/prompt-files

• GitHub Copilot 제품 문서:
  https://docs.github.com/copilot

출처 표기 정책 (Attribution policy):

• 이 저장소(repo)의 플랫폼 관련 주장에는 최소 하나 이상의 공식 소스 링크를 인용해야 합니다.
• 특정 릴리스 (release)와 관련된 새로운 동작은 해당 릴리스 노트 (release note) URL을 포함해야 합니다.
• 설정 키 (settings keys)가 문서화될 때는 가능한 경우 공식 설정/문서 페이지로 링크를 연결해야 합니다.

GitHub Skills 사양 배포 및 릴리스 준비 워크플로우 (release-readiness workflows)에 대해서는 다음을 참조하세요:

• docs/guides/GITHUB-SKILLS-CLI-READINESS.md
• docs/guides/SKILLS-RELEASE-READINESS-TEST-PLAN.md
• .github/workflows/skills-cli-readiness.yml
• .github/workflows/skills-release-readiness.yml

VS Code 1.113에서 Accessibility Agents를 사용 중이라면, 다음 설정과 명령어가 가장 유용한 시작점입니다:

{
"chat.useCustomizationsInParentRepositories": true,
"github.copilot.chat.agentDebugLog.enabled": true,
...
}

• 로드된 지침 (instructions), 에이전트 (agents), 스킬 (skills), MCP 서버, 그리고 플러그인 (plugins)을 검사하려면
  Chat: Open Chat Customizations를 실행하세요.
• 커스텀 설정이 로드되지 않거나 예상되는 도구 (tool)가 누락된 경우
  /troubleshoot을 사용하세요.
• 재귀적 오케스트레이션 (recursive orchestration) 패턴을 의도적으로 실험하는 것이 아니라면
  chat.subagents.allowInvocationsFromSubagents를 비활성화 상태로 유지하세요.

마지막 사항은 저장소 (repo) 권장 사항이며, VS Code의 제한 사항이 아닙니다.

VS Code 사용자: 에이전트가 생각하는 동안 나타나는 로딩 텍스트를 접근성 테마 문구로 개인화할 수 있습니다.

VS Code 설정 (settings.json)에 추가:

{
"chat.agent.thinking.phrases": {
"mode": "append", // 기본 문구에 추가
...
}
}

옵션:

"mode": "append"

• 사용자의 문구를 VS Code의 기본 목록에 추가합니다 (권장)

"mode": "replace"

• 사용자의 커스텀 문구만 표시합니다

이것이 중요한 이유:

• 에이전트 작업 중 접근성 (accessibility) 중심 사고를 강화합니다
• 팀원들에게 접근성이 적극적으로 고려되고 있음을 상기시킵니다
• 대기 시간을 더 흥미롭게 만들기 위한 선택적인 재미 요소입니다

추가 방법:

• VS Code 설정 열기 (Ctrl/Cmd + ,)
• 우측 상단의 "설정 열기 (JSON) (Open Settings (JSON))" 아이콘 클릭
• chat.agent.thinking.phrases 설정을 추가합니다
• 창 다시 로드 (명령 팔레트(Command Palette) → "Developer: Reload Window")

커뮤니티 기여 (Community Contributions):
멋진 접근성 테마의 사고 문구(thinking phrase)가 있나요? CONTRIBUTING.md의 권장 목록에 추가할 수 있도록 PR (Pull Request)을 제출해 주세요!

버전 5.0.0은 Accessibility Agents를 설정, 상태 확인 (health checks), 복구 (repair) 및 훅 (hook) 관리를 위해 네이티브 Go 바이너리 (native Go binaries)로 지원되는 GitHub Skills 설치 흐름으로 이동합니다.

계획된 5.0 흐름:

gh skill install Community-Access/accessibility-agents
gh skill setup Community-Access/accessibility-agents
gh skill health Community-Access/accessibility-agents

중요 사항:

gh skill install은 향후 주요 설치 경로가 될 것입니다.

• 설정 도구는 Node.js 스크립트가 아닌 네이티브 Go 바이너리로 구현되고 있습니다.
• MCP 서버 자체에는 여전히 Node.js가 필요하지만, 설치 프로그램 경험에는 필요하지 않습니다.

5.0 설치 프로그램 전환에 기여하거나 릴리스 아티팩트 (release artifacts)를 준비하는 경우, Go를 설치하고 로컬에서 네이티브 CLI를 빌드하세요.

Windows:

winget install --id GoLang.Go --exact --accept-package-agreements --accept-source-agreements
go version
pwsh -NoProfile -File scripts/build-go-cli.ps1

macOS:

brew install go
go version
bash scripts/build-go-cli.sh

컴파일된 바이너리는 go-cli/bin/에 저장됩니다. Windows 출력물은 .exe 파일이며, macOS 출력물은 네이티브 CLI 실행 파일입니다.

GitHub Actions 또한 .github/workflows/build-go-cli.yml을 통해 Windows, macOS 및 Linux에서 Go CLI를 자동으로 빌드합니다.

5.0 이상 버전은 GitHub Skills / Go CLI 경로를 지원되는 설치 경로로 사용합니다.

GitHub Skills 설치 프로그램을 사용하세요:

gh skill install Community-Access/accessibility-agents

그 다음 필요에 따라 setup/health/repair 유틸리티를 실행하세요:

gh skill setup Community-Access/accessibility-agents
gh skill health Community-Access/accessibility-agents
gh skill repair Community-Access/accessibility-agents

gh skill uninstall Community-Access/accessibility-agents

수동 정리(manual cleanup)에 대한 세부 정보가 필요하면 UNINSTALL.md를 참조하세요.

기존의 레거시 스크립트 설치 프로그램(legacy script installers)은 이번 브랜치에서 제거되었습니다:

install.ps1

, install.sh

, update.ps1

, update.sh

, uninstall.ps1

, uninstall.sh

.

앞으로는 gh skill 명령어를 사용하세요.

설정 흐름(setup flow)은 추가적(additive)이고 비파괴적(non-destructive)으로 설계되었습니다:

에이전트 파일 (Agent files) (~/.claude/agents/, .github/agents/) - 기존 파일은 교체되지 않고 건너뜁니다. 어떤 에이전트가 건너뛰어졌는지 메시지로 알려주므로 이미 보유하고 있는 항목을 확인할 수 있습니다. 설정 파일 (Config files) (copilot-instructions.md, copilot-review-instructions.md