For beginners

Use an AI coding assistant to build a Go app properly

An assistant writing code for an unfamiliar codebase behaves like a capable contractor on their first morning: fast, confident, and about to put the new file in the wrong directory using a library you removed last year. The fix is not better prompting. It is giving it the things a new colleague would be given.

This covers what to set up before asking for anything, the prompts that get usable answers on a Go and React project, and the review habits that catch the specific ways generated code goes wrong.

16 min read. Commands and output last run against Grit v3.560.0.

What you will have at the end

A project an assistant can read its own conventions from, rather than guess at.

Prompts that produce code matching your codebase instead of a tutorial.

A review checklist aimed at the mistakes these tools actually make.

Context first, prompts second

The largest quality difference is not which model you use or how you phrase a request. It is whether the project tells the assistant what it is.

A conventions file at the root

Most assistants read a markdown file at the repository root automatically: AGENTS.md, CLAUDE.md or .cursorrules, depending on the tool. One file, read before every request, is worth more than a hundred careful prompts.

AGENTS.md
# Conventions
Go 1.26, Gin, GORM, Postgres. Next.js App Router, TypeScript, Tailwind,
TanStack Query. pnpm, not npm.
## Structure
- apps/api/internal/handlers thin: parse, call a service, respond
- apps/api/internal/services business logic lives here, nowhere else
- apps/api/internal/models GORM models
- apps/web the customer app
- packages/shared types and Zod schemas, GENERATED, never edited
## Rules
- Every error is handled. Wrap with fmt.Errorf("context: %w", err).
- Handlers never contain business logic or raw queries.
- Every list endpoint paginates, with a maximum page size.
- Every query against a tenant table is scoped by organisation_id in the
WHERE clause, not checked after the fetch.
- Responses use the envelope in API_DESIGN.md: {data} or {error}.
- No new dependency without asking. We have deliberately few.
## Do not
- Do not edit packages/shared by hand; it is generated by `grit sync`.
- Do not use the Pages Router.
- Do not add an ORM, a validation library or a router. We have those.

Note what that file is mostly made of: prohibitions and locations. Those are the two things an assistant cannot infer and will otherwise invent.

Point it at a file that is already right

The single highest-value sentence in any prompt is "follow the pattern in this file". An assistant is far better at imitation than at invention, and a real handler from your codebase specifies the error style, the response shape, the logging and the naming all at once, without you writing any of it down.

Choose the exemplar deliberately

It will copy what is there, including the parts you are not proud of. Pick the file you would want five more of, not the one you happen to have open.

Prompts that work

Say which layer, and what not to touch

Weak:
"Add invoice functionality"
Better:
Add a Void action for invoices.
- Service method in internal/services/invoice.go, following the pattern
of Invoice.Send in the same file.
- A thin handler in internal/handlers/invoice.go and a route in
internal/routes/routes.go behind middleware.Require(authz.InvoiceWrite).
- Voiding is only allowed from status "sent". Any other status returns
ErrInvalidTransition, which maps to 409.
- Scope the query by organisation_id, as the other methods do.
- Table tests for the allowed transition and two refused ones.
- Do not touch the frontend in this change.

The last line matters more than it looks. Without a boundary, an assistant will helpfully also edit three files you did not ask about, and the diff becomes too large to review properly, which is how bad code gets approved.

Ask for the plan before the code

For anything touching more than two files, ask what it intends to do first. A wrong plan costs a sentence to correct; wrong code costs a review to discover.

Before writing anything: list the files you will change and what each
change does, in one line per file. Wait for me to confirm.

Give it the error, not your theory about the error

Paste the full message, the stack trace and the command that produced it. A paraphrase loses the detail that identifies the cause, and stating your theory tends to get it confirmed rather than tested.

Make it check its own work

When you are done: run go build ./... and go test ./..., then paste the
output. If anything fails, fix it and run again. Do not tell me it is
finished until both are clean.

An assistant with a terminal can verify. One without one is guessing, and the difference in output quality is larger than the difference between models.

Reviewing what comes back

Generated code reads well, which is exactly the problem: it is fluent, consistently formatted and plausibly structured, so it passes the skim that would catch a human's rough draft. These are the failure modes worth looking for specifically.

  • An invented API. A method that does not exist on that library, with an entirely convincing name. Most common on libraries that changed between major versions. The compiler catches it in Go, which is one of the reasons Go is a good language to use an assistant with.
  • A dropped scope. The query that forgot organisation_id, or the handler without the ownership check. Compiles, passes tests, returns other customers' rows. This is the one to grep for on every change.
  • Swallowed errors. if err != nil { log.Println(err) } and then carrying on, or a bare _. It satisfies "handle the error" and loses the failure.
  • A new dependency. Check go.mod and package.json in the diff. A library added to save four lines is a library you now own.
  • N+1 queries. A loop containing a database call, often introduced while "simplifying" a preload it did not understand.
  • Tests that assert nothing. A test that calls the function and checks err == nil is coverage without verification. Make one fail on purpose: a test that cannot fail is not a test.
  • Confident wrong comments. A comment explaining why the code does something it does not do. Worse than no comment, because the next reader believes it.

