coding-standards

TypeScript 和 Effect 编码规范

构建正确性由构造保证的代码：将数据解析为有意义的类型，明确表示预期失败，将副作用置于内聚的服务之后，并通过真实接口进行测试。

决策优先级

当规则相互冲突时：

1. 优先保证正确性、安全性和可调试性。
2. 将这些规范应用于新代码和正在更改的完整行为。
3. 遵循兼容的仓库架构和约定。
4. 在最近的现有边界处隔离不兼容的旧模式。
5. 除非要求进行更广泛的迁移，否则保持无关行为不变。
6. 在所属代码旁或仓库现有的决策文档中记录重要的权衡。

核心原则

• 预期失败应表示为值；缺陷可以抛出异常或触发 panic。
• 保留已有的类型证据；解析外部表示，并在其所属位置建立新的不变量。
• 在可行时，让非法状态无法表示。
• 从明确的接口开始构建有意义的服务。
• 优先采用组合、函数式核心和命令式外壳。
• 使用删除测试来保持模块内聚，并降低调用方的负担。
• 通过真实接口，使用真实或忠实的实现测试行为，而不是模拟模块。

1. 明确本地规则

阅读最近的 AGENTS.md、软件包配置、架构文档，以及变更区域在错误处理、架构、服务、测试、可观测性和文件方面的约定。

当本地约定与这些规范冲突时，按照上述决策优先级处理。仓库策略可以进一步收紧这些约束；现有的公开兼容性仍是设计限制。阅读实际生效的 lint 配置和插件入口，以确认规则是否已启用，不要把示例或提案当作已安装的规则。

**完成标准：**已确认适用的文件和运行时／库版本，并已处理所有影响变更行为的兼容或不兼容本地模式。

2. 追踪行为并加载适用的参考文档

追踪每项调用方可见操作，从输入开始，经过每个决策和影响，直到可观察到的结果。将每项变更涉及的问题归类为领域行为、应用策略、技术／框架机制或组合／资源装配。

设计变更前，请完整阅读所有适用的参考文档：

• references/effect.md — 任何 Effect 代码变更都适用；编辑前请遵循其中的分支指引。
• references/effect-alchemy.md — 变更 Alchemy Worker、Durable Object、Workflow、基于绑定的服务或两阶段运行时组合时适用。
• references/errors.md — 行为可能失败或缺失可能属于正常情况时适用。
• references/sensitive-data-and-observability.md — 行为涉及机密、个人数据、日志记录、追踪、指标或错误报告时适用。
• references/parsing-and-schemas.md — 数据跨越外部／序列化边界、添加／移除解析或验证，或架构／表示形式发生变更时适用。
• references/domain-types-and-state.md — ID、单位、受约束值、可选输入、实体、生命周期状态或操作选项发生变更时适用。
• references/modules-services-and-adapters.md — 分配职责、提取辅助函数、降低复杂度，或变更依赖项、模块／服务设计或 Effect 顺序时适用。
• references/persistence.md — 行为读取或写入数据库、缓存、持久化对象、ORM 模型、事务或持久化记录时适用。
• references/workflows-transactions-and-idempotency.md — 工作跨越边界、重试、恢复、接收重新投递、延迟、补偿或可能执行多次时适用。
• references/configuration-and-resources.md — 行为读取配置、创建／关闭资源、执行启动工作、使用时间／随机性或触及全局状态时适用。
• references/testing.md — 行为、公共类型推断、测试或测试实现发生变更时适用。
• references/typescript-safety.md — 类型、签名、可变值、类型断言、非空假设或编译器设置发生变更时适用。
• references/lint-and-policy.md — 变更 lint 配置、编写规则，或评估解析器／复杂度／未使用导出预防工具时适用。
• references/imports-exports-and-files.md — 导入、导出、入口点、辅助函数位置或文件组织发生变更时适用。
• references/comments-and-jsdoc.md — 导出符号、注释、JSDoc、面向用户的文本或呈现的错误发生变更时适用。

完成标准： 每项变更涉及的输入、输出、失败、依赖项、影响、状态转换、外部表示形式和测试范围，都能对应到一个负责模块和适用的参考文档。

3. 从公共类型向内设计

在实现之前，先定义或确认面向调用方的输入、输出、预期错误和服务接口。参照解析参考文档，追踪输入来源和剩余不变量；在内部代码中保留精确类型。保持领域计算纯粹。将应用策略和副作用顺序放在所属服务中。框架／提供方类型应仅对其所属方可见。

添加新模块、服务、客户端、Adapter、架构、错误或辅助工具之前，先检查现有内容。应用删除测试：如果移除某个抽象会将有意义的复杂性扩散到调用方，那么该抽象才有存在的价值。对于每个新抽象，记录已考虑的现有归属方或直接实现，并说明其不适用的原因。

**完成条件：**面向调用方的输入、输出、预期错误和服务接口均已明确；每个变更的依赖项和副作用都各有归属方；每个新抽象都有删除测试的证据，可供最终报告使用；框架／提供方类型仅对其所属方可见。

4. 实现完整的变更行为

实现调用方可见操作所需的所有路径，包括预期失败、外部转换、诊断信息和资源行为。保持无关的旧行为不变。保留现有且兼容的遥测和错误报告钩子。

**完成条件：**每条追踪到的路径都通过其所属接口实现；预期失败使用显式错误值；外部数据以已解析类型传入内部代码；公共应用／领域契约公开的是应用／领域类型。

5. 通过公共接口验证

根据 references/testing.md 添加或更新所需测试。运行仓库要求的验证命令；仅在尚未涵盖时，才额外运行单独的类型检查、测试、构建或 lint 命令。清理代码时，要区分已移除的运行时工作与仅涉及 API／类型的变更；比较公共行为、失败／恢复语义和类型推断，不要把解码器数量或分支数量减少视为证明。重新阅读每份适用的参考文档，并逐一对照检查每个变更的符号。修正每个不符合项，或提供具体证据并报告。

**完成条件：**所有必需检查均已通过，或其失败情况均附有具体证据并已报告；所有适用的参考规则均已检查；每项调用方可见功能均有其所需的覆盖；每个新增或变更的导出项均为有意修改，且已具备 references/comments-and-jsdoc.md 要求的文档；变更行为中的每个抽象、辅助工具和类型断言都是必需的，并符合其适用参考文档的要求；所有变更均在请求范围内。