Skip to content

AGENTS.md

Latest commit

 

History

History
102 lines (76 loc) · 3.28 KB

AGENTS.md

File metadata and controls

102 lines (76 loc) · 3.28 KB
Raw

AGENTS.md

Project Overview

This is a Go backend project.

The AI agent should write simple, idiomatic Go code. Prefer clear control flow, explicit error handling, small functions, and standard library solutions unless a dependency already exists in the project.

Basic Rules

  • Follow existing project structure and naming style.
  • Do not introduce new frameworks or large dependencies unless explicitly asked.
  • Prefer small, focused changes over large rewrites.
  • Keep public APIs stable unless the task explicitly requires changing them.
  • Do not silently ignore errors.
  • Do not use panic for normal application errors.
  • Do not add unnecessary abstraction, generic helpers, or “enterprise-style” layers.
  • Avoid global mutable state unless the existing project already uses it.
  • Keep concurrency simple and safe. Use goroutines only when they clearly help.
  • Use context.Context for request-scoped cancellation, deadlines, and values.

Go Style

  • Run gofmt on all changed Go files.

  • Use idiomatic Go names:

    • package names: short, lowercase, no underscores
    • interfaces: small and behavior-based
    • exported names: documented when they are part of public API

  • Prefer returning (value, error) over special sentinel values.

  • Wrap errors with context using fmt.Errorf("...: %w", err).

  • Keep interfaces close to the consumer, not the implementation.

  • Prefer table-driven tests for multiple input/output cases.

  • Prefer composition over inheritance-like patterns.

  • Avoid clever code. Readability is more important than being compact.

Backend/API Style

  • HTTP handlers should be thin:

    • parse request
    • validate input
    • call service/business logic
    • write response

  • Business logic should not depend directly on HTTP types unless necessary.

  • Database code should be isolated from handlers.

  • Use transactions when multiple database operations must succeed or fail together.

  • Always check SQL errors.

  • Do not build SQL queries by string concatenating user input.

  • Return consistent JSON error responses.

  • Validate request bodies before using them.

Testing

Before finishing a task, run the relevant tests when possible:

go test ./...

For larger backend or concurrency changes, also consider:

go test -race ./...
go vet ./...

If the project has a configured linter, run it:

golangci-lint run

Do not claim tests passed unless they were actually run.

Dependencies

  • Prefer the standard library.
  • Before adding a dependency, check whether the project already has a similar package.
  • If adding a dependency is necessary, explain why.
  • Do not change go.mod or go.sum unnecessarily.

Code Generation Behavior

When modifying code:

  1. Read nearby code first.
  2. Match existing patterns.
  3. Make the smallest correct change.
  4. Add or update tests if behavior changes.
  5. Run formatting and tests.
  6. Summarize what changed and what was tested.

Things to Avoid

  • Do not create unnecessary utils packages.
  • Do not overuse interfaces.
  • Do not add logging everywhere without purpose.
  • Do not swallow errors with _.
  • Do not create background goroutines without a clear shutdown path.
  • Do not mix HTTP, business logic, and database logic in one large function.
  • Do not rewrite working code just to make it look different.