AI가 만든 코드 스파게티를 차단하는 규칙 기반 템플릿과 공개 리포지토리

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

AI 보조 코드는 작은 프로젝트에서는 유용하지만 큰 코드베이스에서는 불필요한 재생성과 경계 침범으로 스파게티화를 초래한다고 작성자는 지적했다. 이를 해결하기 위해 작성자는 단일 명령어(pnpm check)로 동작하는 의견이 고정된 템플릿을 도입했고 eslint --print-config로 확인되는 약 200개의 활성 규칙과 semgrep, ast-grep, knip, jscpd, dependency-cruiser를 조합해 빌드 단계에서 규칙 위반을 차단하도록 구성했다. 규칙 집합은 append-only 정책으로 운영되어 시간이 지날수록 느슨해지지 않으며, 실제로 grademe 프로젝트에 적용해 지인들이 평소보다 더 큰 기능을 안정적으로 배포했다는 실무적 결과가 제시되어 오픈소스로 공개되었다. 이 접근법은 AI가 생성한 코드를 자동화된 게이트로 강제하여 스파게티화를 예방하는 실용적 대안임이 확인된다, 다만 규칙의 과도한 엄격성은 유연성 문제를 야기할 수 있다.

실용적 조언

코드베이스에 AI를 도입할 때는 단일 실행 명령어로 모든 정적 검사와 규칙을 통합하여 규칙 위반 시 빌드를 실패시키는 게이트를 두어야 한다는 점이 실무적 조언으로 제시된다. 이 방식은 컴포넌트 배치, 디자인 토큰 사용, 중복 코드, 불필요한 의존성 등 구조적 문제를 자동으로 차단한다. 또한 규칙 위반 시 실패 메시지가 위반 규칙을 구체적으로 가리키도록 구성해야 AI와 인간이 수정하기 쉽다.
규칙 집합은 추가는 허용하지만 완화는 금지하는 append-only 운영 방침을 적용하면 시간이 지날수록 품질 표준이 낮아지지 않는다고 권장된다. 이 정책은 단기적인 편의성을 위해 규칙을 약화하는 경향을 기술적으로 봉쇄하여 장기적 유지보수성을 보호한다. 다만 실제로는 예외 관리 정책을 별도로 두어 필요한 경우 합리적 절차로 규칙을 조정할 수 있어야 한다.

섹션별 상세

작성자는 AI가 작은 프로젝트에서는 유용하지만 큰 코드베이스에서는 스파게티화를 일으킨다고 문제를 제기했다. 구체적 사례로는 이미 존재하는 컴포넌트를 재생성하거나 'dumb' 컴포넌트 내부에서 데이터를 가져오고, 원치 않는 raw color를 삽입하거나 기능을 한 파일에 몰아넣어 500줄이 넘는 파일을 생성하는 행태를 지적했다. 이로 인해 수개월 후 레포지토리가 뒤엉키고 본인도 AI도 수정을 안전하게 수행할 수 없게 되었다고 보고했다.

해결책으로 작성자는 의견이 강하게 고정된 템플릿과 단일 검증 명령어를 도입했다는 구체적 방식을 소개했다. 템플릿은 명확히 설계된 아키텍처와 스택을 제공하고 pnpm check 실행 시 컴포넌트 위치, 디자인 토큰 사용, 컴포넌트 크기 같은 규칙 위반을 빌드 실패로 처리하며 실패 메시지는 위반 규칙을 정확히 가리킨다. 실행 파이프라인 구성에는 eslint --print-config로 확인되는 약 200개의 활성 규칙과 semgrep, ast-grep, knip, jscpd, dependency-cruiser 같은 정적 검사 도구들이 포함된다고 명시되어 있어 자동화된 게이트가 어떻게 작동하는지 실무적으로 보여준다.

규칙 집합은 append-only 정책으로 운영된다는 점이 작동 원리의 핵심 규칙으로 제시되었다. 규칙은 더 추가할 수는 있어도 기존 규칙을 약화시켜 통과시키는 방식은 허용하지 않으므로 코드베이스는 시간이 지날수록 느슨해지지 않고 오히려 점점 엄격해진다. 이 설계는 개발자가 일시적으로 규칙을 회피해 기술부채를 누적시키는 경로를 봉쇄하며 장기적인 유지보수성을 확보하는 메커니즘으로 작동한다.

작성자는 해당 시스템을 실제 프로젝트에 적용한 결과를 사례로 제시했다. grademe라는 브라우저 기반 C 학습용 IDE가 이 설정으로 구축되었고 작성자는 몇몇 친구에게 전달해 그들이 평소보다 더 큰 기능을 안전하게 배포했다고 보고했다. 프로젝트는 오픈소스로 공개되었고 데모와 GitHub 링크가 함께 제공되어 실무적 검토와 재사용이 가능함을 직접 확인할 수 있다.

용어 해설

린팅(Linting): — 소스코드의 스타일 규칙과 잠재적 버그를 자동으로 검출하는 정적 검사 과정이다. 린터는 코드 구조와 명명 규칙, 타입 사용 등 규칙 위반을 탐지하여 빌드 실패 또는 경고를 발생시키고, 이를 통해 일관된 코드 스타일과 유지보수성 향상을 목표로 한다. 본문에서는 AI가 생성한 코드를 규칙 위반 시 빌드를 중단시키는 방식으로 스파게티화를 방지하는 핵심 수단으로 사용되었다.
정적 분석(Static Analysis): — 실행 전 소스코드를 분석하여 코드 패턴, 중복, 잠재적 오류, 의존성 문제 등을 찾아내는 기법이다. 정적 분석 도구는 AST 기반 검사와 패턴 매칭을 통해 런타임에 드러나기 어려운 문제를 포착하며, 본문에서는 semgrep, ast-grep 같은 도구가 이 역할을 수행했다는 점이 핵심이다. 이러한 도구는 AI가 생성한 코드의 구조적 품질을 자동으로 평가하는 데 사용되었다.
pnpm: — Node 생태계에서 사용하는 패키지 매니저로서 빠른 설치와 디스크 공간 절약을 목표로 설계되었다. 본문에서는 단일 명령어인 pnpm check로 모든 규칙과 정적 검사 파이프라인을 실행하는 게이트 역할을 수행한다고 명시되어 있어 워크플로의 핵심 실행기 역할을 한다. 이 역할 때문에 pnpm은 템플릿의 '문지기'로서 기능한다.

언급된 도구

pnpm추천

단일 명령어(pnpm check)로 규칙과 정적 검사 파이프라인을 실행하는 패키지 매니저 겸 실행기 역할

ESLint추천

코드 스타일과 패턴 위반을 탐지하는 정적 린터로 eslint --print-config로 활성 규칙 수가 확인됨

Semgrep추천

코드 패턴 기반의 정적 분석을 수행하여 보안·구조적 문제를 탐지하는 도구

ast-grep추천

AST 기반의 패턴 매칭으로 코드 구조적 규칙을 검사하는 도구

jscpd추천

코드 중복을 탐지하여 복제된 코드 블록을 식별하는 도구

knip추천

사용되지 않는 의존성과 패키지를 찾아내는 도구로 의존성 관리를 보조

dependency-cruiser추천

모듈 의존성 관계를 검사하여 크로스-피처 import 같은 의도치 않은 의존성을 탐지

언급된 리소스

Demo베드록 데모

GitHubbedrock GitHub 리포지토리