From 18f446b3bb6ebde0fd5931f2b496aeda8b5b790f Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Feb 2026 10:12:03 +0000 Subject: [PATCH] [Docs] Streamline documentation by removing redundant content MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CLAUDE.md: Remove Pre-Development Checklist, directory structure (link to detail_design.md instead), simplify Development Workflow section - conventions.md: Remove Task-Based Development Protocol and Task Status Management (superseded by Claude Code plan mode), simplify Git Commit Protocol - tasks.md: Merge Future Work into basic_design.md and delete file - Total reduction: ~136 lines (~30%) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 111 +++++-------------------------- docs/development/basic_design.md | 12 +++- docs/development/conventions.md | 46 ++----------- docs/development/tasks.md | 27 -------- 4 files changed, 30 insertions(+), 166 deletions(-) delete mode 100644 docs/development/tasks.md diff --git a/CLAUDE.md b/CLAUDE.md index 7a1176a..a4d580f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,18 +22,11 @@ This is an automated benchmark system for optimization solvers (LP, QP, SOCP, SD > **⚠️ DISPATCH HUB NOTICE:** > **CLAUDE.md serves as a navigation hub. All detailed design content is in dedicated documents below.** -### **REQUIRED READING** (Read these documents carefully before any development): +### **REQUIRED READING**: -1. **[📋 Basic Design](docs/development/basic_design.md)** - Project vision, design philosophy, and system overview -2. **[🏗️ Detailed Design](docs/development/detail_design.md)** - Complete technical architecture, implementation specifications, and code examples -3. **[📝 Development Conventions](docs/development/conventions.md)** - Coding standards, git protocols, and engineering guidelines -4. **[✅ Current Tasks](docs/development/tasks.md)** - Active development tasks for current phase - -### **Quick Reference**: -- **[🚀 Setup Guides](docs/guides/)** - Installation and configuration guides -- **[📊 README.md](README.md)** - Project overview and quick start - -> **📖 For system architecture, solver configurations, and implementation details, always refer to the dedicated design documents above rather than this file.** +1. **[📋 Basic Design](docs/development/basic_design.md)** - Project vision, design philosophy, system overview +2. **[🏗️ Detailed Design](docs/development/detail_design.md)** - Technical architecture, directory structure, implementation specs +3. **[📝 Development Conventions](docs/development/conventions.md)** - Coding standards and engineering guidelines --- @@ -47,41 +40,14 @@ This is an automated benchmark system for optimization solvers (LP, QP, SOCP, SD --- -## 🔧 Development Environment Context +## 🔧 Development Environment -### Core Architecture - **Platform**: GitHub Actions CI/CD with GitHub Pages deployment -- **Languages**: Python 3.12+, MATLAB R2024+ -- **Storage**: SQLite database with structured schema -- **Reporting**: Bootstrap 5 + Chart.js interactive dashboards - -### Key Directories -``` -├── config/ # YAML configuration files -├── scripts/ # Core system implementation -│ ├── benchmark/ # Benchmark execution engine -│ ├── solvers/ # Solver implementations -│ │ ├── python/ # Python solver interfaces -│ │ └── matlab/ # MATLAB interfaces -│ ├── data_loaders/ # Problem format loaders -│ │ ├── python/ # Python loaders (MAT/DAT) -│ │ └── matlab/ # MATLAB loaders -│ ├── utils/ # Problem structure analysis, version detection -│ ├── database/ # Data models and storage -│ └── reporting/ # HTML generation and data publishing -├── problems/ # Benchmark problem files -│ ├── DIMACS/ # External DIMACS library (47 problems) -│ └── SDPLIB/ # External SDPLIB library (92 problems) -├── database/ # SQLite database files -│ └── results.db # Benchmark results storage -├── docs/ # Generated reports (GitHub Pages) -└── requirements.txt # Python dependencies (single file) -``` - -### Current Capabilities -**System Status**: Research Tool Complete with **11 solvers** (9 Python + 2 MATLAB) across **139 problems** (DIMACS + SDPLIB) +- **Languages**: Python 3.12+, MATLAB R2024+ (optional) +- **Storage**: SQLite database (`database/results.db`) +- **Reports**: `docs/pages/` (Bootstrap 5 + Chart.js) -**For detailed solver coverage and problem statistics, see [basic_design.md](docs/development/basic_design.md).** +**For directory structure and architecture details, see [detail_design.md](docs/development/detail_design.md).** --- @@ -116,27 +82,12 @@ matlab -batch "setup_matlab_solvers" --- -## 🔄 Development Workflow +## 🔄 Development Principles -### **MANDATORY WORKFLOW** (Follow exactly): -1. **Read Documentation**: Study [basic_design.md](docs/development/basic_design.md), [detail_design.md](docs/development/detail_design.md), and [conventions.md](docs/development/conventions.md) -2. **Check Current Tasks**: Review [tasks.md](docs/development/tasks.md) for active development tasks -3. **Follow Task Protocol**: Complete one task at a time following priority order -4. **Test Implementation**: Validate using task-specific test criteria -5. **Commit Changes**: Use established git commit protocol after user confirmation - -### Task-Based Development -- **Sequential Execution**: Complete one task at a time -- **Test-Driven Validation**: Each task includes specific test criteria -- **Documentation-First**: Update docs for all features -- **User Review**: Stop and wait for approval after each task - -### MVP Development Principles -- **Minimal Viable Product**: Always implement the simplest solution that meets the requirement -- **No Extra Features**: Do not add functionality beyond what is explicitly requested -- **User Confirmation Required**: Before implementing any feature that seems necessary but wasn't explicitly requested, ask the user for confirmation -- **YAGNI Principle**: "You Aren't Gonna Need It" - implement only what is needed right now -- **Incremental Development**: Build the core functionality first, then iterate based on user feedback +- **MVP First**: Implement the simplest solution that meets the requirement +- **YAGNI**: Do not add functionality beyond what is explicitly requested +- **User Confirmation**: Ask before implementing features not explicitly requested +- **Commit on Request**: Only commit changes when user explicitly asks --- @@ -190,36 +141,4 @@ Quick reference: Python solvers via `python_interface.py`, MATLAB solvers via `{ --- -## 📋 For LLM Agents: Pre-Development Checklist - -> **🚨 CRITICAL: CLAUDE.md is a dispatch hub only. All design content is in dedicated documents.** - -**BEFORE starting any coding task, confirm you have:** - -- [ ] Read [@docs/development/basic_design.md](docs/development/basic_design.md) for project vision, design philosophy, and system overview -- [ ] Read [@docs/development/detail_design.md](docs/development/detail_design.md) for complete technical architecture and implementation details -- [ ] Read [@docs/development/conventions.md](docs/development/conventions.md) for coding standards and protocols -- [ ] Reviewed [tasks.md](docs/development/tasks.md) for current development context -- [ ] Understood that all design decisions and technical details are documented in the linked design files, not in CLAUDE.md - -**🚨 CRITICAL CONSTRAINTS CHECKLIST (MUST VERIFY):** - -- [ ] **Requirements Management**: Confirmed to use ONLY the existing `requirements.txt` (do not create requirements/ directory) -- [ ] **CI/CD Philosophy**: Understood that CI should fail when problems exist (no graceful degradation) -- [ ] **File Structure**: Verified existing file locations (docs/pages/, database/, config/) before modification -- [ ] **GitHub Workflows**: Ensured any workflow changes reference existing `requirements.txt` file -- [ ] **Solver Dependencies**: Acknowledged that solver installation failures should cause CI to fail - -**Failure to read these documents or violating critical constraints will result in implementation that doesn't align with project standards and philosophy.** - ---- - - -## 📝 Development Memories - -### Task Management -- **Reflection Note**: Please reflect the latest situation into task.md after completing each task. - -*This dispatch document provides entry point context only. All implementation details, coding standards, and development protocols are documented in the linked files above.* - -*Last Updated: July 2025* \ No newline at end of file +*Last Updated: February 2026* \ No newline at end of file diff --git a/docs/development/basic_design.md b/docs/development/basic_design.md index 8ed650d..46563f9 100644 --- a/docs/development/basic_design.md +++ b/docs/development/basic_design.md @@ -181,4 +181,14 @@ python main.py --all --timeout 600 # 10-minute timeout for large SDP problems --- -*This basic design establishes the conceptual framework and development approach. For implementation details, see [detail_design.md](detail_design.md).* \ No newline at end of file +## Future Work + +### Potential Enhancements +- **QP/LP Benchmark Expansion**: Add more LP and QP benchmark problems from standard libraries +- **Additional Solver Backends**: Include more solver backends for broader comparison + +--- + +*This basic design establishes the conceptual framework and development approach. For implementation details, see [detail_design.md](detail_design.md).* + +*Last Updated: February 2026* \ No newline at end of file diff --git a/docs/development/conventions.md b/docs/development/conventions.md index bd23bf2..43322ff 100644 --- a/docs/development/conventions.md +++ b/docs/development/conventions.md @@ -1,60 +1,22 @@ # Development Conventions and Standards -This document establishes coding standards, development protocols, and engineering guidelines for the optimization solver benchmark system. +Coding standards and engineering guidelines for the optimization solver benchmark system. --- -## Development Workflow - -### Task-Based Development Protocol -1. **Sequential Task Execution**: Complete one task at a time following the priority order in [tasks.md](tasks.md) -2. **Implementation Phase**: Follow task-specific requirements and implementation plans -3. **Testing Phase**: Validate implementation using provided test criteria -4. **Review Phase**: Stop and wait for user approval after each task completion -5. **Commit Phase**: Commit changes only after user confirmation -6. **Proceed**: Move to next task once approved - -### Task Status Management -- **✅ Completed**: Task finished and tested successfully -- **🚧 In Progress**: Currently being worked on (limit to ONE task at a time) -- **⏳ Pending**: Not yet started, waiting for dependencies -- **❌ Blocked**: Waiting for external dependencies or decisions - ---- - -## Git Commit Protocol - -### Commit Message Format -Follow this standardized format for all commits: +## Git Commit Format ``` [Type] Brief description (50 chars max) - Specific changes made -- Files modified -- Impact on system functionality -- Test results if applicable 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude ``` -### Commit Types -- **Complete Task X**: Major task completion with full implementation -- **Fix**: Bug fixes and error corrections -- **Add**: New features or capabilities -- **Update**: Enhancements to existing functionality -- **Refactor**: Code restructuring without functional changes -- **Docs**: Documentation-only changes -- **Test**: Testing-related changes - -### Commit Best Practices -1. **Atomic Commits**: Each commit should represent a single, complete change -2. **Descriptive Messages**: Clearly explain what was changed and why -3. **Test Before Commit**: Ensure all functionality works before committing -4. **Reference Tasks**: Include task numbers when applicable -5. **Clean History**: Avoid "WIP" or temporary commits in main branch +**Commit Types**: Fix, Add, Update, Refactor, Docs, Test --- @@ -491,4 +453,4 @@ pytest tests/unit/test_solver.py::test_specific_function -v -s *These conventions ensure consistent, maintainable, and high-quality code across the optimization solver benchmark system. All contributors should follow these standards to maintain project coherence.* -*Last Updated: December 2025* \ No newline at end of file +*Last Updated: February 2026* \ No newline at end of file diff --git a/docs/development/tasks.md b/docs/development/tasks.md deleted file mode 100644 index e682a8a..0000000 --- a/docs/development/tasks.md +++ /dev/null @@ -1,27 +0,0 @@ -# Current Tasks - -## Status: All Tasks Complete ✅ - -All development tasks have been successfully completed. The optimization solver benchmark system is now fully operational with: - -- **11 solvers** (9 Python + 2 MATLAB) -- **139+ problems** from external libraries (DIMACS + SDPLIB) -- **Production-ready reporting** with interactive HTML dashboards -- **Complete documentation** and local development workflow - ---- - -## Future Work - -### Potential Enhancements - -**QP/LP Benchmark Expansion** -- Add more Linear Programming (LP) and Quadratic Programming (QP) benchmark problems -- Expand coverage of standard optimization problem libraries -- Include additional LP/QP solver backends for broader comparison - -This enhancement would strengthen the benchmark coverage for the most commonly used optimization problem types in industry applications. - ---- - -*Last Updated: August 2025*