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
• Logging and traceability: Logging And Observability
• Runtime safety and task flow: Production Readiness
• Deployment and rollback: Deployment Operations