Community코딩 & 개발github.com

Python 스킬

변경 가능한 기본 인자, 늦은 바인딩 클로저, 얕은 복사, 삼켜진 예외 등 조용히 잘못된 동작을 유발하는 함정과 타입, 환경(uv/venv), 패키징, pytest 구조에 주의하여 Python 코드를 작성하고 디버깅합니다. Python 스크립트, 서비스, 라이브러리를 작성하거나 Python 프로젝트를 설정하거나 불가능해 보이는 동작을 디버깅할 때 사용하세요.

Python 스킬란 무엇인가요?

이 Python 스킬은 개발자가 조용히 실패하는 흔한 함정(변경 가능한 기본 인수, 늦은 바인딩 클로저, 얕은 복사, 삼켜진 예외, 정수 나눗셈 동작, 반복 중 컬렉션 변경, 일회용 생성기)을 피하고, 올바른 프로젝트 환경을 설정하는 데 도움을 줍니다. uv, venv 가상 환경, pyproject.toml 기반 의존성 관리, 잠금 파일, Python 버전 고정을 다룹니다. 또한 함수 시그니처에 타입 애너테이션을 추가하고, dataclass나 검증 모델을 사용하며, Any 대신 `object`를 사용해 타입 검사를 강제하는 방법을 가르칩니다. 파이썬다운 관용구(comprehension, pathlib.Path, 컨텍스트 관리자, enumerate/zip/dict.get)와 pytest 구조(매개변수화된 테스트, 픽스처, 특정 예외 검증), 성능 최적화(내장 함수, set/dict 조회, asyncio/프로세스)도 다룹니다. Claude Code, Cursor, Codex 등 모든 주요 AI 에이전트 플랫폼에서 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-python

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Python

Python은 쓰기는 쉽지만 미묘하게 잘못되기 쉽습니다. 이 문서는 조용히 실패하는 함정과 깨진 환경을 피하는 프로젝트 설정을 다룹니다.

조용히 실패하는 함정

변경 가능한 기본 인수는 정의 시 한 번 평가되며 모든 호출에서 공유됩니다:

def add(item, bucket=[]):   # 틀림: bucket이 호출 간에 유지됨
def add(item, bucket=None): # 맞음
    bucket = [] if bucket is None else bucket

클로저는 늦게 바인딩됩니다. 루프 안에서 생성된 람다는 값이 아닌 변수를 캡처하므로, 모든 람다가 최종 값을 봅니다. 기본 인수로 명시적으로 바인딩하거나 functools.partial을 사용하세요.

is는 항등(identity)이지 동등(equality)이 아닙니다. None, True, False에는 동작하지만 다른 것에는 사용하지 마세요. 작은 정수나 짧은 문자열에서는 인턴(intern)되므로 동작하는 것처럼 보이지만, 이 때문에 버그가 테스트를 통과합니다.

복사는 얕습니다. list(xs), xs[:], dict(d)는 컨테이너를 복사하고 요소는 공유합니다. 중첩 구조는 copy.deepcopy가 필요합니다.

순수 except:는 모든 것을 잡습니다. KeyboardInterrupt와 SystemExit까지도 잡습니다. 특정 예외를 잡고, 절대 except Exception: pass라고 쓰지 마세요. 정말 무시해도 되는 예외라면 로그를 남기고 이유를 설명하세요.

정수 나눗셈과 부동소수점 동등 비교. /는 항상 float을 생성합니다. //는 음의 무한대 방향으로 내림합니다. 따라서 -7 // 2는 -4입니다. float을 ==로 비교하지 말고 math.isclose를 사용하거나 금액에는 Decimal을 사용하세요.

컬렉션을 변경하면서 반복하면 요소가 건너뜁니다. 새 리스트를 만들거나 복사본을 반복하세요.

제너레이터는 한 번만 소비됩니다. 같은 제너레이터를 두 번 순회하면 아무것도 생성되지 않으며, 오류 대신 빈 결과로 보입니다.

환경과 패키징

시스템 인터프리터에 설치하지 마세요. 프로젝트별로 가상 환경을 만들고 활성화하거나 uv가 관리하게 하세요:

