docs(agents): add CI format check guidance to AGENTS and cursor rules

[Lotte-Verheyden]

Summary

The Prettier format check (pnpm run format:check) is the CI job that most often fails on the first push of a PR — agents (and humans) frequently forget to run pnpm run format after editing MDX, TSX, or JSON files.

This PR adds explicit guidance to the agent instruction files so that new PRs are more likely to pass CI on the first try:

• .agents/AGENTS.md (canonical, also surfaced as CLAUDE.md and AGENTS.md via symlinks): adds workflow rule Add Level-and-statusmessage to sdk docs #5 calling out pnpm run format, plus a new "Passing CI checks on the first try" section documenting all three required checks (format, check_h1, build-and-check-links/check-sitemap-links), which file extensions Prettier formats, and which paths are excluded via .prettierignore.
• .agents/cursor/rules/_general-rules.mdc: adds a short "Before committing or opening a PR" section with the same format/H1 guidance for Cursor agents.

Greptile Summary

This PR adds explicit CI guidance to the agent instruction files (AGENTS.md and _general-rules.mdc) to help agents pass CI on the first PR push, targeting the most common failure: the Prettier format check.

• .agents/AGENTS.md: adds workflow rule Add Level-and-statusmessage to sdk docs #5 emphasising pnpm run format, and a new "Passing CI checks on the first try" section covering all three required CI jobs (format, check_h1, build-and-check-links/check-sitemap-links) with accurate details drawn from .prettierrc.json and .prettierignore.
• .agents/cursor/rules/_general-rules.mdc: adds a compact "Before committing or opening a PR" section surfacing the same format/H1 guidance for Cursor agents.

Confidence Score: 4/5

Safe to merge — documentation-only changes to agent instruction files with no runtime impact.

The changes are accurate guidance against the real repo config, with one minor prose imprecision: notebooks are described as excluded via .prettierignore when in practice they are simply skipped by Prettier because no .ipynb parser is registered. The .prettierrc.json values and .prettierignore path patterns are all verified correct.

.agents/AGENTS.md line 67 and .agents/cursor/rules/_general-rules.mdc line 23 both contain the notebook/.prettierignore imprecision.

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
.agents/AGENTS.md:67
**Notebooks described as `.prettierignore`-listed, but they aren't**

The `.prettierignore` file does not contain any entry for `cookbook/` or `*.ipynb`. The source notebooks are skipped by Prettier because Prettier has no built-in parser for `.ipynb`, not because they appear in `.prettierignore`. An agent reading this guidance might incorrectly assume `cookbook/` is explicitly excluded, which could cause confusion if e.g., `.md` files were ever placed in `cookbook/`. The description for `_general-rules.mdc` line 23 has the same inaccuracy.

A more accurate phrasing would be something like: "Prettier does **not** format files matched by `.prettierignore` (generated cookbook docs in `content/guides/cookbook/**`, `content/workshop/**`, lockfiles, generated files in `public/`, etc.); source notebooks (`.ipynb`) are also skipped because Prettier has no parser for them."

