Create agents.md

Author: Zhang-JiahangH

agents.md

@@ -0,0 +1,85 @@
+# AGENTS.md
+
+This file is the operating manual for AI coding agents (Cursor, Claude Code, Codex, Aider, Devin, and others) working in this repository. Read this file before making changes.
+
+Human contributors may also find it useful. It is written in direct, imperative style on purpose.
+
+## What this repo is
+
+`react-virtualized-diff` is a React component for rendering large code/text diffs without freezing the browser. The published library lives in `packages/react/`. The repo is a **pnpm workspace monorepo** — use `pnpm`, not `npm` or `yarn`.
+
+Public documentation lives in `README.md` and `llms.txt`. User-facing API changes must update both.
+
+## Project structure
+
+```
+packages/react/        # published npm package source — this is where most work happens
+apps/demo/             # Vite demo app, used for manual testing and the hosted live demo
+apps/benchmark/        # benchmark harness that produces benchmark-results/results.md
+benchmark-results/     # committed benchmark output, reviewed in PRs when perf changes
+.github/workflows/     # CI: runs lint + build
+scripts/               # repo-level tooling
+```
+
+The published surface area is exactly what `packages/react/` exports. Nothing under `apps/` ships to npm.
+
+## Setup
+
+```
+pnpm install
+```
+
+Node and pnpm are required. Do not run `npm install` or `yarn` — it will corrupt the workspace lockfile.
+
+## Commands
+
+All commands run from the repo root unless noted.
+
+- `pnpm dev` — start the Vite demo app against the local package source (watches and reloads)
+- `pnpm build` — build `packages/react/`
+- `pnpm test` — run the test suite
+- `pnpm lint` — run lint checks
+- `pnpm benchmark` — run the benchmark harness; updates `benchmark-results/results.md`
+
+## Before opening a PR
+
+All of these must pass locally:
+
+1. `pnpm lint` is clean
+2. `pnpm build` succeeds
+3. `pnpm test` passes
+4. `CHANGELOG.md` has an entry for the change
+
+CI also runs `pnpm lint` and `pnpm build`. Tests and CHANGELOG are checked by reviewers.
+
+## Code-change priorities
+
+These are in priority order. If they conflict, earlier rules win.
+
+1. **Default scope is `packages/react/`.** Make changes here unless there is a direct reason not to. If a change requires touching `apps/demo/`, `apps/benchmark/`, or repo-level config, call that out explicitly in the PR description and explain why.
+
+2. **Public API changes must update `README.md` and `llms.txt`.** The list of props in both files is part of the public contract. Renaming a prop, changing a default, adding a prop, or removing a prop requires updating both docs in the same PR. `llms.txt` is how AI coding agents in downstream projects learn this library — keeping it accurate is load-bearing.
+
+3. **Performance-sensitive changes require a benchmark comparison.** "Performance-sensitive" includes anything in the render path, diff computation, virtual list integration, or memoization boundaries. Run `pnpm benchmark` on `main` first, then on your branch, and paste both relevant rows into the PR description. Do not rely on the committed `results.md` alone — it is a snapshot and may be stale.
+
+4. **Every change gets a `CHANGELOG.md` entry.** Even small fixes. Use the existing format in that file. Entries do not need to be long — one sentence is fine — but they must exist.
+
+## Code style
+
+- TypeScript throughout. Strict mode is on — do not introduce `any` to silence type errors. If a type is genuinely unknowable, use `unknown` and narrow.
+- Formatting is controlled by `.prettierrc` and `.editorconfig`. Do not hand-adjust whitespace; run the formatter.
+- Prefer named exports from `packages/react/` entry points.
+- React hooks follow standard rules (exhaustive deps unless justified with a comment).
+
+## Things not to do without explicit instruction
+
+- Do not commit `dist/` or other build output. `.gitignore` covers this; double-check before pushing.
+- Do not hand-edit `pnpm-lock.yaml`. If a dependency needs to change, use `pnpm add` / `pnpm remove` and commit the lockfile update.
+- Do not add new runtime dependencies without flagging the addition in the PR description. Bundle size is part of the library's value.
+- Do not bump the version in any `package.json`. Releases are managed separately.
+- Do not modify `benchmark-results/results.md` by hand — it is generated by `pnpm benchmark`.
+- Do not rewrite the "Why react-virtualized-diff" section of `README.md` or the framing of the benchmark without reviewer discussion. Those sections reflect the project's positioning.
+
+## When in doubt
+
+Open a draft PR with a clear description of what you tried and why. The maintainer (@Zhang-JiahangH) would rather see an honest draft than a polished PR that made the wrong call.