К основному содержанию
правило CX Codex

python-script — правило для Claude Code: что делает и как установить

Правило python-script задаёт стандарты написания утилит автоматизации на Python 3.11+ для Claude Code: управление пакетами через uv, строгие типы и единая структура CLI.

MIT ★ 1 627 обновлён 2026-10-25

Установить в GitHub Copilot · Вручную: положить файлы Все способы и платформы ↓
.github/instructions/python-script.instructions.md
Открыть на GitHub

Что делает python-script

Правило настраивает Claude Code на генерацию скриптов по инженерным стандартам Microsoft. В проектах запрещается прямой вызов pip install: любые зависимости ставятся через uv add, а запуск кода разрешён только внутри виртуального окружения через uv run. Это сразу отсекает проблемы с несовместимостью системных пакетов.

Вместо устаревшего модуля os.path агент обязуется применять pathlib.Path. Для парсинга аргументов командной строки предписано выносить сборку парсера argparse в отдельную функцию либо использовать click при наличии подкоманд. Модель применяет современный синтаксис типов Python 3.11 без устаревших конструкций из typing вроде Union или Optional.

Для перехвата ошибок внедряются фиксированные коды возврата: 0 при успехе, 1 при общей ошибке, 2 при сбое конфигурации и 130 при прерывании процесса. В скриптах без виртуального окружения .venv в корне проект не запустится.

Какие задачи решает

  • запретить прямое использование pip и перевести окружение на uv
  • структурировать обработку аргументов CLI через argparse или click
  • заменить вызовы os.path на методы pathlib.Path
  • внедрить стандартные коды возврата и обработку KeyboardInterrupt

Примеры запросов агенту

  • Напиши CLI-скрипт для пакетной обработки файлов с аргументами через argparse
  • Перепиши скрипт автоматизации под требования python-script с типами Python 3.11
  • Сделай консольную утилиту с подкомандами на click и логированием в файл

Как установить python-script

Вручную: положить файлы

.github/instructions/python-script.instructions.md

Поле applyTo задаёт, к каким файлам применять

По шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать

Вопросы о python-script

Как установить python-script в Claude Code?

Сохраните текст правила в файл .claude/rules/python-script.md в корне вашего проекта. Claude Code автоматически применит инструкции ко всем файлам по маске **/*.py.

Что делает правило python-script?

Оно фиксирует стандарты разработки сценариев автоматизации на Python 3.11+. Агент пишет код с использованием uv, pathlib, явных кодов выхода и Google-формата docstring.

Какие менеджеры пакетов разрешает использовать это правило?

Инструкция строго запрещает вызывать pip install напрямую. Все зависимости устанавливаются и запускаются исключительно через инструмент uv.

Исходный текст

python-script.instructions.md · MIT
---
applyTo: '**/*.py'
description: 'Python scripting conventions'
---

# Python Script Instructions

Conventions for Python 3.11+ scripts used in automation, tooling, and CLI applications.

## Environment and Dependency Management

1. **Never use `pip install` directly.** All package management must be handled using `uv` (e.g., `uv add <package>`).
2. **Never run Python scripts or tools outside a virtual environment.** Always execute scripts via `uv run <script.py>` or ensure the 
`.venv` is activated before running.
3. Ensure a `.venv` exists in the project root before executing any Python code. If starting from scratch, refer to the `uv-projects.instructions.md` file for environment setup.

## Entry Points and Exit Codes

```python
import sys

EXIT_SUCCESS = 0  # Successful execution
EXIT_FAILURE = 1  # General failure
EXIT_ERROR = 2    # Arguments or configuration error


def main() -> int:
    """Main entry point for the script."""
    return EXIT_SUCCESS


if __name__ == "__main__":
    sys.exit(main())
```

Standard exit codes: 0 success, 1 failure, 2 configuration error, 130 user interrupt (SIGINT).

## CLI Argument Parsing

### argparse

Extract parser creation into a separate function for testability.

```python
import argparse
from pathlib import Path


def create_parser() -> argparse.ArgumentParser:
    """Create and configure argument parser."""
    parser = argparse.ArgumentParser(description="Process files")
    parser.add_argument("-v", "--verbose", action="store_true")
    parser.add_argument("-o", "--output", type=Path, default=Path("output.txt"))
    parser.add_argument("input_file", type=Path)
    return parser
```

Use `type=Path` for file arguments and `action="store_true"` for boolean flags.

### click

For complex CLIs with subcommands or interactive prompts, use the *click* framework.

