# How to keep Cursor rules and CLAUDE.md in sync from one source

> Render CLAUDE.md, Cursor rules and Copilot instructions from one source with jostraca, keep a hand correction with merge, and fail CI when the copies drift.

Source: https://voxgig.com/howto/keep-cursor-rules-and-claude-md-in-sync

- Audience: platform-team
- Level: intermediate
- Languages: typescript
- Verified: 2026-11-22
- Published: 2026-11-22

## Short answer

Keep your conventions in one JSON file and render CLAUDE.md, `.cursor/rules/*.mdc` and `.github/copilot-instructions.md` from it with jostraca, each with its tool's front matter. Regenerate with merge mode, so a correction someone made in Cursor survives the next run. Gate CI with jostraca's `check()`, which compares a fresh render with the committed files and fails until the correction moves into the source.

---
## You will need

Node 22 or later, git, and a repository whose agents read more than one instruction format. The
sample pins [jostraca](https://github.com/jostraca/jostraca) 0.42.0 with its peer `shape`, and
runs Hygen 6.2.11 and Handlebars 4.7.10 beside it. If your repository can live with one shared
file, [Migrate CLAUDE.md and .cursor/rules to AGENTS.md](/howto/migrate-cursor-rules-to-agents-md)
first and generate only what is left.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Fern `.fernignore`](https://buildwithfern.com/learn/sdks/current/overview/custom-code) | A Fern SDK repository that also carries instruction files | Fern leaves listed files alone, so syncing them stays your own step | Your SDK repository is not written by Fern |
| [hand-maintained copies](https://cursor.com/docs/rules) | One tool, or two files that rarely change | Every fix is made once per file, and the copies part ways unnoticed | A third format arrives, or the files change monthly |
| [Handlebars template script](https://handlebarsjs.com/guide/expressions.html) | A small script you own end to end | Overwrites the file whole, and double braces escape Markdown backticks | People correct the generated files by hand |
| [Hygen](https://github.com/jondot/hygen/blob/v6.2.11/hygen.io/docs/templates.md) | Scaffolding files once, with a person at the terminal | In CI the overwrite prompt goes unanswered, so the source change never lands | The files must follow the source on every run |
| [jostraca merge and check](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/reference-options.md#check) | Generated files that people also correct by hand | A baseline to commit, a meta log that churns, and conflict markers to resolve | Nobody edits the files, so overwriting is enough |
| [NSwag](https://github.com/RicoSuter/NSwag/wiki/CommandLine) | A C# or TypeScript client generated beside the instruction files | Writes the client only, so the instruction files need a separate generator | You need the instruction files from the API document |

Voxgig maintains jostraca, which lives in its own `jostraca` GitHub organization. It is one of
six options here, not the default, and Voxgig makes none of the other five.

A Handlebars script costs least and loses every correction. Hygen keeps a correction in CI, but
only by declining the whole update. jostraca's merge keeps both, at the price of a merge
baseline to commit and markers to resolve when the two edits change the same lines.

## Write the conventions once

The source names each rule, says whether it applies everywhere, and lists the paths for one that
does not:

```json title="example/conventions.json"
    {
      "id": "api-routes",
      "title": "API routes",
      "description": "Conventions for HTTP route handlers",
      "paths": [
        "src/api/**/*.ts",
        "test/api/**/*.ts"
      ],
```

`emit.mjs` renders it. A rule without `paths` goes into CLAUDE.md, Copilot's repository file and
an always-on Cursor rule. A scoped rule gets the field each tool documents: `globs` for
[Cursor](https://cursor.com/docs/rules), `paths` for a
[Claude Code rule](https://code.claude.com/docs/en/memory), and `applyTo` for a
[Copilot path file](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions).

```js title="emit.mjs"
  for (const rule of source.rules) {
    const cursor = scoped(rule)
      ? `---\ndescription: ${q(rule.description)}\nglobs: ${rule.paths.join(', ')}\nalwaysApply: false\n---\n`
      : `---\ndescription: ${q(rule.description)}\nalwaysApply: true\n---\n`
    files.set(`.cursor/rules/${rule.id}.mdc`, `${cursor}${HEADER}\n\n${section(rule)}`)

    if (scoped(rule)) {
      const paths = rule.paths.map((p) => `  - ${q(p)}`).join('\n')
      files.set(`.claude/rules/${rule.id}.md`, `---\npaths:\n${paths}\n---\n${HEADER}\n\n${section(rule)}`)
      files.set(`.github/instructions/${rule.id}.instructions.md`,
        `---\napplyTo: ${q(rule.paths.join(','))}\n---\n${HEADER}\n\n${section(rule)}`)
    }
  }
```

Print each rendered file with its front matter:

```bash
node preview.mjs
```

```text output
CLAUDE.md
  (no front matter)
.github/copilot-instructions.md
  (no front matter)
.cursor/rules/data.mdc
  description: "How bookshelf-api writes prices, ids and dates"
  alwaysApply: true
.cursor/rules/generated.mdc
  description: "Files in bookshelf-api that a generator writes"
  alwaysApply: true
.cursor/rules/api-routes.mdc
  description: "Conventions for HTTP route handlers"
  globs: src/api/**/*.ts, test/api/**/*.ts
  alwaysApply: false
.claude/rules/api-routes.md
  paths:
    - "src/api/**/*.ts"
    - "test/api/**/*.ts"
.github/instructions/api-routes.instructions.md
  applyTo: "src/api/**/*.ts,test/api/**/*.ts"
```

The three tools write globs three ways. Cursor and Copilot both split on commas, so `validate` refuses a
pattern with a comma, a quote or a line break, along with an id that could leave its folder.[^1]

## Watch what each policy does to a correction

`compare.mjs` runs one scenario per policy: render CLAUDE.md, append a correction, change the
prices line in the source, render again. Hygen runs as a CI job would, with its stdin closed.

```bash
node compare.mjs
```

```text output
policy                      hand correction   source change  second run
Handlebars script           lost              landed         ok
Hygen, prompt unanswered    kept              not applied    exit 0
Hygen, HYGEN_OVERWRITE=1    lost              landed         exit 0
Hygen, unless_exists: true  kept              not applied    exit 0
jostraca, default           lost              landed         ok
jostraca, preserve          in CLAUDE.old.md  landed         ok
jostraca, merge             kept              landed         ok
```

Hygen asks before it overwrites, and an unanswered prompt reads as no, so the run exits 0 with the
file unchanged. Its [`add` operation](https://github.com/jondot/hygen/blob/v6.2.11/src/ops/add.ts)
skips the prompt for `force: true` or `HYGEN_OVERWRITE`, and then overwrites. Only merge keeps the
correction and lands the change.

## Merge the correction, then gate it with check

`sync.mjs` turns merge on and commits the baseline with `control.version: true`. Its `check`
refuses a run that compared anything but the rendered set:

```js title="sync.mjs"
export async function generate(folder, source, { existing = MERGE, control = { version: true } } = {}) {
  const jostraca = Jostraca({ now: NOW, log: quiet, existing, control })
  return jostraca.generate({ folder }, tree(render(source)))
}

export async function check(folder, source) {
  const files = render(source)
  const res = await Jostraca({ now: NOW, log: quiet }).check({ folder }, tree(files))
```

`story.mjs` plays it out in a throwaway git repository, with git given an empty configuration and
a fixed identity:

```bash
node story.mjs
```

```text output
1 generate v1 with control.version: true, commit: 7 files written
  baseline tracked: 7 files under .jostraca/generated
2 hand correction appended to .cursor/rules/data.mdc, commit
3 source v2 changes the prices line, regenerate: merged .cursor/rules/data.mdc .github/copilot-instructions.md CLAUDE.md
  correction kept in .cursor/rules/data.mdc: yes
  prices change landed: 3 of 3 files
  correction in CLAUDE.md: no
4 CI, fresh clone, regenerate, git status: changed .jostraca/jostraca.meta.log
  the same, without .jostraca: clean
  check, which writes nothing: exit 1, drift: content .cursor/rules/data.mdc
5 correction moved into the source as v3, regenerate: merged .github/copilot-instructions.md CLAUDE.md
  correction in: CLAUDE.md .github/copilot-instructions.md .cursor/rules/data.mdc
  check: exit 0
  fresh clone, regenerate, git status: changed .jostraca/jostraca.meta.log
  regenerate again, meta log rewritten: no
```

Step 3 is merge at work, and it is also the sync problem. CLAUDE.md never saw the fix. Step 4 is why the
gate is `check` and not a regenerate followed by `git status`. With the baseline committed, merge
keeps the correction in CI too, so git sees only the meta log. The log records each run's actions,
so the first run in a clone rewrites it even when no file changes. Exclude it and the gate passes
with the copies apart.

`check` renders into an in-memory shadow of the folder, where no existing-file mode fires, as
[`check.ts`](https://github.com/jostraca/jostraca/blob/v0.42.0/ts/src/check.ts) states, and
it never compares `.jostraca/`. Step 5 folds the correction into the source, and all three files
carry it.

## Keep the files beside NSwag and Fern output

NSwag wrote only its client, and Fern's SDK documentation index lists no agent instruction file
among its outputs, so each team runs `sync.mjs` as its own step.
`record.sh` ran NSwag's `openapi2tsclient` twice into a folder holding the seven files:

```bash
cat records/nswag.txt
```

```text output
NSwag 14.8.0.0, openapi2tsclient, two runs into one folder
  files NSwag wrote: src/client.ts
  hand edit in src/client.ts after run 2: lost
  instruction files beside it: 7, unchanged by run 2: yes
  run 2 output identical to run 1: yes
```

NSwag rewrites the one file named by `/output:` and leaves the rest alone. Its header marks the
client as generated, and a rule such as the source's `generated` one tells agents which files a
generator writes:

```ts title="nswag/client.ts"
//----------------------
// <auto-generated>
//     Generated using the NSwag toolchain v14.8.0.0 (NJsonSchema v11.6.2.0 (Newtonsoft.Json v13.0.0.0)) (http://NSwag.org)
// </auto-generated>
//----------------------
```

With GitHub publishing, Fern writes each SDK to a repository of its own. Its
[custom code page](https://buildwithfern.com/learn/sdks/current/overview/custom-code), in the
documentation that configures generation in `sdk-config.yml`, says to list files you own in
`.fernignore`, with `README.md` among its examples. List the instruction files
there and run `sync.mjs` after each regeneration. For edits inside files Fern does generate,
its Replay reapplies your commits by three-way merge in `pull-request` mode.[^2]

## Check it worked

Run the CI gate on the committed example:

```bash
node sync.mjs --check example
```

```text output
checked 7 files
```

It exits 0. The tests cover the front matter, the committed files and their sample notice, the
refused inputs, every row of the policy table, both stories, conflict markers, and the NSwag
record:

```bash
node --test sync.test.mjs
```

```text output
1..13
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

## When it goes wrong

A fresh clone loses the correction. Without `control.version: true`, jostraca's own `.gitignore`
drops the baseline, and merge overwrites a file it has no base for:

```bash
node story.mjs clone
```

```text output
6 without control.version: .jostraca/generated ignored by .jostraca/.gitignore:3:generated
  fresh clone, merge, regenerate v2: unmerged .cursor/rules/data.mdc .github/copilot-instructions.md CLAUDE.md
    correction kept: no
  fresh clone, merge, conflict: 'fail', regenerate v2: throws, .cursor/rules/data.mdc nobase, .github/copilot-instructions.md nobase, CLAUDE.md nobase
    correction kept: yes
```

Commit the baseline, or add `conflict: 'fail'`, which the
[options reference](https://github.com/jostraca/jostraca/blob/v0.42.0/docs/reference-options.md#merge-needs-a-baseline)
lists among the ways a merge stops.

A Cursor rule holds `<<<<<<<` markers. A correction on the line next to a changed one
conflicts, and the markers stay in the file. `check` reports it as drift, which a test shows, so
resolve by hand before you commit.

Backticks arrive as `&#x60;`. A Handlebars double brace HTML-escapes them, as
[`utils.js`](https://github.com/handlebars-lang/handlebars.js/blob/v4.7.10/lib/handlebars/utils.js)
lists. Use triple braces for Markdown.

## When not to do this

Do not generate instruction files that one AGENTS.md can carry. The prerequisite page moves the
shared rules there, and a generator for one file buys a baseline, a meta log, and a CI step.

Do not turn on merge for files nobody edits. jostraca's default overwrite, or the Handlebars
script, writes the same files with nothing to commit under `.jostraca/`, and `check` works the
same under the default.

Skip merge when corrections should never be made in the generated files. Then the default
overwrite and a `check` in CI are the whole policy, because CI fails on any stray edit.

Prefer Fern when people edit the SDK itself. Its Replay reapplies their commits inside generated
files on every regeneration, with no merge code of your own. NSwag suits a .NET team whose
only generated file is the client: its overwrite has nothing to merge or commit.

## Related how-tos

- [Migrate CLAUDE.md and .cursor/rules to AGENTS.md](/howto/migrate-cursor-rules-to-agents-md)

- [Scope agent instructions to one package in a monorepo](/howto/scope-agent-instructions-per-package)

- [Keep generated files out of a coding agent's edits](/howto/keep-generated-files-out-of-agent-edits)

- [Regenerate an SDK with a three-way merge and keep edits](/howto/regenerate-sdk-with-three-way-merge)

- [Pick a jostraca file mode for each generated file type](/howto/pick-a-jostraca-file-mode-per-extension)

## Last verified

Verified 2026-11-22 against Node 22.23.5, jostraca 0.42.0 with `shape` 12.2.5, Hygen 6.2.11 and
Handlebars 4.7.10, each the newest on npm that day. `record.sh` ran NSwag 14.8.0 once on the
ASP.NET Core runtime with .NET's telemetry opt-out set, and its client is committed. Fern was not run: its part comes from its custom
code page, read that day.

[^1]: Cursor's documentation writes `globs` bare, `src/components/**/*.tsx`, while Claude Code
takes a YAML list or a comma-separated string, and Copilot's examples quote one string. Claude Code's
[memory page](https://code.claude.com/docs/en/memory) adds that front matter which does not parse
is ignored, and the rule then loads as if it had no `paths`, at the start of every session.

[^2]: Fern's [documentation pages](https://buildwithfern.com/learn/home/fern-instructions) open
with a note addressed to coding agents, pointing them at a `fern instructions` command that
prints task-scoped workflows. Each Markdown page fetched for this one carried the note before its
title, the custom code page included.