Tom
e09b961f39
* docs(agents): exempt test headers from the two-line comment limit The one-or-two-line comment rule rests on "the diff and commit message carry the rationale". For a test that premise is false. A test outlives the PR that added it, and the next person to read it is reading it because it failed - months later, in someone else's change, with the original discussion out of reach. That reader has one decision to make: real regression, or an expectation that has gone stale? The assertions alone cannot answer it, so the justification has to live in the file. The new "Test comments" section requires three things of a test header - what is under test by symbol and file, why that behavior is required, and the specific regression that returns if the assertions are deleted or relaxed - and grants whatever length they need. Authoritative statement lives in that section of .github/copilot-instructions.md, anchored at #test-comments. AGENTS.md and CLAUDE.md link to it rather than restate it. The test/** entry in .coderabbit.yaml carries the one permitted copy, since a YAML instruction cannot follow a link. This documents existing practice rather than changing it: 57 of the 72 suites with a test_main.cpp already open with three or more comment lines, test/test_gps_fix_hold/test_main.cpp with eleven. The rule as written forbade all of them, and automated reviewers acted on it. Scoped to the single comment bullet, not to the whole "General Style" section. Unlike "Naming Conventions", that section also holds the logging tiers and the Throttle rule, which bind test code as hard as src/; a blanket preamble would have quietly exempted tests from millis() discipline as well. The exception is bounded. The CodeRabbit entry still flags narrative that carries no contract - debugging journey, changelog prose, restating what the assertions plainly do - and per-case comments that merely repeat the test name. The documentation-does-not-live-here rule is untouched. * docs(agents): cut the test-comment rule to its essential statements A section about comment length had no business running to 373 words. Canonical section down to 194: dropped the elaboration of why the commit message is unavailable, the aside about which bullet reviewers most often cut, the "not licence for narrative" preamble, and the closing flourish. What remains is what an agent has to act on - the premise that fails for tests, the three things a header states, the instruction to reject a shorten-this review comment, and the worked example. Pointer files carry scope, not argument. The AGENTS.md bullet is one sentence and a link, matching the Test naming pointer directly above it. The .coderabbit.yaml copy keeps its imperatives, since a YAML instruction cannot follow the link to find them, but loses the causal explanation it did not need in order to act.
3.8 KiB
Claude Code instructions
TL;DR
Local tests ./bin/run-tests.sh(exit 0 GREEN · 1 RED · 2 AMBER · 3 FILTERED)Hardware tests meshtastic/meshtastic-mcp ( MESHTASTIC_FIRMWARE_ROOT→ this checkout)Format trunk fmtMirror docs .github/copilot-instructions.md(canonical) ·AGENTS.mdNeed this? It's here.
General helpers (clamp, UTF-8, string fmt…) src/meshUtils.hLogging macros (LOG_DEBUG / INFO / WARN…) src/DebugConfiguration.hElapsed time / deadlines (never bare millis()compares)src/mesh/Throttle.hNew module skeleton inherit ProtobufModule<T>insrc/mesh/ProtobufModule.hObserver / event wiring src/Observer.hTest naming (the src/rule does not apply)copilot-instructions.md#test-naming Test comments (the 1-2 line limit does not apply) copilot-instructions.md#test-comments
Read .github/copilot-instructions.md first. That file is the canonical agent-facing document for this repo. It covers project layout, coding conventions, the build system, CI/CD, the native C++ test suite, and the MCP Server & Hardware Test Harness. Read it top-to-bottom before starting any non-trivial change.
This file (CLAUDE.md) is a short pointer for Claude Code sessions. Slash commands live in .claude/commands/.
House rule: documentation does not live in this repo
This repository holds firmware code. There is no docs/ directory - the design documents that used to sit there were published to meshtastic/meshtastic in #11488 and the directory was deleted - and it must not come back. Do not create a .md file to describe a feature, a configuration surface, an API, a wire format, or a design; write it in the docs repo and link that PR instead. Never leave a write-up behind in the tree: no investigation notes, no mitigation plans, no migration checklists, no "how we got here" narrative, no summaries of what a change did. That is what the PR description and the commit message are for, and they are the only place it belongs. When you do write documentation upstream, write a technical manual, not a novel - what the feature does, the settings it exposes in the user's terms, and the exact API or protocol a client speaks. No story of the debugging journey, no rationale essays, no changelog prose. Concise and factual, as short as the facts allow.