design（设计）

Design

Guidelines for requirements analysis, design principles, architecture, and security.

Requirements Analysis

Before Writing Code

• Understand the requirements
• Consider edge cases
• Plan the approach
• Think about testing

Tools for Understanding Existing Code

Before designing new features, understand the existing codebase:

# Get project overview with codemapper
cm stats . --format ai
cm map . --level 2 --format ai

# Find entry points and main flows
cm query main . --format ai
cm callees main . --format ai

# Understand module dependencies
cm deps . --format ai
cm deps . --circular --format ai  # Check for issues

Core Principles

SOLID Principles

DRY, KISS, YAGNI

DRY   - Don't Repeat Yourself: Extract common logic, but don't over-abstract
KISS  - Keep It Simple, Stupid: Prefer clarity over cleverness
YAGNI - You Aren't Gonna Need It: Don't build features until needed

Detect DRY violations with jscpd:

# Find duplicate code blocks
npx jscpd /path/to/source
npx jscpd --pattern "src/**/*.ts"

Simplicity Over Complexity

Simple, working code beats clever, complex code.

❌ OVERENGINEERed                    ✅ SIMPLE
─────────────────────────────────────────────────────
AbstractFactoryProvider              Direct instantiation
5 layers of indirection              1-2 layers max
Generic solution for 1 use case      Specific solution that works
"Future-proof" architecture          Solve today's problem
Premature optimization               Optimize when needed

Security by Design

Threat Modeling

• Identify threat vectors
• Plan for input validation
• Consider authentication/authorization
• Plan for data protection
• Plan for logging and monitoring
• Plan for audit trails

Input Validation

// ✅ GOOD: Validate all inputs
interface CreateUserInput {
  name: string;
  email: string;
  age?: number;
}

function createUser(input: CreateUserInput): User {
  if (!input.name || input.name.length < 2) {
    throw new ValidationError("Name must be at least 2 characters");
  }

  if (!isValidEmail(input.email)) {
    throw new ValidationError("Invalid email format");
  }

  if (input.age !== undefined && (input.age < 0 || input.age > 120)) {
    throw new ValidationError("Age must be between 0 and 120");
  }

  // Proceed with valid input
}

Authentication & Authorization

// ✅ GOOD: Proper auth and authorization
interface AuthenticatedRequest {
  userId: string;
  role: "admin" | "user" | "guest";
}

function deleteUser(request: AuthenticatedRequest, userId: string) {
  if (request.role !== "admin") {
    throw new ForbiddenError("Only admins can delete users");
  }

  if (userId === request.userId) {
    throw new BadRequestError("Cannot delete yourself");
  }

  // Proceed with authorized operation
}

Health Assessment Before Design

Before designing new features, assess the health of the area you're changing:

Mechanical Check (quick, verifiable)

• No unused imports or dead exports in affected files
• No import cycles involving the module
• No orphaned files (files nothing imports)
• No near-duplicate logic across sibling files
• Complexity within bounds (no functions > 50 LOC, nesting > 4)

Subjective Check (requires reading)

• Names communicate intent — would a stranger understand without reading the body?
• Error handling is consistent with sibling modules
• Abstractions earn their cost — no single-use wrappers
• Dependencies point in the right direction (domain has no infrastructure imports)
• Conventions match the rest of the directory

If Health Is Poor

Fix the existing issues before adding new features. Adding features to unhealthy code compounds debt. The order is:

1. Fix T1/T2 mechanical issues (unused, dead, lint)
2. Fix convention drift (make siblings consistent)
3. Add the new feature
4. Verify no new issues introduced

Related Skills

• swe: Code quality guidelines, anti-patterns, code health dimensions
• typescript: Type safety and interfaces
• vitest: Test design and patterns