Help us improve
Share bugs, ideas, or general feedback.
From dev-tools
모던 Python 개발 컨벤션을 강제하는 스킬. uv(패키지 관리), ruff(린터/포매터), ty/pyright(타입 체커), typed Python 3.12+ 문법을 사용한다. Python 파일 생성, 프로젝트 초기화, pyproject.toml 수정, 의존성 추가, Python 코드 작성, FastAPI 서비스 구축 등 Python 관련 작업 시 반드시 이 스킬을 사용할 것. pip, poetry, conda, setup.py, requirements.txt 사용을 금지하고 uv로 대체한다.
npx claudepluginhub bahamoth/claude-marketplace --plugin dev-toolsHow this skill is triggered — by the user, by Claude, or both
Slash command
/dev-tools:python-devThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
이 스킬은 Astral 툴체인 중심의 모던 Python 개발을 강제한다. Claude가 기본적으로 제안하는 pip, poetry 등의 구식 도구 대신, uv/ruff/ty 기반의 최신 워크플로우를 사용한다.
Sets up Python projects with uv for deps/envs, ruff for linting/formatting, ty for types, pytest for testing. Use for new projects, scripts, or migrations from pip/Poetry.
Configures Python projects with modern tooling (uv, ruff, ty). Use when creating projects, writing standalone scripts, or migrating from pip/Poetry/mypy/black.
Sets up modern Python projects with uv package manager for fast dependencies, pyproject.toml config, virtual environments, ruff linting/formatting, src layout, and PyPI publishing.
Share bugs, ideas, or general feedback.
이 스킬은 Astral 툴체인 중심의 모던 Python 개발을 강제한다. Claude가 기본적으로 제안하는 pip, poetry 등의 구식 도구 대신, uv/ruff/ty 기반의 최신 워크플로우를 사용한다.
type 키워드, X | None 유니온, 소문자 제네릭(list[str]) 등.pyproject.toml에 통합한다. setup.py, setup.cfg, .flake8, .isort.cfg 등 개별 설정 파일을 만들지 않는다.이 도구들은 절대 사용하지 않는다. 대신 우측의 대체 도구를 사용한다.
| 금지 | 대체 | 이유 |
|---|---|---|
pip install | uv add | uv가 의존성 해결과 설치를 10배 이상 빠르게 수행 |
pip freeze > requirements.txt | uv.lock (자동 관리) | 락 파일이 재현 가능한 빌드를 보장 |
poetry | uv | uv가 poetry의 모든 기능을 더 빠르게 제공 |
conda | uv | uv가 Python 버전 관리까지 통합 |
setup.py / setup.cfg | pyproject.toml | PEP 621 표준, 모든 도구가 지원 |
requirements.txt | pyproject.toml + uv.lock | 선언적 의존성 + 결정적 락 파일 |
isort | ruff (I 규칙셋) | ruff가 isort 기능을 내장 |
flake8 / pylint | ruff | ruff가 대부분의 규칙을 통합 |
black (기본) | ruff format | ruff format이 black 호환 출력을 더 빠르게 제공. black은 ruff format이 부적절한 특수 경우에만 폴백으로 사용 |
virtualenv / venv | uv venv (자동) | uv가 가상환경을 자동 관리 |
uv init <project-name>
cd <project-name>
PyPI 배포 라이브러리이면서 C 확장, 데이터 파일 포함, 커스텀 빌드 훅이 필요한가?
YES → hatchling
NO → uv_build (기본값)
대부분의 프로젝트(웹 서비스, CLI 도구, 단순 라이브러리)는 uv_build를 사용한다. hatchling은 복잡한 빌드 요구사항이 있는 라이브러리에만 선택한다.
항상 src/ 레이아웃을 사용한다. 프로젝트 루트에서 패키지를 직접 import하는 실수를 방지한다.
project-name/
├── pyproject.toml
├── uv.lock
├── src/
│ └── package_name/
│ ├── __init__.py
│ ├── main.py
│ └── py.typed # PEP 561 — 타입 정보 제공 마커
├── tests/
│ ├── conftest.py
│ └── test_main.py
└── .python-version # uv가 자동 생성
pyproject.toml 전체 템플릿은
references/pyproject-templates.md를 참조하라.
Python 3.12+ 문법을 사용한다. 이전 버전 호환 문법을 사용하지 않는다.
list, dict, tuple, set은 소문자로 사용한다 (from typing import List 금지).X | None을 사용한다 (Optional[X] 금지).collections.abc의 Sequence, Mapping, Iterable을 사용한다 (typing에서 import 금지).type 키워드를 사용한다 (Python 3.12+).Any 사용 시 주석으로 이유를 명시한다.# BAD — 구식 타이핑, 리턴 타입 누락
from typing import Optional, List, Dict
def get_users(ids: Optional[List[int]] = None) -> Dict:
...
def process(data):
return data.strip()
# GOOD — 모던 3.12+ 타이핑
from collections.abc import Sequence
type UserMap = dict[int, "User"]
def get_users(ids: list[int] | None = None) -> UserMap:
...
def process(data: str) -> str:
return data.strip()
API 데이터 구조는 Pydantic BaseModel로 정의한다. 딕셔너리를 직접 반환하지 않는다.
from pydantic import BaseModel, Field
class CreateJobRequest(BaseModel):
model_config = {"strict": True}
file_id: str = Field(description="업로드된 파일의 ID")
presets: list[str] = Field(min_length=1, description="변환 프리셋 목록")
mode: str = Field(default="crop", pattern=r"^(crop|padding|blur|stretch)$")
프로젝트 복잡도에 따라 타입 체커를 선택한다.
단순 (단일 패키지, 적은 외부 의존성, 플러그인 불필요)
→ ty
설치: uv add --dev ty
실행: uv run ty check
중간 (FastAPI, SQLAlchemy, Pydantic, 다중 패키지)
→ pyright (strict mode)
설치: uv add --dev pyright
실행: uv run pyright
복잡 (모노레포, Django, 무거운 ORM, 다수의 타입 스텁 필요)
→ mypy (strict mode)
설치: uv add --dev mypy
실행: uv run mypy src/
ty는 Astral이 만든 신규 타입 체커로, 빠르고 가볍다. 아직 생태계 커버리지가 pyright/mypy보다 좁으므로 복잡한 프로젝트에서는 pyright를 권장한다.
각 타입 체커의 pyproject.toml 설정은
references/type-checking-guide.md를 참조하라.
ruff가 린터와 포매터를 모두 담당한다.
[tool.ruff.lint]
select = ["E", "F", "W", "I", "UP", "B", "SIM", "TCH", "RUF", "N", "S", "A", "C4", "DTZ", "T20", "PT", "RET", "ANN"]
| 규칙 | 역할 |
|---|---|
E/F/W | pycodestyle + pyflakes 기본 |
I | import 정렬 (isort 대체) |
UP | 모던 Python 문법 강제 (pyupgrade) |
B | 흔한 버그 패턴 감지 |
ANN | 타입 어노테이션 강제 |
TCH | TYPE_CHECKING 블록 최적화 |
T20 | print() 사용 금지 |
S | 보안 취약점 감지 |
uv run ruff check --fix . # 린트 + 자동 수정
uv run ruff format . # 포매팅
전체 ruff 설정과 per-file-ignores는
references/ruff-config.md를 참조하라.
# 의존성 추가
uv add fastapi uvicorn[standard]
# 개발 의존성 추가
uv add --dev pytest pytest-cov ruff pyright
# 의존성 제거
uv remove <package>
# 스크립트 실행 (가상환경 자동 활성화)
uv run python -m package_name
uv run pytest
uv run ruff check .
# Python 버전 고정
uv python pin 3.12
uv.lock은 uv가 자동으로 관리한다. 수동 편집하지 않는다.uv.lock은 반드시 git에 커밋한다 (재현 가능한 빌드 보장).requirements.txt를 생성하지 않는다. CI에서도 uv sync를 사용한다.# 테스트 실행
uv run pytest
# 커버리지 포함
uv run pytest --cov=src --cov-report=term-missing
# 특정 테스트
uv run pytest tests/test_main.py -k "test_create"
test_<module>.pytests/conftest.pyhttpx.AsyncClient 사용pytest-asyncio로 async 테스트 지원 (asyncio_mode = "auto")import pytest
from httpx import ASGITransport, AsyncClient
from package_name.main import app
@pytest.fixture
async def client() -> AsyncClient:
transport = ASGITransport(app=app)
async with AsyncClient(transport=transport, base_url="http://test") as ac:
yield ac
async def test_health(client: AsyncClient) -> None:
response = await client.get("/health")
assert response.status_code == 200
CLI가 필요한 경우 typer를 사용한다. argparse, click 대신 타입 어노테이션 기반으로 CLI를 선언적으로 정의한다.
uv add typer
import typer
app = typer.Typer()
@app.command()
def process(
input_file: str,
output_dir: str = "output",
verbose: bool = False,
) -> None:
"""파일을 처리한다."""
if verbose:
typer.echo(f"Processing {input_file}")
...
if __name__ == "__main__":
app()
코드를 커밋하기 전에 다음을 실행한다.
uv run ruff check --fix . # 린트
uv run ruff format . # 포맷
uv run pyright . # 타입 체크 (또는 ty check / mypy)
uv run pytest --cov=src # 테스트
모든 명령이 에러 없이 통과해야 한다.
필요할 때 다음 파일을 읽어 상세 설정을 확인하라.
| 파일 | 로드 시점 |
|---|---|
references/pyproject-templates.md | 프로젝트 초기화 또는 pyproject.toml 수정 시 |
references/ruff-config.md | ruff 설정 추가/변경 또는 규칙 문제 해결 시 |
references/type-checking-guide.md | 타입 체커 설정 또는 타입 에러 해결 시 |
references/fastapi-patterns.md | FastAPI 라우터, 모델, 서비스 작성 시 |