5월 초, 인스타그램 릴스를 보며 스크롤하다가 아티클 하나가 눈에 확 들어왔다.
GitHub 스타 15만개를 막 넘은 오픈소스, Everything Claude Code(ECC)였다.
관련해서 포스트를 둘러보니 Claude Code를 포함한 여러 AI 하네스를 위한 프로덕션 레디 플러그인 시스템이라고 했다.
GitHub - affaan-m/ECC: The agent harness performance optimization system. Skills, instincts, memory, security, and research-firs
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond. - affaan-m/ECC
github.com
마친 그 시기에 필자는 Claude Code에서 필자만의 스킬을 직접 만들어가며 AI 하네싱을 실험하고 있었다.
내가 정한 테두리 안에서 AI가 특정 역할에만 집중하도록 만드는 방식이 너무 매력적이었다...
뿐만 아니라 필자는 바로 필자의 애정담긴 프로젝트에 ECC의 `/code-review 커맨드`를 도입해서 사용하기 시작했다.
그때 이런 생각이 들었다.
"내가 만든 스킬이 이 레포에 있다면, 얼마나 많은 사람들에게 닿을 수 있을까?"
단순한 오픈소스 경험을 넘어서 선한 영향력을 끼치는 개발자의 첫 발걸음을 내딛고 싶었다..
그게 이 기여의 시작이 되었다.
Agent, Skill, Command 이 세 가지가 뭘까?
ECC에 기여하기 전에 필자는 이 세가지 개념을 먼저 이해해봤다.
쉽게 설명해보겠다.
- Agent는 전문 직원이라고 보면된다.
Claude가 "너는 이 일만 전담해"라고 별도로 고용하는 서브 AI라고 이해하면 된다. - Skill은 참고서이다.
Claude가 코드를 짤 때 옆에 두고 참고하는 지식 레퍼런스이다. 따라서 별도 실행없이 항상 배경 지식으로 작동한다! - Command는 단축키다.
필자가 직접 쓰는 `/code-review`가 바로 커맨드다. 슬래시를 치면 정해진 워크플로우가 실행되는 방식이다.
💫 왜 하필 접근성인가?!! 중요!!! 💫
이 질문이 사실 이 글에서 제일 중요하다고 생각한다.
항상 프로젝트 중에 PR을 날릴 때마다, 그리고 개인 프로젝트에서 `/code-review`로 피드백을 받을 때마다 같은 피드백 반복되었다.
`<label>`과 `<input>`이 연결되지 않았다, `aria-*` 속성이 없다, `<div>`에 클릭 이벤트를 달았다, 에러 메시지가 스크린리더와 연결되어 있지 안다 등,,,
매번 짠 다음에 고치는 패턴이 반복되었다...
AI 시대에서 처음부터 올바르게 짜도록 도와주는 레퍼런스가 있으면 어땠을까??
필자는 이 문제를 단순한 코드 스타일의 문제가 아니라고 본다.
전 세계의 장애인 사용자의 실제 사용 경험에 직결된 문제라고 본다.
스크린리더를 사용하는 시각장애인이 내가 만든 로그인 폼에서 어떤 필드인지 알 수 없다면,
그건 내 코드가 그 사람을 배제하고 있는 것이다.
그 생각이 들고 나서는 필자에게 선택지란 존재하지 않았던 것 같다.
이 스킬을 만들어 전 세계 개발자에게 사랑 받는 ECC에 기여하여 최대한 많은 개발자에게 쓰임 받는 스킬이 되었으면 좋겠다는 소망이 생겼다.
그렇다면 접근성이란 무엇일까?
웹 접근성은 장애가 있는 사용자도 웹 콘텐츠를 동등하게 사용할 수 있도록 설계하는 것이다.
줄요서 `a11y`라고 쓰는데, `accessibility`의 첫 글자 `a`와 마지막 글자 `y`사이에 11글자가 있다는 뜻이다.
접근성이 필요한 사람은 시각장애인만이 아니다.
손 떨림이 있어 마우스를 쓰기 어려운 사람, 색맹인 사람, 청각장애인, 운동 능력에 제한이 있는 사람 등 다양하다.
그래서 웹 접근성은 키보드만으로도 완전히 사용 가능한 인터페이스, 스크린리더가 올바르게 읽을 수 있는 마크업, 충분한 색상 대비 등을 모두 포함한다고 볼 수 있다!
국제 표준은 WCAG(Web Content Accessibility Guidelines)다.
W3C에서 제정하는데 레벨 A에서 AAA로 갈수록 기준이 높아지는데 대부분의 서비스는 AA 준수를 목표로 삼는다고 한다.
하나만 설명해보자면, 스크린리더가 폼을 읽는 방식을 한 번이라도 직접 들어본 사람이라면, 왜 접근성이 중요한지 바로 납득이 갈 ㄱ섯이라고 생각한다.
위에서 말한 부분과 같이 `<label>`과 `<input>`이 연결되지 않으면 스크린리더는 그냥 "편집 텍스트"라고만 읽는다.
그렇다면 이 필드가 이름인지, 이메일인지, 비밀번호인지 어떻게 알 수 있을까?
기존 ECC 스킬들 조사해보기!
기여하기 전에 ECC의 프론트엔드 스킬 현황을 먼저 파악했다.
frontend-patterns, frontend-design-direction, design-system, motion-ui, nextjs-turbopack이 있었고,
에이전트에는 a11y-architect가 있었다.
`a11y-architect`가 있긴 하지만 이건 에이전트, 즉 감사 작업을 위임하는 용도이다.
그러니까 "이 코드에서 접근성 문제를 찾아줘"라고 시키는 방식이라고 보면된다.
반면 스킬은 처음부터 올바르게 짜도록 가이드하는 지식 베이스이며 두 가지의 역할은 완전히 다르다.
`frontend-patterns`안에도 키보드 내비게이션 예시 하나, 모달 포커스 예시 하나, 즉 두 개의 접근성 관련 예시 밖에는 존재하지 않았다.
뿐만 아니라 이 스킬은 React 컴포넌트 패턴, 커스텀 훅, 상태관리 전반을 다루는 스킬이었고, 접근성에 대한 깊이가 충분하지 않았다.
필자는 접근성만 전문적으로 파고드는 스킬이 없다는 것을 확인했고, 그 틈새가 필자의 `frontend-a11y`스킬의 출발점이 됐다.
스킬 설계
이 글은 필자의 ECC 기여에 관한 글이기 때문에 만든 SKILL.md 속의 접근성들에 대해 깊이 있게 설명은 따로 하지 않겠다.
세부 예시와 내용은 아래의 SKILL.md를 참고하면 좋을 것 같다!
ECC/skills/frontend-a11y/SKILL.md at main · affaan-m/ECC
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond. - affaan-m/ECC
github.com
필자는 먼저 `CONTRIBUTING.md`의 체크리스트를 기준으로 설계했다.
ECC는 스킬을 만들 때 지켜야하는 형식이 있었다. 정리해보자면 아래와 같다.
- When to Activate, 즉 언제 활성화 되어야 하는지에 대한 섹션이 반드시 있어야 된다.
- BAD/GOOD 패턴의 코드 예시가 있어야 한다.
- 외부 패키지 설치 유도를 하게 되면 바로 PR이 close 된다.
- 500줄을 넘으면 안된다.
섹션 구성은 항상 반복적으로 피드백 받았던 순서대로 정리하여 잡아보았다.
가장 많이 피드백 받은 폼 접근성을 앞에 두었다. 정리하면 아래와 같다.
- 폼 접근성
- 시맨틱 HTML
- ARIA 속성
- 키보드 내비게이션
- 포커스 관리
- Anti-Patterns
필자는 예시 코드를 TypeScript와 React/Next.js 기준으로 만들었다.
필자의 메인 스택이기도 하고, ECC의 프론트엔드 스킬들이 모두 TS기준이라 일관성을 맞추기 위해서였다.
스킬 이름은 `frontend-a11y`로 정해 React에 국한하지 않으면서도, 예시 코드는 실제 사용하는 스택 기준으로 작성해서 실용성을 높여보았다.
솔직히 위 섹션들 중 포커스 관리 섹션이 제일 오래 걸렸던 것 같다.
처음에는 섹션 제목을 "Modal Focus Trap"이라고 달았는데,
필자가 작성한 코드는 모달이 열릴 때 포커스를 이동하고, 닫힐 떄 원래 위치로 돌려주는 복원만 구현하였다.
제목이 구현보다 과장되어 있었기 때문에 PR을 날린 후 AI 리뷰 봇인 cubic이 이 부분을 잡아냈다.
그럼 진짜 Focus Trap이란 뭘까?
바로 Tab이나 Shift + Tap이 모달 안에서만 순환해야 하는데, 그 부분이 빠져 있었던 것이다.
즉, 모달 외부까지 나가서 순환이 되는 코드였던 것이다.
처음엔 직접 구현해보려 했다.
모달 안의 포커스 가능한 요소들을 전부 쿼리하고, Tab을 가로채서 처음과 마지막 사이를 순환시키는 로직이었는데,
짜다 보니 동적으로 추가되는 요소라던지, 비활성화 된 요소 등 엣지케이스가 끝도 없이 나왔고 코드라인 수에 부담이 느껴졌다.
스킬 파일은 누군가가 복붙하거나 파일 자체를 사용하는 레퍼런스인데, 불완전한 예시를 넣는 게 오히려 더 위험하다는 생각이 들었다.
결국 필자는 제목을 "Modal Focus Restoration"으로 바꾸고,
완전한 포커스 트랩이 필요하면 `focus-trap-react`와 같은 라이브러리를 쓰라는 안내를 명시했다.
욕심을 버리는 것도 설계의 결정이지 않을까?
PR 올리기!
PR을 열기 전에 필자는 직접 테스트를 진행하였다.
3가지 테스트를 진행했는데 아래와 같다.
- `node scripts/ci/validate-skills.js`를 돌려서 233개 스킬 전체가 정상적으로 검증되는지 확인
- `npx markdownlint-cli skills/frontend-a11y/SKILL.md`로 마크다운 문법 오류도 없는지 체크
- `~/.claude/skills/`에 직접 설치해서 "React 로그인 폼 만들어줘"라고 프롬프트를 날려서 필자가 작성한 접근성 패턴들이 자연스럽게 반영되어있는지 확인
테스트 결과엔 이상이 없었고 심지어 3번의 결과는 너무 인상적이었는데 `htmlFor`와`id`의 페어링과 같이 스킬에서 다룬 패턴들이 전부 생성된 코드에 담겨있었다!
(사실 1번과 2번은 code-owner인 Affaan Mustafa가 이전에 올린 PR에서 1번과 2번 같이 테스트를 했던 부분을 확인하여 이상 없는지 필자 또한 테스트 해보았다!)
머지되던 날
2026년 5월 25일, PR이 머지되었다!!!
`feat(skills): add frontend-a11y skill` 커밋이 `affaan-m/ECC`의 main 브랜치에 들어갔다!
처음 이 레포를 발견했을 때 든 그 생각이 현실이 됐다.
내가 반복적으로 피드백 받았던 그 접근성 이슈들을 claude code를 사용하는 전 세계 개발자들이 처음부터 올바르게 피해갈 수 있는 레퍼런스가 생긴 것이다!
첫 오픈소스 기여는 생각보다 훨씬 구체적인 작업이었던 것 같다.
기존 스킬, 혹은 코드들은 분석하고, 틈새를 찾고, 형식을 맞추며, AI 리뷰 봇들의 피드백을 하나씩 수정하는 과정이었다.
그리고 그 모든 과정이 결국 더 나은 기여를 만들기 위한 것이라 생각을 한다.
선한 영향력을 끼치는 개발자의 첫 발걸음이라고 생각하고 시작했는데,
이젠 다음 스텝으로 걸음을 내딛어 봐야겠다!
내 경험이 아닌, 정말 개발자 생태계를 위한 기여를 하고 싶다!