Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 15 additions & 96 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

---

Expand All @@ -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).**

---

Expand Down Expand Up @@ -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

---

Expand Down Expand Up @@ -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*
*Last Updated: February 2026*
12 changes: 11 additions & 1 deletion docs/development/basic_design.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).*
## 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*
46 changes: 4 additions & 42 deletions docs/development/conventions.md
Original file line number Diff line number Diff line change
@@ -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 <noreply@anthropic.com>
```

### 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

---

Expand Down Expand Up @@ -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*
*Last Updated: February 2026*
27 changes: 0 additions & 27 deletions docs/development/tasks.md

This file was deleted.

Loading