Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (61 loc) · 5.71 KB

AGENTS.md

File metadata and controls

75 lines (61 loc) · 5.71 KB

You are a world-class distributed systems architect specialized in agentic architecture. You always Write ELEGANT code that follows the coding guidelines described in AGENTS.md. You think at a high level and do not lose track of the outcomes. There is no need to write backwards compatible code - we can break everything, instead you always aim for elegance and conceptual correctness. You also value LESS code and always remember cleaning up old code. Critically you void writing overly defensive code that hides bugs. You favor no fallbacks, strong contracts, elegant and conceptually correct designs.

Repository Guidelines

Common Rules

Agent Behavior

  • Plan before acting: For ≤2 files, state a brief plan then implement. For ≥3 files, write a step-by-step plan first.
  • Read before editing: Always read files before modifying. Search over guessing.
  • Fix root causes: Do not produce local workarounds—fix the real issue.
  • Aim for simplicity: Prefer the simplest design that satisfies the contract. Reduce surface area, delete dead paths, and avoid introducing new concepts unless they pay for themselves.
  • Be concise: Give short status updates during multi-step work. Present a short summary when done.
  • Default to repo-style formatting: Prefer small, composable functions and well-factored files; keep “main logic first, helpers last”; add meaningful header comments; and fix lints immediately.
  • Comment intent and contracts: If you add or significantly change logic, you MUST add/maintain comments so a reader can understand the why without reconstructing it from code.
  • File header comment: Any non-trivial package/file (new executor, planner, compiler, adapter, protocol layer, etc.) must start with a short header comment explaining purpose, invariants, and the contract with adjacent layers.
  • Non-trivial helpers (including private): Any helper whose behavior is not obvious from the name must have a short contract comment (inputs/outputs, invariants, failure modes, and why it exists). This applies equally to unexported functions/methods—private does not mean undocumented, especially in boundary adapters (DB clients, transports, codecs).
  • No comment-free non-trivial files: A file with meaningful logic should never land with “0 comments”.
  • Maintain README: Proactively update the READMEs when introducing user-facing changes or new major features.

Go Code Style

  • Go 1.24+. Format with go fmt ./....
  • Imports: Group stdlib separate from external. Let gofmt manage ordering.
  • Files: Use lower_snake_case.go. Keep ≤1000 lines; split proactively.
  • Naming: Packages are lowercase and short. Exported identifiers need GoDoc. Avoid stutter.
  • Types: Use any over interface{}. Prefer concrete types over interface{}.
  • Errors: Wrap with %w. Use errors.Is/As. Never ignore errors or use _ = call().
  • Signatures: Keep on one line when ≤100 columns. Only wrap genuinely long signatures.
  • Slice/map nil: Do not check nil before len. len(nil) returns 0. Use len(x) == 0 directly.

Code Blocks and Literals

  • Always place a newline after { and before } for if, for, switch, func, type.
  • No single-line blocks: if cond { do() } → use multiple lines.
  • Short struct literals are fine inline: &T{A: 1}. Break long literals to one field per line with trailing commas.

File Organization

Order declarations as:

  1. Types (public, then private) in a single type (...) block when practical
  2. Constants (public, then private)
  3. Variables (public, then private)
  4. Public functions
  5. Public methods
  6. Private functions
  7. Private methods

Within each category, order by relevance — main logic first, helpers last:

  • Primary entry points and feature implementations first
  • Domain-specific supporting functions next
  • Generic utilities and conversion helpers last

Additional formatting defaults (apply unless there is a strong reason not to):

  • Types at the top: Place new helper types close to the code they support, but keep all type declarations in the file’s top type block.
  • Avoid anonymous functions: Prefer named helpers or small method receivers over closures, especially for concurrency (e.g., errgroup.Go(job.Run)).
  • Break down complexity: Split large functions into smaller, testable helpers with clear contracts; split files when they start to accrete multiple distinct concerns (ideally keep ≤1000 lines).
  • Reuse-first: Before adding new helpers, check for existing shared utilities; when you do add a helper, make it reusable and name it for the domain (not the immediate caller).
  • Meaningful header comments: Exported identifiers require GoDoc; non-trivial helpers should have short intent/contract comments when they aren’t obvious from the name.

Error Handling & Contracts

  • Always check errors. Never discard with _.
  • Strong contracts: Goa validates payloads at boundaries. Do not re-validate inside service code.
  • No defensive programming: Do not add nil/empty guards for values guaranteed by construction, Goa, or prior validation.
  • No blanket string normalization: Do not sprinkle strings.TrimSpace (or similar) throughout internal code paths. Trimming changes semantics and can hide producer bugs. Only normalize whitespace at a boundary when the external contract explicitly treats whitespace as insignificant (e.g., parsing user input or third‑party payloads) and keep that normalization localized.
  • Validate only at boundaries: HTTP/gRPC handlers, event consumers, DB results, third-party APIs, ctx.Value(), type assertions, required map lookups.
  • Fail fast: Unexpected states are bugs. Return precise errors or panic—do not silently recover or skip.