python-script — правило для Claude Code: что делает и как установить
Правило python-script задаёт стандарты написания утилит автоматизации на Python 3.11+ для Claude Code: управление пакетами через uv, строгие типы и единая структура CLI.
MIT ★ 1 627 обновлён 2026-10-25
.github/instructions/python-script.instructions.mdЧто делает 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 задаёт, к каким файлам применять
Вручную: положить файлы
.claude/rules/python-script.mdПоле paths во frontmatter ограничивает файлы: applyTo из источника → paths
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/python-script.mdcВо frontmatter: description, globs, alwaysApply. applyTo из источника → globs, иначе правило само не подключится
Вручную: положить файлы
.devin/rules/python-script.mdВручную: положить файлы
.clinerules/python-script.mdПо шагам, с командами для каждой платформы: 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