coding-standards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript and Effect Coding Standards

TypeScript 与 Effect 编码标准

Build correct by construction: parse data into meaningful types, make expected failures explicit, keep effects behind cohesive services, and test through real interfaces.

遵循构造即正确原则：将数据解析为有意义的类型，明确预期失败，将副作用封装在内聚的服务之后，通过真实接口进行测试。

Decision priority

决策优先级

When rules pull in different directions:

Preserve correctness, safety, and debuggability.
Apply these standards to new code and the complete behavior being changed.
Follow compatible repository architecture and conventions.
Contain incompatible older patterns at the nearest existing edge.
Keep unrelated behavior unchanged unless a broader migration was requested.
Record meaningful trade-offs beside the owning code or in the repository's existing decision documentation.

当不同规则之间存在冲突时，按以下优先级处理：

优先保障正确性、安全性与可调试性。
新标准适用于新代码以及被修改的完整逻辑。
遵循代码库中兼容的架构与约定。
将不兼容的旧模式限制在最近的现有边界内。
除非要求进行更广泛的迁移，否则不修改无关逻辑。
在所属代码旁或代码库现有的决策文档中记录有意义的权衡取舍。

Core principles

核心原则

Expected failures are values; defects may throw or panic.
Preserve established type evidence; parse external representations and establish new invariants at their owner.
Make illegal states unrepresentable where practical.
Start meaningful services from explicit interfaces.
Prefer composition, a functional core, and an imperative shell.
Use the deletion test to keep cohesive modules with low caller burden.
Test behavior through real interfaces using real or faithful implementations rather than module mocks.

预期失败是值；缺陷可以抛出或触发panic。
保留已确立的类型证据；解析外部表示，并在其所属模块中建立新的不变量。
在可行的情况下，让非法状态无法被表示。
从显式接口出发构建有意义的服务。
优先使用组合、函数式核心与命令式外壳的架构模式。
使用“删除测试”来保证模块内聚，降低调用方负担。
通过真实接口测试行为，使用真实或高保真的实现而非模块mock。

1. Establish the local rules

1. 确立本地规则

Read the nearest

AGENTS.md

, package configuration, architecture docs, and the changed area's conventions for errors, schemas, services, tests, observability, and files.

Apply the decision priority above when local conventions conflict with these standards. Repository policy may tighten these guardrails; existing public compatibility remains a design constraint. Read active lint configuration and plugin entrypoints for enforcement rather than treating examples or proposals as installed rules.

Complete when: the governing files and runtime/library versions have been identified, and every compatible or incompatible local pattern touching the changed behavior is accounted for.

阅读最近的

AGENTS.md

、包配置、架构文档，以及待修改区域在错误处理、schema、服务、测试、可观测性和文件组织方面的约定。

当本地约定与本标准冲突时，遵循上述决策优先级。代码库的策略可能会收紧这些约束；现有的公共兼容性仍然是设计约束之一。请读取当前生效的lint配置和插件入口来确定实际执行的规则，不要将示例或提案当作已落地的规则。

完成条件： 已确定所有管控文件和运行时/库版本，且所有涉及修改逻辑的本地模式（无论兼容与否）都已梳理清楚。

2. Trace the behavior and load applicable references

2. 梳理逻辑链路并加载适用参考文档

Trace each caller-visible operation from input through every decision and effect to its observable result. Classify each changed concern as domain behavior, application policy, technology/framework mechanics, or composition/resource wiring.

Read every applicable reference completely before designing the change:

```
references/effect.md
```
— whenever Effect code changes; follow its branch pointers before editing.
```
references/effect-alchemy.md
```
— when an Alchemy Worker, Durable Object, Workflow, binding-backed service, or two-phase runtime composition changes.
```
references/errors.md
```
— when behavior can fail or absence may be ordinary.
```
references/sensitive-data-and-observability.md
```
— when behavior handles secrets, personal data, logging, tracing, metrics, or error reporting.
```
references/parsing-and-schemas.md
```
— when data crosses an external/serialized edge, parsing or validation is added/removed, or a schema/representation changes.
```
references/domain-types-and-state.md
```
— when IDs, units, constrained values, optional inputs, entities, lifecycle states, or operation options change.
```
references/modules-services-and-adapters.md
```
— when assigning ownership, extracting helpers, reducing complexity, or changing dependencies, module/service design, or effect order.
```
references/persistence.md
```
— when behavior reads or writes a database, cache, durable object, ORM model, transaction, or persisted record.
```
references/workflows-transactions-and-idempotency.md
```
— when work spans boundaries, retries, resumes, receives redelivery, delays, compensates, or may execute more than once.
```
references/configuration-and-resources.md
```
— when behavior reads configuration, creates/closes resources, performs startup work, uses time/randomness, or touches global state.
```
references/testing.md
```
— whenever behavior, public inference, tests, or test implementations change.
```
references/typescript-safety.md
```
— when types, signatures, mutable values, casts, non-null assumptions, or compiler settings change.
```
references/lint-and-policy.md
```
— when changing lint configuration, writing rules, or evaluating parser/complexity/unused-export prevention tooling.
```
references/imports-exports-and-files.md
```
— when imports, exports, entrypoints, helper placement, or file organization change.
```
references/comments-and-jsdoc.md
```
— when exported symbols, comments, JSDoc, user-facing text, or rendered errors change.

