TL;DR

React Doctor는 결정론적 정적 스캔을 통해 상태·effect·성능·아키텍처·보안·접근성 영역의 문제를 탐지하는 CLI 기반 도구이다. 프로젝트 루트에서 npx로 즉시 실행할 수 있으며 풀리퀘스트 단위 검사로 변경에 의해 새로 도입된 문제만 식별하고 CI에 통합해 요약 코멘트를 게시하도록 설계되었다. 추가로 감지 결과를 에이전트 스킬로 연계해 코딩 에이전트가 유사한 문제를 수정하거나 회피하도록 만들 수 있으며 익명화된 텔레메트리 수집은 `--no-telemetry`로 비활성화할 수 있다. 이 도구는 다양한 React 생태계를 지원함으로써 여러 프로젝트에 일관된 규칙을 적용하는 데 유용하지만 개별 규칙의 세부 동작과 적용 범위는 구성 파일로 조정해야 한다.

주요 기능

• 프로젝트 전체를 결정론적으로 스캔해 상태와 effect 관련 패턴, 성능 병목, 아키텍처 반패턴, 보안 취약점, 접근성 문제를 규칙 기반으로 탐지한다. 이 과정은 런타임 없이 소스코드 분석을 통해 수행되며 프레임워크 구분 없이 Next.js, Vite, TanStack, React Native, Expo 같은 환경에서 동작을 목표로 한다. 검사 결과는 CLI 출력과 CI 주석으로 전달되어 개발 흐름에 통합된다.
• 풀리퀘스트 단위 검사 설정을 제공해 변경으로 새로 도입된 문제만 보고하도록 구성할 수 있다. CI 설치 명령은 워크플로를 추가하고 PR에 요약 코멘트를 게시하며 스캔 범위와 gate 설정을 런타임에 변경할 수 있도록 구성 옵션을 노출한다. 이 접근법은 기존 백로그를 반복해서 노출하지 않고 신규 도입 이슈에만 주의를 집중하게 한다.
• 코딩 에이전트용 스킬을 설치하는 기능을 제공해 감지된 문제 패턴을 에이전트가 학습하고 향후 자동 수정 시 활용하도록 연계할 수 있다. 설치 과정은 단일 npx 명령으로 수행되며 README는 Claude Code, Cursor, Codex, OpenCode 등 다양한 에이전트와의 호환성을 명시한다. 이 연동은 수동 리뷰 부담을 낮추고 반복적인 코드 정리 작업을 자동화하는 데 기여한다.
• 익명화된 실행 메타데이터와 충돌 정보를 Sentry로 전송하는 텔레메트리 옵션을 제공하며 사용자는 명령행 플래그로 수집을 차단할 수 있다. 수집 항목에는 CLI 버전, 플랫폼, Node 버전, 호출한 커맨드, 프로젝트 형태 등 코드 내용이 포함되지 않는 메타 정보가 포함된다. 이 데이터는 안정성 개선과 우선순위 결정을 위해 사용된다.

어떻게 동작하는가

React Doctor는 소스코드를 규칙 기반으로 결정론적 스캔을 수행해 상태와 effect, 성능, 아키텍처, 보안, 접근성 관련 규칙을 적용해 문제를 식별한다. 풀리퀘스트 환경에서는 변경된 범위에 대해서만 규칙을 적용해 '신규로 도입된' 문제만 보고하도록 동작하며 CI 워크플로에 통합되어 자동으로 요약 코멘트를 게시한다. 감지 결과는 에이전트 스킬로 전파되어 이후 에이전트가 유사한 문제를 수정하도록 연계할 수 있다.

해결 문제

