docs: add CLAUDE.md and Agents.md for AI coding assistant guidance by akrem-chabchoub · Pull Request #5437 · ethersphere/bee

akrem-chabchoub · 2026-04-15T11:00:09Z

Checklist

I have read the coding guide.
My change requires a documentation update, and I have done it.
I have added tests to cover my changes.
I have filled out the description and linked the related issues.

Description

Add Agents.md and CLAUDE.md to help ai agents understood better the code

Open API Spec Version Changes (if applicable)

Motivation and Context (Optional)

Related Issue (Optional)

#5407

Screenshots (if appropriate):

AI Disclosure

This PR contains code that has been generated by an LLM.
I have reviewed the AI generated code thoroughly.
I possess the technical expertise to responsibly review the code generated in this PR.

Made-with: Cursor

martinconic · 2026-04-16T10:40:04Z

+- `bee start` — full or light node (`cmd/bee/cmd/start.go`)
+- `bee init` — initialize data directory
+- `bee deploy` — deploy smart contracts
+- `bee db` — database management


Should we go even deeper with db repair and db nuke?

Yes, it can be added, but the frequency of use is unclear. If it is not needed too often, it remains practical. When required, the agent can execute bee db to retrieve the information.

AFAIK, these files are meant to serve as a map for agents rather than a fully detailed manual.

gacevicljubisa

Claude Code should read AGENTS.md as fallback. So, no need to have both.

I would focsu on the code Guidelines like:

adding refs to CODING.md, CODINGSTYLE.md, CONTRIBUTING.md
minimal, focused changes
do not add, remove, or update dependencies
error handling
testing
loging

Regarding make targets, I would include only necesary during dev proces.
There is no need to start actual bee node using agents.

Additionally commit msg format can be included.

Maybe this can serve as example https://github.com/ethereum/go-ethereum/blob/master/AGENTS.md wit

akrem-chabchoub · 2026-04-16T12:25:42Z

@gacevicljubisa

adding refs to CODING.md, CODINGSTYLE.md, CONTRIBUTING.md

It is already there

minimal, focused changes

I will add it

do not add, remove, or update dependencies

Maybe we can say unless I explicitly mention ?

Regarding make targets, I would include only necesary during dev proces. There is no need to start actual bee node using agents.

Additionally commit msg format can be included.

I will remove unnecessary ones and add commits msg format.

Thanks !

…hecklist

gacevicljubisa

Also, maybe it would be good to add CLAUDE.md with short disclosure that instructions are in AGENT.md?

… guidelines

…S.md

acud · 2026-05-01T23:10:11Z

