codebase-design

代码库设计

按照用户偏好的风格设计和实现代码。本次运行将 ../coding-standards/ 视为权威标准包。

步骤

1. 加载核心设计标准。

   • 始终阅读 ../coding-standards/PRINCIPLES.md、../coding-standards/VOCABULARY.md 和 ../coding-standards/MODULES.md。
   • 完成标准：在提出结构之前，了解设计优先级、架构词汇、模块惯例和 Seam 规则。

2. 设计前审查本地惯例。

   • 检查现有的模块布局、错误处理、Schema 解析、依赖注入、适配器、可观测性、测试、工具链和平台 Seam 方面的选择。
   • 合适时复用匹配的领域概念、解析器、适配器、服务和 Prelude 辅助工具。
   • 完成标准：每种新模式、库、适配器或抽象都已对照本地先例进行检查。

3. 加载相关主题标准，并用领域术语界定问题。

   • 当任务涉及相关主题时，阅读 ../coding-standards/TYPESCRIPT.md、../coding-standards/CLOUDFLARE.md 或 ../coding-standards/EFFECT.md。
   • 识别领域概念、不变量、生命周期状态、信任 Seam、预期失败、运行时跳转、持久化 Seam、取消／重试路径和验证义务。
   • 优先使用用户的词汇：预期失败、适配器、接口、Seam、深度、深模块、杠杆效应、局部性、状态机、函数式核心、命令式外壳、真实 Seam 测试等。
   • 完成标准：设计问题以领域行为和 Seam 来表述；选择设计的每个相关部分之前，都已加载对应主题文件。

4. 选择最简单的深层设计。

   • 在可行时，让非法状态无法表示。
   • 尽早解析，并向内部传递精确值。
   • 保持函数式核心行为不依赖入口点。
   • 将 I/O、框架转换、遥测、时间／随机数和依赖构造放在命令式外壳或组合 Seam 中。
   • 优先采用内聚的深模块、狭窄的依赖接口，以及 Effect 之外的构造函数注入；在 Effect 代码库中使用 Effect 服务／层。
   • 避免推测性 Seam、浅层包装器、依赖包、每张表一个仓库的惯例，以及顺手进行的迁移。
   • 对于影响重大的接口，先勾勒两到三种实质不同的接口形式，再作选择；当设计空间足够广、可从独立尝试中受益时，使用并行 Agent。
   • 完成标准：每个提议的模块／接口都能通过减轻调用方负担、维护不变量、提升杠杆效应／局部性，或转换真实 Seam 来证明其 Seam 的必要性。

5. 同步设计失败处理、异步行为和验证方案。

   • 预期失败应是类型化值；不可恢复的缺陷可以抛出异常。
   • 在可达的路径中，将取消和重试视为一等要素。
   • 可变更／可重试的工作应具备幂等性或原子性策略。
   • 验证应通过真实 Seam 检查可观察行为，并在有用时使用属性测试验证一般不变量。
   • 完成标准：计划涵盖有意义的失败路径、并发／重试风险，以及建立信任所需的证据。

6. 按要求在本地按比例实现。

   • 以满足设计要求为准，尽可能缩小改动范围。
   • 遵循既有项目风格，除非它与正确性、安全性、可调试性或用户的明确要求相冲突。
   • 运行或建议相关检查／测试。
   • 完成标准：实现、测试和交接均遵循本地惯例，同时推动改动区域向这些标准靠拢。

输出结构

对于仅涉及设计的工作，如果任务规模足以从中受益，请按以下结构回复；对于较小的任务，仅保留相关要点：

• 领域模型和不变量
• 建议的模块／边界
• 边界／故障／异步处理策略
• 验证计划
• 权衡和未采纳的替代方案

对于实现工作，请返回：

• 变更内容的简要摘要
• 已做出的标准敏感型决策
• 已运行或未运行的测试／检查
• 后续风险（如有）