Skip to content

docs(agents): document running targeted tests with BLS cgo flags - #1622

Merged
lklimek merged 1 commit into
devfrom
docs/agents-test-hints
Nov 17, 2026
Merged

lklimek merged 1 commit into
devfrom
docs/agents-test-hints

Conversation

@Claudius-Maginificent

@Claudius-Maginificent Claudius-Maginificent commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

TL;DR: Contributor and AI-agent instructions now explain how to run a single test package without a native-library compile error, and Claude Code actually loads those instructions.

User story

As a contributor or AI coding agent, I want to run just the tests I touched, to get fast feedback without running the whole suite through make.

Scenario

Base flow

A contributor changes one package and runs its tests directly with go test.

Actual behavior

The build fails with blschia.cpp:17:10: fatal error: dashbls/bls.hpp: No such file or directory, and the docs do not say why. Claude Code also does not load AGENTS.md: CLAUDE.md only mentions it in prose.

Expected behavior

The docs give the exact environment needed to run go test on one package, and Claude Code sessions start with AGENTS.md in context.

Detailed discussion

What was done

  • AGENTS.md:
    • New "Running targeted tests" section: explains the error (the Makefile passes the BLS cgo flags only to its own targets) and gives the CGO_ENABLED/CGO_CXXFLAGS/CGO_LDFLAGS exports, copied from the Makefile.
    • Hints: build/ exists only where make build-bls ran (fresh clones and git worktrees need it, or BLS_DIR pointing at a checkout that built it); macOS gmp flags; how CI runs tests; libpcap-dev for cmd/abcidump; -count=1.
    • Build/test command list: adds make build-bls with its prerequisites, documents LINT_BASE for stacked PRs, and corrects the target descriptions. make test uses -tags deadlock without -race, make test_race uses -race without the tag, and neither is how CI runs tests.
  • CLAUDE.md: replaces the prose reference with an @AGENTS.md import. Per the Claude Code memory docs, a CLAUDE.md that only tells Claude to read AGENTS.md does not load it, and a CLAUDE.md in the repo stops Claude Code from reading AGENTS.md on its own.

Testing

  • Ran the documented exports followed by go test -count=1 ./crypto/bls12381/: passes. The same flags with BLS_DIR pointing at another checkout let go test -race ./internal/p2p/ pass in a git worktree that had no BLS build.
  • markdownlint with .github/linters/markdownlint.yml: no new findings. The 4 MD007 findings on the existing Protobufs list predate this PR.

Breaking changes

None.

🤖 Co-authored by Claudius the Magnificent AI Agent

🤖 Generated with Claude Code

PR Hygiene · 3bdab33

  • Bots — thepastaclaw not yet — /skip-bots proceeds without the ones not yet reported
  • Self-review — not asked of a bot author
  • Build green
  • Approvals
    • files with no dedicated owner (AGENTS.md, CLAUDE.md) — lklimek or shumkov

When every merge requirement is met, the PR Hygiene check passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.

A bare `go test` fails with `dashbls/bls.hpp: No such file or directory`
because only Makefile targets pass the BLS cgo flags. Document the flags,
worktree/macOS/CI hints, and correct the make target descriptions.

CLAUDE.md now imports AGENTS.md with `@AGENTS.md`; a plain-text reference
does not load the file into Claude Code's context.

<sub>🤖 Co-authored by [Claudius the Magnificent](https://github.com/lklimek/claudius) AI Agent</sub>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@thepastaclaw

thepastaclaw commented Nov 17, 2026 •

Copy link
Copy Markdown

🕓 Review not started yet because the new head is waiting for the 30-minute push debounce.

  • Request normal review — click when the PR is ready for review.
  • Request priority review — click to move this review to the front of the queue.

Commit 3bdab33. Normal review starts when eligible; priority review starts as soon as a slot is available.

@lklimek
lklimek marked this pull request as ready for review November 17, 2026 08:43
@github-actions

Copy link
Copy Markdown

Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

@github-actions github-actions Bot added the waiting-bots Waiting for the review bots to report on this head label Nov 17, 2026
@lklimek
lklimek merged commit ecdbe41 into dev Nov 17, 2026
23 of 25 checks passed
@lklimek
lklimek deleted the docs/agents-test-hints branch November 17, 2026 09:08
@github-actions github-actions Bot added this to the v2.0 milestone Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

waiting-bots Waiting for the review bots to report on this head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants