design-philosophy
Establishes design standards for APIs and modules, prioritizing maintainability and abstraction.
Install
mkdir -p .claude/skills/design-philosophy && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/3915" && unzip -o skill.zip -d .claude/skills/design-philosophy && rm skill.zipInstalls to .claude/skills/design-philosophy
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Core design principles for the codebase - cognitive load, progressive disclosure, type safety, abstraction worth. Use when designing APIs, modules, or data structures.Key capabilities
- →Minimize cognitive load through separation of concerns
- →Implement progressive disclosure for APIs
- →Enforce type safety with newtypes and enums
- →Standardize error handling with miette
- →Apply ADT const params for zero-cost behavior
How it works
The skill provides a set of design principles and patterns that prioritize compile-time safety and developer experience through structured abstraction.
Inputs & outputs
When to use design-philosophy
- →Design a new API module
- →Review data structure abstractions
- →Ensure type safety in design
- →Refactor complex code for clarity
About this skill
Design Philosophy Skill
Apply these principles when writing or reviewing code.
When to Use
- Proactively when designing new APIs, modules, or data structures
- When refactoring existing code
- When reviewing code for maintainability
Core Principles
1. Minimize Cognitive Load
Code should be easy to understand without loading too much into working memory.
Guidelines:
- Good Separation of Concerns (SoC) means fewer "things" to keep in mind
- Each module/function should have a single, clear responsibility
- Limit the number of concepts a reader must hold simultaneously
- Clean Imports: Use
usestatements at the top of files rather than inline absolute paths (e.g.crate::Type) to reduce visual noise and cognitive clutter in function bodies. - No Magic Numbers/Strings: Extract domain-specific numbers and strings (like ANSI mode integers or escape sequences) into named constants (e.g., in
tui/src/core/ansi/constants/). Do not use magic numbers directly in business logic or pattern matches, as this requires readers to memorize their meaning. - Single Source of Truth for Constants: Never duplicate raw literals across byte, string, and length constants. Follow the Constant Derivation Hierarchy:
- Atomic Primitives (Single byte/char):
u8is the SSOT (u8tocharviaascii_byte_to_charto&strviaascii_byte_to_str). - Composed Sequences (Multi-byte strings):
&stris the SSOT (&strvia compile-time concatenation/macro to&[u8]via.as_bytes()tousizevia.len()). See Constant Design Patterns inpatterns.md.
- Atomic Primitives (Single byte/char):
- Technical Precision: Use standard, precise terminology (e.g., Parameter vs. Argument) to ensure the reader's mental model matches the implementation exactly. See the Terminology Precision guide.
2. Progressive Disclosure
Reveal complexity only when needed.
Guidelines:
- Public APIs should be minimal and intuitive
- Advanced features should be discoverable but not in-your-face
- Documentation follows inverted pyramid: high-level first, details later
- Module structure should guide users from simple to advanced
- Type-Centric Co-location (Associated Functions over Floating Functions): Prefer associated functions and methods on domain types over free-floating helper functions.
- Co-locate with Return Type: When a function's primary job is constructing, parsing, or classifying a domain type
T(e.g.classify_csi_buffer -> CsiBufferKind), make it an associated function onT(CsiBufferKind::classify). - Co-locate with Subject Type: When a function interprets, translates, or queries
T(e.g.parse_ss3_command(byte) -> Option<VT100KeyCodeIR>), make it an associated method or function onT(Ss3BufferKind::decode(self)/Ss3BufferKind::parse_command(byte)). - Keep Floating When Appropriate: Reserve floating functions for high-level pipeline entry points / coordinators (e.g.
parse_keyboard_sequencereturning generic IR), multi-type algorithms, or functions returning external/standard library types (u32,String).
- Co-locate with Return Type: When a function's primary job is constructing, parsing, or classifying a domain type
3. Make Illegal States Unrepresentable
Use the type system to prevent bugs at compile time.
Guidelines:
- Prefer newtypes over primitives (e.g.,
Indexinstead ofusize) - Eliminate Boolean Soup / Boolean Blindness: Never use raw
boolflags, struct fields, function parameters, or return values in domain code (e.g.fn process(flag: bool)orfn is_default() -> bool). Replace boolean soup with self-documenting domain enums (e.g.SyntaxHighlightPipeline::R3BLMarkdowninstead ofis_file_extension_default() -> bool,TrailingNewline::Present/Absent, orHasSelection::Yes/No). Domain enums make call sites self-documenting and leverage Rust'smatchor==for explicit checking.- No
.is_*() -> boolHelpers on Domain Enums: Do NOT addpub fn is_modified(self) -> boolor similar boolean conversion helpers onto domain enums. Callers must match on the enum or compare directly against the variant (e.g.status == FormatStatus::Modified). - When
boolIs Acceptable (std& Third-Party Compatibility Only): Rawboolis permitted solely when required for compatibility withstd,clippy, or third-party crate contracts:stdcollection conventions:pub fn is_empty(&self) -> boolwhen paired withpub fn len(&self)(enforced byclippy::len_without_is_empty).stdtrait signatures and higher-order closures: implementingPartialEq::eqor passing predicate closures tostditerator/collection methods (.filter(...),.any(...),.all(...),.retain(...)).- Third-party derive macro contracts: struct fields required by derive macros such as
#[derive(clap::Parser)]CLI switch flags (#[arg(long)] pub verbose: bool).
- No
- Avoid Boolean Blindness in Mutator Returns (
Option<T>/Option<()>vs Domain Enums): Mutator methods taking&mut selfthat delete or replace text cannot return borrowed slices (Option<&str>) or metadata offsets (DocSeg) because the borrow checker forbids returning a&strborrowing fromselfacross a&mut selfmutation, and deleted bytes no longer exist in memory. Returning a text payload from a&mut selfmutator unavoidably requires an owned heap allocation (Option<String>). Return a payloadOption<T>(e.g.Option<LineMetadata>for zero-allocation metrics orOption<String>for text) ONLY when callers genuinely consume it. If no text payload is consumed by callers:- Use
Option<()>ONLY when callers chain with?: When a mutator can fail (e.g. out-of-bounds index) and callers short-circuit onNoneusing?, returnOption<()>(Some(())for success,Nonefor failure). - Use a Domain Enum when callers do NOT chain with
?: UsingOption<()>when callers do not short-circuit with?is an anti-pattern because it forces.is_some()checks (boolean blindness in disguise) and misrepresents a valid no-op state as failure (None). For sequential passes or status-reporting mutators, return an explicit domain enum (e.g.FormatStatus::Modified/FormatStatus::Unchanged).
- Use
- Constructor Conventions (
Defaultover No-Argnew()): If a type requires no arguments for construction, derive or implementDefault(#[derive(Default)]) and do NOT create a redundantpub fn new() -> Selfmethod. Use parameterized constructors (with_capacity(...)ornew(arg: Type)) only when arguments are required. - Design enums and structs so invalid combinations cannot be constructed
- Move validation from runtime to compile time where possible
- See
check-bounds-safetyskill for exemplary patterns
4. Abstractions Must Earn Their Keep
An abstraction should reduce cognitive load, not add to it.
Guidelines:
- If understanding the abstraction requires more effort than the concrete code, don't abstract
- Good abstractions match mental models developers already have
- Three similar lines of code is often better than a premature abstraction
- Abstractions should hide complexity, not just move it
5. High-Fidelity Error Handling
Treat errors as a user interface (UI) for developers. Public-facing errors must provide actionable information.
Guidelines:
- Standardize on
miette: All custom error types (enums/structs) must derivemiette::Diagnosticin addition tothiserror::Error. - Actionable Metadata: Use
#[diagnostic(help(...))]to provide hints on how to resolve the error. - Searchable Codes: Use
#[diagnostic(code(...))]to provide unique identifiers for errors, facilitating documentation and search. - Preserve Context: Avoid "lossy" error conversions (like turning a rich
miette::Reportinto a plain string). Use transparent delegation or dedicated variants to preserve the full error chain.
6. Modern Rust Patterns: ADT Const Params
Use Enums with Const Generics (Algebraic Data Type Const Params) to control behavior without runtime overhead or boilerplate. This pattern is enabled by the adt_const_params feature flag.
When to Apply:
- Proactively apply this pattern when writing new code or refactoring existing code that requires choosing between a closed set of behaviors or strategies at compile-time.
Guidelines:
- Zero-Cost Behavior: Prefer
const POLICY: MyEnumover runtime fields. This allows the compiler to prune dead code and branches at compile-time (monomorphization). Example:ScopedMutex. - Reduce Boilerplate: Prefer
constEnums over the Trait-based Strategy pattern. This centralizes logic and eliminates the need for multiple marker structs and trait implementations. - Type-Level Identity: Use this pattern when you want different behaviors to result in different types, enabling compile-time enforcement of safety rules.
7. Strict Encapsulation & Testing Hygiene
Maintain strict encapsulation boundaries in production code and do not leak internal state merely for the convenience of tests.
Guidelines:
- No
pubfor tests: Never make a field or methodpuborpub(crate)if its only external caller is a test. - Test-Only Accessors: Keep production fields strictly scoped (private or
pub(in crate::...)). If tests need to inspect or manipulate internal state, provide explicit accessor methods annotated with#[cfg(test)](e.g.,pub(crate) fn internal_state_for_testing(&self)). This cleanly compiles the escape hatch out of the production binary.
Supporting Files
patterns.md- Detailed patterns with good/bad examples
Related Skills
check-bounds-safety- Type-safe Index/Length patterns (exemplar of principle #3)organize-modules- Module organization for encapsulation (supports principle #1)- `write_documentatio
Content truncated.
When not to use it
- →Creating premature abstractions
Prerequisites
Limitations
- →Requires adherence to specific Rust patterns
- →Not suitable for simple, short-lived scripts
How it compares
It focuses on minimizing cognitive load and preventing illegal states at compile-time, rather than just functional correctness.
Compared to similar skills
design-philosophy side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| design-philosophy (this skill) | 1 | 5mo | No flags | Advanced |
| architect-review | 109 | 7mo | No flags | Advanced |
| solid-principles | 57 | 1y | No flags | Intermediate |
| codex | 32 | 5mo | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by r3bl-org
View all by r3bl-org →You might also like
architect-review
sickn33
Master software architect specializing in modern architecture patterns, clean architecture, microservices, event-driven systems, and DDD. Reviews system designs and code changes for architectural integrity, scalability, and maintainability. Use PROACTIVELY for architectural decisions.
solid-principles
SmidigStorm
Enforce SOLID principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion) in object-oriented design. Use when writing or reviewing classes and modules.
codex
Lucklyric
Invoke Codex CLI for complex coding tasks requiring high reasoning capabilities. This skill should be invoked when users explicitly mention "Codex", request complex implementation challenges, advanced reasoning, or need high-reasoning model assistance. Automatically triggers on codex-related requests and supports session continuation for iterative development.
error-handling-patterns
wshobson
Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applications. Use when implementing error handling, designing APIs, or improving application reliability.
deepwiki-rs
sopaco
AI-powered Rust documentation generation engine for comprehensive codebase analysis, C4 architecture diagrams, and automated technical documentation. Use when Claude needs to analyze source code, understand software architecture, generate technical specs, or create professional documentation from any programming language.
senior-fullstack
davila7
Comprehensive fullstack development skill for building complete web applications with React, Next.js, Node.js, GraphQL, and PostgreSQL. Includes project scaffolding, code quality analysis, architecture patterns, and complete tech stack guidance. Use when building new projects, analyzing code quality, implementing design patterns, or setting up development workflows.