Building with AI agents

Laju Go was designed for AI agents. AGENTS.md at the repo root tells the agent where everything lives, so it can build features without guessing the conventions. Your job is not to write code or remember syntax — it’s to describe what you need and review what the agent produces.

The workflow at a glance

1. Install         npm create laju-go@latest my-app — you do this first
2. Plan            tell the story — the agent writes PLAN.md
3. Design          all pages with dummy data — you review, until you love it
4. Wire            backend + database — strict unit tests prove it works
5. Loop            prompt → agent implements → tests pass → commit
6. Ship            agent verifies everything is green

Setup: install first, then bring in the agent

The agent works inside an already-installed project — you scaffold and install before it ever starts:

npm create laju-go@latest my-app
cd my-app
npm run dev:all

(Full walkthrough — prerequisites and scripts — is in Installation.)

Once the app runs, open the project in your agent (omp.sh, Claude Code, Cursor, opencode, Windsurf) and confirm it read the project rules:

What are the hard rules in AGENTS.md? Summarize them.

You should hear back the core conventions — Handler → Service → Query, one handler file per feature, sqlc for type-safe SQL, useForm + <form> for Inertia submissions, use:inertia for internal links. If the agent can’t answer, tell it to read AGENTS.md before proceeding. This is your first checkpoint.

Plan: tell the story — the agent writes PLAN.md

Describe what you need in plain language, like you’re explaining to a friend. No structure, no technical detail — just the story:

I want a bookmark manager where users save links and organize them with tags. Only logged-in users, no public pages. Write PLAN.md — what it is, who uses it, what it does. Ask me if anything’s unclear.

The agent turns your story into a PLAN.md in the project root — the full plan: pages, data model, routes, validation, edge cases, and an implementation order. You never mention pages, routes, database tables, or code — the agent figures out all of that itself. It knows the conventions from AGENTS.md; your job is to describe the need, not the implementation.

A real result looks something like this (abridged):

# PLAN — Bookmark Manager

> **Clarifying questions (non-blocking):** per-user or global tags?
> Allow duplicate URLs? (Assumptions noted — you can veto them.)

## What it is
A private bookmark manager inside the app. Logged-in users save URLs
with a title, note, and tags. No public pages, no sharing.

## Pages
- `/app/bookmarks` — paginated list + search + tag filter
- `/app/bookmarks/new` — create form
- `/app/bookmarks/:id/edit` — edit form (owner only)

## Data model
`migrations/0005_bookmarks.sql` — bookmarks, tags, bookmark_tags
(user-scoped, FK cascade, indexes on user_id).

## Routes & endpoints
All in `app/handlers/bookmarks.go`:
- GET /app/bookmarks — AuthRequired middleware, Inertia render Bookmarks/Index
- POST /app/bookmarks — BodyParser validation, tag normalization, flash + redirect
- POST /app/bookmarks/:id/delete — ownership check → delete → orphan tag cleanup

## Edge cases
- Ownership enforced in handlers (foreign bookmarks get 404, not 403)
- Tags trimmed / lowercased / deduplicated server-side
- Empty state when a user has zero bookmarks

## Acceptance criteria
- [ ] Auth-only, strictly user-scoped (no cross-user access)
- [ ] Search + tag filter combine correctly
- [ ] `go test ./...` passes

## Implementation order
1. Migration → 2. sqlc queries → 3. service → 4. handler → 5. Svelte pages → 6. tests

Real plans are longer — this is the shape. The agent lists the assumptions it made and asks questions wherever your story was ambiguous.

Include a design in your prompt

If you have a visual design — a mockup from ChatGPT, a Figma export, a hand-drawn sketch — put it in the project and mention it in the same prompt. The design carries what words can’t: colors, spacing, layout. Without one, the agent plans without it; it never invents a design reference on its own.

Two ways to provide it:

Image (design/mockup.png) — the agent reads it and matches the design. Requires the agent’s model to support image input.
HTML mockup (design/mockup.html) — a single static page with real markup and CSS, generated in ChatGPT or Gemini Canvas. Works even when the agent can’t read images, because the structure is in the markup itself.

Either way, reference it in your prompt:

I want a bookmark manager where users save links and organize them with tags. Only logged-in users, no public pages. Design reference: design/bookmarks-mockup.html — match its structure, spacing, and colors. Write PLAN.md — what it is, who uses it, what it does. Ask me if anything’s unclear.

The agent reflects the design in the plan — layout, components, pages — and builds against it.

Review the plan

Read back what the agent wrote. Does it describe what you need? Would a non-technical friend understand it? If it reads like code, it’s too technical — tell the agent to rewrite it in plain language. Check the assumptions it listed and veto anything wrong. Once it reads like a story, the agent can start building.

Design the pages (your review)

Before touching the database, have the agent build all the pages with dummy data. Every page, every state — filled with fake content that looks real. Tell the agent:

Build all the pages from PLAN.md with dummy data — no backend, no database. Use realistic sample content so I can judge the design. Show me every page.

Then judge the design on real pages instead of sketches:

Do the pages look like the mockup?
Do the empty, loading, and filled states all exist?
Is the flow between pages natural?

Iterate until you are personally satisfied with every single page — this is the cheapest time to change things. There’s no schema, no migration, no route logic to rework when you move a button or rename a field. Don’t wire the backend until every page feels right to you.

Design is the only thing that needs your judgment — it’s subjective. There’s no right or wrong layout, only one you like. So this phase is the only one where you review manually.

Wire the backend (automated tests)

Only when the design is final, wire the pages to the backend:

The design is done. Now replace the dummy data with real data — add the database schema, migrations, and routes so the pages read and write for real.

The wiring phase needs no manual review — unlike design, backend logic is objectively right or wrong, and that’s exactly what automated verification is for. The agent writes strict unit tests for the wiring (schema, routes, validation, data flow) and runs them until they pass:

Make the unit tests strict — cover the schema, every route, and validation. The wiring isn’t done until the tests pass.

The agent follows the three-tier rule (Handler → Service → Query), writes SQL in queries/*.sql, regenerates with npm run db:generate, and calls queries through services — never from handlers. Same pages, same design — the agent just swaps the dummy data for real queries, and the tests prove it works. Manual review for the subjective part (design), automated tests for the objective part (wiring).

Work in slices, then ship

Build one slice at a time — not the whole app in one prompt:

Read PLAN.md and build the next slice. When it works, commit it.

After each verified slice, the agent commits — a checkpoint you can roll back to. A plan with several slices produces several commits.

When the slices are done, the agent verifies everything is green — go test ./..., vite build, browser console — and the app is ready to ship:

Run the full checks and confirm everything passes.

The plan evolves

As you build, you’ll realize the plan missed something — a field, a behavior, a page. Tell the agent what changed, and it updates PLAN.md:

Bookmarks should also show the domain. Update PLAN.md and continue from where you left off.

The plan stays the source of truth. When it changes, the agent follows the update.

What’s next

Architecture overview — how the codebase is structured.
Three-tier rule — the load-bearing convention.
Testing — the test suite the agent runs.