A teammate adds a line to .cursor/rules/data.mdc saying ratings are whole numbers, because
Cursor kept writing them as decimals. The next run of the script that writes your instruction
files drops the line. CLAUDE.md never had it, Copilot’s file never had it, and the Cursor rule has
lost it too.
What you get
You will end up with one source that renders seven instruction files for three tools, keeps hand corrections, and fails CI until each correction reaches the source. This is for you if several coding agents read your repository.
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 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
first and generate only what is left.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
Fern .fernignore | 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 | 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 | 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 | 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 | 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 | 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:
{
"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, paths for a
Claude Code rule, and applyTo for a
Copilot path file.
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:
node preview.mjs
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.
node compare.mjs
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
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:
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:
node story.mjs
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 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:
cat records/nswag.txt
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:
//----------------------
// <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, 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:
node sync.mjs --check example
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:
node --test sync.test.mjs
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:
node story.mjs clone
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
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 `. A Handlebars double brace HTML-escapes them, as
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
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.
Footnotes
-
Cursor’s documentation writes
globsbare,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 adds that front matter which does not parse is ignored, and the rule then loads as if it had nopaths, at the start of every session. ↩︎ Back to text -
Fern’s documentation pages open with a note addressed to coding agents, pointing them at a
fern instructionscommand that prints task-scoped workflows. Each Markdown page fetched for this one carried the note before its title, the custom code page included. ↩︎ Back to text