_{Reviews (1): Last reviewed commit: "docs(agents): add CI format check guidan..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[github-actions]

@claude review

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-docs	Ready	Preview, Comment	May 28, 2026 9:17pm

[claude]

LGTM, documentation-only update to agent instruction files.

Extended reasoning...

Overview

This PR adds CI guidance to two agent instruction files: .agents/AGENTS.md and .agents/cursor/rules/_general-rules.mdc. The additions document the three CI checks (Prettier format, H1 heading, build+links) with emphasis on running pnpm run format before committing — the most common first-push CI failure.

Security risks

None. This is documentation-only content in agent instruction files. No code, configuration, build, or deploy logic is modified.

Level of scrutiny

Minimal scrutiny is appropriate. This PR touches only Markdown/MDC instruction files consumed by agents (Claude, Cursor). There is no runtime or build impact, and the guidance accurately reflects the existing CI jobs and .prettierrc.json/.prettierignore configuration described in the surrounding repo.

Other factors

The content is internally consistent between the two files, accurately describes the existing CI workflow, and the file extensions/ignored paths match the repo's actual Prettier configuration. Small, self-contained, and clearly intended.

[claude]

LGTM — documentation-only update to agent instruction files; the inline nits about phrasing are minor and don't block merge.

Extended reasoning...

Overview

This PR adds CI guidance to two agent instruction files: .agents/AGENTS.md (the canonical file surfaced as both CLAUDE.md and AGENTS.md via symlinks) and .agents/cursor/rules/_general-rules.mdc (for Cursor agents). The content explains the three CI checks — Prettier format, H1 heading check, and build/link checks — that agents most commonly miss before pushing, and tells them to run pnpm run format first. No runtime code is touched.

Security risks

None. These are markdown instruction files for agents; they have no effect on the deployed site, build pipeline, or any user-facing behavior.

Level of scrutiny

Very low. Documentation-only, no executable code paths, no config changes that affect CI itself. The blast radius is limited to how well future agents follow the guidance, which is correctable in subsequent PRs at any time.

Other factors

The bug hunter and Greptile both flagged the same paragraph for two prose imprecisions: .prettierignore doesn't actually contain JSON entries under public/ (it has MD/TXT/XML), and the 'only a notebook' example for .prettierignore'd files contradicts the paragraph's own carve-out that notebooks are skipped via a different mechanism. Both findings are accurate and nit-level — they don't change what an agent will actually do (run pnpm run format), only the precision of the categorization. The PR is otherwise accurate against .prettierrc.json and the CI job names. Safe to approve; the author can take or leave the inline suggestions.

[claude]

Prior feedback addressed in follow-up commits; remaining inline finding is a docs-only nit.

Extended reasoning...

Overview

Docs-only PR touching two agent-instruction files (.agents/AGENTS.md and .agents/cursor/rules/_general-rules.mdc). Adds a workflow rule plus a "Passing CI checks on the first try" section documenting the Prettier format, H1, and build/link CI jobs. No runtime code or config is changed.

Security risks

None. These files are read by AI coding assistants as guidance and are not loaded by any runtime path. No new dependencies, no secrets, no public-facing surface.

Level of scrutiny

Low. Agent-instruction documentation is essentially a README for coding agents — incorrect phrasing degrades guidance quality but cannot break the site, leak data, or affect users. The factual claims about Prettier extensions, .prettierignore, and CI jobs are verifiable against repo config and were largely confirmed accurate.

Other factors

The author has been responsive to prior review feedback: my earlier comment flagged two imprecisions (the public/ exclusion phrasing and the notebook-as-.prettierignore'd example) and both were fixed in follow-up commits a98ed54 and b115caa, aligning AGENTS.md with the sibling cursor-rules wording. The remaining inline finding on this run (.mjs/.cjs missing from the extension enumeration) is a legitimate but minor nit that does not block merging — the doc also tells agents "when in doubt, just run pnpm run format", which mitigates the closed-list gap. PR is labeled auto-merge.

[claude]

All prior review feedback (mine and Greptile's) has been incorporated — docs-only change to agent instruction files.

Extended reasoning...

Overview

This PR adds CI guidance to .agents/AGENTS.md and .agents/cursor/rules/_general-rules.mdc to help agents pass the Prettier format check, H1 check, and link/sitemap checks on the first push. It's documentation-only, affecting agent instruction files surfaced as CLAUDE.md / AGENTS.md via symlinks.

Security risks

None. No runtime code, no build configuration, no auth/permissions. The only consumer is agent tooling that reads markdown guidance.

Level of scrutiny

Low — this is markdown content in agent instruction files. The accuracy bar is correctness of the documented commands, paths, and extensions; the worst-case failure is an agent following slightly off guidance, not a production issue.

Other factors

My two prior review comments and Greptile's inline comment all flagged accuracy issues in the new Prettier section. All three have been addressed in the latest commits: public/ exclusions now use the accurate "generated assets in public/" phrasing, the notebook-vs-.prettierignore distinction is preserved consistently in both the explanatory paragraph and the example bullet, and .mjs/.cjs are included in the extension list in both files (matching what Prettier actually formats and what next.config.mjs requires). Nothing outstanding remains.