docs: expand agent guidance with directory context and CLAUDE links - #5022
Conversation
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughRepository documentation expanded with hierarchical AGENTS.md guidelines for root, client, includes (backend), agentic-commerce, and e2e layers; CLAUDE.md pointers added. A new AI readability audit doc and changelog/readme entries were added. No executable code or public APIs changed. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
daledupreez
left a comment
daledupreez
left a comment
There was a problem hiding this comment.
Thanks for updating the files, @ebinnion!
I have some minor suggestions to improve the files. Maybe the only thing we would want to add would be explicit instructions for adding changelog entries to changelog.txt and readme.txt, possibly in conjunction with a dedicated script that can take the entry as arguments or piped input. (Our current npm run changelog script is intended as an interactive developer tool.)
| - **CRITICAL:** Treat `test:e2e-setup` against `--base_url` as destructive setup for a target site. Use only disposable/staging environments. | ||
| - **CRITICAL:** Do not commit secrets from `tests/e2e/config/local.env`. | ||
| - **CRITICAL:** Keep tests deterministic; avoid unnecessary sleeps and flaky selectors. | ||
| - **CRITICAL:** For Stripe iframe interactions, do not rely on `networkidle`; use deterministic field readiness/visibility checks. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (2)
AGENTS.md (2)
66-77: Add a language to the fenced code block.Markdownlint flags this block without a language; add
text(orplaintext) to keep lint clean.🧩 Proposed fix
-``` +```text WC_Payment_Gateway_CC (WooCommerce) └── WC_Stripe_Payment_Gateway (abstract) └── WC_Stripe_UPE_Payment_Gateway └── Uses WC_Stripe_UPE_Payment_Method subclasses WC_Stripe_UPE_Payment_Method (abstract) ├── WC_Stripe_UPE_Payment_Method_CC ├── WC_Stripe_UPE_Payment_Method_Klarna ├── WC_Stripe_UPE_Payment_Method_SEPA └── ... (20+ methods)
3-9: Document the AI agent implementations and capabilities.This root guidance should explicitly list which AI agents are supported and what they can/can’t do, per the repo learning. Consider a short section near the top.
🧭 Proposed addition
This file provides guidance to coding agents working in this repository. +## Supported AI Agents and Capabilities + +- List the agent implementations used in this repo (e.g., ChatGPT, Claude, Copilot, etc.). +- Summarize capability boundaries (code review, refactoring, doc updates, test guidance, etc.). +- Note any explicit limitations or disallowed actions. + ## Project OverviewBased on learnings: "Document AI agent implementations and their capabilities in AGENTS.md".
I wonder if this should be a pre-commit hook instead? |
Mayisha
left a comment
Mayisha
left a comment
There was a problem hiding this comment.
Thanks for adding these. Looks good to me 🎉
malithsen
left a comment
malithsen
left a comment
There was a problem hiding this comment.
Looks good to me. Thanks for the improvements!
|
|
||
| | Task | Command | Notes | | ||
| | --- | --- | --- | | ||
| | Install dependencies | `composer install && npm install` | Runs Composer install and npm install, which then installs all dependencies. | |
There was a problem hiding this comment.
nit: Running npm install should be enough, as it has a postinstall step that runs composer install
04aeb12 to
e3f43e3
Compare
Co-authored-by: daledupreez <dale.du.preez@automattic.com>
Co-authored-by: daledupreez <dale.du.preez@automattic.com>
Co-authored-by: daledupreez <dale.du.preez@automattic.com>
e3f43e3 to
9b9778b
Compare
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
Verify each finding against the current code and only fix it if needed.
In `@client/CLAUDE.md`:
- Line 1: Add a top-level H1 to CLAUDE.md (e.g., "# CLAUDE") or update
markdownlint config to exclude CLAUDE.md from the MD041 rule; specifically
either insert an H1 as the first line of the file to satisfy first-line-h1, or
add a pattern for CLAUDE.md to the markdownlint rules (e.g., with "MD041": false
for matching files) so the single-line pointer format remains allowed across the
CLAUDE.md files.
In `@includes/AGENTS.md`:
- Line 69: Fix the hyphenation in the phrase "recurring-payment capable methods"
by changing it to the compound adjective "recurring-payment-capable methods"
(and update any other identical occurrences in the same document), ensuring
consistency in AGENTS.md where the phrase appears.
In `@includes/CLAUDE.md`:
- Line 1: CLAUDE.md currently contains only the single-line pointer
"@AGENTS.md", which triggers markdownlint MD041 (first-line-h1); either add a
top-level heading to CLAUDE.md (e.g., "# CLAUDE" followed by the pointer) to
satisfy the rule, or update the markdownlint config to exclude CLAUDE.md (or the
matching glob) from MD041 checks; locate the file CLAUDE.md and choose one of
these fixes and commit the change so the linter no longer reports MD041.
In `@tests/e2e/CLAUDE.md`:
- Line 1: Add a markdownlint exception so CLAUDE.md files with the single-line
pointer "@AGENTS.md" do not trigger MD041: update the linter config
(coderabbit.markdownlint-cli2.jsonc) to add a rule override for MD041 that
ignores files matching the CLAUDE.md pattern (or lines that exactly equal
"@AGENTS.md"), ensuring the linter rule is suppressed for those files instead of
modifying CLAUDE.md; reference the MD041 rule and the CLAUDE.md/@AGENTS.md
pattern when making the change.
4 participants
Changes proposed in this Pull Request:
This PR improves AI-agent guidance for this repository and makes
CLAUDE.mdusage consistent with current guidance (@AGENTS.mdfile references, not symlinks).What changed
Updated root AGENTS.md after recent guidance. Add some AGENTS.md in subdirectories. Codex also made suggestons after reviewing past 6 months of commits and PRs.
Why this is needed
Sets a new baseline for AI context following Field Guide guidance.
How this could break
Mitigations
AGENTS.md.AGENTS.mdis easily changeable.Testing instructions
Review guidance and verify that it makes sense.
Changelog entry
Changelog Entry Comment
Comment
This PR only updates internal AI guidance documentation (
AGENTS.md/CLAUDE.md) and adds an internal audit doc. It does not change plugin runtime behavior or user-facing functionality.Post merge