# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Testing
```bash
# Run all tests
cd tests && ./run-tests.sh

# Run specific test suites
./run-tests.sh --basic      # Only deterministic tests
./run-tests.sh --format     # Only format validation tests  
./run-tests.sh --semantic   # Only semantic tests (requires claude)
./run-tests.sh --no-semantic # Skip semantic tests
```

### Prerequisites
- Claude CLI tool must be installed and configured for semantic tests
- Python3 required for JSON validation in format tests
- All tools must be built and executable in the root directory

## Architecture

### Core Design Philosophy
The codebase follows a **composable functional architecture** with strict separation of concerns:

- **Pure functions** for validation and data processing (no side effects)
- **Controlled side effects** isolated to specific I/O functions
- **Standardized error handling** with consistent exit codes across all tools
- **Shared common library** (`ai-common`) containing all reusable functionality

### Tool Structure
Each AI tool (`ai-grep`, `ai-cut`, `ai-class`, `ai-test`, `ai-tr`) follows an identical pattern:

1. **Source common library**: `source "$SCRIPT_DIR/ai-common"`
2. **Usage function**: `show_usage()` with tool-specific help
3. **Prompt builder**: Tool-specific prompt construction function
4. **Response processor**: Specialized processing for tool's output format
5. **Validation function**: `validate_and_setup()` for arguments and environment
6. **Main function**: Standard option parsing and execution flow

### Exit Code Standards
All tools use standardized exit codes from `ai-common`:
- `0` - Success
- `1` - No matches found
- `2` - Usage/system error (invalid options, files not found)
- `3` - LLM behavioral error (ambiguous patterns, context issues)
- `4` - API/infrastructure error
- `127` - Command not found (Claude CLI missing)
- `130` - Interrupted

### Common Library (`ai-common`)
Contains three categories of functions:

1. **Pure Functions**: Validation, data processing, error message generation
2. **I/O Functions**: Input processing, LLM execution, error printing
3. **High-level Orchestration**: Dependency checking, file validation, option handling

### Response Processing Strategy
Each tool has specialized response processors to handle non-deterministic AI output:
- **Filtering**: Remove explanatory text and AI chatter
- **Format validation**: JSON, boolean, count, categorization formats
- **Error recovery**: Standardized error messages for malformed responses

### Testing Architecture
Three-tier testing strategy accounting for AI non-determinism:

1. **Deterministic Tests** (`unit/test-basic.sh`): Exit codes, option parsing, file handling
2. **Format Tests** (`unit/test-formats.sh`): Output format validation (JSON, TSV, etc.)  
3. **Semantic Tests** (`integration/test-semantic.sh`): Uses `ai-test` to validate AI output quality

### LLM Integration Pattern
All tools use the same LLM interaction pattern:
1. Build structured prompt with critical requirements
2. Execute via `claude` command with `--max-turns 1`
3. Process response through tool-specific processors
4. Handle errors with standardized error reporting

## Key Implementation Notes

- **Signal Handling**: All tools handle SIGINT/SIGTERM gracefully
- **Input Sources**: Support stdin, single file, or multiple files uniformly
- **Early Exit Strategy**: Fail fast on validation errors, empty input, or LLM failures
- **Modular Design**: Each function has single responsibility and clear interfaces
- **Error Propagation**: Errors bubble up through return codes, not exceptions