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

[akrem-chabchoub]

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.

[martinconic]

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

[akrem-chabchoub]

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]

@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 !

[gacevicljubisa]

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

[acud]

this is just my preference, but i honestly am very averse to claude touching my git history. in most of my projects there's a big fat line saying - never commit anything to git. NEVER!!!. it makes things very difficult to follow since the agents add a lot of intermediate commits - i like to have my own messages and history that i as an operator can relate to.

that being said, i don't have much resistance to having this committed as it is, but i would strongly suggest to add both of these files to the .gitignore file, so that devs can be free to make their own changes locally, and we can just keep the "spine" of the document in the repo, with little changes as needed

[akrem-chabchoub]

Yes good idea I agree

[acud]

LGTM, just please add now these files to the repos .gitignore as part of this changeset before merging, as this will just be more convenient for devs using this inadvertently