docs: add AGENTS.md for AI coding agent guidance#3914
Conversation
- Critical Rules: MUST/NEVER markers for common pitfalls (OOM, storage backends, L1 reorgs) - Architecture: HotShot vs Sequencer separation, internal components, L1 integration - Catchup: sparse merkle trees, on-demand proof fetching from local DB or peers - Testing philosophy: correctness over coverage for blockchain infrastructure - Storage layer: three backends (PostgreSQL, SQLite, filesystem), migration workflow - Code style: Rust imports, error handling, Solidity upgrade patterns - Commands: package-specific cargo commands, contract testing, E2E demos Includes CLAUDE.md symlink for Claude Code compatibility.
Summary of ChangesHello @sveitser, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a new Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces AGENTS.md, a comprehensive guide for AI coding agents, which is a valuable addition for navigating this complex repository. The document is well-structured and covers critical aspects from architecture to development workflows. My review identifies a key issue where CLAUDE.md is not implemented as a symlink as intended, and a minor inaccuracy in the AGENTS.md file that could be improved for clarity.
| @@ -0,0 +1 @@ | |||
| AGENTS.md No newline at end of file | |||
There was a problem hiding this comment.
The pull request description mentions that CLAUDE.md should be a symlink to AGENTS.md. However, this file has been added as a regular text file containing the string "AGENTS.md", not as a symbolic link. This will not work as intended. Please replace this file with a proper symlink.
There was a problem hiding this comment.
/gemini isn't that what a symlink looks like in git?
There was a problem hiding this comment.
That's a great question, sveitser! While the content of a symlink file in Git is indeed the path to its target (in this case, AGENTS.md), Git also tracks a special file mode to distinguish a symlink from a regular file. If you simply create a text file named CLAUDE.md with the content AGENTS.md, Git will treat it as a regular file, not a symbolic link.
To create a proper symbolic link that Git recognizes, you need to use the ln -s command and then add it to Git. Here's how you can fix it:
- Remove the existing file:
git rm CLAUDE.md
- Create the symbolic link:
ln -s AGENTS.md CLAUDE.md
- Add the symbolic link to Git:
git add CLAUDE.md
After these steps, git status should show CLAUDE.md as a new file with a special mode (e.g., new file: CLAUDE.md -> AGENTS.md), indicating it's a symlink.
|
|
||
| - Modify V1 contract storage layout (V2 inherits V1; changing V1 breaks upgrades) | ||
| - Combine `embedded-db` feature with default features (sqlx feature conflict) | ||
| - Use `just test` during iteration (compiles everything; use `cargo test -p <package>`) |
There was a problem hiding this comment.
The explanation for why just test should not be used during iteration is slightly inaccurate. It states that it "compiles everything", but the justfile shows that just test actually excludes some packages (sequencer-sqlite, hotshot-testing, slow-tests, espresso-dev-node). While the advice to use package-specific tests for faster iteration is excellent, the reason could be clarified to be more precise, for example, by stating it builds and tests most of the workspace.
sveitser
requested review from
bfish713,
imabdulbasit,
jbearer,
lukaszrzasik,
rob-maron and
ss-es
as code owners
2 participants
The CLAUDE.md file is loaded into context by claude code (among other things). So having some overall description of the projects should help it find stuff and guide it into the right direction. A more recent product agnostic name for such a file is AGENTS.md so I added that instead and symlinked CLAUDE.md.
Includes CLAUDE.md symlink for Claude Code compatibility.