Readable Code：生成与修改约束

每次编写或修改代码前，先阅读本技能；将规则应用于本次任务涉及的代码。

以研究者能够看懂、检查和修改为目标。以 Python 为起点，让实际工作步骤、数据含义与计算假设可见。自用科研脚本不为未提出的公共接口、配置能力或未来扩展建设框架；库和服务保留已有协议、框架及运行约束。其他语言借鉴同样原则，保留语言确实需要的结构。

适用范围

将这些规则用于当前任务新增或修改的代码。不要顺便清理周围代码、重排整个文件，或扩大为全项目重构；用户明确要求整理的范围除外。维持既定计算方法、输入输出、副作用及必要的资源管理。遇到风格与项目现有格式检查冲突时，遵守项目约束，不擅自停用或重配格式化工具。

主流程与状态

• 按实际任务顺序组织代码，让读者容易辨认准备输入、处理、计算、输出等阶段。异步任务也应让启动、等待、重试和结束的关系清楚，不为表面线性改变执行语义。
• 将紧密相关的数据变化放在附近；缩短中间变量和状态标志的作用范围，减少跨几十行追踪初始化、重置和使用。状态确有必要时保留，用名称说明其含义和计数口径。
• 使用直白的条件和循环。简单 NumPy/pandas 运算、推导式和短方法链可以保留；多层条件表达式、嵌套推导式或长链增加理解负担时，展开为步骤和有意义的中间变量。
• 结束、继续和重试条件应容易定位。不要仅为缩短正文，将关键判断藏进回调、通用分发器或多级转发调用。

封装需要实际收益