aiagent: Instructions file for Codex

Agentic Coding Guidelines for aiagent

This file provides guidelines for agentic coding agents working in this Go codebase. Focus on build/test commands, code quality, and style consistency.

Build Commands

• Run TUI (default): go run . [--storage=file|mongo]
• Run web server: go run . serve [--storage=file|mongo]
• Run all tests: go test ./...
• Run specific test: go test ./internal/domain -run TestUserService
• Run tests with coverage: go test ./internal/domain -cover
• Build and run with Docker: docker-compose up --build

Development Commands

• Lint: go fmt ./... - Format Go code
• Vet: go vet ./... - Report suspicious constructs
• Mod tidy: go mod tidy - Clean up module dependencies
• Build: go build . - Compile the project
• Test with coverage: go test ./... -cover - Run tests with coverage
• Test verbose: go test ./... -v - Run tests with verbose output
• Race detection: go test ./... -race - Run tests with race detection
• Benchmark: go test ./... -bench=. - Run benchmarks

Quality Assurance Workflow

Agents should run this workflow after any code changes:

1. go fmt ./... - Format code
2. go vet ./... - Check for suspicious code
3. go mod tidy - Clean dependencies
4. go build . - Compile and check for build errors
5. go test ./... - Run all tests

If any command fails, analyze errors, fix issues, and repeat until all pass. Run this before committing changes.

Code Style Guidelines

• Architecture: Domain-Driven Design (DDD) with clear separation between domain and impl
• Error Handling: Use detailed error messages with fmt.Errorf, always check and propagate errors. Wrap errors with context using fmt.Errorf("failed to %s: %w", operation, err)
• Context: Pass context.Context in all repository and service method signatures
• Naming:
  • Use NewXxx for constructor functions
  • Interfaces should end with er (e.g., Repository, Service)
  • Variables should be camelCase
  • Struct fields should be PascalCase for exported fields
• Formatting: Run go fmt ./... before committing (equivalent to gopls auto-format on save)
• Imports: Group standard library, external, and internal imports. Use blank lines to separate groups
• Types and Structs:
  • Use struct tags for JSON/BSON: json:"fieldName" bson:"fieldName"
  • Define interfaces in domain layer, implementations in impl
  • Use dependency injection for services
• Testing: Write unit tests for all service methods, use mocks for dependencies. Test files should end with _test.go
• Logging: Use structured logging with context. Avoid fmt.Printf; use proper logging libraries
• Concurrency: Use channels and goroutines carefully; avoid race conditions
• Security: Never log sensitive data (API keys, passwords). Use environment variables for secrets