```python
import click


@click.command()
@click.option("-v", "--verbose", is_flag=True)
@click.argument("input_file", type=click.Path(exists=True))
@click.pass_context
def main(ctx: click.Context, verbose: bool, input_file: str) -> None:
    """Process input files."""
    ctx.exit(0)  # Explicit exit code
```

Use `@click.group()` for subcommands, `ctx.exit(code)` for exit codes, and `ctx.fail(message)` for errors.

## Logging Configuration

```python
import logging

logger = logging.getLogger(__name__)


def configure_logging(verbose: bool = False) -> None:
    """Configure logging based on verbosity level."""
    level = logging.DEBUG if verbose else logging.INFO
    logging.basicConfig(level=level, format="%(levelname)s: %(message)s")
```

Create module-level logger, configure early in main. For file logging, add *FileHandler* to the root logger.

## Path Handling

Use *pathlib.Path* exclusively; avoid *os.path*.

```python
from pathlib import Path


def process_file(path: Path) -> None:
    """Read, process, and write file content."""
    content = path.read_text(encoding="utf-8")
    processed = transform_content(content)
    output_path = path.with_suffix(".out")
    output_path.parent.mkdir(parents=True, exist_ok=True)
    output_path.write_text(processed, encoding="utf-8")
```

Common patterns: `cwd()`, `resolve()`, `exists()`, `is_dir()`, `is_file()`, `iterdir()`, `glob()`, `rglob()`, `read_text()`, `write_text()`, `mkdir(parents=True, exist_ok=True)`, `parent`, `name`, `stem`, `suffix`.

## Subprocess Execution

Use *subprocess.run()* with error handling.

```python
import subprocess
import os
from pathlib import Path


def run_command(cmd: list[str], cwd: Path | None = None, extra_env: dict[str, str] | None = None) -> str:
    """Run command and return stdout, raising on failure."""
    env = os.environ.copy()
    if extra_env:
        env.update(extra_env)
    try:
        result = subprocess.run(cmd, capture_output=True, text=True, check=True, cwd=cwd, env=env)
        return result.stdout
    except subprocess.CalledProcessError as e:
        logger.error("Command failed: %s\nstderr: %s", e.returncode, e.stderr)
        raise
    except FileNotFoundError:
        logger.error("Command not found: %s", cmd[0])
        raise
```

Use `capture_output=True` and `text=True` for string output. Use `check=True` to raise on non-zero exit.

## Type Hints

Use Python 3.11+ syntax with built-in generics.

```python
from pathlib import Path
from typing import Literal, Self


def process_items(items: list[str]) -> dict[str, int]:  # Built-in generics
    return {item: len(item) for item in items}


def read_file(path: str | Path) -> str:  # Union with pipe
    return Path(path).read_text(encoding="utf-8")


def find_config(name: str) -> Path | None:  # Optional with pipe
    config = Path(name)
    return config if config.exists() else None


def set_level(level: Literal["debug", "info", "warning"]) -> None:  # Constrained values
    pass


class Builder:
    def add(self, item: str) -> Self:  # Fluent interface
        self.items.append(item)
        return self
```

Use `list[str]` not `typing.List[str]`, `str | None` not `Optional[str]`, `Literal` for constrained values, `Self` for chained methods.

## Error Handling

Handle interrupts and pipe errors at the top level.

```python
import sys


def main() -> int:
    """Main entry point with error handling."""
    try:
        return run()
    except KeyboardInterrupt:
        print("\nInterrupted by user", file=sys.stderr)
        return 130
    except BrokenPipeError:
        sys.stderr.close()
        return 1
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        return 1
```

Custom exceptions can carry exit codes:

```python
class ScriptError(Exception):
    def __init__(self, message: str, exit_code: int = 1) -> None:
        super().__init__(message)
        self.exit_code = exit_code
```

## Documentation

Use Google-style docstrings with Args, Returns, Raises, and Example sections.

```python
def process_data(data: list[str], *, normalize: bool = False) -> dict[str, int]:
    """Process input data and return statistics.

    Args:
        data: List of strings to process.
        normalize: If True, normalize values before processing.

    Returns:
        Dictionary mapping processed items to their counts.

    Raises:
        ValueError: If data is empty.

    Example:
        >>> process_data(["a", "b", "a"])
        {'a': 2, 'b': 1}
    """
```

Include module docstrings with description, usage, and examples.

## Script Organization

Organize scripts in this order:

