obra/clank.

Commenting Intent

Comment WHY code exists and non-obvious decisions, not WHAT code does (mechanics)

Creating Skills

TDD for process documentation - test with subagents before writing, iterate until bulletproof

Designing Before Coding

Design in pseudocode first, iterate approaches, then translate to code

Domain-Focused Naming

Name code by what it does in the domain, not how it's implemented or its history

Encapsulating Complexity

Hide implementation details behind interfaces - work at domain level (what), not implementation level (how)

Exploring Alternatives

Try 2-3 different approaches before implementing - don't settle for first design you think of

Installing Skills System

Fork, clone to ~/.clank, run installer, edit CLAUDE.md

Keeping Routines Focused

Each routine does one thing and does it well - extract when routines have multiple responsibilities

Localizing Variables

Declare variables in smallest possible scope, initialize close to first use, minimize span and live time

Maintaining Consistent Abstractions

Class interfaces present one cohesive abstraction - don't mix domain logic with serialization, persistence, or unrelated concerns

Naming Variables

Choose names that fully and accurately describe what the variable represents

Reducing Complexity

Managing complexity is software's primary technical imperative - all other goals are secondary

Refactoring Safely

Refactor with tests first, one change at a time, never mix refactoring with bug fixes or new features

Simplifying Control Flow

Flatten nested conditionals with early returns or table-driven methods - keep nesting depth under 3 levels

Single Purpose Variables

Use each variable for exactly one purpose - no hybrid coupling or hidden meanings

Validating Inputs

Check all external inputs for validity - garbage in, nothing out, never garbage out

Writing Evergreen Comments

Write comments explaining WHAT and WHY, never temporal context or history