Help us improve
Share bugs, ideas, or general feedback.
From functional-clarity
This skill should be used when the user asks about "functional clarity", "функциональная ясность", "принципы функциональной ясности", fail-fast architecture, Error Hiding prevention, context-adaptive defaults, error handling patterns, refactoring principles, or asks to apply the Functional Clarity methodology. Also activates when the user says "apply our coding principles", "check against our style guide", "review this against functional clarity", "how should I handle errors", "рефакторинг", "обработка ошибок", or "code review against our standards". Provides a 22-principle methodology for building reliable, simple, and understandable software with emphasis on fail-fast error handling, explicit dependencies, and minimal cognitive load.
npx claudepluginhub spumer/i-m-senior-developer --plugin functional-clarityHow this skill is triggered — by the user, by Claude, or both
Slash command
/functional-clarity:functional-clarityThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A methodology for building reliable, simple, and understandable software. Every principle serves one goal: minimize cognitive load while maximizing code reliability.
Enforces clean code principles during code generation and refactoring: function focus, naming clarity, complexity limits, error handling, and self-documenting style. Supports project-specific overrides via config.
Applies SRP, DRY, YAGNI, naming, error handling, dependency direction, and Kent Beck's four rules of simple design when writing, reviewing, or refactoring code.
Scores and improves code readability using six disciplines: meaningful names, small functions, clean error handling, comments, formatting, and unit tests. For code review, refactoring, PR feedback, or establishing quality standards.
Share bugs, ideas, or general feedback.
A methodology for building reliable, simple, and understandable software. Every principle serves one goal: minimize cognitive load while maximizing code reliability.
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.
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.
Numbering follows the original scheme: 1, 2, 2A, 3–22.
Concrete techniques against exception swallowing:
try-except Exception without re-raise — FORBIDDENAlways set timeouts for network calls. Your SLO depends on it.
| 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.
pytest.fail() not raise in testsSee references/01-style-guide.md for the full version with details.
# 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
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/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/00-principles.mdreferences/01-style-guide.mdreferences/03-developer-levels.mdreferences/04-bash-instructions.mdreferences/frameworks/python.mdThis skill complements tdd-master:
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/.