Python dengan Claude Code: panduan uv, pytest, Ruff, dan FastAPI

Saat memakai Claude Code untuk Python, masalah pertama biasanya bukan membuat file. Masalah yang lebih penting adalah memastikan proyek benar-benar sehat: environment bisa dibuat ulang, import tidak rusak, test berjalan, format konsisten, dan perubahan berikutnya bisa diperiksa dengan jelas.

Panduan ini membuat fondasi kecil untuk pemula. Kita akan memakai uv atau venv, menyimpan konfigurasi di pyproject.toml, membuat API kecil dengan FastAPI, menambahkan CLI opsional, menulis test dengan pytest, dan mengecek kode dengan ruff. Claude Code akan jauh lebih berguna ketika bekerja dalam batas yang jelas.

Gunakan dokumentasi resmi sebagai sumber utama: Claude Code, panduan Python untuk pyproject.toml, instalasi uv, pytest, Ruff, dan FastAPI first steps.

Tentukan target kecil dulu

Jangan langsung meminta autentikasi, database, Docker, CI, dan background job. Untuk pemula, target pertama harus mudah dibuktikan.

• uv run pytest berhasil
• uv run ruff check . dan uv run ruff format . berjalan
• FastAPI bisa membuat dan menampilkan satu task
• CLI bisa menambahkan task dari terminal
• Claude Code melaporkan command yang dijalankan

flowchart LR
  A["Brief tugas"] --> B["uv atau venv"]
  B --> C["pyproject.toml"]
  C --> D["Implementasi di src"]
  D --> E["pytest"]
  E --> F["ruff"]
  F --> G["Iterasi kecil dengan Claude Code"]

Brief tugas adalah batas kerja untuk coding agent. Tulis tujuan, file yang boleh disentuh, versi Python, dan command verifikasi. Untuk aturan repo yang lebih permanen, pakai juga praktik CLAUDE.md. Saat API mulai besar, lanjutkan dengan pengembangan API Claude Code dan strategi testing.

Prompt awal untuk Claude Code

Prompt berikut cukup praktis untuk tugas pertama.

Tambahkan API manajemen task kecil untuk Python 3.12 di repository ini.

Syarat:
- Gunakan uv untuk dependency dan simpan konfigurasi di pyproject.toml.
- Letakkan implementasi di src/task_api/ dan test di tests/.
- Implementasikan POST /tasks dan GET /tasks dengan FastAPI.
- Tulis pytest untuk jalur sukses dan satu kasus 404.
- ruff check dan ruff format harus lolos.
- Sebelum edit, tampilkan rencana. Setelah edit, laporkan command yang dijalankan.

