[rmad17]

Summary

This PR gives AI coding agents (Claude Code, Codex, Gemini CLI, and others) a shared set of instructions for working in auth0-fastapi. CLAUDE.md holds the guidelines and AGENTS.md points to it, so every tool reads the same rules. It's docs only: nothing under src/ changes, and nothing ships to PyPI.

Changes

CLAUDE.md (always loaded, about 110 lines)

• An annotated map of the package: where AuthClient, the routes, the stores, the errors, and the tests live.
• Boundaries in three tiers:
  • Always Do: keep AuthClient methods as thin wrappers over ServerClient, send redirect targets through to_safe_redirect, update the README and examples/ guides in the same PR, keep pyproject.toml and requirements.txt in sync, and stick to Python 3.9 syntax.
  • Ask First: breaking changes, dependency bumps, public signature changes, cookie or session changes, and CI edits.
  • Never Do: commit secrets, log tokens, weaken cookie flags, or hand-edit poetry.lock.
• A security section covering what the code does today: cookie flags per store, open-redirect protection, MCD proxy-header trust, the backchannel logout issuer check, and the error-response shape.
• One-line summaries that link to the reference docs below.

AGENTS.md

• Imports @./CLAUDE.md, so there's a single source of truth.

references/ (read only when a task needs them)

• commands.md: install, lint, test, and build commands that match CI.
• testing.md: test layout, fixtures, and which mocking pattern to use where.
• code-style.md: ruff rules, naming, and a good and bad wrapper example.
• git-workflow.md: branch, commit, and PR conventions.
• pitfalls.md: known gotchas, like the missing top-level import, the ignored cookie_name setting, and unmarked async tests being skipped.
• docs-update.md: which doc to update for each kind of code change.

Testing

No code changed, so there's no runtime behavior to test. What I checked:

• poetry run ruff check . still passes.