You don’t have to write this app by hand. The starter ships with an AGENTS.md file that teaches a coding
agent — Claude Code, Cursor, or whatever you use — the whole app model in one pass: what an app is, where
the seams are, how to do the common tasks, and the one rule it must never break. Open your agent in the
starter directory, describe what you want, and it can extend the app for you — safely, because the guardrails
travel with the code.
This works whether or not you write code yourself. A developer gets an agent that already understands the
trust model instead of guessing at it. A non-developer gets to describe a feature in plain language and have
it built against a starter that’s correct by construction.
What the agent already knows
AGENTS.md is a short, deliberate briefing. It’s not general documentation — it’s the exact context an agent
needs to make good edits without reading the whole SDK. It covers:
- The app model — the four capabilities (install lifecycle, embed UI, public API, webhooks), and that the
security-critical protocol lives in
@sentralbee/app-sdk, never hand-rolled.
- The one security rule — the workspace always comes from a verified token, never from the request body
or a query parameter. This is the rule that keeps a merchant’s data safe, so it’s stated first and stated
plainly.
- The lifecycle — what happens from the moment a merchant clicks Install to the moment they uninstall.
- The file map — which file does what, and specifically that
api/src/app.ts is where features go.
- Common tasks — how to add an endpoint, request a scope, call the API, handle a webhook, store a secret.
- Guardrails — keep changes scoped, don’t weaken auth, don’t log secrets, run
typecheck before finishing.
Because all of that is in the repo, the agent reads it before touching anything and stays inside the lines.
How to do it
Get the starter (the Quickstart covers this), then open your agent in that directory.
AGENTS.md sits at the root, next to your manifest:
Now just describe what you want. Real asks look like this:
The agent will read AGENTS.md, find the right seam, and make the change the way the briefing describes it —
reading the tenant with c.get('workspace') from the verified session, decrypting your stored key with the
SDK’s cypher before calling sentralbeeClient, verifying webhook signatures over the raw body. It won’t
invent an insecure shortcut, because the file tells it not to and tells it what to do instead.
When it’s done, the same tools you’d use by hand confirm the work:
sentralbee dev mock-installs a workspace and opens your embed with a live session token, so you can exercise
a new endpoint or fire a signed test webhook without any Sentralbee infrastructure. That’s the fastest way to
check that what the agent built actually works.
Keep it in the repo
Leave AGENTS.md in your project and keep it committed. Every future session — yours or a teammate’s, any
agent — starts from the same accurate briefing instead of relearning the app from scratch. If you add a
convention of your own (a house style for endpoints, a service you always call), add a line for it. The file
is yours to grow.
AGENTS.md teaches the app model, not this documentation. When you or your
agent needs the details behind a task — the exact manifest fields, the
webhook headers, the checkout contract — the pages in this tab are the
source of truth.
Where to next
