1 files changed, 54 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..40e0fb0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+```bash
+# Build the project
+cd sorsyl && dune build
+
+# Run tests
+cd sorsyl && dune test
+
+# Clean build artifacts
+cd sorsyl && dune clean
+
+# Install dependencies (if needed)
+opam install --deps-only .
+```
+
+## Project Architecture
+
+Sorsyl is an OCaml library for phonological analysis, specifically focused on sonority calculation for IPA (International Phonetic Alphabet) segments.
+
+### Core Components
+
+- **lib/sonority.ml**: Main sonority calculation logic using a decision tree based on phonological features (scale 1-9: voiceless stops to low vowels)
+- **lib/feature.ml**: Phonological feature definitions and segment representation
+- **lib/ipa_table.ml**: CSV data loading and IPA segment lookup functionality
+
+### Data Files
+
+The `data/` directory contains:
+- `ipa_all.csv`: Main IPA character database with phonological features
+- Various YAML configuration files for linguistic data (ASJP, diacritic definitions, etc.)
+
+### Decision Tree Sonority Scale
+
+The sonority calculation uses phonological features to classify segments:
+- 9: Low vowels (most sonorous)
+- 8: High vowels  
+- 7: Glides/approximants
+- 6: Liquids
+- 5: Nasals
+- 4: Voiced fricatives
+- 3: Voiceless fricatives
+- 2: Voiced stops
+- 1: Voiceless stops (least sonorous)
+
+### Development Environment
+
+Uses devenv.nix for development environment setup with OCaml toolchain and dependencies (csv, base, stdio libraries).
+
+The main executable (bin/main.ml) is currently incomplete - contains only a failwith placeholder.
+\ No newline at end of file