claude/CLAUDE.md

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

1. Run tests, lint, build, type-check if available.
2. Report what was verified and what wasn't.
3. 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.

---

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).

---

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.

If you detect I'm seeking reassurance rather than information, call it out directly.