begriffs open source - ai-unix/blob - CLAUDE.md

   1 # CLAUDE.md
   2
   3 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
   4
   5 ## Development Commands
   6
   7 ### Testing
   8 ```bash
   9 # Run all tests
  10 cd tests && ./run-tests.sh
  11
  12 # Run specific test suites
  13 ./run-tests.sh --basic      # Only deterministic tests
  14 ./run-tests.sh --format     # Only format validation tests
  15 ./run-tests.sh --semantic   # Only semantic tests (requires claude)
  16 ./run-tests.sh --no-semantic # Skip semantic tests
  17 ```
  18
  19 ### Prerequisites
  20 - Claude CLI tool must be installed and configured for semantic tests
  21 - Python3 required for JSON validation in format tests
  22 - All tools must be built and executable in the root directory
  23
  24 ## Architecture
  25
  26 ### Core Design Philosophy
  27 The codebase follows a **composable functional architecture** with strict separation of concerns:
  28
  29 - **Pure functions** for validation and data processing (no side effects)
  30 - **Controlled side effects** isolated to specific I/O functions
  31 - **Standardized error handling** with consistent exit codes across all tools
  32 - **Shared common library** (`ai-common`) containing all reusable functionality
  33
  34 ### Tool Structure
  35 Each AI tool (`ai-grep`, `ai-cut`, `ai-class`, `ai-test`, `ai-tr`) follows an identical pattern:
  36
  37 1. **Source common library**: `source "$SCRIPT_DIR/ai-common"`
  38 2. **Usage function**: `show_usage()` with tool-specific help
  39 3. **Prompt builder**: Tool-specific prompt construction function
  40 4. **Response processor**: Specialized processing for tool's output format
  41 5. **Validation function**: `validate_and_setup()` for arguments and environment
  42 6. **Main function**: Standard option parsing and execution flow
  43
  44 ### Exit Code Standards
  45 All tools use standardized exit codes from `ai-common`:
  46 - `0` - Success
  47 - `1` - No matches found
  48 - `2` - Usage/system error (invalid options, files not found)
  49 - `3` - LLM behavioral error (ambiguous patterns, context issues)
  50 - `4` - API/infrastructure error
  51 - `127` - Command not found (Claude CLI missing)
  52 - `130` - Interrupted
  53
  54 ### Common Library (`ai-common`)
  55 Contains three categories of functions:
  56
  57 1. **Pure Functions**: Validation, data processing, error message generation
  58 2. **I/O Functions**: Input processing, LLM execution, error printing
  59 3. **High-level Orchestration**: Dependency checking, file validation, option handling
  60
  61 ### Response Processing Strategy
  62 Each tool has specialized response processors to handle non-deterministic AI output:
  63 - **Filtering**: Remove explanatory text and AI chatter
  64 - **Format validation**: JSON, boolean, count, categorization formats
  65 - **Error recovery**: Standardized error messages for malformed responses
  66
  67 ### Testing Architecture
  68 Three-tier testing strategy accounting for AI non-determinism:
  69
  70 1. **Deterministic Tests** (`unit/test-basic.sh`): Exit codes, option parsing, file handling
  71 2. **Format Tests** (`unit/test-formats.sh`): Output format validation (JSON, TSV, etc.)
  72 3. **Semantic Tests** (`integration/test-semantic.sh`): Uses `ai-test` to validate AI output quality
  73
  74 ### LLM Integration Pattern
  75 All tools use the same LLM interaction pattern:
  76 1. Build structured prompt with critical requirements
  77 2. Execute via `claude` command with `--max-turns 1`
  78 3. Process response through tool-specific processors
  79 4. Handle errors with standardized error reporting
  80
  81 ## Key Implementation Notes
  82
  83 - **Signal Handling**: All tools handle SIGINT/SIGTERM gracefully
  84 - **Input Sources**: Support stdin, single file, or multiple files uniformly
  85 - **Early Exit Strategy**: Fail fast on validation errors, empty input, or LLM failures
  86 - **Modular Design**: Each function has single responsibility and clear interfaces
  87 - **Error Propagation**: Errors bubble up through return codes, not exceptions