modern-python
작성자 trailofbitsmodern-python은 uv, ruff, ty를 사용해 Python 프로젝트를 구성합니다. 새 패키지, 독립 실행형 스크립트, 또는 pip, Poetry, mypy, black에서의 마이그레이션에 modern-python 스킬을 사용하세요. pyproject.toml, PEP 723 스크립트, dependency groups, 반복 가능한 프로젝트 설정까지 실무적으로 안내합니다.
이 스킬은 78/100점으로, 현대적인 Python 워크플로 가이드를 찾는 사용자에게 실용적인 가치가 있는 디렉터리 항목입니다. 트리거 조건이 비교적 분명해 올바르게 연결되기 쉽고, 워크플로 정보도 충분해 일반적인 프롬프트보다 에이전트가 덜 추측하고 작업할 수 있습니다. 다만 완전 자동 설치형 패키지라기보다, 참고 자료가 풍부한 설정용 스킬에 더 가깝습니다.
- 프론트매터와 사용 사례가 명확합니다. 새 프로젝트, pyproject 설정, 도구 구성, 스크립트 의존성, 마이그레이션이 모두 스킬 설명에 직접 드러납니다.
- 9개의 참고 파일과 템플릿이 뒷받침하는 충분한 워크플로 콘텐츠가 있으며, uv, ruff, ty, PEP 723 스크립트, Dependabot, 보안 설정, 마이그레이션 단계까지 구체적으로 다룹니다.
- 운영상 반패턴과 사용하지 말아야 할 경우를 안내해, 스킬 적용 여부를 판단하는 에이전트의 모호성을 줄여줍니다.
- SKILL.md에 설치 명령이 없으므로, 패키지화된 자동화 흐름을 실행하기보다 문서를 읽고 따라야 합니다.
- 내용이 최신 도구와 Python 3.11+에 맞춰져 있어, 레거시 도구를 쓰는 프로젝트나 오래된 인터프리터에는 잘 맞지 않습니다.
modern-python 스킬 개요
modern-python이 하는 일
modern-python 스킬은 pip, Poetry, mypy, black 같은 구형 조합 대신 uv, ruff, ty 중심으로 Python 프로젝트를 새로 시작하거나 현대화할 때 도움을 줍니다. 프로젝트 초기 설정, 스크립트 패키징, 마이그레이션 작업을 빠르고, 유지보수 부담이 적고, 반복 가능하게 정리해야 할 때 특히 유용합니다.
누가 사용해야 하나요
새 패키지를 작성하거나, CLI를 만들거나, 의존성이 있는 단일 스크립트를 작성하거나, 기존 repo를 현대적인 툴체인으로 옮기려는 경우에 modern-python 스킬을 사용하세요. Python 3.11+ 팀이 설치, linting, formatting, testing, 의존성 관리를 한 흐름으로 통일하고 싶을 때 잘 맞습니다.
일반적인 프롬프트와 다른 점
이 스킬은 단순히 “uv를 쓰자”는 수준이 아닙니다. pyproject.toml을 언제 써야 하는지, 언제 PEP 723 스크립트 메타데이터를 써야 하는지, 언제 uv.lock을 커밋해야 하는지, 또 언제 기존 워크플로우를 바꾸지 말아야 하는지에 대한 판단 규칙을 담고 있습니다. 그래서 modern-python 스킬은 막연한 선호가 아니라 구체적인 제약을 제공한다는 점에서 일반 프롬프트보다 훨씬 실용적입니다.
modern-python 스킬 사용법
설치하고 올바른 컨텍스트를 불러오기
디렉터리의 일반적인 skill 명령으로 modern-python 스킬을 설치한 뒤, 먼저 SKILL.md를 읽고 다음으로 references/pyproject.md, references/ruff-config.md, references/uv-commands.md를 읽으세요. 마이그레이션 작업이라면 변경을 시작하기 전에 references/migration-checklist.md와 references/testing.md도 함께 확인하세요.
스킬에 실제 프로젝트 형태를 알려주기
modern-python 사용은 아래 중 무엇을 다루는지 명확히 말할수록 더 잘 작동합니다.
- library, app, CLI 중 무엇인지
- 단일 파일 스크립트인지, 여러 파일로 이루어진 프로젝트인지
- 새 repo인지, 마이그레이션인지
- 당분간 legacy tools를 유지해야 하는 repo인지
좋은 요청 예시는 이렇게 쓸 수 있습니다: “이 repo를 uv, ruff, ty, uv_build를 사용하는 Python 3.12 package로 설정해 주세요. library 친화적으로 유지하고, dev dependency groups를 추가하고, Poetry는 쓰지 마세요.” 이것이 “modern Python best practices”라고만 묻는 것보다 훨씬 낫습니다. 스킬이 어떤 파일과 명령을 선택해야 하는지 더 정확히 판단할 수 있기 때문입니다.
신호가 가장 강한 파일부터 읽기
설치 중심 작업이라면 아래 경로를 다음 순서로 미리 보세요.
SKILL.mdreferences/pyproject.mdreferences/uv-commands.mdreferences/ruff-config.md- 작업이 스크립트라면
references/pep723-scripts.md - 작업이 전환이라면
references/migration-checklist.md
repo 스캐폴딩이나 CI 훅이 필요하다면 templates/dependabot.yml와 templates/pre-commit-config.yaml을 구현 기준점으로 확인하세요.
추측을 줄이는 입력을 주기
modern-python 스킬은 명시적인 제약이 있을수록 더 잘 동작합니다. Python 버전, 대상 package 이름, .venv/를 무시할지 여부, uv.lock을 커밋할지 여부, 반드시 써야 하는 도구를 알려 주세요. 마이그레이션 도움을 받고 싶다면 현재 스택과 반드시 유지해야 하는 요소도 함께 적어, 스킬이 불필요하게 워크플로우를 다시 짜지 않도록 하세요.
modern-python 스킬 FAQ
modern-python은 새 프로젝트에만 쓰는 건가요?
아닙니다. modern-python 스킬은 마이그레이션에도 쓰도록 설계되어 있지만, 그 경우에도 repo를 uv, ruff, ty 쪽으로 옮기고 싶을 때에만 적합합니다. 프로젝트가 현재 도구를 유지해야 한다면 이 스킬은 제한적으로 쓰거나, 아예 쓰지 않는 편이 맞습니다.
PEP 723는 언제 쓰고 pyproject.toml은 언제 쓰나요?
의존성이 있는 단일 파일 유틸리티라면 modern-python 스킬의 스크립트 경로를 사용하세요. 여러 파일이 있거나, 재사용 가능한 코드가 있거나, package boundary가 있다면 pyproject.toml을 사용하세요. 이 경계 판단이 바로 modern-python 스킬을 설치할 가치가 있는 핵심 이유 중 하나입니다.
일반적인 프롬프트를 대체하는 건가요?
반복 가능한 설정 판단이 필요하다면 그렇습니다. 일반 프롬프트도 도구를 설명할 수는 있지만, modern-python 스킬은 dependency management, linting, formatting, migration tradeoff에 대한 가이드를 제공하므로 모델이 서로 맞지 않는 패턴을 섞을 가능성이 훨씬 줄어듭니다.
초보 Python 사용자에게도 맞나요?
네, 깔끔한 현대식 스택이 목표라면 적합합니다. 다만 아직 오래된 툴링 관습을 배우는 중이거나 Python 3.11 미만을 써야 한다면 덜 적합합니다. 이 스킬은 modern-python 전제를 중심으로 구성되어 있기 때문입니다.
modern-python 스킬 개선 방법
가장 중요한 결과가 무엇인지 먼저 말하기
modern-python 결과를 더 좋게 만들려면 library packaging, script portability, CI readiness, migration safety 중 무엇이 가장 중요한지 먼저 알려 주세요. 그에 따라 결과가 달라집니다. library는 dependency discipline과 lockfile 가이드가 중요하고, 스크립트는 전체 project layout 대신 PEP 723 메타데이터가 더 적합할 수 있습니다.
빠진 프로젝트 정보를 미리 제공하기
가장 흔한 실패 원인은 설정 정보가 너무 적은 경우입니다. 아래 항목을 포함하세요.
- 목표 Python 버전
- package name과 import name
- flat layout 또는
src/layout uv.lock커밋 여부- 필요한 도구:
ruff,ty, tests, pre-commit, Dependabot
이 정보가 있어야 modern-python 스킬이 generic recommendation이 아니라 실제로 쓸 수 있는 install plan을 만들어낼 수 있습니다.
첫 초안을 repo 규칙과 대조하기
첫 결과를 받은 뒤에는 dependency groups, formatter 설정, test command가 repo의 기대와 맞는지 확인하세요. 어긋난 부분이 있으면 “legacy CI는 유지하되 linting과 dependency management만 modern-python 방식으로 바꿔 주세요”처럼 범위를 좁혀 수정하는 것이 좋습니다.
자주 어긋나는 경우를 주의하기
프로젝트가 pip/Poetry 의미를 유지해야 하거나, 오래된 interpreter를 지원해야 하거나, 반쯤 현대식이고 반쯤 legacy인 상태를 장기간 유지해야 한다면 modern-python은 상대적으로 약합니다. 그런 경우에는 스택을 전면 개편하기보다 보수적으로 적응하도록 요청하거나, 해당 repo에서는 이 스킬을 사용하지 않는 편이 낫습니다.