creating-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating Spec

规范创建

Systematic workflow for creating comprehensive technical specifications that centralize scattered functionality, fill SDK gaps, or plan new feature modules. This skill encodes the proven process used to produce high-quality specs like session-management and tool-registry-bridge specs.

<critical_rules>

用于创建全面技术规范的系统性工作流，可实现分散功能集中化、填补SDK缺口或规划新功能模块。该技能整合了经实践验证的流程，可产出如会话管理、工具注册桥接等高质量规范文档。

<critical_rules>

MANDATORY WORKFLOW

强制工作流

You MUST follow these phases in order. Skipping phases or combining them will produce incomplete specs.

你必须按顺序遵循以下阶段。跳过阶段或合并阶段会导致规范不完整。

Phase 1: DEEP EXPLORATION (output only, no writes)

阶段1：深度探索（仅输出，不写入）

Goal: Map the full landscape of existing code across ALL relevant codebases before proposing anything.

Launch parallel exploration agents (4-5 simultaneous) covering:
- The target package where the spec will be implemented (e.g.,
```
providers/sdk
```
  )
- The reference implementation that has the most complete version (e.g.,
```
providers/runtime
```
  )
- Consumer codebases that have their own versions (e.g.,
```
packages/electron/src/agents/
```
  ,
```
packages/electron/src/looper/
```
  )
- Any shared packages that contain related types or utilities (e.g.,
```
packages/types
```
  )