+
+## Commit message format and PR titles
+
+This repo uses **[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)** with **`commitlint.config.js`**: allowed types are `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `test`. Header **max 100** characters; footer lines **max 72**. Use **imperative** mood and **no trailing period** on the subject.


i don't think all the prose around conventional commits is needed and i'm sure that just dropping the fact that the repo uses conventional commits is enough

acud · 2026-05-01T23:22:32Z

+
+## Coding conventions (summary)
+
+Authoritative detail: `CODING.md` and `CODINGSTYLE.md`.


references the same files that were mentioned before, not sure if it's needed

acud · 2026-05-01T23:23:01Z

+### Errors, logging, concurrency
+
+- Propagate errors; do not log and return the same error. Use `fmt.Errorf("context: %w", err)`. Avoid stacking "failed to" prefixes.
+- Sentinel errors: `var ErrFoo = errors.New("package: description")` when appropriate.


typed errors

acud · 2026-05-01T23:27:44Z

+## Common pitfalls
+
+- Do not confuse `ChunkSize` (4096 data bytes) with `ChunkWithSpanSize` (4104 including span).
+- XOR distance: "closer" is more shared prefix bits, not smaller integers.


it is exactly the same :) XOR distance between two addresses will generate smaller integers as a result of the operation when the amount of shared prefix bits grows

acud · 2026-05-01T23:28:07Z

+
+- Do not confuse `ChunkSize` (4096 data bytes) with `ChunkWithSpanSize` (4104 including span).
+- XOR distance: "closer" is more shared prefix bits, not smaller integers.
+- Do not both log and return the same error.


this was mentioned at least once above, and it is also mentioned in the coding guidelines that are referred to

acud · 2026-05-01T23:28:25Z

+- Do not confuse `ChunkSize` (4096 data bytes) with `ChunkWithSpanSize` (4104 including span).
+- XOR distance: "closer" is more shared prefix bits, not smaller integers.
+- Do not both log and return the same error.
+- Tests: `foo_test` + `export_test.go` pattern.


this repeats stuff that was already mentioned

acud · 2026-05-01T23:30:08Z

+- Goroutines must be stoppable (context cancel, quit channel, etc.).
+- Full node vs light node: reserve and storage incentives are full-node concerns.
+- Postage batches can be unusable (expired, depleted, unsynced); check before relying on stamps.
+- `*.pb.go` is generated; do not edit by hand. Regenerate with `make protobuf` after `.proto` changes.


just add the command at the dev commands section (with an inline comment that it should be used after changing protobuf specs)

akrem-chabchoub added 2 commits April 15, 2026 12:59

docs: add Agents.md for AI coding assistant guidance

9fc6302

docs: add CLAUDE.md for AI coding assistant guidance

4b74650

akrem-chabchoub changed the title ~~Feat/agents~~ docs: add CLAUDE.md for AI coding assistant guidance Apr 15, 2026

akrem-chabchoub self-assigned this Apr 15, 2026

docs: update AGENTS.md and CLAUDE.md

b2536ac

akrem-chabchoub marked this pull request as ready for review April 15, 2026 13:29

akrem-chabchoub added this to the 2026 milestone Apr 15, 2026

akrem-chabchoub linked an issue Apr 15, 2026 that may be closed by this pull request

Add CLAUDE.md / AGENTS.md for AI coding assistant context #5407

Open

akrem-chabchoub changed the title ~~docs: add CLAUDE.md for AI coding assistant guidance~~ docs: add CLAUDE.md and Agents.md for AI coding assistant guidance Apr 15, 2026

lint: trigger ci

8fc73dd

Made-with: Cursor

martinconic reviewed Apr 16, 2026

View reviewed changes

chore: trigger ci

f47de70

akrem-chabchoub requested review from acud, gacevicljubisa, janos and sbackend123 April 16, 2026 11:23

docs: remove flaky related infos

bfa02ac

gacevicljubisa requested changes Apr 16, 2026

View reviewed changes

akrem-chabchoub added 2 commits April 16, 2026 14:32

docs: remove CLAUDE.md

8e17f24

docs: enhance AGENTS.md with contribution guidelines and pre-commit c…

9a3590d

…hecklist

akrem-chabchoub requested review from gacevicljubisa and martinconic April 28, 2026 12:05

martinconic approved these changes Apr 28, 2026

View reviewed changes

gacevicljubisa requested changes Apr 30, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

akrem-chabchoub added 3 commits May 1, 2026 17:37

docs: update AGENTS.md to streamline instructions and clarify testing…

9dbbd03

… guidelines

docs: create CLAUDE.md with initial code notes and reference to AGENT…

ae3a40d

…S.md

docs: update AGENTS.md and CLAUDE.md

f65949b

akrem-chabchoub requested a review from gacevicljubisa May 1, 2026 15:43

acud reviewed May 1, 2026

View reviewed changes


		## Commit message format and PR titles

		This repo uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) with `commitlint.config.js`: allowed types are `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `test`. Header max 100 characters; footer lines max 72. Use imperative mood and no trailing period on the subject.


		## Coding conventions (summary)

		Authoritative detail: `CODING.md` and `CODINGSTYLE.md`.

Conversation

akrem-chabchoub commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Description

Open API Spec Version Changes (if applicable)

Motivation and Context (Optional)

Related Issue (Optional)

Screenshots (if appropriate):

AI Disclosure

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akrem-chabchoub Apr 16, 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!

gacevicljubisa left a comment

Choose a reason for hiding this comment

Uh oh!

akrem-chabchoub commented Apr 16, 2026

Uh oh!

gacevicljubisa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

akrem-chabchoub commented Apr 15, 2026 •

edited

Loading

akrem-chabchoub Apr 16, 2026 •

edited

Loading