tree-sitter-analyzer 1.7.2__tar.gz → 1.7.4__tar.gz

{tree_sitter_analyzer-1.7.2 → tree_sitter_analyzer-1.7.4}/.roo/rules/ROO_RULES.md

@@ -54,8 +54,11 @@ use_mcp_tool:
 
 ##### コード読取用ツール
 - `analyze_code_structure`: 全体構造の把握
+  - `suppress_output + output_file`でトークン節約対応
 - `extract_code_section`: 特定行範囲の抽出
+  - `suppress_output + output_file`でトークン節約対応
 - `query_code`: 特定要素の検索（関数、クラス等）
+  - `suppress_output + output_file`でトークン節約対応
 
 ##### ファイル検索用ツール
 - `list_files`: ファイル一覧取得（fd使用）
@@ -730,8 +733,8 @@ use_mcp_tool:
   tool_name: find_and_grep
   arguments:
     roots: ["."]
-    pattern: "*HQBFS060*"
-    query: "局署名|lblKyokushoName"
+    pattern: "*XXXX060*"
+    query: "项目名|lblKoumokuName"
     # → 大量の出力でトークン消費
 
 # 新しい解決策: ファイル出力でトークン節約
@@ -740,8 +743,8 @@ use_mcp_tool:
   tool_name: find_and_grep
   arguments:
     roots: ["."]
-    pattern: "*HQBFS060*"
-    query: "局署名|lblKyokushoName"
+    pattern: "*XXXX060*"
+    query: "项目名|lblKoumokuName"
     case: "insensitive"
     group_by_file: true
     suppress_output: true
