HYPERFLEET-721 - feat: agent-native repo optimization with nested CLAUDE.md#68
Conversation
… CLAUDE.md files Add hierarchical CLAUDE.md files, refactor AGENTS.md, add make verify-all, and create .claude/settings.json to optimize the repo for AI coding agents. - Root CLAUDE.md (~133 lines) with project identity, setup, conventions, boundaries - 9 nested CLAUDE.md files in key directories (handlers, services, dao, db, errors, plugins, test, charts, openapi) - AGENTS.md refactored from ~800 to ~164 lines (6-section standard format) - make verify-all target (verify + lint + test, no DB required) - .claude/settings.json with team-shared safe command permissions - .gitignore updated to track .claude/settings.json Co-Authored-By: Claude <noreply@anthropic.com>
WalkthroughThis pull request adds Claude Code integration infrastructure to the HyperFleet API repository. It introduces a Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (5)
pkg/errors/CLAUDE.md (1)
7-16: Add language specifier to fenced code block.The
ServiceErrorstruct definition lacks a language identifier. Addinggoimproves syntax highlighting.📝 Suggested fix
-``` +```go type ServiceError struct { RFC9457Code string // HYPERFLEET-CAT-NUM format🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pkg/errors/CLAUDE.md` around lines 7 - 16, The fenced code block showing the ServiceError struct should include a language specifier for proper syntax highlighting; edit the markdown in pkg/errors/CLAUDE.md so the opening fence becomes ```go before the ServiceError definition (the block containing ServiceError, RFC9457Code, Type, Title, Reason, HttpCode, Details) and leave the rest of the code unchanged.pkg/db/CLAUDE.md (1)
7-17: Add language specifier to fenced code block.The
SessionFactoryinterface definition lacks a language identifier.📝 Suggested fix
-``` +```go type SessionFactory interface { Init(*config.DatabaseConfig) DirectDB() *sql.DB🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pkg/db/CLAUDE.md` around lines 7 - 17, The fenced code block showing the SessionFactory interface is missing a language specifier; update the markdown block fence that contains the SessionFactory interface (the lines starting with "type SessionFactory interface { ... }") to include "go" (i.e., change ``` to ```go) so the block is syntax-highlighted as Go.pkg/services/CLAUDE.md (1)
9-13: Add language specifier to fenced code block.The code block illustrating the service interface pattern lacks a language identifier. Adding
goimproves syntax highlighting and satisfies markdown lint rules.📝 Suggested fix
-``` +```go type ClusterService interface { ... } type sqlClusterService struct { ... } func NewClusterService(dao, adapterStatusDao, config) ClusterService</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@pkg/services/CLAUDE.mdaround lines 9 - 13, The fenced code block showing
the service pattern (containing ClusterService, sqlClusterService, and
NewClusterService) is missing a language specifier; update the Markdown fenced
block to use the Go language tag by changing the opening backticks to ```go so
syntax highlighting and markdown linting are correct.</details> </blockquote></details> <details> <summary>openapi/CLAUDE.md (1)</summary><blockquote> `15-18`: **Add language specifiers to fenced code blocks.** Multiple code blocks in this file lack language identifiers. Adding `bash` or `text` improves readability and satisfies markdown lint. <details> <summary>📝 Suggested fix for lines 15-18</summary> ```diff -``` +```bash make generate # Regenerates pkg/api/openapi/ from openapi/openapi.yaml make generate-all # generate + generate-mocks ``` ``` </details> Similar changes apply to other code blocks (lines 21, 25-29, 33-36). <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@openapi/CLAUDE.mdaround lines 15 - 18, Several fenced code blocks in
CLAUDE.md (for example the block containing "make generate" and "make
generate-all") are missing language specifiers; update each triple-backtick
fence (including the blocks at the shown snippet and the other blocks referenced
at lines 21, 25-29, and 33-36) to include an appropriate language tag such as
"bash" or "text" so they render and lint correctly (e.g., replacewithbash for shell commands and use ```text for plain output). Ensure every
fenced block in CLAUDE.md has a language identifier.</details> </blockquote></details> <details> <summary>AGENTS.md (1)</summary><blockquote> `10-18`: **Add language specifiers to fenced code blocks.** Static analysis flags multiple code blocks without language identifiers. Adding `bash` improves syntax highlighting and lint compliance. <details> <summary>📝 Suggested fix for setup block</summary> ```diff -``` +```bash make generate-all # REQUIRED FIRST — generated code not in git go mod download make secrets # Initialize secrets/ with defaults ``` </details> Similar changes apply to other code blocks throughout the file (lines 21, 29, 36, 47, 76, 135, 141). <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@AGENTS.mdaround lines 10 - 18, Several fenced code blocks in AGENTS.md are
missing language identifiers; update each triple-backtick fence that contains
shell commands to include a language specifier (use bash). Locate the block that
begins with "make generate-all # REQUIRED FIRST — generated code not in git"
and changetobash, and do the same for other command blocks (e.g., those
containing "./bin/hyperfleet-api migrate", "make run-no-auth", and the other
setup/commands noted in the review). Ensure every fenced block with shell
commands throughout the file uses ```bash so syntax highlighting and linters
pick them up.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@charts/CLAUDE.md:
- Around line 12-15: Add the missing language tag "bash" to the fenced code
blocks that contain the Helm --set snippets (the blocks showing --set
'adapters.cluster=["validation"]' and --set 'adapters.nodepool=["validation"]'
and the longer helm template example); update the opening triple-backtick for
each of those fenced blocks to ```bash so markdownlint MD040 is satisfied while
leaving the block contents unchanged.In
@CLAUDE.md:
- Around line 16-18: Update the fenced code block in CLAUDE.md so it includes a
language tag (e.g., replace the opening "" before the make generate-all snippet with "bash") to satisfy markdownlint rule MD040; ensure the closing
backticks remain unchanged so the snippet reads as a bash command and linter no
longer flags the block.- Line 7: Update the documented Go version in CLAUDE.md from "Go 1.24+" to "Go
1.25+" so it matches the enforced GO_VERSION := go1.25 in the Makefile; keep the
FIPS/CGO note (CGO_ENABLED=1 GOEXPERIMENT=boringcrypto) unchanged and ensure
the version string is the only change.In
@Makefile:
- Line 227: Update the follow-up message in the Makefile (the echo line that
currently prints "Run 'make test-integration' separately for integration tests
(requires database).") to reflect that integration tests auto-provision
PostgreSQL via Testcontainers; change the text to something like "Run 'make
test-integration' separately for integration tests (Postgres is auto-provisioned
via Testcontainers)." This keeps the instruction to run the target separately
while removing the incorrect “requires database” wording; modify the echo
invocation in the same Makefile target that emits that string.In
@pkg/dao/CLAUDE.md:
- Around line 9-13: Add the Go language tag to all fenced code blocks in this
markdown so markdownlint MD040 passes: update the blocks containing the
ClusterDao interface, sqlClusterDao struct, and NewClusterDao constructor (the
snippet showing "type ClusterDao...", "type sqlClusterDao...", "func
NewClusterDao...") and the other blocks showing "db :=
d.sessionFactory.New(ctx)" and "db.MarkForRollback(ctx, err)" to usego instead of; search for those exact snippets or symbols (ClusterDao,
sqlClusterDao, NewClusterDao, d.sessionFactory.New, db.MarkForRollback) and
replace their opening fences with ```go.In
@plugins/CLAUDE.md:
- Around line 18-22: Add a language tag to the fenced code block so markdownlint
MD040 is satisfied: update the fence that surrounds the snippet containing
ServiceLocator, NewServiceLocator, and Service to use a Go language identifier
(i.e., replace the openingwithgo) so the block is properly highlighted
and linted.In
@test/CLAUDE.md:
- Line 13: Update the guidance text that currently reads "Located in
integration/" to the correct repo path "test/integration/"; locate the string
"Located inintegration/" in the test/CLAUDE.md content and replace it so the
documentation accurately points to the test/integration/ directory.
Nitpick comments:
In@AGENTS.md:
- Around line 10-18: Several fenced code blocks in AGENTS.md are missing
language identifiers; update each triple-backtick fence that contains shell
commands to include a language specifier (use bash). Locate the block that
begins with "make generate-all # REQUIRED FIRST — generated code not in git"
and changetobash, and do the same for other command blocks (e.g., those
containing "./bin/hyperfleet-api migrate", "make run-no-auth", and the other
setup/commands noted in the review). Ensure every fenced block with shell
commands throughout the file uses ```bash so syntax highlighting and linters
pick them up.In
@openapi/CLAUDE.md:
- Around line 15-18: Several fenced code blocks in CLAUDE.md (for example the
block containing "make generate" and "make generate-all") are missing language
specifiers; update each triple-backtick fence (including the blocks at the shown
snippet and the other blocks referenced at lines 21, 25-29, and 33-36) to
include an appropriate language tag such as "bash" or "text" so they render and
lint correctly (e.g., replacewithbash for shell commands and useidentifier. In `@pkg/db/CLAUDE.md`: - Around line 7-17: The fenced code block showing the SessionFactory interface is missing a language specifier; update the markdown block fence that contains the SessionFactory interface (the lines starting with "type SessionFactory interface { ... }") to include "go" (i.e., change ``` to ```go) so the block is syntax-highlighted as Go. In `@pkg/errors/CLAUDE.md`: - Around line 7-16: The fenced code block showing the ServiceError struct should include a language specifier for proper syntax highlighting; edit the markdown in pkg/errors/CLAUDE.md so the opening fence becomes ```go before the ServiceError definition (the block containing ServiceError, RFC9457Code, Type, Title, Reason, HttpCode, Details) and leave the rest of the code unchanged. In `@pkg/services/CLAUDE.md`: - Around line 9-13: The fenced code block showing the service pattern (containing ClusterService, sqlClusterService, and NewClusterService) is missing a language specifier; update the Markdown fenced block to use the Go language tag by changing the opening backticks to ```go so syntax highlighting and markdown linting are correct.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID:
9d2bf800-f134-4879-8fa3-588232e7309d📒 Files selected for processing (14)
.claude/settings.json.gitignoreAGENTS.mdCLAUDE.mdMakefilecharts/CLAUDE.mdopenapi/CLAUDE.mdpkg/dao/CLAUDE.mdpkg/db/CLAUDE.mdpkg/errors/CLAUDE.mdpkg/handlers/CLAUDE.mdpkg/services/CLAUDE.mdplugins/CLAUDE.mdtest/CLAUDE.md
| ``` | ||
| --set 'adapters.cluster=["validation"]' | ||
| --set 'adapters.nodepool=["validation"]' | ||
| ``` |
There was a problem hiding this comment.
Add language tags to both fenced command blocks.
Both snippets should be marked as bash to satisfy markdownlint MD040.
Suggested edit
-```
+```bash
--set 'adapters.cluster=["validation"]'
--set 'adapters.nodepool=["validation"]'@@
- +bash
helm template test-release charts/ --set 'adapters.cluster=["validation"]' --set 'adapters.nodepool=["validation"]' [additional overrides]
Also applies to: 32-34
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 12-12: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@charts/CLAUDE.md` around lines 12 - 15, Add the missing language tag "bash"
to the fenced code blocks that contain the Helm --set snippets (the blocks
showing --set 'adapters.cluster=["validation"]' and --set
'adapters.nodepool=["validation"]' and the longer helm template example); update
the opening triple-backtick for each of those fenced blocks to ```bash so
markdownlint MD040 is satisfied while leaving the block contents unchanged.
|
|
||
| HyperFleet API is a **stateless REST API** serving as the pure CRUD data layer for HyperFleet cluster lifecycle management. It persists clusters, node pools, and adapter statuses to PostgreSQL — no business logic, no events. Sentinel handles orchestration; adapters execute and report back. | ||
|
|
||
| - **Language**: Go 1.24+ with FIPS crypto (`CGO_ENABLED=1 GOEXPERIMENT=boringcrypto`) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== CLAUDE.md language line ==="
rg -n '^\-\s+\*\*Language\*\*:' CLAUDE.md || echo "Pattern not found, trying broader search:"
rg -n 'Language.*Go' CLAUDE.md
echo ""
echo "=== Makefile enforced Go version ==="
rg -n '^GO_VERSION\s*:=' Makefile || echo "Pattern not found, trying broader search:"
rg -n 'GO_VERSION' Makefile | head -5Repository: openshift-hyperfleet/hyperfleet-api
Length of output: 671
Update documented Go version to match enforced requirement.
CLAUDE.md line 7 documents "Go 1.24+", but Makefile enforces Go 1.25 (line 57: GO_VERSION := go1.25.). Update the documentation to reflect the actual minimum required version.
Suggested edit
-- **Language**: Go 1.24+ with FIPS crypto (`CGO_ENABLED=1 GOEXPERIMENT=boringcrypto`)
+- **Language**: Go 1.25 with FIPS crypto (`CGO_ENABLED=1 GOEXPERIMENT=boringcrypto`)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Language**: Go 1.24+ with FIPS crypto (`CGO_ENABLED=1 GOEXPERIMENT=boringcrypto`) | |
| - **Language**: Go 1.25 with FIPS crypto (`CGO_ENABLED=1 GOEXPERIMENT=boringcrypto`) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` at line 7, Update the documented Go version in CLAUDE.md from "Go
1.24+" to "Go 1.25+" so it matches the enforced GO_VERSION := go1.25 in the
Makefile; keep the FIPS/CGO note (`CGO_ENABLED=1 GOEXPERIMENT=boringcrypto`)
unchanged and ensure the version string is the only change.
| ``` | ||
| make generate-all # Generates OpenAPI types + mock implementations | ||
| ``` |
There was a problem hiding this comment.
Specify a language for fenced code blocks to satisfy markdownlint.
The command snippet should use a language tag (e.g., bash) to clear MD040.
Suggested edit
-```
+```bash
make generate-all # Generates OpenAPI types + mock implementations</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` around lines 16 - 18, Update the fenced code block in CLAUDE.md so
it includes a language tag (e.g., replace the opening "```" before the make
generate-all snippet with "```bash") to satisfy markdownlint rule MD040; ensure
the closing backticks remain unchanged so the snippet reads as a bash command
and linter no longer flags the block.
| .PHONY: verify-all | ||
| verify-all: verify lint test ## Run all static checks + unit tests (no database required) | ||
| @echo "All static checks and unit tests passed." | ||
| @echo "Run 'make test-integration' separately for integration tests (requires database)." |
There was a problem hiding this comment.
Adjust the verify-all follow-up message for integration tests.
Line 227 says integration tests “require database”, but this repo’s integration flow auto-provisions PostgreSQL via Testcontainers.
Suggested edit
- `@echo` "Run 'make test-integration' separately for integration tests (requires database)."
+ `@echo` "Run 'make test-integration' separately for integration tests (requires container runtime; DB is auto-provisioned)."📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| @echo "Run 'make test-integration' separately for integration tests (requires database)." | |
| `@echo` "Run 'make test-integration' separately for integration tests (requires container runtime; DB is auto-provisioned)." |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@Makefile` at line 227, Update the follow-up message in the Makefile (the echo
line that currently prints "Run 'make test-integration' separately for
integration tests (requires database).") to reflect that integration tests
auto-provision PostgreSQL via Testcontainers; change the text to something like
"Run 'make test-integration' separately for integration tests (Postgres is
auto-provisioned via Testcontainers)." This keeps the instruction to run the
target separately while removing the incorrect “requires database” wording;
modify the echo invocation in the same Makefile target that emits that string.
| ``` | ||
| type ClusterDao interface { ... } | ||
| type sqlClusterDao struct { sessionFactory *db.SessionFactory } | ||
| func NewClusterDao(sessionFactory *db.SessionFactory) ClusterDao | ||
| ``` |
There was a problem hiding this comment.
Add language tags to fenced code snippets.
These code blocks should specify go to satisfy markdownlint MD040.
Suggested edit
-```
+```go
type ClusterDao interface { ... }
type sqlClusterDao struct { sessionFactory *db.SessionFactory }
func NewClusterDao(sessionFactory *db.SessionFactory) ClusterDao@@
- +go
db := d.sessionFactory.New(ctx)
@@
-```
+```go
db.MarkForRollback(ctx, err)
</details>
Also applies to: 18-20, 26-28
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>
[warning] 9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @pkg/dao/CLAUDE.md around lines 9 - 13, Add the Go language tag to all fenced
code blocks in this markdown so markdownlint MD040 passes: update the blocks
containing the ClusterDao interface, sqlClusterDao struct, and NewClusterDao
constructor (the snippet showing "type ClusterDao...", "type sqlClusterDao...",
"func NewClusterDao...") and the other blocks showing "db :=
d.sessionFactory.New(ctx)" and "db.MarkForRollback(ctx, err)" to use go instead of ; search for those exact snippets or symbols (ClusterDao,
sqlClusterDao, NewClusterDao, d.sessionFactory.New, db.MarkForRollback) and
replace their opening fences with ```go.
</details>
<!-- fingerprinting:phantom:poseidon:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ``` | ||
| type ServiceLocator func() services.ClusterService | ||
| func NewServiceLocator(env *environments.Env) ServiceLocator | ||
| func Service(s *environments.Services) services.ClusterService | ||
| ``` |
There was a problem hiding this comment.
Add a language identifier to the fenced snippet.
This block should be tagged (e.g., go) to satisfy markdownlint MD040.
Suggested edit
-```
+```go
type ServiceLocator func() services.ClusterService
func NewServiceLocator(env *environments.Env) ServiceLocator
func Service(s *environments.Services) services.ClusterService</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>
[warning] 18-18: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @plugins/CLAUDE.md around lines 18 - 22, Add a language tag to the fenced
code block so markdownlint MD040 is satisfied: update the fence that surrounds
the snippet containing ServiceLocator, NewServiceLocator, and Service to use a
Go language identifier (i.e., replace the opening withgo) so the block
is properly highlighted and linted.
</details>
<!-- fingerprinting:phantom:poseidon:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ## Integration Tests | ||
|
|
||
| - Run: `make test-integration` (sets `OCM_ENV=integration_testing` and `TESTCONTAINERS_RYUK_DISABLED=true`) | ||
| - Located in `integration/` |
There was a problem hiding this comment.
Fix integration test path in the guidance.
Line 13 says integration/, but the repo target points to test/integration/.
Suggested edit
-- Located in `integration/`
+- Located in `test/integration/`📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Located in `integration/` | |
| - Located in `test/integration/` |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@test/CLAUDE.md` at line 13, Update the guidance text that currently reads
"Located in `integration/`" to the correct repo path "test/integration/"; locate
the string "Located in `integration/`" in the test/CLAUDE.md content and replace
it so the documentation accurately points to the test/integration/ directory.
|
/lgtm |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: rh-amarin The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
openshift-merge-bot
bot
merged commit 89c8376
into
openshift-hyperfleet:main
2 participants
Summary
make verify-alltarget (verify + lint + test, no DB required) for fast agent self-checks.claude/settings.jsonwith team-shared safe command permissions.gitignoreto selectively track.claude/settings.jsonJIRA
https://issues.redhat.com/browse/HYPERFLEET-721
Test plan
make verify-allruns successfully (new target)make helpshowsverify-allunder "Agent Verification"pre-commit run validate-agents-mdpasses on refactored AGENTS.mdpkg/handlers/CLAUDE.mdprovides handler-specific guidancemake test-helmstill passes (Helm charts unmodified)🤖 Generated with Claude Code
Summary by CodeRabbit
Chores
Documentation