用途：在编写、评审或重构 Python 代码时，为常见设计选择提供一套固定默认答案，而不是每次重新评估各种方案。适用于个人、由智能体维护的 Python 项目；当需求明确要求“评估替代方案”时不适用。偏离默认值仅在确实命中其列出的升级路径时允许。测试套件约定与 MCP 服务器相关规则已拆分为独立安装项。
主要能力： 数据建模：解析外部或不可信数据（API 响应、MCP 工具参数）及配置时默认使用 Pydantic v2 且 frozen=True；其余内部结构化数据、函数返回值、记录使用 @dataclass(frozen=True)。升级路径包括 attrs、NamedTuple（约 3 个字段以内、无校验或行为需求）、msgspec、TypedDict。文中指出 NamedTuple 继承元组排序可能带来跨单位比较静默成功的风险；无 Pydantic 时可用 post_init 做“先解析后校验”。若项目任何地方使用 Pydantic，可全项目统一使用。
Pydantic 陷阱：model_copy(update=...) 不做校验；宽松模式会把 float 强制转为 Decimal，可用 Annotated[Decimal, Strict()] 恢复；配置建议写在类声明中；校验器抛出的 ValueError 会被包装为 pydantic.ValidationError，影响自定义异常层级。
日期时间：只使用带时区的 datetime，并在每个边界归一化为 UTC，拒绝而非强制转换 naive datetime，展示时才转本地时间；使用 zoneinfo，不用 pytz。给出 Utc 注解写法。处理本地墙钟时间需用 fold（PEP 495）并明确策略，通过比较偏移量而非 datetime 检测不存在或歧义时间。不要用 datetime.utcnow()，也不要存浮点时间戳。DST 正确性需要真实转换点的已知答案测试。
配置与密钥：默认 pydantic-settings，基类带生产安全默认值，每个非生产环境一个子类，由 ENVIRONMENT 环境变量选择，在包 init.py 顶部赋值一次，全程 frozen=True。仅在出现多环境部署矩阵时升级到 dynaconf。非 FastAPI 应用不要用 @lru_cache 包装的配置工厂。
守卫子句与异常：守卫子句用于一个正常路径加一个罕见提前退出的非对称情况，不用于拆分两个对等业务分支；assert 仅用于内部“不可能发生”的自检，不用于输入校验；失败时不要返回 None、哨兵值或 (success, result)；每个包至少一个根异常，仅在调用方需要区分时增加层级。
模块化：倾向重复而非过早抽象，遵循三次法则。
限制：这是设计指导，不涉及安装哪个类型检查器或 linter，也不涉及如何配置；具体工具配置由仓库自行决定。文中未提供安装命令、收费或平台信息。