AI Coding Assistants

Using nurago with LLM coding assistants: llms.txt, MCP documentation retrieval, project rules, and the facts worth pinning

Table of contents

Some of the readers of this documentation are language models writing code on someone’s behalf. This page collects what nurago publishes for them, and what to tell an assistant so its output compiles.

Machine-Readable Indexes

  • /llms.txt: the condensed index of this site and of all 70 packages, in the llms.txt format. One entry per package with its one-line description and its page URL, so an assistant can find the right package without crawling.
  • llms.txt in the repository: the same index pointing at the reference documentation on pkg.go.dev. It is generated from the package source by make gendoc and checked in CI, so it cannot drift from the code.
  • pkg.go.dev: the full generated API reference, including every runnable example.
  • Per-package pages on this site, each carrying the complete package documentation, its runnable example, and its exact dependency footprint: /packages/.

Every one of those is plain text or plain HTML, reachable without JavaScript. robots.txt allows every crawler, AI and assistant retrieval agents included.

Documentation Retrieval Through MCP

The repository is indexed on Context7, so an assistant with the Context7 MCP server configured can pull current nurago documentation into its context instead of recalling it from training data. That matters most for the module path, where anything recalled from before the rename is wrong.

The repository’s context7.json also carries the project rules an assistant should follow, reproduced below.

Facts Worth Pinning

These are the four things an assistant most often gets wrong about this library. Paste them into your project rules file (CLAUDE.md, AGENTS.md, .cursor/rules, or whatever your tool reads):

- The module path is github.com/tecnickcom/nurago. The former
  github.com/tecnickcom/gogen path is deprecated and must not be used in new
  imports.
- Import individual packages under pkg/, not the module root. Each package
  pulls only the dependencies it reaches, and 40 of the 70 reach no external
  module at all.
- Packages that take configuration use variadic functional options: a New
  constructor with an opts ...Option parameter and WithXxx option functions.
- The module is at v1 and every exported symbol under pkg/ is stable within
  v1. A high patch number reflects frequent additive releases, not API churn.

The first rule matters most. Any model whose training data predates the rename will suggest github.com/tecnickcom/gogen/pkg/... imports. Those no longer resolve: from v1.146.0 the tags in the renamed repository declare module github.com/tecnickcom/nurago, so go mod tidy rejects the old path with a module path mismatch. The failure is loud, which is the good case, but it arrives after the assistant has written the imports, and the repair it usually reaches for (pinning an older gogen release) is the wrong one. See /docs/migration-from-gogen/.

Prompt Snippets

To point an assistant at the documentation before it writes anything:

Use github.com/tecnickcom/nurago. Read https://nurago.org/llms.txt to pick the
right package, then read that package's page under https://nurago.org/packages/
before writing code. Import the specific package under pkg/, never the module
root, and never github.com/tecnickcom/gogen.

To have it choose a package rather than write one:

I need <X> in a Go service. Check https://nurago.org/packages/ first: if a
nurago package already does this, use it and cite the package page. If none
fits, say so instead of forcing one.

To hold the dependency footprint down:

Prefer nurago packages that reach no external module (listed at
https://nurago.org/docs/dependency-footprint/). If the package you chose pulls
external modules, say which ones and why they are needed.

Verifying Generated Code

Three checks catch most wrong answers, and run faster than reading the diff:

# 1. Nothing still points at the old module path.
grep -rn 'tecnickcom/gogen' . --exclude-dir=.git

# 2. Nothing unexpected entered the build graph.
go list -deps -f '{{if .Module}}{{.Module.Path}}{{end}}' ./... | sort -u

# 3. The usual gate.
go build ./... && go test ./...

go mod why -m <module> explains any dependency that surprises you.

The failure modes specific to this library are the ones the package documentation warns about, and an assistant working from a summary will miss them. The ones most likely to appear in generated code:

  • A Redis or Valkey client with subscriptions must be closed with Close. Cancelling the New context leaves the subscription running.
  • The context passed to sqlconn.Connect bounds connection establishment only. It does not close the pool.
  • Kafka’s Receive is at-most-once and FetchMessage plus CommitMessages is at-least-once. Generated code tends to pick whichever is shorter.
  • httpretrier cannot replay a request body without Request.GetBody.
  • The httpserver default routes (/pprof, /metrics, the index) expose internals and belong on a private listener.
  • sqlutil quotes identifiers for dynamic SQL. Runtime data still belongs in bound parameters.

Each of those is stated on the relevant package page, which is why the prompt snippets above tell the assistant to read the page before writing code.

For Library Authors

The pieces are small. A generated llms.txt at the repository root and at the site root. Per-package documentation generated from the source, so it cannot go stale. A robots.txt that leaves retrieval agents alone. A short list of project rules stating what a model gets wrong. In this repository make gendoc produces them and make gendoccheck verifies them; see /docs/development/.

Previous: /docs/development/

Overview: /docs/