chore: add guidance file for agents #6416
Conversation
LesnyRumcajs
requested review from
akaladarshi and
hanabi1224
and removed request for
a team
WalkthroughAdded two documentation files, Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~4 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @AGENTS.md:
- Around line 1-2: Header/title mismatch: the document named AGENTS.md currently
has the top-level header "# CLAUDE.md", which is confusing; either rename the
file to CLAUDE.md or update the header to match the filename by changing the
first line to "# AGENTS.md" (or to the intended agent name) so the file title
and filename are consistent; ensure any references in the PR description or docs
are updated accordingly.
🧹 Nitpick comments (1)
AGENTS.md (1)
168-171: Consider adding language specifiers to code blocks.The fenced code blocks at lines 168-171, 181-186, and 214-222 are missing language specifiers. While these are text-based diagrams rather than executable code, adding a language specifier improves rendering and clarity.
Proposed fix
-``` +```text Request → AuthLayer → FilterLayer → SegregationLayer → SetExtensionLayer → LogLayer → MetricsLayer → RpcHandlerApply the same `text` language specifier to the code blocks at lines 181-186 and 214-222. </details> Based on static analysis hints. Also applies to: 181-186, 214-222 </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Repository UI **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 111c24b965a0029c740818afee021ab2cd5f9507 and 949273cb343e5d39997709a2f8e911f5f119dc7b. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `AGENTS.md` * `CLAUDE.md` </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧠 Learnings (7)</summary> <details> <summary>📓 Common learnings</summary>Learnt from: LesnyRumcajs
Repo: ChainSafe/forest PR: 5907
File: src/rpc/methods/state.rs:523-570
Timestamp: 2025-08-06T15:44:33.467Z
Learning: LesnyRumcajs prefers to rely on BufWriter's Drop implementation for automatic flushing rather than explicit flush() calls in Forest codebase.</details> <details> <summary>📚 Learning: 2025-08-07T13:39:15.107Z</summary>Learnt from: hanabi1224
Repo: ChainSafe/forest PR: 5886
File: interop-tests/src/tests/go_app/gen.go:29-29
Timestamp: 2025-08-07T13:39:15.107Z
Learning: Auto-generated files like those created by rust2go (indicated by "Generated by rust2go. Please DO NOT edit this C part manually." comment) in the Forest project should be skipped during code review as they are not intended for manual editing.**Applied to files:** - `AGENTS.md` </details> <details> <summary>📚 Learning: 2025-10-17T09:36:15.757Z</summary>Learnt from: elmattic
Repo: ChainSafe/forest PR: 6128
File: src/ipld/util.rs:23-30
Timestamp: 2025-10-17T09:36:15.757Z
Learning: Always runcargo checkorcargo buildto verify actual compilation errors in the Forest codebase before flagging them as issues. Do not rely solely on documentation or assumptions about trait implementations.**Applied to files:** - `AGENTS.md` </details> <details> <summary>📚 Learning: 2025-08-07T13:39:29.732Z</summary>Learnt from: hanabi1224
Repo: ChainSafe/forest PR: 5886
File: interop-tests/src/tests/go_app/gen.go:58-58
Timestamp: 2025-08-07T13:39:29.732Z
Learning: In the Forest project, auto-generated files (like those generated by rust2go tool) should be skipped during code review as they are not meant to be manually edited.**Applied to files:** - `AGENTS.md` </details> <details> <summary>📚 Learning: 2025-08-08T12:10:45.218Z</summary>Learnt from: hanabi1224
Repo: ChainSafe/forest PR: 5867
File: src/ipld/util.rs:553-558
Timestamp: 2025-08-08T12:10:45.218Z
Learning: Forest project targets Rust stable >=1.89; features stabilized in 1.88 like let-chains are acceptable in this codebase.**Applied to files:** - `AGENTS.md` </details> <details> <summary>📚 Learning: 2025-08-28T12:52:46.927Z</summary>Learnt from: LesnyRumcajs
Repo: ChainSafe/forest PR: 6011
File: src/cli/main.rs:18-25
Timestamp: 2025-08-28T12:52:46.927Z
Learning: In Forest CLI (src/cli/main.rs), the early RPC network check before Cli::parse_from() does not block help/version commands because clap processes these internally before reaching the RPC call. LesnyRumcajs confirmed this implementation works correctly and that RPC call failures are acceptable in this context.**Applied to files:** - `AGENTS.md` </details> <details> <summary>📚 Learning: 2025-09-17T11:32:44.185Z</summary>Learnt from: hanabi1224
Repo: ChainSafe/forest PR: 6074
File: src/rpc/methods/chain.rs:55-56
Timestamp: 2025-09-17T11:32:44.185Z
Learning: In the Forest codebase, hanabi1224 prefers that CodeRabbit should not warn about potential compilation issues (such as Send bounds, async/await compatibility, etc.) since they are already guarded by CI tests. Focus should be on higher-level design and logic issues instead.**Applied to files:** - `AGENTS.md` </details> </details><details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>AGENTS.md</summary> 168-168: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 181-181: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 214-214: Fenced code blocks should have a language specified (MD040, fenced-code-language) </details> </details> </details> <details> <summary>⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (9)</summary> * GitHub Check: Check * GitHub Check: Build MacOS * GitHub Check: Build Ubuntu * GitHub Check: cargo-publish-dry-run * GitHub Check: rubocop * GitHub Check: Build forest binaries on Linux AMD64 * GitHub Check: tests-release * GitHub Check: Coverage * GitHub Check: All lint checks </details> <details> <summary>🔇 Additional comments (2)</summary><blockquote> <details> <summary>CLAUDE.md (1)</summary><blockquote> `1-1`: **Clarify the intended file structure.** The file `CLAUDE.md` contains only the text "AGENTS.md", while the actual comprehensive guidance content is in `AGENTS.md` (which internally titles itself as "# CLAUDE.md"). This creates confusion about the intended structure. Please clarify: - Is `CLAUDE.md` meant to be a simple redirect to `AGENTS.md`? - Should the content from `AGENTS.md` be moved to `CLAUDE.md` instead? - Or is this the intended structure where `CLAUDE.md` points to `AGENTS.md`? Based on the PR description mentioning "add guidance file (CLAUDE.md)", it seems the comprehensive documentation should be in `CLAUDE.md` rather than split across two files. </blockquote></details> <details> <summary>AGENTS.md (1)</summary><blockquote> `1-399`: **Well-structured documentation for AI assistants.** This is a comprehensive and well-organized guidance document that covers: - Project overview and architecture - Development commands and workflows - Code patterns and conventions - Configuration options The document provides valuable context for AI coding assistants working with the Forest codebase. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
LesnyRumcajs
force-pushed
the
add-claude-md
branch
from
949273c to
faf62aa
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @AGENTS.md:
- Line 1: The document header in AGENTS.md currently reads "# CLAUDE.md",
causing a mismatch between the filename and the top-level header; update the
header to match the file (e.g., change "# CLAUDE.md" to "# AGENTS.md" or a
clearer title like "# AI Agent Guidance"), or alternatively rename the file to
CLAUDE.md so the filename and header are consistent; ensure the chosen title
accurately reflects the document contents and remove any residual references to
the old name.
🧹 Nitpick comments (1)
AGENTS.md (1)
168-171: Add language identifier to fenced code blocks.The markdown linter correctly identifies missing language specifiers for fenced code blocks. For ASCII art diagrams like this middleware stack, use
```textor```plaintextinstead of just```.This also applies to lines 181-186 and 214-222.
📝 Suggested fix
-``` +```text Request → AuthLayer → FilterLayer → SegregationLayer → SetExtensionLayer → LogLayer → MetricsLayer → RpcHandlerApply similar changes to the other two code blocks at lines 181 and 214. </details> </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Repository UI **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 949273cb343e5d39997709a2f8e911f5f119dc7b and faf62aa62b067314323013670f43872c7b3f52be. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `AGENTS.md` * `CLAUDE.md` </details> <details> <summary>🚧 Files skipped from review as they are similar to previous changes (1)</summary> * CLAUDE.md </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧠 Learnings (6)</summary> <details> <summary>📓 Common learnings</summary>Learnt from: LesnyRumcajs
Repo: ChainSafe/forest PR: 5907
File: src/rpc/methods/state.rs:523-570
Timestamp: 2025-08-06T15:44:33.467Z
Learning: LesnyRumcajs prefers to rely on BufWriter's Drop implementation for automatic flushing rather than explicit flush() calls in Forest codebase.</details> <details> <summary>📚 Learning: 2025-08-07T13:39:15.107Z</summary>Learnt from: hanabi1224
Repo: ChainSafe/forest PR: 5886
File: interop-tests/src/tests/go_app/gen.go:29-29
Timestamp: 2025-08-07T13:39:15.107Z
Learning: Auto-generated files like those created by rust2go (indicated by "Generated by rust2go. Please DO NOT edit this C part manually." comment) in the Forest project should be skipped during code review as they are not intended for manual editing.**Applied to files:** - `AGENTS.md` </details> <details> <summary>📚 Learning: 2025-10-17T09:36:15.757Z</summary>Learnt from: elmattic
Repo: ChainSafe/forest PR: 6128
File: src/ipld/util.rs:23-30
Timestamp: 2025-10-17T09:36:15.757Z
Learning: Always runcargo checkorcargo buildto verify actual compilation errors in the Forest codebase before flagging them as issues. Do not rely solely on documentation or assumptions about trait implementations.**Applied to files:** - `AGENTS.md` </details> <details> <summary>📚 Learning: 2025-08-07T13:39:29.732Z</summary>Learnt from: hanabi1224
Repo: ChainSafe/forest PR: 5886
File: interop-tests/src/tests/go_app/gen.go:58-58
Timestamp: 2025-08-07T13:39:29.732Z
Learning: In the Forest project, auto-generated files (like those generated by rust2go tool) should be skipped during code review as they are not meant to be manually edited.**Applied to files:** - `AGENTS.md` </details> <details> <summary>📚 Learning: 2025-08-08T12:10:45.218Z</summary>Learnt from: hanabi1224
Repo: ChainSafe/forest PR: 5867
File: src/ipld/util.rs:553-558
Timestamp: 2025-08-08T12:10:45.218Z
Learning: Forest project targets Rust stable >=1.89; features stabilized in 1.88 like let-chains are acceptable in this codebase.**Applied to files:** - `AGENTS.md` </details> <details> <summary>📚 Learning: 2025-08-28T12:52:46.927Z</summary>Learnt from: LesnyRumcajs
Repo: ChainSafe/forest PR: 6011
File: src/cli/main.rs:18-25
Timestamp: 2025-08-28T12:52:46.927Z
Learning: In Forest CLI (src/cli/main.rs), the early RPC network check before Cli::parse_from() does not block help/version commands because clap processes these internally before reaching the RPC call. LesnyRumcajs confirmed this implementation works correctly and that RPC call failures are acceptable in this context.**Applied to files:** - `AGENTS.md` </details> </details><details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>AGENTS.md</summary> 168-168: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 181-181: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 214-214: Fenced code blocks should have a language specified (MD040, fenced-code-language) </details> </details> </details> <details> <summary>⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)</summary> * GitHub Check: Build forest binaries on Linux AMD64 * GitHub Check: tests-release * GitHub Check: rubocop * GitHub Check: Check * GitHub Check: All lint checks * GitHub Check: Coverage </details> <details> <summary>🔇 Additional comments (3)</summary><blockquote> <details> <summary>AGENTS.md (3)</summary><blockquote> `9-105`: **Comprehensive development commands documentation.** The development commands section is well-organized and covers all major workflows (building, testing, linting, coverage, cleaning). The inline comments explaining what each command does are helpful for AI assistants. --- `107-236`: **Excellent architecture documentation.** The high-level architecture section provides comprehensive coverage of core modules, architectural patterns, and key flows. The inclusion of code examples (Blockstore pattern), flow diagrams (daemon startup, VM execution), and specific type references will be valuable for AI assistants understanding the codebase structure. --- `238-398`: **Comprehensive practical guidance for development.** The sections on project-specific patterns, workflows, environment variables, cargo features, build profiles, and contributing guidelines provide excellent practical guidance. The code style rules (no indexing, no unwrap, etc.) and workflow examples will help AI assistants generate code that aligns with project conventions. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
LesnyRumcajs
force-pushed
the
add-claude-md
branch
from
faf62aa to
f519a96
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @AGENTS.md:
- Around line 181-186: Add a language specifier to the fenced code block
containing the VM execution flow diagram to satisfy markdown linting; update the
block that lists StateManager::call_with_gas(), VM::new(ExecutionContext),
vm.apply_message() / apply_implicit_message(), and VM::flush() → new_state_root
to use a language tag (e.g., "text") after the opening backticks so the diagram
becomes ```text ... ``` in the AGENTS.md file.
- Around line 214-222: The fenced code block containing the database
organization diagram lacks a language specifier and triggers markdown lint
warnings; update the opening fence from ``` to ```text so the block becomes a
```text fenced code block (i.e., modify the diagram block around "Application
(StateManager, ChainStore) ... ParityDb (embedded KV store)" to use the text
language tag).
- Around line 168-171: Add a language specifier to the fenced code block
containing the RPC middleware flow diagram so Markdown linting stops flagging
it; update the triple-backtick fence that wraps the line "Request → AuthLayer →
FilterLayer → SegregationLayer → SetExtensionLayer → LogLayer → MetricsLayer →
RpcHandler" to use a specifier such as "text" (e.g., ```text) so the block is
properly annotated.
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
AGENTS.mdCLAUDE.md
🚧 Files skipped from review as they are similar to previous changes (1)
- CLAUDE.md
🧰 Additional context used
🧠 Learnings (6)
📓 Common learnings
Learnt from: LesnyRumcajs
Repo: ChainSafe/forest PR: 5907
File: src/rpc/methods/state.rs:523-570
Timestamp: 2025-08-06T15:44:33.467Z
Learning: LesnyRumcajs prefers to rely on BufWriter's Drop implementation for automatic flushing rather than explicit flush() calls in Forest codebase.
📚 Learning: 2025-10-17T09:36:15.757Z
Learnt from: elmattic
Repo: ChainSafe/forest PR: 6128
File: src/ipld/util.rs:23-30
Timestamp: 2025-10-17T09:36:15.757Z
Learning: Always run `cargo check` or `cargo build` to verify actual compilation errors in the Forest codebase before flagging them as issues. Do not rely solely on documentation or assumptions about trait implementations.
Applied to files:
AGENTS.md
📚 Learning: 2025-08-07T13:39:15.107Z
Learnt from: hanabi1224
Repo: ChainSafe/forest PR: 5886
File: interop-tests/src/tests/go_app/gen.go:29-29
Timestamp: 2025-08-07T13:39:15.107Z
Learning: Auto-generated files like those created by rust2go (indicated by "Generated by rust2go. Please DO NOT edit this C part manually." comment) in the Forest project should be skipped during code review as they are not intended for manual editing.
Applied to files:
AGENTS.md
📚 Learning: 2025-08-07T13:39:29.732Z
Learnt from: hanabi1224
Repo: ChainSafe/forest PR: 5886
File: interop-tests/src/tests/go_app/gen.go:58-58
Timestamp: 2025-08-07T13:39:29.732Z
Learning: In the Forest project, auto-generated files (like those generated by rust2go tool) should be skipped during code review as they are not meant to be manually edited.
Applied to files:
AGENTS.md
📚 Learning: 2025-08-08T12:10:45.218Z
Learnt from: hanabi1224
Repo: ChainSafe/forest PR: 5867
File: src/ipld/util.rs:553-558
Timestamp: 2025-08-08T12:10:45.218Z
Learning: Forest project targets Rust stable >=1.89; features stabilized in 1.88 like let-chains are acceptable in this codebase.
Applied to files:
AGENTS.md
📚 Learning: 2025-08-28T12:52:46.927Z
Learnt from: LesnyRumcajs
Repo: ChainSafe/forest PR: 6011
File: src/cli/main.rs:18-25
Timestamp: 2025-08-28T12:52:46.927Z
Learning: In Forest CLI (src/cli/main.rs), the early RPC network check before Cli::parse_from() does not block help/version commands because clap processes these internally before reaching the RPC call. LesnyRumcajs confirmed this implementation works correctly and that RPC call failures are acceptable in this context.
Applied to files:
AGENTS.md
🪛 markdownlint-cli2 (0.18.1)
AGENTS.md
168-168: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
181-181: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
214-214: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)
- GitHub Check: Build MacOS
- GitHub Check: Build Ubuntu
- GitHub Check: cargo-publish-dry-run
- GitHub Check: Coverage
- GitHub Check: tests-release
- GitHub Check: Build forest binaries on Linux AMD64
- GitHub Check: rubocop
🔇 Additional comments (4)
AGENTS.md (4)
1-106: LGTM! Comprehensive command reference.The development commands section provides excellent guidance covering build profiles, testing variants, and linting tools. The examples are clear and well-organized for AI assistants.
107-236: Excellent architecture documentation.The high-level architecture section provides valuable context about core modules, patterns, and subsystems. The detailed breakdown of daemon startup flow, chain synchronization, RPC architecture, FVM integration, and P2P networking will be very helpful for AI coding assistants understanding the codebase structure.
238-331: Well-documented patterns and workflows.The project-specific patterns section clearly articulates error handling conventions, async patterns, code style requirements, and testing utilities. The common development workflows provide practical examples for running nodes, using the CLI, and working with snapshots.
333-399: Comprehensive configuration and contribution guidance.The debugging, environment variables, Cargo features, build profiles, and contributing guidelines sections provide valuable reference material for AI assistants. The information is well-organized and covers essential configuration options.
Summary of changes
Changes introduced in this pull request:
Reference issue to close (if applicable)
Closes
Other information and links
Change checklist
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.