Each explorer must report:
- File paths with key types/interfaces
- How components connect and interact
- What patterns are used (Effect services, Context.Tag, factories, etc.)
- Duplication and fragmentation across codebases
MANDATORY: Read the key files directly after exploration to verify findings. Do NOT rely solely on explorer summaries for type signatures or API shapes.
Present findings FIRST — show the user:
- A cross-codebase comparison table (what exists where)
- A duplication map (what's doing the same thing in multiple places)
- What should be centralized vs. what should stay where it is
- Clear identification of gaps

FORBIDDEN: Writing any files during Phase 1. Output analysis to chat only.

目标：在提出任何方案前，梳理所有相关代码库中的现有代码全貌。

启动并行探索Agent（4-5个同时运行），覆盖范围包括：
- 规范将落地的目标包（例如：
```
providers/sdk
```
  ）
- 拥有最完整实现版本的参考代码（例如：
```
providers/runtime
```
  ）
- 各自实现了相关功能的消费端代码库（例如：
```
packages/electron/src/agents/
```
  、
```
packages/electron/src/looper/
```
  ）
- 包含相关类型或工具的共享包（例如：
```
packages/types
```
  ）
每个探索Agent必须汇报：
- 包含关键类型/接口的文件路径
- 组件间的连接与交互方式
- 使用的设计模式（Effect服务、Context.Tag、工厂模式等）
- 跨代码库的重复与碎片化情况
强制要求：探索完成后直接阅读关键文件以验证结果。不要仅依赖探索Agent的摘要来获取类型签名或API结构。
先展示探索结果——向用户呈现：
- 跨代码库对比表（各功能的分布位置）
- 重复代码映射表（哪些功能在多个位置重复实现）
- 哪些功能应集中化、哪些应保留在原位置
- 明确的缺口识别

禁止：在阶段1中写入任何文件。仅在聊天中输出分析内容。

Phase 2: CLARIFICATION (ask questions before writing)

阶段2：需求澄清（编写前先提问）

Goal: Resolve design decisions that affect the spec's architecture.

Use the AskUserQuestion tool to ask 2-4 focused questions about:
- Scope decisions (full replacement vs. building blocks vs. thin wrapper)
- Automation level (fully automatic vs. manual vs. hybrid)
- Backward compatibility concerns (native support vs. consumer handles)
- What to include vs. exclude from the centralized module
Question format:
- Each question should have 2-3 concrete options with descriptions
- Mark the recommended option with "(Recommended)"
- Options should represent genuinely different architectural choices, not trivial preferences
MANDATORY: Wait for user answers before proceeding. Do NOT assume defaults.

FORBIDDEN: Asking more than 4 questions at once. Keep it focused on decisions that materially affect the spec.

目标：解决影响规范架构的设计决策问题。

使用AskUserQuestion工具提出2-4个聚焦问题，涉及：
- 范围决策（完全替换、构建基础模块还是轻量封装）
- 自动化程度（全自动化、手动或混合模式）
- 向后兼容性考量（原生支持还是由消费端处理）
- 集中化模块应包含/排除的内容
问题格式：
- 每个问题需提供2-3个带描述的具体选项
- 用"(推荐)"标记推荐选项
- 选项应代表真正不同的架构选择，而非无关紧要的偏好
强制要求：等待用户答复后再继续。不要假设默认值。

禁止：一次提出超过4个问题。聚焦于对规范有实质性影响的决策。

Phase 3: SPEC WRITING

阶段3：规范编写

Goal: Write a comprehensive specification at the right level of abstraction — behavioral contracts and architectural decisions, not implementation code.

Check existing spec format — Read any previous specs in the same directory (e.g.,
```
tasks/prd-sdk/1_*.md
```
,
```
tasks/prd-sdk/2_*.md
```
) to match the established style and structure.
Write the spec following the template structure below.
MANDATORY sections (all must be present):
- Problem Statement (what's broken/duplicated, what it costs today)
- Design overview (architecture diagram in ASCII, high-level flow)
- New files (directory structure)
- Detailed API specifications (interfaces, types, service tags)
- What this replaces (file-by-file mapping of what changes where)
- Interaction with existing systems (how it coexists with what's already there)
- Public API surface (explicit exports list)
- High-Level Implementation Overview (consumer-facing code examples)
- Testing strategy (unit + integration test plans)
- Implementation order (numbered steps with dependencies and parallelization)
- Migration path (phased rollout for existing consumers)
- What does NOT move (explicit exclusion list with reasons)

目标：编写抽象程度恰当的全面规范——聚焦行为契约与架构决策，而非实现代码。

检查现有规范格式——阅读同一目录下的所有历史规范（例如：
```
tasks/prd-sdk/1_*.md
```
、
```
tasks/prd-sdk/2_*.md
```
），匹配已确立的风格与结构。
遵循以下模板结构编写规范。
强制包含的章节（所有章节必须存在）：
- 问题陈述（当前存在的问题/重复内容、造成的成本）
- 设计概述（ASCII架构图、高层级流程）
- 新增文件（目录结构）
- 详细API规范（接口、类型、服务标签）
- 替代内容映射（逐文件说明变更位置）
- 与现有系统的交互（如何与现有系统共存）
- 公共API表面（明确的导出列表）
- 高层级实现概述（消费端代码示例）
- 测试策略（单元测试+集成测试计划）
- 实现顺序（带依赖关系与并行化说明的编号步骤）
- 迁移路径（面向现有消费端的分阶段部署）
- 不迁移内容（明确的排除列表及原因）

Phase 3b: EFFECT-TS COMPLIANCE CHECK

阶段3b：Effect-TS合规性检查

Goal: Verify all code snippets in the spec follow Effect-TS patterns before presenting to the user.

MANDATORY: After writing the spec, audit every code snippet against the

effect-ts

and

effect-ts

skills. Check:

Import patterns: Must use

import * as Module from "effect/Module"

, never

import { X } from "effect"

Branded types: All domain primitives (IDs, keys, names) must be branded via
```
Schema.String.pipe(Schema.brand("X"))
```
. Check existing
```
protocol/branded.ts
```
for established patterns.
Schema class patterns:
```
Schema.Class
```
for records,
```
Schema.TaggedClass
```
for discriminated variants (events, status types). Check how existing events in
```
protocol/events.ts
```
are defined and match exactly.

No
Schema.Unknown
: Use

JsonValue

JsonObject

(from

protocol/shared.ts

), or

Schema.Defect

(for wrapping external errors). Never

Schema.Unknown

or bare

unknown

in types.

No
Schema.Enums
: Use
```
Schema.Literal("a", "b", "c")
```
for string literal unions.
```
Schema.Enums
```
is only for TypeScript
```
enum
```
types.
No
Schema.suspend
: Only for recursive types. Not needed for referencing other schemas.
Service pattern: Services must use
```
Context.Tag
```
with static factory methods and static
```
layer
```
. Never module-scoped functions for service logic or layer factories.
Static helpers: Helper/utility functions must be static methods on a helper class (e.g.,
```
MyHelpers.resolve()
```
), not module-scoped
```
export const
```
functions.
Effect.fn
tracing: All service method implementations must specify
```
Effect.fn("ServiceName.methodName")
```
for observability. Note this requirement explicitly in the spec.
Error handling: Domain errors use
```
Schema.TaggedError
```
. Unknown external errors wrapped with
```
Schema.Defect
```
. No
```
unknown
```
in error channels.
Secrets: API keys and sensitive values use
```
Redacted.Redacted
```
, not plain
```
string
```
.
Testability: Use
```
Clock.currentTimeMillis
```
instead of
```
Date.now()
```
or raw
```
clock
```
callbacks. Effect's
```
TestClock
```
handles test time control.
Immutable state: Service state must be held in
```
Ref
```
or
```
SynchronizedRef
```
, not mutable
```
Map
```
/
```
Set
```
. Prefer
```
HashMap.HashMap
```
from Effect.
Schema.Class construction: When returning instances of
```
Schema.Class
```
types, always use
```
new ClassName({...})
```
constructors, not plain object literals.

目标：向用户呈现规范前，验证所有代码片段是否遵循Effect-TS模式。

强制要求：编写完规范后，对照

effect-ts

及相关技能审核每个代码片段，检查以下内容：

导入模式：必须使用

import * as Module from "effect/Module"

，禁止使用

import { X } from "effect"

品牌化类型：所有领域原语（ID、键、名称）必须通过
```
Schema.String.pipe(Schema.brand("X"))
```
实现品牌化。参考现有
```
protocol/branded.ts
```
中的既定模式。
Schema类模式：记录类型使用
```
Schema.Class
```
，区分变体（事件、状态类型）使用
```
Schema.TaggedClass
```
。参考
```
protocol/events.ts
```
中现有事件的定义方式并完全匹配。
禁止使用Schema.Unknown：使用
```
JsonValue
```
、
```
JsonObject
```
（来自
```
protocol/shared.ts
```
）或
```
Schema.Defect
```
（用于包装外部错误）。禁止在类型中使用
```
Schema.Unknown
```
或裸
```
unknown
```
。
禁止使用Schema.Enums：字符串字面量联合类型使用
```
Schema.Literal("a", "b", "c")
```
。
```
Schema.Enums
```
仅适用于TypeScript的
```
enum
```
类型。
禁止滥用Schema.suspend：仅用于递归类型，引用其他Schema时无需使用。
服务模式：服务必须使用
```
Context.Tag
```
搭配静态工厂方法和静态
```
layer
```
。禁止使用模块级函数实现服务逻辑或层工厂。
静态工具函数：工具/实用函数必须作为辅助类的静态方法（例如：
```
MyHelpers.resolve()
```
），禁止使用模块级
```
export const
```
函数。
Effect.fn追踪：所有服务方法实现必须指定
```
Effect.fn("ServiceName.methodName")
```
以支持可观测性。需在规范中明确注明此要求。
错误处理：领域错误使用
```
Schema.TaggedError
```
。未知外部错误使用
```
Schema.Defect
```
包装。错误通道中禁止使用
```
unknown
```
。
敏感信息：API密钥和敏感值使用
```
Redacted.Redacted
```
，而非普通
```
string
```
。
可测试性：使用
```
Clock.currentTimeMillis
```
替代
```
Date.now()
```
或原生
```
clock
```
回调。Effect的
```
TestClock
```
负责测试时间控制。
不可变状态：服务状态必须存储在
```
Ref
```
或
```
SynchronizedRef
```
中，而非可变的
```
Map
```
/
```
Set
```
。优先使用Effect的
```
HashMap.HashMap
```
。
Schema.Class实例化：返回
```
Schema.Class
```
类型实例时，必须使用
```
new ClassName({...})
```
构造函数，而非普通对象字面量。

Phase 3c: CROSS-SPEC CONSISTENCY CHECK

阶段3c：跨规范一致性检查

Goal: Ensure the new spec doesn't contradict or duplicate definitions from other specs.

MANDATORY: Before finalizing, check against all existing specs in the same directory:

No duplicate definitions: If a type, constant, or function is already defined in another spec, import it — don't redefine. Common sources of duplication:
- Provider family resolution functions
- Provider metadata key fallback maps
- Type definitions that span multiple concerns
Consistent naming: Same concept must have the same name across all specs. If Spec N defines
```
ProviderFamilyId
```
, Spec N+1 must not call it
```
OpenResponsesProviderFamily
```
.
Compatible types: If two specs extend the same interface (e.g.,
```
CompozyCallProviderOptions
```
), list ALL fields from all specs, not just yours.
Implementation ordering: If your spec depends on a type expansion from another spec (e.g.,
```
ProviderId
```
growing from 3 to 11 values), document this dependency explicitly in the Implementation Order section.
Canonical ownership: Each type/function/constant must have ONE canonical source file. The spec that defines it is the owner. All other specs that need it must say "Import from
```
src/path/file.ts
```
(defined in Spec N)".

目标：确保新规范与其他规范的定义不冲突、不重复。

强制要求：最终定稿前，检查同一目录下的所有现有规范：

无重复定义：若某类型、常量或函数已在其他规范中定义，直接导入——不要重新定义。常见重复来源：
- 供应商家族解析函数
- 供应商元数据键 fallback 映射
- 跨多个领域的类型定义
命名一致性：同一概念在所有规范中必须使用相同名称。若规范N定义了
```
ProviderFamilyId
```
，规范N+1不得将其命名为
```
OpenResponsesProviderFamily
```
。
类型兼容性：若两个规范扩展同一接口（例如：
```
CompozyCallProviderOptions
```
），需列出所有规范中的所有字段，而非仅当前规范的字段。
实现顺序依赖：若当前规范依赖其他规范的类型扩展（例如：
```
ProviderId
```
从3个值扩展到11个值），需在「实现顺序」章节中明确记录此依赖关系。
规范所有权：每个类型/函数/常量必须有唯一的规范来源。定义它的规范即为所有者，其他需要使用该内容的规范必须注明「从
```
src/path/file.ts
```
导入（定义于规范N）」。

Phase 4: HIGH-LEVEL IMPLEMENTATION (iterate if asked)

阶段4：高层级实现（按需迭代）

Goal: Show concrete consumer-facing API examples that demonstrate how the final result works.

Include in the spec a "High-Level Implementation Overview" section with:
- Setup / configuration code
- Registration / initialization code
- Usage during streaming or execution
- Direct utility usage (codec, helpers, etc.)
- Custom provider / extension example
- Before/after dependency graph (ASCII)
If user asks for this separately, present it as a concise chat response with annotated code blocks.

</critical_rules>

<spec_template>

目标：展示具体的消费端API示例，说明最终成果的工作方式。

在规范中包含「高层级实现概述」章节，内容包括：
- 设置/配置代码
- 注册/初始化代码
- 流处理或执行期间的使用示例
- 直接工具使用示例（编解码器、辅助函数等）
- 自定义供应商/扩展示例
- 前后依赖关系图（ASCII格式）
若用户单独要求此内容，以简洁的聊天回复形式呈现，并附带带注释的代码块。

</critical_rules>

<spec_template>

Spec Document Structure

规范文档结构

Follow this structure for every spec. Sections are numbered for cross-referencing.

markdown

undefined

所有规范均需遵循此结构。章节编号用于交叉引用。

markdown

undefined

[Feature Name] for [Target Package]

[功能名称] 适配 [目标包]

Problem Statement

问题陈述

What systems currently exist (list each with location)
What duplication exists (table format: concern | location A | location B | location C)
What this costs today (concrete pain points, not abstract)

当前存在的系统（列出每个系统的位置）
重复内容（表格格式：关注点 | 位置A | 位置B | 位置C）
当前造成的成本（具体痛点，而非抽象描述）

Design: [Design Name]

设计方案：[设计名称]

Architecture diagram (ASCII art showing data flow)
Key principle (e.g., "fully automatic", "opt-in", "plug-in")

架构图（展示数据流的ASCII艺术图）
核心原则（例如："全自动化"、"可选启用"、"插件化"）

New Files

新增文件

Directory tree of new files to create

1-N. Detailed Specifications

1-N. 详细规范

Each major component gets its own numbered section
Include full TypeScript interfaces with JSDoc
Show Effect service tags, Layer factories
Specify error types

每个主要组件单独作为一个编号章节
包含完整的TypeScript接口及JSDoc注释
展示Effect服务标签、Layer工厂
指定错误类型

N+1. What This Replaces

N+1. 替代内容映射

Table: Current File | What Moves | What's Eliminated
Separate tables per codebase (runtime, agents, looper)

表格：当前文件 | 迁移内容 | 移除内容
按代码库（runtime、agents、looper）分别制作表格

N+2. Interaction With Existing Systems

N+2. 与现有系统的交互

How new code coexists with existing services
What changes vs. what stays the same

新代码如何与现有服务共存
变更内容与保留内容

N+3. Public API Surface

N+3. 公共API表面

Explicit export lists from sub-path and main entry

子路径和主入口的明确导出列表

N+4. High-Level Implementation Overview

N+4. 高层级实现概述

Consumer-facing code examples (setup, usage, customization)
Before/after dependency graph

消费端代码示例（设置、使用、自定义）
前后依赖关系图

N+5. Testing Strategy

N+5. 测试策略

Unit test plan per module
Integration test plan
Migrated tests from existing codebases

各模块的单元测试计划
集成测试计划
从现有代码库迁移的测试用例

N+6. Implementation Order

N+6. 实现顺序

Numbered steps with dependency column and parallelization notes
Table format: Step | What | Depends On | Parallelizable

带依赖列和并行化说明的编号步骤
表格格式：步骤 | 内容 | 依赖项 | 是否可并行

N+7. Migration Path

N+7. 迁移路径

Phased rollout (Phase 1, 2, 3...)
Each phase: what changes, what re-exports, what gets deleted

分阶段部署（阶段1、2、3...）
每个阶段：变更内容、重新导出内容、删除内容

N+8. What Does NOT Move

N+8. 不迁移内容

Table: Concern | Location | Why It Stays
Be explicit about boundaries


</spec_template>

<quality_standards>

表格：关注点 | 位置 | 保留原因
明确界定边界


</spec_template>

<quality_standards>

Quality Checklist

质量检查清单

Before considering a spec complete, verify:

Cross-codebase exploration was done (not just the target package)
Duplication map clearly shows what's duplicated where
All design decisions were confirmed with the user via AskUserQuestion
TypeScript interfaces are complete (not pseudocode)
Effect-TS compliance — all code snippets pass Phase 3b checks (branded types, Schema patterns, service patterns, Effect.fn, no Schema.Unknown)
Cross-spec consistency — no duplicate definitions, consistent naming, compatible type extensions (Phase 3c)
Canonical ownership — every type/function/constant has ONE owning spec, all others import
Effect patterns follow project conventions (Context.Tag, Layer, Schema.TaggedError)
Implementation order has clear dependency chains (including cross-spec dependencies)
Migration path is phased (not big-bang)
What does NOT move section explicitly excludes consumer concerns
High-level implementation shows real consumer-facing code
File path follows the existing spec naming convention (e.g.,
```
tasks/prd-sdk/N_feature-name.md
```
)
Not over-specified — passes the Spec-vs-Implementation test (see below)

规范完成前需验证以下内容：

跨代码库探索已完成（不仅限于目标包）
重复代码映射表清晰展示了重复内容的分布位置
所有设计决策已通过AskUserQuestion与用户确认
TypeScript接口完整（不是伪代码）
Effect-TS合规——所有代码片段通过阶段3b检查（品牌化类型、Schema模式、服务模式、Effect.fn、无Schema.Unknown）
跨规范一致性——无重复定义、命名一致、类型扩展兼容（阶段3c）
规范所有权——每个类型/函数/常量有唯一的所属规范，其他规范均通过导入使用
Effect模式遵循项目约定（Context.Tag、Layer、Schema.TaggedError）
实现顺序有清晰的依赖链（包括跨规范依赖）
迁移路径采用分阶段方式（非一次性大变更）
不迁移内容章节明确排除了消费端关注点
高层级实现展示了真实的消费端代码
文件路径遵循现有规范命名约定（例如：
```
tasks/prd-sdk/N_feature-name.md
```
）
不过度规范——通过「规范vs实现」测试（见下文）

Writing Style

写作风格

Use tables for comparisons and mappings (not prose)
Use ASCII art for architecture diagrams (not mermaid)
Use TypeScript code blocks for interfaces (not pseudocode)
Be concrete: file paths, function names, type names (not "the service" or "the module")
Show the "what it costs today" with specific line counts and file names
Every section should answer "what changes and what stays the same"

使用表格进行对比和映射（而非散文）
使用ASCII艺术图绘制架构图（而非mermaid）
使用TypeScript代码块展示接口（而非伪代码）
内容具体：包含文件路径、函数名、类型名（避免使用"该服务"或"该模块"等模糊表述）
用具体的行数和文件名说明「当前造成的成本」
每个章节需回答「哪些内容变更，哪些内容保留」

Spec-vs-Implementation Test (Anti-Bloat)

规范vs实现测试（反冗余）

Specs must describe WHAT the system does and WHY, not HOW it does it line-by-line. Apply this test to every code block:

规范需描述系统做什么以及为什么，而非逐行描述怎么做。对每个代码块应用以下测试：

APPROPRIATE in a spec (keep these):

规范中可保留的内容：

Type/schema definitions — these ARE the contract (e.g.,
```
Schema.Class
```
, interfaces, branded types)
Interface signatures — public API surface with JSDoc
Short behavioral pseudocode (< 15 lines) — key algorithm steps at a high level
Decision tables — provider → config → behavior mappings
ASCII diagrams — architecture, data flow, before/after dependency graphs
One example per pattern — show the pattern once, note "apply same pattern for X, Y, Z"

类型/Schema定义——这些属于契约（例如：
```
Schema.Class
```
、接口、品牌化类型）
接口签名——带JSDoc注释的公共API表面
简短行为伪代码（少于15行）——高层级的核心算法步骤
决策表——供应商→配置→行为映射
ASCII图——架构、数据流、前后依赖关系图
单例模式示例——展示一次模式，注明「对X、Y、Z应用相同模式」

NOT appropriate in a spec (replace these):

规范中不应包含的内容：

Full function bodies (> 15 lines) — replace with behavioral description: "When X happens, the system should Y"
Repetitive implementations (same pattern shown N times) — show once, use a table for variations
Internal state types — internal data structures are implementation details, describe behavior instead
Exact variable names and loop structures — over-constrains the implementer
Copy-paste-ready production code — if an implementer would copy rather than interpret, it's too detailed

完整函数体（超过15行）——替换为行为描述："当X发生时，系统应执行Y"
重复实现（同一模式重复展示N次）——展示一次，用表格列出变体
内部状态类型——内部数据结构属于实现细节，应描述行为而非类型
精确变量名和循环结构——过度约束实现者
可直接复制粘贴的生产代码——若实现者会直接复制而非理解，说明内容过于详细

How to fix bloated sections:

如何修复冗余章节：

Extract the architectural decision from the code and state it in prose ABOVE the code
Replace implementation code with: behavioral contract, mapping table, or interface signature
Move to appendix if reference code is truly needed — label it "Reference Implementation Sketch (non-normative)"
One example rule: Show one concrete example (e.g., one env builder), then use a table for the rest

从代码中提取架构决策，并在代码上方用散文形式说明
替换实现代码：使用行为契约、映射表或接口签名
移至附录：若确实需要参考代码，标记为「参考实现草图（非规范性）」
单例示例规则：展示一个具体示例（例如：一个环境变量构建器），其余用表格呈现

Example transformation:

示例转换：

BLOATED (131 lines of 8 env builders):

typescript

export const buildZaiEnvVars = (config: ZaiConfig): Record<string, string> => {
  const env: Record<string, string> = {};
  env.ANTHROPIC_BASE_URL = "https://api.zai.com/v1";
  if (config.apiKey) env.ANTHROPIC_AUTH_TOKEN = config.apiKey;
  // ... 15 more lines
};
export const buildOpenRouterEnvVars = (config: OpenRouterConfig): ... => { ... };
// ... 6 more builders, same pattern

CORRECT (table + 1 example):

Key decision: Env vars are built fresh per-request (not pre-computed at construction).

Provider	Base URL	Auth Var	Extra Vars	Clears API_KEY?
zai	`https://api.zai.com/v1`	`ANTHROPIC_AUTH_TOKEN`	—	Yes
openrouter	`https://openrouter.ai/api/v1`	`ANTHROPIC_AUTH_TOKEN`	—	Yes
...	...	...	...	...

All builders follow the same pattern. Reference:

buildZaiEnvVars

(shown above).

</quality_standards>

<anti_patterns>

冗余版本（131行代码，8个环境变量构建器）：

typescript

export const buildZaiEnvVars = (config: ZaiConfig): Record<string, string> => {
  const env: Record<string, string> = {};
  env.ANTHROPIC_BASE_URL = "https://api.zai.com/v1";
  if (config.apiKey) env.ANTHROPIC_AUTH_TOKEN = config.apiKey;
  // ... 15行更多代码
};
export const buildOpenRouterEnvVars = (config: OpenRouterConfig): ... => { ... };
// ... 6个更多构建器，模式相同

优化版本（表格+1个示例）：

核心决策：环境变量按请求实时构建（而非在初始化时预计算）。

供应商	基础URL	认证变量	额外变量	是否清除API_KEY？
zai	`https://api.zai.com/v1`	`ANTHROPIC_AUTH_TOKEN`	—	是
openrouter	`https://openrouter.ai/api/v1`	`ANTHROPIC_AUTH_TOKEN`	—	是
...	...	...	...	...

所有构建器遵循相同模式。参考：

buildZaiEnvVars

（如上所示）。

</quality_standards>

<anti_patterns>

What NOT To Do

禁止操作

Workflow Anti-Patterns

工作流反模式

Do NOT write the spec without exploring first — you will miss duplication and context
Do NOT skip the clarification phase — design decisions affect every section
Do NOT skip Phase 3b (Effect-TS check) — every spec we wrote without this phase had 5-7 violations
Do NOT skip Phase 3c (cross-spec check) — specs 2 and 5 independently defined the same 3 functions with different signatures, causing 3 Critical contradictions
Do NOT write the spec without reading previous specs — format consistency AND type consistency matter
Do NOT ask more than 4 clarification questions — focus on architectural decisions only

禁止未探索就编写规范——会遗漏重复内容和上下文信息
禁止跳过澄清阶段——设计决策影响所有章节
禁止跳过阶段3b（Effect-TS检查）——未执行此阶段的规范通常存在5-7项违规
禁止跳过阶段3c（跨规范检查）——规范2和5曾独立定义了3个相同函数但签名不同，导致3项严重冲突
禁止未阅读历史规范就编写——格式一致性和类型一致性至关重要
禁止提出超过4个澄清问题——仅聚焦于架构决策

Content Anti-Patterns

内容反模式

Do NOT write vague interfaces — include full type signatures with Effect patterns
Do NOT propose big-bang migrations — always use phased rollout
Do NOT include consumer concerns in the SDK — approval gates, UI streaming, prompt injection stay in consumers
Do NOT skip the "What does NOT move" section — explicit boundaries prevent scope creep
Do NOT present high-level overview without concrete code — show setup, registration, usage, and customization

禁止编写模糊接口——需包含完整的类型签名及Effect模式
禁止提议一次性大迁移——始终采用分阶段部署
禁止在SDK中包含消费端关注点——审批流程、UI流处理、提示注入等内容保留在消费端
禁止跳过「不迁移内容」章节——明确边界可防止范围蔓延
禁止展示无具体代码的高层级概述——需展示设置、注册、使用和自定义示例

Bloat Anti-Patterns (from real audit findings)

冗余反模式（来自真实审计发现）

Do NOT write full function implementations — specs with 100+ line function bodies (env builders, adapters, drivers) bury architectural decisions in code walls. Use behavioral descriptions + tables instead.
Do NOT repeat the same pattern N times — show once, table the variations. One env builder shown 8 times = 131 wasted lines; a table + 1 example = 20 lines with better clarity.
Do NOT specify internal state types —
```
RegistryState
```
with exact
```
Map
```
key formats is an implementation detail. Describe the behavioral contract ("caches bridges by tool-set signature").
Do NOT write copy-paste-ready production code — if an implementer would copy your code verbatim, you've written an implementation, not a spec. Specs should require interpretation.
Do NOT bury key decisions in code — the "dual role of request.model" decision was invisible inside a 99-line class body. State decisions in prose BEFORE any code.

禁止编写完整函数实现——包含100+行函数体（环境变量构建器、适配器、驱动）的规范会将架构决策淹没在代码中。应使用行为描述+表格替代。
禁止重复展示同一模式N次——展示一次，用表格列出变体。8个环境变量构建器占131行冗余代码；表格+1个示例仅需20行且更清晰。
禁止指定内部状态类型——包含精确
```
Map
```
键格式的
```
RegistryState
```
属于实现细节。应描述行为契约（"按工具集签名缓存桥接器"）。
禁止编写可直接复制粘贴的生产代码——若实现者会直接复制你的代码，说明你写的是实现而非规范。规范应要求实现者理解后再实现。
禁止将核心决策隐藏在代码中——"request.model的双重角色"决策曾隐藏在99行类代码中。应在代码前用散文形式说明决策。

Effect-TS Anti-Patterns (from real audit findings)

Effect-TS反模式（来自真实审计发现）

Do NOT use
Schema.Unknown
— use

JsonValue

JsonObject

, or

Schema.Defect

Do NOT use plain type aliases for IDs — use branded schemas:
```
Schema.String.pipe(Schema.brand("X"))
```
Do NOT use
Schema.Class
for events — discriminated variants (events with
```
type
```
field) must use
```
Schema.TaggedClass
```

Do NOT use
Schema.Enums
for string literals — use

Schema.Literal("a", "b", "c")

Do NOT define module-scoped functions — use static methods on helper/service classes
Do NOT return plain objects from Schema.Class factories — use
```
new ClassName({...})
```
constructors
Do NOT use raw callbacks for testable operations — use Effect services (e.g.,
```
Clock
```
instead of
```
clock?: () => number
```
)
Do NOT use
as unknown as X
double casts — use spread syntax or
```
Schema.encode
```

禁止使用Schema.Unknown——使用
```
JsonValue
```
、
```
JsonObject
```
或
```
Schema.Defect
```
禁止对ID使用普通类型别名——使用品牌化Schema：
```
Schema.String.pipe(Schema.brand("X"))
```
禁止对事件使用Schema.Class——带
```
type
```
字段的区分变体（事件）必须使用
```
Schema.TaggedClass
```
禁止对字符串字面量使用Schema.Enums——使用
```
Schema.Literal("a", "b", "c")
```
禁止定义模块级函数——使用辅助类/服务类的静态方法
禁止从Schema.Class工厂返回普通对象——使用
```
new ClassName({...})
```
构造函数
禁止对可测试操作使用原生回调——使用Effect服务（例如：用
```
Clock
```
替代
```
clock?: () => number
```
）
禁止使用
as unknown as X
双重类型转换——使用扩展语法或
```
Schema.encode
```

Cross-Spec Anti-Patterns (from real audit findings)

跨规范反模式（来自真实审计发现）

Do NOT redefine a function that another spec already defines — import it. Common trap: utility functions like
```
resolveProviderMetadata
```
get independently spec'd by multiple gap specs.
Do NOT give the same concept different names —
```
ProviderFamilyId
```
vs
```
OpenResponsesProviderFamily
```
caused confusion. Pick one name and use it everywhere.
Do NOT silently drop fields when extending a shared type — if Spec 1 adds
```
apiKey
```
to an options type and Spec 2 extends that type, include
```
apiKey
```
or explicitly note its removal.
Do NOT assume implementation order — if your spec depends on type expansions from another spec (e.g.,
```
ProviderId
```
growing from 3 to 11 values), document the dependency in your Implementation Order section.

</anti_patterns>

禁止重新定义其他规范已定义的函数——直接导入。常见陷阱：
```
resolveProviderMetadata
```
等工具函数被多个缺口规范独立定义。
禁止对同一概念使用不同名称——
```
ProviderFamilyId
```
与
```
OpenResponsesProviderFamily
```
曾造成混淆。选定一个名称并统一使用。
禁止扩展共享类型时静默删除字段——若规范1为选项类型添加了
```
apiKey
```
，规范2扩展该类型时需包含
```
apiKey
```
或明确说明移除原因。
禁止假设实现顺序——若当前规范依赖其他规范的类型扩展（例如：
```
ProviderId
```
从3个值扩展到11个值），需在「实现顺序」章节中记录此依赖关系。

</anti_patterns>