React 스캔을 통해 배운 점

Clear Code Intelligence는 공개된 React 저장소: react/react를 스캔했습니다.

이것은 React에 대한 비난이 아닙니다.

React는 세계에서 가장 중요한 오픈 소스 프론트엔드 프로젝트 중 하나입니다. 또한 기술 부채 보고가 단순한 패턴 매칭 이상이어야 하는 이유를 보여주는 바로 그 종류의 저장소이기도 합니다.

성숙한 프레임워크 저장소에는 런타임 내부 코드(runtime internals), 컴파일러 코드, 서버 렌더링 코드, DevTools 구현, 테스트용 더미 데이터(fixtures), 생성된 기대값(generated expectations), 변경 로그 기록(changelog history), 호환성 로직(compatibility logic), 빌드 도구(build tooling) 및 장기적인 공개 API 결정 사항들이 포함되어 있습니다.

만약 보고서가 이 모든 것을 동일한 종류의 부채로 취급한다면, 그 보고서는 유용하지 않습니다.

스캔 내용

Clear Code는 공개된 react/react 저장소를 검토하여 기술 실사(technical diligence) PDF 보고서를 작성했습니다.

스캔은 다음을 측정했습니다:

7,228개의 저장소 파일
7,070개의 분석 파일
1,033,022줄의 코드
PDF에 표시된 250가지 발견 사항(findings)
보고서 정리 전 생성된 4,742개의 원시 발견 사항
높은 AI 토큰 부채 위험성

원시 점수표는 의도적으로 가혹했습니다:

영역	점수
전체 원시 실사 점수	1/100
...
그 원시 점수는

그러한 분류(classification) 없이는 보고서가 노이즈로 가득 차게 됩니다.

그러한 분류가 있다면, 그것은 의사 결정 지원(decision support) 도구가 됩니다.

AI 토큰 부채(AI Token Debt)가 나타나는 곳

AI 토큰 부채(AI token debt)란 코드베이스를 추론하기 어려울 때 발생하는 추가적인 컨텍스트(context), 검색(search), 추론(inference), 재시도(retry), 그리고 검토(review) 작업을 의미합니다.

React는 이 저장소에서 작업하는 AI 에이전트가 다음과 같은 다층적인 컨텍스트를 이해해야 하기 때문에 강력한 사례가 됩니다:

공용 API 호환성 (public API compatibility)
리컨실러 동작 (reconciler behavior)
서버 렌더링 및 스트리밍 동작 (server rendering and streaming behavior)
React Server Components 및 Flight 인터페이스 (Flight surfaces)
컴파일러 로워링 및 생성된 기대 사항 (compiler lowering and generated expectations)
DevTools 동작 (DevTools behavior)
빌드/릴리스 모드 (build/release modes)
테스트 픽스처 의도 (test fixture intent)

이는 비판이 아닙니다. 성숙한 공개 프레임워크의 본질입니다.

하지만 이는 AI 에이전트가 파일 하나를 읽는 것만으로는 많은 영역을 안전하게 수정할 수 없음을 의미합니다. 에이전트는 컨텍스트를 수집하고, 관련 패키지를 조사하며, 픽스처 의미론(fixture semantics)을 이해하고, 호환성 가정을 깨뜨리지 않도록 주의해야 합니다.

그것이 바로 토큰 세금(token tax)입니다.

에이전트가 더 많은 것을 추론해야 할수록, 더 많은 토큰을 소모합니다.

흥미로운 핫스팟(Hotspots)

스캔 결과, AI 에이전트가 수정하기에 본질적으로 비용이 많이 드는 영역에서 지연된 작업 클러스터(deferred-work clusters)가 드러났습니다:

packages/react-server/src/ReactFizzServer.js
packages/react-server/src/ReactFlightServer.js
packages/react-reconciler/src/ReactFiberCommitWork.js
packages/react-reconciler/src/ReactFiberWorkLoop.js
packages/react-client/src/ReactFlightClient.js
compiler/packages/babel-plugin-react-compiler/src/HIR/BuildHIR.ts
compiler/crates/react_compiler_lowering/src/build_hir.rs

이것들이 자동으로 결함(defect)인 것은 아닙니다.

이곳들은 컨텍스트가 중요한 영역입니다. 이 파일들을 다루게 될 미래의 인간이나 AI 에이전트는 동작을 변경하기 전에 주변 프로토콜, 런타임(runtime), 컴파일러, 호환성 및 테스트 기대 사항을 이해해야 합니다.

이것이 바로 현대적인 기술 부채(technical debt) 보고서가 보여주어야 할 모습입니다.

등급 하향이 필요한 발견 사항

