docs: add comprehensive CLAUDE.md for AI assistant guidance #1
Conversation
Add detailed CLAUDE.md documentation covering: - Project overview and philosophy - Complete repository structure - Development workflows and setup - Code conventions and style guidelines - Testing strategy and coverage - Key technologies and dependencies - Common development tasks - Important patterns and anti-patterns - External tools plugin system - Quick reference guide This guide provides AI assistants with everything needed to understand the codebase structure, development workflows, and conventions for contributing to doctk.
Summary of ChangesHello @tommcd, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a new, extensive Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive CLAUDE.md guide for AI assistants, which is an excellent initiative for improving collaboration with AI on this project. The document is thorough and well-structured. I've provided a few review comments to correct some commands in the development workflow, fix minor typos, and improve the clarity of a code example to ensure the guide is as accurate and helpful as possible.
Fix technical inaccuracies and improve documentation clarity: 1. Fix uv sync command syntax - Change from `uv sync --all-groups` to `uv sync --group dev --group docs` - Matches current uv CLI syntax for dependency groups 2. Fix pytest command for running slow tests - Replace non-standard `--run-slow` flag with proper marker syntax - Use `pytest -m slow` or `pytest -m "slow or not slow"` - Aligns with pytest marker configuration in pyproject.toml 3. Use relative path instead of absolute path - Change `/home/user/doctk/` to `doctk/` - Makes documentation more generic and less user-specific 4. Fix file extension typo in repository structure - Correct `markdown.md` to `markdown.py` in writers directory - Matches actual file in src/doctk/writers/ 5. Add missing imports to code example - Include `Callable`, `Document`, `Node` imports - Define `Operation` type alias - Makes code example complete and runnable All changes based on gemini-code-assist review: #1 (review)
After investigating gemini-code-assist review feedback, determined that --all-groups is actually valid and preferable: - `uv sync --all-groups` was added in uv 0.5.4 (Nov 2024) - See: astral-sh/uv#8892 - It's cleaner, matches setup-environment.sh, and is more maintainable - Added clarifying comments "(dev and docs)" to show what groups exist Changes kept from previous commit (df36f34): ✅ Fix pytest -m slow marker syntax (was incorrectly --run-slow) ✅ Use relative path doctk/ instead of /home/user/doctk/ ✅ Fix markdown.py typo in writers directory (was markdown.md) ✅ Add missing imports to code example (Callable, Document, Node, Operation) Changes reverted: ↩️ Restore --all-groups instead of --group dev --group docs The explicit --group syntax was the reviewer's suggestion, but --all-groups is simpler, matches actual implementation, and is now well-established.
Reduce GitHub Actions test jobs from 15 to 6: Before: - 3 OS × 5 Python versions = 15 jobs - Ubuntu, macOS, Windows all tested with Python 3.10-3.14 After: - Ubuntu: All Python versions (3.10, 3.11, 3.12, 3.13, 3.14) - 5 jobs - Windows: Only Python 3.14 (compatibility check) - 1 job - macOS: Removed (not critical for this project) - Total: 6 jobs (60% reduction) Rationale: - Few tests in the suite don't justify extensive cross-platform matrix - Ubuntu is primary development/deployment platform - Windows 3.14 provides basic cross-platform validation - Codecov still uploads from Ubuntu 3.11 Additional fix: - Change uv sync --all-extras to --all-groups (correct flag) - Update CLAUDE.md CI/CD documentation to reflect optimized matrix
Focus on actively maintained Python versions only. Changes: - Require Python 3.12+ (was 3.10+) - CI: Test only 3.12, 3.13, 3.14 on Ubuntu + 3.14 on Windows - Reduce CI jobs from 6 to 4 (33% faster) Rationale: - Python 3.10 and 3.11 are in security-fix-only mode - For a new project (v0.1.0), supporting only actively maintained versions reduces maintenance burden - 3 Python versions provides adequate coverage - Users on older Python can stay on doctk v0.0.x if needed Updated files: - pyproject.toml: requires-python = ">=3.12" - .github/workflows/tests.yml: Remove 3.10, 3.11 from matrix - README.md: Update badge to Python 3.12+ - CLAUDE.md: Update all references to Python versions - CONTRIBUTING.md: Update prerequisites - scripts/setup-environment.sh: Check for 3.12+ with updated regex - scripts/check-environment.sh: Check for 3.12+ (was 3.10+) - docs/: Update installation and development guides - examples/sample.md: Update Python version requirement Codecov now uploads from Ubuntu 3.13 (was 3.11).
Further optimize CI by removing Windows builds. Changes: - Remove Windows job from CI matrix - Reduce from 4 jobs to 3 jobs (25% faster) - Simplify matrix syntax (no more include blocks) Rationale: - Windows builds are significantly slower in GitHub Actions - Project is early stage (v0.1.0) with limited test suite - Document processing is primarily Unix/Linux focused - Can add Windows back later if users report issues - 3 Python versions on Ubuntu provides adequate coverage New matrix: - Ubuntu: Python 3.12, 3.13, 3.14 - Total: 3 jobs This saves ~2-5 minutes per CI run and simplifies maintenance.
Add detailed design and implementation plan for 2 remaining PR #6 review issues: 1. CRITICAL: Granular document edits (Issue #1) - Added 'Optimized Edits (CRITICAL IMPROVEMENT)' section to design.md - Explains problem: full document replacement clears undo/redo, loses cursor - Solution: Backend computes ModifiedRange[], frontend applies granular edits - Added 5 subtasks (22.5.1-22.5.5) to tasks.md with implementation steps 2. MEDIUM: Centralize ID generation (Issue #5) - Added 'Centralized Node ID Generation' section to design.md - Explains problem: Duplicate ID logic in frontend and backend - Solution: Backend as single source of truth for tree structure & IDs - Added 4 subtasks (22.6.1-22.6.4) to tasks.md with implementation steps Both sections include: - Problem statement and impact - Proposed solution with code examples - Design rationale - Backend and frontend changes - Testing requirements This provides clear roadmap for addressing the remaining architectural issues identified in #6 (review)
Implement ModifiedRange-based edits to preserve cursor position and undo/redo stack. This addresses the CRITICAL issue from PR #6 review. Backend changes: - Add ModifiedRange dataclass to protocols.py with line/column positions - Implement DiffComputer class to compute changed text ranges - Update all operations (promote, demote, move_up, move_down, nest, unnest) to return modified_ranges in addition to full document - Update bridge.py to serialize ModifiedRange objects to JSON Frontend changes: - Add ModifiedRange interface to types.ts - Update extension.ts executeOperation() to use granular edits when available - Fall back to full document replacement if modified_ranges not provided - This preserves cursor position and undo/redo stack Design changes: - Remove Approach 2 (Backend ID Service) from design.md - Keep only Backend-Driven Tree Structure approach for centralized IDs All 34 existing tests pass. Granular edits improve UX by: - Preserving cursor position during operations - Maintaining VS Code undo/redo stack - Better performance for large documents Related: PR #6 review issue #1 (CRITICAL)
Add detailed CLAUDE.md documentation covering:
This guide provides AI assistants with everything needed to understand the codebase structure, development workflows, and conventions for contributing to doctk.