| id | python-product-quality |
|---|---|
| type | guide |
| title | Build a Python Product That Can Be Changed Safely |
| summary | A practical quality model for moving from a useful script to an operable Python product. |
| lang | en-US |
| content_version | 1 |
| status | reviewed |
| reviewed_on | 2026-09-02 |
A good Python product is not defined by framework choice or code volume. It solves a clear user problem, behaves predictably at its boundaries, and can be changed without gambling with user data or production behavior.
Write a concrete sentence: “Given this input, this user can obtain this result.” Turn it into acceptance examples before choosing a framework. If the result cannot be observed, the product requirement is not yet testable.
Keep domain logic independent from HTTP, databases, files, model providers, and other APIs. Validate untrusted input at those boundaries, return stable error forms, and set timeouts for every network call.
Decide which operations may be retried, which must be idempotent, and which need human confirmation. Never hide partial failure. Preserve enough context for a user or operator to recover without guessing.
Use fast unit tests for domain rules, integration tests for boundaries, and a small number of end-to-end checks for the real user path. A green test suite is evidence for only the behavior it actually exercises.
Use structured logs, request or job identifiers, useful health checks, and metrics tied to user outcomes. Do not log secrets, raw credentials, or sensitive payloads. An operator should be able to answer what failed, for whom, and where.
Pin runtime and dependencies, document configuration, separate schema changes from application rollout when needed, and define rollback before deployment. Verify the deployed behavior through the real interface, not only build output.
Model output is untrusted input. Give tools the minimum permissions they need, validate structured output, cap time and cost, record tool calls, and require human approval for irreversible actions. A Skill or MCP server improves reuse; it does not remove the need for authentication, authorization, tests, and audit.
- A user outcome and its failure behavior are documented.
- Boundary inputs and outputs are typed and validated.
- The main behavior and recovery path have tests.
- Logs and health signals answer actionable questions without leaking secrets.
- The release and rollback commands are known.
- The production behavior has been checked through the real user path.