dotfiles: Skill for Claude Code

Codebase Design

Design modules that hide substantial behavior behind interfaces callers can understand. Judge a design by the knowledge and coordination it removes from callers, not by file counts or implementation length.

Use the project's established domain language. The vocabulary below supports reasoning; it does not forbid terms such as component, service, API, or boundary.

Working vocabulary

• Module: Code with an interface and an implementation, from a function to a package or feature.
• Interface: Everything callers must know: inputs, outputs, invariants, ordering, errors, configuration, and relevant performance constraints.
• Depth: Useful behavior exposed relative to the complexity callers must understand.
• Seam: A place where behavior can be substituted without editing its consumers.
• Adapter: A concrete implementation that connects a dependency at a seam.
• Locality: Related decisions and changes stay together instead of spreading across callers.

Design from the actual problem

Inspect callers, implementation, and dependencies before proposing a new interface. Identify the concrete cost: repeated policy, change amplification, unclear ownership, or difficult verification. Keep the existing design when a new abstraction would add more navigation or coordination than it removes.

• Hide implementation decisions and maintain invariants inside the module that owns them.
• Keep callers' common operations straightforward. Fewer methods are useful only when they reduce the contract callers must learn.
• Keep related behavior together. Do not split a coherent function or file merely to satisfy size targets.
• Introduce dependency injection where substitution, side-effect control, or an existing architectural boundary provides a concrete benefit. Do not invent a second adapter to justify an interface.
• Keep internal dependencies private unless callers need to supply or configure them.
• Prefer pure computation for domain decisions and explicit ownership for effects. An orchestration module may legitimately perform I/O.
• Consider removing a pass-through layer when it contributes no policy, isolation, or stable contract. A thin adapter may still be valuable for an external dependency.