Architectural guidance provided to Claude Code CLI for building yugioh game engine with prompts

ARCHITECTURAL_PRINCIPLES.md

System Prompt: Architectural Principles to Code By

Use rg tool to search for files efficiently

Core Principles

1. Clean, Simple, Maintainable Code

   • Favor readability over cleverness
   • Prioritize simplicity in design
   • Write code that future developers can easily understand
   • Follow established patterns within the codebase

2. React Paradigm Compliance

   • Use functional components with hooks
   • Maintain unidirectional data flow
   • Treat components as pure renderers of state
   • Minimize side effects in rendering logic
   • Separate UI concerns from business logic

3. No Hacky Fixes

   • Avoid workarounds that bypass the architecture
   • Don't use DOM manipulation where React state should be used
   • No direct DOM access except in isolated, ref-based scenarios
   • Never use global state outside the established state management system

4. Thoughtful Change Management

   • Consider the full impact of every change
   • Document assumptions behind your implementation
   • Write tests that validate your changes
   • Consider large-scale refactoring if it provides better architecture

5. Logical Decision Making

   • Be careful and thoughtful with every change
   • Avoid replacing working solutions with inferior alternatives
   • Refrain from making unnecessary changes
   • Focus on improvements that add clear, tangible value
   • Prioritize maintaining and improving overall code quality

System Architecture Overview

The Yu-Gi-Oh! Web Duel Interface follows a strict separation of concerns:

Game Engine (Source of Truth)

• Maintains the complete and authoritative game state
• Processes actions through dedicated handlers
• Emits domain events describing game occurrences
• Translates domain events to state patches
• Has no knowledge of UI components or rendering

UI Layer (Pure Rendering)

• Renders the current game state without modifying it
• Listens for events to trigger animations and UI feedback
• Maintains minimal UI-specific state (animations, menus, etc.)
• Dispatches player actions to the game engine
• Never directly modifies game state

Communication Pattern

• Game Engine → UI: Event-based (domain events, state patches)
• UI → Game Engine: Action-based (dispatching typed actions)

Implementation Guidelines

1. Domain Events vs. State Patches

   • Domain events describe WHAT HAPPENED (e.g., MONSTER_DESTROYED)
   • State patches describe HOW STATE CHANGED (e.g., STATE_PATCH)
   • UI components should process domain events for animations
   • State management should process state patches for updates

2. When to Consider Refactoring

   • When new requirements don't fit the current architecture
   • When multiple components need the same hack
   • When state management becomes complex or inconsistent
   • When the separation between engine and UI is compromised

3. Making Architectural Decisions

   • Evaluate if the change maintains separation of concerns
   • Consider the long-term maintainability over short-term convenience
   • Check if the solution follows the established event/action pattern
   • Determine if it's an isolated case or represents a systemic issue

Decision Framework for Changes

When implementing features or fixes, ask yourself:

1. Does this change maintain the separation between game logic and UI?
2. Would a proper domain event solve this problem better than a UI hack?
3. Is this a symptom of a larger architectural issue that should be addressed?
4. Am I introducing state duplication or inconsistency?
5. Would other developers understand my approach without extensive comments?

Remember: It's better to spend time on a proper architectural solution than to accumulate technical debt through quick fixes.