Keep CLAUDE.md consistent across repos in a GitHub org
For platform and engineering teams: write the shared part of CLAUDE.md once, in a
central repo, and have it proposed to every repo as a pull request. Each repo keeps its own notes
outside the managed sections.
← home · all how-tos · concepts · companions · markdown
TL;DR
- Every change reaches a target repo as a pull request that its owners review. Nothing is force-pushed or merged for you.
- Split
CLAUDE.mdinto managed sections (the org standard) and local notes (owned by each repo). - Keep the managed sections in one central repo as a template, with a
steerspec-sync.ymlthat lists the target repos. - A GitHub Actions workflow runs the strspc-sync action on every push to the template and opens one pull request per template, per repo.
- A render that has not changed opens no pull request.
- Next: detect drift when a repo edits its copy afterwards.
// What changes in your repos, and what does not
- Every change to a target repo lands as a pull request. Sync never force-pushes a git ref and never merges
(README).
The
forceoption only bypasses the recorded hash check; it does not force-push. - The central repo is the exception: after every run, sync commits
.steerspec/deployment-state.jsonstraight to the central repo's default branch. If that branch requires pull requests, the identity running sync must be allowed to bypass the ruleset, or the run fails and records nothing (configuration). - Commits go through GitHub's
createCommitOnBranchmutation, which GitHub signs, so they pass rulesets that require verified signatures with a token or an App (authentication, since v0.4.3). - strspc-sync is Apache 2.0 licensed. Its behaviour is specified by the
dev.steerspec.syncrealm, whose rules are Draft (rules).
// Why copies drift apart
A CLAUDE.md copied into each repo by hand becomes many files with one history each. A fix to
the shared standard has to be repeated in every repo, and an edit in one repo is invisible to the others.
Two things make the problem tractable: decide which lines are the org's and which are the repo's, and
make a single place the source of the org's lines.
// 1. Create a central repo
One repo in your org holds the templates and the configuration, for example
your-org/steerspec-config. It also receives the deployment state, the record of what was
proposed to which repo.
// 2. Write the template with managed sections
With the marker strategy, sync replaces only the sections between
STEERSPEC:BEGIN and STEERSPEC:END markers and leaves the rest of the target
file alone. The template below is the quickstart file
(CLAUDE.md.mustache);
{{org_name}} and the other placeholders are Mustache variables from the configuration.
# {{org_name}} Project Standards
<!-- STEERSPEC:BEGIN:project-standards -->
## Project Standards
- Use {{default_model}} as the default AI model
- Follow coding standards at {{coding_standards_url}}
- Write tests for all new functionality
- Use conventional commits
<!-- STEERSPEC:END:project-standards -->
<!-- STEERSPEC:BEGIN:coding-conventions -->
## Coding Conventions
- Follow the language-specific style guide
- Maximum function length: 50 lines
- All public APIs must have documentation
<!-- STEERSPEC:END:coding-conventions -->
## Local Project Notes
Add project-specific notes below. This section is not managed by SteerSpec.
// 3. List the template and the target repos
steerspec-sync.yml sits at the root of the central repo. This excerpt of the
quickstart config
keeps the CLAUDE.md template and drops the other templates, the target overrides, the monitor and conflicts sections, and the
comments. targets selects repos by name pattern and topic; overrides (in the full file) sets
per-repo variables or skips a template for one repo.
version: "1.0.0"
central-repo: acme-corp/steerspec-config
auth:
method: github-token
variables:
org_name: "acme-corp"
default_model: "claude-sonnet-4-6"
coding_standards_url: "https://acme-corp.dev/standards"
templates:
- id: claude-md
version: "1.0.0"
type: claude-md
source: templates/CLAUDE.md.mustache
destination: CLAUDE.md
strategy: marker
targets:
include:
- "acme-corp/*"
exclude:
- "acme-corp/archived-*"
- "acme-corp/.github"
- "acme-corp/steerspec-config"
topics:
- claude-managed
sync:
concurrency: 5
pr-label: steerspec-sync
close-stale-prs: true
// 4. Give sync a token that reaches the other repos
The workflow's own GITHUB_TOKEN is scoped to the central repo and cannot open pull requests
anywhere else. Store a PAT, or use a GitHub App installation, with contents and
pull_requests write on every target repo
(authentication).
An App is confined to the repos it is installed on
(quickstart config).
Sync also commits .steerspec/deployment-state.json straight to the central repo's default branch after every
run, so the same credential needs contents write there too. If a ruleset or branch protection on that branch
requires pull requests or status checks, the identity running sync must be allowed to bypass it; otherwise the run fails
with deployment state not saved
(configuration).
The quickstart's App permissions are Contents, Pull requests and Issues, each read and write.
// 5. Add the sync workflow
This is the
quickstart workflow
with its comments removed and the action pin moved from v0.4.1, which the docs still show,
to the v0.4.5 release.
Pin an exact tag, never a branch. For a first run, set dry-run: true to preview the changes
without opening pull requests.
name: SteerSpec Sync
on:
push:
branches: [main]
paths:
- 'templates/**'
- 'steerspec-sync.yml'
workflow_dispatch:
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: SteerSpec/strspc-sync/sync@v0.4.5
with:
dry-run: false
token: ${{ secrets.STEERSPEC_TOKEN }}
// 6. Review the pull requests
Each target repo gets one pull request per template, titled
chore(steerspec-sync): update <template-id> to <version>; the type and scope are
configurable for repos with stricter commit rules
(how it works).
The repo's owners review and merge it like any other change. To change the standard later, edit the
template, raise its version (it appears in the pull request title) and push: the workflow
proposes the new text to every target whose copy differs from it.
// Where SteerSpec fits
strspc-sync is the SteerSpec GitHub Action for this job, and SteerSpec uses it on its own repos: the
org-standards section of
strspc-sync's CLAUDE.md
is a managed section synced from a central repo.
The quickstart configuration also distributes .claude/agents/, .claude/skills/ and
.claude/settings.json. Two companion commands run after sync: monitor reports files
that have drifted from their template (see detect drift), and
conflict flags contradictions between AI config files across the fleet
(commands). strspc-sync
works without the rest of SteerSpec; the
SteerSpec 101 covers rules and realms, and concepts defines sync and
drift. Listing: GitHub Marketplace,
companions.