File length limits ****≤200 lines (dynamic langs) / ≤250 lines (static langs):**
Shorter files reduce cognitive load, speed up reviews, and localize side-effects. Static languages typically include more declarations/boilerplate, hence a slightly higher cap. Max 8 files per folder ****≤8 siblings per directory:
Keeps discovery time low and prevents “junk drawers.” If a folder grows, the domain likely needs sub-domains (subfolders) and clearer boundaries. **Architectural “bad smells” **Rigidity: Small changes shouldn’t cause cascading edits. If they do, abstractions or boundaries are wrong. **Redundancy: Duplicate logic drifts out of sync; extract functions/modules to ensure a single source of truth. **Circular dependency: Cycles block reuse and testing. Introduce an interface/port or move shared code to a lower layer. **Fragility: Unrelated breakages signal high coupling or hidden shared state; tighten encapsulation and tests. **Obscurity: If intent isn’t obvious, refactor for clarity (names, smaller functions, clearer modules). **Data clump: Repeated parameter groups want a value object/DTO to express intent and reduce call-site noise. **Needless complexity: Prefer the simplest design that works; postpone patterns until justified by real needs. **Enforcement mindset

Treat limits as default rules, not absolute laws; break them only with explicit, documented reasons. Prompt for optimization when a smell appears—early feedback is cheaper than late rewrites. HTML separation of concerns ****Structure vs. style vs. behavior:
Keep HTML lean; move CSS/JS out to keep markup readable and cacheable. ****≤500 lines per HTML file:**
Encourages componentization (partials, includes, web components) and improves maintainability.

Code Architecture

  • Hard limits

    1. For dynamic languages (Python, JavaScript, TypeScript), keep each source file ≤ 200 lines where reasonably possible.

    2. For static languages (Java, Go, Rust), keep each source file ≤ 250 lines where reasonably possible.

    3. In any folder, keep the number of files ≤ 8. If it exceeds 8, reorganize into subfolders with clear boundaries.

  • Architectural quality
    Beyond the hard limits, continuously uphold elegant design and watch for code smells that erode quality:

    1. Rigidity: Small changes trigger widespread edits.

    2. Redundancy: The same logic appears in multiple places.

    3. Circular Dependency: Modules depend on each other in loops.

    4. Fragility: A change in one place breaks unrelated features.

    5. Obscurity: Intent is unclear; structure is confusing.

    6. Data Clump: The same set of parameters travels together—use a dedicated object/value type.

    7. Needless Complexity: Over-engineering beyond the problem’s needs.

  • Very important: Whether writing your own code or reviewing others’, enforce the hard limits and actively monitor architectural quality.

  • Very important: Whenever you identify a potential code smell, ask the author if they want improvements and propose concrete refactorings (e.g., extract function/module, introduce interface, flatten dependency, create value object).

HTML Guidelines

  • Apply Separation of Concerns: keep structure (HTML) separate from style (CSS) and behavior (JavaScript).

  • Keep a single HTML file ≤ 500 lines where possible. If it carries too many features or UI sections, split into smaller, reusable components (partials, includes, or web components).

Note: These are defaults, not dogma. If you must exceed a limit, document the rationale and plan a follow-up refactor.