Complete when: every changed input, output, failure, dependency, effect, state transition, external representation, and test surface maps to an owning module and an applicable reference.

从输入开始追踪每个对调用方可见的操作，经过所有决策和副作用，直到其可观测结果。将每个被修改的关注点归类为领域逻辑、应用策略、技术/框架机制，或组合/资源编排。

在设计修改方案之前，完整阅读所有适用的参考文档：

```
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
```
— 数据跨越外部/序列化边界、新增/移除解析或校验逻辑，或schema/表示形式发生变化时。
```
references/domain-types-and-state.md
```
— 涉及ID、单位、约束值、可选输入、实体、生命周期状态或操作选项修改时。
```
references/modules-services-and-adapters.md
```
— 涉及分配归属、提取辅助函数、降低复杂度，或修改依赖、模块/服务设计、副作用执行顺序时。
```
references/persistence.md
```
— 逻辑涉及读写数据库、缓存、durable object、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. Design from the public types inward

3. 从公共类型向内设计

Define or confirm the caller-facing input, output, expected errors, and service interfaces before implementing them. Trace input provenance and remaining invariants using the parsing reference; retain precise types through inner code. Keep domain calculations pure. Put application policy and effect order in the owning service. Keep framework/provider types private to their owner.

Check existing modules, services, clients, Adapters, schemas, errors, and helpers before adding one. Apply the deletion test: an abstraction earns its place when removing it would spread meaningful complexity into callers. For each new abstraction, record the existing owner or direct implementation considered and why it does not fit.

Complete when: caller-facing inputs, outputs, expected errors, and service interfaces are explicit; every changed dependency and effect has one owner; each new abstraction has deletion-test evidence for the final report; and framework/provider types remain private to their owner.

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

在新增模块、服务、客户端、Adapter、schema、错误类型和辅助函数之前，先检查是否已有现成实现。应用删除测试：如果移除某个抽象会导致调用方的有效复杂度增加，那么这个抽象就有存在的价值。对于每个新增的抽象，记录曾考虑过的现有所属模块或直接实现，以及它们不适用的原因。

完成条件： 面向调用方的输入、输出、预期错误和服务接口均已明确；每个被修改的依赖和副作用都有唯一归属；每个新增抽象都有删除测试的依据，可用于最终报告；框架/提供方的类型仍仅在其所属模块内部可见。

4. Implement the complete changed behavior

4. 实现完整的修改逻辑

Implement every path required by the caller-visible operation, including expected failures, external translations, diagnostics, and resource behavior. Keep unrelated old behavior unchanged. Preserve existing compatible telemetry and error-reporting hooks.

Complete when: every traced path is implemented through its owning interface; expected failures use explicit error values; external data reaches inner code as parsed types; and public application/domain contracts expose application/domain types.

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

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

5. Verify through public interfaces

5. 通过公共接口验证

Add or update the tests required by

references/testing.md

. Run the repository's required verification commands, adding individual typecheck, test, build, or lint commands only when they are not already covered. For cleanup, distinguish runtime work removed from API/type-only changes; compare public behavior, failure/recovery semantics, and inference rather than treating lower decoder or branch counts as proof. Re-read each applicable reference and check every changed symbol against it. Fix each exception or report it with concrete evidence.

Complete when: every required check passes or has a reported failure with concrete evidence; every applicable reference rule has been checked; every caller-visible feature has its required coverage; every added or changed export is intentional and has the documentation required by

references/comments-and-jsdoc.md

; each abstraction, helper, and cast in the changed behavior is required and conforms to its applicable reference; and all changes remain within the requested scope.

根据

references/testing.md

的要求新增或更新测试。运行代码库要求的验证命令，仅当现有命令未覆盖时，才添加单独的typecheck、test、build或lint命令。在清理代码时，区分移除的运行时逻辑与仅涉及API/类型的修改；对比公共行为、失败/恢复语义和类型推导，不要将更低的解码器数量或分支数量当作正确性证明。重新阅读每篇适用的参考文档，并对照检查每个被修改的符号。修复每个异常，或附上具体证据上报。

完成条件： 所有要求的检查均已通过，或已上报失败并附上具体证据；所有适用的参考文档规则都已检查；每个对调用方可见的功能都达到了要求的覆盖率；每个新增或修改的导出都是有意为之，且具备

references/comments-and-jsdoc.md

要求的文档；修改逻辑中的每个抽象、辅助函数和类型转换都是必要的，且符合适用的参考文档；所有修改都在请求的范围内。