Start

AI-Assisted Development

Claude Code, Codex, Cursors and other AI coding assistants have not seen Goribu in their training data. Goribu fixes this with AGENTS.md, a project-level rules file your AI tools read before writing any code. The scaffold ships one at the project root, and most modern tools pick it up automatically, so out of the box, your assistant already understands the framework.

What's in the file

AGENTS.md covers the mental model, the full req and res surface, <Link> and <Form>, D1 and Postgres patterns, cache, middleware, error pages, and the anti-patterns assistants reach for from other frameworks. It is compact enough that a tool reads it once per session, which is far cheaper than the back-and-forth of correcting wrong-framework code.

It stays cheap, too

The rules file is read once per session — roughly the size of a single source file — not a per-message cost. And because Goribu's surface is small and every route keeps its page, handlers and data in one file, an assistant rarely needs more than the file it's editing in context. The expensive part of AI coding is the round-trips spent correcting another framework's idioms; loading Goribu's conventions once up front is what removes them.

Per-tool setup

AGENTS.md works as-is in any tool that follows the AGENTS.md convention. For tools that prefer a different filename or location, grab the matching variant. All of them share the same content, only the filename and location change.

  • Claude Code, OpenAI Codex CLI, OpenCode, Cursor — read AGENTS.md natively. Nothing to do as create-goribu already ships it.
  • Cursor (native rules) — download goribu.mdc and place it at .cursor/rules/goribu.mdc if you prefer Cursor's own rules system.
  • Claude Code (legacy filename) — download CLAUDE.md and place it at the project root.
  • Aider — download CONVENTIONS.md and place it at the project root.

Adding your own app rules

AGENTS.md is yours to edit. The framework conventions are the foundation. Your app's conventions stack on top and tools read the whole file so they pick up both layers. A short app-specific section at the bottom is enough. Common additions:

  • Your data access pattern — "All database access goes through functions in src/data/ or handlers don't call req.d1 directly."
  • Your auth flow — "Sessions are JWTs in the session cookie, the requireAuth middleware in src/routes/_middleware.js sets req.user."
  • What's off-limits — "Don't refactor src/server.tsx. Don't touch migrations/ unless asked."
  • Your stack choices — "Use Drizzle for queries, not raw SQL." Or the inverse.

When a new Goribu release changes a public convention, the upstream AGENTS.md updates — diff your copy against the latest AGENTS.md to merge changes in.

Pasting context manually

For tools without a project-rules convention like web ChatGPT, the Claude.ai chat, ad-hoc scripts, you can paste this tighter version at the start of a session. It covers enough for most questions and small route edits:

You're working with a Goribu app. Goribu is a full-stack React framework for Cloudflare Workers. It is not Next.js, not Remix, not Express.

Routing: file-based under src/routes/. Each file's default export is the page component. Named exports GET, POST, PUT, PATCH, DELETE are handlers. They co-locate. No pages/api split.

Handler signature:
  export async function GET(req, res) {
    const poll = await req.d1.get("SELECT * FROM polls WHERE id = ?", [req.params.id])
    return res.render(PageComponent, { poll })
  }

req: params, query() / searchParams, body() / json() / form(), env, d1, postgres, cache, url, method, headers
res: render(Comp, props), json, text, html, redirect, status(code) (chainable), notFound()

Imports come from "goribu":
  import { Link, Form } from "goribu"

For SPA navigation use <Link href>. For form submissions use <Form>. Both progressive-enhancement-safe.

Pages are pure functions of props; every res.render call must pass ALL props the component needs:
  return res.status(400).render(Page, { user, values, errors })

Page metadata is a `meta` export (object or ({ props }) => ({...})), not JSX <title>.

Database: req.d1.get/all/run/batch (D1) or req.postgres tagged templates (Postgres). Always parameterize.

Cache: req.cache wraps the Cloudflare Cache API. URL-keyed (must start with /). Per-POP. ttl in seconds.

Middleware: _middleware.{js,jsx,ts,tsx} in any folder under src/routes/. Signature (req, res, next) => Promise<Response>. Modify the Response from await next().

Error pages: _404.jsx for unmatched URLs (auto). _500.jsx for uncaught errors. For a missing record use res.notFound(), not status(404) on a normal render.

Common mistakes to avoid:
- Don't create src/pages or src/api directories
- Don't use next/link or react-router; use Link from goribu
- Don't use raw <form> for in-app POST flows; use <Form>
- req.body/req.json/req.form are async methods — await them: await req.body(). Use req.form() for multipart/file uploads
- Don't call process.env; use req.env server-side, import.meta.env.PUBLIC_X client-side
- Don't call req.env.DB.prepare directly; use req.d1
- Don't interpolate user input into SQL; always parameterize
- Don't pass JSX to res.render; pass the component reference

Full docs: https://goribu.dev/docs

For deeper questions, point the assistant at https://goribu.dev/docs.