01-house-style/01-core-principles.md

Core principles

These principles define the preferred engineering style for Vroq apps.

They are written for ChatGPT and other LLMs, but they are equally useful for humans.

1. Make intention obvious

Code should make it easy to understand:

Prefer explicit names, direct logic, and simple structure over cleverness.

Keep related behavior together.

A feature should usually keep its UI, actions, reducer, and API helpers near each other instead of scattering them across the app.

This makes reading, editing, and debugging more local and less risky.

A file should usually have one main responsibility.

Small files are easier for LLMs to inspect, patch, and refactor. They also reduce the chance of broad accidental edits.

Do not split files arbitrarily. Split them at real responsibility boundaries.

Before writing a new helper, section, component, action pattern, or API wrapper, first check whether a good existing one can be reused or extended.

Prefer extending a good existing pattern over introducing a second competing pattern.

When a bug appears, identify the owning layer and fix it there.

Examples of owning layers:

Do not scatter defensive one-off fixes across unrelated files if the problem has a clearer source.

Presentation-only UI should usually stay separate from store-aware feature orchestration.

Transport code should usually stay separate from UI files.

Reducers should own state transitions.

Actions should make transitions explicit.

If there is already a good pattern in the app or docs, follow it.

Do not invent a new naming scheme, folder layout, state shape, or UI composition style unless there is a strong reason.

Good Vroq code should be easy to inspect through:

This is especially important because LLMs debug better when state changes and ownership are explicit.

When an app is messy, improve it incrementally.

Prefer a sequence of small cleanups over a large rewrite unless the structure is beyond repair.

This reduces risk and keeps diffs easier to review and reason about.

Always write code so the next change is easier, not harder.

The code should become more understandable and more structured over time.