design（设计）

Design

Code, component, and API design evaluation.

Abstraction Quality

Naming

• Does processData() actually process data?
• Do names reveal intent?
• Consistent vocabulary (don't mix "user" and "account" for same concept)?

Red flags:

• Manager, Handler, Processor, Utils — often god classes
• Single-letter names outside tight loops
• Abbreviations that aren't universally known

Single Responsibility

• One reason to change?
• Can you describe the class without using "and"?

Test: "The {ClassName} is responsible for..." — if you need "and", split it.

Leaky Abstractions

• Does implementation leak through interface?
• Are internal data structures exposed?

Example leak:

// Leaky — exposes internal Map structure
class Cache {
  getAll(): Map<string, Value> { return this.internal; }
}

// Clean — hides implementation
class Cache {
  entries(): Array<[string, Value]> { return [...this.internal]; }
}

Tell, Don't Ask

• Behavior on objects vs external orchestration?
• Objects should do things, not just hold data

Ask (bad):

if (order.status === 'pending' && order.items.length > 0) {
  order.status = 'confirmed';
}

Tell (good):

order.confirm(); // Object owns its state transitions

SOLID Compliance

API Design

Protocol Selection

Universal Principles

1. Contract-First: Define API before implementation
2. Consistency: Same patterns everywhere
3. Evolvability: Version from day one
4. DX: Clear errors, good docs

DX (Developer Experience)

• Onboarding: Can a new dev understand in 15 minutes?
• Error Messages: Actionable or cryptic?
• Documentation: Matches reality?
• Conventions: Consistent with ecosystem?

Guild Members for Design

Primary: Karman (naming/abstractions), Ace (DX), Burner (coupling) Secondary: Dijkstra (correctness), Vector (auth for APIs)

Output Format

## Design Review: {Component}

### Abstraction Quality
- {Finding 1}
- {Finding 2}

### SOLID Violations
- {Principle}: {violation}

### API Assessment (if applicable)
- {Finding}

### DX Friction Points
- {Point 1}

### Recommendations
1. {Action}
2. {Action}

Additional Resources

• references/solid-gotchas.md — Common SOLID violations with fixes
• references/api-rest.md — REST production gotchas
• references/api-graphql.md — GraphQL N+1, complexity, caching traps
• references/api-grpc.md — gRPC streaming, versioning gotchas