# Universal Patterns

> Code organization, error handling, data flow, naming and anti-patterns in any language. Use while writing or reviewing everyday code. Do not use to choose a system shape or a design pattern — read the architecture skill instead.

- Skill: `madappgang/universal-patterns-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add madappgang/universal-patterns-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/madappgang/universal-patterns-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: MadAppGang (https://skillmd.com/u/madappgang)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/madappgang/universal-patterns-2

---


# Universal Development Patterns

## Overview

Language-agnostic development patterns and best practices applicable across all technology stacks.

## The deep catalog lives next door — read it for any real design decision

**This file is the quick reference.** It carries enough to keep everyday code honest. It is
deliberately shallow on architecture, and it contains **none** of the 22 GoF design
patterns.

For anything beyond a reminder — choosing a style, comparing two, or picking a design
pattern — **read the `architecture` skill's index**, then follow where it routes you:

```
<dev-plugin-root>/skills/architecture/SKILL.md
```

Locate it relative to this plugin's root, which covers both the installed-cache and
local-source layouts:

```bash
ls "${CLAUDE_PLUGIN_ROOT}/skills/architecture/SKILL.md" 2>/dev/null \
  || ls "$(dirname "$(dirname "$(pwd)")")"/plugins/dev/skills/architecture/SKILL.md 2>/dev/null
```

That index routes in two steps: **altitude first** (is this about system shape or class
collaboration), then the specific file. What it covers, none of which is below:

| Tier | Files | Contents |
|---|---|---|
| Architectural styles | `references/styles/*.md` | layered, hexagonal (ports and adapters), clean, modular monolith, microservices, event-driven, CQRS + event sourcing |
| GoF categories | `references/{creational,structural,behavioral}.md` | the shared framing for each family |
| GoF patterns | `references/patterns/*.md` | all 22, with TypeScript, trade-offs, and when not to use each |
| Selection | `references/selection.md` | how to choose, overuse smells, and where TypeScript already gives you the pattern free |

**Do not answer an architecture question from the summaries below when the deep file
exists.** The summaries omit the trade-offs and the failure modes, which are the parts that
decide whether the choice is right.

## Architecture Patterns (summary — see the `architecture` skill for the real treatment)

### Layered Architecture

```
┌─────────────────────────────┐
│     Presentation Layer      │  UI, API handlers, CLI
├─────────────────────────────┤
│     Application Layer       │  Use cases, services
├─────────────────────────────┤
│       Domain Layer          │  Business logic, entities
├─────────────────────────────┤
│    Infrastructure Layer     │  DB, cache, external APIs
└─────────────────────────────┘
```

**When to Use**: Most applications benefit from clear separation of concerns.

### Clean Architecture

```
         ┌─────────────────┐
         │   Frameworks    │  (outermost)
         │   & Drivers     │
     ┌───┴─────────────────┴───┐
     │    Interface Adapters    │
     │   (Controllers, Gateways)│
 ┌───┴─────────────────────────┴───┐
 │        Application Business      │
 │           Rules (Use Cases)      │
 ┌─────────────────────────────────┐
 │    Enterprise Business Rules     │  (innermost)
 │         (Entities)               │
 └─────────────────────────────────┘
```

**Dependency Rule**: Dependencies point inward. Inner layers don't know about outer layers.

### Component-Based Architecture (Frontend)

```
src/
├── components/
│   ├── common/         # Shared UI components
│   ├── layout/         # Layout components
│   └── features/       # Feature-specific components
├── hooks/              # Custom hooks
├── stores/             # State management
├── services/           # API services
└── utils/              # Utilities
```

## Code Organization Principles

### Single Responsibility

Each module/function should do ONE thing well.

```
// BAD: Multiple responsibilities
function processUser(user) {
  validateUser(user);
  saveToDatabase(user);
  sendEmail(user);
  logAnalytics(user);
}

// GOOD: Single responsibility
function validateUser(user) { /* validation only */ }
function saveUser(user) { /* persistence only */ }
function notifyUser(user) { /* notification only */ }
```

### Dependency Injection

Inject dependencies rather than creating them internally.

```
// BAD: Hard dependency
class UserService {
  constructor() {
    this.db = new Database(); // Hard-coded
  }
}

// GOOD: Injected dependency
class UserService {
  constructor(db) {
    this.db = db; // Injected
  }
}
```

### Interface Segregation

Prefer many specific interfaces over one general interface.

```
// BAD: Fat interface
interface Worker {
  work();
  eat();
  sleep();
}

// GOOD: Segregated interfaces
interface Workable { work(); }
interface Eatable { eat(); }
interface Sleepable { sleep(); }
```

## Error Handling Patterns

### Fail Fast

Validate inputs early and fail immediately on invalid data.

```
function processOrder(order) {
  // Validate early
  if (!order) throw new Error('Order required');
  if (!order.items?.length) throw new Error('Order must have items');
  if (!order.customerId) throw new Error('Customer ID required');

  // Process only after validation passes
  return executeOrder(order);
}
```

### Error Boundaries

Contain errors at appropriate boundaries.

```
// API boundary - catch and format errors
async function apiHandler(req, res) {
  try {
    const result = await processRequest(req);
    res.json({ success: true, data: result });
  } catch (error) {
    res.status(error.statusCode || 500).json({
      success: false,
      error: error.message
    });
  }
}
```

### Result Types (Where Supported)

Use Result/Either types instead of exceptions for expected failures.

```typescript
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

function parseConfig(input: string): Result<Config, ParseError> {
  try {
    return { ok: true, value: JSON.parse(input) };
  } catch (e) {
    return { ok: false, error: new ParseError(e.message) };
  }
}
```

## Data Flow Patterns

### Unidirectional Data Flow

Data flows in one direction through the application.

```
Action → Dispatcher → Store → View → Action
```

### Event-Driven Architecture

Decouple components through events.

```
// Publisher
eventBus.emit('user.created', { userId: '123' });

