diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..783dafa
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+JBZoo PHPUnit is a PHP library that provides a collection of short assertion aliases and testing utilities built on top of PHPUnit. The library extends `PHPUnit\Framework\TestCase` with convenient function aliases for common test assertions.
+
+## Development Commands
+
+### Essential Commands
+- `make update` - Install/update all dependencies via Composer
+- `make test` - Run PHPUnit tests
+- `make codestyle` - Run all linters and code quality checks
+- `make test-all` - Run complete test suite including tests, reports, and codestyle
+
+### Testing Commands
+- `vendor/bin/phpunit` - Run PHPUnit directly
+- `vendor/bin/phpunit tests/PHPUnitAliasesTest.php` - Run specific test file
+- `make server-start` - Start test web servers (fake and PHPUnit servers on ports 8888/8889)
+- `make server-stop` - Stop test web servers
+
+### Code Quality
+- `make codestyle` - Run linters (includes PHPStan, PHP CS Fixer, etc.)
+- `make report-all` - Generate all reports including coverage
+
+## Architecture
+
+### Core Components
+
+1. **Base Test Class** (`src/PHPUnit.php`)
+   - Simple abstract class extending `PHPUnit\Framework\TestCase`
+   - All test classes should extend `JBZoo\PHPUnit\PHPUnit`
+
+2. **Function Libraries** (`src/functions/`)
+   - `aliases.php` - Short assertion functions (isTrue, isFalse, is, etc.)
+   - `defines.php` - Path definitions and autoloader setup
+   - `tools.php` - Additional utility functions
+   - All functions are auto-loaded via composer.json files section
+
+3. **Test Infrastructure**
+   - `tests/` - All test files following `*Test.php` naming convention
+   - `tests/fixtures/` - Test fixtures and HTTP root for web server tests
+   - `tests/web-root/` - Web root for PHPUnit server tests
+   - `bin/` - Server scripts for HTTP testing
+
+### Key Features
+
+- **Short Assertion Aliases**: Functions like `isTrue()`, `isFalse()`, `is()`, `isEmpty()` instead of verbose PHPUnit methods
+- **Web Server Testing**: Built-in support for testing HTTP requests with fake servers
+- **Coverage Support**: Integrated code coverage reporting (HTML, XML, Clover formats)
+
+### File Organization
+
+```
+src/
+├── PHPUnit.php           # Base test class
+├── functions/            # Function libraries (auto-loaded)
+│   ├── aliases.php      # Assertion aliases
+│   ├── defines.php      # Constants and paths
+│   └── tools.php        # Utility functions
+└── CovCatcher.php       # Coverage utilities
+```
+
+### Testing Patterns
+
+Test classes should:
+- Extend `JBZoo\PHPUnit\PHPUnit`
+- Use short assertion aliases (e.g., `isTrue($value)` instead of `$this->assertTrue($value)`)
+- Follow naming convention `*Test.php`
+- Be placed in `tests/` directory
+
+Example test structure:
+```php
+namespace JBZoo\PHPUnit;
+
+class MyFeatureTest extends PHPUnit
+{
+    public function testSomething()
+    {
+        isTrue(true);
+        is(1, 1);
+        isEmpty([]);
+    }
+}
+```
+
+## Dependencies
+
+- PHP 8.2+ required
+- PHPUnit ^9.6.29 as core testing framework
+- JBZoo toolbox ecosystem (codestyle, markdown, etc.)
+- Development dependencies managed via jbzoo/toolbox-dev
+
+## CI/CD
+
+GitHub Actions workflow runs:
+- PHPUnit tests across PHP 8.1, 8.2, 8.3
+- Code quality checks (linters)
+- Coverage reporting to Coveralls
+- Matrix testing with different Composer flags (--prefer-lowest)
\ No newline at end of file
diff --git a/README.md b/README.md
index 8a55be1..9599ffa 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,17 @@
 # JBZoo / PHPUnit
 
