Update CLAUDE.md

[neekolas]

Streamline CLAUDE.md with improved structure and clarity

Completely rewrote the Claude AI guidance document to be more concise and better organized:

• Simplified project overview and added clear architecture diagram
• Restructured development commands into logical categories
• Added more specific testing examples and benchmark commands
• Removed outdated Nix development environment section
• Condensed test writing guidance with clearer examples
• Simplified code change requirements section
• Improved formatting throughout for better readability

This update provides Claude with more accurate and focused information about the codebase structure and development workflows.

[neekolas]

• Update CLAUDE.md #3019 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label mergequeue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Claude finished @neekolas's task —— View job

---

PR Review - January 15, 2026, 5:02 PM UTC

Summary

This PR successfully removes Nix-specific content and improves the documentation structure. The changes are clean and the updated guidance is accurate and helpful for Claude Code users.

Key Improvements

1. ✅ Removed Nix section - Simplified developer onboarding by removing the Nix development environment section
2. ✅ Enhanced test documentation - Added important clarification about unwrap_try = true parameter and its benefits
3. ✅ Architecture accuracy - Verified architecture diagram and key patterns match actual codebase structure
4. ✅ Command verification - All referenced commands (dev/lint, dev/test/wasm, dev/test/coverage) exist and are executable

Feedback

Testing Section Enhancement (CLAUDE.md:84-85)
The addition of unwrap_try = true documentation is excellent. The old version only mentioned #[xmtp_common::test] while the new version clarifies that #[xmtp_common::test(unwrap_try = true)] should be used with an explanation of why (better error messages with ? operators). This is a significant improvement for developer experience.

Minor Suggestion (Optional)
Consider adding a brief note about when NOT to use unwrap_try = true if there are any cases where developers should use plain #[xmtp_common::test]. If unwrap_try = true should always be used, the current documentation is perfect as-is.

Verification

• ✅ All directory paths referenced exist (bindings/mobile, bindings/wasm, bindings/node, crates/xmtp_db/migrations/)
• ✅ All dev/* commands mentioned are present and executable
• ✅ Architecture diagram accurately represents crate structure

---

Review date: January 15, 2026, 5:02 PM UTC

[macroscopeapp]

Rewrite CLAUDE.md to provide Claude Code–focused guidance and consolidate development, testing, and code quality procedures in CLAUDE.md

Replace the prior assistant context with a Claude Code guide, add architecture and design pattern notes, update testing conventions and examples, and consolidate dev commands, logging, and database notes in CLAUDE.md.

📍Where to Start

Start with the updated structure and testing guidance in CLAUDE.md.

---

Macroscope summarized 8ee5773.