// Subscriber
eventBus.on('user.created', async (event) => {
  await sendWelcomeEmail(event.userId);
});
```

### Command Query Separation (CQS)

Separate commands (mutations) from queries (reads).

```
// Query - returns data, no side effects
function getUser(id) { return db.users.find(id); }

// Command - mutates data, returns void/status
function updateUser(id, data) { db.users.update(id, data); }
```

## Naming Conventions

### Functions

| Type | Convention | Examples |
|------|------------|----------|
| Actions | verb + noun | `createUser`, `deleteOrder`, `validateInput` |
| Queries | get/find/is/has + noun | `getUser`, `findOrders`, `isValid`, `hasPermission` |
| Handlers | handle + event | `handleClick`, `handleSubmit`, `handleError` |
| Callbacks | on + event | `onSuccess`, `onError`, `onChange` |

### Variables

| Type | Convention | Examples |
|------|------------|----------|
| Booleans | is/has/can/should | `isActive`, `hasAccess`, `canEdit`, `shouldRefresh` |
| Collections | plural | `users`, `orders`, `items` |
| Counts | count/num/total | `userCount`, `numItems`, `totalPrice` |

### Files

| Type | Convention | Examples |
|------|------------|----------|
| Components | PascalCase | `UserProfile.tsx`, `OrderList.vue` |
| Utilities | camelCase/kebab | `formatDate.ts`, `string-utils.ts` |
| Constants | SCREAMING_SNAKE | `API_ENDPOINTS.ts`, `ERROR_CODES.ts` |
| Tests | name.test/spec | `user.test.ts`, `order.spec.ts` |

## Code Quality Checklist

Before committing code, verify:

- [ ] Single responsibility - each function does one thing
- [ ] Clear naming - intent is obvious from names
- [ ] Error handling - failures are handled gracefully
- [ ] No magic numbers - constants are named and documented
- [ ] DRY - no unnecessary duplication (but don't over-abstract)
- [ ] Tests - critical paths are tested
- [ ] Documentation - complex logic is explained

## Anti-Patterns to Avoid

### God Objects
Objects that know too much or do too much. Split into focused components.

### Premature Optimization
Don't optimize before measuring. Write clear code first, optimize proven bottlenecks.

### Stringly Typed
Using strings where enums/types would be safer. Use type systems.

### Copy-Paste Programming
Duplicating code instead of abstracting. But: prefer duplication over wrong abstraction.

### Boolean Parameters
Functions with boolean flags that change behavior. Split into explicit functions.

```
// BAD
function process(data, isAdmin) { /* behaves differently based on flag */ }

// GOOD
function processUserData(data) { /* user logic */ }
function processAdminData(data) { /* admin logic */ }
```

## Performance Principles

1. **Measure First**: Profile before optimizing
2. **Lazy Loading**: Load resources only when needed
3. **Caching**: Cache expensive computations and API calls
4. **Pagination**: Don't load everything at once
5. **Batch Operations**: Combine multiple operations when possible
6. **Async/Parallel**: Use concurrency for independent operations

## Security Principles

1. **Input Validation**: Never trust user input
2. **Output Encoding**: Encode data for its context (HTML, SQL, etc.)
3. **Least Privilege**: Request minimum permissions needed
4. **Defense in Depth**: Multiple layers of security
5. **Fail Secure**: Default to denying access on errors
6. **Secrets Management**: Never hardcode secrets, use environment variables

## Language-Specific Knowledge Bases (cross-plugin)

These universal patterns are language-agnostic. When the task targets a specific
language, a companion plugin may ship a **curated, production-grade knowledge base**
for it. Prefer that knowledge over generic patterns when it exists.

### Go — the `go` plugin's knowledge base

If the task involves Go, check whether the `go@magus` plugin is installed alongside
this one and read its knowledge base. It is bundled as plain files next to the `dev`
plugin, so locate it relative to this plugin's root (`${CLAUDE_PLUGIN_ROOT}`), which
covers both install topologies:

```bash
# Both layouts: installed cache (…/cache/magus/go/<version>/) and local source
# (…/plugins/go/). Run from inside an agent that knows ${CLAUDE_PLUGIN_ROOT}:
ls "${CLAUDE_PLUGIN_ROOT}/../go/knowledge/roles" 2>/dev/null \
  || ls "${CLAUDE_PLUGIN_ROOT}"/../../go/*/knowledge/roles 2>/dev/null
```

**If found**, read the files matching your role and task before writing Go:
- `knowledge/roles/<role>/best-practices.md` — role guidance (`developer`,
  `architect`, `tester`, `code-reviewer`)
- `knowledge/roles/<role>/implementation-references.md` — index into the references
- `knowledge/references/*.md` — production-code patterns (error handling, concurrency,
  interface design, context usage, testing, http-api, etc.)
- `knowledge/uber-go-style-guide.md`, `knowledge/100-go-mistakes.md`,
  `knowledge/go-proverbs.md` — style and pitfalls

Apply this Go knowledge in preference to the generic patterns above. The role names
map to dev agents: developer→`dev:developer`, architect→`dev:architect`,
tester→`dev:test-architect`, code-reviewer→`dev:reviewer`.

**If NOT found** and the task is Go-heavy, tell the user once, then proceed with the
generic patterns:

> 💡 A curated Go knowledge base (Uber style guide, 100 Go Mistakes, production
> patterns) is available in the `go` plugin. Install it for higher-quality Go work:
> `/plugin install go@magus`

Do not block on this — it is an enhancement, not a requirement.

---

*Universal patterns applicable to all technology stacks*