chore: add ai agent guidance

[maribethb]

The basics

• I validated my changes

The details

Resolves

Proposed Changes

• Adds a couple of AGENTS.md files: one top level with repo-wide info, plus links to the ones for the individual sub-areas of core/docs/plugins
• Add symlinks of these at CLAUDE.md (note that these symlinks won't work on windows but claude can probably figure out what to do there)
• Update copilot-instructions with updated instructions when people request copilot as a reviewer
• Update CONTRIBUTING.md to point to the in-repo source of the docs, because agents often read that file but won't go on the internet to read the site it points to.
• add .claude/ to the gitignore and prettierignore

Reason for Changes

• Tries to address some of the common mistakes AI agents make when writing or reviewing code in this repository. This includes breaking changes, matching old style that we don't use anymore, doing translations wrong, writing an entire civilization's worth of history into the tsdoc for a changed method, and assuming this repo is a fork of google/blockly.

Test Coverage

n/a

Documentation

this is that, sort of

Additional Information

Claude generated all these files, I hand-reviewed and made or requested changes where it missed some nuance.

@gonfunko requesting you specifically because i know you had some ideas and i'm not sure if i missed any of them
@zspriggs adding as fyi because this is adjacent to some of the things you're working on, feel free to add feedback

[gonfunko]

A few comments:

• I'm not sure how much value the available npm command sections add; IME LLMs seem to find those fine.
• We should add something on where we do and don't use the Canadian spellings of things
• I'd like some guidance to keep code changes minimal and prefer small PRs, and especially to avoid verbose infrastructure and tooling implementations and comments in favor of invoking common command line tools. Code is the enemy; it's where bugs live, and the less of it that we have the better.
• Something about us being very skeptical of dependencies, especially direct dependencies
• Don't propagate existing antipatterns in the interest of maintaining consistency
• Prefer fixing root causes rather than creating lists of exceptions or special-casing particular files or implementations
• Accessibility is important to the project; make sure that changes do not introduce regressions, and that new additions work well for screenreader and keyboard users
• Don't use the DOM/class/CSS/transform methods from dom.ts; they exist for backwards compatibility, but vanilla JS should be used for new code. createSvgElement is allowable. DO use aria.ts for all new code.
• Prefer ? or guards vs ! for Typescript null checks
• Don't remove or revert user-added debugging code during a session unless preparing a final commit/PR.
• New tests should be written in Typescript!
• Always take a final pass for opportunities to condense or simplify changes, and ensure that all changes are still needed and relevant, and that comments are accurate.

[gonfunko]

Maybe specify "RaspberryPiFoundation/blockly" so that "this repository" doesn't carry over to forks

[gonfunko]

I'd drop the "avoid" here, as it kind of counteracts the "prefer"

[gonfunko]

License

[gonfunko]

rendered_connection.ts might be worth a mention

[maribethb]

Thanks, I'll fold those suggestions in.

re: script commands, claude really seems to want them and I do think explicitly telling it to just run the mocha tests in node for quick verification is better because it does often try to run all of npm run test too often when there is no conceivable need to run the generator goldens for example

[gonfunko]

Sounds good, and yeah agreed on the guidance to just run the node tests most of the time.