uv venv && uv pip install -e ".[dev]"     # 또는: python -m venv .venv

의존성은 pyproject.toml에 선언하고 잠금 파일을 커밋하여 환경을 재현 가능하게 만드세요. 버전이 고정되지 않은 requirements.txt는 재현 가능하지 않으며 미래의 머신에서 깨집니다.

프로젝트가 지원하는 Python 버전을 고정하고 pyproject.toml에 명시하세요. 동작은 부 버전(micro version) 간에도 예상보다 많이 다릅니다.

어떤 모듈이 어떤 곳에서는 임포트되고 다른 곳에서는 안 될 때, 원인은 거의 항상 코드가 아니라 인터프리터입니다. 임포트를 디버깅하기 전에 which python과 python -c "import sys; print(sys.executable)"을 확인하세요.

타입

함수 시그니처(매개변수와 반환값)에 애너테이션을 추가하세요. 본문에는 애너테이션이 거의 필요 없지만 경계에는 항상 필요합니다. 다른 코드가 그 경계에 의존하기 때문입니다.

CI에서 타입 검사기를 실행하세요. 어떤 것도 검증하지 않는 애너테이션은 시간이 지나면서 낡아져 오해를 불러일으키는 문서가 됩니다.

관례상의 옵셔널(optional-by-convention) 대신 X | None을 사용하고, 시그니처에서 옵셔널임을 명확히 드러내세요. Any보다는 구체적인 타입을 선호하고, 타입이 진정으로 알 수 없을 때는 unknown의 동등한 표현인 object를 사용하고 좁혀(narrow)서 검사기가 좁히기를 강제하게 하세요.

구조화된 데이터에는 dataclass를 선호하거나, 외부에서 데이터가 들어오는 경계에서 검증 모델을 사용하세요. 함수 사이에 전달되는 문자열 딕셔너리는 첫 번째 오타에서 모든 보장을 잃습니다.

중요한 관용구

매핑(mapping)이나 필터링(filtering)을 할 때는 컴프리헨션을 사용하고, 그 외의 작업은 루프를 사용하세요. 부작용이 있거나 절이 세 개인 컴프리헨션은 대체한 루프보다 읽기 어렵습니다.

문자열 경로 대신 pathlib.Path를 사용하고, 닫아야 하는 것(파일, 연결, 잠금, 임시 디렉터리)에는 컨텍스트 관리자를 사용하세요.

입력이 크거나 무한할 때는 리스트를 만드는 대신 제너레이터에서 생성(yield)하세요. 이것이 스트리밍하는 스크립트와 메모리를 고갈시키는 스크립트의 차이입니다.

인덱스 산술과 멤버십 검사 대신 enumerate, zip, 기본값이 있는 dict.get을 사용하세요. 더 빠르고 off-by-one 오류를 없애줍니다.

테스트

pytest를 사용하고 일반 assert를 쓰세요. 하나의 테스트 안에서 루프를 쓰는 대신 @pytest.mark.parametrize를 사용하여 테이블 기반 케이스를 처리하면 각 케이스가 별도로 보고됩니다.

공유 설정은 가장 좁은 범위의 픽스처에 넣으세요. 세션 범위 픽스처가 변경 가능한 상태를 보유하면 테스트 간에 누수가 발생하여 순서 의존적 실패를 만듭니다.

특정 예외는 pytest.raises로 단언하고, 중요할 때는 메시지도 포함하세요.

성능, 중요할 때

최적화하기 전에 측정하세요. 대략적인 숫자는 time.perf_counter, 어디서 시간이 가는지는 cProfile을 사용하세요.

일반적인 개선 방법은 작업을 인터프리터 밖으로 옮기는 것입니다: 내장 함수, 컴프리헨션, 반복적인 연결 대신 str.join, 리스트 스캔 대신 set이나 dict 조회, 또는 수치 작업을 위한 벡터화된 라이브러리 호출.

I/O 바운드 동시성에는 asyncio나 스레드를 사용하고, CPU 바운드 작업에는 프로세스를 사용하세요. 전역 인터프리터 잠금(GIL) 때문에 스레드는 도움이 되지 않습니다.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

관련 스킬