AGENT SKILL

m05-type-driven

CRITICAL: Use for type-driven design. Triggers: type state, PhantomData, newtype, marker trait, builder pattern, make invalid states unrepresentable, compile-time validation, sealed trait, ZST, 类型状态, 新类型模式, 类型驱动设计

使用场景视觉设计
License 许可
MIT
最近更新
2026-04-11
Stars
★ 3
Forks
0

01 前言 Front Matter

name
m05-type-driven
description
CRITICAL: Use for type-driven design. Triggers: type state, PhantomData, newtype, marker trait, builder pattern, make invalid states unrepresentable, compile-time validation, sealed trait, ZST, 类型状态, 新类型模式, 类型驱动设计
user-invocable
false

03 SKILL.md 正文

Type-Driven Design

Layer 1: Language Mechanics

Core Question

How can the type system prevent invalid states?

Before reaching for runtime checks:

  • Can the compiler catch this error?
  • Can invalid states be unrepresentable?
  • Can the type encode the invariant?

Error → Design Question

Pattern Don't Just Say Ask Instead
Primitive obsession "It's just a string" What does this value represent?
Boolean flags "Add an is_valid flag" Can states be types?
Optional everywhere "Check for None" Is absence really possible?
Validation at runtime "Return Err if invalid" Can we validate at construction?

Thinking Prompt

Before adding runtime validation:

  1. Can the type encode the constraint?

    • Numeric range → bounded types or newtypes
    • Valid states → type state pattern
    • Semantic meaning → newtype
  2. When is validation possible?

    • At construction → validated newtype
    • At state transition → type state
    • Only at runtime → Result with clear error
  3. Who needs to know the invariant?

    • Compiler → type-level encoding
    • API users → clear type signatures
    • Runtime only → documentation

Trace Up ↑

When type design is unclear:

"Need to validate email format"
    ↑ Ask: Is this a domain value object?
    ↑ Check: m09-domain (Email as Value Object)
    ↑ Check: domain-* (validation requirements)
Situation Trace To Question
What types to create m09-domain What's the domain model?
State machine design m09-domain What are valid transitions?
Marker trait usage m04-zero-cost Static or dynamic dispatch?

Trace Down ↓

From design to implementation:

"Need type-safe wrapper for primitives"
    ↓ Newtype: struct UserId(u64);

"Need compile-time state validation"
    ↓ Type State: Connection<Connected>

"Need to track phantom type parameters"
    ↓ PhantomData: PhantomData<T>

"Need capability markers"
    ↓ Marker Trait: trait Validated {}

"Need gradual construction"
    ↓ Builder: Builder::new().field(x).build()

Quick Reference

Pattern Purpose Example
Newtype Type safety struct UserId(u64);
Type State State machine Connection<Connected>
PhantomData Variance/lifetime PhantomData<&'a T>
Marker Trait Capability flag trait Validated {}
Builder Gradual construction Builder::new().name("x").build()
Sealed Trait Prevent external impl mod private { pub trait Sealed {} }

Pattern Examples

Newtype

struct Email(String);  // Not just any string

impl Email {
    pub fn new(s: &str) -> Result<Self, ValidationError> {
        // Validate once, trust forever
        validate_email(s)?;
        Ok(Self(s.to_string()))
    }
}

Type State

struct Connection<State>(TcpStream, PhantomData<State>);

struct Disconnected;
struct Connected;
struct Authenticated;

impl Connection<Disconnected> {
    fn connect(self) -> Connection<Connected> { ... }
}

impl Connection<Connected> {
    fn authenticate(self) -> Connection<Authenticated> { ... }
}

Decision Guide

Need Pattern
Type safety for primitives Newtype
Compile-time state validation Type State
Lifetime/variance markers PhantomData
Capability flags Marker Trait
Gradual construction Builder
Closed set of impls Sealed Trait
Zero-sized type marker ZST struct

Anti-Patterns

Anti-Pattern Why Bad Better
Boolean flags for states Runtime errors Type state
String for semantic types No type safety Newtype
Option for uninitialized Unclear invariant Builder
Public fields with invariants Invariant violation Private + validated new()

Related Skills

When See
Domain modeling m09-domain
Trait design m04-zero-cost
Error handling in constructors m06-error-handling
Anti-patterns m15-anti-pattern

04 同仓库更多 Skills

0xharryriddle
0xharryriddle/codex-field-kit

vercel-react-best-practices

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

前端开发
★ 3
0xharryriddle
0xharryriddle/codex-field-kit

swarm-planner

[EXPLICIT INVOCATION ONLY] Creates dependency-aware implementation plans optimized for parallel multi-agent execution.

★ 3
0xharryriddle
0xharryriddle/codex-field-kit

super-swarm-spark

Only to be triggered by explicit super-swarm-spark commands.

★ 3
0xharryriddle
0xharryriddle/codex-field-kit

role-creator

Create and install Codex custom agent roles in ~/.codex/config.toml, generate role config files, enforce supported keys, and guide users through required role inputs (model, reasoning effort, developer_instructions).

★ 3
0xharryriddle
0xharryriddle/codex-field-kit

read-github

Read and search GitHub repository documentation via gitmcp.io MCP service. **WHEN TO USE:** - User provides a GitHub URL - User mentions a specific repo in owner/repo format - User asks "what does this repo do?", "read the docs for X repo", or similar - User wants to search code or docs within a repo

Skill与智能体开发
★ 3
0xharryriddle
0xharryriddle/codex-field-kit

planner

Create comprehensive, phased implementation plans with sprints and atomic tasks. Use when user says: "make a plan", "create a plan", "plan this out", "plan the implementation", "help me plan", "design a plan", "draft a plan", "write a plan", "outline the steps", "break this down into tasks", "what's the plan for", or any similar planning request. Also triggers on explicit "/planner" or "/plan" commands.

★ 3