AGENTS.md

# Agent Guidelines for CAATSM Repository

## Build/Test Commands
- **Build**: `make build` or `task build` (compiles to `bin/receiver`)
- **Run dev**: `make run-dev` or `task run-dev` (uses `configs/config.dev.toml`)
- **Lint**: `make lint` or `task lint` (golangci-lint required)
- **Unit tests**: `make test` (Ginkgo) or `ginkgo -r -v ./path/to/package` for single test
- **Integration tests**: `make test-int` (requires Docker)
- **All tests**: `make test-all`
- **Coverage**: `make coverage` (target: maintain >80% coverage)

## Code Style Guidelines
- **Formatting**: Use tabs, `go fmt ./...` or `goimports` before commits
- **Naming**: `camelCase` for locals/unexported, `CamelCase` for exported; package names match directories
- **Imports**: Standard library → third-party → internal (alphabetized within groups)
- **Types**: Use interfaces for ports, appropriate Go types; avoid `any` unless necessary
- **Error handling**: Wrap errors with context, use `errors.Is()` for checking
- **Generated code**: Never edit `/pkg/di/wire_gen.go` or other generated files
- **Linting**: `golangci-lint run ./...` required; fix all issues before PR

## Testing Guidelines
- **Unit tests**: Ginkgo BDD style next to implementation (`*_test.go`); declarative descriptions
- **Integration**: Testcontainers in `test/integration`; spin up NATS/TimescaleDB
- **Coverage**: Run `make coverage` before merging; address regressions

## Architecture
- **Structure**: Clean Architecture - `domain` (business logic), `app` (use cases), `adapter` (I/O), `infra` (framework deps)
- **Entry point**: `cmd/main`
- **Config**: `configs/config.<env>.toml`; secrets via `CAATSM_*` env vars
✨ Refactor NATS consumer management by introducing a dedicated `ConsumerManager` and `StreamManager` for lifecycle management. Enhance error handling with a new `ErrorHandler` to streamline message processing and recovery logic. Update consumer initialization to utilize the new managers, improving code organization and maintainability. Add comprehensive tests for the new components to ensure reliability and robustness in handling NATS operations. 2025-11-18 08:38:03 +08:00			`# Agent Guidelines for CAATSM Repository`
✨ Add repository guidelines and enhance documentation for project structure, build commands, coding standards, and testing practices. Introduce `AGENTS.md` for contributor guidance, update `README.md` to reference new guidelines, and improve configuration documentation for NATS modes. Update Makefile and Taskfile with clearer run commands and requirements for development and production modes. Add production deployment guide and improve logging configuration for better observability. 2025-11-17 16:25:23 +08:00
✨ Refactor NATS consumer management by introducing a dedicated `ConsumerManager` and `StreamManager` for lifecycle management. Enhance error handling with a new `ErrorHandler` to streamline message processing and recovery logic. Update consumer initialization to utilize the new managers, improving code organization and maintainability. Add comprehensive tests for the new components to ensure reliability and robustness in handling NATS operations. 2025-11-18 08:38:03 +08:00			`## Build/Test Commands`
			- Build: `make build` or `task build` (compiles to `bin/receiver`)
			- Run dev: `make run-dev` or `task run-dev` (uses `configs/config.dev.toml`)
			- Lint: `make lint` or `task lint` (golangci-lint required)
			- Unit tests: `make test` (Ginkgo) or `ginkgo -r -v ./path/to/package` for single test
			- Integration tests: `make test-int` (requires Docker)
			- All tests: `make test-all`
			- Coverage: `make coverage` (target: maintain >80% coverage)
✨ Add repository guidelines and enhance documentation for project structure, build commands, coding standards, and testing practices. Introduce `AGENTS.md` for contributor guidance, update `README.md` to reference new guidelines, and improve configuration documentation for NATS modes. Update Makefile and Taskfile with clearer run commands and requirements for development and production modes. Add production deployment guide and improve logging configuration for better observability. 2025-11-17 16:25:23 +08:00
✨ Refactor NATS consumer management by introducing a dedicated `ConsumerManager` and `StreamManager` for lifecycle management. Enhance error handling with a new `ErrorHandler` to streamline message processing and recovery logic. Update consumer initialization to utilize the new managers, improving code organization and maintainability. Add comprehensive tests for the new components to ensure reliability and robustness in handling NATS operations. 2025-11-18 08:38:03 +08:00			`## Code Style Guidelines`
			- Formatting: Use tabs, `go fmt ./...` or `goimports` before commits
			- Naming: `camelCase` for locals/unexported, `CamelCase` for exported; package names match directories
			`- Imports: Standard library → third-party → internal (alphabetized within groups)`
			- Types: Use interfaces for ports, appropriate Go types; avoid `any` unless necessary
			- Error handling: Wrap errors with context, use `errors.Is()` for checking
			- Generated code: Never edit `/pkg/di/wire_gen.go` or other generated files
			- Linting: `golangci-lint run ./...` required; fix all issues before PR
✨ Add repository guidelines and enhance documentation for project structure, build commands, coding standards, and testing practices. Introduce `AGENTS.md` for contributor guidance, update `README.md` to reference new guidelines, and improve configuration documentation for NATS modes. Update Makefile and Taskfile with clearer run commands and requirements for development and production modes. Add production deployment guide and improve logging configuration for better observability. 2025-11-17 16:25:23 +08:00
			`## Testing Guidelines`
✨ Refactor NATS consumer management by introducing a dedicated `ConsumerManager` and `StreamManager` for lifecycle management. Enhance error handling with a new `ErrorHandler` to streamline message processing and recovery logic. Update consumer initialization to utilize the new managers, improving code organization and maintainability. Add comprehensive tests for the new components to ensure reliability and robustness in handling NATS operations. 2025-11-18 08:38:03 +08:00			- Unit tests: Ginkgo BDD style next to implementation (`*_test.go`); declarative descriptions
			- Integration: Testcontainers in `test/integration`; spin up NATS/TimescaleDB
			- Coverage: Run `make coverage` before merging; address regressions
✨ Add repository guidelines and enhance documentation for project structure, build commands, coding standards, and testing practices. Introduce `AGENTS.md` for contributor guidance, update `README.md` to reference new guidelines, and improve configuration documentation for NATS modes. Update Makefile and Taskfile with clearer run commands and requirements for development and production modes. Add production deployment guide and improve logging configuration for better observability. 2025-11-17 16:25:23 +08:00
✨ Refactor NATS consumer management by introducing a dedicated `ConsumerManager` and `StreamManager` for lifecycle management. Enhance error handling with a new `ErrorHandler` to streamline message processing and recovery logic. Update consumer initialization to utilize the new managers, improving code organization and maintainability. Add comprehensive tests for the new components to ensure reliability and robustness in handling NATS operations. 2025-11-18 08:38:03 +08:00			`## Architecture`
			- Structure: Clean Architecture - `domain` (business logic), `app` (use cases), `adapter` (I/O), `infra` (framework deps)
			- Entry point: `cmd/main`
			- Config: `configs/config.<env>.toml`; secrets via `CAATSM_*` env vars