수요일 오후 2시, 강남의 한 스타트업 개발실.
모니터에는 Cursor(AI 기반 코드 에디터)가 순식간에 작성한 수백 줄의 리액트 컴포넌트가 띄워져 있다. 개발자는 코드가 정상 작동하는 것은 확인했지만, 불필요한 리렌더링이나 잠재적 메모리 누수가 없는지 일일이 훑으며 미간을 찌푸린다.
AI가 코드를 짜는 속도는 빨라졌지만, 이를 검토하는 인간의 속도는 그대로다. 이 비효율을 해결하려는 시도가 시작됐다.
npx 한 줄로 실행하는 100개 이상의 oxlint 규칙
AI가 작성한 리액트 코드를 어떻게 신뢰할 수 있을까? 개발자는 터미널에서 `bash npx react-doctor@latest` 명령어를 입력하는 것만으로 프로젝트 전체를 스캔한다. 분석 결과는 0점에서 100점 사이의 진단 점수로 환산되어 즉시 출력된다. 이 점수는 상태 관리, 부수 효과, 성능, 보안, 접근성, 아키텍처 등 6개 주요 범주를 종합적으로 평가한 수치다. Million.co(리액트 성능 최적화 도구 개발사)가 개발해 MIT 라이선스로 공개한 이 도구는 AI 에이전트가 생성한 코드의 무결성을 검증하는 용도로 설계되었다. 코드 품질을 주관적 판단이 아닌 정량적 지표로 변환해 프로젝트의 전반적인 건강 상태를 수치로 증명한다.
분석 엔진의 핵심은 oxlint(Rust 기반의 고성능 자바스크립트 린터)다. React Doctor는 100개 이상의 자체 규칙을 내장하고 있으며 이를 `oxlint-plugin-react-doctor` 플러그인 형태로 구현했다. 기존의 정적 분석 도구들이 ESLint(자바스크립트 정적 분석 도구) 런타임 위에서 동작하며 발생하는 실행 지연과 메모리 오버헤드를 제거했다. Rust 언어의 메모리 효율성과 병렬 처리 능력을 활용해 런타임 없이 직접 코드를 분석하는 구조를 취한다. 이는 수천 개의 파일이 포함된 대규모 코드베이스에서도 지연 시간 없이 즉각적인 피드백을 가능하게 한다. 개발자는 코드 수정 직후 즉시 검증 결과를 확인해 수정 주기를 단축할 수 있다.
프레임워크별 특성을 반영한 프리셋 제공으로 분석의 정밀도를 높였다. Next.js(리액트 기반 웹 프레임워크), TanStack(상태 관리 및 쿼리 라이브러리), React Native(모바일 앱 프레임워크), Expo(리액트 네이티브 생태계 도구)를 위한 전용 규칙 세트가 각각 준비되어 있다. 개발자는 사용하는 환경에 맞는 프리셋을 선택해 해당 프레임워크의 모범 사례 준수 여부를 확인한다. 프레임워크 간의 미묘한 구현 차이를 규칙에 반영해 불필요한 경고를 줄이고 정확도를 높였다. 기존 ESLint 플러그인들이 사용자가 규칙을 일일이 선택하고 설정 파일을 구성해야 했던 수동적 방식과 대조된다. React Doctor는 설치 즉시 전체 범주를 진단하는 감사 도구로 포지셔닝되어 전체적인 품질 수준을 빠르게 파악하는 데 최적화되어 있다.
ESLint 플러그인을 넘어 AI 에이전트의 '검문소'로
린팅 도구는 개발자가 실수한 코드를 잡아내는 보조 수단이라는 인식이 강했다. React Doctor는 이 도구를 AI 에이전트가 생성한 코드를 스스로 검증하고 수정하게 만드는 제어 장치로 활용한다. 사용자가 `bash react-doctor install` 명령어를 실행하면 Claude Code, Cursor, Codex, OpenCode 같은 AI 에이전트에 분석 스킬이 자동으로 등록된다. 여기에 git post-checkout 및 post-merge 훅 설치를 지원해 코드 변경 시점마다 검증이 이뤄지게 했다. AI가 생성한 코드를 다른 AI 에이전트가 즉시 검토하고 수정하는 자동화 파이프라인을 구축해 인간의 개입을 최소화했다.
React Compiler가 활성화된 환경에서는 수동 메모이제이션 코드가 오히려 성능 저하를 일으킨다. React Doctor는 이 지점을 정밀하게 감지해 불필요한 최적화 코드를 찾아낸다. 사람이 코드 리뷰 단계에서 일일이 확인하던 중복 최적화 문제를 자동화된 스캔으로 대체하여 검토 비용을 줄였다. GitHub Actions 공식 액션을 통해 PR 단계에서 인라인 어노테이션과 스티키 코멘트로 결과를 남기며, `--diff` 모드를 적용해 변경된 파일만 스캔함으로써 CI 시간을 단축했다. 분석 결과는 react.doctor/share를 통해 외부로 공유할 수 있다. 단순한 규칙 준수 여부를 넘어 프로젝트 전체의 품질 점수를 정량적으로 관리하고 팀 간에 공유하는 체계다.
분석 엔진의 내부 구조는 Effect v4(타입 안전성을 강조한 함수형 프로그래밍 라이브러리) 기반의 병렬 분석 파이프라인으로 설계됐다. 의존성 주입과 태그드 에러, 제너레이터 기반 제어 흐름을 도입해 분석 과정에서 발생하는 예외 상황을 타입 수준에서 엄격하게 제어한다. 린팅과 데드코드 분석을 동시에 실행해 처리 속도를 높였으며,
import { diagnose } from '@react-doctor/api';const result = await diagnose(projectPath);
와 같이 `@react-doctor/api` 패키지의 `diagnose()` 함수를 통해 Node.js 환경에서 직접 진단 결과를 처리할 수 있다. 버전 흐름을 보면 v0.2.4에서 Effect v4 마이그레이션을 완료했고, v0.2.7에서 병렬 분석과 에이전트 감지 기능을 추가했으며, 최근 v0.2.8까지 릴리스를 이어갔다. 짧은 주기 내에 핵심 엔진의 교체와 기능 확장을 수행하며 AI 에이전트가 생성한 코드를 자동으로 검증하는 파이프라인의 안정성을 확보했다.
이처럼 강력한 자동 검증 기능을 실무에 효과적으로 적용하기 위해서는 단순한 설치를 넘어 전략적인 운영 기준이 필요하다.
코드 품질의 정량적 임계점 설정이 우선이다
React Doctor가 제공하는 0점에서 100점 사이의 점수는 프로젝트의 기술 부채를 객관적으로 측정하는 지표다. 개발 팀은 신규 프로젝트 시작 시점이나 대규모 리팩토링 단계에서 이 점수를 기준으로 코드 품질의 최소 허용치를 설정해야 한다. 점수가 80점 미만인 모듈은 AI 에이전트의 자동 수정 기능을 제한하고 인간 개발자가 직접 검토하는 단계를 거치는 것이 안전하다. 정량적 수치를 통해 리뷰어마다 다른 판단 기준을 통일하고, 팀이 합의한 최소 품질 기준을 강제할 수 있다.
**AI 에이전트 워크플로우에 최적화된 통합 지점을 선택한다**
Git 훅과 GitHub Actions를 활용한 검증 파이프라인은 AI가 생성한 코드의 무결성을 보장하는 필수 장치다. 변경된 파일만 스캔하는 `--diff` 모드는 CI 파이프라인의 실행 시간을 최소화하므로 대규모 코드베이스를 운영하는 팀에 적합하다. 반면, 로컬 개발 환경에서는 실시간 피드백을 위해 에이전트 스킬로 등록하여 코드 작성 즉시 오류를 수정하는 방식을 권장한다. 팀의 개발 속도와 코드 안정성 요구 수준에 맞춰 도입 범위를 결정해야 한다.
**프레임워크별 프리셋과 런타임 환경을 고려해 적용한다**
Next.js나 React Native 등 특정 프레임워크 환경에서는 해당 프리셋을 적용해야 불필요한 경고를 방지하고 정확한 분석이 가능하다. 특히 React Compiler를 사용하는 환경이라면 수동 메모이제이션 규칙을 비활성화하여 도구가 불필요한 최적화 코드를 지적하지 않도록 설정해야 한다. Rust 기반의 고성능 엔진이라도 프로젝트의 아키텍처와 도구의 규칙이 충돌하면 오히려 개발 흐름을 방해할 수 있다. 모든 규칙을 일괄 적용하기보다 현재 사용 중인 라이브러리와 프레임워크 버전에 맞는 프리셋을 선택해 오탐(False Positive)을 줄이는 것이 실질적인 방법이다.
자동화된 코드 검증은 인간의 리뷰를 대체하는 것이 아니라 AI가 생성한 코드의 신뢰 범위를 확정하는 통제 수단이다.