@@ -812,6 +815,225 @@ use_mcp_tool:
     output_file: "controller_analysis.json"  # ファイル保存
 ```
 
+### 16. 新機能: コード読取ツールでのファイル出力最適化
+
+#### 16.1 対応ツール
+- [`extract_code_section`](tree_sitter_analyzer/mcp/tools/read_partial_tool.py): 特定行範囲の抽出
+- [`query_code`](tree_sitter_analyzer/mcp/tools/query_tool.py): tree-sitterクエリによる要素抽出
+
+#### 16.2 新パラメータ
+- `output_file`: 結果をファイルに保存（拡張子自動検出）
+- `suppress_output`: `output_file`指定時に詳細出力を抑制してトークン節約
+
+#### 16.3 推奨使用パターン
+
+##### 16.3.1 大きなコードセクションの抽出
+```markdown
+# 従来の問題: 大きなコードセクションでトークン消費
+use_mcp_tool:
+ server_name: tree-sitter-analyzer
+ tool_name: extract_code_section
+ arguments:
+   file_path: "src/large_file.py"
+   start_line: 100
+   end_line: 500
+   # → 大量のコード出力でトークン消費
+
+# 新しい解決策: ファイル出力でトークン節約
+use_mcp_tool:
+ server_name: tree-sitter-analyzer
+ tool_name: extract_code_section
+ arguments:
+   file_path: "src/large_file.py"
+   start_line: 100
+   end_line: 500
+   suppress_output: true
+   output_file: "code_section_extract"
+
+# 後で詳細を確認
+read_file:
+ path: "code_section_extract.txt"
+```
+
+##### 16.3.2 大量のクエリ結果の処理
+```markdown
+# 従来の問題: 大量のクエリ結果でトークン消費
+use_mcp_tool:
+ server_name: tree-sitter-analyzer
+ tool_name: query_code
+ arguments:
+   file_path: "src/complex_file.java"
+   query_key: "methods"
+   output_format: "json"
+   # → 大量のメソッド情報でトークン消費
+
+# 新しい解決策: ファイル出力でトークン節約
+use_mcp_tool:
+ server_name: tree-sitter-analyzer
+ tool_name: query_code
+ arguments:
+   file_path: "src/complex_file.java"
+   query_key: "methods"
+   output_format: "json"
+   suppress_output: true
+   output_file: "methods_analysis"
+
+# 後で詳細を確認
+read_file:
+ path: "methods_analysis.json"
+```
+
+##### 16.3.3 段階的コード解析戦略（更新版）
+```markdown
+# ステップ1: 全体構造把握（トークン節約）
+use_mcp_tool:
+ server_name: tree-sitter-analyzer
+ tool_name: analyze_code_structure
+ arguments:
+   file_path: "src/target_file.py"
+   format_type: "compact"
+   suppress_output: true
+   output_file: "structure_overview"
+
+# ステップ2: 特定要素の詳細抽出（トークン節約）
+use_mcp_tool:
+ server_name: tree-sitter-analyzer
+ tool_name: query_code
+ arguments:
+   file_path: "src/target_file.py"
+   query_key: "functions"
+   output_format: "summary"
+   suppress_output: true
+   output_file: "functions_summary"
+
+# ステップ3: 興味のある部分の詳細取得（トークン節約）
+use_mcp_tool:
+ server_name: tree-sitter-analyzer
+ tool_name: extract_code_section
+ arguments:
+   file_path: "src/target_file.py"
+   start_line: 45
+   end_line: 80
+   suppress_output: true
+   output_file: "detailed_section"
+
+# ステップ4: 結果の段階的確認
+read_file:
+ path: "structure_overview.md"
+read_file:
+ path: "functions_summary.json"
+read_file:
+ path: "detailed_section.txt"
+```
+
+#### 16.4 ファイル形式の自動選択
+- **extract_code_section**: テキスト形式（.txt）で保存
+- **query_code**: JSON形式（.json）で保存（output_format="json"の場合）
+- **query_code**: JSON形式（.json）で保存（output_format="summary"の場合）
+- 拡張子は内容に基づいて自動決定
+
+#### 16.5 実践的な使用例
+
+##### 16.5.1 大規模ファイルの段階的解析
+```markdown
+# ステップ1: ファイルサイズ確認
+use_mcp_tool:
+ server_name: tree-sitter-analyzer
+ tool_name: check_code_scale
+ arguments:
+   file_path: "src/huge_service.java"
+
+# ステップ2: 構造概要取得（大規模ファイル対応）
+use_mcp_tool:
+ server_name: tree-sitter-analyzer
+ tool_name: analyze_code_structure
+ arguments:
+   file_path: "src/huge_service.java"
+   format_type: "compact"
+   suppress_output: true
+   output_file: "huge_service_structure"
+
+# ステップ3: 特定メソッドの検索（トークン節約）
+use_mcp_tool:
+ server_name: tree-sitter-analyzer
+ tool_name: query_code
+ arguments:
+   file_path: "src/huge_service.java"
+   query_key: "methods"
+   filter: "name=~process*"
+   suppress_output: true
+   output_file: "process_methods"
+
+# ステップ4: 興味のあるメソッドの詳細抽出
+use_mcp_tool:
+ server_name: tree-sitter-analyzer
+ tool_name: extract_code_section
+ arguments:
+   file_path: "src/huge_service.java"
+   start_line: 150
+   end_line: 200
+   suppress_output: true
+   output_file: "target_method_detail"
+```
+
+##### 16.5.2 複数ファイルの効率的解析
+```markdown
+# 複数ファイルを順次解析（各ファイルでトークン節約）
+files=["controller.py", "service.py", "model.py"]
+
+for file in files:
+ # 構造解析
+ use_mcp_tool:
+   server_name: tree-sitter-analyzer
+   tool_name: analyze_code_structure
+   arguments:
+     file_path: f"src/{file}"
+     format_type: "compact"
+     suppress_output: true
+     output_file: f"{file}_structure"
+ 
+ # 関数抽出
+ use_mcp_tool:
+   server_name: tree-sitter-analyzer
+   tool_name: query_code
+   arguments:
+     file_path: f"src/{file}"
+     query_key: "functions"
+     output_format: "summary"
+     suppress_output: true
+     output_file: f"{file}_functions"
+
+# 結果の一括確認
+for file in files:
+ read_file:
+   path: f"{file}_structure.md"
+ read_file:
+   path: f"{file}_functions.json"
+```
+
+#### 16.6 トークン最適化のベストプラクティス
+
+##### 16.6.1 適切なツール選択
+```markdown
+# 用途別の最適なツール選択
+1. 全体構造把握: analyze_code_structure (suppress_output: true)
+2. 特定要素検索: query_code (suppress_output: true)
+3. 詳細コード確認: extract_code_section (suppress_output: true)
+4. 後続処理: read_file で保存されたファイルを読取
+```
+
+##### 16.6.2 段階的詳細化戦略
+```markdown
+# レベル1: 概要のみ（最小トークン）
+suppress_output: true + output_file
+
+# レベル2: 必要に応じて保存ファイル読取
+read_file: 保存されたファイル
+
+# レベル3: さらに詳細が必要な場合のみ追加抽出
+extract_code_section: 特定行範囲
+```
+
 ## まとめ
 
 ROOはtree-sitter-analyzer MCPツールを最大限活用し、効率的で安全なコード解析・編集を実現する。標準ツールよりもMCPツールを優先し、トークン効率化と構造化された解析を重視する。
@@ -823,4 +1045,5 @@ ROOはtree-sitter-analyzer MCPツールを最大限活用し、効率的で安
 4. **適切なツール選択**: 目的に応じた最適なMCPツール使用
 5. **セキュリティ重視**: プロジェクト境界内での安全な操作
 6. **日本語検索対策**: 汎用語での無制限検索を避け、段階的アプローチを採用
-7. **NEW: 検索最適化**: `find_and_grep`と`search_content`でのファイル出力機能活用
+7. **NEW: 検索最適化**: `find_and_grep`と`search_content`でのファイル出力機能活用
+8. **NEW: コード読取最適化**: `extract_code_section`と`query_code`でのファイル出力機能活用

{tree_sitter_analyzer-1.7.2 → tree_sitter_analyzer-1.7.4}/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## [1.7.4] - 2025-10-10
+
+### Improved
+- **📊 Quality Metrics**:
+  - Test count increased to 2934 (up from 2831)
+  - Code coverage improved to 80.08% (up from 79.19%)
+  - All tests passing with enhanced system stability
+- **🔧 Development Workflow**: Continued improvements to development and release processes
+- **📚 Documentation**: Maintained comprehensive documentation and examples
+
+### Technical Details
+- **Test Coverage**: All 2934 tests passing with 80.08% coverage
+- **Quality Metrics**: Enhanced test suite with improved coverage
+- **Breaking Changes**: None - all improvements are backward compatible
+
+This minor release maintains the high quality standards while improving test coverage and system stability.
+
+## [1.7.3] - 2025-10-09
+
+### Added
+- **🆕 Complete Markdown Plugin Enhancement**: Comprehensive Markdown element extraction capabilities
+  - **5 New Element Types**: Added blockquotes, horizontal rules, HTML elements, text formatting, and footnotes
+  - **Enhanced Element Extraction**: New extraction methods for comprehensive Markdown analysis
+  - **Structured Analysis**: Convert Markdown documents to structured data for AI processing
+  - **Query System Integration**: Full integration with existing query and filtering functionality
+
+- **📝 New Markdown Extraction Methods**: Powerful new analysis capabilities
+  - `extract_blockquotes()`: Extract > quoted text blocks with proper attribution
+  - `extract_horizontal_rules()`: Extract ---, ***, ___ separators and dividers
+  - `extract_html_elements()`: Extract HTML blocks and inline tags within Markdown
+  - `extract_text_formatting()`: Extract **bold**, *italic*, `code`, ~~strikethrough~~ formatting
+  - `extract_footnotes()`: Extract [^1] references and definitions with linking
+
+- **🔧 Enhanced Tree-sitter Queries**: Extended query system for comprehensive parsing
+  - **New Footnotes Query**: Dedicated query for footnote references and definitions
+  - **Updated All Elements Query**: Enhanced query covering all 10 Markdown element types
+  - **Improved Pattern Matching**: Better recognition of complex Markdown structures
+
+### Enhanced
+- **📊 Markdown Formatter Improvements**: Enhanced table display for new element types
+  - **Comprehensive Element Display**: All 10 element types now displayed in structured tables
+  - **Better Formatting**: Improved readability and organization of Markdown analysis results
+  - **Consistent Output**: Unified formatting across all Markdown element types
+
+- **🧪 Test Suite Expansion**: Comprehensive test coverage for new functionality
+  - **67 New Test Cases**: Complete validation of all new Markdown features
+  - **Element-Specific Testing**: Dedicated tests for each new extraction method
+  - **Integration Testing**: Full validation of query system integration
+  - **Backward Compatibility**: Ensured all existing functionality remains intact
+
+### Improved
+- **📊 Quality Metrics**:
+  - Test count increased to 2831 (up from 2829)
+  - Code coverage improved to 79.19% (up from 76.51%)
+  - All tests passing with enhanced system stability
+  - CLI regression tests updated to reflect 47→69 elements (46% improvement)
+
+- **📚 Documentation**: Enhanced examples/test_markdown.md analysis coverage significantly
+- **🔧 Development Workflow**: Improved Markdown analysis capabilities for AI-assisted development
+- **🎯 Element Coverage**: Expanded from 5 to 10 Markdown element types for comprehensive analysis
+
+### Technical Details
+- **Enhanced Files**:
+  - `tree_sitter_analyzer/languages/markdown_plugin.py` - Added 5 new extraction methods
+  - `tree_sitter_analyzer/formatters/markdown_formatter.py` - Enhanced table formatting
+  - `tree_sitter_analyzer/queries/markdown.py` - Extended query definitions
+- **Test Coverage**: All 2831 tests passing with 79.19% coverage
+- **Quality Metrics**: Enhanced Markdown plugin with comprehensive validation
+- **Breaking Changes**: None - all improvements are backward compatible
+- **Element Count**: Increased from 47 to 69 elements in examples/test_markdown.md analysis
+
+This minor release introduces comprehensive Markdown analysis capabilities, making Tree-sitter Analyzer a powerful tool for document analysis and AI-assisted Markdown processing, while maintaining full backward compatibility.
+
 ## [1.7.2] - 2025-10-09
 
 ### Added

tree_sitter_analyzer-1.7.4/GITFLOW.md

@@ -0,0 +1,324 @@
+# GitFlow Branching Strategy (English Documentation)
+
+This document explains the GitFlow branching strategy implemented in the `tree-sitter-analyzer` project using Mermaid diagrams and English descriptions.
+
+## GitFlow Diagram
+
+```mermaid
+gitGraph
+    commit id: "Initial commit"
+    branch develop
+    commit id: "dev-1"
+
+    branch feature/my-feature
+    commit id: "feat-1"
+    commit id: "feat-2"
+
+    checkout develop
+    merge feature/my-feature id: "merge-feat"
+
+    branch release/v1.0.0
+    commit id: "release-prep"
+
+    checkout main
+    merge release/v1.0.0 tag: "v1.0.0"
+
+    checkout develop
+    merge release/v1.0.0
+
+    checkout main
+    branch hotfix/critical-fix
+    commit id: "fix-bug"
+
+    checkout main
+    merge hotfix/critical-fix tag: "v1.0.1"
+
+    checkout develop
+    merge hotfix/critical-fix
+```
+
+## Branch Structure
+
+### Main Branches
+
+- **`main`**: Production-ready code. Always contains the latest stable version. Should be deployable at any time.
+- **`develop`**: Feature integration branch. Contains the latest delivered development changes and serves as the starting point for all feature development.
+
+### Supporting Branches
+
+- **`feature/*`**: Feature development branches.
+    - **Origin**: `develop`
+    - **Merge back to**: `develop`
+    - **Naming**: `feature/descriptive-name` (e.g., `feature/user-authentication`)
+- **`release/*`**: Release preparation branches. Used to prepare new production releases, performing only minor bug fixes and release-oriented tasks like documentation generation.
+    - **Origin**: `develop`
+    - **Merge back to**: `main` and `develop`
+    - **Naming**: `release/v1.2.0`
+- **`hotfix/*`**: Emergency production bug fix branches. Used to quickly fix critical issues in the production environment.
+    - **Origin**: `main`
+    - **Merge back to**: `main` and `develop`
+    - **Naming**: `hotfix/critical-bug-fix`
+
+## Workflow
+
+### 1. Feature Development
+
+1.  **Create `feature` branch from `develop`**: 
+    ```bash
+    git fetch origin
+    git checkout -b feature/your-feature-name origin/develop
+    ```
+2.  **Develop the feature** and commit regularly.
+3.  **After development completion**, push the `feature` branch to remote and create a Pull Request to the `develop` branch.
+4.  After code review and continuous integration (CI) checks pass, **merge to `develop`**.
+
+### 2. Release Process
+
+The project recommends using automated release workflows, but the manual process is as follows:
+
+1.  **Create `release` branch from `develop`**: 
+    ```bash
+    git fetch origin
+    git checkout -b release/v1.0.0 origin/develop
+    ```
+2.  **Prepare release**: Update version numbers, generate documentation, etc.
+    ```bash
+    # Update version number in pyproject.toml
+    # Update server_version
+    # Sync version number to __init__.py
+    uv run python scripts/sync_version_minimal.py
+
+    # Get current test count and coverage statistics:
+    # Test count: uv run python -m pytest --collect-only -q | findstr /C:"collected"
+    # Coverage: uv run python -m pytest --cov=tree_sitter_analyzer --cov-report=term-missing --cov-report=json -x -q | findstr "TOTAL"
+
+    # Update documentation:
+    # - Update version number, test count, and coverage in README.md
+    # - Update version badge, test badge, coverage badge
+    # - Update version references in "Latest Quality Achievements" section
+    # - Update version references in test environment section
+    # - Update all other version references in documentation
+    # - Update translated versions README_zh.md and README_ja.md
+    # - If workflow changes exist, update GITFLOW_zh.md and GITFLOW_ja.md
+    # - Update CHANGELOG.md release details
+    ```
+3.  **Push `release` branch to remote to trigger PyPI release**:
+    ```bash
+    git checkout release/v1.0.0
+    git push origin release/v1.0.0
+    ```
+4.  **After PyPI release completion, merge to `main` and `develop`**:
+    ```bash
+    # Switch to main branch and merge
+    git checkout main
+    git merge release/v1.0.0
+    git tag -a v1.0.0 -m "Release v1.0.0" # Add version tag
+    git push origin main --tags
+
+    # Switch to develop branch and merge
+    git checkout develop
+    git merge release/v1.0.0
+    git push origin develop
+    ```
+5.  **Create GitHub Release**:
+    ```bash
+    # Create temporary release message file (avoid encoding and symbol errors)
+    cat > release_message.md << 'EOF'
+    ## v1.7.2 - File Output Optimization and ROO Rules Documentation
+
+    ### 🎯 New Features
+    - **File Output Optimization**: Added `suppress_output` and `output_file` parameters to MCP search tools, significantly reducing token consumption
+    - **Automatic Format Detection**: Intelligent file format selection (JSON/Markdown) based on content type
+    - **ROO Rules Documentation**: Added comprehensive tree-sitter-analyzer MCP optimization usage guide
+
+    ### 📊 Quality Metrics
+    - Test count: 2675 tests (100% pass rate)
+    - Code coverage: 78.85%
+    - New features: File output optimization significantly reduces AI conversation token consumption
+
+    ### 🔧 Technical Improvements
+    - Response size reduction up to 99% (when outputting large search results to files)
+    - Backward compatible, no impact on existing functionality usage
+    - Complete test coverage including file output optimization feature verification
+    EOF
+
+    # Create release using gh CLI
+    gh release create v1.7.2 \
+        --title "Release v1.7.2: File Output Optimization and ROO Rules Documentation" \
+        --notes-file release_message.md \
+        --target main
+
+    # Delete temporary file
+    rm release_message.md
+    ```
+6.  **Delete `release` branch**:
+    ```bash
+    # Delete local branch
+    git branch -d release/v1.0.0
+    # Delete remote branch
+    git push origin --delete release/v1.0.0
+    ```
+
+**Important Explanation**: This release workflow adopts a "PyPI-first" strategy, ensuring the package is successfully published before updating the main branch. This approach avoids the risk of code being published on GitHub but packages being unavailable on PyPI, providing a safer release process.
+
+### 3. Hotfix Process
+
+1.  **Create `hotfix` branch from `main`**: 
+    ```bash
+    git fetch origin
+    git checkout -b hotfix/critical-bug-fix origin/main
+    ```
+2.  **Fix the bug** and commit.
+3.  **Update version and documentation**:
+    ```bash
+    # Update version number in pyproject.toml (e.g., 1.0.0 -> 1.0.1)
+    # Update server_version
+    # Sync version number to __init__.py
+    uv run python scripts/sync_version_minimal.py
+
+    # Get current test count and coverage statistics:
+    # Test count: uv run python -m pytest --collect-only -q | findstr /C:"collected"
+    # Coverage: uv run python -m pytest --cov=tree_sitter_analyzer --cov-report=term-missing --cov-report=json -x -q | findstr "TOTAL"
+
+    # Update documentation:
+    # - Add hotfix details to CHANGELOG.md
+    # - Update version number, test count, and coverage in README.md
+    # - Update version badge, test badge, coverage badge
+    # - Update version references in "Latest Quality Achievements" section
+    # - Update version references in test environment section
+    # - Update all other version references in documentation
+    # - Update translated versions README_zh.md and README_ja.md
+    # - If workflow changes exist, update GITFLOW_zh.md and GITFLOW_ja.md
+    ```
+4.  **Push `hotfix` branch to remote to trigger PyPI release**:
+    ```bash
+    git checkout hotfix/critical-bug-fix
+    git push origin hotfix/critical-bug-fix
+    ```
+
+5.  **After PyPI release completion, merge to `main` and `develop`**:
+    ```bash
+    # Switch to main branch and merge
+    git checkout main
+    git merge hotfix/critical-bug-fix
+    git tag -a v1.0.1 -m "Hotfix v1.0.1" # Add fix version tag
+    git push origin main --tags
+
+    # Switch to develop branch and merge
+    git checkout develop
+    git merge hotfix/critical-bug-fix
+    git push origin develop
+    ```
+6.  **Create GitHub Release**:
+    ```bash
+    # Create temporary hotfix release message file
+    cat > hotfix_release_message.md << 'EOF'
+    ## v1.0.1 - Emergency Fix
+
+    ### 🐛 Fix Details
+    - Fixed critical production environment issue
+    - Improved system stability and security
+
+    ### 📊 Quality Metrics
+    - All tests passing
+    - Emergency fix verification completed
+
+    ### ⚡ Deployment Notes
+    - This version is an emergency fix, immediate deployment to production environment recommended
+    - Verified through complete testing
+    EOF
+
+    # Create hotfix release using gh CLI
+    gh release create v1.0.1 \
+        --title "Hotfix v1.0.1: Critical Production Fix" \
+        --notes-file hotfix_release_message.md \
+        --target main
+
+    # Delete temporary file
+    rm hotfix_release_message.md
+    ```
+7.  **Delete `hotfix` branch**:
+    ```bash
+    # Delete local branch
+    git branch -d hotfix/critical-bug-fix
+    # Delete remote branch
+    git push origin --delete hotfix/critical-bug-fix
+    ```
+
+**Important Explanation**: This hotfix workflow also adopts the "PyPI-first" strategy, updating the main branch after successful package release to avoid the risk of emergency fix code being published but packages being unavailable.
+
+**Note**: According to the actual automated workflow, hotfix branches **do** automatically trigger PyPI releases. However, this may cause version conflicts, so it's recommended to ensure version numbers are correctly updated before using hotfix branches.
+
+## Automation Workflows
+
+### Develop Branch Automation (`develop-automation.yml`)
+When code is pushed to the `develop` branch, automatically executes:
+
+1. **Test Job**:
+   - Run complete test suite using pytest with detailed traceback and failure limits
+   - Generate coverage reports (XML and terminal formats)
+   - Upload coverage to Codecov
+
+2. **Build Job**:
+   - Build Python package using `python -m build`
+   - Validate package using `twine check`
+   - Upload build artifacts (retained for 1 day)
+
+3. **Create Release PR Job**:
+   - Automatically create PR from develop to main
+   - Include quality metrics and test results
+   - Ready for production deployment
+
+**Important**: Pushes to develop branch do **not** trigger PyPI deployment.
+
+### Release Branch Automation (`release-automation.yml`)
+When code is pushed to `release/v*` branches, automatically executes:
+
+1. **Test Job**:
+   - Run complete test suite using pytest with detailed traceback and failure limits
+   - Generate coverage reports (XML and terminal formats)
+   - Upload coverage to Codecov
+
+2. **Build and Deploy Job**:
+   - Build Python package
+   - Validate package using `twine check`
+   - **Deploy to PyPI using `twine upload`**
+
+3. **Create Main PR Job**:
+   - Create PR to main branch after successful PyPI deployment
+   - Marked as critical hotfix, ready for immediate production
+
+### Hotfix Branch Automation (`hotfix-automation.yml`)
+When code is pushed to `hotfix/*` branches, automatically executes:
+
+1. **Test Job**:
+   - Run complete test suite using pytest with detailed traceback and failure limits
+   - Generate coverage reports (XML and terminal formats)
+
+2. **Build and Deploy Job**:
+   - Build Python package
+   - Validate package using `twine check`
+   - **Deploy to PyPI using `twine upload`**
+
+3. **Create Main PR Job**:
+   - Create PR to main branch after successful PyPI deployment
+   - Marked as critical hotfix, ready for immediate production
+
+**Important**: According to the actual automated workflow, hotfix branches **do** automatically trigger PyPI deployment, same as release branches. This may cause version conflicts, so careful use of hotfix branches is recommended.
+
+### CI Workflow (`ci.yml`)
+Runs on all branches (`main`, `develop`, `hotfix/*`, `feature/*`, `release/*`) and PRs:
+
+1. **Quality Check Job**:
+   - Multi-Python version testing (3.10, 3.11, 3.12, 3.13)
+   - Code quality checks using `check_quality.py`
+
+2. **Test Matrix Job**:
+   - Cross-platform testing (Ubuntu, Windows, macOS)
+   - Multi-Python version compatibility testing
+
+**PyPI Deployment Strategy**: Both `release/*` and `hotfix/*` branches automatically deploy to PyPI. However, hotfix branches may cause version conflicts, so careful usage is recommended.
+
+---
+
+*This English documentation aims to help understand the core concepts in [`GITFLOW.md`](GITFLOW.md). For more detailed information on automation workflows, quality checks, and CI/CD integration, please refer to the original [GITFLOW.md](GITFLOW.md) file.*