docs: add CLAUDE.md agent guidelines for auth0-spa-js#1651
Draft
sanchitmehtagit wants to merge 8 commits into
Draft
docs: add CLAUDE.md agent guidelines for auth0-spa-js#1651sanchitmehtagit wants to merge 8 commits into
sanchitmehtagit wants to merge 8 commits into
Conversation
Add a canonical CLAUDE.md as the single source of truth for AI coding agents (persona, commands, testing conventions, three-tier boundaries, browser security notes, telemetry via the Auth0-Client header, and the MIGRATION_GUIDE.md rule), and repoint AGENTS.md at @CLAUDE.md so non-Claude agents share the same guidance. No docs/ offload — docs/ holds generated TypeDoc output and the SDK is a lean single package, so the file stays inline.
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAGENTS.md now points to CLAUDE.md, and CLAUDE.md adds AI agent guidance for repository conventions, workflow rules, security constraints, browser-auth pitfalls, and documentation update requirements. New reference docs add command lookup and common pitfall notes. ChangesDocumentation restructure
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Line 54: The directory tree fence in CLAUDE.md is missing a language tag,
which causes markdownlint-cli2 to fail; update the fenced block that shows the
tree diagram to use a plain text language label such as text or plaintext so the
docs lint passes.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
|
|
||
| ## Project Structure | ||
|
|
||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Label the directory tree fence so docs lint stays green.
markdownlint-cli2 flags this fence as missing a language tag. Use text or plaintext for the tree block.
♻️ Proposed fix
-```
+```text📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 54-54: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` at line 54, The directory tree fence in CLAUDE.md is missing a
language tag, which causes markdownlint-cli2 to fail; update the fenced block
that shows the tree diagram to use a plain text language label such as text or
plaintext so the docs lint passes.
Source: Linters/SAST tools
- Add universal "Any breaking change — always ask first" Ask-First boundary - Stop tracking MIGRATION_GUIDE.md as a fixed doc (breaking changes are covered by the Ask-First boundary; the guide is inferred from the branch) - Add version-source sync boundary (.version, src/version.ts, package.json, README/FAQ pins via .shiprc) - Refresh structure (myaccount/, passkey/) and code-to-docs mapping
sanchitmehtagit
force-pushed
the
claude-md-guidelines
branch
from
e9f7885 to
372b950
Compare
Regenerated with the updated generating-claude-md skill: adds the universal Working Principles preamble (think before coding, simplicity first, surgical changes, goal-driven execution) after Your Role, and drops the now-duplicate surgical-changes bullet from Boundaries.
Move the full command list and detailed pitfalls out of CLAUDE.md into references/*.md behind lazy "read when you need it" pointers, keeping the root file lean. Core commands, boundaries, security, and the persona stay inline. references/ avoids colliding with the generated TypeDoc docs/.
sanchitmehtagit
force-pushed
the
claude-md-guidelines
branch
from
daa02c5 to
a45b2c0
Compare
…inters Regenerated via the generating-claude-md skill: - Project Structure now sits right after Project Overview (orientation before command detail). - Testing conventions and the code-to-docs mapping move into references/testing.md and references/docs-update.md; the "update README/EXAMPLES in the same PR" boundary stays inline. - All references/ pointers are now clickable markdown links.
Keep the dominant naming/formatting convention inline as a one-line anchor; move the full linter setup, naming rules, bundle discipline, and dominant patterns into references/code-style.md behind a linked pointer.
Keep the enforced commit convention inline (commitlint fails CI otherwise); move branch naming, PR requirements, and changelog format into references/git-workflow.md behind a linked pointer.
Move Boundaries and Security up so all always-loaded substantive sections (Overview, Structure, Boundaries, Security) come first, then the reference sections (Commands, Testing, Code Style, Git, Pitfalls, Docs) as a contiguous "read when you need it" pointer block.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds AI-agent onboarding docs for auth0-spa-js, generated by the
generating-claude-mdskill and tailored to this repo.CLAUDE.md— the canonical, lean guidelines file: a concrete agent persona, core commands, testing conventions (Jest unit + Cypress against a local mock OIDC provider), three-tier boundaries, browser-security notes (PKCE, web-worker token isolation, DPoP), and theMIGRATION_GUIDE.mdbreaking-change rule.AGENTS.md— now references@CLAUDE.mdso non-Claude agents (Codex, Gemini) read one source of truth (replaces the older standalone AGENTS.md; its architecture/tribal knowledge was folded into CLAUDE.md).Notes
package.jsonand the CI workflows; every file path referenced inCLAUDE.mdresolves on disk.src/api.tsAuth0-Clientheader, preserving theauth0Clientwrapping of@auth0/auth0-auth-js.docs/offload —docs/holds generated TypeDoc output and the SDK is a lean single package, so the file stays inline.Test plan
CLAUDE.mdfor accuracy against the current SDK surfaceSummary by CodeRabbit