docs: improve CLAUDE.md with better architecture description

[jxnl]

Summary

• Add required Claude Code header
• Update installation commands to include both uv and poetry options
• Add command for building documentation
• Add a commit style guideline based on the CONTRIBUTING.md
• Add a new Core Architecture section that explains the high-level design of the library
• Add a Key Components section highlighting the important modules and their purposes
• Add a Testing Guidelines section with best practices for writing tests
• Reorganize the Provider Architecture section for better clarity

Test plan

• Verify that the CLAUDE.md file is properly formatted
• Ensure all commands and instructions are accurate

🤖 Generated with Claude Code

---

Important

Enhances CLAUDE.md with improved architecture descriptions, new sections on core architecture, key components, and testing guidelines, and updates to installation and commit style guidelines.

• Documentation Enhancements:
  • Add required Claude Code header to CLAUDE.md.
  • Update installation commands to include uv and poetry options.
  • Add command for building documentation using mkdocs.
  • Add commit style guideline based on CONTRIBUTING.md.
  • Reorganize Provider Architecture section for clarity.
• New Sections:
  • Add Core Architecture section explaining high-level design.
  • Add Key Components section highlighting important modules.
  • Add Testing Guidelines section with best practices.

^{This description was created by for aac139f. You can customize this summary. It will automatically update as commits are pushed.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to aac139f in 2 minutes and 4 seconds. Click for details.

• Reviewed 85 lines of code in 1 files
• Skipped 0 files when reviewing.
• Skipped posting 9 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. CLAUDE.md:8

• Draft comment:
  Clarify the usage of 'uv pip install' versus 'poetry install' to help users understand when to use each command.
• Reason this comment was not posted:
  Confidence changes required: 66% <= threshold 85% None

2. CLAUDE.md:9

• Draft comment:
  Commands like 'pytest' and 'pyright' are now invoked directly. Document that this assumes an activated virtual environment.
• Reason this comment was not posted:
  Confidence changes required: 66% <= threshold 85% None

3. CLAUDE.md:26

• Draft comment:
  Consider linking to the CONTRIBUTING.md or adding further details on the conventional commits format to guide commit messages.
• Reason this comment was not posted:
  Confidence changes required: 50% <= threshold 85% None

4. CLAUDE.md:28

• Draft comment:
  The 'Core Architecture' section is informative. Consider adding links or more detail on complex aspects (e.g., the patching mechanism) to further aid new contributors.
• Reason this comment was not posted:
  Confidence changes required: 50% <= threshold 85% None

5. CLAUDE.md:43

• Draft comment:
  Clarify the distinction between the unified access via 'from_provider()' and the provider detection using 'get_provider' to avoid potential confusion.
• Reason this comment was not posted:
  Confidence changes required: 66% <= threshold 85% None

6. CLAUDE.md:45

• Draft comment:
  Consider linking the listed key components (e.g., process_response.py, patch.py) to their source files to enhance navigability for contributors.
• Reason this comment was not posted:
  Confidence changes required: 50% <= threshold 85% None

7. CLAUDE.md:54

• Draft comment:
  The Testing Guidelines are clear; adding concrete examples or command snippets could further assist contributors in understanding the recommended practices.
• Reason this comment was not posted:
  Confidence changes required: 33% <= threshold 85% None

8. CLAUDE.md:70

• Draft comment:
  Add a trailing newline at the end of the file to comply with POSIX standards.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 85% While having a trailing newline is indeed a POSIX standard and good practice, this is an extremely minor issue that would typically be handled automatically by code formatters and linters. The project uses Ruff for formatting, which would automatically fix this. Additionally, this kind of minor formatting issue doesn't impact functionality or readability. The comment is technically correct - POSIX standards do recommend trailing newlines. And it is a change in the diff. However, this is exactly the kind of minor formatting issue that should be handled by automated tools rather than manual review comments. The project already uses Ruff for formatting which would fix this automatically. Delete this comment as it's too minor of an issue and would be better handled by automated formatting tools.

9. CLAUDE.md:8

• Draft comment:
  Typo/lexicographical suggestion: The command 'uv pip install -e ".[dev,anthropic]"' on this line might be a mistake. Did you mean to use 'pip install -e ".[dev,anthropic]"'? Please verify if 'uv' is intended.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 0% vs. threshold = 85% 1. uv is a legitimate Python package installer that's gaining popularity as a faster alternative to pip. 2. The line intentionally offers two valid installation methods. 3. The comment incorrectly assumes uv is a typo when it's actually a valid tool. 4. This seems like a deliberate addition to provide users with a modern alternative. Could uv be too new or unfamiliar to most users? Should we stick with more standard tools? The line already provides pip/poetry alternatives, so including uv as an additional option doesn't hurt - users can choose their preferred method. The comment should be deleted as it incorrectly flags uv as a mistake when it's actually a valid and intentional installation option.

Workflow ID: wflow_qufxAHmS8OZmCYra

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}