millionco 'react-doctor' 공개, AI 작성 React 코드 0~100점 자동 진단

millionco가 AI 에이전트가 작성한 React 코드를 검사하는 한 줄 명령 도구 'react-doctor'를 GitHub에 공개했다. 'Your agent writes bad React, this catches it'을 슬로건으로 내세웠으며, 프로젝트 루트에서 'npx -y react-doctor@latest .' 한 번이면 즉시 코드베이스를 스캔한다.

스캔 결과는 0~100 범위의 단일 헬스 스코어와 함께 진단 리스트로 출력된다. 75점 이상은 'Great', 50~74점은 'Needs work', 50점 미만은 'Critical'로 분류된다. 진단 카테고리는 상태·이펙트, 성능, 아키텍처, 보안, 접근성, 데드 코드 6종이며, 사용 중인 프레임워크(Next.js, Vite, React Native)와 React 버전에 맞춰 룰이 자동으로 켜지고 꺼진다.

에이전트가 애초에 나쁜 코드를 쓰지 못하도록 룰을 학습시키는 'install' 서브커맨드도 제공된다. 'npx -y react-doctor@latest install'을 실행하면 머신에서 감지된 코딩 에이전트를 골라 룰 세트를 설치할 수 있다. Claude Code, Cursor, Codex, OpenCode를 포함해 50종 이상의 에이전트가 대상이다.

CI 통합용으로는 컴포지트 GitHub Action이 함께 배포된다. '.github/workflows/react-doctor.yml'에 'millionco/react-doctor@main' 액션을 배치하면 push와 pull_request 이벤트에서 동작하며, github-token 입력값이 설정된 경우 진단 결과를 PR 댓글로 게시하고 새 푸시마다 업데이트한다. 액션은 0~100 'score' 출력값을 노출해 후속 스텝에서 활용할 수 있고, 'fail-on' 입력을 error·warning·none 중 하나로 지정해 임계치 초과 시 빌드를 실패시킬 수 있다.

설정은 프로젝트 루트의 'react-doctor.config.json' 또는 package.json의 'reactDoctor' 키로 관리한다. ignore 옵션은 3단계 입자도로 나뉘는데, ignore.rules는 코드베이스 전체에서 룰을 끄고, ignore.files는 매칭된 파일의 모든 룰을 끄며, ignore.overrides는 지정된 파일에서 일부 룰만 끄고 나머지는 살린다. CLI 플래그는 항상 설정값을 덮어쓴다.

기존 린트 자산과의 통합도 자동 처리된다. '.oxlintrc.json' 또는 '.eslintrc.json'이 존재하면 룰이 점수 계산에 함께 반영되며, 'adoptExistingLintConfig: false'로 끌 수 있다. '.gitignore', '.eslintignore', '.oxlintignore', '.prettierignore'와 '.gitattributes'의 linguist-vendored·linguist-generated 어노테이션을 인식하고, 인라인 '// eslint-disable*'와 '// oxlint-disable*' 주석도 그대로 존중한다.

선택적 피어 의존성을 통해 외부 ESLint 플러그인 룰도 흡수한다. 'eslint-plugin-react-hooks' v6·v7이 설치되면 React Compiler 프런트엔드의 정확성 룰이 'react-hooks-js/*' 네임스페이스로 합류하고, 'eslint-plugin-react-you-might-not-need-an-effect' v0.10 이상이 설치되면 'no-derived-state', 'no-chain-state-updates', 'no-event-handler', 'no-pass-data-to-parent' 등 이펙트 안티패턴 룰이 'effect/*' 네임스페이스로 추가된다.

동일한 룰 세트가 oxlint 플러그인과 ESLint 플러그인 양쪽으로 동시에 출시되어, 프로젝트가 이미 쓰고 있는 린트 엔진에 그대로 연결된다. ESLint flat config에서는 'react-doctor/eslint-plugin'에서 recommended, next, react-native, tanstack-start, tanstack-query 등 프리셋을 가져와 합성할 수 있다.

CLI는 부분 스캔과 자동화 옵션을 폭넓게 제공한다. '--diff [base]'는 베이스 브랜치 대비 변경 파일만 스캔하고, '--staged'는 pre-commit 훅에서 스테이징된 파일만 검사한다. '--score'는 점수만 출력하고, '--json'은 'ok: false' 케이스를 포함해 항상 파싱 가능한 단일 객체를 stdout으로 내보낸다. 'react-doctor --explain <file:line>'(별칭 '--why')은 특정 위치에서 룰이 왜 발화했는지 또는 인근 suppression 주석이 왜 적용되지 않았는지를 진단해, 한 번의 스캔이 곧 suppression 감사로도 쓰이도록 했다.