itwinjs-core
AGENTS.md742 starsChanged 4 months agoMITView on GitHub
Read only the references relevant to the task: When editing docs/changehistory/NextVersion.md: Before committing work that will be pushed, apply only the checks required by the final diff:
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- api-promotionSkill
- backport-resolutionSkill
- cve-remediationSkill
- merge-conflict-resolvingSkill
- pr-review-considerationsSkill
- test-suite-refactoringSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
17 rules. About 0 are common, 9 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 5
Read only the references relevant to the task:
- Distinctive: line 19
Do not push, create pull requests, or update GitHub issues unless asked.
- Distinctive: line 20
Use non-interactive Git. Do not discard changes without explicit approval.
- Very specific: line 21
Use rush from the repository root and rushx in a package.
- Very specific: line 22
Use relative imports within a package.
- Very specific: line 23
Import Node.js built-ins with the node: prefix (node:fs, node:path), not bare specifiers.
- Very specific: line 24
Keep backend and native dependencies out of core/common and core/frontend.
- Distinctive: line 26
Do not change an existing exported API or RPC signature without a compatibility plan.
- Very specific: line 27
Keep private implementation in src/internal/.
- Distinctive: line 31
Check the release tag and API report before changing an exported symbol.
- Very specific: line 32
Do not break a @public API outside a major-version migration plan.
- Very specific: line 34
Do not hand-write dates in @deprecated tags.
- Distinctive: line 46
Before committing work that will be pushed, apply only the checks required by the final diff:
- Distinctive: line 57
Commit intentional API reports and change files with the implementation.
- Distinctive: line 58
Treat a runtime or logical behavior change as breaking even when existing consumer code still compiles.
- Distinctive: line 59
If a required check is blocked, state the command and blocker.
- Very specific: line 60
Do not commit .only tests.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
iTwin.js Core Agent Instructions
Read the source of truth
Read only the references relevant to the task:
| Need | Source |
| Setup, Rush commands, contribution and PR workflow | CONTRIBUTING.md |
| Package scripts, test runner, local conventions | Affected package's package.json, tests, and configuration |
| Project graph and publish status | rush.json |
| Public API contract | common/api/<package>.api.md API report |
| Lockstep version policy | common/config/rush/version-policies.json |
| CI behavior | .github/workflows/ and common/config/azure-pipelines/ |
Boundaries
- Change only files relevant to the task. Preserve unrelated changes.
- Do not push, create pull requests, or update GitHub issues unless asked.
- Use non-interactive Git. Do not discard changes without explicit approval.
- Use
rushfrom the repository root andrushxin a package. Do not usenpm install,pnpm install, or editpnpm-lock.yamldirectly. - Use relative imports within a package. Do not self-import through
@itwin/*. - Import Node.js built-ins with the
node:prefix (node:fs,node:path), not bare specifiers. - Keep backend and native dependencies out of
core/commonandcore/frontend. - Frontend code uses
IModelConnectionand its managers, not new direct RPC clients. - Do not change an existing exported API or RPC signature without a compatibility plan.
- Keep private implementation in
src/internal/. Cross-package internals belong in the owning package'ssrc/internal/cross-package.ts.
Public APIs
- Check the release tag and API report before changing an exported symbol.
- Do not break a
@publicAPI outside a major-version migration plan. Prefer an additive API and deprecation. - Give every new export a release tag.
- Do not hand-write dates in
@deprecatedtags.
Change notes
When editing docs/changehistory/NextVersion.md:
- List the allowed
##sections withnode .github/workflows/automation-scripts/check-nextversion.mjs --sections. Add each entry as a###heading under the section it belongs to, reusing that section when it already exists, and add it to the table of contents. - If the table of contents is missing, create it below
# NextVersionand before the first##section, following past release notes such asdocs/changehistory/5.14.0.md. Use a nested Markdown list of heading links:NextVersionat the top level,##sections indented two spaces,###entries indented four spaces, and deeper headings nested accordingly. Include all existing headings in document order, not just the entry being added. A passing validator does not excuse a missing table of contents. - Done when
node .github/workflows/automation-scripts/check-nextversion.mjspasses. It checks the whole file, so fix any problems already there in the same change, and tell the user what you fixed and why, since it is outside the task you were given.
Before remote work
Before committing work that will be pushed, apply only the checks required by the final diff:
| Final diff includes | Required before push |
| Production code | Targeted build, tests, and affected-package lint |
| Exported API, entry point, or release tag | rush clean && rush build && rush extract-api; review API report changes |
| Published package | Rush change file with "type": "none"; use an empty comment when behavior is unchanged |
| Breaking API or behavior change, or significant feature | Migration guidance in docs/changehistory/NextVersion.md |
| External dependency manifest | rush check and the Rush update flow |
| Documentation extract or package docs | Relevant rushx docs build when available |
- Commit intentional API reports and change files with the implementation.
- Treat a runtime or logical behavior change as breaking even when existing consumer code still compiles.
- If a required check is blocked, state the command and blocker.
- Do not commit
.onlytests.
Manual offline tests
AI assistants require network access and cannot work while this machine is offline. Do not launch or supervise a test requiring machine-wide disconnection through assistant tools. While still online, give the operator the complete commands, expected results, cancellation steps, and manual network-restoration instructions, then end your turn before disconnection. Resume work only after the operator confirms networking is restored. For Vertical CRS acceptance, follow the Vertical CRS testing guide.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

