Aaronontheweb · Jun 12, 2026 · Jun 12, 2026
diff --git a/AGENT.md b/AGENT.md
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,184 @@
+# AGENTS.md
+
+This file provides guidance to Claude Code (claude.ai/code) and other coding agents when
+working with code in this repository. `CLAUDE.md` is a symlink to this file, so both names
+resolve to the same guidance.
+
+## Build and Test Commands
+
+### Building the Solution
+```bash
+# Standard build
+dotnet build
+dotnet build -c Release
+
+# Build with warnings as errors (CI validation)
+dotnet build -warnaserror
+```
+
+### Running Tests
+```bash
+# Run all tests
+dotnet test -c Release
+
+# Run tests for specific framework
+dotnet test -c Release --framework net8.0
+dotnet test -c Release --framework net48
+
+# Run specific test by name
+dotnet test -c Release --filter DisplayName="TestName"
+
+# Run tests in a specific project
+dotnet test path/to/project.csproj -c Release
+```
+
+### Incremental Testing (for changed code only)
+```bash
+# Run only unit tests for changed projects
+dotnet incrementalist run --config .incrementalist/testsOnly.json -- test -c Release --no-build --framework net8.0
+
+# Run only multi-node tests for changed projects
+dotnet incrementalist run --config .incrementalist/mutliNodeOnly.json -- test -c Release --no-build --framework net8.0
+```
+
+### Code Quality
+```bash
+# Format check
+dotnet format --verify-no-changes
+
+# API compatibility check
+dotnet test -c Release src/core/Akka.API.Tests
+```
+
+### Documentation
+```bash
+# Generate API documentation
+dotnet docfx metadata ./docs/docfx.json --warningsAsErrors
+dotnet docfx build ./docs/docfx.json --warningsAsErrors
+```
+
+### API Approvals
+- Run API approval tests when making public API changes: `dotnet test -c Release src/core/Akka.API.Tests`
+- Approval files live at `src/core/Akka.API.Tests/CoreAPISpec.ApproveCore.approved.txt` (and sibling `*.approved.txt` files)
+- A diff viewer (WinMerge, TortoiseMerge, etc.) makes reviewing/approving API changes easier
+- Follow **extend-only** design — don't modify existing public APIs, only extend them
+- Mark deprecated APIs with `[Obsolete("Obsolete since v{current-akka-version}")]`
+
+## High-Level Architecture
+
+### Project Structure
+- **`/src/core/`** - Core actor framework components
+  - `Akka/` - Base actor system, routing, dispatchers, configuration
+  - `Akka.Remote/` - Distributed actor communication and serialization
+  - `Akka.Cluster/` - Clustering, gossip protocols, distributed coordination
+  - `Akka.Persistence/` - Event sourcing, snapshots, journals
+  - `Akka.Streams/` - Reactive streams with backpressure
+  - `Akka.TestKit/` - Testing utilities for actor systems
+- **`/src/contrib/`** - Contributed modules (DI integrations, serializers, cluster extensions)
+- **`/src/benchmark/`** - Performance benchmarks using BenchmarkDotNet
+- **`/src/examples/`** - Sample applications demonstrating patterns
+- **`/src/**/*.Tests/`** - xUnit test projects
+- **`/docs/`** - Public-facing documentation; contributor policies and style guides live under `docs/community/contributing/`
+
+### Key Architectural Concepts
+- **Actor Model**: Message-driven, hierarchical supervision, location transparency
+- **Fault Tolerance**: Supervision strategies, let-it-crash philosophy
+- **Distribution**: Remote actors, clustering, sharding
+- **Reactive Streams**: Backpressure-aware stream processing
+- **Event Sourcing**: Persistence with journals and snapshots
+
+## Code Style and Conventions
+
+### C# Style
+- Allman style braces (opening brace on new line)
+- 4 spaces indentation, no tabs
+- Private fields prefixed with underscore `_fieldName`; PascalCase for public/protected members
+- Use `var` when the type is apparent
+- No `this.` qualifier unless necessary
+- Sort `using` statements with `System.*` first
+- XML doc comments on public APIs
+- Default to `sealed` classes and records
+- Enable `#nullable enable` in new/modified files
+- Never use `async void`, `.Result`, or `.Wait()` — these cause deadlocks
+- Always pass `CancellationToken` through async call chains
+
+### API Design
+- Maintain compatibility with JVM Akka while being .NET idiomatic
+- Use `Task<T>` instead of Future, `TimeSpan` instead of Duration
+- Extend-only design - don't modify existing public APIs
+- Preserve wire format compatibility for serialization
+- Include unit tests with all changes
+
+### Test Naming
+- Use `DisplayName` attribute for descriptive test names
+- Follow pattern: `Should_ExpectedBehavior_When_Condition`
+
+### General Conventions
+- Keep pull requests small and focused (< 300 lines when possible)
+- Fix warnings instead of suppressing them
+- Treat `TBD` comments as action items to be resolved
+- Benchmark performance-critical changes with BenchmarkDotNet
+- Avoid adding new dependencies without a license/security check
+
+## Akka.NET TestKit Guidelines
+- Actor tests should derive from `AkkaSpec` or `TestKit` to access actor-testing facilities
+- **Always use async TestKit methods** (e.g. `ExpectMsgAsync`, `ExpectNoMsgAsync`, `AwaitAssertAsync`, `FishForMessageAsync`, `ResolveOne`) — never the synchronous variants (`ExpectMsg`, `ExpectNoMsg`, `AwaitAssert`, `.Result`, `.Wait()`)
+- Pass `ITestOutputHelper output` to the test constructor and forward it to the base: `public MySpec(ITestOutputHelper output) : base(config, output)` — this captures all test output, including actor-system logs
+- Configure logging in tests as needed: `akka.loglevel = DEBUG` or `akka.loglevel = INFO`
+- Use `EventFilter` to assert on log messages (e.g. `await EventFilter.Error().ExpectOneAsync(async () => { /* test code */ })`)
+- For dead letters, use `EventFilter.DeadLetter()` (e.g. `await EventFilter.DeadLetter().ExpectAsync(1, async () => { /* code that should dead-letter */ })`)
+- Use `TestProbe` for lightweight test actors to verify interactions
+- Set explicit timeouts on message expectations to avoid long-running tests
+- Tests should clean up after themselves (stop created actors, reset state)
+- Multi-node tests live in separate `*.Tests.MultiNode.csproj` projects
+- To verify specialized message wrappers, check the log form `wrapped in [$TypeName]`
+
+## Development Workflow
+
+### Git Branches
+- **`dev`** - Main development branch (default for PRs)
+- **`v1.4`**, **`v1.3`**, etc. - Version maintenance branches for older releases
+- Feature branches: `feature/description`
+- Bugfix branches: `fix/description`
+
+### Git Repository Management
+- Remotes:
+  - `akkadotnet` / `upstream` → `https://github.com/akkadotnet/akka.net.git` (main repository)
+  - `origin` → your fork (e.g. `https://github.com/yourusername/akka.net.git`)
+- Sync with upstream:
+  - `git fetch akkadotnet` (or `upstream`)
+  - `git checkout dev`
+  - `git merge akkadotnet/dev`
+- Create a feature branch:
+  - `git checkout -b feature/your-feature-name`
+  - `git push -u origin feature/your-feature-name`
+
+### Making Changes
+1. Always read existing code patterns in the module you're modifying
+2. Follow existing conventions for that specific module
+3. Add/update tests for your changes
+4. Run incremental tests before committing
+5. Ensure API compatibility tests pass for core changes
+6. If the change is breaking, record it in `BREAKING_CHANGES_V1.6.md` in the same change (see below)
+
+### Tracking Breaking Changes (v1.6 cycle)
+Until a stable **v1.6.0** ships, **every** change that goes into the `dev` branch and
+introduces a **breaking behavior, wire-format, or public-API change** MUST be documented in
+[`BREAKING_CHANGES_V1.6.md`](BREAKING_CHANGES_V1.6.md) (repo root), in the **same PR** that
+makes the change. Use the entry format described in that file (status, component, type,
+change, migration). This ledger is retired once `v1.6.0` is released, when its contents are
+folded into the release notes / upgrade guide.
+
+### Target Frameworks
+- **.NET 8.0** - Primary target
+- **.NET 6.0** - Library compatibility
+- **.NET Framework 4.8** - Legacy support
+- **.NET Standard 2.0** - Library compatibility
+
+## Important Files
+- `Directory.Build.props` - MSBuild properties, package versions
+- `global.json` - .NET SDK version (8.0.403)
+- `xunit.runner.json` - Test configuration (60s timeout, no parallelization)
+- `.incrementalist/*.json` - Incremental build configurations
+- `RELEASE_NOTES.md` - Version history and changelog
+- `BREAKING_CHANGES_V1.6.md` - Running list of v1.6 breaking changes (until v1.6.0 ships)