- The harness auto-loads every ancestor AGENTS.md (including root), so
a nested file telling an agent to "see the repo-level AGENTS.md" is
pure overhead — it can trigger a re-load/duplication-check/discard
cycle, and some models just retain the duplicate content in context.
Drop that pointer from every nested AGENTS.md; keep pointers to
things that are NOT auto-loaded (README.md, docs/consensus.md,
non-ancestor AGENTS.md like tx/ -> rpc/).
- Root AGENTS.md's Build section is now a short index pointer to
BUILD.md and docs/build/nix.md instead of restating Nix setup steps,
per review feedback that AGENTS.md should mostly index other docs
rather than duplicate them.
Addresses PR review comments:
https://github.com/XRPLF/rippled/pull/8198#discussion_r3979325914https://github.com/XRPLF/rippled/pull/8198#discussion_r3979424992
- ledger/helpers/AGENTS.md: std::expected<..., TER>/std::unexpected(tec*)
is already the established idiom here (confirmed in AMMHelpers.cpp,
CredentialHelpers.cpp), not something to avoid; reword so the rule
doesn't read as discouraging it.
- transactors/AGENTS.md: the UNREACHABLE/LCOV_EXCL coverage rule isn't
amendment-specific, so give it its own heading instead of nesting it
under "Gating amendment-dependent code".
- Root AGENTS.md: comments should explain why, not what/how, since the
code already shows that.
- Drop the pseudo-account exemption rule from transactors/AGENTS.md —
needs refining before it's codified.
Addresses PR review comments:
https://github.com/XRPLF/rippled/pull/8198#discussion_r3962352164https://github.com/XRPLF/rippled/pull/8198#discussion_r3967566278
- Build section now recommends the Nix devshell rather than requiring
it; contributors can use their own toolchain/build flow.
- Move the directory-by-directory architecture map out of AGENTS.md
into a new top-level ARCHITECTURE.md, with a pointer left behind.
- Add a short note asking contributors to keep AGENTS.md/README/
ARCHITECTURE.md files current when they change what those docs cover.
- ledger/helpers/AGENTS.md also needs the amendment-gating shape,
per-amendment flag naming, and UNREACHABLE/LCOV_EXCL pairing notes
(previously only in transactors/AGENTS.md) — the vault/lending
helper files these were evidenced on live in ledger/helpers/, not
tx/transactors/.
Team decided AGENTS.md content should live in the narrowest folder it
applies to, rather than the broadest, to keep context small for agents
working elsewhere in the repo. Restructure round 1/2's additions
accordingly, with no change in the rules themselves:
- Move the repo-wide API-CHANGELOG.md rule out of root AGENTS.md and
into rpc/AGENTS.md (its natural home), with a one-line pointer left
in tx/AGENTS.md for the signing-behavior case.
- Move the amendment-gating *code style* rules (single enabled/disabled
block, per-amendment flag naming, UNREACHABLE/LCOV_EXCL pairing) from
tx/AGENTS.md down into transactors/AGENTS.md, since all cited PR
evidence was in transactor code, not tx/-level files.
- Move the "shared test setup belongs in jtx/" rule out of root
AGENTS.md into a new src/test/AGENTS.md (+ CLAUDE.md symlink).
- Trim the now-duplicated amendment sentence out of root's Architecture
bullet in favor of a pointer to tx/AGENTS.md.
Round 2 of PR-review mining: found two subsystem-specific, unrecorded
conventions (pseudo-account auth/freeze exemption in vault/lending
transactors; SLE-type assertion in ledger helpers) that warrant their
own nested AGENTS.md rather than more root-level bullets.
Also added thin AGENTS.md pointer files (with CLAUDE.md symlinks,
matching the existing convention) for subsystems that already have a
substantial README.md but no AGENTS.md — agent tooling auto-loads
AGENTS.md when working in a directory but not README.md, so those
conventions were otherwise invisible to an agent that didn't think to
look.
Mined 6 months of merged PR review comments (human reviewers only) for
conventions that recur across multiple PRs/reviewers but aren't already
documented in CONTRIBUTING.md/CodingStyle.md, and folded them in:
- Doxygen comments expected on new public functions/methods.
- API-CHANGELOG.md requirement is repo-wide, not RPC-directory-scoped.
- Shared test setup belongs in jtx/, not copy-pasted across test files.
- Amendment requirement test and a design-considerations checklist,
sourced from the internal "Considerations for Future Amendments" doc.
- Amendment gating shape (single enabled/disabled block), per-amendment
flag naming, and UNREACHABLE/LCOV_EXCL pairing, all recurring asks in
tx/vault/invariant PR reviews.
