From 16a0541d4cee01817b6c6bb25c7174264a496014 Mon Sep 17 00:00:00 2001 From: Anders Lehmann Pier Date: Fri, 13 Jun 2025 09:35:02 +0200 Subject: [PATCH] Add comprehensive project instructions for Claude behavior throughout development --- project-config/project-instructions.md | 146 +++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 project-config/project-instructions.md diff --git a/project-config/project-instructions.md b/project-config/project-instructions.md new file mode 100644 index 0000000..d4f6e2a --- /dev/null +++ b/project-config/project-instructions.md @@ -0,0 +1,146 @@ +# Enhanced Claude Projects Instructions - Neural Nexus + +## Project Configuration + +**PROJECT TYPE:** HTML5 Puzzle Game Development +**PROJECT FOCUS:** Modern neural network-themed connection puzzle game +**FAST-TRACK STAGE:** Prototype → Development + +Please maintain this behavior throughout our collaboration: + +## Core Development Principles + +### Game Development Philosophy +- **Player Experience First:** Every decision should enhance fun and engagement +- **Performance-Driven Design:** Maintain 60fps on target devices at all costs +- **Progressive Complexity:** Gradual difficulty curve that builds player confidence +- **Contemporary Relevance:** Keep neural network theme modern and accessible +- **Accessibility Focus:** Ensure game works for diverse players and devices + +### Technology Stack Guidelines +- **Vanilla JavaScript Mastery:** Leverage ES6+ features for clean, efficient code +- **Canvas 2D Optimization:** Maximize rendering performance with smart drawing techniques +- **Mobile-First Responsive:** Design for touch interfaces, enhance for desktop +- **Zero Dependencies:** Maintain independence from external libraries for maximum control +- **Memory Efficiency:** Implement object pooling and proper cleanup patterns + +## Stage-Specific Behavior + +### Prototype Stage (Current Focus) +- **Prove Core Mechanics:** Validate that node connection gameplay is engaging +- **Establish Visual Style:** Create appealing modern aesthetic with neural theme +- **Optimize Performance:** Achieve target 60fps with smooth animations +- **Test Across Devices:** Ensure compatibility with desktop and mobile +- **Document Decisions:** Capture successful patterns and failed experiments + +### Development Stage (Next Phase) +- **Feature Implementation:** Add audio, save system, advanced levels +- **Code Quality Focus:** Refactor for maintainability and extensibility +- **Comprehensive Testing:** Systematic validation across all target platforms +- **User Experience Polish:** Smooth animations, feedback, and accessibility +- **Performance Tuning:** Detailed optimization for all device categories + +## Game-Specific Guidelines + +### Gameplay Mechanics + +#### Connection System Design +- **Intuitive Interaction:** Click/drag should feel natural and responsive +- **Visual Feedback:** Clear indication of valid targets and connection states +- **Error Prevention:** Graceful handling of invalid connection attempts +- **Pattern Clarity:** Target patterns must be immediately understandable +- **Progress Indication:** Players should always know completion status + +#### Level Design Philosophy +```javascript +// Level generation principles +const levelDesign = { + nodeCount: { + progression: "Start with 3-5 nodes, gradually increase to 12 max", + variation: "Occasional easier levels to maintain flow state" + }, + patternComplexity: { + early: "Simple chains and basic shapes", + middle: "Hub patterns and parallel paths", + advanced: "Complex networks and symmetrical designs" + }, + timing: { + generousStart: "60+ seconds for early levels", + gradualIncrease: "Reduce time as patterns become familiar", + skillBasedAdjustment: "Consider player success rate" + } +}; +``` + +### Performance Requirements + +#### Frame Rate Targets +- **Desktop:** Consistent 60fps on mid-range hardware (2019+) +- **Mobile:** Minimum 30fps on devices from 2020+ +- **Tablet:** 45-60fps for smooth touch interaction +- **Degradation Strategy:** Reduce particle effects before dropping frame rate + +#### Memory Management +```javascript +// Memory efficiency patterns +const performanceGuidelines = { + objectPooling: { + particles: "Reuse particle objects to avoid garbage collection", + connections: "Pool temporary connection objects during drag", + uiElements: "Cache frequently accessed DOM elements" + }, + canvasOptimization: { + clearStrategy: "Use clearRect() instead of fillRect() when possible", + drawCalls: "Batch similar drawing operations", + imageData: "Avoid getImageData() in animation loops" + }, + eventHandling: { + throttling: "Limit mousemove/touchmove events to 60fps max", + delegation: "Use event delegation for dynamic elements", + cleanup: "Remove all event listeners during level transitions" + } +}; +``` + +## Communication Style + +### Code Review and Suggestions +- **Performance First:** Always consider frame rate impact of new features +- **Explain Trade-offs:** Clearly articulate pros/cons of technical decisions +- **Show Examples:** Provide working code snippets for complex concepts +- **Test Recommendations:** Suggest specific testing scenarios for new features +- **Future Considerations:** Note how changes affect planned features + +### Problem-Solving Approach +- **Isolate Issues:** Break complex problems into testable components +- **Provide Alternatives:** Offer multiple solutions with different trade-offs +- **Consider Context:** Factor in current project stage and constraints +- **Document Decisions:** Capture reasoning for future reference +- **Progressive Enhancement:** Build features incrementally and test frequently + +## Quality Assurance Standards + +### Code Quality Metrics +- **Readability:** Code should be self-documenting with clear variable names +- **Modularity:** Functions should have single responsibilities under 50 lines +- **Performance:** No operations in game loop that cause frame drops +- **Error Handling:** Graceful degradation for all failure scenarios +- **Browser Compatibility:** Works consistently across target browsers + +### Success Criteria by Stage + +#### Prototype Success Indicators +- ✅ Core connection mechanics feel satisfying and responsive +- ✅ Visual style creates appealing, modern aesthetic +- ✅ Performance targets achieved on primary test devices +- ✅ Level generation creates engaging progression +- ✅ Players can complete 10+ levels without confusion + +#### Development Success Indicators +- ✅ All planned features implemented and tested +- ✅ Comprehensive cross-platform compatibility verified +- ✅ Performance optimized for target device range +- ✅ User experience polished with smooth transitions +- ✅ Code organized for maintainability and future features + +Remember: Neural Nexus should demonstrate that modern web games can be both technically excellent and deeply engaging. Every decision should serve the dual goals of player satisfaction and technical achievement. \ No newline at end of file