docs(claude): expand CLAUDE.md with commands, conventions, architecture, review scope - #197
Merged
Conversation
📝 WalkthroughWalkthrough
ChangesRepository guidance
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Oddly
force-pushed
the
docs/claude-md-expand
branch
3 times, most recently
from
August 12, 2026 08:24
c40433d to
6a29a18
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Line 89: Update the directory-tree fences in CLAUDE.md, including the sections
around lines 89 and 141-143, to use the text language tag. Add the
markdownlint-cli2 command to the validation guidance, or narrow the stated lint
and drift-check coverage so it does not claim to validate CLAUDE.md.
- Around line 50-60: Update the role-gate guidance to use a falsey-aware default
or explicit null handling before checking length, covering undefined, null,
empty strings, lists, and dictionaries. Correct the scripts/check_argspecs.py
description to state that it compares top-level variables in defaults/main.yml
with argument_specs.yml, and remove the claim that it scans task gates.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: ebaaecfe-b037-4090-83f1-01627caea2fe
📒 Files selected for processing (1)
CLAUDE.md
|
|
||
| Six roles, hierarchical: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Make the documentation pass Markdown lint.
markdownlint-cli2 reports MD040 because the directory-tree fence on Line [89] has no language. Add text to the opening fence. Also name the Markdown lint command in the validation guidance, or narrow the claim that the listed lint and drift checks cover CLAUDE.md.
Proposed fix
-```
+```textAlso applies to: 141-143
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 89-89: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` at line 89, Update the directory-tree fences in CLAUDE.md,
including the sections around lines 89 and 141-143, to use the text language
tag. Add the markdownlint-cli2 command to the validation guidance, or narrow the
stated lint and drift-check coverage so it does not claim to validate CLAUDE.md.
Source: Linters/SAST tools
Oddly
force-pushed
the
docs/claude-md-expand
branch
3 times, most recently
from
August 12, 2026 08:46
6f43590 to
6939610
Compare
…ecture, review scope CLAUDE.md previously carried only the Fix Workflow and role-default gating sections. Expand to four practical chunks based on patterns seen in similar repos (ansible/metrics-service, leogallego's claude-ansible-skills, Red Hat CoP good practices): - Development commands: what to run for check_argspecs, gen_argspecs, ansible-lint, molecule per-scenario, CI coverage. Stops the guessing step at the start of every session. - Repository conventions: task naming (role_prefix | Verb), commit message style, FQCN, Co-authored-by casing, optional-string pointer convention. All already implicit; now written down. - Architecture: six-role hierarchy, elasticstack meta-role, cert host, key task-file entry points. Explains why the same include patterns repeat across service roles. - Multi-OS + memory notes: PR-time distro matrix, why full_stack uses max-parallel 3, which scenarios carry the largest memory footprint. Answers the questions that came up during #186's capacity-flake diagnosis. - Reviewing PRs (diff-aware): what to skip vs. what to always re-verify per touched path. Includes the cross-role gate-pattern guidance that codifies today's elasticsearch+kibana fix pair.
Oddly
force-pushed
the
docs/claude-md-expand
branch
from
August 12, 2026 10:45
6939610 to
6c54c3a
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Around line 98-109: Correct the role hierarchy description in CLAUDE.md to
state that four service roles import the elasticstack meta-role, while repos is
included directly by callers. Update the corresponding later wording as well,
preserving the existing distinction between service-role imports and direct
repos inclusion.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: e40ff4a0-f4e5-4c0f-be54-dc96a39c2202
📒 Files selected for processing (1)
CLAUDE.md
Comment on lines
+98
to
+109
| Six roles — one meta-role plus five siblings that import it: | ||
|
|
||
| ``` | ||
| roles/ | ||
| elasticstack/ Meta-role. Runs once per host (idempotency fact | ||
| _elasticstack_role_imported). Owns cert generation via | ||
| elasticsearch-certutil, CA lifecycle, initial password | ||
| handling (elasticstack-passwords.yml), and the shared | ||
| variables service roles read (elasticstack_release, | ||
| elasticstack_security, elasticstack_cert_pass, | ||
| elasticstack_ca_host). | ||
| repos/ Elastic APT/YUM repo setup. Version-aware. Included |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Correct the role hierarchy statement.
The heading says that all five sibling roles import oddly.elasticstack.elasticstack. The later text identifies repos as a directly included role and limits the import to service roles. State that four service roles import the meta-role, while repos is included directly by callers.
Proposed wording
-Six roles — one meta-role plus five siblings that import it:
+Six roles — one meta-role plus five sibling roles:
+
+The four service roles import the meta-role. The `repos` role is included
+directly by playbooks and Molecule scenarios.Also applies to: 124-129
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 100-100: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` around lines 98 - 109, Correct the role hierarchy description in
CLAUDE.md to state that four service roles import the elasticstack meta-role,
while repos is included directly by callers. Update the corresponding later
wording as well, preserving the existing distinction between service-role
imports and direct repos inclusion.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds four practical sections to
CLAUDE.mdbased on patterns seen in similar repos (ansible/metrics-service,leogallego/claude-ansible-skills, Red Hat CoP good practices):read, notguess.role_prefix | Verb), commit message style, FQCN,Co-authored-by:casing. All previously implicit.elasticstackmeta-role, cert host, key task-file entry points.full_stackusesmax-parallel: 3, which scenarios are memory-heavy. Codifies what came up during the chore(ci): fail CI when defaults/main.yml drifts from argument_specs.yml #186 capacity-flake diagnosis.elasticstack_cert_passfix pair.Summary by CodeRabbit