Python research software coding agent seed prompt

python-prompt.md

Seed a research software Python repository

Create a new, production-quality Python research software repository.

Use a small, opinionated engineering baseline that works well for both human developers and coding agents. Prefer established tools, explicit configuration, and reproducible workflows. Do not add infrastructure without a concrete need.

Baseline stack

Use:

• Python with a src/ package layout
• uv for dependency management, environments, locking, and builds
• pyproject.toml as the primary project configuration
• Ruff for formatting and linting
• pytest for testing
• ty for static type checking where useful
• Make as the common development interface
• Docker for reproducible execution
• MyST Markdown for documentation
• GitHub Actions for continuous integration
• CITATION.cff for software citation metadata
• an SPDX-recognized open-source license

Commit uv.lock.

Do not add Poetry, Pipenv, pre-commit, tox, nox, coverage services, SonarCloud, or similar tooling unless the project has a demonstrated requirement for them.

Repository structure

Start from approximately:

.
├── .github/
│   └── workflows/
│       └── ci.yml
├── docs/
│   └── index.md
├── src/
│   └── <package>/
├── tests/
├── .editorconfig
├── .gitignore
├── AGENTS.md
├── CITATION.cff
├── codemeta.json
├── Dockerfile
├── LICENSE
├── Makefile
├── README.md
├── compose.yaml
├── pyproject.toml
└── uv.lock

Adapt this structure only when the project has a concrete reason to differ.

Python project configuration

Use standard project metadata in pyproject.toml.

Use a lightweight PEP 517 build backend, preferably Hatchling.

Keep tool configuration in pyproject.toml where practical.

Use a clear supported Python version range and avoid compatibility machinery for unsupported versions.

The project must build a source distribution and wheel with:

uv build

Development interface

Keep the Makefile small.

Provide these targets when applicable:

make test
make lint
make format
make typecheck
make check
make build
make docs
make docker

Each target should delegate directly to the underlying tool.

make check should run the normal local validation suite.

Do not hide substantial logic inside Make.

Testing

Use pytest.

Test observable behavior and semantics rather than implementation details.

Prefer tests that remain valid through reasonable refactoring.

Create only enough initial tests to establish meaningful behavior and verify that the package and test environment work correctly.

Do not generate tests merely to mirror implementation structure or increase coverage.

Docker

Provide a simple Dockerfile that builds and runs the project using the same dependency metadata as local development.

Use uv inside the container.

Keep compose.yaml minimal. Do not invent supporting services such as databases, queues, or caches unless the project requires them.

Documentation

Use MyST Markdown.

Start with docs/index.md and keep the documentation hierarchy small.

The README should remain the primary project landing page and should cover:

• what the software does
• installation
• basic usage
• development
• citation
• license

Do not invent scientific claims, authorship, or usage examples when information is unavailable.

Research software metadata

Create:

• CITATION.cff for citation metadata
• codemeta.json for machine-readable research software metadata

Keep CITATION.cff, codemeta.json, and pyproject.toml consistent for overlapping fields such as name, version, authors, repository, license, and description.

Use CodeMeta JSON-LD with the current supported context and schema conventions.

Do not duplicate metadata unnecessarily beyond what is required for interoperability.

Ask the user for input to decide which open-source software license is appropriate to the project. DO NOT infer or select a license without user input

Do not add badges unless they communicate useful project state.

Agent guidance

Create a concise AGENTS.md.

Use the following baseline:

# Development

Use the repository's existing tooling and conventions.
Prefer the smallest change that solves the problem.
Preserve existing architecture unless there is a concrete reason to change it.

Use `uv` for Python environments and dependencies.
Use `make` for common development workflows.

## Tests

Test observable behavior and semantics rather than implementation details.
Prefer tests that remain valid through reasonable refactoring.

## Commits

Use Conventional Commits with imperative subjects of at most 72 characters.
Use scopes only for established repository areas.
For non-trivial changes, explain the rationale in the body.

Keep AGENTS.md intentionally small.

Do not teach capable coding agents general Python, Git, testing, or software-engineering knowledge. Add project-specific guidance only when it is durable and necessary.

Continuous integration

Create one straightforward GitHub Actions workflow that exercises the same interfaces developers use locally.

At minimum, validate:

• formatting
• linting
• type checking when configured
• tests
• package build
• documentation build
• Docker image build

Avoid unnecessary CI abstractions and duplicated workflow logic.

Design principles

Favor:

• boring, established tooling
• reproducibility
• explicit dependencies
• simple interfaces
• semantic tests
• small dependency graphs
• ecosystem-native configuration
• code and configuration that agents can inspect easily

Avoid:

• speculative architecture
• unnecessary abstraction layers
• redundant configuration
• generated boilerplate without purpose
• premature automation
• project structure justified only by convention

The initial repository should be small enough to understand quickly but complete enough to clone, install, test, build, document, and containerize immediately.

Completion criteria

Before finishing:

1. synchronize the environment with uv
2. run the repository's full validation suite
3. build the Python package
4. build the documentation
5. build the Docker image

Fix failures rather than leaving broken placeholders.

Conclude with a concise summary of the repository created, important design choices, and validation results.