Add CLAUDE.md with development guidance for AI coding agents - #324
Merged
Conversation
Captures the non-obvious knowledge needed to work productively in this repo: the custom pymtl3 fork setup, how to actually exercise Verilog translation in tests (--test-verilog), RTLIR translator constraints, the ctrl-step protocol and val/rdy conventions (including FUs that snoop operands without handshakes), register-cluster token semantics, test-suite timing expectations, and how to distinguish local toolchain issues from real failures.
ShangkunLi
reviewed
Jul 18, 2026
Per review: the content moves to AGENTS.md (the convention Codex and other agents read) with a tool-neutral header; CLAUDE.md becomes an @AGENTS.md import so Claude Code loads the same single source of truth. Also documents the naming conventions observed in the codebase: CamelCase classes/type names, snake_case functions and variables, UPPER_SNAKE_CASE constants, and the kCamelCase attribute keys.
ShangkunLi
approved these changes
Jul 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
CLAUDE.mdat the repo root — the standard file Claude Code (and other AI coding agents) read at session start to learn how a repository works.The content is distilled from the practical lessons of recent development sessions (PRs #320 and #322), prioritizing knowledge that is not discoverable by reading a file or two:
pymtl3.1@yo-struct-list-fixfork requirement, submodules, verilator/pkg-config, and how to recognize the local verilator-version import failure as a toolchain issue rather than a code bug.--test-verilogdoes),pytest.ini's hidden tracebacks, which test tiers take seconds vs. ~20 minutes, and thatassert N < Nfailures mean a kernel deadlocked.in/not inon hardware values, no tuple free variables, silent no-op bit-slice<<=in@update_ff(use set/clear masks), and the constant-wire pattern that works instead.ctrl_proceed, per-consumer done-latching), val/rdy conventions including FUs that snoop operands without handshakes, the comb-loop hazard through FUrecv_in.rdy→send_out.rdy, register-cluster armed/token semantics, the three tile variants that must stay in sync, and how kernels are encoded in tests.Docs-only change; no RTL or test modifications.