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?

gacevicljubisa · 2026-04-30T08:56:14Z

+## Directory structure (high level)
+
+```
+cmd/bee/              CLI and Cobra commands
+openapi/              OpenAPI specs (Swarm.yaml, SwarmCommon.yaml)
+packaging/            deb, rpm, homebrew, scoop, docker, systemd
+pkg/
+  api/                HTTP API
+  node/               composition root
+  swarm/              Address, Chunk, core constants
+  p2p/                libp2p transport
+  topology/           Kademlia
+  storage/            storage interfaces
+  storer/             local storer implementation
+  sharky/             blob slots
+  postage/            stamps and batches
+  storageincentives/  redistribution
+  pushsync/ pullsync/ retrieval/ pingpong/ hive/ pricing/  # protocols
+  feeds/ pss/ soc/ cac/ bmt/ manifest/ accesscontrol/ redundancy/ replicas/
+  settlement/ accounting/ crypto/ keystore/ log/ metrics/ tracing/
+  ...                 ~60 packages total
+```


There is no actual value from this incompleted list. I would remove ti

gacevicljubisa · 2026-04-30T08:56:51Z

+- 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` files are committed; regenerate with `make protobuf` after `.proto` changes.


*.pb.go is generated; do not edit by hand. Regenerate with make protobuf after .proto changes.

gacevicljubisa · 2026-04-30T08:57:38Z

+### Linting
+
+`golangci-lint` v2 per `.golangci.yml`. Notable: `goheader`, `paralleltest`, `misspell`, `errorlint`, `gochecknoinits`, `prealloc`, `forbidigo` (no `fmt.Print` except under `cmd/bee/cmd/`), `govet` with `enable-all` (minus `fieldalignment`, `shadow`). Run `make lint` and `make format`.
+


For lint section it is enough to have:

- Linting: `golangci-lint` v2 per `.golangci.yml`. Run `make lint`.

gacevicljubisa · 2026-04-30T08:58:04Z

+
+Codex users: see [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md/) for how global and project instructions merge and for the default combined size limit (`project_doc_max_bytes`, often 32 KiB).
+
+This repo also has **`CLAUDE.md`**, tuned for **Claude Code** (shorter session prompt, `@` imports, `.claude/rules/`). Keep factual content aligned when you change workflows or versions.


This can be removed.

gacevicljubisa · 2026-04-30T08:59:16Z

+
+1. **Formatting** — `make format` (gofumpt + gci; see `CODING.md`).
+2. **Compile** — `make build` (all packages) and, when you need the binary artifact, `make binary` (`dist/bee`, `CGO_ENABLED=0`).
+3. **Tests** — `make test` (unit tests, `-failfast`). Use `make test-race` when concurrency is central to the change. Use `make test-integration` only when you touch integration-tagged code.


Maybe to add here single package testing to not test everytime all of the unit tests. Something like:

3. **Tests** — `make test` (unit tests, `-failfast`). For a single package use `go test ./pkg/<name>/...`. Use `make test-race` when concurrency is central to the change. Use `make test-integration` only when you touch integration-tagged code.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add CLAUDE.md and Agents.md for AI coding assistant guidance#5437

docs: add CLAUDE.md and Agents.md for AI coding assistant guidance#5437
akrem-chabchoub wants to merge 8 commits intomasterfrom
feat/agents

akrem-chabchoub commented Apr 15, 2026 •

edited

Loading

Uh oh!

martinconic Apr 16, 2026

Uh oh!

akrem-chabchoub Apr 16, 2026 •

edited

Loading

Uh oh!

gacevicljubisa left a comment

Uh oh!

akrem-chabchoub commented Apr 16, 2026

Uh oh!

gacevicljubisa left a comment

Uh oh!

gacevicljubisa Apr 30, 2026

Uh oh!

gacevicljubisa Apr 30, 2026

Uh oh!

gacevicljubisa Apr 30, 2026

Uh oh!

gacevicljubisa Apr 30, 2026

Uh oh!

gacevicljubisa Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		### Linting

		`golangci-lint` v2 per `.golangci.yml`. Notable: `goheader`, `paralleltest`, `misspell`, `errorlint`, `gochecknoinits`, `prealloc`, `forbidigo` (no `fmt.Print` except under `cmd/bee/cmd/`), `govet` with `enable-all` (minus `fieldalignment`, `shadow`). Run `make lint` and `make format`.


		Codex users: see [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md/) for how global and project instructions merge and for the default combined size limit (`project_doc_max_bytes`, often 32 KiB).

		This repo also has `CLAUDE.md`, tuned for Claude Code (shorter session prompt, `@` imports, `.claude/rules/`). Keep factual content aligned when you change workflows or versions.

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!

martinconic Apr 16, 2026

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!

gacevicljubisa Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

gacevicljubisa Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

gacevicljubisa Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

gacevicljubisa Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

gacevicljubisa Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

akrem-chabchoub commented Apr 15, 2026 •

edited

Loading

akrem-chabchoub Apr 16, 2026 •

edited

Loading