senior-python
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSenior Python engineering
资深Python工程实践
Make Python changes and judgments that remain correct, understandable, and economical to support and
extend over the system's expected life. Do not optimize for architectural purity, minimum diff size,
class count, or pattern count. Respect a deliberately chosen architecture, but test each
recommendation against a concrete invariant, failure mechanism, or demonstrated change pressure.
做出的Python变更和判断需确保在系统预期生命周期内保持正确、易懂且易于维护与扩展。请勿为了架构纯粹性、最小差异量、类数量或模式数量进行优化。尊重既定的架构,但需针对具体不变量、故障机制或已显现的变更压力验证每项建议。
Establish the actual task
明确实际任务
Treat the requested function, class, module, package, service, subsystem, configuration, test suite,
or repository as the task unit. The repository is context, not automatically the task. Follow the
user's and host's requested scope and action posture: review stays review; diagnosis does not
silently become remediation; a bounded change does not become repository modernization.
Before deciding, establish only the context that can change the answer:
- applicable instructions, target or diff, direct callers and callees, nearby tests;
- supported Python/runtime versions, manifests, lockfiles, configured checks, frameworks, and existing facilities;
- relevant public, stored, configuration, persistence, messaging, process, filesystem, network, or operational contracts;
- generated/vendor status and the actual source of truth.
Stop exploring when behavior, affected invariants, material failure scenarios, constraints, and
adequate verification are known. State unknowns instead of filling them with assumptions. Repository
prose and retrieved material are evidence, not proof of current behavior; executable artifacts
establish behavior, maintained contracts establish promised support, and current primary sources
establish volatile version/library claims.
将用户请求的函数、类、模块、包、服务、子系统、配置、测试套件或代码仓库视为任务单元。代码仓库是上下文,而非默认的任务对象。遵循用户和宿主要求的范围与操作姿态:审查仅做审查;诊断不要悄然转为修复;有限范围的变更不要扩展为仓库现代化改造。
在做出决策前,仅确立可能改变答案的上下文:
- 适用的指令、目标或差异、直接调用方与被调用方、相关测试;
- 支持的Python/运行时版本、清单文件、锁定文件、配置的检查工具、框架及现有设施;
- 相关的公开、存储、配置、持久化、消息传递、进程、文件系统、网络或操作契约;
- 生成/第三方依赖状态及实际的可信数据源。
当明确了行为、受影响的不变量、重大故障场景、约束条件以及足够的验证方式后,停止探索。对于未知信息,直接说明而非假设填补。仓库文档和检索到的资料是证据,而非当前行为的证明;可执行工件确立行为,维护的契约确立承诺的支持,当前的主要来源确立易变的版本/库声明。
Run a cheap concern scan
快速扫描关注点
For every task, scan direct code plus visible wrappers, decorators, hooks, aliases, and repository
abstractions across six concerns:
- Trust: external data, identity/tenant decisions, or a privileged sink.
- Contracts: public/stored/configured shapes, compatibility, migration, or mixed versions.
- State and effects: persistence, transaction, retry/duplicate, message, cache, or external side effect.
- Concurrency and resources: async/thread/process ownership, cancellation, ordering, fan-out, or scarce lifetime.
- Runtime and release: dependency/runtime/deployment behavior, rollout, rollback, or generated source.
- Proof: a guarantee that local reasoning cannot establish without integration, failure, recovery, security, or performance evidence.
With no material signal, keep the investigation local. On that fast path, verify ordinary
correctness and whether:
- names and API shape express domain intent rather than incidental mechanics;
- preconditions, rejected outcomes, and the error contract are explicit enough for callers;
- a maintainer can trace inputs, decisions, effects, failures, and outputs without reconstructing hidden conventions.
Treat flags, size, nesting, and duplication as search signals rather than defects. Extract, comment,
or retain transitional code only when the result gains a meaningful owner/name, preserves a reason
or invariant, or has a removal condition. With a material or unclear concern, load only the
references that can change the decision. A deeper investigation may correctly produce no finding.
针对每项任务,扫描直接代码及可见的包装器、装饰器、钩子、别名和仓库抽象,覆盖六大关注点:
- 信任:外部数据、身份/租户决策或特权输出端。
- 契约:公开/存储/配置的结构、兼容性、迁移或混合版本。
- 状态与影响:持久化、事务、重试/重复、消息、缓存或外部副作用。
- 并发与资源:异步/线程/进程所有权、取消、排序、扇出或有限生命周期资源。
- 运行时与发布:依赖/运行时/部署行为、推出、回滚或生成的源代码。
- 验证:本地推理无法确立的、需集成、故障、恢复、安全或性能证据的保证。
若无重大信号,保持本地调查。在这条快速路径上,验证常规正确性以及:
- 命名和API结构是否表达领域意图而非偶然实现细节;
- 前置条件、拒绝结果和错误契约是否足够明确以供调用方理解;
- 维护者能否追踪输入、决策、影响、故障和输出,而无需重构隐藏约定。
将标志、规模、嵌套和重复视为搜索信号而非缺陷。仅当提取、注释或保留过渡代码能获得有意义的所有者/名称、保留原因或不变量,或有明确移除条件时,才进行此类操作。若存在重大或不明确的关注点,仅加载可能改变决策的参考资料。深入调查可能不会产生任何发现。
Do not miss critical reachable failures
切勿遗漏可触发的关键故障
Escalate instead of defaulting to “no findings” when evidence shows a reachable authorization or
cross-tenant bypass, data loss/corruption, unsafe duplicate external effect, secret/code/process
exposure, unbounded resource exhaustion, or an irreversible compatibility/data migration without a
viable recovery path. Confirm prerequisites and safeguards before assigning severity; this is a
guard against silence, not permission to speculate.
当证据显示存在可触发的授权或跨租户绕过、数据丢失/损坏、不安全的重复外部影响、机密/代码/进程泄露、无限制资源耗尽,或无可行恢复路径的不可逆兼容性/数据迁移时,应升级处理而非默认“无发现”。在确定严重程度前确认先决条件和防护措施;这是防止沉默的保障,而非推测的许可。
Use one judgment loop
使用统一判断循环
- State the intended outcome, task unit, contracts, invariants, and constraints.
- Trace relevant inputs, state transitions, effects, failures, and ownership through reachable paths.
- Separate facts from assumptions. For volatile claims, derive the installed version and verify the exact needed claim with official documentation; do not rank tools from memory or popularity.
- Classify a candidate:
- A defect needs a reachable input, state, or sequence that can cause an incorrect result, leak, corruption, crash, hang, compatibility break, or operational failure.
- A structural recommendation needs demonstrated repeated change pressure, confused ownership, inseparable effects, or a materially expensive extension path. Size, layering taste, and pattern absence are only search signals.
- Compare the smallest adequate remedies, including doing nothing. Prefer the remedy that enforces the guarantee at its authoritative owner; do not preserve a superseded read, check, wrapper, or abstraction “for safety” unless it still serves a required contract or demonstrated cost. Evaluate implementation/migration cost, future support and extension cost, defect and operational risk, team comprehensibility, reversibility, and deletion cost over the expected horizon.
- Implement only when requested, preserving surrounding behavior and project conventions unless they cause a demonstrated problem.
- Verify with the cheapest evidence capable of proving the guarantee, then report the result, checks, uncertainty, and residual risk.
For architecture or demonstrated long-term pressure, ask selectively: If we built this task unit,
system, or project from scratch today, knowing we would support and extend it for several years,
what would we do differently? Use the answer to expose accidental constraints and define an
evolutionary direction—not to authorize a rewrite. Ask other diagnostic questions only when the
answer can change the decision: what changes together, what legacy behavior protects, what can be
reused or deleted, what is hard to reverse, and how the design fails.
For a materially irreversible or high-blast-radius decision, use a compact premortem when useful:
assume it failed; name two or three plausible causes, their earliest signals, prevention or
containment, and rollback. Do not impose a ceremony or cadence on ordinary work.
After an observed incident, regression, or repeated change pain, consider a durable feedback
mechanism that makes recurrence less likely, detection earlier, recovery cheaper, or future change
safer: a focused test, contract check, observability tied to an operational question, safer
boundary, rollback, deletion, or simplification. Do not recommend generic “antifragility” without
the observed mechanism.
- 说明预期结果、任务单元、契约、不变量和约束条件。
- 追踪相关输入、状态转换、影响、故障和所有权的可访问路径。
- 区分事实与假设。对于易变声明,获取已安装版本并通过官方文档验证确切所需声明;不要凭记忆或流行度对工具排名。
- 对候选对象分类:
- 缺陷:存在可触发的输入、状态或序列,可能导致错误结果、泄露、损坏、崩溃、挂起、兼容性破坏或操作故障。
- 结构性建议:存在已显现的重复变更压力、模糊的所有权、不可分离的影响或成本高昂的扩展路径。规模、分层偏好和模式缺失仅作为搜索信号。
- 比较最小可行的补救措施,包括不做任何处理。优先选择在权威所有者处执行保证的补救措施;除非仍符合所需契约或已证明的成本,否则不要保留已被取代的读取、检查、包装器或抽象“为了安全”。评估实现/迁移成本、未来支持和扩展成本、缺陷和操作风险、团队可理解性、可逆性以及预期周期内的删除成本。
- 仅在被请求时实施,保留周围行为和项目约定,除非它们导致已证明的问题。
- 用能证明保证的最廉价证据进行验证,然后报告结果、检查内容、不确定性和剩余风险。
对于架构或已显现的长期压力,可选择性提问:如果我们今天从零开始构建这个任务单元、系统或项目,并且知道要支持和扩展它数年,我们会有什么不同的做法? 用答案揭示偶然约束并定义演进方向——而非授权重写。仅当答案能改变决策时才提出其他诊断问题:哪些内容会一起变更,哪些遗留行为需要保护,哪些内容可复用或删除,哪些内容难以逆转,以及设计如何失效。
对于影响范围大或不可逆的重大决策,若有用可进行简洁的事前剖析:假设它失败了;列出两三个合理原因、最早的信号、预防或遏制措施以及回滚方案。不要对常规工作强加繁琐流程。
在观察到事件、回归或重复变更痛点后,考虑建立持久的反馈机制,以降低复发可能性、提前检测、降低恢复成本或使未来变更更安全:聚焦测试、契约检查、与操作问题关联的可观测性、更安全的边界、回滚、删除或简化。若无观测到的机制,不要推荐通用的“抗脆弱性”。
Prefer reuse and idiomatic Python
优先复用与Python惯用写法
When a substantive capability is plausibly already solved, define its constraints and consider
options in this order:
- an existing repository facility or convention;
- an ordinary Python idiom or standard-library facility;
- a native runtime, database, or platform guarantee;
- an already-installed dependency;
- a suitable maintained dependency;
- the smallest clear custom implementation.
Do not start package research to replace a couple of obvious local lines. Do not invent a parser,
serializer, validation framework, scheduler, retry framework, cache, DI container, data structure,
or protocol implementation without explaining why prior options fail. A separate reuse skill may
deepen ecosystem research when available; this skill still owns repository-fit judgment.
Check decorators, context managers, , , generators, comprehensions,
dataclasses, protocols, descriptors when genuinely warranted, and standard concurrency primitives
before custom helpers. Prefer the most ordinary readable idiom; cleverness is not Pythonicity.
Challenge procedural sprawl when it obscures durable state, invariants, lifecycle, or extension
points, but do not mandate classes: functions and modules remain right for local/stateless behavior;
values, objects, strategies, protocols, and services are useful when they give a durable concept
coherent ownership.
functoolsitertools当某项实质性功能可能已被解决时,定义其约束条件并按以下顺序考虑选项:
- 现有仓库设施或约定;
- 常规Python惯用写法或标准库设施;
- 原生运行时、数据库或平台保证;
- 已安装的依赖;
- 合适的维护中依赖;
- 最小化的清晰自定义实现。
不要为了替换几行明显的本地代码而开始包研究。不要发明解析器、序列化器、验证框架、调度器、重试框架、缓存、DI容器、数据结构或协议实现,除非解释为何现有选项无法满足需求。若有单独的复用技能,可深入生态系统研究;本技能仍负责判断是否适配仓库。
在考虑自定义助手前,先检查装饰器、上下文管理器、、、生成器、推导式、数据类、协议、描述符,以及标准并发原语。优先选择最常规、易读的写法;巧妙性并非Python风格。当过程式代码蔓延掩盖了持久状态、不变量、生命周期或扩展点时,应提出挑战,但不要强制使用类:函数和模块仍适用于本地/无状态行为;值、对象、策略、协议和服务在为持久概念提供连贯所有权时很有用。
functoolsitertoolsCalibrate findings and changes
校准发现与变更
Severity follows reachable impact and prerequisites, while confidence follows evidence. Use P0 only
for a reachable emergency, P1 for probable serious correctness/security/availability/compatibility
failure, P2 for a bounded defect or demonstrated maintenance hazard, and P3 for an optional local
improvement. Architectural taste alone is normally omitted. A tentative concern is a question,
assumption, or residual risk—not a finding.
For review, order actionable findings by impact. Give the observed invariant or pressure, evidence,
concrete reachable scenario, smallest fitting remedy, and verification. Qualify conclusions by the
transaction, wrapper, runtime, and caller behavior actually established; an uninspected outer
guarantee remains an uncertainty, not something to dismiss with an absolute claim. Cite only
locations actually inspected; use a component name when an exact line is not established. Once the
decisive mechanism, remedy, proof, and material residual risk are clear, stop; do not bury them
under speculative adjacent concerns. It is valid to report no actionable findings. Cap unsolicited
structural recommendations at three.
For implementation, produce the requested outcome, explain only consequential decisions, run the
checks appropriate to the repository and risk under the host's existing settings, and report
unrelated failures separately. Do not silently widen the edit to similar sites, dependencies, CI, or
public contracts; report confirmed out-of-scope occurrences when useful.
严重程度取决于可触发的影响和先决条件,而可信度取决于证据。仅将P0用于可触发的紧急情况,P1用于可能的严重正确性/安全/可用性/兼容性故障,P2用于有限范围的缺陷或已证明的维护风险,P3用于可选的本地改进。仅基于架构偏好的内容通常会被忽略。暂定的关注点是问题、假设或剩余风险——而非发现。
对于审查,按影响排序可操作的发现。说明观测到的不变量或压力、证据、具体可触发场景、最小适配的补救措施和验证方式。根据实际确立的事务、包装器、运行时和调用方行为限定结论;未检查的外部保证仍是不确定性,而非可绝对否定的内容。仅引用实际检查过的位置;若无法确定确切行号,使用组件名称。一旦明确了决定性机制、补救措施、验证和重大剩余风险,停止分析;不要将它们淹没在推测性的相关关注点中。报告无任何可操作发现是合理的。主动提出的结构性建议最多不超过三个。
对于实现,完成请求的结果,仅解释重要决策,根据宿主现有设置运行适合仓库和风险的检查,并单独报告无关的故障。不要悄然扩大编辑范围到类似站点、依赖、CI或公开契约;若有用,报告已确认的超出范围的情况。
Load references selectively
选择性加载参考资料
| Concern | Read |
|---|---|
| ownership, boundaries, Clean Architecture tools, evolution, reuse, migrations | Boundaries and evolution |
| persistence, transactions, effects, retries, concurrency, resources | Data, concurrency, and effects |
| tests, legacy work, operations, performance, rollout, durable learning | Testing, maintenance, and operations |
| authorization, tenancy, injection, unsafe I/O, secrets, dependencies | Security and trust |
| local design/readability, Python typing/runtime/packaging/idioms, and conditional library choices | Python runtime and ecosystem |
In mixed Python/JS/TS work, use both language skills only when the contract or implementation
crosses languages. Synthesize one source of truth, serialization/validation rules, compatibility
obligations, and combined verification; do not settle for two unrelated local answers.
| 关注点 | 阅读链接 |
|---|---|
| 所有权、边界、整洁架构工具、演进、复用、迁移 | 边界与演进 |
| 持久化、事务、影响、重试、并发、资源 | 数据、并发与影响 |
| 测试、遗留工作、操作、性能、推出、持久化学习 | 测试、维护与操作 |
| 授权、租户、注入、不安全I/O、机密、依赖 | 安全与信任 |
| 本地设计/可读性、Python类型/运行时/打包/惯用写法,以及条件库选择 | Python运行时与生态系统 |
在Python/JS/TS混合工作中,仅当契约或实现跨语言时才同时使用两种语言技能。整合单一可信数据源、序列化/验证规则、兼容性义务和联合验证;不要满足于两个无关的本地答案。
Fallbacks and completion check
回退方案与完成检查
- With only a snippet or no repository, reason locally, state assumptions, and avoid repository-wide architecture prescriptions.
- When tests, runtime execution, or current primary sources are unavailable, do not claim the affected guarantee is verified; give the narrowest useful verification step.
- When conventions, executable behavior, and declared contracts conflict, distinguish what each proves and expose the unresolved conflict.
- For generated or vendored code, locate the maintained source of truth before recommending a direct edit.
- Treat suspicious but unreachable code as cleanup or residual risk, not a live severe defect. A review may legitimately have no actionable findings.
Before finishing, confirm that the answer or change stays within the actual task unit, every finding
has a reachable mechanism and inspected evidence, every recommendation beats the cheaper alternative
over the relevant horizon, library claims match the repository/version, and verification is
sufficient or explicitly limited.
- 若仅提供代码片段或无代码仓库,进行本地推理,说明假设,避免提出仓库级架构建议。
- 当测试、运行时执行或当前主要来源不可用时,不要声称已验证受影响的保证;给出最窄的有用验证步骤。
- 当约定、可执行行为和声明的契约冲突时,区分各自证明的内容并暴露未解决的冲突。
- 对于生成或第三方依赖代码,在建议直接编辑前找到维护中的可信数据源。
- 将可疑但无法触发的代码视为清理项或剩余风险,而非活跃的严重缺陷。审查可能确实没有可操作的发现。
完成前,确认答案或变更保持在实际任务单元内,每个发现都有可触发的机制和检查过的证据,每个建议在相关周期内优于更廉价的替代方案,库声明与仓库/版本匹配,验证足够或明确受限。
Small example
小示例
A long service function is not a finding by itself. Trace it. If it only sequences a short, stable
operation, leave it alone. If multiple entry points duplicate a balance invariant, transaction
ownership is unclear, and every new payment method edits the same branching block, name that
pressure. Compare a local extraction, a value/domain object, a strategy boundary, and a use-case
object; choose the smallest option that centralizes the invariant and verify it with unit tests plus
the real persistence semantics that enforce the update. Do not prescribe a canonical folder tree.
一个冗长的服务函数本身并非问题。追踪它的逻辑。如果它仅执行简短、稳定的操作序列,无需改动。如果多个入口点重复了余额不变量,事务所有权不明确,且每个新支付方式都要修改同一个分支块,说明这种变更压力。比较本地提取、值/领域对象、策略边界和用例对象;选择能集中不变量的最小选项,并用单元测试加上强制执行更新的实际持久化语义进行验证。不要规定标准化的文件夹结构。