Clean Principles — Active Coding Standards & Quality Gates

STATUS: ALWAYS ACTIVE ON EVERY PROMPT & CODE TASK This ruleset governs all code generation, refactoring, architecture, and review across every session. Never drift back to unprincipled, bloated, or unverified code.

1. Ambiguity Gate (Clarify Before Build)

Stop and ask before writing code when requirements are ambiguous.

• Trigger words: "simple", "quick", "basic", "clean", "proper", "production-ready".
• Action: Ask 1 targeted clarifying question to disambiguate scope before writing code, OR explicitly state the minimal assumptions chosen before providing code. Read skills/clarify-before-build/SKILL.md.
• Prevent over-engineering: Never assume "production-ready" justifies adding unrequested frameworks, complex layers, or unneeded dependencies.

2. Functions & Methods

• ≤ 3 parameters: Any function requiring > 3 parameters must use a parameter object, options map, or dataclass.
• One responsibility (SRP): One task per function. If you need "and" to describe what it does, split it.
• No boolean flag parameters: Never pass process(true). Use two named functions (processSync() / processAsync()).
• Small & focused: Keep functions small enough to understand in one glance.
• No hidden side effects: Functions do what their name promises and nothing else.

3. File Sizing & Modularity

• ≤ 300 lines per file (soft limit 200, hard limit 400) — split larger files into cohesive modules.
• Avoid junk-drawer files (utils.ts, helpers.py, Common.java).

4. Human-Readable Code (Senior 10+ YoE Mindset)

• Write for humans first, compiler second — optimize for the engineer on-call at 2 AM.
• Guard clauses over nested if/else — return early on invalid conditions (max indentation level ≤ 2).
• No clever one-liners — split complex expressions into obvious, named steps.
• Self-documenting conditionals — encapsulate predicates into named booleans/functions.
• Command-Query Separation (CQS) — never mutate state inside getters/queries.

5. Naming Standards

• Intention-revealing: elapsedDays not d, isUserActive not flag.
• Functions = Verb phrases: calculateTotal(), sendEmail(), validateInput().
• Classes = Noun phrases: UserAccount, OrderProcessor, InvoiceGenerator.
• No cryptic abbreviations: Standard acronyms (url, id, api) are fine; avoid usrActFlg or ctxObj.

6. Code Quality & Hygiene

• No magic numbers or strings: Extract to named constants (MAX_RETRIES = 3, DEFAULT_TIMEOUT_MS = 5000).
• No commented-out code: Delete dead code immediately; version control preserves history.
• Comments explain WHY, not WHAT: The code explains what is happening; comments explain non-obvious rationale or trade-offs.
• No null/nil/None returns for collections: Return empty arrays/lists/sets/maps instead.
• Specific exception handling: Always catch specific exceptions; never use bare except: or catch (Exception e).

7. Design & Architecture (SOLID · DRY · KISS · YAGNI)

• DRY: One single source of truth per business rule.
• KISS: Simple over clever. Simplicity requires justification before adding complexity.
• YAGNI: Build only what is requested right now. No speculative generalizations or premature wrappers.
• SOLID:
  • Single Responsibility: One class/module = one reason to change.
  • Open/Closed: Open for extension, closed for modification.
  • Liskov Substitution: Subtypes must fulfill base type contracts without unexpected exceptions.
  • Interface Segregation: Clients must not be forced to depend on interfaces they do not use.
  • Dependency Inversion: High-level modules depend on abstractions, not concrete details.

8. Ecosystem Idioms & Conventions

• Adhere to the target language's idiomatic style — write native-feeling code, not transplanted paradigms.
• Follow framework & community standards (PSR-12/Laravel, PEP 8, Effective Go, React Rules of Hooks, Rust API Guidelines).
• Respect local toolchain configs (tsconfig.json, phpstan.neon, .eslintrc, pyproject.toml).
• Consistency over personal preference — existing codebase conventions always win.

9. Mandatory Full-Skill Reading (Read Full Skill When Needed)

Do not rely on memory or general LLM training weights. When a task enters any of the following domains, the agent MUST read the corresponding full SKILL.md using the file-reading tool (read_file, View, etc.) BEFORE generating code or making architectural decisions:

Rationalization Red Flags (STOP and READ the skill file):

• ❌ "I already know SOLID/KISS/YAGNI definitions" → The skills contain specific project contracts, smell checklists, and anti-patterns.
• ❌ "The task is small, so I can skip reading" → Small tasks are where premature abstractions and flag parameters slip in.
• ❌ "I will write code first and check the skill later" → Code written without the skill causes avoidable rework. Read first.

10. Pre-Output Verification Gate

Before completing any code generation or edit, verify:

1. Does every function have ≤ 3 parameters?
2. Is each function's purpose explainable in a single sentence?
3. Are there magic numbers or unrequested abstractions?
4. Is any file exceeding 300 lines or any function nested more than 2 levels deep?