Add comprehensive CLAUDE.md for AI assistant guidance#2
Conversation
Documents codebase structure, tech stack, CLI commands, architecture (ECHO vs Raft), config conventions, testing, CI/CD, and known quirks across all three deployment tiers (simulation, MQTT demo, ESP32). https://claude.ai/code/session_017TNhudtHXNTBnVkwbjuKYo
There was a problem hiding this comment.
Pull request overview
Adds a new CLAUDE.md to document the echod repository for AI-assisted development, covering repo layout, phase-specific commands, architecture notes (ECHO vs Raft), configuration conventions, testing, CI, and known quirks across simulation/MQTT demo/ESP32 tiers.
Changes:
- Introduces a comprehensive
CLAUDE.mdguide describing the repo’s components and phases. - Documents common CLI workflows (simulation + MQTT demo), env vars, and configuration centralization.
- Summarizes architecture and CI/testing expectations for contributors/agents.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Development Branch | ||
|
|
||
| Active development happens on branch `claude/add-claude-documentation-Dvls5`. The stable branch is `main`. |
There was a problem hiding this comment.
The "Development Branch" section hard-codes a specific feature branch name. This will become stale and is not actionable for most readers once the branch is merged/deleted; consider removing it or replacing it with evergreen guidance (e.g., refer to main as default branch and avoid documenting ephemeral branch names).
| │ │ ├── config.py # ALL timing/energy/consensus constants live here | ||
| │ │ ├── node.py # Base Node + Coordinator + Leaf classes | ||
| │ │ ├── cluster.py # Cluster orchestrator + event loop management |
There was a problem hiding this comment.
simulation/core/node.py is described as containing the base Node + Coordinator + Leaf classes, but Coordinator and Leaf are implemented in simulation/core/coordinator.py and simulation/core/leaf.py in the current repo. Update this repository tree entry (and/or add entries for coordinator.py/leaf.py) so readers can locate the right implementation files.
| pip install -r requirements.txt | ||
|
|
||
| # Run tests | ||
| python3 -m pytest simulation/tests/ rpi/tests/ -v | ||
|
|
There was a problem hiding this comment.
In the Phase 1 section, the instructions install only requirements.txt but then run pytest over rpi/tests/ too. rpi/tests imports rpi.coordinator.transport, which imports paho.mqtt.client, so this command will fail unless rpi/requirements.txt is installed. Consider changing this Phase 1 test command to run only simulation/tests/, or explicitly install -r rpi/requirements.txt before including rpi/tests/.
Documents codebase structure, tech stack, CLI commands, architecture
(ECHO vs Raft), config conventions, testing, CI/CD, and known quirks
across all three deployment tiers (simulation, MQTT demo, ESP32).
https://claude.ai/code/session_017TNhudtHXNTBnVkwbjuKYo