HDDS-15316. Add AGENTS.md and CLAUDE.md by smengcl · Pull Request #10302 · apache/ozone

smengcl · 2026-05-18T22:27:04Z

Generated-by: Claude Code w/ Opus 4.7

What changes were proposed in this pull request?

Init CLAUDE.md for ozone.

This can be considered a subtask of HDDS-15158

This is generated using /init command in Claude Code. Using Opus 4.7 xhigh.

Added checkstyle CI workflow in addition to the originally generated content.

Pls feel free to suggest new lines to be added to this md, or we can revise later on.

What is the link to the Apache JIRA

https://issues.apache.org/jira/browse/HDDS-15316

How was this patch tested?

n/a

Generated-by: Claude Code w/ Opus 4.7

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

- Add CLAUDE.md to RAT exclusions (rat.sh would otherwise fail). - Trim inline submodule enumeration; point at pom.xml for full lists. - Reorder build commands to recommend `install` over `verify` for iterative dev. - Consolidate code-conventions and PR-workflow into one section pointing at CONTRIBUTING.md. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Point at pom.xml for groupId/artifactId/version instead of inlining 2.2.0-SNAPSHOT, which will drift on each release. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

ivandika3

Thanks @smengcl , left first reviews.

Will research more on the agents.md and claude.md best practices.

ivandika3 · 2026-05-19T01:34:52Z

+Useful flags (composable):
+- `-DskipShade` — skip building the shaded Ozone FS jar (saves time; omit this flag if you need to run filesystem integration tests, which require the shaded jar)
+- `-DskipRecon` — skip Recon Web UI (~2 min faster)
+- `-DskipDocs` — skip Hugo docs build
+- `-Pdist` — build the binary tarball under `hadoop-ozone/dist/target/`


We can prompt the model to use these options when building locally.

Do you mean we should remove this section? Or keep it here

Agent shall know what commands to execute to validate the changes, optional commands could confuse the agent.

Sorry what I meant is we keep it, but we can specify in the markdown that we should use these options when building locally.

…d hints - Rename CLAUDE.md -> AGENTS.md (cross-tool convention per agents.md); add CLAUDE.md as a symlink so existing Claude Code users still work. - Drop Claude-specific intro; rewrite tool-agnostic. - Add Tech stack line (Java 8 / JDK21 runtime, Maven, JUnit 5, Hadoop RPC + gRPC over Protobuf, RocksDB, Ratis). - Recommend `-DskipShade -DskipRecon -DskipDocs` for iterative builds. - Add `Generated-by: Claude Code (Opus 4.7)` attribution per ASF generative-tooling policy. - RAT: add AGENTS.md alongside CLAUDE.md in rat-exclusions. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Per ASF generative-tooling policy, contributors should attribute non-trivial AI-generated content as `Generated-by: TOOL (MODEL)`. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

yandrey321 · 2026-05-19T19:31:54Z

@@ -0,0 +1,80 @@
+# AGENTS.md


it would be nice to add skills and rules files for Cursor:
https://cursor.com/docs/skills & https://cursor.com/docs/rules

