Python을 3배 빠르게 작성하고 디버깅하세요, 사용하는 것은 Claude Code

터미널을 열고 cd로 Python 프로젝트 디렉터리로 이동한 뒤 claude를 실행하세요. 그게 전부입니다. Claude Code는 pyproject.toml, setup.py, requirements.txt, Pipfile 중 하나를 읽어 Python 프로젝트를 자동으로 감지합니다. 첫 명령부터 프로젝트의 구조, 의존성, 패키지 구성을 이해합니다.

프로젝트 루트에 CLAUDE.md 파일을 만들고 Python 특화 명령을 작성하세요. 테스트 러너(pytest, python -m pytest), 린터(ruff check, flake8), 포매터(ruff format, black), 타입 체커(mypy, pyright). 이렇게 하면 Claude Code가 매 변경 후 자신의 작업을 직접 검증할 수 있습니다.

팀이 Google 스타일 docstring, 절대 import, 테스트용 특정 디렉터리 구조 같은 특정 패턴을 사용한다면, 그 관례를 CLAUDE.md에 추가하세요. Claude Code는 모든 상호작용 전에 이 파일을 읽기 때문에 처음부터 프로젝트 스타일에 맞는 코드를 생성합니다. 이렇게 하면 나중에 스타일 선택을 고치느라 주고받는 과정을 없앨 수 있습니다.

Claude Code는 Python의 점진적 타입 시스템을 이해합니다. 타입이 없는 코드베이스에 타입 힌트를 추가하고, mypy와 pyright 에러를 고치며, 필요할 때는 TypeVar, Protocol, ParamSpec, Generic 같은 고급 타입 패턴을 사용할 수 있습니다. 사용 중인 Python 버전에 따라 str | None과 Optional[str] 중 무엇을 써야 하는지도 알고 있습니다.

Claude Code는 Google, NumPy, Sphinx 형식처럼 프로젝트 스타일에 맞는 docstring을 생성합니다. 함수 구현을 읽고 매개변수, 반환 타입, 엣지 케이스를 이해해, 일반적인 자리채우기용 텍스트가 아니라 함수가 실제로 무엇을 하는지 설명하는 문서를 작성합니다. 한 번의 작업으로 모듈 전체에 docstring을 추가할 수 있습니다.

Claude Code는 venv, poetry, pipenv, conda, uv 중 무엇을 사용하든 가상 환경 설정을 존중합니다. 의존성 파일을 읽어 어떤 패키지가 어떤 버전으로 사용 가능한지 알기 때문에, 설치하지 않은 라이브러리의 사용을 제안하거나 더 새로운 버전에서 바뀐 API에 맞춰 코드를 작성하는 일이 없습니다.

필요한 엔드포인트를 설명하세요. "이름과 이메일을 받아 이메일 형식을 검증하고 데이터베이스에 저장한 뒤 201 상태로 생성된 사용자를 반환하는 POST /api/users 엔드포인트를 만들어줘"와 같이 말하면, Claude Code가 라우트, Pydantic 모델(또는 Django 시리얼라이저), 데이터베이스 쿼리, 에러 처리를 작성합니다. 기존 코드를 읽어 패턴을 맞추므로, 다른 엔드포인트가 의존성 주입을 사용한다면 새 엔드포인트도 똑같이 사용합니다.

Claude Code는 데이터 모델 설명만으로 완전한 CRUD API를 만들 수 있습니다. 모델, 라우트, 검증 스키마, 데이터베이스 마이그레이션(Alembic이나 Django 사용), 테스트 파일을 생성합니다. 생성되는 각 파일은 프로젝트 구조를 따르며, 라우트가 app/api/v1/에 있고 모델이 app/models/에 있다면 Claude Code는 파일을 제자리에 둡니다. 또한 새 라우트를 기존 앱 인스턴스에 연결하고 적절한 HTTP 상태 코드와 에러 응답을 추가합니다.

엔드포인트를 만든 뒤, Claude Code에게 테스트를 작성해달라고 하세요. happy path, 검증 에러, 중복 처리, 인증 실패, 엣지 케이스를 다루는 pytest 테스트를 생성합니다. FastAPI 프로젝트라면 적절한 테스트 픽스처와 함께 httpx.AsyncClient을 사용합니다. Django라면 팩토리 기반 테스트 데이터와 함께 APIClient을 사용합니다. 이후 커밋하기 전에 모든 테스트가 통과하는지 확인하기 위해 테스트를 실행합니다.

Claude Code는 Jupyter 노트북 파일(.ipynb)을 읽고 이해하며, 셀 출력을 분석하고 노트북 코드의 디버깅을 도울 수 있습니다. 다만 Claude Code는 터미널에서 동작하기 때문에, 노트북의 로직을 Python 스크립트나 모듈로 추출했을 때 가장 잘 작동합니다. 데이터 탐색 작업에서는 많은 개발자가 Claude Code를 사용해 분석 코드를 .py 파일에 작성한 뒤 시각화를 위해 노트북으로 가져옵니다.

Claude Code는 웹 개발을 위한 Django, FastAPI, Flask, Starlette, Tornado, 데이터 과학을 위한 pandas, NumPy, polars, scikit-learn, 테스트를 위한 pytest, unittest, hypothesis, 데이터베이스 접근을 위한 SQLAlchemy, Tortoise ORM, Django ORM, 작업 큐를 위한 Celery와 Dramatiq 등 모든 주요 Python 프레임워크에서 작동합니다. 프로젝트의 의존성을 읽어 어떤 프레임워크를 사용하는지 파악하고 프레임워크별 패턴을 적용합니다.

Claude Code는 가상 환경 설정을 자동으로 감지합니다. pyproject.toml, requirements.txt, Pipfile, poetry.lock을 읽어 프로젝트 의존성을 이해합니다. 테스트나 스크립트를 실행할 때는 프로젝트 설정을 그대로 따릅니다. 가상 환경 활성화 명령과 테스트 러너를 CLAUDE.md 파일에 추가하면, Claude Code가 모든 작업에서 올바른 환경을 사용하게 됩니다.

네. Claude Code는 데이터 변환 파이프라인, pandas 연산, SQL 쿼리, 통계 분석 코드 작성에 강합니다. CSV 파일을 읽고 데이터 스키마를 이해하며 정제와 변환 로직을 작성하고 matplotlib이나 plotly로 시각화를 생성할 수 있습니다. 복잡한 데이터 파이프라인에서는 거대한 하나의 노트북 셀 대신 읽기 쉽고 테스트 가능한 함수들로 다단계 변환을 분해하는 데 도움을 줍니다.

원하는 동작을 설명하면서 함수에 대한 pytest 테스트를 작성해달라고 Claude Code에게 요청하세요. 기존 테스트 패턴, 픽스처, conftest.py를 읽어 당신의 스타일에 맞는 테스트를 생성합니다. TDD 워크플로를 사용해보세요. 먼저 동작을 설명하고, Claude Code가 테스트를 작성하게 한 다음, 그 테스트를 통과시키도록 코드를 구현하세요.

네. Claude Code는 함수를 추출하고, 여러 파일에 걸쳐 변수 이름을 바꾸고, 클래스를 dataclass로 변환하고, 타입 힌트를 추가하고, 모듈 구성을 재구조화하고, 오래된 코드를 현대화할 수 있습니다. 변경을 적용하기 전에 프로젝트 전체를 읽어 의존성을 이해하고, 리팩터링 후에는 테스트 스위트를 실행해 아무것도 깨지지 않았는지 확인합니다.