Conversation
Add a module-shaped CLAUDE.md template that syncs into every CAT-supported module on pdk update, giving Claude an explicit conventions file before it touches code. Consolidates the proven pattern from the 5 modules that already hand-maintain a CLAUDE.md (firewall, lvm, package, postgresql, service). - ERB with OS-conditional content driven by the module's metadata.json via @configs['module_metadata']['operatingsystem_support'] (same convention as moduleroot_init/*.erb), with rescue fallbacks. Renders a "Linux specifics" and/or "Windows specifics" section; the Windows section is a stub expanded by MODULES-11830. Empty metadata defaults to Linux, and `has_linux ||= !has_windows` ensures AIX/Solaris/Darwin-only metadata still renders at least one section. - Common content covers project layout, rake commands, rspec-puppet patterns, coverage, litmus/beaker, Ruby code style, Gemfile gem sourcing + version-pin env vars, type/provider DSL gotchas, task-module conventions, metadata.json conventions, CI/nightly log pointers, outcome-based review policy, and the canonical project rules. - moduleroot/ is the community-wide default template, so the file lands in public consumer repos: no internal Jenkins/runbook pointers, no internal Jira stub, and CI guidance does not assume cat-github-actions shared workflows. - Pure ASCII: PDK's diff engine raises invalid-byte-sequence on non-ASCII under a non-UTF-8 locale, so the template avoids unicode entirely. Modules with their own CLAUDE.md opt out via .sync.yml `CLAUDE.md: unmanaged: true`. Validated locally with PDK 3.4.0: pdk convert renders the Linux-only section for lvm and both sections for concat across Linux-only, Linux+Windows, Windows-only, AIX-only, and empty-metadata cases; output is pure ASCII with no leftover ERB tags and is MD022 clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the 4-bullet Windows stub in the OS-conditional CLAUDE.md template with a full "Windows specifics" section, consolidating the MODULES-11830 artifact into this PR (which now delivers both MODULES-11829 and MODULES-11830). Adds Windows guidance covering: platform basics (Chocolatey/MSI providers, SCM services, backslash/case-insensitive paths, ACL permissions), DSC resource patterns (machine-generated dsc_* types, mangled names, Sensitive() credentials, Test-TargetResource idempotency), PowerShell exec idioms (powershell provider, idempotent onlyif/unless, ruby-pwsh, -EncodedCommand), scheduled_task semantics (taskscheduler_api2, trigger comparison, compatibility), native-extension Ruby gotchas (win32-* gems guarded by microsoft_windows?, Linux CI stubbing), and Windows Litmus/acceptance (real VMs not Docker, WinRM, reboots). Stays inside the existing `<% if has_windows -%>` conditional so it renders only for Windows-supporting modules. Pure ASCII (PDK's diff engine chokes on non-ASCII under a non-UTF-8 locale). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Respond to review on #642: - Move CLAUDE.md.erb from moduleroot/ (force-synced on every pdk update) to moduleroot_init/ so it is a one-time default: new modules get it and own it, existing modules are never overwritten (per @david22swan). This also removes the clobber risk for the 5 modules that hand-maintain a CLAUDE.md -- no .sync.yml opt-out needed. moduleroot_init needs no config_defaults entry. - Reframe the header from "do not edit" to "starting point, tailor it to this repo" -- the file is meant to carry module-specific detail, not stay generic. - Drop `has_linux ||= !has_windows`: it mislabelled AIX/Solaris/Darwin-only modules as Linux (@Copilot). Empty/unknown metadata still defaults to Linux. - Keep RuboCop under bundler: `bundle exec rubocop -A`, not bare `rubocop -a` (@Copilot). - Note facts come from facterdb via rspec-puppet-facts/on_supported_os (@david22swan). - Mention spec_helper_acceptance.rb(+_local) for Litmus setup (@david22swan). - Note that rules needing enforcement should be backed by runtime hooks in .claude/, since prose alone can be treated as suggestions (@david22swan). Validated with PDK 3.4.0: pdk new module deploys the file (owned, customizable); pdk update leaves an existing module's copy untouched. Pure ASCII, ERB balanced. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot
AI
changed the title
[WIP] Add synced CLAUDE.md.erb with Linux and Windows specifics
(MODULES-11829, MODULES-11830) Add initial CLAUDE.md.erb template (moduleroot_init) with Linux + Windows specifics
Jul 1, 2026
imaqsood
force-pushed
the
MODULES-11829-moduleroot-claude-md
branch
4 times, most recently
from
35aeb59 to
abaa7b2
Compare
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
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.
Summary
Adds an OS-aware
CLAUDE.md.erbas a one-time starter template inmoduleroot_init/(notmoduleroot/), so new/converted modules get an initial framework they can tailor, andpdk updatedoes not re-sync or overwrite hand-maintainedCLAUDE.md.This PR includes both:
CLAUDE.md.erbframework + Linux specificsKey details:
@configs['module_metadata']['operatingsystem_support'](with rescue fallbacks) to render Linux and/or Windows sections.bundle exec rubocop -A).rspec-puppet-facts/on_supported_os),spec_helper_acceptance.rbreferences, and.claude/runtime-hooks guidance.Additional Context
Validation performed locally with PDK 3.4.0:
pdk new module/pdk convertdeployCLAUDE.md.pdk updateleaves existing module-ownedCLAUDE.mduntouched.metadata.jsonsupport matrix.Related Issues (if any)
Checklist