- AI Agent Instructions

Instructions for AI agents (Claude Code, GitHub Copilot, etc.) working on this module.

Module Context

• Primary Language: C# (.NET 10)
• Project Type: Library / WebService / Worker
• Test Framework: xUnit with Testcontainers

Key Files

Common Tasks

Adding a New Feature

1. Start with the interface in *.Core
2. Implement in the appropriate layer
3. Add tests in the corresponding *.Tests project
4. Update API contracts if WebService

Fixing a Bug

1. Write a failing test first
2. Fix the implementation
3. Verify all related tests pass

Patterns to Follow

• Dependency Injection: All dependencies via constructor injection
• Async/Await: Propagate CancellationToken through all async chains
• Error Handling: Use Resultpattern, not exceptions for expected failures
• Logging: Structured logging with semantic properties

Anti-Patterns to Avoid

• Direct new HttpClient() - use IHttpClientFactory
• DateTime.UtcNow - use TimeProvider injection
• Guid.NewGuid() - use IGuidGenerator injection
• Culture-sensitive string operations - use InvariantCulture

Testing Requirements

• Unit tests for all public APIs
• Integration tests for database operations
• Snapshot tests for serialization
• All tests must be deterministic

Related Documentation

• Architecture
• CLAUDE.md - Global coding rules
• src/__Tests/AGENTS.md - Test infrastructure