스캔을 통해 도구(tooling)가 더 똑똑해져야 할 지점들도 드러났습니다.

예를 들어:

CHANGELOG.md는 런타임 코드 (runtime code)처럼 점수가 매겨져서는 안 됩니다.
생성된 컴파일러 기대 파일 (generated compiler expectation files)은 프로덕션 구현 파일 (production implementation files)처럼 점수가 매겨져서는 안 됩니다.
todo를 포함하는 피스처 (fixture) 이름은 관리되지 않는 인도 부채 (unmanaged delivery debt)가 아니라 테스트 분류 (test taxonomy)인 경우가 많습니다.
릴리스 노트 (release notes)의 긴 줄은 비즈니스 로직 (business logic)의 긴 줄과 동일하지 않습니다.
프레임워크 호환성 주석 (framework compatibility comments)은 부주의한 부채가 아니라 의도적인 트레이드오프 (tradeoffs)를 나타낼 수 있습니다.

이는 유용한 제품 피드백입니다.

Clear Code는 프레임워크 저장소 (framework repositories)를 위한 파일 범위 분류 (file-scope classification)를 계속 개선해야 합니다:

changelog (변경 이력)
docs (문서)
test fixture (테스트 피스처)
generated output (생성된 출력물)
snapshot (스냅샷)
benchmark (벤치마크)
compiler expectation (컴파일러 기대값)
runtime implementation (런타임 구현)
public API surface (공개 API 표면)
accepted compatibility cost (수용된 호환성 비용)

해당 분류 계층이야말로 가공되지 않은 발견 사항을 경영진 수준의 분석 (executive-grade analysis)으로 전환하는 핵심입니다.

이것이 AI 지원 엔지니어링 (AI-Assisted Engineering)에 중요한 이유

차세대 기술 부채 (technical debt)는 단순히 인간의 가독성 (human readability)에 관한 것만이 아닙니다.

그것은 또한 AI 비용 (AI cost)에 관한 것이기도 합니다.

코드 소유권 (code ownership)이 불분명하고, 테스트가 실패 동작을 설명하지 못하며, 피스처 (fixtures)를 프로덕션 코드와 구별할 수 없고, 생성된 아티팩트 (generated artifacts)가 구현 파일과 섞여 있을 때, AI 에이전트 (AI agents)는 컨텍스트 (context)를 재구성하는 데 더 많은 토큰 (tokens)을 소비합니다.

그 비용은 다음과 같은 형태로 나타납니다:

더 큰 프롬프트 (prompts)
더 많은 파일 검색 (file searches)
더 많은 도구 호출 (tool calls)
더 많은 재시도 (retries)
더 긴 리뷰 주기 (review cycles)
환각된 변경 (hallucinated changes)의 더 높은 위험
더 많은 인간의 감독 (human supervision)

다시 말해, 이제 기술 부채는 엔지니어링 시간과 AI 에이전트 운영 비용 (AI-agent operating cost) 모두에서 이자를 발생시킵니다.

다음에 개선할 사항

React 스캔은 자동화된 보고 (automated reporting)의 힘과 한계를 모두 보여주었기에 유용했습니다.

보고서의 다음 버전은 다음과 같아야 합니다:

심각도 (severity) 점수를 매기기 전에 프레임워크 저장소 경로를 분류 (classify) 할 것
원시 점수 (raw score)와 해석된 점수 (interpreted score)를 분리할 것
생성된 파일 및 피스처 (fixture)가 많은 경로를 자동으로 식별할 것
수용된 호환성 복잡성 (compatibility complexity)과 정리 대상 (cleanup candidates)을 구분할 것
도메인 영역별로 AI 토큰 부채 (AI-token-debt) 유발 요인을 보여줄 것
어떤 결과가 조치를 취해야 하는지, 어떤 결과가 인지 (acknowledgement)만 하면 되는지 설명할 것

이것이 기술 리더들에게 필요한 표준입니다.

스캐너의 덤프 (scanner dumps)가 아니라,

의사 결정 지원 (Decision support)입니다.

초대 (Invitation)

공개 저장소 (Public repositories)가 유용한 이유는 증거를 검토할 수 있고 방법론에 이의를 제기할 수 있기 때문입니다.

React 유지 관리자 (maintainer) 커뮤니티의 누군가가 전체 PDF 보고서를 원하신다면, 기꺼이 공유하고 스캔 결과가 수정되거나, 조정되거나, 혹은 범위를 다르게 설정해야 할 부분이 어디인지 듣고 싶습니다.

공개된 코드는 공개적이고, 공정하며, 증거에 기반한 분석을 받을 자격이 있습니다.