AI 시대의 Python 컨벤션 — Ruff·Pre-commit·CLAUDE.md로 코드 멱등성 잡기

pip install ruff
# 또는
uv add --dev ruff

# 검사
ruff check .
 
# 자동 수정 가능한 건 고침
ruff check --fix .
 
# 포맷팅 (Black 대체)
ruff format .
 
# 포맷이 맞는지만 확인 (CI용)
ruff format --check .

[tool.ruff]
line-length = 100
target-version = "py312"
 
[tool.ruff.lint]
select = [
  "E",    # pycodestyle errors
  "W",    # pycodestyle warnings
  "F",    # pyflakes
  "I",    # isort
  "N",    # pep8-naming
  "UP",   # pyupgrade
  "B",    # flake8-bugbear
  "SIM",  # flake8-simplify
  "RUF",  # ruff-specific
]
ignore = [
  "E501",  # line too long (formatter가 처리)
]
 
[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"]  # tests에선 assert 허용
 
[tool.ruff.format]
quote-style = "double"
indent-style = "space"

pip install pre-commit

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.5.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
 
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

# 한 번 설치 (.git/hooks/에 hook 배치)
pre-commit install
 
# 전체 파일에 한 번 돌리기 (도입 시점)
pre-commit run --all-files

pip install mypy

[tool.mypy]
python_version = "3.12"
strict = true
plugins = ["pydantic.mypy"]
 
[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

[tool.pytest.ini_options]
minversion = "8.0"
addopts = [
  "--cov=src",
  "--cov-report=term-missing",
  "--cov-fail-under=85",
]
 
[tool.coverage.run]
branch = true
source = ["src"]

# 프로젝트 가이드라인
 
## 기술 스택
- Python 3.12
- FastAPI, Pydantic v2, SQLAlchemy 2.x
- 패키지 매니저: uv
 
## 코드 컨벤션
- snake_case 함수/변수, PascalCase 클래스
- 모든 public 함수에 타입 힌트 필수
- docstring은 Google style
- 테스트는 `tests/` 아래, 함수명 `test_`로 시작
 
## 금지 패턴
- `from x import *` 금지
- `print()`로 디버깅 — `logger`만 사용
- 빈 `except:` — 항상 구체적 예외
 
## 아키텍처
- src/api/ — FastAPI 라우터
- src/services/ — 비즈니스 로직
- src/repositories/ — DB 접근
- 라우터 → 서비스 → 리포지토리 (단방향)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "ruff check --fix $CLAUDE_FILE_PATHS && ruff format $CLAUDE_FILE_PATHS"
          }
        ]
      }
    ]
  }
}

name: CI
on:
  pull_request:
  push:
    branches: [main]
 
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv sync --dev
 
      - name: Lint
        run: uv run ruff check .
 
      - name: Format check
        run: uv run ruff format --check .
 
      - name: Type check
        run: uv run mypy src/
 
      - name: Test
        run: uv run pytest --cov=src --cov-fail-under=85

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["fastapi>=0.110", "pydantic>=2.6"]
 
[project.optional-dependencies]
dev = ["ruff>=0.5", "mypy>=1.10", "pytest>=8.0", "pytest-cov>=5.0"]
 
[tool.ruff]
line-length = 100
target-version = "py312"
 
[tool.ruff.lint]
select = ["E", "W", "F", "I", "N", "UP", "B", "SIM", "RUF"]
 
[tool.mypy]
strict = true
python_version = "3.12"
 
[tool.pytest.ini_options]
addopts = ["--cov=src", "--cov-fail-under=85"]