best-practices

Best Practices and Code Patterns

Code Writing Principles

Clean Code Principles

• Single Responsibility Principle: Each function and class has only one clear responsibility
• Clear Naming: Variable, function, and class names clearly express their purpose
• Small Functions: Functions are limited to a size that fits on one screen
• Dependency Injection: Use injection structure rather than hardcoded dependencies

TypeScript Best Practices

Type Definitions

// Good example: Clear and specific types
interface ContextConfig {
  readonly version: number;
  readonly kind: 'task' | 'role' | 'workflow';
  readonly name: string;
  readonly description: string;
  readonly context: {
    workflow?: string;
    personas?: readonly string[];
    rules?: readonly string[];
    mcps?: readonly string[];
  };
}

// 피해야 할 예시: any 타입 사용
const config: any = loadConfig();

유니온 타입 활용

// 상태 관리에 유니온 타입 사용
type LoadingState = 
  | { status: 'loading' }
  | { status: 'success'; data: ContextConfig }
  | { status: 'error'; error: string };

타입 가드 패턴

function isContextConfig(obj: unknown): obj is ContextConfig {
  return typeof obj === 'object' && 
         obj !== null && 
         'version' in obj && 
         'kind' in obj;
}

File Structure Best Practices

Module Separation Principles

src/
├── cli/
│   ├── commands/        # CLI command modules
│   ├── utils/          # CLI utilities
│   └── index.ts        # CLI entry point
├── core/
│   ├── context/        # Context-related logic
│   ├── workflow/       # Workflow engine
│   ├── notification/   # Notification system
│   └── types.ts        # Common type definitions
├── schemas/
│   ├── context.ts      # Context schemas
│   ├── workflow.ts     # Workflow schemas
│   └── index.ts        # Schema exports
└── types/
    ├── cli.ts          # CLI-related types
    ├── mcp.ts          # MCP-related types
    └── index.ts        # Type exports