File yang boleh diubah:
- pyproject.toml
- src/task_api/**
- tests/**

Dengan prompt seperti ini, Claude Code tidak bebas mengubah semua hal. Jika diff menyentuh folder lain atau tidak menjalankan test, masalahnya langsung terlihat saat review.

Buat environment dengan uv atau venv

Untuk proyek baru, uv nyaman karena cepat dan command-nya pendek. Jika laptop kantor tidak mengizinkan tool baru, venv bawaan Python tetap cukup. Yang penting, pilih satu jalur dan jangan campur.

macOS atau Linux:

mkdir task-api
cd task-api
uv init --app --python 3.12
uv add "fastapi[standard]"
uv add --dev pytest ruff
mkdir -p src/task_api tests
touch src/task_api/__init__.py

Windows PowerShell:

mkdir task-api
cd task-api
uv init --app --python 3.12
uv add "fastapi[standard]"
uv add --dev pytest ruff
New-Item -ItemType Directory -Force src/task_api, tests
New-Item -ItemType File -Force src/task_api/__init__.py

Alternatif venv:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "fastapi[standard]" pytest ruff

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install "fastapi[standard]" pytest ruff

Simpan konfigurasi di pyproject.toml

Pemula sering bingung ketika dependency, test, dan lint tersebar di banyak file. Untuk starter kecil, satukan aturan penting di pyproject.toml.

[project]
name = "task-api"
version = "0.1.0"
description = "Small FastAPI and CLI sample for Claude Code practice"
requires-python = ">=3.11"
dependencies = [
  "fastapi[standard]>=0.115.0",
]

[project.scripts]
task-api = "task_api.cli:main"

[dependency-groups]
dev = [
  "pytest>=8.0.0",
  "ruff>=0.8.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/task_api"]

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP"]

Implementasi FastAPI dan CLI

Simpan kode ini sebagai src/task_api/main.py. Data disimpan di memory, jadi ini bukan desain produksi. Justru itu cocok untuk belajar routing, validasi, model respons, dan error handling.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI(title="Task API")


class TaskCreate(BaseModel):
    title: str = Field(min_length=1, max_length=80)


class Task(BaseModel):
    id: int
    title: str
    done: bool = False


_tasks: dict[int, Task] = {}
_next_id = 1


@app.post("/tasks", response_model=Task, status_code=201)
def create_task(payload: TaskCreate) -> Task:
    global _next_id
    task = Task(id=_next_id, title=payload.title)
    _tasks[task.id] = task
    _next_id += 1
    return task


@app.get("/tasks", response_model=list[Task])
def list_tasks() -> list[Task]:
    return list(_tasks.values())


@app.patch("/tasks/{task_id}/done", response_model=Task)
def mark_done(task_id: int) -> Task:
    task = _tasks.get(task_id)
    if task is None:
        raise HTTPException(status_code=404, detail="Task not found")
    updated = task.model_copy(update={"done": True})
    _tasks[task_id] = updated
    return updated

uv run fastapi dev src/task_api/main.py

Untuk CLI, buat src/task_api/cli.py.

import argparse
import json
from pathlib import Path

DB_PATH = Path("tasks.json")


def load_tasks() -> list[dict[str, object]]:
    if not DB_PATH.exists():
        return []
    return json.loads(DB_PATH.read_text(encoding="utf-8"))


def save_tasks(tasks: list[dict[str, object]]) -> None:
    DB_PATH.write_text(json.dumps(tasks, ensure_ascii=False, indent=2), encoding="utf-8")


def add_task(title: str) -> dict[str, object]:
    tasks = load_tasks()
    task = {"id": len(tasks) + 1, "title": title, "done": False}
    tasks.append(task)
    save_tasks(tasks)
    return task


def main() -> None:
    parser = argparse.ArgumentParser(description="Task CLI")
    subparsers = parser.add_subparsers(dest="command", required=True)
    add_parser = subparsers.add_parser("add")
    add_parser.add_argument("title")
    args = parser.parse_args()
    if args.command == "add":
        task = add_task(args.title)
        print(f"Added #{task['id']}: {task['title']}")


if __name__ == "__main__":
    main()

uv run task-api add "write pytest"

Amankan iterasi dengan pytest dan Ruff

Buat tests/test_main.py. Setelah itu, setiap perubahan dari Claude Code harus melewati command yang sama.

import pytest
from fastapi.testclient import TestClient

from task_api import main
from task_api.main import app


@pytest.fixture(autouse=True)
def clean_tasks() -> None:
    main._tasks.clear()
    main._next_id = 1


def test_create_and_list_tasks() -> None:
    client = TestClient(app)
    response = client.post("/tasks", json={"title": "Write pytest"})
    assert response.status_code == 201
    assert response.json()["title"] == "Write pytest"
    list_response = client.get("/tasks")
    assert list_response.status_code == 200
    assert len(list_response.json()) == 1


def test_mark_done_returns_404_for_missing_task() -> None:
    client = TestClient(app)
    response = client.patch("/tasks/999/done")
    assert response.status_code == 404
    assert response.json()["detail"] == "Task not found"

uv run pytest
uv run ruff check .
uv run ruff format .

Use case nyata

Use case pertama adalah API belajar: routing, Pydantic, dokumentasi OpenAPI, test, dan format terlihat dalam satu proyek kecil. Use case kedua adalah CLI otomasi bisnis, misalnya membersihkan CSV, mengganti nama file ekspor, atau membuat laporan mingguan. Use case ketiga adalah menambah test pada script Python lama sebelum refactor. Use case keempat adalah template pelatihan tim agar semua orang mulai dari struktur yang sama.

Untuk individu, produk Claude Code membantu mengulang brief dan review. Untuk tim dengan repo nyata, onboarding, dan risiko produksi, training dan konsultasi lebih tepat.

Kesalahan umum

Jangan biarkan package manager tidak jelas, karena pip, poetry, uv, dan requirements.txt bisa tercampur. Jangan menambah database dan JWT sebelum versi memory berjalan. Periksa diff Ruff sebelum menerima auto-fix. Pastikan pythonpath = ["src"] atau instalasi paket benar. Jangan pernah menempelkan secret, data pelanggan, atau URL produksi ke prompt.

Hasil verifikasi

Untuk pembaruan ini, saya mengikuti urutan yang Masa gunakan untuk materi Python pemula: environment dulu, pyproject.toml, FastAPI kecil, test, lalu Ruff. Hasilnya, setiap kegagalan bisa dilokalkan ke environment, import, perilaku test, atau format. Itulah yang membuat Claude Code berguna untuk belajar, pelatihan, dan perbaikan repository nyata.