1. Shebang: `#!/usr/bin/env python3`
2. Copyright header: `# Copyright (c) 2026 Microsoft Corporation. All rights reserved.`
3. SPDX license identifier: `# SPDX-License-Identifier: MIT`
4. PEP 723 inline script metadata (if applicable)
5. Future imports: `from __future__ import annotations`
6. Imports: standard library, third-party, local (separated by blank lines)
7. Constants and exit codes
8. Module-level logger
9. Helper functions
10. Parser creation function
11. Logging configuration function
12. Run logic function
13. Main entry point
14. Module guard: `if __name__ == "__main__": sys.exit(main())`

## Inline Script Metadata

PEP 723 inline metadata enables automatic dependency installation with *uv*.

```python
#!/usr/bin/env python3
# Copyright (c) 2026 Microsoft Corporation. All rights reserved.
# SPDX-License-Identifier: MIT
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "click>=8.0",
#     "rich>=13.0",
# ]
# ///
```

Place after copyright and SPDX headers, before module docstring. Run with `uv run script.py`.

© microsoft · MIT · microsoft/hve-core

Похожие правила IDE

Все правила IDE по теме «Языки программирования» →
writing-python julianobarbosa Скилл writing-python держит агента в правилах Python 3.14+: сначала стандартная библиотека, аннотации типов у всех функций, uv и ruff вместо pip и black. CX Codex +1 134установок python-scaffold Seth Hobson Команда python-scaffold для Claude Code создаёт каркас Python-проекта под FastAPI, Django, библиотеку или CLI. По запросу она формирует структуру каталогов, настройки и тесты. CX Codex +1 ★ 42 780звёзд репо cli-anything-hermes HKUDS Скилл cli-anything-hermes для Hermes агента в Claude Code, который строит CLI-обёртки над графическими приложениями и репозиториями. Оборачивает любое ПО в командную строку с состоянием, undo/redo и JSON-выводом. CX Codex +1 314установок python-guidelines fcakyon Скилл python-guidelines задаёт правила написания и ревью Python-кода: интеграция в существующий код, запрет на лишние абстракции и единый формат докстрингов. CX Codex +1 ★ 1 216звёзд репо cli-anything HKUDS Скилл cli-anything для Claude Code, Codex, Cursor и других агентов, который превращает любое GUI-приложение или репозиторий в CLI-обёртку на Python. Агент сам строит харнесс: анализирует источник, пишет Click-команды, тесты и документацию. CX Codex +1 2 200установок click sanjeed5 Правило задаёт рекомендации по созданию CLI на Python с библиотекой click. Помогает организовать команды, параметры, вывод и подсказки. CX Codex +1 ★ 3 589звёзд репо

Из того же набора148

Весь набор →
python-tests Правило python-tests задаёт конвенции написания тестов на pytest: структуру AAA, именование test_given_when_then и выбор между mocker, monkeypatch и MagicMock. CX Codex +1 ★ 1 627звёзд репо vex Справочник по спецификации OpenVEX v0.2.0 и сценарии для оформления, проверки и публикации документов уязвимостей в проекте. CX Codex +1 ★ 1 627звёзд репо rust-tests Правило rust-tests для Claude Code задаёт структуру и стиль тестов Rust: размещение модульных и интеграционных тестов, именование, фикстуры и изоляцию HTTP-запросов. Унифицирует тесты проекта. CX Codex +1 ★ 1 627звёзд репо CVE Analyzer Субагент CVE Analyzer для глубокого анализа CVE: проверяет достижимость уязвимого кода в проекте и возвращает статус VEX с доказательствами. CX Codex +1 ★ 1 627звёзд репо hve-artifact-authoring Скилл hve-artifact-authoring для Claude Code помогает создавать и проверять агентов, промпты, инструкции и скиллы для HVE Core. Помогает подготовить артефакт и проверить его в репозитории. CX Codex +1 ★ 1 627звёзд репо vex-generation Правило vex-generation задаёт требования к доказательствам, уровням уверенности и статусам при подготовке VEX-документов. Оно пригодится для анализа CVE с участием ИИ. CX Codex +1 ★ 1 627звёзд репо dataops Справочник Microsoft по DataOps и DS/MLOps-тестированию: где проверять данные, как писать тесты пайплайнов и что считать дрифтом, а что — ошибкой валидации. CX Codex +1 ★ 1 627звёзд репо session-log-canvas-update Скилл session-log-canvas-update сверяет схемы событий сессий Copilot с базовой структурой канваса. Помогает адаптировать парсер, тесты и отображение к новым релизам. CX Codex +1 ★ 1 627звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой