# Python Project Guardrails

> Define and enforce Python project build rules for uv-only dependency management, .env-driven configuration, strict contracts, typed interfaces, structured logging, async I/O, retries, task state machines, media validation, and json-repair fallback. Use when creating or reviewing Python project standards, architecture rules, implementation guardrails, or production-readiness constraints.

- Skill: `yu-xuan99/python-project-guardrails` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add yu-xuan99/python-project-guardrails`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yu-xuan99/python-project-guardrails/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Yu-xuan99 (https://skillmd.com/u/yu-xuan99)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yu-xuan99/python-project-guardrails

---


# Python Project Guardrails

## Use This Skill

Apply these rules when starting a Python project, adding a module, reviewing code, or deciding whether an implementation is production-ready.

## When To Use

- Use for backend Python services, async workers, model-invoking systems, and deployment-related engineering.
- Use when the codebase depends on `uv`, `.env`, structured logs, retries, task state machines, or JSON output validation.
- Use when reviewing production readiness or operational behavior.

## When Not To Use

- Do not use for frontend-only projects.
- Do not use for one-off scripts that do not need production guardrails.
- Do not use when the task is purely domain content, product copy, or non-engineering documentation.

## Core Red Lines

- Use `uv` as the only package manager.
- Store all configuration in `.env`.
- Define contracts before implementation.
- Keep public interfaces typed and `pyright`-strict compatible.
- Use `logging`, not `print`, except in the main entry file.
- Use `async` / `await` for all I/O.
- Validate outputs before marking work complete.
- Use `json-repair` as the JSON fallback path when parsing fails.

## Implementation Order

1. Define the contract.
2. Define configuration keys and `.env` defaults.
3. Define logging and error-handling behavior.
4. Implement the smallest real slice of logic.
5. Add validation and retry handling.
6. Add state transitions and observability.
7. Verify `ruff`, `pyright`, and runtime behavior before release.

## Review Checklist

- No hidden config values.
- No sync I/O inside async code.
- No silent failures.
- No undocumented interface fields.
- No fake placeholders.
- No direct model output returned without validation.
- No deployment variable hardcoding.
- No missing trace IDs in operational logs.
- No unbounded retries or missing drain path.

## References

- Contract and config: [Contract And Config](references/contract-and-config.md)
- Logging and traceability: [Logging And Observability](references/logging-observability.md)
- Runtime safety and task flow: [Production Readiness](references/production-readiness.md)
- Deployment and rollback: [Deployment Operations](references/deployment-operations.md)