Yes, but I think we can address this in the future. I would prefer if we develop our own Ozone-related skills (e.g. Cassandra bug hunting skills apache/cassandra#4794 or backporting skills for release process) instead of using the generic skills like https://github.com/obra/superpowers / https://github.com/mattpocock/skills / https://github.com/addyosmani/agent-skills

And for skills, let's standardize to something like https://agentskills.io instead of Cursor specific formats.

ivandika3 · 2026-05-20T01:34:30Z

This is generated using /init command in Claude Code. Using Opus 4.7 xhigh.

I think using the AGENTS.md using Claude Code /init is not advisable. See https://www.humanlayer.dev/blog/writing-a-good-claude-md for the reasoning.

Since AGENTS.md will be loaded for each session, it is important we get this right (otherwise it might be a regression). I would prefer if the creator can try using the AGENTS.md for a while (to do bug fixes, creating small to large features) and update based on their findings and shortcomings. This would increase the community confidence in these AGENTS.md

Personally, these are the things I would add:

Prefer merging new integration tests with existing integration tests (i.e. avoid creating a new MiniOzoneCluster for every test).
Prefer to use Ratis utilites (e.g. Ratis Preconditions, etc) and reuse existing functions
No unnecessary line-wrap (as long it fits the checkstyle max length)
Add Apache header by default
Add "HDDS-XXXX" for each commit message (but this requires the agent to know which ticket is assigned to so might be difficult).
Prefer using existing Ozone related glossary instead of inventing new ones unless necessary (things like "control plane", "materialized", etc)

PTAL of these links I found, we can research on the Harness engineering best practices

smengcl and others added 2 commits May 18, 2026 15:24

HDDS-15316. Add CLAUDE.md

a7e7448

Generated-by: Claude Code w/ Opus 4.7

HDDS-15316. Add note to run checkstyle.sh before posting PR

fa02226

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

smengcl requested review from ivandika3 and jojochuang May 18, 2026 22:27

smengcl added documentation Improvements or additions to documentation AI-gen labels May 18, 2026

smengcl and others added 3 commits May 18, 2026 16:01

HDDS-15316. Avoid hardcoding Maven version in CLAUDE.md

a95799c

Point at pom.xml for groupId/artifactId/version instead of inlining 2.2.0-SNAPSHOT, which will drift on each release. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

HDDS-15316. Use real test method in CLAUDE.md single-test example

705efaa

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

ivandika3 reviewed May 19, 2026

View reviewed changes

Comment thread CLAUDE.md Outdated

smengcl and others added 2 commits May 19, 2026 01:35

HDDS-15316. Add Generated-by attribution rule to AGENTS.md conventions

974e76b

Per ASF generative-tooling policy, contributors should attribute non-trivial AI-generated content as `Generated-by: TOOL (MODEL)`. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

smengcl changed the title ~~HDDS-15316. Add CLAUDE.md~~ HDDS-15316. Add AGENTS.md and CLAUDE.md May 19, 2026

smengcl marked this pull request as ready for review May 19, 2026 18:16

Copilot AI review requested due to automatic review settings May 19, 2026 18:16

Copilot started reviewing on behalf of smengcl May 19, 2026 18:17 View session

Copilot AI reviewed May 19, 2026

View reviewed changes

yandrey321 reviewed May 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HDDS-15316. Add AGENTS.md and CLAUDE.md#10302

HDDS-15316. Add AGENTS.md and CLAUDE.md#10302
smengcl wants to merge 7 commits into
apache:masterfrom
smengcl:HDDS-15316-claude-md

smengcl commented May 18, 2026 •

edited

Loading

Uh oh!

ivandika3 left a comment •

edited

Loading

Uh oh!

Uh oh!

ivandika3 May 19, 2026 •

edited

Loading

Uh oh!

smengcl May 19, 2026

Uh oh!

yandrey321 May 19, 2026

Uh oh!

ivandika3 May 20, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

yandrey321 May 19, 2026

Uh oh!

ivandika3 May 20, 2026 •

edited

Loading

Uh oh!

ivandika3 commented May 20, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

smengcl commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes were proposed in this pull request?

What is the link to the Apache JIRA

How was this patch tested?

Uh oh!

ivandika3 left a comment • 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!

Uh oh!

ivandika3 May 19, 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!

smengcl May 19, 2026

Choose a reason for hiding this comment

Uh oh!

yandrey321 May 19, 2026

Choose a reason for hiding this comment

Uh oh!

ivandika3 May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

yandrey321 May 19, 2026

Choose a reason for hiding this comment

Uh oh!

ivandika3 May 20, 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!

ivandika3 commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

smengcl commented May 18, 2026 •

edited

Loading

ivandika3 left a comment •

edited

Loading

ivandika3 May 19, 2026 •

edited

Loading

ivandika3 May 20, 2026 •

edited

Loading

ivandika3 commented May 20, 2026 •

edited

Loading