Add initial CLAUDE.md for AI-assisted development

[BryanFauble]

Summary

• Adds root CLAUDE.md (95 lines) and 4 module-level CLAUDE.md files (170 lines total) capturing non-obvious conventions and patterns that AI assistants cannot infer from the code alone
• Root: async-to-sync decorator system, protocol classes, dataclass models with fill_from_dict(), concrete Java type mapping, mixin composition, layered architecture, testing conventions
• synapseclient/models/: new model checklist, standard fields, _last_persistent_instance lifecycle, EnumCoercionMixin, fill_from_dict() pattern, @otel_trace_method usage
• synapseclient/api/: function signature conventions, REST call patterns, pagination helpers, new service file checklist
• synapseclient/core/: async_to_sync internals, retry strategies, credentials chain, upload/download resilience, concrete types registration
• tests/: async-only test convention, socket blocking, schedule_for_cleanup(), fixture scoping
• All commands verified from CI configs (build.yml, pytest.ini, .pre-commit-config.yaml)

Test plan

• Root file under 150 lines (95 lines)
• All module files under 150 lines (54, 45, 38, 33 lines)
• Every line passes the quality test: "If I remove this, will Claude mess up?"
• Commands are verbatim from config files
• No duplication with README.md content
• No linter/formatter rules restated (those are enforced by ruff/black/isort/bandit configs)
• Module files only contain patterns that differ from or extend the root CLAUDE.md

🤖 Generated with Claude Code

[thomasyu888]

🔥 I will continue taking a look at this, and I think this would be a great PR to review in a DPE code spaces so that @Sage-Bionetworks/dpe has the opportunity to learn and review the structure.

[Copilot]

Pull request overview

Adds a set of CLAUDE.md guidance files (root + module-level) intended to document non-obvious repository conventions and patterns for AI-assisted development.

Changes:

• Introduces a root CLAUDE.md describing overall architecture, stack, and development/testing commands.
• Adds module-level CLAUDE.md files capturing conventions for synapseclient layers (api/core/models/operations), synapseutils, tests, and docs.
• Documents patterns such as async-first + sync-wrapper generation, concrete type registration, services/mixins usage, and test suite conventions.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
CLAUDE.md	Root-level AI/dev conventions, commands, architecture overview
docs/CLAUDE.md	Documentation build/contribution conventions (MkDocs/mkdocstrings/Diataxis)
tests/CLAUDE.md	Test suite conventions (unit vs integration, fixtures, networking, cleanup)
synapseutils/CLAUDE.md	Legacy synapseutils constraints and key module notes
synapseclient/api/CLAUDE.md	REST service-layer signature and pagination conventions
synapseclient/core/CLAUDE.md	Core infrastructure patterns (async_to_sync, retry, creds, transfers)
synapseclient/core/constants/CLAUDE.md	Concrete type + constants registration guidance
synapseclient/core/credentials/CLAUDE.md	Credential-provider chain and logging constraints
synapseclient/core/download/CLAUDE.md	Download flow conventions (MD5, collisions, progress)
synapseclient/core/upload/CLAUDE.md	Multipart upload conventions (sync/async parity, retries, memory)
synapseclient/models/CLAUDE.md	Dataclass model conventions (fill_from_dict, annotations, lifecycle)
synapseclient/models/mixins/CLAUDE.md	Mixin-specific patterns and constraints
synapseclient/models/protocols/CLAUDE.md	Protocol/type-hint conventions for generated sync methods
synapseclient/models/services/CLAUDE.md	Internal service-layer conventions for models
synapseclient/operations/CLAUDE.md	Operations-layer sync wrapper + dispatch conventions
synapseclient/extensions/curator/CLAUDE.md	Curator extension conventions and constraints

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[andrewelamb]

I would be in favor of removing the line counts, I'm not sure it adds anything. Other than that LGTM!

[jaymedina]

I added a few suggestions to help clarify things & provide more context to Claude. This is great, thanks!

[linglp]

I did my first round of review. I think this is definitely a good start, but I think some of the description in the CLAUDE.md details include unnecessary details, such as what exists in a given data class. I think we should focus more on "what Claude would get wrong without guidance" rather than describing what exists.

Issues resolved