feat: add claude.md

[ninja-shreyash]

Summary

Adds CLAUDE.md — the single source of truth for all SDK conventions, rules, and patterns. Loaded automatically into every Claude Code conversation in this repo.

What's in it

• Architecture — repo layout, service map (import paths → services → patterns), BaseService vs FolderScopedService, dual auth, error hierarchy
• Code style — casing rules, file naming, optional fields
• Service conventions — type naming ({Entity}GetResponse, Raw{Entity}GetResponse, Options not Request), 3-file model structure, method attachment, export naming, singular vs batch patterns
• Response transforms — 4-step pipeline, standard field renames, outbound transforms, OData prefix handling
• Pagination — offset vs token, constants, excludeFromPrefix, conditional return types, setup steps
• NEVER Do — 30+ anti-patterns organized by category (naming, types, transforms, method binding, internal types, endpoints, OperationResponse, pagination, tests, code hygiene, docs), each with a reason
• Testing — vitest + shared mocks, integration test helpers, v0/v1 modes
• Documentation — JSDoc rules, required file updates per PR
• Verification checklist — commands to run + manual + doc checks before committing
• Key source files — pattern-to-file lookup table

How it works with the onboard-api skill

CLAUDE.md has the conventions (always loaded). The /onboard-api skill (PR #302) has the workflow (loaded on demand). No duplication between them — the skill references conventions already in context.

For non-onboarding work (bug fixes, refactoring, reviews), CLAUDE.md applies directly without any skill.

Test plan

• Verify conventions match existing code patterns
• Verify NEVER Do items match actual PR review feedback
• Invoke /onboard-api and confirm it follows CLAUDE.md conventions during implementation

[Raina451]

can you add this in agents.md, and in claude.md refer agents.md ? as agents.md is generic used by other agentic ides.

[Raina451]

also as per best practices, we should have claude.md under 200 lines. ref: https://code.claude.com/docs/en/memory#write-effective-instructions

can we move some part of it in .claude/rules or agent_docs? or something and refer that here?
The recommended approach is to use @import references — so instead of embedding everything inline, you point to separate files that load on demand.

[ninja-shreyash]

The recommended approach is to use https://github.com/import references — so instead of embedding everything inline, you point to separate files that load on demand.

Is it loaded on demand? I think irrespective on @import, it will be loaded by default always. Anyways I have broken it down as per guidelines

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud