# Coding Effectively

> Always use this skill when writing or refactoring code. Covers general code design, error handling, file organization, and code style patterns.

- Skill: `jamiebrynes7/coding-effectively` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jamiebrynes7/coding-effectively`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jamiebrynes7/coding-effectively/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jamiebrynes7 (https://skillmd.com/u/jamiebrynes7)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jamiebrynes7/coding-effectively

---


# Coding Effectively

## Correctness over convenience

Model the full error space, not the path you had in mind. Handle every edge case — race conditions, timing issues, partial failures. Encode constraints in the type system, and prefer compile-time guarantees to runtime checks. Never bypass the type system to silence a compiler error (`as any`, unchecked casts). When uncertain, explore and iterate rather than assume.

## Error handling

Never swallow an error. Every error is one of three things:

- **Recoverable locally** — handle it
- **Unrecoverable locally** — pass it up the stack
- **Non-critical** — log it, increment a metric, or both

Two tiers: user-facing errors get semantic exit codes, rich diagnostics, and actionable messages. Internal errors are programming errors, and may panic or use internal types. Never emit a generic message where the specific cause is known.

**Message format** — lowercase sentence fragments, so that `"operation failed: " + error.message` composes:

```
Good: failed to connect to database: connection refused
Bad:  Failed to Connect to Database: Connection Refused
```

## Design

- Don't abstract until you have seen the pattern three times. Three similar lines beat a premature abstraction.
- Prefer specific, composable logic over abstract frameworks.
- Evolve the design incrementally rather than perfecting it upfront, and don't build for hypothetical future requirements.
- Document the trade-off when making a non-obvious choice.

Before implementing a feature, read `references/property-driven-design.md`. Property questions surface design gaps — deleted entities, case sensitivity, tie-breaking — during design rather than during debugging.

## File organization

- Name files for what they contain, never a generic category: `string-formatting.ts`, `date-arithmetic.ts`, `user-validation.ts`, not `utils.ts` or `helpers.ts`. When tempted to create one of those, ask what the functions have in common and name the file after that.
- Keep module boundaries strict, with restricted visibility.
- Platform-specific code goes in its own file: `unix.ts`, `windows.ts`, `posix.ts`, selected by conditional compilation or a runtime check.
- Test helpers belong in dedicated modules, not mixed into production code.
- Prefer many small files to a few large ones.

## Style

- Keep the happy path left-aligned. Return early instead of nesting.
- Declare identifiers in the files that need them; export or make public only when something else needs them.
- Declare variables close to their usage.
- Limit assignment scope — reassignment and shadowing cause subtle bugs.

## Code comments

**REQUIRED**: Load the 'house-style-code-comments' skill for the comment policy.