-[![CI](https://github.com/JBZoo/PHPUnit/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/JBZoo/PHPUnit/actions/workflows/main.yml?query=branch%3Amaster)    [![Coverage Status](https://coveralls.io/repos/github/JBZoo/PHPUnit/badge.svg?branch=master)](https://coveralls.io/github/JBZoo/PHPUnit?branch=master)    [![Psalm Coverage](https://shepherd.dev/github/JBZoo/PHPUnit/coverage.svg)](https://shepherd.dev/github/JBZoo/PHPUnit)    [![Psalm Level](https://shepherd.dev/github/JBZoo/PHPUnit/level.svg)](https://shepherd.dev/github/JBZoo/PHPUnit)    [![CodeFactor](https://www.codefactor.io/repository/github/jbzoo/phpunit/badge)](https://www.codefactor.io/repository/github/jbzoo/phpunit/issues)    
+[![CI](https://github.com/JBZoo/PHPUnit/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/JBZoo/PHPUnit/actions/workflows/main.yml?query=branch%3Amaster)    [![Coverage Status](https://coveralls.io/repos/github/JBZoo/PHPUnit/badge.svg?branch=master)](https://coveralls.io/github/JBZoo/PHPUnit?branch=master)    [![Psalm Coverage](https://shepherd.dev/github/JBZoo/PHPUnit/coverage.svg)](https://shepherd.dev/github/JBZoo/PHPUnit)    [![Psalm Level](https://shepherd.dev/github/JBZoo/PHPUnit/level.svg)](https://shepherd.dev/github/JBZoo/PHPUnit)    [![CodeFactor](https://www.codefactor.io/repository/github/jbzoo/phpunit/badge)](https://www.codefactor.io/repository/github/jbzoo/phpunit/issues)
 [![Stable Version](https://poser.pugx.org/jbzoo/phpunit/version)](https://packagist.org/packages/jbzoo/phpunit/)    [![Total Downloads](https://poser.pugx.org/jbzoo/phpunit/downloads)](https://packagist.org/packages/jbzoo/phpunit/stats)    [![Dependents](https://poser.pugx.org/jbzoo/phpunit/dependents)](https://packagist.org/packages/jbzoo/phpunit/dependents?order_by=downloads)    [![GitHub License](https://img.shields.io/github/license/jbzoo/phpunit)](https://github.com/JBZoo/PHPUnit/blob/master/LICENSE)
 
+PHPUnit toolbox with short assertion aliases and useful testing utilities. This library provides a more concise and readable way to write tests by offering shorter function names for common PHPUnit assertions.
 
+## Features
+
+- **Short assertion aliases** - Use `isTrue()` instead of `$this->assertTrue()`
+- **Extended assertions** - Additional assertions for emails, dates, amounts, file contents
+- **Environment detection** - Detect if running under TeamCity, Travis, PhpStorm
+- **Built-in utilities** - Tools for test organization and debugging
+- **PHP 8.2+ support** - Modern PHP features and strict typing
 
 ## Installation
 
@@ -11,8 +19,7 @@
 composer require jbzoo/phpunit --dev
 ```
 
-
-## Usage
+## Quick Start
 
 ```php
 namespace JBZoo\PHPUnit;
@@ -86,6 +93,73 @@ class PackageTest extends PHPUnit
 }
 ```
 
-### License
+## Available Assertions
+
+### Basic Assertions
+- `is($expected, $actual)` - assertEquals
+- `isNot($expected, $actual)` - assertNotEquals
+- `isSame($expected, $actual)` - assertSame
+- `isNotSame($expected, $actual)` - assertNotSame
+- `isTrue($value)` - assertTrue
+- `isFalse($value)` - assertFalse
+- `isNull($value)` - assertNull
+- `isNotNull($value)` - assertNotNull
+- `isEmpty($value)` - assertEmpty
+- `isNotEmpty($value)` - assertNotEmpty
+
+### Arrays & Objects
+- `isKey($key, $array)` - assertArrayHasKey
+- `isNotKey($key, $array)` - assertArrayNotHasKey
+- `isAttr($name, $object)` - Check object attribute exists
+- `isNotAttr($name, $object)` - Check object attribute doesn't exist
+- `isClass($expected, $actual)` - assertInstanceOf
+- `isCount($expected, $countable)` - assertCount
+
+### Strings & RegExp
+- `isLike($pattern, $value)` - assertMatchesRegularExpression
+- `isNotLike($pattern, $value)` - assertDoesNotMatchRegularExpression
+- `isContain($needle, $haystack)` - String contains check
+- `isNotContain($needle, $haystack)` - String doesn't contain check
+
+### Files & Filesystem
+- `isFile($path)` - assertFileExists
+- `isNotFile($path)` - File doesn't exist
+- `isDir($path)` - Directory exists
+- `isNotDir($path)` - Directory doesn't exist
+- `isFileEq($expected, $actual)` - assertFileEquals
+- `isFileContains($expected, $filepath)` - File contains string
+- `isFileNotContains($expected, $filepath)` - File doesn't contain string
+
+### Extended Assertions
+- `isEmail($email)` - Valid email check
+- `isNotEmail($email)` - Invalid email check
+- `isCurrentDate($date, $timeDiff)` - Date is close to current time
+- `isSameDate($expected, $actual, $format)` - Date comparison
+- `isAmount($expected, $actual, $allowableDiff)` - Amount comparison with tolerance
+- `isDiffBetweenDates($date1, $date2, $expectedDiff)` - Time difference check
+
+### Test Control
+- `skip($message)` - markTestSkipped
+- `fail($message)` - fail test
+- `incomplete($message)` - markTestIncomplete
+- `success($message)` - Mark test as successful
+
+### Environment Detection
+- `isWin()` - Running on Windows
+- `isTeamCity()` - Running under TeamCity
+- `isTravis()` - Running under Travis CI
+- `isPhpStorm()` - Running in PhpStorm
+
+## Requirements
+
+- PHP 8.2 or higher
+- PHPUnit ^9.6.29
+- ext-filter, ext-mbstring
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+## License
 
 MIT