How-to › Expose your API to agents

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.

Audience
Platform team
Level
intermediate
Topic
Write agent skills and instruction files
Languages
TypeScript
Verified

Read first: Migrate CLAUDE.md and .cursor/rules to AGENTS.md

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Fern .fernignoreA Fern SDK repository that also carries instruction filesFern leaves listed files alone, so syncing them stays your own stepYour SDK repository is not written by Fern
hand-maintained copiesOne tool, or two files that rarely changeEvery fix is made once per file, and the copies part ways unnoticedA third format arrives, or the files change monthly
Handlebars template scriptA small script you own end to endOverwrites the file whole, and double braces escape Markdown backticksPeople correct the generated files by hand
HygenScaffolding files once, with a person at the terminalIn CI the overwrite prompt goes unanswered, so the source change never landsThe files must follow the source on every run
jostraca merge and checkGenerated files that people also correct by handA baseline to commit, a meta log that churns, and conflict markers to resolveNobody edits the files, so overwriting is enough
NSwagA C# or TypeScript client generated beside the instruction filesWrites the client only, so the instruction files need a separate generatorYou 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 &#x60;. 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.

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

  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 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. ↩︎ Back to text

  2. Fern’s documentation pages 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. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.