Python standards

Opinionated, single-path standards for building Python projects: how a project is structured, the tooling it uses, and the conventions an agent follows while working in it. One set of standards, shared by every project, kept in one place so nothing drifts.

Stack: uv (deps and envs), ruff (lint and format), pytest (tests), ty (type check, with mypy as the documented fallback), stdlib logging. Python 3.14, src/ layout, pyproject.toml as the single source of truth, uv.lock committed.

Contents

• The Standards
  • The manifest
  • Always-on
  • Read on demand
  • Opt-in
  • MAC
• Use the standards in a project
• Versioning and updates
• Releases
• Skills

The Standards

The manifest

• standards/manifest.md: the entry point a project imports. It pulls in the always-on standards files, so a project subscribes to all of them through this one import, and names the read-on-demand and opt-in files without importing them.

Always-on

Imported by the manifest, so they load in every project session — the conventions an agent follows on every task. uv.md is short and imperative, the single source of truth for the uv conventions.

• uv — uv and environments
• structure — the src/ layout
• ruff — lint and format
• pytest — tests
• ty — type check
• docstrings — Google-style docstrings
• logging — stdlib logging
• error-handling — exception hierarchy and boundaries
• configuration — typed config and secrets

Read on demand

Named by the manifest but not imported. Open the matching file when the task calls for it:

• Building a project: pyproject, dependencies, upgrading-python.
• Tooling and templates: pre-commit, templates (ready-to-copy pyproject.toml, CI workflow, logging setup, CLI entry point), quick-reference.
• CLI apps: cli.

Opt-in

• standards/mac-launch-on-startup.md: not imported by the manifest. How to run a project at login on macOS as one always-on instance that is also the development instance. Followed only when the user explicitly asks for it.

MAC

• MAC.md: one-time setup for a Python dev machine: installing uv, global config, the virtual-env guardrail, and VS Code extensions. Run once per machine, independent of any project.

Use the standards in a project

Vendor this repo once as a git submodule at standards/python/:

git submodule add https://github.com/etoews/python-standards.git standards/python

Then the project's own CLAUDE.md imports the manifest and adds nothing but project-specific notes:

# Python standards

@standards/python/standards/manifest.md

# project-specific guidance below

The import means the standards are never pasted into the project, so there is one source of truth and no copy to drift. The manifest pulls in the always-on standards files, and names the read-on-demand files that a task opens when it needs them. Commit the submodule and the CLAUDE.md change together.

Versioning and updates

The standards are released as git tags, and each project pins the submodule to one tag, so a project adopts changes deliberately rather than having them shift underneath it.

Adopt that version in a project (this example moves it from 1.1.0 to 1.2.0):

git -C standards/python fetch --tags
git -C standards/python checkout 1.2.0
git -C standards/python log --oneline 1.1.0..1.2.0    # review what changed

Then commit the updated submodule pointer. Nothing in the project's CLAUDE.md changes, because it only imports the manifest.

Releases

Each release is an annotated git tag, versioned with Semantic Versioning: major when adopting it needs more than a submodule bump (a moved import, a removed standard), minor when standards are added or changed compatibly, patch for fixes and wording. The tag message summarises what changed.

Cut a release from main:

git tag -a 1.4.0 -m "one-line summary of what changed"
git push origin 1.4.0

Projects adopt it deliberately — see Versioning and updates.

Skills

The repo ships two Claude Code skills under .claude/skills/. Each is a folder with a SKILL.md and its scripts. Claude loads a skill when the task matches its description, or you invoke it by name with /<name>.

• sync: keep this repo in step across machines and confirm this Mac still matches MAC.md. It pulls, reconciles drift, fast-forward-merges the working branch, pushes, and re-audits. A read-only audit script reports git state, this Mac's conformance to MAC.md, and doc and manifest integrity, without changing anything. Runs inside this repo.
• test-manifest-import-chain-from-consumer: prove that a fresh Claude Code session in a project loads the standards through the chained import (CLAUDE.md → manifest.md → uv.md). It plants a random sentinel in the deepest file, probes with a headless claude session, checks the answer came from the loaded import rather than a file read, then reverts. Run it from a consumer project after adding the submodule or bumping it to a new tag.