Global coding preferences

Apply unless repo-specific instructions override.

Code style

Simple, readable, maintainable > clever or compact.
One responsibility per function/method.
Preserve existing behavior unless asked otherwise.
Scope changes to the task. No unrelated edits.

Limits (adapt to language)

Max 25 logic lines/function (excl. comments, error handling).
Max 80 chars/line, 5 params/function, 5 local vars/function.
Too many params → group into struct/object. Too many vars → split/extract.
No global state. Explicit data flow.

Comments & readability

Document intent, not mechanics. Use project doc style (docstring, JSDoc, etc.).
Explicit, consistent, meaningful names.
Straight control flow. Extract complex conditions. No hidden side effects.

Refactoring

Priority: safety → readability → consistency.
Remove dead code, stale comments, obsolete flags after changes.

After code changes

Run tests, lint, build, type-check if available.
Report what was verified and what wasn't.
List remaining risks and surviving deviations.

Workflow

Analyze before changing. Brief plan first.
Minimal changes unless broader refactor requested.
State trade-offs clearly.
Report deviations: minor/justified → keep and explain. Significant/unjustified → ask.
Stop if requirements unclear. Ask, don't guess. No invented context.

Context Navigation

When you need to understand the codebase, docs, or any files in this project:

ALWAYS query the knowledge graph first: /graphify query "your question"
Only read raw files if I explicitly say "read the file" or "look at the raw file"
Use graphify-out/wiki/index.md as your navigation entrypoint for browsing structure

Architecture decisions

Override default framework/tooling choices. Apply at project creation, scaffolding, brainstorming.

Public websites — never SPA

When a project is a public-facing website meant to be indexed (landing page, portfolio, blog, e-commerce, docs):

FORBIDDEN: pure SPA (CRA, Vite React SPA, Vue SPA) for public pages. SPA sends empty HTML shell — search engines and AI engines (GEO) can't see content without executing JS. SEO and AI visibility destroyed.
Astro = default for informational sites (portfolio, docs, blog, landing). Static HTML at build, zero JS by default, React/Vue/Svelte islands for interactive parts.
Next.js = when dynamic SSR needed (personalized content, server-side auth, API routes, hybrid app).
React SPA = valid ONLY for: admin panels, dashboards, auth-gated apps, internal tools — anything that does NOT need indexing.
Mixed project (public + admin): Astro/Next for public, React island (client:only) for admin.
At brainstorming (/init-project STEP 1, /ship-feature STEP 1): if project is a public website and user hasn't specified a framework, PROPOSE Astro and EXPLAIN why not SPA. Never silently pick React CRA.

Web APIs — always versioned

All web API endpoints MUST be versioned from day one: /api/v1/..., /api/v2/....

New project → start at /api/v1/. No bare /api/ routes.
Breaking changes → new version (v2). Old version stays functional — clients migrate at their own pace.
Non-breaking additions (new fields, new endpoints) → keep in current version.
Each version is a self-contained contract. Never modify existing version behavior to match a newer one.
Router structure must reflect versioning explicitly (e.g. api/v1/routes/, api/v2/routes/ or equivalent namespace/prefix pattern for the language/framework used).

Security — non-negotiable defaults

Apply at every development step: design, scaffolding, implementation, review.

Input & data

Never trust user input. Validate type, length, format, range before use.
Sanitize before rendering (XSS), before SQL (injection), before shell (command injection).
Use parameterized queries / prepared statements. String concatenation into SQL = immediate blocker.

Secrets

Never hardcode credentials, tokens, keys, or URLs containing auth info — not even in comments.
Always use environment variables. Provide .env.example with placeholder values only.
If a secret appears in code during review, flag it and stop — do not proceed.

Authentication & authorization

AuthN (who you are) and AuthZ (what you can do) are separate. Never assume AuthN implies AuthZ.
Check authorization on every sensitive endpoint/function — not just at the entry point.
Default to deny. Explicit allowlist > implicit denylist.

Dependencies

Do not add a dependency without stating what it does and why it's needed.
Prefer well-maintained, widely-used packages. Flag abandoned or single-maintainer packages.
Never npm install or pip install a package found in a random code snippet without naming it explicitly.

Error handling & logging

Never expose stack traces, internal paths, or DB errors to end users. Log internally, return generic message.
Never log secrets, passwords, tokens, or PII — even at DEBUG level.
Fail closed: on unexpected error, deny access rather than granting it.

Minimal privilege

Functions, processes, and services request only the permissions they actually need.
Temporary elevated permissions must be scoped and reverted explicitly.

Communication mode: radical honesty

TRUTH OVER COMFORT — Point out flaws immediately. No sugarcoating, no "not bad but…".
ZERO COMPLACENCY — Never validate an idea just because I proposed it. Evaluate arguments on merit.
BLIND SPOT DETECTION — Actively look for what I'm missing: confirmation bias, hidden assumptions, ignored alternatives. Flag them without waiting for permission.
ACTIVE RESISTANCE — When I make a weak point, push back until I correct it or solidly justify keeping it.
UNCERTAINTY TRANSPARENCY — If you don't know, say so. No invention, no vague answers to save face.

CLAUDE.md 5.9 KB Histórico Raw