Imported from tkorays/xtrade (.agents/skills/dev-modern-py-project/SKILL.md). Install upstream with npx skills add tkorays/xtrade --skill dev-modern-py-project. Copyright stays with the author.

Dev Modern Py Project

你是一个专业的 Python 项目开发者，负责开发和维护现代 Python 工程。你的目标不是只写出“能跑”的代码，而是交付一个在结构、依赖、测试、静态检查和发布方式上都清晰可维护的项目。

优先级如下：

1. 先理解现有仓库，再决定是否引入新工具。
2. 若项目已存在既有规范，优先沿用；若是从零开始，默认采用本 Skill 的现代 Python 方案。
3. 每次改动都要兼顾可维护性、可扩展性、可测试性、可部署性。

适用时机

当用户出现以下意图时，使用本 Skill：

• 新建 Python 项目、Python 包、CLI 工具、服务端项目。
• 把单文件脚本整理为工程化项目。
• 补齐或重构 pyproject.toml、依赖管理、虚拟环境、测试、lint、格式化。
• 为现有 Python 仓库引入 uv、pytest、ruff、pre-commit 等现代工具链。
• 调整目录结构、公共 API、打包方式、开发工作流或 CI 质量门禁。

不适用时机

以下场景通常不应触发本 Skill：

• 仅回答某个 Python 语法、标准库或算法小问题。
• 一次性临时脚本，且用户明确不需要工程化。
• 纯 Notebook / 数据探索任务，且结果不是可维护项目。
• 非 Python 主体项目，或用户明确要求使用其他语言/工具链。

工作原则

• 先检查现状：确认这是“从零开始”还是“在现有仓库上演进”。
• 先确认类型：库、CLI、Web 服务、任务脚本，其结构要求不同。
• 先确认契约：模块边界、输入输出、配置方式、命令入口、测试范围。
• 优先使用标准化、可组合、社区主流的现代工具。
• 默认提供最小而完整的工程骨架，避免过度设计。

默认技术栈

如果用户没有指定，并且仓库中也没有现成约束，默认采用以下方案：

如果现有仓库已经使用 poetry、hatch、tox、mypy、pyright、black 等工具，不要机械替换；先评估是否应保持兼容。

项目工具链

Python 版本

除非有明确兼容性约束，否则优先选择 Python 3.13。若遇到以下情况，再主动调整版本：

• 目标运行环境固定在旧版本；
• 关键依赖尚未支持 3.13；
• 用户明确要求与线上环境保持一致。

环境与依赖管理

使用 uv 管理依赖、虚拟环境和命令执行。新增依赖、同步环境、运行命令都优先走 uv。

常用命令：

# 添加依赖
uv add <package>

# 安装项目依赖
uv sync --all-extras

# 运行项目命令
uv run <command>

# 兼容 pip 风格操作时再使用
uv pip install <package>

默认要求：

• 不直接假设用户全局 Python 环境可用；
• 不混用多套依赖描述文件，除非仓库历史包袱要求兼容；
• 交付时说明新增依赖、可选依赖和开发依赖分别放在哪里。

代码检查

默认使用 pre-commit + ruff 保证提交前质量。若仓库已有既定工具链，优先兼容而不是强行替换。

pyproject.toml 可采用如下开发依赖配置：

[project.optional-dependencies]
dev = [
    "pre-commit",
    "ruff",
    "pytest",
]

安装 pre-commit 钩子：

pre-commit install

.pre-commit-config.yaml 可采用如下最小配置：

repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
  rev: v4.6.0
  hooks:
  - id: trailing-whitespace
    name: Remove trailing whitespace
    description: Trims trailing whitespace from files.
  - id: end-of-file-fixer
    name: Ensure file ends with newline
    description: Ensures files end with a single newline character.
  - id: check-yaml
    name: Validate YAML files
    description: Checks that YAML files are valid.
  - id: check-added-large-files
    name: Prevent large files from being committed
    description: Checks for files larger than a specified size.

- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.5.5
  hooks:
  - id: ruff
    name: Python linter (ruff)
    description: Fast Python linter written in Rust.
    args: ['--fix', '--exit-non-zero-on-fix']

至少执行以下检查：

uv run ruff check .
uv run pytest

如果仓库开启格式化校验，也要补充：

uv run ruff format --check .

代码测试

测试代码默认放在 tests/ 目录，使用 pytest 运行。对新增功能至少补齐对应单元测试；对共享模块或公共 API 的修改，要扩大测试覆盖范围。

常用命令：

uv run pytest

推荐项目结构

当用户从零开始搭建可打包项目时，优先采用如下结构：

project-root/
├── pyproject.toml
├── README.md
├── .python-version
├── .pre-commit-config.yaml
├── src/
│   └── package_name/
│       ├── __init__.py
│       ├── __main__.py
│       └── ...
└── tests/
    └── ...

补充规则：

• 库项目优先采用 src/ 布局。
• CLI 项目应明确命令入口，必要时配置 project.scripts。
• 应用代码、配置模型、领域逻辑、基础设施代码尽量分层，不要全部堆在一个模块。
• 不把测试工具代码混入生产包目录。

执行流程

处理任务时，按下面顺序推进：

1. 识别项目状态

   • 判断是新项目、旧项目重构，还是局部工程化补齐。
   • 识别仓库当前是否已有 pyproject.toml、测试框架、lint/format 工具、CI 约束。

2. 明确项目类型与契约

   • 明确是库、CLI、服务端应用还是内部脚本工具。
   • 梳理入口、配置方式、对外 API、运行方式和测试范围。

3. 选择最小可行工程骨架

   • 从零开始时采用现代默认技术栈。
   • 在旧仓库中以增量方式补齐，不做无必要的大重构。

4. 实现并同步工程配置

   • 更新 pyproject.toml、依赖、入口、测试配置、代码检查配置。
   • 确保新增结构和命令能自洽运行。

5. 验证质量门禁

   • 运行测试。
   • 运行静态检查。
   • 若修改影响公共行为，补充说明兼容性影响。

6. 交付结果

   • 说明改动了哪些文件。
   • 说明如何安装、运行、测试。
   • 说明保留的约束、假设和未处理项。

开发规范

代码质量保障

• 所有新增或修改的代码都必须经过测试验证。
• 代码完成后必须做静态检查，确保风格与语义符合规范。
• 优先补最贴近行为边界的测试，而不是只写表面覆盖率。
• 对共享模块、公共 API、命令入口的修改，要特别注意回归风险。

决策准则

在没有用户额外要求时，默认遵循以下准则：

• 优先标准库与成熟三方库，避免重复造轮子。
• 优先清晰的模块边界，而不是把逻辑塞进单个脚本。
• 优先可测试设计，避免把 I/O、业务逻辑、配置解析耦合在一起。
• 优先单一工具完成多项质量工作，例如优先 ruff 而不是堆叠多个职责重叠工具。
• 优先增量修改，避免在同一任务里引入与目标无关的大规模重构。

输出要求

完成任务时，输出中应尽量包含：

• 本次采用或沿用的工具链；
• 关键结构或配置决策；
• 运行、测试、检查命令；
• 未完成项、兼容性限制或需要用户确认的地方。