Skip to content

docs: Codify recurring PR review feedback into AGENTS.md #8198

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mvadari wants to merge 10 commits into
base: develop
Choose a base branch
from
Open

docs: Codify recurring PR review feedback into AGENTS.md #8198

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
5b6cd13
docs: Codify recurring PR review feedback into AGENTS.md
mvadari Sep 5, 2026
0a1708d
docs: Add subsystem AGENTS.md files for transactors, ledger helpers, …
mvadari Sep 8, 2026
6d2c699
Merge branch 'develop' into mvadari/codify-agents-md
mvadari Sep 8, 2026
7c642cd
docs: Scope AGENTS.md content to the smallest applicable folder
mvadari Sep 9, 2026
40988e1
Merge remote-tracking branch 'upstream/mvadari/codify-agents-md' into…
mvadari Sep 9, 2026
6b9db24
docs: Loosen Nix mandate, extract ARCHITECTURE.md, add docs-upkeep note
mvadari Sep 9, 2026
6dc958c
docs: Fix std::unexpected wording, split UNREACHABLE out of amendment…
mvadari Sep 9, 2026
de1a5f8
Merge branch 'develop' into mvadari/codify-agents-md
mvadari Sep 9, 2026
ef55ca9
docs: Drop redundant repo-level AGENTS.md pointers, shorten Build sec…
mvadari Sep 10, 2026
b4417cb
Merge remote-tracking branch 'upstream/mvadari/codify-agents-md' into…
mvadari Sep 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 9 additions & 15 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,7 @@ This file provides guidance to AI coding agents (Claude Code, and other AGENTS.m

@pratikmankawde pratikmankawde Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of duplicating content here, we should just point to the relevant files. BUILD.md, CONTRIBUTING.md, others: rippled/docs/*.md. This doesn't need to sit it context. This should only be fetched when required.

@mvadari mvadari Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any specific places I should point to? It's already pointing to those files when one exists and not duplicating existing documentation.

@pratikmankawde pratikmankawde Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pointing will be per-heading:
Build: Build.md
Coding Guidlines: docs/CodingStyle.md
Please check the project-map.md file I attached in another comment.

## Build

Required on Linux/macOS: use the Nix devshell, which sets up the compiler, Conan, ccache, and (optionally) Rust automatically.

```bash
nix develop
```

For alternate devshell variants (specific compiler, no-compiler, coverage), see [docs/build/nix.md](./docs/build/nix.md). For the manual build steps, CMake options, and protocol codegen commands, see [BUILD.md](./BUILD.md) (`## Steps`, `## Options`, `## Code generation`).
For the build steps, CMake options, and protocol codegen commands, see [BUILD.md](./BUILD.md) (`## Steps`, `## Options`, `## Code generation`). Nix development shells are available in the repo (not required) — see [docs/build/nix.md](./docs/build/nix.md) for setup and variants.

Rust crate tests (independent of the CMake build): `cargo test --manifest-path crates/Cargo.toml --workspace` (CI uses `cargo nextest`).

Expand All @@ -21,22 +15,22 @@ Unit tests are a custom framework built into the `xrpld` binary itself (not Boos
- A suite's `--unittest` name is built from the arguments to its `BEAST_DEFINE_TESTSUITE`/`BEAST_DEFINE_TESTSUITE_PRIO` macro (usually at the bottom of the test file), in reverse order and joined with `.`: `BEAST_DEFINE_TESTSUITE(Credentials, app, xrpl)` → `xrpl.app.Credentials`.
- `--unittest-arg` does nothing — don't use it.
- Tests that run offline in under a minute should be automatic `--unittest` suites; anything else is a manual/integration test.
- New tests should be written using `gtest` under `src/tests/` unless that isn't possible, in which case fall back to the legacy Beast framework under `src/test/`. `tests/` (top-level) holds integration tests exercised against `libxrpl`/`xrpld`.
- New tests should be written using `gtest` under `src/tests/` unless that isn't possible, in which case fall back to the legacy Beast framework under `src/test/` (see [src/test/AGENTS.md](./src/test/AGENTS.md) for conventions specific to that directory). `tests/` (top-level) holds integration tests exercised against `libxrpl`/`xrpld`.

## Lint/Format

See [CONTRIBUTING.md](./CONTRIBUTING.md#pre-commit-hooks) for `pre-commit` setup and [CONTRIBUTING.md](./CONTRIBUTING.md#clang-tidy) for `clang-tidy` (opt-in, needs local `clang-tidy` and generated headers).

## Code Style

New file placement and header levelization: see [CONTRIBUTING.md](./CONTRIBUTING.md#before-making-a-pull-request). Braces, whitespace, member order, and other conventions: see [docs/CodingStyle.md](./docs/CodingStyle.md). `XRPL_ASSERT`/`UNREACHABLE` contracts: see [CONTRIBUTING.md](./CONTRIBUTING.md#contracts-and-instrumentation). Commit messages: see [CONTRIBUTING.md](./CONTRIBUTING.md#good-commit-messages).
New file placement and header levelization: see [CONTRIBUTING.md](./CONTRIBUTING.md#before-making-a-pull-request). Braces, whitespace, member order, and other conventions: see [docs/CodingStyle.md](./docs/CodingStyle.md). `XRPL_ASSERT`/`UNREACHABLE` contracts: see [CONTRIBUTING.md](./CONTRIBUTING.md#contracts-and-instrumentation). Commit messages: see [CONTRIBUTING.md](./CONTRIBUTING.md#good-commit-messages). New public functions/methods need a Doxygen-style comment.

Comments should explain _why_, not _what_/_how_ — the code already shows that. Only describe what/how when the code itself would otherwise be confusing (a non-obvious workaround, a subtle invariant, a surprising constraint).

@bthomee bthomee Sep 15, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd also suggest expressing a preference here for comments that follow proper sentence format: start with a Capital letter and end with a period.

The codebase is very inconsistent and it's not worth spending dedicated time on cleaning them up by rewriting. However, it would be worth to ensure that new/updated comments are consistent.


## Architecture

Paths below reflect the current layout; update this section if modularization moves a subsystem to a different directory.
See [ARCHITECTURE.md](./ARCHITECTURE.md) for the directory-by-directory map of the codebase.

## Keeping docs current

- `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/` — unit tests for `libxrpl` written in `gtest`, gradually replacing the `src/test` equivalents.
- `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).
When you add or change a convention, or touch a subsystem that has its own `AGENTS.md`, `README.md`, or `ARCHITECTURE.md`, update that documentation in the same change rather than leaving it stale.
9 changes: 9 additions & 0 deletions ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Architecture

@pratikmankawde pratikmankawde Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs to go in project-map.md file. Attaching mine:
project-map.md

@pratikmankawde pratikmankawde Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

project-map.md file then links to other files like docs/consensus.md to deeper details. None of those files are actually loaded in context at startup. They are pulled as required. I have files containing details on architecture, components, features, etc.

@mvadari mvadari Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feels like primarily a disagreement on file name, and seems to disagree with your desire on keeping context small (i.e. IMO this project map file should be split up into smaller files, one of them being this ARCHITECTURE.md). Can you clarify what you're looking for?

@pratikmankawde pratikmankawde Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not the name really. Since we will need to refer it in some repo level CLAUDE.md/AGENTS.md file, and we can use any name there.

It's about the purpose. So the project-map is supposed to contain short idea about how the project is structured. It is supposed to map the project tree itself. It is the go to place for AI Agent to find things. Hence the name. A map basically. It stays under 200 lines. It should always remain in context, so that the agent can look at the map and navigate. It should need to be read again and again. If we break this down into individual files, the agent will definitely miss (intentionally skip in most cases) reading connected/related pieces together.

The architecture.md contains the architecture of the software itself. Like the building blocks and how they interact. I am sharing my achitecture.md file here.
architecture.md

I had this linked into the project-map file but I removed it before sharing that file, it it had local paths and to avoid confusion.

@pratikmankawde pratikmankawde Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

project-map file basically removes the need of individual indirection files in each sub-folder. I tried to find the blog post from Anthropic or OpenAI, where they suggest the usecase and benefits of project-map.md file and they use the same name. But couldn't find it now. Maybe they removed it after their source leak was attributed to the leaked project-map file XD
Not attached to the name though. It is just that architecture.md should define software, and project-map should define the project arrangement.

@mvadari mvadari Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you open a separate PR that adds those? I'd like to get the benefits from this PR in first, and these changes would be a big scope expansion (plus, I think it makes more sense for that PR to come from you).

@pratikmankawde pratikmankawde Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But that new PR will anyway remove all the agents.md files from all the sub dirs!

For this PR, I would suggest we put the project-map.md file in .agents/ folder. That's it. Remove everything else.

It already points to other important files. It points to Contributing.md file as well, which contains code guidelines. It also points to other coding and general guidelines files.

Any developer can just point their agents.md/claude.md to this project-map.md.
In next iterations, we can include more specific files. All of them will go in .agents/ folder.

If we do it any other way, we just add redundant linked files all over the repo. This way we get what we need, a repo level+ repo. specific common info. inside the repo. itself, without breaking anyone's personal setup. Since that goes through repo level AGENTS.md/CLAUDE.md files, which we really should not touch.

@kuznetsss What do you think?

@mvadari mvadari Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sub-dir AGENTS.md files are all different than what's contained in the project-map - the project-map.md file doesn't contain information that is helpful for an agent wrt actually doing the work, it only points it to the right section of the code to get started.

@pratikmankawde pratikmankawde Sep 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's exactly what the project-map.md file is for. 'information helpful for actually doing the work' is something, we want the agent to read only when it is needed. We don't want to pollute the context with info about each module per say.
A-few lines in info about a feature is not going to help the agent much anyway. It will read the code and docs. And its better that it reads it on need basis. But we can anyway put such info at one place, like in architecture.md, workflow.md, feature.md file. That way the agent has info about the subject + dependencies.

@kuznetsss kuznetsss Sep 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should have a good default for everyone with a way to opt out. Turns out claude code has a way to exclude any file form automatic loading: https://code.claude.com/docs/en/memory#exclude-specific-claude-md-files. Maybe worth adding the link to CONTRIBUTING.md.

Because there is a way to opt out, I'm ok to merge this PR as it is and improve the structure in the next iteration.

My suggestion would be to put all the rules into a doc file per subdirectory, something like docs/conventions/dirs/subdirectory.md. And reference such file in subdirectory's AGENTS.md.
Such structure would help to avoid duplications between include and src subdirectories, keep all the rules in one place and store rules as docs, so humans could also read them.


Paths below reflect the current layout; update this doc if modularization moves a subsystem to a different directory.

- `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 — see [src/libxrpl/tx/AGENTS.md](./src/libxrpl/tx/AGENTS.md) for amendment-gating conventions). `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/`.
- `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/` — unit tests for `libxrpl` written in `gtest`, gradually replacing the `src/test` equivalents.
- `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).
3 changes: 3 additions & 0 deletions include/xrpl/consensus/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# AGENTS.md — consensus

See [README.md](./README.md) for a short pointer, and [docs/consensus.md](../../../docs/consensus.md) for the full consensus design.
1 change: 1 addition & 0 deletions include/xrpl/consensus/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
3 changes: 3 additions & 0 deletions include/xrpl/nodestore/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# AGENTS.md — nodestore

See [README.md](./README.md) for backend and benchmark design.
1 change: 1 addition & 0 deletions include/xrpl/nodestore/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
3 changes: 3 additions & 0 deletions include/xrpl/shamap/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# AGENTS.md — shamap

See [README.md](./README.md) for the SHAMap design.
1 change: 1 addition & 0 deletions include/xrpl/shamap/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
7 changes: 7 additions & 0 deletions src/libxrpl/ledger/helpers/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# AGENTS.md — ledger/helpers

A helper that takes an `SLE`/`std::shared_ptr<SLE const>` should `XRPL_ASSERT` that it's non-null and of the expected ledger-entry type at entry, and keep a real runtime check/error-return alongside the assert (asserts compile out in release builds) — the established idiom in this directory is `std::expected<..., TER>`, returning `std::unexpected(tec*)` on failure. Don't invent a new error-handling idiom for this.

@g-ripple g-ripple Sep 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we limit this to helpers where non-nullness and the entry type are actual preconditions? isPseudoAccount, for example, explicitly accepts null pointers and non-account entries and returns false. Adding the assertions described here would break that contract in Debug builds, even if we kept the runtime checks.


Prefer a single amendment-enabled block and a single disabled block over scattering `rules.enabled(...)` checks through a function, even if the two blocks are similar. When a file or function checks more than one amendment, name local enablement booleans per-amendment (e.g. `fix340Enabled` for `fixCleanup3_4_0`), not a generic `fixEnabled`.

Only use `UNREACHABLE` for genuinely impossible paths, not to avoid writing a test for one that's reachable but rare. When a branch marked `UNREACHABLE` is excluded from coverage, wrap it in `LCOV_EXCL_START`/`LCOV_EXCL_STOP`.

@kuznetsss kuznetsss Sep 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a general rule for the whole project and it is duplicated in src/libxrpl/tx/transactors/AGENTS.md.

@mvadari mvadari Sep 11, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When we talked on Wednesday, you didn't want this to be in the top level of the project because it doesn't apply to Rust code. Can you confirm which you'd prefer?

@kuznetsss kuznetsss Sep 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it should be in a document cpp_guidelines.md and AGENTS.md could reference that document.

@pratikmankawde pratikmankawde Sep 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or it can be in a single code_conventions.md file with the file/path filtering you shared earlier?
https://code.claude.com/docs/en/memory#path-specific-rules
Either way is fine.

@mvadari mvadari Sep 11, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The UNREACHABLE/codecov stuff I'm fine with moving to a separate doc, but the amendment notes should stay here, since that doesn't apply to the whole repo.

@pratikmankawde pratikmankawde Sep 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could put them in amendments.md file. There will also be a features.md file with short desc. of features and links to XLS docs.

@mvadari mvadari Sep 11, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That won't work if the agent is working on something that it doesn't think is an amendment.

@kuznetsss kuznetsss Sep 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

subdir/AGENTS.md could refer to the related directory doc which would contain directory specific rules or links to the other common docs. I would prefer to keep AGENTS.md as simple as possible and not duplicating docs for humans (not a blocker for this PR).

@bthomee bthomee Sep 15, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You'll also want to mention SOMETIMES here. We tend to use it for situations that are rare.

For instance, values that should be positive - the code rejects non-positive values, but since the values are supplied by a peer it is technically possible for them to send us a negative value. Example:

bool isNegative = value.peek() < 0;
SOMETIMES(isNegative, "....")
if (isNegative)
{
    JLOG(journal.debug(), "....");
    return false;
}

@bthomee bthomee Sep 15, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since these AGENTS.md files discuss UNREACHABLE, XRPL_ASSERT, etc. multiple times, I'd highly recommend updating the external/antithesis-sdk/README.md with explanations of these defines, and then referencing that README.md in the agent files.

1 change: 1 addition & 0 deletions src/libxrpl/ledger/helpers/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
14 changes: 12 additions & 2 deletions src/libxrpl/tx/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# AGENTS.md — tx

See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance.
## When an amendment is required

@kuznetsss kuznetsss Sep 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe instead we should have a contributing guidelines doc? Such rules may be useful not only for agents but for new contributors

@mvadari mvadari Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No objections here, we can make it a readme that the agents.md points to like what other files in this PR do. That should be a separate PR though, because I'd like this in first. Fine with this info migrating later, but I'd rather not have perfect be the enemy of good here.


Any change to transaction-processing behavior must be gated behind an amendment. New amendments (and fixes, i.e. `fix*` amendments) are added to [`include/xrpl/protocol/detail/features.macro`](../../../include/xrpl/protocol/detail/features.macro), as an `XRPL_FEATURE(...)` or `XRPL_FIX(...)` entry added to the top of the list (the list is kept in reverse chronological order). Once the pre-amendment code path for a retired amendment is removed, move its entry to `XRPL_RETIRE_FEATURE(...)`/`XRPL_RETIRE_FIX(...)` instead of deleting it.
A change needs an amendment if it affects transaction processing, ledger objects, or anything else about the binary format or hash of the ledger. An amendment is optional if a change only affects what transactions get proposed for consensus (e.g. fee escalation). Otherwise, don't use one.

New amendments (and fixes, i.e. `fix*` amendments) are added to [`include/xrpl/protocol/detail/features.macro`](../../../include/xrpl/protocol/detail/features.macro), as an `XRPL_FEATURE(...)` or `XRPL_FIX(...)` entry added to the top of the list (the list is kept in reverse chronological order). Once the pre-amendment code path for a retired amendment is removed, move its entry to `XRPL_RETIRE_FEATURE(...)`/`XRPL_RETIRE_FIX(...)` instead of deleting it.

When adding a new amendment or transaction type, check its interaction with: invariants, fees, Deposit Auth, Batch transaction inclusion/exclusion, Permission Delegation inclusion/exclusion, Freeze/Deep Freeze (IOU) and Lock (MPT), Clawback, Credentials and Permissioned Domain, the case where the submitting account is the asset's issuer, and numeric over/underflow. Stick to existing paradigms rather than inventing new ones — consistency between features matters more than a locally "better" design.

New (or deleted) invariant checks must be amendment-gated: they introduce (or remove) a way for a transaction to fail, and an un-gated change risks validators disagreeing on a transaction's result, i.e. a network fork.

See [transactors/AGENTS.md](./transactors/AGENTS.md) for conventions on writing the amendment-gated code itself.

A change to transaction/signing behavior that's visible through the public API also needs an `API-CHANGELOG.md` entry — see [../../xrpld/rpc/AGENTS.md](../../xrpld/rpc/AGENTS.md) for the full rule.
13 changes: 13 additions & 0 deletions src/libxrpl/tx/transactors/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# AGENTS.md — transactors

Prefer a single object-level invariant over duplicating the same delta/balance check in every transactor that touches an object — e.g. one invariant asserting a Vault's pseudo-account balance and `assetsAvailable` always move together, rather than repeating that check in `VaultDeposit`, `VaultWithdraw`, `VaultClawback`, `LoanSet`, etc.

## Gating amendment-dependent code

Prefer a single amendment-enabled block and a single disabled block over scattering `rules.enabled(...)` checks through a function, even if the two blocks are similar.

When a file or function checks more than one amendment, name local enablement booleans per-amendment (e.g. `fix340Enabled` for `fixCleanup3_4_0`), not a generic `fixEnabled` — it becomes ambiguous once a second amendment is checked in the same scope.

## `UNREACHABLE` and test coverage

Only use `UNREACHABLE` for genuinely impossible paths, not to avoid writing a test for one that's reachable but rare. When a branch marked `UNREACHABLE` is excluded from coverage, wrap it in `LCOV_EXCL_START`/`LCOV_EXCL_STOP`.
1 change: 1 addition & 0 deletions src/libxrpl/tx/transactors/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
5 changes: 5 additions & 0 deletions src/test/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# AGENTS.md — test

See [README.md](./README.md) for basic `--unittest` invocation.

Shared test setup/helper code used by more than one test file belongs in `jtx/`, not copy-pasted across test files.

@g-ripple g-ripple Sep 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we scope this to shared transaction-building helpers rather than all shared test code? We already keep general utilities like SuiteJournal in src/test/unit_test/ and shared lending fixtures in src/test/app/lending/LoanTestBase.h. Avoiding copy-paste makes sense, but those helpers shouldn't have to move into jtx/ just because multiple tests use them.

1 change: 1 addition & 0 deletions src/test/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
3 changes: 3 additions & 0 deletions src/xrpld/app/consensus/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# AGENTS.md — consensus

See [README.md](./README.md) for a short pointer, and [docs/consensus.md](../../../../docs/consensus.md) for the full consensus design.
1 change: 1 addition & 0 deletions src/xrpld/app/consensus/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
3 changes: 3 additions & 0 deletions src/xrpld/app/ledger/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# AGENTS.md — ledger

See [README.md](./README.md) for ledger lifecycle and fetch-pack design.
1 change: 1 addition & 0 deletions src/xrpld/app/ledger/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
3 changes: 3 additions & 0 deletions src/xrpld/overlay/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# AGENTS.md — overlay

See [README.md](./README.md) for the peer-protocol handshake, clustering, gossip, and monitoring design.
1 change: 1 addition & 0 deletions src/xrpld/overlay/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
Comment thread
kuznetsss marked this conversation as resolved.
3 changes: 3 additions & 0 deletions src/xrpld/peerfinder/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# AGENTS.md — peerfinder

See [README.md](./README.md) for the peer-discovery design.
1 change: 1 addition & 0 deletions src/xrpld/peerfinder/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
4 changes: 2 additions & 2 deletions src/xrpld/rpc/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# AGENTS.md — rpc

See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance.
See [README.md](./README.md) for the RPC subsystem design.

Any change to a public RPC method's behavior (new/changed/removed fields, parameters, or error conditions) needs a corresponding entry in [`API-CHANGELOG.md`](../../../API-CHANGELOG.md), under the `## Unreleased` section (`### Additions`, `### Deprecations`, etc. as appropriate).
Any change to publicly-visible API behavior — RPC/WebSocket fields, parameters, or error conditions, or transaction/signing behavior surfaced through the API even from outside this directory — needs an entry in [`API-CHANGELOG.md`](../../../API-CHANGELOG.md) under `## Unreleased` (`### Additions`, `### Deprecations`, etc. as appropriate).
Loading