superior-logic

Superior Logic

让正确性从输入到可观察结果始终清晰可见。让解决方案契合仓库现有架构，并同步更新契约影响到的各方。

如果主要目标是检查差异、提交、分支、拉取请求或工作区并找出问题，请改用 superior-code-review。如果要进行聚焦于领域逻辑的审查，或实现已确认的行为变更，请使用此技能。

建模行为

选择代码方案之前，请明确：

• 受信任和不受信任的输入；
• 输出和可观察的副作用；
• 不变量和授权规则；
• 使用方和兼容性约束；
• 预期的失败、重试、重复、顺序和并发情况。

只有当代码和文档都无法确定重要假设时，才明确说明该假设。如果不同答案会改变产品契约，请询问用户。

如果要更改可能跨越多个版本、重试或部分部署的共享 API、事件、文件格式、客户端／服务端契约、状态机或多步骤工作流，请阅读 references/contract-evolution-and-workflows.md。

明确职责归属

• 在现有架构支持的情况下，将领域决策与渲染、传输和持久化分离。
• 在数据进入受信任系统的边界处进行验证。客户端验证可以改善体验，但不能保证服务端正确性。
• 为状态转换保留唯一的权威所有者；通过推导生成依赖状态，而不是同步多个副本。
• 当共享架构和类型是仓库的事实来源时，应使用它们。
• 更改共享契约时，应同步更改生产方、消费方、验证逻辑、测试和文档。

保护状态和副作用

• 如果部分完成会破坏不变量，就让相关写入保持原子性；否则应定义可恢复的部分状态或补偿机制。
• 如果重试或重复投递可能导致重复创建、重复扣费或数据损坏，就让可重复操作具备幂等性。
• 在任务可能发生竞争时，定义顺序和并发行为。任意延迟不能替代同步。
• 对远程任务使用超时、取消和有界重试，并遵循项目既有模式；只重试瞬时故障。
• 在安全的前提下，预期故障发生后应保留用户输入并提供有用的恢复选项。

如果架构设计、查询形态、索引、事务隔离、迁移、回填或数据存储的发布安全性成为请求的主要部分，请加载 superior-database。如果底层数据契约未改变，常规持久化编排仍归此技能负责。

如果延迟、吞吐量、资源使用、容量或可扩展性是需要测量和分析的主要关注点，请加载 superior-performance。常规的有界处理和避免明显不必要的工作仍属于此技能。

如果服务目标、故障隔离、优雅降级、故障转移或运维恢复是主要关注点，请加载 superior-reliability。如果任务负责流水线、制品、环境晋级、发布或回滚行为，请加载 superior-delivery。

在可信边界强制执行安全措施

• 身份验证用于识别调用方；授权仍需针对每项资源和操作进行控制。
• 尽可能将读写范围限制在已获授权的主体内。
• 将路由参数、标头、隐藏字段、文件名、客户端状态、Webhook 和外部负载视为不可信数据。
• 使用维护良好的库处理凭据和密码学。切勿自行设计令牌、加密、签名或密钥存储方案。
• 不要在日志和面向用户的错误信息中记录密钥、敏感个人数据和支付详情。

当请求涉及 API 加固、速率限制、令牌安全、滥用防范、SSRF 或专门的安全审查时，加载 superior-api-security。由 superior-logic 负责领域契约和不变量；使用安全技能实施由威胁驱动的控制措施并进行负向验证。

诊断原因不明的故障

当存在具体故障，但其原因不明、受环境影响、间歇性出现或需要追溯因果关系时，加载 superior-debugging。确定原因后，对于范围内涉及领域规则、状态、持久化或 API 行为的修复，使用此技能。对于原因已明确的简单实现缺陷，无需采用专门的调试工作流。

确保故障可观测

• 在能够恢复、转换错误或补充有用上下文的层级处理错误。
• 包装错误时保留原始原因。
• 切勿将未知故障转换为成功，也不要仅为让流程继续而吞掉故障。
• 向用户提供安全且可采取行动的信息，并通过项目既定的可观测性路径发送诊断详情。
• 限制依赖数据的循环、队列、结果集、递归、重试和内存累积。

验证契约

测试可观察到的行为，而非私有步骤。覆盖正常路径，以及此次更改影响的重要边界、无效输入、授权、部分失败、重复、重试或并发情形。在可行时，用针对性失败测试复现缺陷。

当请求主要涉及测试设计、测试层级选择、夹具、测试替身、不稳定行为或测试套件可靠性时，加载 superior-testing。常规实现验证仍属于此技能的范围，无需加载专门的测试工作流。

当需要围绕多步骤用户旅程、信息架构、反馈或恢复体验来设计领域行为时，加载 superior-ux。由此技能负责可强制执行的状态转换、不变量、API 和持久化。

遵循现有测试惯例，并运行范围最小且相关的 lint、类型检查、测试和构建检查。明确说明未经验证的情况和兼容性风险。

报告最终契约、受影响的生产方和消费方、故障行为、兼容性或推出假设，以及实际执行的检查。除非实现和底层系统能够证明，否则不要将工作流描述为原子性或恰好一次。