ai-vision-mcp: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. Please always use context7 MCP, web search, or web fetch for additional information when fixing bugs or implementing new features.

CRITICAL: Documentation Maintenance Requirements

BEFORE starting any coding work:

1. ALWAYS create a plan document in the docs/llm_logs/ folder before writing any code
2. ALWAYS update README.md when introducing changes that affect:
   • New MCP tools or parameters
   • Environment variables
   • Configuration options
   • Installation instructions
   • Breaking changes
3. ALWAYS update docs/SPEC.md when introducing changes that affect:
   • Architecture modifications
   • New provider implementations
   • API interface changes
   • File handling logic
   • Error handling patterns

Planning Process:

• Create plan documents in docs/llm_logs/ folder (e.g., docs/llm_logs/feature-name-plan.md)
• Include architecture decisions, implementation steps, and testing strategy
• Reference this plan in your commit messages
• Keep plan documents as documentation of implementation decisions

Solution Planning Best Practices:

• ALWAYS present at least 3 options when planning solutions to problems
• Analyze trade-offs: effort vs. benefit, maintainability vs. speed, risk vs. reward
• Provide clear recommendations with rationale (e.g., "Option 2 recommended because...")
• Consider: quick fixes, balanced approaches, and comprehensive solutions
• Include effort estimates, risk assessments, and rollback strategies for each option
• Use structured format: Option 1 (Simple), Option 2 (Balanced), Option 3 (Comprehensive)

Example Planning Structure:

## Plan: [Problem Description]

### Option 1: Quick Fix (15 min)
- ✅ Minimal change, fastest implementation
- ❌ Technical debt, not future-proof
- **When to use**: Urgent hotfixes, time pressure

### Option 2: Balanced Solution (45 min) - RECOMMENDED
- ✅ Good maintainability, moderate effort
- ✅ Addresses root cause, extensible
- ❌ Longer implementation time
- **When to use**: Most production scenarios

### Option 3: Comprehensive Refactor (2 hours)
- ✅ Perfect architecture, future-proof
- ❌ High effort, potential for new bugs
- **When to use**: Major feature additions, architectural improvements

### Recommendation: Option 2
**Rationale**: Balances immediate needs with long-term maintainability...