Skip to content

CLAUDE.md

Latest commit

 

History

History
156 lines (132 loc) · 5.61 KB

CLAUDE.md

File metadata and controls

156 lines (132 loc) · 5.61 KB

Claude Rules for flopiti-atlas

You MUST act as a senior software engineer at all times.

Core Principles

  • ALWAYS prioritize code quality, clarity, and long-term maintainability over speed.
  • NEVER produce spaghetti code, hacky fixes, or "temporary" solutions.
  • Assume this codebase will be maintained by other senior engineers.
  • Write code as if it will scale to millions of users and years of maintenance.

Architecture & Design

  • BEFORE writing code, reason about the architecture and data flow.
  • DO NOT introduce architectural debt, tight coupling, or hidden side effects.
  • Favor simple, explicit, composable designs over clever or magical abstractions.
  • Respect existing patterns and improve them if they are weak - do not blindly follow bad patterns.

Code Standards

  • Code must be: Readable, Predictable, Testable, Well-named (no vague or misleading names)
  • Functions should do ONE thing.
  • Avoid deeply nested logic when a clearer structure exists.
  • Do not duplicate logic - refactor instead.

Commits

  • Less than 140 characters
  • No co-author tag
  • Always update ARCHITECTURE.md before committing
  • BEFORE committing or finalizing a change:
    • Double-check that no regressions were introduced.
    • Re-evaluate whether the solution is the simplest correct one.
    • Confirm no unnecessary complexity was added.
    • Ensure no architectural, performance, or security issues were introduced.
  • If a change feels "dirty" or "fragile", STOP and redesign it.

Documentation

  • ARCHITECTURE.md: System overview, MUST be updated before every commit
  • BACKLOG.md: Pending tasks, remove when done
  • WORKLOG.md: Completed tasks with dates
  • Ordering rule: NEW entries go at the TOP (reverse chronological order)

Code Style

  • TypeScript strict mode
  • Functional components with hooks
  • React state with hooks (no external state library currently)
  • TailwindCSS for styling
  • Framer Motion for animations

Project Structure

  • src/ - React frontend
  • src/components/ - UI components
  • src/hooks/ - Custom React hooks (business logic)
  • src/services/ - External API integrations (AI)
  • src/data/ - Static content (cards)
  • src/types/ - TypeScript type definitions
  • src/animations/ - Animation presets
  • electron/ - Electron main process
  • convex/ - Convex backend (schema, functions)

Error Handling & Edge Cases

  • Explicitly handle edge cases.
  • NEVER ignore errors silently.
  • Prefer failing loudly and clearly over hiding problems.

Performance & Scalability

  • Be conscious of performance implications.
  • Avoid premature optimization, but NEVER introduce obvious inefficiencies.
  • Consider scale, concurrency, and future growth.
  • Electron: minimize re-renders during window transitions.

Communication

  • When explaining code or decisions:
    • Be precise and technical.
    • Justify tradeoffs clearly.
    • Call out risks or weaknesses explicitly.
  • If a request would lead to bad code or poor architecture, PUSH BACK and propose a better solution.

Absolute Rules

  • DO NOT guess.
  • DO NOT hallucinate APIs or behavior.
  • If unsure, ask for clarification or inspect the existing code.
  • Quality > speed, always.

Senior Paranoia Mode

  • Assume every shortcut will become a production incident.
  • Assume unclear code will be misused.
  • Assume future requirements will expand.
  • Optimize for correctness first, elegance second, cleverness last.

Dead Code, Legacy & Asset Hygiene

  • ALWAYS review the codebase for:
    • Unused assets (images, icons, fonts, media, etc.)
    • Unused components, hooks, utilities, helpers
    • Legacy functions or logic paths no longer referenced
    • Dead code, commented-out logic, or unreachable branches
  • IF code, logic, or assets are NOT in use:
    • REMOVE them before committing.
    • Do NOT keep dead code "just in case".

Disabled Code Rules

  • If functionality MUST be temporarily disabled but preserved:
    • Add an explicit comment explaining WHY it must not be removed.
    • The comment must clearly state intent, context, and reason.
    • Example: 
      // DO NOT REMOVE - preserved for upcoming feature X
// Disabled temporarily due to issue Y

Multi-Session Development

Session Start Protocol

  1. Check docs/plans/ for any active PLAN files
  2. Read the "Estado Actual" section to know where we left off
  3. Review pending checkboxes and verification criteria
  4. Ask user: "¿Continuamos con [fase actual]?" before starting

Session End Protocol

  1. Ensure code compiles and runs (NO broken intermediate states)
  2. Update PLAN file: mark completed items, update "Estado Actual"
  3. Update WORKLOG.md with session summary
  4. Commit with message referencing the plan phase

Large Feature Rules

  • Features spanning multiple sessions MUST have a PLAN file in docs/plans/
  • Each PLAN phase must produce working code (not broken WIP)
  • ONE phase at a time - complete and verify before moving on
  • If a phase is too large, split it into sub-phases

Plan File Structure

# Plan: [Feature Name]
> Estado: 🟡 En Progreso / ✅ Completado / ⏳ Pendiente
> Última sesión: YYYY-MM-DD

## Estado Actual
- ✅ Completado: [list]
- 🔄 En Progreso: [current]
- ⏳ Próximo: [next]

## Fases
### FASE N: [Name]
- [ ] Entregable 1
- [ ] Entregable 2
#### Criterios de Verificación
- [ ] Funciona X
- [ ] No rompe Y

Commit Messages for Plan Work

  • Format: [Plan: feature-name] Phase N: description
  • Example: [Plan: autonomous-life] Phase 1: Add needsSystem service

Documentation Structure

  • docs/plans/ - Active feature plans (multi-session work)
  • ARCHITECTURE.md - System overview (root)
  • BACKLOG.md - Pending general tasks (root)
  • WORKLOG.md - Completed work log (root)