friendly-python

friendly-python

编写清晰、易维护且易于扩展的 Python 代码的简明指南。

用途和触发条件

• 用于编写新代码、重构、代码审查或设计公共 API/CLI。
• 优先考虑清晰度和可维护性，而非微优化。
• 适用于 Python 或 .py 文件。
• 如果 $piglet 可用，建议搭配使用，以获取更多精益求精的示例和模式。

决策顺序

1. 正确性和清晰的边界
2. 可读性和可维护性
3. 可扩展性和演进成本
4. 性能和优化

工作流

1. 找到下面相关的主题。
2. 应用相应指南和示例。
3. 如果 $piglet 可用，建议将其与此技能搭配使用。
4. 根据 references/review-checklist.md 进行检查。

主题

主题	指南	参考
原则	正确性优先，其次是清晰度，最后是性能	references/principles.md
错误处理	只捕获能够处理的异常；保留上下文	references/error-handling.md
API 设计	提供默认值和简单入口；隐藏内部连接逻辑	references/api-design.md
扩展架构	集中管理扩展点和变更位置	references/extension-architecture.md
OOP 设计	构造函数清晰；避免在 __init__ 中切换模式	references/oop-design.md
复用与组合	优先采用精简包装器和组合	references/reuse-composition.md
可移植性与 Pythonic 风格	避免照搬其他语言的模式；遵循 Pythonic 风格	references/portability-pythonic.md
Python 约定	明确签名、命名、包 API 和资源	references/python-conventions.md
测试	根据行为确定测试范围、隔离性、结构和时间控制	references/testing.md
应用架构	分离传输、编排、领域逻辑和基础设施	references/application-architecture.md
清除 AI 废话	删除冗余验证、泄露的内部细节和占位式错误处理	references/kill-ai-slop.md
CLI Argparse	将解析与执行分开；合理组织子命令	references/cli-argparse.md
审查	代码质量审查清单	references/review-checklist.md

参考资料

• 除非明确适用例外情况，否则主题文件必须在 frontmatter 的 urls 中列出来源 URL。