From 79dcb83d5e44d5313a47d05da2ba11a36962b96d Mon Sep 17 00:00:00 2001 From: Mayukha Vadari Date: Thu, 20 Aug 2026 12:21:04 -0400 Subject: [PATCH] docs: Add AGENTS.md/CLAUDE.md for AI coding agent guidance Adds shared build/test/lint/architecture guidance for AI coding agents, with CLAUDE.md symlinked to AGENTS.md for Claude Code. Updates .gitignore so only personal/local AI-tool config is excluded, and documents the shared vs. local convention in CONTRIBUTING.md. --- .gitignore | 12 ++++++-- AGENTS.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + CONTRIBUTING.md | 12 ++++++++ 4 files changed, 98 insertions(+), 2 deletions(-) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/.gitignore b/.gitignore index c5af8eb7b4..745e74e2e7 100644 --- a/.gitignore +++ b/.gitignore @@ -72,11 +72,19 @@ DerivedData /.zed/ # AI tools. +# Shared/committable AI agent config (AGENTS.md, CLAUDE.md, GEMINI.md, .claude/settings.json, +# tool-specific rules files, etc.) should be checked in — see CONTRIBUTING.md. Only the +# personal/local variants below are ignored. /.agent /.agents /.augment -/.claude -/CLAUDE.md +/.claude/settings.local.json +AGENTS.local.md +CLAUDE.local.md +GEMINI.local.md +.aider.chat.history.md +.aider.input.history +.aider.tags.cache.v3 # Python __pycache__ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..3f075ac603 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,75 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (Claude Code, and other AGENTS.md-compatible +tools) when working with code in this repository. `CLAUDE.md` is a symlink to this file. + +For personal, untracked notes to an AI agent (not meant to be shared with other contributors), +use `AGENTS.local.md` / `CLAUDE.local.md` instead — see [CONTRIBUTING.md](./CONTRIBUTING.md). + +## Build + +Preferred: use the Nix devshell, which sets up the compiler, Conan, ccache, and (optionally) Rust automatically. + +```bash +nix develop # default shell (clang on macOS, gcc on Linux); also .#gcc, .#clang, .#gcc-plain, .#clang-plain, .#apple-clang +``` + +Manual build (also what the devshell does under the hood): + +```bash +./conan/init.sh # one-time Conan profile/remote setup (auto-run inside nix develop) +mkdir .build && cd .build +conan install .. --output-folder . --build missing --settings build_type=Release +cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release -Dxrpld=ON -Dtests=ON .. +cmake --build . --parallel +``` + +Key CMake options: `-Dxrpld=ON` (build the server binary, not just `libxrpl`), `-Dtests=ON`, `-Drust=ON` (builds `crates/`, requires cargo/rustc — off by default but always on in CI), `-Dunity=ON`, `-Dcoverage=ON`, `-Dwerr=ON`. `-Dverify_headers` is on by default; `cmake --build . --target verify-headers` compiles every header standalone. + +Protocol codegen (from `.macro` files) must be regenerated and committed when changed: + +```bash +cmake --build . --target setup_code_gen +cmake --build . --target code_gen +``` + +Rust crate tests (independent of the CMake build): `cargo test --manifest-path crates/Cargo.toml --workspace` (CI uses `cargo nextest`). + +## Testing + +Unit tests are a custom framework built into the `xrpld` binary itself (not Boost.Test/GTest/Catch): + +```bash +./xrpld --unittest --unittest-jobs # run all suites; N = ~half of available cores +./xrpld --unittest SomeSuiteName # run by name/prefix; an exact name match runs only that suite +``` + +(Multi-config generators produce the binary under e.g. `./Release/xrpld`.) Tests that run offline in under a minute should be automatic `--unittest` suites under `src/test/`; anything else is a manual/integration test. `tests/` (top-level, separate from `src/test/`) holds integration tests exercised against `libxrpl`/`xrpld`. + +## Lint/Format + +```bash +pip install pre-commit && pre-commit install +pre-commit run --all-files +pre-commit run clang-format --all-files # single hook +TIDY=1 pre-commit run clang-tidy # clang-tidy is opt-in (needs local clang-tidy + generated headers) +``` + +Manual clang-tidy: build the `tidy_prerequisites` target first, then `run-clang-tidy -p build -allow-no-checks src tests` (add `-fix -format` to auto-fix). + +## Architecture + +- `include/xrpl/` + `src/libxrpl/` — the core protocol library: ledger, shamap, consensus, crypto, json, resource, nodestore, rdb, peerfinder, and `tx/` (transaction application: `Transactor.cpp`, `applySteps.cpp`, invariants, payment paths). `tx/transactors/` has one file per transaction type, grouped by subsystem: `escrow/`, `vault/`, `lending/`, `sponsor/`, `nft/`, `token/` (MPT), `payment_channel/`, `permissioned_domain/`, `dex/`, `oracle/`, `did/`, `credentials/`, `bridge/`, `check/`, `delegate/`, `account/`, `system/`. Any change to transaction-processing behavior must be gated behind an Amendment. +- `src/xrpld/` — the server application built on top of `libxrpl`: `app`, `core`, `overlay` (P2P networking), `peerfinder`, `perflog`, `rpc`, `shamap`. `main` builds an `ApplicationImp` implementing `Application`; most components hold a reference to it (`app_`), giving broad cross-component access — expect to trace call chains through `Application&`. +- `src/test/` — unit tests mirroring the subsystems above, plus `jtx/` (the transaction-building test DSL — e.g. `jtx/escrow.h`, `jtx/vault.h`, `jtx/sponsor.h`, `jtx/permissioned_dex.h`) and `unit_test/` (the custom test framework itself, derived from Beast). +- `src/tests/` — a second, separate tree of integration-style tests for `libxrpl`. +- `crates/` — a Rust workspace (only built with `-Dxrpld -Drust=ON`) bridged into C++ via `cxxbridge`/the `cxx` crate; currently just a `hello_world` interop scaffold. Requires the Rust toolchain pinned in `rust-toolchain.toml` (the Nix devshell provides it automatically). + +## Code Style (see `docs/CodingStyle.md` and `CONTRIBUTING.md` for full detail) + +- New file placement is strict: `libxrpl` headers → `include/xrpl`; `libxrpl` sources → `src/libxrpl`; other non-test server code → `src/xrpld`; tests → `src/test`; benchmarks → `src/benchmarks`. +- Header includes must stay levelized (checked by `.github/scripts/levelization`). +- Allman braces, tabs-as-4-spaces (no literal tabs), 80-char lines, east `const`, no naked `new`/`delete`, `*`/`&` bound to the type not the variable (`SomeObject* myObject`), never declare multiple pointers/refs in one statement. +- Class member order: private members first, then the six special members in order (dtor, default ctor, copy ctor, copy assign, move ctor, move assign). +- Use `XRPL_ASSERT`/`UNREACHABLE` instead of raw `assert`/`assert(false)` outside constexpr functions and unit tests; each needs a unique name of the form `scope::function : short description` (used for Antithesis instrumentation). +- Commits: imperative subject line ≤50 chars (72 hard limit), capitalized, no trailing period; each commit should build and pass tests on its own; prefer squashing to one logical commit per PR. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 35309a9824..312ad32840 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,6 +59,18 @@ to an existing XLS. Neither change will be released (in an amendment's case, marked as `Supported::yes`) until the corresponding XLS's status is `Final`. +## AI coding agents + +[`AGENTS.md`](./AGENTS.md) (and its `CLAUDE.md` symlink, for Claude Code) holds shared, +checked-in guidance for AI coding agents working in this repository — build/test/lint +commands and architecture notes. Additional `AGENTS.md`/`CLAUDE.md` files may exist in +subdirectories to give agents context specific to that part of the codebase. + +If you want to give an agent personal instructions that shouldn't be shared with other +contributors (e.g. your own workflow preferences), put them in `AGENTS.local.md` or +`CLAUDE.local.md` instead — those are gitignored. Likewise, `.claude/settings.local.json` +is for personal, untracked Claude Code settings, while `.claude/settings.json` is shared. + ## Before making a pull request (Or marking a draft pull request as ready.)