Skip to content

CLAUDE.md

Latest commit

 

History

History
134 lines (98 loc) · 6.1 KB

CLAUDE.md

File metadata and controls

134 lines (98 loc) · 6.1 KB

CLAUDE.md

CRITICAL WINDOWS-ONLY PLATFORM REQUIREMENTS

ABSOLUTE RULE: This is a Windows-only codebase. Claude Code MUST NEVER use Linux commands.

FORBIDDEN Linux Commands - NEVER USE THESE:

  • ls, grep, find, chmod, ./script.sh, /usr/bin/bash, cat, head, tail, rm, mv, cp

REQUIRED Windows Commands - ALWAYS USE THESE:

  • dir (not ls)
  • findstr (not grep)
  • where (not find)
  • del (not rm)
  • move (not mv)
  • copy (not cp)
  • type (not cat)
  • script.bat (not ./script.sh)
  • python (not python3)

File Operations:

  • Use Windows paths: E:\HOME\PyFlowGraph\
  • Execute batch files directly: run.bat (not ./run.bat)
  • Use backslashes \ or forward slashes / for paths

Project Overview

PyFlowGraph: Universal node-based visual scripting editor built with Python and PySide6. "Code as Nodes" philosophy with automatic pin generation from Python function signatures.

Commands

Running: run.bat Testing: run_test_gui.bat - Professional GUI test runner Dependencies: pip install PySide6

Architecture

Core: src/ contains 25+ Python modules

  • main.py - Entry point with Font Awesome fonts/QSS
  • node_editor_window.py - Main QMainWindow
  • node_editor_view.py - QGraphicsView (pan/zoom/copy/paste)
  • node_graph.py - QGraphicsScene (nodes/connections/clipboard)
  • execution/graph_executor.py - Execution engine with single process architecture
  • execution/single_process_executor.py - Direct Python interpreter execution management
  • commands/ - Command pattern for undo/redo system

Node System: node.py, pin.py, connection.py, reroute_node.py Code Editing: code_editor_dialog.py, python_code_editor.py, python_syntax_highlighter.py Event System: event_system.py - Live mode execution support

Key Concepts

Node Function Parsing: Automatic pin generation from Python function signatures with type hints Data Flow Execution: Data-driven (not control-flow), single process architecture, direct object references Graph Persistence: Clean JSON format, saved to examples/ directory Virtual Environments: Graphs can specify dependencies and use isolated venvs/ environments

File Organization

PyFlowGraph/
├── src/                    # 25+ Python modules + commands/
├── tests/                  # 18+ test files with GUI test runner
├── docs/                   # Organized documentation
│   ├── architecture/       # Technical architecture docs
│   ├── specifications/     # Feature specs (flow_spec.md, ui-ux, etc.)
│   └── development/        # Testing guides, implementation notes
├── examples/               # Sample .md graph files
├── venv/ + venvs/         # Virtual environments
└── run.bat, run_test_gui.bat # Launchers

Testing

Enhanced Testing Infrastructure (NEW):

  • 67-81% faster execution through parallel testing (pytest-xdist)
  • Intelligent failure analysis with automated fix suggestions
  • Coverage-driven test generation for missing tests
  • Token-efficient reporting optimized for Claude Code

Current Suite: 50+ test files covering node system, pins, connections, execution, file formats GUI Runner: run_test_gui.bat - Professional PySide6 interface with real-time status Coverage: Core components, command system, integration scenarios

Enhanced Testing Commands:

  • /test fast - Quick development cycle tests (unit + headless)
  • /test all --coverage - Full suite with coverage analysis
  • /fix-tests auto - Automated failure resolution with confidence scoring
  • /test-health overview - Test suite health monitoring and alerts

Direct Tool Usage:

  • python testing/test_runner.py --fast --format claude - Parallel execution with Claude-optimized output
  • python testing/test_analyzer.py --format claude - Failure pattern analysis and recommendations
  • python testing/test_generator.py - Generate missing tests from coverage gaps

Test Timeout Requirements: All tests MUST complete within 10 seconds maximum. Tests that run longer indicate performance issues or infinite loops and must be fixed to complete faster, not given longer timeouts.

Development Notes

  • PySide6 Qt-based GUI with Font Awesome icons
  • Single process execution for performance
  • No Claude attribution in commits or code comments
  • NEVER use emojis in any code, tests, or temporary files - causes encoding issues
  • Clean, professional, technical documentation only

Code Standards

NO UNICODE CHARACTERS RULE: Absolutely no Unicode characters (including emojis, symbols, special characters) in:

  • Source code (.py files)
  • Test files (all tests in tests/ directory)
  • Temporary test files or scripts
  • Comments, docstrings, or print statements
  • Variable names, function names, or any identifiers
  • Console output or logging messages

Reason: Unicode characters cause encoding errors on Windows console (cp1252 codec) and create test failures. Use ASCII text alternatives like "PASS"/"FAIL", "OK"/"ERROR", "->", "=>", etc.

Forbidden Characters: ✅❌⚠️📊💡🔄⏳🚨ℹ️🎯 and any character outside ASCII range (0x00-0x7F)

important-instruction-reminders

Do what has been asked; nothing more, nothing less. NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User. NEVER use emojis in any code, tests, or temporary files - causes Windows encoding errors.

CRITICAL GIT COMMIT RULE: NEVER commit changes unless the user explicitly asks to commit. Always wait for the user to test and verify changes work before committing. Do NOT commit automatically after making changes - this is forbidden.

RELEASE NOTES RULE: Write professional, technical release notes. Never use marketing language, excessive emojis, or promotional tone. Focus on factual changes, technical details, and concrete improvements. Avoid words like "revolutionary", "breakthrough", "amazing", etc.