에이전트가 생성하거나 개발자가 도입한 잘못된 React 코드로 인한 품질 저하를 조기에 발견하는 문제를 해결한다. 결정론적 정적 스캔을 통해 상태·effect·성능·아키텍처·보안·접근성 분야의 패턴을 자동으로 식별함으로써 수동 리뷰 비용을 낮춘다. 풀리퀘스트 스코프 중심의 검사로 기존 백로그를 반복적으로 재노출하지 않으면서 변경에 의해 새로 생긴 문제에만 집중할 수 있게 만든다.

지금 주목받는 이유

레포지토리가 13,321개의 스타를 보유하고 있어 오픈소스 커뮤니티에서 널리 채택되고 있다는 지표가 있다.

차별점

• 변경 기반(PR 스코프) 검사로 기존 코드베이스의 누적 이슈를 반복해서 경고하지 않고 오직 변경으로 도입된 문제만 보고하도록 작동한다. 이 방식은 CI에서의 노이즈를 줄이고 리뷰어가 실제로 수정해야 할 항목에만 집중하게 만든다. README는 `react-doctor ci install`로 워크플로를 설치해 이 동작을 자동화할 수 있음을 명시한다.
• 다양한 React 생태계와 호환되도록 설계되어 Next.js, Vite, TanStack, React Native, Expo 등에서 동작을 목표로 한다. 프레임워크별 별도 설정 없이 프로젝트 형태를 인식해 검사 범위를 결정하는 것으로 설계되어 있어 여러 코드베이스를 가진 조직에서 일관된 검사가 가능하다. 이 호환성은 라이브러리·플랫폼 전반에서 동일한 규칙 세트를 적용할 수 있게 한다.
• 에이전트 스킬 설치 기능을 통해 감지된 패턴을 코딩 에이전트에 연계할 수 있다는 점이 차별화 요소다. 스킬을 설치하면 에이전트가 이전에 기록된 이슈 유형을 바탕으로 향후 자동 수정을 시도하거나 코드를 생성할 때 회피하도록 동작할 수 있다. 이 통합은 반복적인 수리 작업을 자동화하고 에이전트의 출력 품질을 점진적으로 개선하는 운영 흐름을 만든다.

사용 사례

• 개발 파이프라인에 CI 워크플로를 추가해 풀리퀘스트에서 새로 도입된 React 관련 버그·성능·접근성 문제를 자동으로 감지하고 요약 코멘트를 남기는 용도로 사용할 수 있다. 이 방식은 리뷰 노이즈를 줄이고 자동 게이트를 통해 품질 저하를 방지하는 데 유용하다. GitLab CI 환경에서는 gate-only scaffold를 사용해 최소한의 통합으로 운영을 시작할 수 있다.
• 코딩 에이전트에 스킬을 설치해 에이전트가 생성한 코드의 품질을 개선하도록 연계할 수 있다. 스킬 연동을 통해 에이전트는 과거에 감지된 규칙 위반을 학습하고 유사한 실수를 반복하지 않도록 행동을 조정할 수 있다. 이 흐름은 자동화된 코드 생성 파이프라인의 출력 신뢰도를 높이는 데 기여한다.
• 로컬 개발 환경에서 수시로 npx 명령을 실행해 전체 코드베이스 수준의 규칙 위반을 탐지하고 팀 내 코딩 스타일·안전성·접근성 규범을 유지하는 데 활용할 수 있다. 단일 명령으로 초기 감사를 수행해 규칙 설정 파일(doctor.config.ts)을 생성하고 이후 세부 규칙을 조정할 수 있다. 이 과정은 코드베이스의 기술 부채를 줄이는 사전 예방적 관리를 지원한다.

시작하기

프로젝트 루트에서 `npx react-doctor@latest`를 실행하면 즉시 감사가 수행되어 검사 결과가 출력된다. 코딩 에이전트와 연동하려면 `npx react-doctor@latest install` 명령으로 스킬을 설치하면 되고 CI 통합이 필요하면 `npx react-doctor@latest ci install`로 워크플로를 추가하면 된다. 추가 규칙과 실행 방식은 doctor.config.ts 파일을 통해 구성할 수 있다.