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-toolsThis skill uses the workspace's default tool permissions.
이 스킬은 Astral 툴체인 중심의 모던 Python 개발을 강제한다. Claude가 기본적으로 제안하는 pip, poetry 등의 구식 도구 대신, uv/ruff/ty 기반의 최신 워크플로우를 사용한다.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides MCP server integration in Claude Code plugins via .mcp.json or plugin.json configs for stdio, SSE, HTTP types, enabling external services as tools.
이 스킬은 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 라우터, 모델, 서비스 작성 시 |