relay: Skill for Claude Code

You fix one pattern: a runtime Schema and a manual TypeScript type describe the same shape.

The preferred boundary is schema-first. Define the schema once, export type X = typeof XSchema.Type or type X = Schema.Schema.Type<typeof XSchema>, and make domain code consume the inferred type. This prevents drift between parsing and static types.

Trace before changing

1. Find the runtime schema. Look for Schema.Struct, Schema.Union, Schema.TaggedStruct, Schema.Record, Schema.Array, or Schema.decodeTo.
2. Find the duplicate static shape. A nearby interface X or type X = { ... } repeats the same fields, nullability, optionality, or literals.
3. Check export consumers. If callers import the type, keep the exported type name stable and change only its definition.
4. Confirm the schema is the source of truth. If the manual type is wider/narrower than runtime parsing, decide whether the schema or consumers are wrong before replacing it.
5. Handle recursion narrowly. Recursive schemas may need one private recursive helper type to annotate Schema.suspend; keep exported domain types inferred from the schema.

Fix shape

• Move the schema before the exported type alias when needed.
• Replace duplicated exported interfaces with aliases derived from the schema:

export const SourceSchema = Schema.Struct({
  id: SourceId,
  name: Schema.String,
  enabled: Schema.Boolean,
});

export type Source = typeof SourceSchema.Type;

• Use Schema.Schema.Type<typeof XSchema> when it reads better for non-exported or generic schemas:

type IntrospectionResult = Schema.Schema.Type<typeof IntrospectionResultModel>;

• If using Schema.decodeTo, infer the domain type from the decoded/domain schema, not from the raw transport schema.
• Do not keep a manual interface solely for documentation. Add schema annotations or comments only when they clarify behavior the schema cannot express.

Bad

export interface StoredSource {
  readonly id: string;
  readonly url: string;
  readonly headers: readonly Header[];
}

export const StoredSourceSchema = Schema.Struct({
  id: Schema.String,
  url: Schema.String,
  headers: Schema.Array(HeaderSchema),
});