本规范参考 Google Python Style Guide，并结合项目使用的 Black、Prettier、FastAPI 和 React 约定。
- 可读性和职责边界优先于行数。行数只用于触发结构审查，不能单独作为拆分理由
- 拆分应形成高内聚边界，或实质降低认知复杂度；独立命名、独立测试和复用是判断依据，不是前置条件
- 禁止仅为压缩行数创建没有独立职责或独立变化原因的转发、重导出、Mixin 拼装或单消费者
helper/types文件 - 只与调用方共同变化的私有组件、类型和帮助函数优先同文件共置
- 名称应表达领域含义和动作；仅在上下文不足时避免含糊缩写或
data、item、process等泛化名称 - 只在能够恢复、转换异常或补充有效上下文的边界捕获错误；避免重复记录后原样抛出
- 手写后端 Python 源码与脚本超过 400 行时必须审查职责；超过 600 行时须在变更说明中记录保留理由，无法说明单一变化原因时拆分
- 手写前端 TypeScript/TSX 源码超过 400 行时必须审查职责；超过 500 行时须在变更说明中记录保留理由，无法说明单一变化原因时拆分
- 后端函数或方法超过约 40 行时，按 Google Python Style Guide 检查能否在不破坏控制流的前提下拆分；不设置仅按行数触发的强制拆分上限
- 前端组件或 Hook 超过 200 行时必须审查状态、数据获取和展示职责；超过 300 行时须在变更说明中说明这些职责仍属于同一变化原因
- Alembic migration、生成文件和以声明式数据为主的文件不受文件行数限制
- Python 文件使用 Black 格式化；不通过手工换行与 Black 对抗
- 模块、函数、方法和变量使用
snake_case，类使用PascalCase，常量使用UPPER_SNAKE_CASE - 非公开模块成员以
_开头；不要用_代替清晰的模块边界 - 公共函数和复杂内部函数必须标注参数与返回类型
- 返回超过 3 个独立值时，必须使用
dataclass、Pydantic 模型或NamedTuple等具名结构，不返回依赖位置记忆的长元组 - 捕获具体异常类型；转换异常时使用
raise ... from exc保留异常链 - 异步路径不得执行阻塞 I/O；HTTP 客户端、数据库会话和连接池必须由明确的生命周期统一管理
- TypeScript、TSX 和样式文件使用 Prettier 格式化
- 组件文件使用
PascalCase，Hook 和工具文件使用camelCase，Hook 名称以use开头 - 新增局部布尔变量优先使用
is、has、can、should等语义前缀；API 契约中的enabled等领域字段保持原名 - 组件保持单一展示职责；状态编排、数据获取和纯展示只有在形成清晰边界时才拆分
- 一个函数需要返回多个独立结果时使用具名对象，不使用需要调用方记忆位置的长元组
- Props 必须有明确类型；Hook 返回值在推断不清或作为公共契约时显式标注，禁止用
any绕过边界建模 - 存在独立样式文件时，样式文件与组件同名