Docs: Add Code Authoring Principles for agents

[valentinpalkovic]

What

Adds a Code Authoring Principles For Agents section to AGENTS.md, distilled from recurring failure modes observed in agent-authored PRs (concretely, the review of #34833).

Why

These six patterns showed up repeatedly and each cost a review round. Writing them into the canonical agent instruction file makes them preventable instead of caught-after-the-fact:

1. Comments as an investigation transcript — internal codes (AC-X2, Probe B), how-I-figured-it-out narrative, fragile cross-file line refs that rot.
2. Encoding environment assumptions without an empirical probe.
3. Over-engineered defensive tests — asserting "internal API not called" instead of behavior.
4. Speculative generality — flexibility for consumers/scenarios that don't exist.

Each is a short rule + one-line rationale, placed just before Maintenance Rules For Agents. Docs-only; no code changes. CLAUDE.md already references AGENTS.md, so no duplication.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a "Code Authoring Principles" subsection with practical guidelines for agent-authored changes: where to put explanatory comments, how to empirically validate environment assumptions, using static checks and boundary assertions for invariants, focusing tests and assertions on public contracts and observable side effects, handling security/migration edge cases with version-scoped compatibility, and preferring deletion or simplicity over speculative generality to improve reliability.

[github-actions]

	Fails
🚫	PR description is missing the mandatory "#### Manual testing" section. Please add it so that reviewers know how to manually test your changes.

Generated by 🚫 dangerJS against d24c7e6

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d1a56d05-c5e5-48cb-93b0-cd422fa86580

📥 Commits

Reviewing files that changed from the base of the PR and between d24c7e6 and 4596fa3.

📒 Files selected for processing (1)

• AGENTS.md

---

📝 Walkthrough

Walkthrough

This PR adds a "Code Authoring Principles" subsection to AGENTS.md documenting recurring agent failure modes and concrete do/don't guidelines for comments, empirical verification of assumptions, contract-focused tests, and preferring deletion/simplicity over speculative generality.

Changes

Agent Code Authoring Principles Documentation

Layer / File(s)

Summary

Code Authoring Principles For Agents AGENTS.md

New section documenting recurring agent failure modes and concrete guidelines for writing agent-authored changes, including what belongs in comments, empirical verification of environment assumptions, static and runtime assertions for invariants, focusing tests on public contracts/side effects, addressing security/migration edge cases with version-scoped compatibility, and preferring deletion/simplicity over speculative generality.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• storybookjs/storybook#33568: Related prior work on AGENTS.md that established the canonical agent instruction source.
• storybookjs/storybook#34181: Also updates AGENTS.md to document repository branch guidance relevant to agent instructions.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}