Skip to content

Aarvion-AI/stackwise-skills / skills/engineering-rules

engineering-rules

Verified

references/reusability-and-structure.md

View on GitHub
# Reusability and Structure (Rules 1-2)

Rule 1: search before writing, extract on the second occurrence, one responsibility per unit.
Rule 2: small units, clear boundaries, one-way dependencies, no hidden global state, config over hardcoding, follow the project's idioms.

## Search Before Writing

Before writing any helper, run searches by domain concept, not just by the name you would have picked:

```bash
# Looking to format a date? Search the concept, its synonyms, and likely locations.
grep -rn "formatDate\|toDateString\|dateFmt\|humanDate" src/
ls src/utils src/lib src/shared 2>/dev/null
# Python projects
grep -rn "def .*date" src/ --include="*.py" | grep -i "format\|parse\|human"
```

If a near-fit exists, extend it with a parameter rather than writing a sibling:

```typescript
// Bad: found formatDate but wrote a variant anyway
export function formatDate(d: Date): string { return d.toISOString().slice(0, 10); }
export function formatDateWithTime(d: Date): string { return d.toISOString().slice(0, 16).replace("T", " "); }

// Good: one function, one axis of variation
export function formatDate(d: Date, withTime = false): string {
  const iso = d.toISOString();
  return withTime ? iso.slice(0, 16).replace("T", " ") : iso.slice(0, 10);
}
```

## Extract on the Second Occurrence

The first time a shape appears, write it inline. The second time, extract it. Do not wait for a third.

```python
# Bad: same retry shape copy-pasted into two clients
class OrdersClient:
    def fetch(self, order_id: str) -> Order:
        for attempt in range(3):
            try:
                return self._get(f"/orders/{order_id}")
            except TransientError:
                time.sleep(2 ** attempt)
        raise RetryExhaustedError(order_id)

class InvoicesClient:
    def fetch(self, invoice_id: str) -> Invoice:
        for attempt in range(3):
            try:
                return self._get(f"/invoices/{invoice_id}")
            except TransientError:
                time.sleep(2 ** attempt)
        raise RetryExhaustedError(invoice_id)
```

```python
# Good: the repeated shape becomes one function; call sites keep their meaning
def with_retry(op: Callable[[], T], key: str, attempts: int = 3) -> T:
    for attempt in range(attempts):
        try:
            return op()
        except TransientError:
            time.sleep(2 ** attempt)
    raise RetryExhaustedError(key)

class OrdersClient:
    def fetch(self, order_id: str) -> Order:
        return with_retry(lambda: self._get(f"/orders/{order_id}"), order_id)

class InvoicesClient:
    def fetch(self, invoice_id: str) -> Invoice:
        return with_retry(lambda: self._get(f"/invoices/{invoice_id}"), invoice_id)
```

Extraction test: the extracted unit must be nameable by what it does (`with_retry`), not by where it came from (`shared_fetch_logic`). If you cannot name it, the duplication may be coincidental; leave it.

## Single Responsibility

A function that fetches, transforms, and persists is three functions wearing one name.

```typescript
// Bad: one function, three jobs, untestable seams
async function syncUsers(): Promise<void> {
  const res = await fetch(`${API}/users`);
  const users = (await res.json()) as ApiUser[];
  const rows = users.map((u) => ({ id: u.id, email: u.email.toLowerCase(), active: u.status === "ok" }));
  for (const row of rows) await db.upsert("users", row);
}

// Good: each unit testable alone; the orchestrator reads as the plan
async function fetchUsers(): Promise<ApiUser[]> {
  const res = await fetch(`${API}/users`);
  return res.json();
}

function toUserRow(u: ApiUser): UserRow {
  return { id: u.id, email: u.email.toLowerCase(), active: u.status === "ok" };
}

async function syncUsers(): Promise<void> {
  const users = await fetchUsers();
  await db.upsertMany("users", users.map(toUserRow));
}
```

## Module Boundaries and Dependency Direction

Dependencies point from outer layers (HTTP, CLI, UI) toward the domain, never the reverse. A domain module importing a controller, view, or ORM entity is a boundary violation.

```
src/
  domain/        # pure logic; imports nothing outside domain/
  services/      # orchestrates domain; imports domain/, not routes/
  routes/        # HTTP shells; imports services/; no business logic
```

```python
# Bad: domain reaching outward
# domain/pricing.py
from routes.checkout import current_request       # domain now depends on HTTP
def discount(total): return total * (0.9 if current_request.user.is_vip else 1.0)

# Good: caller passes what the domain needs
# domain/pricing.py
def discount(total: Decimal, is_vip: bool) -> Decimal:
    return total * (Decimal("0.9") if is_vip else Decimal("1"))
# routes/checkout.py
price = discount(cart.total, is_vip=request.user.is_vip)
```

## No Hidden Global State

Module-level mutable state makes call order matter and tests order-dependent.

```typescript
// Bad: mutable module global; who set it, and when?
let currentTenant: string;
export function setTenant(t: string) { currentTenant = t; }
export function tableName(base: string) { return `${currentTenant}_${base}`; }

// Good: state travels explicitly
export function tableName(tenant: string, base: string) { return `${tenant}_${base}`; }
```

Acceptable module-level state: immutable constants, and caches that are pure functions of their inputs.

## Configuration Over Hardcoding

Anything that varies by environment (URLs, limits, timeouts, feature toggles, file paths) is read from config, once, at the edge.

```python
# Bad: literals buried mid-function, different per environment
def upload(file: bytes) -> str:
    if len(file) > 10 * 1024 * 1024:
        raise FileTooLargeError()
    return s3.put("prod-uploads-bucket", file)

# Good: config object built once at startup, injected where needed
@dataclass(frozen=True)
class UploadConfig:
    bucket: str
    max_bytes: int

def upload(file: bytes, cfg: UploadConfig) -> str:
    if len(file) > cfg.max_bytes:
        raise FileTooLargeError(limit=cfg.max_bytes)
    return s3.put(cfg.bucket, file)
```

Do not swing to the other extreme: a value used once, identical in every environment, is a named constant next to its use, not a config entry.

## Follow the Project's Structure and Idioms

Before adding a file, look at how neighbors do it and match them, even when you would have chosen differently:

- Where do tests live (`__tests__/`, `*.test.ts` beside source, `tests/` tree)? Put yours in the same place.
- How are errors surfaced (exceptions, `Result` types, error codes)? Use the existing channel; do not introduce a second.
- Naming conventions (`camelCase` vs `snake_case` files, `IThing` vs `Thing`)? Consistency beats preference.

A diff that is locally "better" but idiomatically foreign costs every future reader a context switch. Change the idiom repo-wide in its own PR, or follow it.

## Checklist for This Reference

- [ ] Searched for an existing helper before writing a new one
- [ ] Every shape appearing twice in the diff is extracted, and the extraction has a behavior-based name
- [ ] Each new function does one thing; orchestration is separate from work
- [ ] No import points from domain code outward to HTTP/UI/DB layers
- [ ] No new mutable module-level state
- [ ] Environment-dependent values come from config; single-use constants stay local
- [ ] New files, tests, and errors follow the surrounding project's conventions
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall