project-claude-md

Task

Generate or update a CLAUDE.md for the project at $1 (relative path under packages/<domain>/).

Process

1. Read the project source to understand its internals:

   • main/*.c, main/*.h — all source files, pin defines, task structure
   • main/CMakeLists.txt — REQUIRES list
   • sdkconfig.defaults — target, features, stack sizes
   • justfile — build/flash/monitor recipes and their exact names
   • README.md — existing description
   • WIRING.md — hardware details
   • Kconfig.projbuild — configurable options
   • components/ — local components
   • idf_component.yml or managed_components/ — external dependencies

2. Generate CLAUDE.md following the template below

Template

Model after the best existing examples: audiobook-player/CLAUDE.md (181 lines) and xbox-switch-bridge/CLAUDE.md (125 lines).

# CLAUDE.md

This file provides guidance to Claude Code when working with this project.

## Project Overview

<What this project does, target hardware, current status.>

## Build Commands

### Using justfile

```bash
just build       # Build firmware (containerized)
just flash       # Flash to device
just monitor     # Serial monitor
just develop     # Build + flash + monitor
just clean       # Remove build artifacts

<Include ALL recipes from the project's justfile with descriptions.>

Critical Hardware Notes

GPIO Pin Constraints

<Board-specific pin reservations, strapping pins, bus contention issues.> <Only include if there ARE constraints — omit for simple projects.>

Power Considerations

<Only if non-trivial: battery, deep sleep, current requirements.>

Architecture

<How the firmware is structured: main loop vs FreeRTOS tasks, state machine, communication flow.> <Include component/module descriptions for multi-file projects.>

Common Development Tasks

<Task 1>

Troubleshooting

Style Rules

• Target 80-150 lines — enough detail for Claude to work effectively, not a tutorial
• Build commands must be accurate — read the actual justfile, don't guess recipe names
• Pin constraints only when real — omit the section for simple projects
• Architecture section scales with complexity — 2 lines for a single-file project, a component table for complex ones
• No generic ESP-IDF advice — only project-specific information
• Include credential handling if the project uses WiFi/API keys (where to create credentials.h, what values to set)