AGENTS.md: Add CLAUDE.md symlinks, architecture decisions, and common pitfalls

[youknowriad]

What?

Improves the AGENTS.md setup for coding agents working on Gutenberg.

Why?

Claude Code only reads CLAUDE.md, not AGENTS.md, so it was getting zero project context. The existing AGENTS.md also lacked sections on architectural decisions and common pitfalls, which are high-value for reducing agent mistakes.

How?

1. CLAUDE.md symlinks — Created at root, packages/components/, and packages/ui/ pointing to their respective AGENTS.md files.
2. Architectural decisions section — Covers package layering, block data model, data layer, styles system, and modularity. Links to full architecture docs.
3. Common pitfalls section — Covers lib/compat/ targeting, private APIs in bundled packages, block-editor WP-agnosticism, and @wordpress/scripts genericity.

Testing Instructions

1. Verify symlinks resolve correctly: ls -la CLAUDE.md should show -> AGENTS.md
2. Start a fresh Claude Code session in the repo and confirm it picks up the context from CLAUDE.md
3. Review the new sections in AGENTS.md for accuracy

🤖 Generated with Claude Code

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: youknowriad <youknowriad@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: mtias <matveb@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[aduth]

Makes sense; I've seen similar setups in other projects 👍

[t-hamano]

Symlinks are a bit tricky on Windows host OS. Git's default configuration doesn't work properly with symlinks.

Instead, how about adding @AGENTS.md to CLAUDE.md? This seems to be the official way to do it. Many people have reported this format working correctly in this issue. anthropics/claude-code#6235 (comment)

[t-hamano]

LGTM 👍

[justlevine]

Did anyone here eval either the CLAUDE.md file or the ai-generated additions to the AGENTS.md file before merging this?

[tellthemachines]

I think the contents of that AGENTS.md would be helpful to humans, not only to AI. Nothing in there is AI-specific, and I for one would have benefited enormously from reading these clear cut guidelines when I started contributing to the project. Some of that stuff took me quite a while to figure out 😅

So what I'd like to propose is adding these to the README.md, either instead of AGENTS, because agents already do read readmes (and we could reserve AGENTS for anything AI-specific that might need adding later) or duplicating it across both files.

I know the README already has links to extensive docs, but those are very fluffy in style so it helps a lot to have concise guidelines too.