feat(runtime): add claude.md with runtime overview by jancionear · Pull Request #15098 · near/nearcore

jancionear · 2026-02-13T22:54:51Z

Add a CLAUDE.md with a summary of how things work in the runtime.

Hopefully this can serve as a sort of "long-term memory", so that claude doesn't have to relearn everything each time it goes to the runtime.

AFAIU claude should read it whenever it goes into the runtime directory.

It's 100% human-generated

Claude is actually a good motivation to write docs :)

Copilot

Pull request overview

This PR adds comprehensive documentation for the NEAR runtime in a CLAUDE.md file. The documentation provides an overview of how the runtime works, covering key concepts like receipts, actions, accounts, and the receipt processing flow. It's designed to serve as "long-term memory" for AI assistants working with the runtime codebase.

Changes:

Added CLAUDE.md documentation file explaining runtime architecture and key concepts
Included Rust struct definitions for core types (ReceiptV0, ActionReceiptV2, Action, AccountV2)
Documented receipt types, execution flow, and important features like yield/resume and congestion control

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

runtime/runtime/AGENTS.md

runtime/runtime/CLAUDE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-13T23:02:08Z

runtime/runtime/CLAUDE.md

+pub struct ActionReceiptV2 {
+    /// A signer of the original transaction
+    pub signer_id: AccountId,
+    /// The receiver of any balance refunds from this receipt if it is different from receiver_id.


In the Rust snippet, the comment says "refunds form this receipt" which looks like a typo; it should be "refunds from this receipt" for clarity.

Suggested change

/// The receiver of any balance refunds from this receipt if it is different from receiver_id.

/// The receiver of any balance refunds from this receipt if it is different from receiver_id.

/// A signer of the original transaction

/// The receiver of any balance refunds from this receipt if it is different from receiver_id.

Copilot · 2026-02-13T23:02:08Z

runtime/runtime/CLAUDE.md

+    /// that means we have all the `ReceivedData` input which will be then converted to a
+    /// `PromiseResult::Successful(value)` or `PromiseResult::Failed`


In the Rust snippet, "will be than converted" should be "will be then converted" ("than" is comparative and reads incorrectly here).

runtime/runtime/AGENTS.md

codecov · 2026-02-13T23:18:28Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 69.00%. Comparing base (f50a2b9) to head (43ed91a).
⚠️ Report is 17 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##           master   #15098       +/-   ##
===========================================
+ Coverage    1.29%   69.00%   +67.70%     
===========================================
  Files         726      921      +195     
  Lines      141763   204023    +62260     
  Branches   141763   204023    +62260     
===========================================
+ Hits         1839   140783   +138944     
+ Misses     139871    57385    -82486     
- Partials       53     5855     +5802

Flag	Coverage Δ
pytests-nightly	`1.29% <ø> (+<0.01%)`	⬆️
unittests	`68.59% <ø> (?)`
unittests-nightly	`68.57% <ø> (?)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

darioush · 2026-02-13T23:20:53Z

I think we should make it AGENTS.md and symlink CLAUDE.md for compatibility with other agents, as AGENTS.md is standard https://agents.md/

darioush · 2026-02-13T23:30:49Z

runtime/runtime/CLAUDE.md

+```rust
+pub struct ReceiptV0 {
+    /// An issuer account_id of a particular receipt.
+    /// `predecessor_id` could be either `Transaction` `signer_id` or intermediate contract's `account_id`.


Maybe we can omit the code and add reference to keep the context shorter.

I agree in principle, Claude says:

Copy-pasting structs is mostly a waste of tokens. What actually helps: - Reference by name and location: JsonRpcHandler in chain/jsonrpc/src/lib.rs:322 - anyone can jump there - Describe the why, not the what: "holds async senders to the four backend actors" is more useful than listing every field - Call out non-obvious fields: If one field has a surprising role or subtle semantics, mention that specific field with a one-liner explanation

Removed code, left only names of the structs. I thought about location, but this will be hard to maintain. Claude should be able to grep for the structs by their name.

ssavenko-near

Would be good to add something like "life of a contract". I can do it later, after this is merged. Please address the comment from Darioush and Andrea regarding the code sections. Otherwise LGTM.

ssavenko-near · 2026-02-16T13:03:51Z

runtime/runtime/AGENTS.md

+- If the applied chunk is missing (old_chunk), skip the rest
+- Read buffered outgoing receipts and send out as many as possible within the outgoing limits
+- Process transactions in the chunk and convert them to the receipts
+- Process receipts, executing them and producing new outgoing receipts


Shall we mention that these are (usually) not the receipts from the previous step?

I don't know, for local receipts they are often processed in the same chunk as the transaction that created them. Feels like a detail that LLM doesn't need to know about.

ssavenko-near · 2026-02-16T13:06:10Z

runtime/runtime/CLAUDE.md

+- Read buffered outgoing receipts and send out as many as possible within the outgoing limits
+- Process transactions in the chunk and convert them to the receipts
+- Process receipts, executing them and producing new outgoing receipts
+- Finalize the post-state


That is not very informative in itself. Perhaps worth extending a bit.

True, not very useful, removed it to save tokens

ssavenko-near · 2026-02-16T13:14:09Z

runtime/runtime/AGENTS.md

+
+Executing actions costs gas. Each receipt has some amount of gas attached to it. If the gas runs out, receipt execution fails. Unused gas is sent back to the transaction author as a gas refund.
+
+ReceiptSink takes new outgoing receipts and tries to send them out to other shards. If the receipt can't be sent because of outgoing limits, the receipt is stored in a buffer in the shard's trie and will be sent later.


This creates an impression that this is the only responsibility of ReceiptSink. At least when I read it. Maybe rephrase to emphasize that this describes the life of outgoing receipts, rather than specifies the ReceiptSink behavior.

Most of the outgoing receipt management code is in ReceiptSink, so imo we can say that this is its main responsibility.

jancionear · 2026-02-16T14:17:17Z

Renamed to AGENTS.md
Removed code, replaced with struct names
Removed some irrelevant info to save tokens

I'm gonna merge it, should be good enough to start with, we can improve it in the future.

The file is 982 words long. From what I read, Claude Opus 4.6 has ~150k words of context. Claude says that it's ok, and could even be bigger. If we wanted to make it smaller we could make it readable on demand? Or split into smaller files. I'll leave that for later.

feat(runtime): add claude.md with runtime overview

6f7bd83

jancionear requested review from Trisfald, Copilot, darioush and ssavenko-near February 13, 2026 22:54

jancionear requested a review from a team as a code owner February 13, 2026 22:54

Copilot started reviewing on behalf of jancionear February 13, 2026 22:55 View session

typo

34bfcaa

Copilot AI reviewed Feb 13, 2026

View reviewed changes

Update runtime/runtime/CLAUDE.md

c16d389

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 13, 2026 22:59

Copilot started reviewing on behalf of jancionear February 13, 2026 23:00 View session

jancionear and others added 5 commits February 13, 2026 23:00

Update runtime/runtime/CLAUDE.md

36d83fb

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update runtime/runtime/CLAUDE.md

c398bdd

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update runtime/runtime/CLAUDE.md

d934dfc

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update runtime/runtime/CLAUDE.md

ff9a403

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update runtime/runtime/CLAUDE.md

d768cdd

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Feb 13, 2026

View reviewed changes

darioush approved these changes Feb 13, 2026

View reviewed changes

ssavenko-near approved these changes Feb 16, 2026

View reviewed changes

jancionear added 3 commits February 16, 2026 14:07

Remove code

42ae237

Rename AGENTS.md

031568f

Remove the note about finalization, it's not very useful

43ed91a

jancionear enabled auto-merge February 16, 2026 14:17

jancionear added this pull request to the merge queue Feb 16, 2026

Merged via the queue into near:master with commit 5be0716 Feb 16, 2026
32 checks passed

jancionear deleted the runtime-claude branch February 16, 2026 14:39

		/// that means we have all the `ReceivedData` input which will be then converted to a
		/// `PromiseResult::Successful(value)` or `PromiseResult::Failed`


		Executing actions costs gas. Each receipt has some amount of gas attached to it. If the gas runs out, receipt execution fails. Unused gas is sent back to the transaction author as a gas refund.

		ReceiptSink takes new outgoing receipts and tries to send them out to other shards. If the receipt can't be sent because of outgoing limits, the receipt is stored in a buffer in the shard's trie and will be sent later.

Conversation

jancionear commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codecov bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

darioush commented Feb 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Trisfald Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ssavenko-near left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jancionear commented Feb 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jancionear commented Feb 13, 2026 •

edited

Loading

codecov bot commented Feb 13, 2026 •

edited

Loading

Trisfald Feb 14, 2026 •

edited

Loading