Skip to content

AGENTS.md

Latest commit

 

History

History
66 lines (48 loc) · 4.17 KB

AGENTS.md

File metadata and controls

66 lines (48 loc) · 4.17 KB

Agent Rules

1. Technology Stack

2. Go Development Rules

2.1 Fundamentals & Best Practices

  • Idiomatic Go: Follow Effective Go and community standards.
  • Simplicity: Prioritize readability over cleverness.
  • Explicit Errors: Handle all errors immediately; return them as the last value. Use fmt.Errorf("%w", err) for wrapping.
  • Composition: Prefer composition over inheritance. Use interfaces for flexibility.
  • Project Layout: Follow standard Go project structure (/cmd, /pkg, /internal).
  • Formatting: Always use gofmt and goimports to maintain consistent code style.
  • Linting: Ensure code passes golangci-lint with the project's configuration before submission.

2.2 Concurrency (Goroutines & Channels)

  • Communication: Share memory by communicating (via channels); do not communicate by sharing memory.
  • Lifecycle: Always manage goroutine lifecycles to avoid leaks. Use sync.WaitGroup or context.Context for synchronization/cancellation.
  • Safety: Protect shared state with sync.Mutex/sync.RWMutex or atomic operations. Always run tests with -race.

2.3 Testing & Quality

  • Coverage: Maintain a minimum of 80% code coverage for all new Go files and packages. Focus on critical logic and edge cases.
  • Table-Driven Tests: Use for covering multiple scenarios efficiently.
  • Benchmarks: Write benchmarks for performance-critical paths using testing.B.
  • Fuzzing: Use Go native fuzzing for input validation testing.

2.4 Performance Optimization

  • Profiling: Use pprof to identify bottlenecks (CPU, Memory, Block).
  • Memory: Minimize heap allocations; use sync.Pool for object reuse where applicable.
  • Preallocation: Preallocate slices and maps if the size is known.

2.5 Integration & Architecture

  • gRPC/Protobuf: Use for high-performance internal RPC.
  • Database: Use connection pooling. Prevent SQL injection by using prepared statements or proper ORM/sqlx patterns.
  • Microservices: Decouple by domain. Use lightweight communication and implement observability (tracing, metrics, logs).
  • Web: Use net/http for simple services; use frameworks like Gin or Echo for complex routing/middleware while maintaining clean architecture.

2.6 ECS Design Principles (Best Practices)

  • Component Granularity: Favor small, specialized components (e.g., JumpComponent, ControlComponent) over monolithic "God" components.
  • Tag Components: Use empty structs as tags for filtering (e.g., DisabledTag, EnemyTag) instead of boolean flags inside larger components.
  • Command Components: Use components as one-time signals for systems to process and then remove/cleanup.
  • Logic in Components: Components should be pure data. Simple read-only helper methods (e.g., IsExpired() bool) are acceptable, but any state mutation must happen in systems.
  • Entities for Abstract Concepts: Use entities to represent higher-level concepts like Squad, Formation, or GameSession to manage shared state and relationships.
  • System Separation: Split complex logic into multiple systems that each depend on the minimum set of components.
  • Lazy Initialization: Delay creating expensive visual or OS resources until the entity is actually needed for rendering or physics.

Completion Protocol (Mandatory Checklist)

Before finishing any task, the agent MUST verify the following:

  • Technology Stack: Code is written in Go (latest stable), prioritizing the standard library.
  • Cognitive Discipline: No steps skipped, no assumptions made without asking.
  • ECS Architecture Reference: Skill loaded before any spec work.
  • Visual Excellence: Web/UI components (if any) follow premium design guidelines.
  • Code Quality:
    • All new Go files have at least 80% test coverage.
    • Code is formatted with gofmt and follows standard linting rules.