From 54b3b09a882df3a92eb3a2cbb6f4edaf27f1b8ee Mon Sep 17 00:00:00 2001
From: Your Name <j@842.be>
Date: Tue, 2 Sep 2025 17:26:10 +1200
Subject: [PATCH] Add CLAUDE.md

---
 CLAUDE.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..625355a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+dshash is a simple SHA256 hashing library and command-line utility with no external dependencies. It consists of:
+- **Library** (`src/`): Pure C++ SHA256 implementation that can hash strings, files, and directory trees
+- **Utility** (`dshash/`): Command-line tool for hashing files and directories
+- **Tests** (`tests/`): Comprehensive test suite including NIST vectors and system comparisons
+
+## Build Commands
+
+```bash
+# Build the utility (from project root)
+cd dshash && make clean && make
+
+# Alternative: Use the build script
+./build.sh  # Creates output/dshash
+
+# Build just the library for testing
+cd tests
+g++ -std=c++17 -o test_lib test_lib.cpp ../src/dshash.cpp -I../src
+```
+
+## Test Commands
+
+```bash
+# Run all tests (recommended)
+./test.sh  # or ./tests/test.sh
+
+# The test suite includes:
+# - Library unit tests
+# - Utility tests  
+# - System sha256sum comparisons
+# - NIST test vectors
+# - Stress tests
+# - Edge cases
+# - Performance benchmarks
+
+# Build and run a specific test
+cd tests
+g++ -std=c++17 -o test_lib test_lib.cpp ../src/dshash.cpp -I../src && ./test_lib
+g++ -std=c++17 -O2 -o test_stress test_stress.cpp ../src/dshash.cpp -I../src && ./test_stress
+```
+
+## Architecture
+
+### SHA256 Implementation
+The DSHash class (`src/dshash.hpp`) implements SHA256 from scratch:
+- Uses standard SHA256 constants and operations (Ch, Maj, Σ0, Σ1, etc.)
+- Processes data in 64-byte blocks
+- Returns hash as `std::array<uint8_t, 32>` or hex string
+- No external crypto library dependencies
+
+### Key Design Decisions
+1. **Single responsibility**: Library handles hashing only, utility handles CLI
+2. **Directory hashing**: Recursively hashes all files in sorted order for deterministic results
+3. **Static linking**: Utility is statically linked for portability (`-static` flag in Makefile)
+4. **C++17**: Uses `std::filesystem` for cross-platform file operations
+
+### Testing Strategy
+The test suite (`tests/test.sh`) validates correctness by:
+- Comparing output with system `sha256sum` for various inputs
+- Verifying against official NIST test vectors
+- Testing edge cases (empty files, special characters, padding boundaries)
+- Stress testing with large files and many operations
+
+## Development Guidelines
+
+When modifying the SHA256 implementation:
+- Ensure all NIST test vectors still pass
+- Verify against system sha256sum for any new test cases
+- The implementation follows FIPS 180-4 specification
+
+When adding features to the utility:
+- Maintain backward compatibility with existing command-line interface
+- Keep the utility simple and focused on hashing
+- Preserve static linking for distribution
\ No newline at end of file