trpc-agent-go AGENTS.md

AGENTS.md

Project overview

tRPC-Agent-Go is a Go multi-module framework for building AI agent systems. It is not a standalone application and does not have a single root main.go.

The root module path is:

trpc.group/trpc-go/trpc-agent-go

The root module requires Go 1.21. Some independent modules, including modules under test/, require newer Go toolchains.

Engineering principles

Preserve syntax, semantic, behavioral, serialization, persistence, and protocol compatibility unless the task explicitly requires a documented change.

Prefer minimal, focused changes. Avoid unrelated refactoring and avoid creating new abstractions before their responsibility and ownership are clear.

New behavior should preserve existing defaults and should be opt-in when practical.

Framework abstractions should be capability-oriented. Keep implementation-specific concepts in their owning packages unless their semantics are genuinely shared across implementations.

Update documentation and examples whenever public behavior, defaults, configuration, or recommended usage changes.

Go design conventions

Follow Effective Go and the Go Code Review Comments, while preserving established APIs when compatibility requires it.

• Use gofmt and goimports.
• Use short, lowercase, single-word package names, and make exported names read naturally with their package qualifier without stutter.
• Use MixedCaps and spell common initialisms consistently.
• Prefer small, consumer-oriented interfaces and concrete constructor return types. Do not add an interface for a hypothetical abstraction.
• Make zero values useful when practical; use constructors to establish invariants when necessary.
• Pass context.Context first when needed, propagate cancellation, and avoid storing contexts in structs unless the type owns that lifetime.
• Keep error strings lowercase and without trailing punctuation. Preserve causes with %w when callers need them; expose inspectable errors only for a stable caller contract.
• Make goroutine, channel, resource, cancellation, and shutdown ownership explicit.
• Write Godoc for exported declarations as complete sentences beginning with the declared name and describing the caller-visible contract.