Make the generated code fail before you trust it

The cheapest check available: break the thing the new code is supposed to protect, and confirm something complains. If the validation is supposed to reject an empty title, send an empty title. If a test is supposed to catch a regression, introduce the regression. Code that was never observed failing has not been observed at all.

What these tools are good and bad at

Matching the task to the tool saves more time than any prompt technique.

Good

  • Repetitive work with a clear example. The eighth handler that looks like the first seven.
  • Tests for existing code, especially the edge cases you would skip.
  • Translating between languages, such as a Python script into Go.
  • Explaining unfamiliar code, which is often the fastest way into a codebase you inherited.
  • Boring transformations: a struct into a form, a schema into a migration, a list into a table.

Bad

  • Architecture. It will produce a confident answer with no knowledge of your constraints, your team or next year's plan.
  • Anything where being subtly wrong is expensive: auth, payments, permissions, migrations against real data. Use it to draft, review it as if a stranger wrote it, because one did.
  • Deciding what to build. It has never met your customers.
  • Recent library changes. Training data has a date and an API that changed last month is a confident answer about the old one.

Generate the generated parts with a generator

The one piece of advice that saves the most time: do not ask an assistant to produce code that a deterministic generator already produces.

A CRUD resource, with model, service, handler, routes, types, schema, hooks and admin screen, is a scaffolding command. The command produces the same output every time, that output is tested, and it does not quietly diverge from your conventions on the fourth resource. An assistant asked to produce the same thing gives you eight files that are nearly right in eight slightly different ways.

Terminal
# Deterministic: the same every time, and it stays current with the
# framework when you upgrade.
$grit generate resource Invoice --fields "number:string,total:money,due:date"
# Then the assistant does the part that is actually yours:
# "In internal/services/invoice.go, add the late-fee calculation:
# 2% of the total per started week after the due date, capped at 20%.
# Money is in minor units. Table tests for the boundaries."

The division is: generators for what is the same in every project, an assistant for what is specific to yours. Reversing it is the common mistake, and it produces the most review work for the least value.

Giving the assistant real access

A tool that can read your files, run your tests and query your schema is categorically more useful than one working from pasted snippets, because it can check itself.

  • Let it run the build and the tests. This single change removes most invented APIs and most incorrect assumptions, because the compiler disagrees with them immediately.
  • Give it the schema, not the database. It should know what columns exist. It does not need credentials to production, and the distance between those two is worth keeping.
  • Keep secrets out of the workspace. A .env in a directory the assistant reads is a secret in a context window, and possibly in a log.
  • Review every diff. Autonomy over a branch is useful. Autonomy over a commit to main is a code review you decided to skip.
Terminal
# Grit exposes its project knowledge over MCP: the resource list, the
# field types, the route table and the commands.
$grit plugin add mcp

The MCP documentation covers what it exposes and how to connect an assistant to it.

Telling it about the framework

A model's training data will not include a framework this new, or will include an old version of it. Rather than letting it guess, hand it the current reference:

Terminal
$grit init # writes AGENTS.md with this project's conventions
$grit docs search "field types"
$grit docs show docs/concepts/field-types

grit docs works offline and prints the documentation as text, which is exactly the shape an assistant can use. There is also an llms.txt and a skills plugin for assistants that support them.

Frequently asked questions

Will using an assistant stop me learning?
It can, in one specific way: accepting code you cannot explain. The habit that prevents it costs nothing. Before accepting a change, say out loud what it does and why. When you cannot, ask the assistant to explain it, and if the explanation does not satisfy you, do not keep the code. Used that way it is closer to pairing with somebody faster than you than to copying homework.
Which parts should I never let it write unreviewed?
Authentication, authorisation, payment handling, anything cryptographic, and migrations that run against real data. Not because it writes them badly, but because a subtle error in those is expensive and invisible, and the fluency of the output makes a skim read feel sufficient when it is not.
Why does it keep using the wrong library version?
Training data has a date, so an API that changed recently gets a confident answer about the old one. Two defences: name the versions in your conventions file, and give it a real file from your codebase that uses the library correctly. Imitation beats recall.
Is generated code worse than hand-written code?
It is differently wrong. A human's rough draft looks rough, so it gets read carefully. Generated code is fluent, consistently formatted and plausible, so it gets skimmed. The quality problem is mostly a review problem: the same scrutiny you would give a pull request from somebody you have never worked with.

Next steps