# <Module Name> - 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

| File | Purpose |
|------|---------|
| `src/<Module>/__Libraries/StellaOps.<Module>.Core/` | Core business logic |
| `src/<Module>/StellaOps.<Module>.WebService/Program.cs` | Service entry point |
| `src/<Module>/__Tests/` | Test projects |

## 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 Result<T> pattern, 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](./architecture.md)
- [CLAUDE.md](../../../CLAUDE.md) - Global coding rules
- [src/__Tests/AGENTS.md](../../../src/__Tests/AGENTS.md) - Test infrastructure