PYTHON PACKAGE (UV) AGENTS.MD

A Python library managed with uv and published to PyPI. The rules protect the public API, keep the environment reproducible through uv, and set typing and linting expectations that tools can check.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
The Python package (uv) filesCustomize in the generator
AGENTS.mdFor Codex, Cursor, Copilot, Jules, Windsurf and more
# AGENTS.md

Project: my-python-lib. A typed Python library managed with uv and published to PyPI.

This file is the single source of truth for every coding agent working in this repository. The tool-specific files (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md and .cursor/rules/project.mdc) point here. Edit this file, not those.

## Stack

- Language: Python
- Hosting: A package registry (npm, PyPI, crates.io)
- Tests: pytest
- Package manager: uv

## Commands

Run these from the repository root.

- Install dependencies: `uv sync`
- Build: `uv build`
- Run all tests: `uv run pytest`
- Run one test file: `uv run pytest tests/test_core.py::test_parse`
- Lint: `uv run ruff check .`
- Type-check: `uv run mypy src`
- Format: `uv run ruff format .`

## Project layout

- `src/<package>/`: The importable package (src layout)
- `src/<package>/__init__.py`: Public API: everything in __all__
- `tests/`: pytest tests
- `pyproject.toml`: Metadata, dependencies and tool config
- `uv.lock`: Locked dependencies (generated)

## Code style

- Indent with 4 spaces. Never tabs.
- Every new or changed Python function has type hints for its parameters and return value.
- Match the style and patterns of the surrounding code, even where you would personally choose differently.
- Prefer small pure functions and immutable data; keep side effects at the edges (handlers, jobs, I/O modules).
- Never swallow an error. Handle it where you can act on it, or rethrow it with context about what failed.
- Delete code you make unused, including imports, flags and files. Do not leave commented-out code behind.

## Working rules

- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- For a bug fix or behavior change, first write or update a test that fails, then make it pass.
- Never delete, skip or loosen a test to make it pass. If a test is wrong, say why and ask before changing it.
- Never write secrets, API keys, tokens or passwords into code, tests, fixtures, logs or commits. Read them from environment variables, and never commit `.env` files.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.
- Do not hand-edit generated files or lockfiles; change the source and regenerate.
- When you change commands, structure or conventions, update this file and the README in the same change.

## Project-specific notes

- Manage dependencies only with `uv add` and `uv remove`; never edit `uv.lock` or call `pip install` into the environment.
- Run everything through `uv run` so it uses the project environment.
- Names listed in `__all__` are the public API; changing their signatures is a breaking change and needs a major version bump.
- Keep the package importable on every Python version listed in `requires-python`; do not use newer syntax than the minimum allows.
- Use `pathlib` for paths and context managers for files and resources.
- Ship a `py.typed` marker and keep mypy clean on `src`.
- Never run `uv publish`; releases happen in CI from a tag.

## Project phase

This project is in maintenance. Make minimal, low-risk changes, preserve behavior and public APIs, and explain any change that could affect users.
CLAUDE.mdFor Claude Code
# CLAUDE.md

@AGENTS.md

## Claude Code

- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file, so every agent stays in sync.
- Put Claude-only preferences below this line. Personal, uncommitted notes belong in CLAUDE.local.md.
GEMINI.mdFor Gemini CLI
# GEMINI.md

@./AGENTS.md

## Gemini CLI

- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file.
- Alternative: delete this file and set "context": { "fileName": ["AGENTS.md"] } in .gemini/settings.json so Gemini CLI reads AGENTS.md directly.
.github/copilot-instructions.mdFor GitHub Copilot
# Copilot instructions

Project: my-python-lib. A typed Python library managed with uv and published to PyPI.

The full instructions are in AGENTS.md at the repository root. Read it before you change code; if anything here disagrees with it, AGENTS.md wins. The essentials are repeated below for Copilot surfaces that only read this file.

## Stack

- Language: Python
- Hosting: A package registry (npm, PyPI, crates.io)
- Tests: pytest
- Package manager: uv

## Commands

- Install dependencies: `uv sync`
- Build: `uv build`
- Run all tests: `uv run pytest`
- Run one test file: `uv run pytest tests/test_core.py::test_parse`
- Lint: `uv run ruff check .`
- Type-check: `uv run mypy src`
- Format: `uv run ruff format .`

## Working rules

- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- For a bug fix or behavior change, first write or update a test that fails, then make it pass.
- Never delete, skip or loosen a test to make it pass. If a test is wrong, say why and ask before changing it.
- Never write secrets, API keys, tokens or passwords into code, tests, fixtures, logs or commits. Read them from environment variables, and never commit `.env` files.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.
- Do not hand-edit generated files or lockfiles; change the source and regenerate.
- When you change commands, structure or conventions, update this file and the README in the same change.
.cursor/rules/project.mdcFor Cursor
---
description: Project instructions for every task (mirrors AGENTS.md)
globs:
alwaysApply: true
---

# Project rules

