AI 작성 파이썬 코드 포트폴리오 공개 전 필수 검사 도구 3가지 (Ruff·Pyright·pytest)
AI가 생성한 파이썬 코드를 깃허브나 포트폴리오에 공개하기 전 코드 린트와 포맷팅(Ruff), 정적 타입 검사(Pyright), 단위 테스트(pytest)를 거치는 3단계 코드 품질 점검 가이드.
LLM과 코딩 어시스턴트의 발전으로 누구나 손쉽게 파이썬 프로젝트를 완성할 수 있게 되었지만, AI가 작성한 코드를 면밀한 검토 없이 포트폴리오나 깃허브(GitHub) 공개 저장소에 그대로 올리는 것은 위험합니다. AI 생성 코드는 겉보기에 동작하더라도 사용되지 않는 import, 잘못된 타입 전달, 경계값 예외 처리 누락 등 초보적인 결함을 내포하기 쉽습니다. 개발자 꼬마봇(@BBBang9900)이 제안한 파이썬 프로젝트 공개 전 필수 점검 도구 3가지와 사전 검증 워크플로우를 정리합니다.
이미지 출처: 꼬마봇 (@BBBang9900)
1. Ruff: 린트 검사와 코드 포맷팅 자동화
Ruff는 Rust로 작성되어 기존 Flake8, Black, isort 등의 도구보다 10배에서 100배 빠른 실행 속도를 자랑하는 차세대 파이썬 린터 및 포매터입니다.
- 규칙 위반 및 미사용 코드 탐지: 불필요하게 선언된 모듈 import나 PEP 8 스타일 가이드라인 위반, 자주 발생하는 안티패턴(Flake8-bugbear 호환)을 즉시 찾아냅니다.
- 자동 수정 기능(
--fix):ruff check --fix명령을 통해 미사용 import 제거와 같은 단순 위반 사항을 자동으로 정리할 수 있으며,ruff format으로 일관된 코드 포맷을 유지합니다.
pyproject.toml 파일의 [tool.ruff] 섹션에 기본 검사 규칙을 설정하고 실행하는 것만으로도 AI가 남긴 지저분한 보일러플레이트와 문법적 군더더기를 빠르게 정돈할 수 있습니다.
2. Pyright: 런타임 이전 정적 타입 결함 검출
파이썬은 동적 타입 언어이지만, 대규모 코드베이스와 포트폴리오에서는 명확한 타입 힌트와 정적 검증이 코드 신뢰성을 좌우합니다. Pyright는 마이크로소프트가 개발한 고속 정적 타입 검사기(VS Code Pylance 확장의 핵심 엔진)입니다.
- 타입 불일치 조기 발견: 함수 시그니처에 선언된 타입과 실제 전달되는 인수 타입 간의 불일치, 반환값 타입 오류,
None처리 누락 등을 실행 전에 정적으로 감지합니다. - Node.js 기반 CLI: Pyright CLI는 Node.js 런타임 환경 기반으로 구동되며,
pyproject.toml의[tool.pyright]또는pyrightconfig.json을 통해 점진적 검사 모드(basic,standard,strict)를 지정할 수 있습니다.
AI가 임의로 추론하거나 생략한 함수 인자 타입을 명시적으로 고정하고 검증함으로써, 실행 시점에 발생할 수 있는 TypeError나 AttributeError를 사전에 차단합니다.
3. pytest: 빈 입력과 경계값을 검증하는 단위 테스트
린트와 타입 검사가 정적 구조를 보장한다면, 실제 비즈니스 로직이 의도한 대로 동작하는지는 단위 테스트를 통해 입증해야 합니다. pytest는 파이썬 생태계에서 가장 널리 쓰이는 표준 테스트 프레임워크입니다.
- 기대값과 실제 결과 비교: 함수의 입출력 계약이 올바른지
assert구문으로 직관적인 테스트 코드를 작성합니다. - 경계값 및 비정상 입력 검증: 빈 문자열, 빈 리스트,
None, 음수, 타입 외 입력값 등 AI가 정상 시나리오에만 치중해 간과하기 쉬운 엣지 케이스를 집중적으로 검증합니다.
테스트 스위트가 갖춰진 프로젝트는 코드 리뷰어와 잠재적 채용 담당자에게 단순 AI 복사-붙여넣기가 아닌 엔지니어링 검증 과정을 거쳤음을 보여주는 강력한 근거가 됩니다.
실무 적용 시 주의점과 한계
이 세 가지 도구를 프로젝트 워크플로우에 통합할 때 유의해야 할 실무적인 주의점들이 있습니다.
- 로컬 설치 및 설정 파일 구축: 각 도구를 정상적으로 운용하려면 가상 환경 내 패키지 설치와 함께
pyproject.toml을 통한 프로젝트별 경로(src,tests) 및 규칙 설정이 선행되어야 합니다. - 자동 수정 결과 검토:
ruff --fix등의 자동 수정 옵션은 편리하지만, 의도된 부수 효과나 주석 구조를 변경할 수 있으므로 반드시 git diff를 통해 변경 사항을 검토해야 합니다. - 테스트 코드의 주도적 작성: 테스트 케이스 자체는 개발자가 직접 도메인 요구사항과 예외 시나리오를 정의해야 유의미한 검증력을 가집니다.
- 품질의 하한선일 뿐 완벽성의 보증은 아님: Ruff, Pyright, pytest를 모두 통과했다고 해서 논리적 설계 오류, 보안 취약점, 비즈니스 요구사항 불일치가 완전히 없다는 뜻은 아닙니다. 이 3단계 검사는 AI 코드 검토의 출발선이자 기초 위생 필터로 활용해야 합니다.