go

name	go
description	ALWAYS invoke this skill as your FIRST action — before any Read, Write, Edit, or Bash — whenever a task involves Go in any way — creating or editing any `.go` file, `go.mod`, or `go test`; adding or changing handlers, structs, methods, interfaces, error handling, goroutines, channels, sqlc/database code, or gomponents views; or refactoring, reviewing, debugging, or testing Go. This is a hard requirement, not a suggestion — the user develops all Go through this skill, which encodes project-specific conventions (structure, error handling, testing, naming) that default Go habits violate. Do not start editing Go and consult it later — load it first. Skip only when no Go code is read or written (pure Python, shell, SQL, Dockerfiles, CI config, or conceptual Go questions with no code).
license	MIT

Go

This is a guide for how to develop applications and modules/libraries in Go.

Some of it is only applicable for applications, not modules used as libraries in other projects, such as database access and running a server.

Application structure

Generally, I build web applications and libraries/modules.

These are the packages typically present in applications (some may be missing, which typically means I don't need them in the project).

• main: contains the main entry point of the application (in directory cmd/app)
• model: contains the domain model used throughout the other packages
• sql/sqlite/postgres: contains SQL database-related logic as well as database migrations (under subdirectory migrations/) and test fixtures (under subdirectory testdata/fixtures/). The database used is either SQLite or PostgreSQL.
• sqltest/sqlitetest/postgrestest: package used in testing, for setting up and tearing down test databases
• s3: logic for interacting with Amazon S3 or compatible object stores
• s3test: package used in testing, for setting up and tearing down test S3 buckets
• llm: clients for interacting with large language models (LLMs) and foundation models
• llmtest: package used in testing, for setting up LLM clients for testing
• http: HTTP handlers for the application
• html: HTML templates for the application, written with the gomponents library (see https://www.gomponents.com/llms.txt for how to use that if you need to)

Code style

Dependency injection

I make heavy use of dependency injection between components. This is typically done with private interfaces on the receiving side. Note the use of userGetter in this example:

package http

import (
	"net/http"

	"github.com/go-chi/chi/v5"
	"maragu.dev/httph"

	"model"
)

type UserResponse struct {
	Name string
}

type userGetter interface {
	GetUser(ctx context.Context, id model.ID) (model.User, error)
}

func User(r chi.Router, db userGetter) {
	r.Get("/user", httph.JSONHandler(func(w http.ResponseWriter, r *http.Request, _ any) (UserResponse, error) {
		id := r.URL.Query().Get("id")
		user, err := db.GetUser(r.Context(), model.ID(id))
		if err != nil {
			return UserResponse{}, httph.HTTPError{Code: http.StatusInternalServerError, Err: errors.New("error getting user")}
		}
		return UserResponse{Name: user.Name}, nil
	}))
}

Tests

I write tests for most functions and methods. I almost always use subtests with a good description of what is going on and what the expected result is.

Tests for a given file always go in one test file: for example.go, the test file is always example_test.go, never example_this_feature_test.go. The one exception is when the test package needs to change, for internal tests, in which case the file is example_internal_test.go.

Here's an example:

package example

type Thing struct {}

func (t *Thing) DoSomething() (bool, error) {
	return true, nil
}

package example_test

import (
	"testing"

	"maragu.dev/is"

	"example"
)

func TestThing_DoSomething(t *testing.T) {
	t.Run("should do something and return a nil error", func(t *testing.T) {
		thing := &example.Thing{}

		ok, err := thing.DoSomething()
		is.NotError(t, err)
		is.True(t, ok)
	})
}

Sometimes I use table-driven tests:

package example

import "errors"

type Thing struct {}

var ErrChairNotSupported = errors.New("chairs not supported")

func (t *Thing) DoSomething(with string) error {
	if with == "chair" {
		return ErrChairNotSupported
	}
	return nil
}

package example_test

import (
	"testing"

	"maragu.dev/is"

	"example"
)

func TestThing_DoSomething(t *testing.T) {
	tests := []struct {
		name     string
		input    string
		expected error
	}{
		{name: "should do something with the table and return a nil error", input: "table", expected: nil},
		{name: "should do something with the chair and return an ErrChairNotSupported", input: "chair", expected: example.ErrChairNotSupported},
	}

	for _, test := range tests {
		t.Run(test.name, func(t *testing.T) {
			thing := &example.Thing{}

			err := thing.DoSomething(test.input)
			if test.expected != nil {
				is.Error(t, test.expected, err)
			} else {
				is.NotError(t, err)
			}
		})
	}
}

I prefer integration tests with real dependencies over mocks, because there's nothing like the real thing. Dependencies are typically run in Docker containers. You can assume the dependencies are running when running tests.

It makes sense to use mocks when the important part of a test isn't the dependency, but it plays a smaller role. But for example, when testing database methods, a real underlying database should be used.

I use test assertions with the module maragu.dev/is. Available functions: is.True, is.Equal, is.Nil, is.NotNil, is.EqualSlice, is.NotError, is.Error. All of these take an optional message as the last parameter.

Since tests are shuffled, don't rely on test order, even for subtests.

Every time the postgrestest.NewDatabase(t)/sqlitetest.NewDatabase(t) test helpers are called, the database is in a clean state (no leftovers from other tests etc.).

You can use database fixtures for tests. Prefer these for test data setups when multiple tests rely on the same or very similar data, so that every test doesn't have to set up the same data. They are in sqlite/testdata/fixtures/postgres/testdata/fixtures. Use them with sqlitetest.NewDatabase(t, sqlitetest.WithFixtures("fixture one", "fixture two")). They are applied in the order given.

Test helper functions should call testing.T.Helper().

In tests, use t.Context() instead of context.Background(), and always use it inline instead of pulling out into a ctx variable.

Tests that exercise timing -- timeouts, retries, tickers, anything sleeping or waiting on a clock -- should use the testing/synctest package (stable since Go 1.25). It runs the test against a fake clock, making timing tests fast and deterministic instead of slow and flaky.

Miscellaneous

• Variable naming:
  • req for requests, res for responses
• There are SQL helpers available, at Database.H.Select, Database.H.Exec, Database.H.Get, Database.H.InTx.
• Use the any builtin in Go instead of interface{}
• There's an alias for sql.ErrNoRows from stdlib at maragu.dev/glue/sql.ErrNoRows, so you don't have to import both
• All HTML buttons need the cursor-pointer CSS class
• SQLite time format is always a string returned by strftime('%Y-%m-%dT%H:%M:%fZ'). Use maragu.dev/glue/model.Time (usually aliased in model.Time in the project) instead of stdlib time.Time when working with the database.
• Remember that private functions in Go are package-level, so you can use them across files in the same package
• Documentation must follow the Go style of having the identifier name be the first word of the sentence, and then completing the sentence without repeating itself. Example: "// SearchProducts using the given search query and result limit." NOT: "// SearchProducts searches products using the given search query and result limit."
• Link to identifiers you reference in doc comments with the [identifier] doclink syntax, e.g. [http.HandlerFunc], [context.Canceled], including unexported identifiers in the same package. Never link the leading identifier (the symbol being documented) — that one is plain text, since you don't link it to itself.
• Comments in a package never look outward: a package doesn't know who imports it, so don't mention callers or their packages (e.g. "used by the http handlers"). Referencing direct dependencies is fine — that's part of its own story — but only their public API: when a package depends on an interface, comments describe the contract, never a concrete implementation behind it.
• Comments describe the code as it is, not as it was. Never leave historical notes ("previously this used X", "replaced the old Y") — the moment the old code is gone, such comments only confuse. That history belongs in the diary (see the [[diary]] skill) and in git.
• Package-level identifiers must begin with lowercase by default, i.e. have package-level visibility, to make the API surface area towards other packages smaller.
• Don't pull values used in only one place out as constants — timeouts, string literals for headers, query keys, and the like read best inline at their use site. Even a couple of uses within a single function can stay inline. Extract a constant when the value is reused across functions or the name adds real meaning, not before.

Testing, linting, evals

Run make test or go test -shuffle on ./... to run all tests. To run tests in just one package, use go test -shuffle on ./path/to/package. To run a specific test, use go test ./path/to/package -run TestName.

Run make lint or golangci-lint run to run linters. They should always be run on the package/directory level, it won't work with single files.

Run make eval or go test -shuffle on -run TestEval ./... to run LLM evals.

Run make fmt to format all code in the project, which is useful as a last finishing touch.

You can access the database by using psql or sqlite3 in the shell.

Documentation

You can generally look up documentation for a Go module using go doc with the module name. For example, go doc net/http for something in the standard library, or go doc maragu.dev/gai for a third-party module. You can also look up more specific documentation for an identifier with something like go doc maragu.dev/gai.ChatCompleter, for the ChatCompleter interface.

Checking apps in a browser

You can assume the app is running and available in a browser using the Chrome Dev Tools MCP tool. It auto-reloads on code changes so you don't have to. Log output from the running application is in app.log in the project root.