The project instructions live in @AGENTS.md at the repository root, which Cursor loads automatically. They are not repeated here, so they cost context only once. Edit AGENTS.md, not this rule.

Before you change code, check the Commands and Working rules sections of AGENTS.md, and run its test and lint commands before you say a task is done.

Put Cursor-only rules below, or add scoped rules as more .mdc files with `globs` (for example `src/components/**/*.tsx`).

These are the exact files the generator writes for this preset. Change any command or rule in the generator and download your own set.

About the Python package (uv) preset

What Is in the Python package (uv) AGENTS.md?

The preset describes a a typed Python library managed with uv and published to PyPI. Its AGENTS.md is 48 non-empty lines with 7 exact commands, 5 key directories, and 7 stack-specific rules on top of the shared working rules.

  • Commands: uv sync, uv build, uv run pytest, uv run pytest tests/test_core.py::test_parse, uv run ruff check ., uv run mypy src, uv run ruff format ..
  • Layout: src/<package>/, src/<package>/__init__.py, tests/, pyproject.toml, uv.lock.
  • Wrappers: CLAUDE.md and GEMINI.md import AGENTS.md; the Copilot file repeats the essentials; the Cursor rule points to AGENTS.md.

Why These Rules for Python package (uv)?

pip install bypasses the lockfile

An agent that runs pip install makes something work locally while the lockfile and pyproject stay unchanged. The next person, or CI, gets a different environment and a failure nobody can reproduce.

Minimum Python version is a promise

Agents write modern syntax such as match statements or new typing forms by default. If your package supports an older Python, that code breaks for some users with an unhelpful SyntaxError.

The src layout catches packaging bugs

With a src layout, tests import the installed package, not the folder, so missing package data shows up in tests instead of after release.

__all__ defines the contract

Without an explicit public API, every helper becomes something a user may depend on.

Which Stack Rules Does the File Add?

  • Manage dependencies only with uv add and uv remove; never edit uv.lock or call pip install into the environment.
  • Run everything through uv run so it uses the project environment.
  • Names listed in __all__ are the public API; changing their signatures is a breaking change and needs a major version bump.
  • Keep the package importable on every Python version listed in requires-python; do not use newer syntax than the minimum allows.
  • Use pathlib for paths and context managers for files and resources.
  • Ship a py.typed marker and keep mypy clean on src.
  • Never run uv publish; releases happen in CI from a tag.

How Do You Add These Files to a Python package (uv) Repository?

  1. Download the zip above. It is laid out exactly as the files go into the repository.
  2. Unzip it at the repository root. AGENTS.md, CLAUDE.md and GEMINI.md go next to your README; the Copilot file goes in .github/ and the Cursor rule in .cursor/rules/.
  3. Open AGENTS.md and check every command against your package scripts or Makefile.
  4. Delete wrappers for tools your team does not use, and any old .cursorrules or .windsurfrules file.
  5. Commit, then run the linter on AGENTS.md whenever you change it.

Want different commands or rules? Load this preset into the generator, change anything, and download your own set.

Which Agents Will Read These Files?

AGENTS.md is read directly by Codex, Cursor, Windsurf, Cline, Zed and Jules, and by GitHub Copilot's cloud agent, code review and CLI. Claude Code reads it through the generated CLAUDE.md, and Gemini CLI through GEMINI.md. See the compatibility table for details, last verified 2026-11-13.

Which Similar Stacks Are in the Library?

All presets are on the stacks page.

Frequently Asked Questions

Can I use Poetry or Hatch instead of uv?

Yes. Choose Poetry in the generator or edit the commands; the API, typing and release rules stay the same.

Why mypy and not pyright?

Either works. mypy is the template default because it is common in libraries; replace the type-check command if your project uses pyright.

Does the agent need to know about PyPI tokens?

No. Publishing should run in CI with trusted publishing, so no token exists in the repository or the agent session at all.

Are these Python package (uv) files free to use?

Yes. Copy them into any project, commercial or not, without attribution. They are a starting point: adjust the commands and rules to match your repository.

How Can You Verify That Nothing Leaves This Browser?

You do not have to take our word for it. Developer tools show every request a page makes, so you can watch this page work and confirm that nothing you type is sent. The check takes under a minute.

  1. Open your browser developer tools with F12, or Cmd+Option+I on a Mac, and select the Network tab.
  2. Reload the page and let it finish. You will see the page's own files, its web fonts, and one anonymous page-view request. Nothing has been typed yet, so none of them can contain your input.
  3. Click the clear icon in the Network tab so that the log is empty.
  4. Switch between the file tabs, copy a file and download the zip.
  5. Look at the Network tab again. It is still empty. Downloads are built in the page as Blob URLs, so even the zip never touches a server. For extra proof, turn on offline mode after the page loads: everything keeps working.

Only the feedback form can add a line to that log, and it sends only the vote and comment you type into it. 2prompt has no server code at all: no API, no model and no database of your files. The production site also sends a Content-Security-Policy header that tells your browser to refuse connections to anywhere except this site, the fonts and the anonymous analytics endpoint.

Was this helpful?