Rules for AI assistants writing my Python applications, a complete template project they start from, and a Claude Code plugin that scaffolds, audits and releases projects that follow them.
AI disclosure: This project was written by AI under human oversight, following these rules.
| Path | What it is |
|---|---|
| RULES.md | The rules. Point an AI at this file. |
| templates/ | A working example app: src layout, tests, Dockerfile, dev/test/lint/prod compose files, CI, release workflow, pre-commit, Renovate, docs skeletons |
| templates/optional/postgres/ | How to add PostgreSQL (or, if it must be, SQLite) |
| SKILL.md | Makes this repo an Agent Skill |
| skills/, .claude-plugin/ | The python-rules Claude Code plugin |
| UPGRADING.md | Fixes repos set up under older rules must apply |
| SECURITY.md | How to report a vulnerability |
| docs/ | Release strategy, Claude Code usage, configuration guide, overview |
- How the AI works: no invented APIs, ask before adding frameworks, services or dependencies, run the tests and lint before claiming success, say what wasn't tested, look up current versions instead of trusting training data.
- Python: the newest Python, uv for development (pip still works),
src layout, strict mypy, ruff, configuration from environment variables
with a complete
.env.example, logging, clean shutdown. - Tests: pytest with an 80% coverage floor, fast and deterministic, real PostgreSQL when there's a database.
- Databases: none unless needed; PostgreSQL by default, SQLite only by agreement, migrations always.
- Docker: dev, test, lint and production compose files; a small, non-root, read-only production image.
- Tooling: pre-commit for lint, format, types and secrets; GitHub
Actions with uv and layer caching; Renovate; protected
main. - Releases: semver, changelog-driven release notes, a multi-arch production image on ghcr.io and a GitHub Release with the wheel for every version; optionally PyPI.
- Installing: Docker, uv or plain pip, all documented.
- Docs: README layout, badges, AI disclosure, CHANGELOG, configuration reference, a short overview for AIs.
With Claude Code, install the plugin (details):
/plugin marketplace add romkey/python-ai-rules
/plugin install python-rules@romkey-python
Then /python-rules:new starts a project, /python-rules:check audits
one, and /python-rules:release cuts a release.
As an Agent Skill, for Claude (claude.ai, the desktop app, the API)
or any other tool that reads Agent Skills: download
python-ai-rules-skill.zip from the
latest release
and upload it as a skill, or clone the repo into the tool's skills folder:
git clone https://github.com/romkey/python-ai-rules ~/.claude/skills/python-ai-rulesThe skill covers the same tasks as the plugin's commands: describe them ("start a new Python app", "audit this repo", "cut a release").
With any AI assistant, tell it: "Follow https://github.com/romkey/python-ai-rules/blob/main/RULES.md", or copy templates/AGENTS.md into the project.
By hand, copy templates/ and follow the
configuration guide.
The templates are tested like a real project; this repo's CI runs the template's tests and builds its production image.
docker compose -f docker-compose.lint.yaml run --rm lint
cd templates
docker compose -f docker-compose.test.yaml run --rm test
docker compose -f docker-compose.prod.yaml build
cd ..
claude plugin validate .main is protected: changes go through pull requests, which merge once
CI passed and Lint pass. .github/workflows/ci.yaml is generated
from the template's: edit
templates/.github/workflows/ci.yaml and run scripts/sync-ci.py.