에이전트가 짠 React를 잡아주는 react-doctor

Aiden Bai의 트윗에 한 문장이 눈에 걸렸습니다 — Your agent writes bad React. This catches it. 최근에도 Claude Code가 만들어 준 컴포넌트에서 useEffect로 데이터를 페칭하는 패턴을 손으로 걷어내고 있던 참이었습니다.

react-doctor는 그 작업을 한 줄로 줄여 줍니다.

점수와 진단

npx -y react-doctor@latest .

프로젝트 루트에서 한 번 돌리면 0에서 100 사이의 health score 가 나옵니다. 75 이상이면 Great, 50–74는 손볼 곳 있음, 50 미만은 위험 신호입니다. 점수 옆에는 카테고리별 진단이 따라옵니다 — state & effects, performance, architecture, security, accessibility, dead code 여섯 갈래입니다.

Next.js, Vite, React Native를 자동으로 감지해 프레임워크와 React 버전에 맞는 룰만 켭니다. .gitignore, .eslintignore, 인라인 // eslint-disable* 주석은 모두 그대로 존중합니다.

더 흥미로운 모드: 짜기 전에 가르치기

npx -y react-doctor@latest install

같은 패키지의 install 서브커맨드는 사용 중인 코딩 에이전트에 React 베스트 프랙티스를 룰 파일로 주입합니다. Claude Code, Cursor, Codex, OpenCode를 비롯한 50개 넘는 에이전트를 자동으로 감지해, 어디에 설치할지 묻습니다.

핵심은 작용하는 시점 입니다. 일반 린터는 이미 짠 코드를 봅니다. 사후입니다. install 모드는 코드를 짜기 전에 작용합니다. 코드 리뷰가 아니라 신입 동료에게 컨벤션을 미리 건네는 일에 가깝습니다.

물론 룰 주입은 시스템 프롬프트에 얹는 가이드일 뿐, 에이전트가 매번 그 룰을 따른다는 보장은 없습니다. 그래서 사후 검사는 여전히 필요합니다. 두 모드는 양자택일이 아니라 같이 굴리는 관계입니다.

끼워 넣는 자리

GitHub Actions 연동도 기본 제공됩니다. PR에 점수와 진단을 코멘트로 남기고 갱신해 주며, --fail-on warning 한 줄로 일정 등급 이상의 진단에서 빌드를 실패시킬 수 있습니다.

룰 셋 자체는 oxlint와 ESLint 양쪽의 플러그인으로도 배포됩니다. 별도 도구를 더하기 부담스러운 프로젝트라면 기존 린트 파이프라인에 그대로 묻혀 들어갑니다. 끄고 싶은 룰이 있다면 react-doctor.config.json에 ignore.rules / ignore.files / overrides 세 단계가 준비돼 있습니다 — 가장 좁은 단계를 고르는 편이 다른 룰의 커버리지를 잃지 않습니다.

린터의 역할이 조금씩 바뀌고 있습니다. 잘못 짠 코드를 짚어 주는 일에서, 잘못 짜기 전에 가르쳐 두는 일까지 한 도구가 묶어 다룹니다. 다음번 프로젝트의 setup 단계에 npx react-doctor install 한 줄을 끼워 두면, 적어도 같은 안티패턴을 두 번 고치는 일은 줄어듭니다.