mirror of
https://github.com/langchain-ai/docs.git
synced 2026-08-27 02:41:59 -04:00
Lauren Hirata Singh
392db4cdf8
## Why
`.cursorrules` and `.github/copilot-instructions.md` were
hand-maintained subsets of `CLAUDE.md`. Comparing headings, the subsets
dropped 26 of them, including the whole style guide and the structure
conventions:
```console
$ diff <(grep -E "^#{2,3} " CLAUDE.md) <(grep -E "^#{2,3} " .cursorrules) | grep '^<'
< ## Style guide
< ### Structure conventions
< ### Model references
< ### Release stage names
< ### Product and feature name capitalization
< ## Components
< ## Mermaid diagram styling
...
```
So a contributor on Cursor or Copilot got the repository layout and none
of the rules about how the prose should read.
They are also stale. Both last changed **2026-05-13**; `CLAUDE.md` last
changed **2026-07-22**. The product and feature name capitalization rule
added in #5036 never reached either file.
## What changed
Rather than copying all 398 lines into every file, the style guide is
mirrored into two path-scoped rule files, which is each tool's native
way to attach rules to file patterns:
| File | Scoping | Loads when |
|------|---------|-----------|
| `.cursor/rules/docs-style.mdc` | `globs: src/**/*.mdx` | Editing a
page under `src/` |
| `.github/instructions/docs-style.instructions.md` | `applyTo:
"src/**/*.mdx"` | Editing a page under `src/` |
Both bodies are byte-identical to lines 219 to 309 of `CLAUDE.md`,
verified with `diff`. The scoping matches 2,275 MDX files under `src/`.
`.cursorrules` and `copilot-instructions.md` are trimmed to what applies
to every task: critical rules, repository structure, quick reference,
frontmatter, syntax, and a pointer to `AGENTS.md`. Both are 68 lines and
differ only in the line naming their own style rule file.
The sync banner at the top of `CLAUDE.md` and `AGENTS.md` now names all
four derived files and says which sections feed each, so the next style
guide edit updates them in the same PR.
## Removed on purpose
The trimmed files no longer carry a navigation map. The one they had was
wrong: it listed the LangSmith "Configure app" tab and Fleet's "Tools
and integrations" group, neither of which exists now. `AGENTS.md` has
the current map, and the trimmed files point at it. Restating it in four
places is what produced the staleness in the first place.
## Review notes
Two things worth a second opinion:
1. **The cut line.** Only the style guide is path-scoped. Frontmatter,
components, and Mermaid styling rules still live only in `CLAUDE.md` and
`AGENTS.md`, though they are just as relevant when editing an MDX file.
Extending the scoped files to cover them is a reasonable follow-up; it
was left out to keep this reviewable.
2. **Sync is still manual.** The banner tells a human what to update. It
does not enforce anything. A CI drift check would, and is the obvious
next step if this pattern holds.
No page content is touched, so there is nothing to preview.
Drafted with Claude Code.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>