docs: add AI agent onboarding and CodeRabbit code review configuration

[jimmyjames]

Summary

This PR adds AI agent onboarding documentation and CodeRabbit code review configuration for the openfga/go-sdk repository. It was generated using the improving-claude-instructions skill in Claude Code via a 3-phase analysis workflow (5 parallel analysis agents → strategy review → implementation).

What was added

File	Purpose
AGENTS.md	Universal developer onboarding for all AI agents (Claude, Codex, Gemini, Jules, CodeRabbit). Covers tech stack, architecture, dev commands, code generation policy, key patterns, and gotchas.
CLAUDE.md	Claude Code entry point — imports AGENTS.md and references .claude/rules/ for Claude-specific coding instructions.
.coderabbit.yaml	CodeRabbit PR review configuration. Points to AGENTS.md for project context. Has path-specific instructions enforcing the same standards as the rules files.
.claude/rules/code-generation.md	Exhaustive generated vs. hand-written file taxonomy. Hard guardrail: never edit model_*.go, api_open_fga.go, etc. — redirect to sdk-generator repo.
.claude/rules/streaming.md	StreamingChannel[T] drain pattern, goroutine leak prevention, context cancellation.
.claude/rules/error-handling.md	Error type hierarchy, retry eligibility (429/5xx retried; 4xx not), Retry-After header behavior.
.claude/rules/telemetry.md	OTel metric names and attributes, noop provider pattern for unit tests, PII guardrails.
.claude/rules/oauth2-credentials.md	Token lifecycle, 300s threshold + 300s jitter expiry window, no time-based tests in oauth2/.

Design decisions

AGENTS.md as the universal source of truth

Rather than writing a Claude-only CLAUDE.md, the project context lives in AGENTS.md — a format recognized by OpenAI Codex, Google Jules, GitHub Copilot, and CodeRabbit. CLAUDE.md simply imports it via @AGENTS.md. This means any AI tool a contributor uses gets the same quality onboarding from a single file.

CodeRabbit + Claude enforce the same standards

.coderabbit.yaml mirrors the .claude/rules/ guardrails so standards are enforced at two points: by Claude during development, and by CodeRabbit during PR review. Key example: any PR that edits model_*.go or api_open_fga.go will get a hard CodeRabbit stop redirecting the author to the sdk-generator repo.

Rules files are unconditional (no path scoping)

All 5 .claude/rules/ files are loaded unconditionally (no paths frontmatter). The gotchas they cover — generated file editing, streaming leaks, token jitter — can trip up contributors working in any part of the SDK, not just specific directories.

Key findings from analysis

These were surfaced during the Phase 1 codebase analysis and are now documented in the files above:

1. ~63% of files are auto-generated — model_*.go (88 files), api_open_fga.go, streaming.go, internal/constants/constants.go, docs/ (90+ files). Edits get wiped on regeneration from the sdk-generator repo.
2. api_executor.go is the newer preferred pattern — it's hand-written and preferred over direct calls to the generated api_open_fga.go for new methods.
3. Token expiry jitter — OAuth2 tokens refresh 300–600s before expiry. Time-based tests in oauth2/ will fail unpredictably.
4. StreamingChannel[T] goroutine leak — both Results and Errors channels must be drained; a blocked read on either leaks the streaming goroutine.
5. golangci-lint excludes model_*.go — intentional design in .golangci.yaml; lint errors in generated code are not caught by CI.
6. Batch limits — 50 tuples per batch, 10 parallel requests (defined in internal/constants/constants.go).
7. Deprecated config fields — ApiScheme and ApiHost are deprecated; use ApiUrl.

For the reviewer / team

Before merging, please review and adjust:

• AGENTS.md — verify the architecture description and gotchas match your team's understanding. Add any workflow conventions not captured (e.g., release process, versioning policy).
• .coderabbit.yaml — adjust the profile (assertive → chill) and request_changes_workflow if preferred. Add or remove path-specific instructions to match your review standards.
• .claude/rules/ — each file is short and focused. Add team-specific patterns or remove anything that doesn't match how you actually work.
• Gap: example submodules — example/*/go.mod modules are independent and not tested in CI. The docs note this but the team may want to add CI coverage or explicitly document the maintenance expectation.
• Gap: release/versioning process — not captured in AGENTS.md since it wasn't visible in the codebase. If there's a release workflow, add it to AGENTS.md under a ## Release section.

Testing

No code changes — documentation only. make check passes on the branch.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3b1c3c7b-ccdd-49d9-b7f8-0a7382b4bb3b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/ai-docs

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: jimmyjames / name: Jim Anderson (a4a38aa)
• ✅ login: rhamzeh / name: Raghd Hamzeh (0e642a4, f2be1c9)

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 34.38%. Comparing base (d8c395e) to head (f2be1c9).
⚠️ Report is 1 commits behind head on main.

❌ Your project status has failed because the head coverage (34.38%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #288      +/-   ##
==========================================
+ Coverage   33.70%   34.38%   +0.67%     
==========================================
  Files         115      115              
  Lines        9826     9982     +156     
==========================================
+ Hits         3312     3432     +120     
- Misses       6244     6272      +28     
- Partials      270      278       +8     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.