
functional-clarity
Помогает писать простой, надёжный и понятный код, а существующий менять без лишнего риска.
- GitHub stars
- 14
Install
/plugin install functional-clarity@i-m-senior-developerRun it inside Claude Code after adding the marketplace with /plugin marketplace add spumer/i-m-senior-developer.
Contents
Discovered from sourceSkills 1
Functional Clarity — Development Philosophy
A methodology for building reliable, simple, and understandable software. Every principle serves one goal: minimize cognitive load while maximizing code reliability.
Core Values
Simplicity — the right solution is the simplest one that works. Reliability — fail-fast, no Error Hiding, honest error reflection. Clarity — code reads like a story, names explain intent. Maintainability — every change reduces cost of future changes.
Foundation
Analyze your solutions to extract general principles and apply them to new tasks. This works not only for technical tasks but for any challenge. Programming reflects reality — solutions are inseparable from the real world. A principle works everywhere; if there's an exception, it's not a principle.
The 22 Principles
Numbering follows the original scheme: 1, 2, 2A, 3–22.
Responsibility & Structure
- Limited Responsibility — Each function solves one task, 20-30 lines max. One reason to change.
- Minimal Changes — Understand existing abstractions first. Extend, don't duplicate. High cost of rewriting.
2A. Fail-Fast Architecture — System must crash immediately on errors. Graceful degradation only via feature flags.
- Feature flag OFF → early return (None/0/skip)
- Feature flag ON → functionality required → errors crash
- No try-catch "just in case", no defaults on errors, no logging without re-raise
- Architecture Supporting Change — Every change should reduce cost of future changes, not just solve today's task.
- Explicit Error Handling — Custom exception classes with informative messages. Exception hierarchies for flexible handling.
- Minimal Dependencies — Prefer stdlib. Encapsulate external deps behind interfaces. Isolate via factories and services.
Code Quality
- Domain-Oriented Generalization — Group by business meaning, not technical similarity. No context-free utility functions.
- Expressive Naming — Names express purpose and context. Verbs for functions, nouns for objects. Answers "what?" and "why?".
- Explicit Entity Relationships — Dependencies visible through constructor params or function args. No global state, no hidden side effects.
- Transparent State Management — Explicit state transitions, validity checks. Prefer immutable structures. Controlled interfaces for state changes.
- Separation of Business Logic and Infrastructure — Business logic operates on abstractions, not concrete DB/HTTP/API implementations.
Validation & Safety
- Immediate Parameter Validation — Validate inputs at function start. Fast exit on invalid conditions.
- Atomic Transactions — Explicit locks and transactions for data integrity. Optimistic/pessimistic locking by context.
- Complexity = Understanding, Not Size — Clear 30-line function beats cryptic 10-line one. Document complex algorithms, skip obvious code.
- Modern Python — Python 3.11+, type annotations, context managers, pathlib, modern syntax.
- Testability — Pure functions, isolated side effects, explicit I/O params. Testable code = modular code.
Meta-Principles
- Understand the Problem First — Ask clarifying questions. Verify understanding on simple examples. Read existing code before writing new.
- Prevent Logical Deadlocks — Analyze event dependencies at design time. No cyclic waits in component lifecycle.
- Minimum Sufficient Solution — Complexity matching the task. Excessive complexity = imprecise understanding. Start simple, complicate only when needed.
- Ruthless Deletion of Unused Code — Delete immediately when unused. No "just in case" code. VCS remembers everything.
Error Hiding Prevention (Principle 20)
Concrete techniques against exception swallowing:
try-except Exceptionwithout re-raise — FORBIDDEN- Returning defaults (None/0/[]) instead of exception — FORBIDDEN
- Logging error and continuing — FORBIDDEN
- Marking as "processed" when actually skipped — FORBIDDEN
- Error reaction hierarchy: status field → error table/metric → raise
External Interactions (Principle 21)
Always set timeouts for network calls. Your SLO depends on it.
Context-Adaptive Defaults (Principle 22)
| Role | Defaults | Rationale |
|---|---|---|
| FK dependency | Minimal for validity | Consumer doesn't care about details |
| Entry point (API, factory) | Maximal for usefulness | Consumer wants to work, not configure |
| Edge case | Explicitly different | Deviation must be visible |
Default != Error Hiding: Returning empty value on error is NOT a default, it's Error Hiding.
Style Guide
- Simple, single-task functions — one task, minimal side effects, 20-30 lines
- Fail-fast error handling — no unnecessary try/finally, custom exceptions
- Minimal dependencies — stdlib first, encapsulate external deps
- Expressive naming — descriptive names, docstrings for complex logic
- Code organization — clear public API, hidden helpers, group by functionality
- Testability — pure functions, isolated side effects,
pytest.fail()notraisein tests - Timeouts — all blocking operations and external calls must have timeouts
See references/01-style-guide.md for the full version with details.
Error Handling Patterns
# CORRECT: Fail-fast with feature flag
def process_with_feature(data):
if not settings.FEATURE_ENABLED:
return 0 # Only legitimate early return
result = _do_actual_work(data) # Let exceptions bubble up
return result
# CORRECT: Re-raise with context enrichment
try:
result = external_api.call()
except ExternalApiError as e:
raise ServiceError(f"Failed for {user_id=}") from e
# CORRECT: Honest error reflection in data
except Config.DoesNotExist as e:
event.status = 'FAILED'
event.error_message = str(e)
event.save()
# FORBIDDEN: Error Hiding
try:
do_something()
except Exception:
logger.error("Failed") # Swallowed!
return None
Reference Documentation
references/00-principles.md— Complete 22 principles with detailed explanations and code examplesreferences/01-style-guide.md— Full style guide with details on each pointreferences/02-code-change-discipline.md— 7-step algorithm for working with existing code, reinforced by FPF principles (A.7 Strict Distinction, A.10 Evidence Graph, A.11 Ontological Parsimony, A.1.1 BoundedContext)references/03-developer-levels.md— Developer level definitions (Junior → Senior+)references/04-bash-instructions.md— Bash script guidelinesreferences/frameworks/python.md— Python-specific: modern syntax, pathlib, type annotations, pytest patternsreferences/05-comment-style.md— Comment discipline: four comment smell classes (doc-refs, changelog-in-code, restating the obvious, reporting your own work to the human) with ❌/✅, the allowlist, and borderline cases (external standards, versioned-API docs). Normative source — every other mention points here. Tracking-id (FEAT-XXXX) enforced separately bysdlc.references/06-boundary-vocabulary.md— Boundary vocabulary: what a context declares on its boundary it names in its own language — and the rule is the same at every scale (layer, module, service, cross-team system). The ownership rule, the three leak channels (name, type/signature, prose), the substitution test (objective criterion), the translation duty (the dependent side translates, in its own adapter), a worked module-level case with ❌/✅, and false-positive guards (context-internal names, presentation-layer copy). Normative source — every other mention points here. Design-time check owned bysdlc:architect, review category bysdlc:code-reviewer.
Reference Loading Order
- SKILL.md provides the working summary for applying principles during coding
- IF user asks for detailed explanation of a specific principle → read
references/00-principles.md - IF writing or reviewing code and need detailed style guidance → read
references/01-style-guide.md - IF modifying existing code (refactoring, bug fix, extending unfamiliar code) → read
references/02-code-change-discipline.mdBEFORE making changes - IF discussing developer levels, requirements, expectations, or code review standards → read
references/03-developer-levels.md - IF writing bash scripts → read
references/04-bash-instructions.md - IF writing Python code → read
references/frameworks/python.md - IF writing or reviewing code comments → read
references/05-comment-style.md - IF designing, implementing, or reviewing elements declared on a context boundary at any scale — layer, module, service, published schema; especially under dependency inversion → read
references/06-boundary-vocabulary.md
Integration
This skill complements tdd-master:
- functional-clarity defines HOW to write code (principles, style, architecture)
- tdd-master defines WHEN to write tests (Red-Green-Refactor workflow)
Both share the Fail-Fast and Error Hiding prevention philosophy.
If the user asks about writing tests, TDD, or test-driven development and the tdd-master skill is not available, recommend installing the tdd-master plugin from the same repository: plugins/tdd-master/.
Hooks 1
Sponsors
Details
- Marketplace
- spumer/i-m-senior-developer
- Source
- plugins/functional-clarity
- Author
- spumer
- Category
- Development