Add AI Agent rules

[ernestognw]

Fixes #????

PR Checklist

• Tests
• Documentation
• Changeset entry (run npx changeset add)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9cec98c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Walkthrough

This pull request adds four new documentation files that establish comprehensive guidelines for OpenZeppelin contract development. The additions include API design rules, Solidity style conventions, testing patterns, and a centralized AI-assisted development practices reference. The files codify patterns for function visibility, parameter types, override points, error handling, formal verification approaches, and testing strategies. No functional code changes are introduced.

Possibly related PRs

• OpenZeppelin/openzeppelin-contracts#5794: Implements solhint rule changes that enforce API-design conventions on public/external visibility and virtual function marking, directly corresponding to the guidelines introduced in this PR.

Suggested labels

ignore-changeset

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Add AI Agent rules' is vague and generic, using non-descriptive terms that don't clearly convey what specific rules or changes are being added.	Provide a more specific title that identifies the key rules being added, such as 'Add AI Agent design guidelines for library APIs and Solidity patterns' or similar descriptive phrasing.
Description check	❓ Inconclusive	The description is largely a template with unchecked checklist items and no substantive explanation of the changes, though it acknowledges the addition of AI Agent rules.	Fill in the PR description with details about the purpose of the AI Agent rules, what guidelines are covered, and why they are being added to the codebase.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

📝 Coding Plan

• Generate coding plan for human review comments

---

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

Tip

You can validate your CodeRabbit configuration file in your editor.

If your editor has YAML language server, you can enable auto-completion and validation by adding # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json at the top of your CodeRabbit configuration file.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

AGENTS.md (1)

333-333: Align Certora CI label guidance with .cursor/rules/test-patterns.mdc

Line 333 lists only formal-verification, while the other rules file also documents formal-verification-force-all. Keep both docs in sync to avoid workflow confusion.

Suggested patch

-[Certora](https://certora.com) specs live in `fv/specs/` as `.conf` + `.spec` pairs. The CI job runs on PRs labeled `formal-verification`. To run locally, apply harness patches first (`make -C fv apply`), then `node fv/run.js <SpecName>`. Use Certora for properties too complex for Halmos, or when deeper state machine coverage is needed. Requires a `CERTORAKEY`.
+[Certora](https://certora.com) specs live in `fv/specs/` as `.conf` + `.spec` pairs. The CI job runs on PRs labeled `formal-verification` or `formal-verification-force-all`. To run locally, apply harness patches first (`make -C fv apply`), then `node fv/run.js <SpecName>`. Use Certora for properties too complex for Halmos, or when deeper state machine coverage is needed. Requires a `CERTORAKEY`.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` at line 333, Update the label guidance in AGENTS.md so it lists
both CI labels used by the rules file: add "formal-verification-force-all"
alongside the existing "formal-verification" string in the sentence that
describes which PRs the Certora job runs on; cross-check against
.cursor/rules/test-patterns.mdc to ensure the two labels match exactly and
update the documentation sentence to mention both labels.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.cursor/rules/test-patterns.mdc:
- Line 32: The phrase "re-declaring" is flagged by codespell; locate the
occurrence of "re-declaring" in the test-patterns documentation and replace it
with "redeclaring" (preserving surrounding punctuation/formatting) so the
spelling check passes.

In `@AGENTS.md`:
- Line 317: Update the spelling of “re-declaring” to “redeclaring” in the
sentence that reads "Even within a manual mock, call the auto-generated `$_`
functions rather than re-declaring the same internal exposure." (referencing the
phrase containing the auto-generated `$_` functions) so the documentation uses
the correct term "redeclaring".

---

Nitpick comments:
In `@AGENTS.md`:
- Line 333: Update the label guidance in AGENTS.md so it lists both CI labels
used by the rules file: add "formal-verification-force-all" alongside the
existing "formal-verification" string in the sentence that describes which PRs
the Certora job runs on; cross-check against .cursor/rules/test-patterns.mdc to
ensure the two labels match exactly and update the documentation sentence to
mention both labels.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 3bc018ef-fb97-4e72-9fc7-a03930beb160

📥 Commits

Reviewing files that changed from the base of the PR and between 45f032d and 8353d96.

📒 Files selected for processing (4)

• .cursor/rules/api-design.mdc
• .cursor/rules/solidity-style.mdc
• .cursor/rules/test-patterns.mdc
• AGENTS.md