next16-claude-starter
AGENTS.md141 starsChanged 33 days agoUnlicenseView on GitHub
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Heed deprecation notices and verify against the docs before writing routing or framework code. All project documentation is the obsidian/ Obsidian vault — it is the single source of truth for how this project is built. Before working, read: - obsidian/README.md — Map of Content (index of every doc) - obsidian/workflows/ai-agent-guide.md — full rules of engagement - The relevant topic note (e.g.…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- aeo-visibilitySkill
- figma-to-sectionSkill
- i18n-seoSkill
- local-seoSkill
- mobile-device-qaSkill
- optimize-3d-sceneSkill
- optimize-loadSkill
- optimize-performanceSkill
- payload-adminSkill
- payload-analyticsSkill
- payload-cmsSkill
- qa-verifySkill
- schema-markupSkill
- seo-auditSkill
- seo-growSkill
- ship-checkSkill
- site-migrationSkill
- supabase-authSkill
- supabase-dbSkill
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 0 are common, 0 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
All project documentation is the obsidian/ Obsidian vault — it is the single source of truth for how this project is built.
- Very specific: line 19
Before optimising anything: obsidian/knowledge/fix-catalog.md and obsidian/knowledge/pitfalls.md — fixes measured on many production sites, …
- Very specific: line 35
No CSS keyframes, no framer-motion.
- Very specific: line 92
3D performance → use the skill: If the request is about performance, jank, or shipping readiness and the project renders a three.js / WebGL …
- Very specific: line 97
Routes stay static; crawlers get the robot form: Never headers(), cookies() or isBot() in a page, view, layout, lib/site or the SEO helpers …
- Very specific: line 106
Loops and frames: Every looping spring reads useMotionOff() (reduced motion and the robot form would otherwise freeze the page).
- Very specific: line 111
Never stop drawing a canvas that is on screen.
- Very specific: line 129
Update the vault: dependency changes → tech-stack.md + changelog.md.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Guide — next16-claude-starter
This is NOT the Next.js you know
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Heed deprecation notices and verify against the docs before writing routing or framework code.
Documentation lives in the vault
All project documentation is the obsidian/ Obsidian vault — it is the
single source of truth for how this project is built.
Before working, read:
obsidian/README.md— Map of Content (index of every doc)obsidian/workflows/ai-agent-guide.md— full rules of engagement- The relevant topic note (e.g.
frontend/animation-system.mdbefore animation work,workflows/new-page.mdbefore building a page) - Before optimising anything:
obsidian/knowledge/fix-catalog.mdandobsidian/knowledge/pitfalls.md— fixes measured on many production sites, and the traps that misled the measurements. Try rule entries first.
Commands, skills and agents live in .claude/ and are mapped in
obsidian/workflows/agent-harness.md. Common entry points: /new-page,
/section, /qa, /ship, /cms, /db, /seo, /seo-grow, /migrate-site, /perf,
/load, /mobile. The testing tools are tools/qa/* (yarn qa:*) — see
tools/qa/README.md and obsidian/workflows/testing-pipeline.md.
Notes link each other with [[wikilinks]] — follow them to navigate.
Hard rules (never violate)
- All motion is spring-based —
@react-spring/webvia the components insrc/components/animation/springs/. Text animation usesspring-text-engine. No CSS keyframes, noframer-motion. One exception: CSStransition-*is allowed for simple discrete state changes (hover/focus colour, opacity, border, small nudges) with token-backed timing —duration-[var(--duration-fast)] ease-entrance. Everything scroll-driven, revealing, staggered, or layout-affecting stays a spring. Seeobsidian/frontend/design-system.md. - Do not modify
src/components/animation/springs/orsrc/hooks/animation/without explicit sign-off — they are the vendored animation engine. One authorized performance refactor has been made (seedecisions-log.mdADR-0009); they remain protected by default. - Never
mode="manual"onTextEngine— usealways/once/forward/progress.TextEngine's container is flex, sotext-alignalone cannot align it — always pairtext-centerwithjustify-center(etc.) on the tag. Andoverflowclips to the line-height box, so keep leading ≥ 1.1 (leading-display); neverleading-nonewithoverflow, or glyphs get shaved. Seeobsidian/frontend/text-engine.md. - No hardcoded values — design tokens in
globals.cssfor styles; props/hooks for content. No raw hex/px in class names. Tokens follow a strict three-tier convention (--raw-*primitive → semantic role →@themebinding) that is identical across every project built from this starter — seeobsidian/frontend/design-system.md. - Routes delegate to views —
app/**/page.tsximports only fromsrc/views/. - Server Components by default; add
"use client"only at the leaves. - No
any. Type everything. Runyarn lintbefore finishing. - Navigation — standard
next/link<Link>andnext/navigationuseRouter. - API & secrets — external/third-party calls run server-side in
app/api/**/route.ts; secret keys are server-only env vars (neverNEXT_PUBLIC_, read viasrc/env.ts). The browser only calls same-origin/api/*. Validate input withzod; return the{ data }/{ error }envelope. Seeobsidian/backend/api-architecture.md. - Semantic, SEO-correct HTML — native elements over
divs, one<h1>+ a clean heading outline, named landmarks, realbutton/a,alttext, JSON-LD (not microdata), semantictagon animation components. Seeobsidian/frontend/html-semantics.md. - Verify before reporting done.
yarn verify(.claude/scripts/verify.sh, zero FAILs) +yarn lint+yarn buildafter any code change, and theqa-verifyskill after any UI change. Seeobsidian/workflows/qa-verification.md. - CMS & database are Payload + Supabase, added per project — not shipped in
the starter. Use the
payload-cms/supabase-dbskills; seeobsidian/backend/cms-payload.md. Notemiddleware.tsdoes not exist in Next 16 — it isproxy.ts. - Performance → measure, never guess. Build, measure, attribute, fix one
thing, re-measure. Never report a performance win you did not measure.
Records come from
tools/qa/*against a production build (yarn build && yarn start, nevernext dev), PC and mobile, median of 3+ runs, confirmed on the real host. The bar: Performance ≥ 90 on PC and mobile; Accessibility, Best Practices and SEO 100 — for people and for the robot form; scroll ideal (no frame > 50 ms) on PC and phone, first and second visit. Runyarn qa:setuponce per machine. Two skills, by what is slow:- Load — Lighthouse scores, Core Web Vitals, accessibility, SEO →
optimize-load(yarn qa:lh,yarn qa:axe). Seeobsidian/workflows/optimize-load.md. - After load — scroll jank, micro-freezes, dropped frames →
optimize-performance(yarn qa:scroll,--first-scrollafter a loader). Check first whether the first scroll is worse than the second; Lighthouse never scrolls and cannot see this. Seeobsidian/workflows/optimize-performance.md.
- Load — Lighthouse scores, Core Web Vitals, accessibility, SEO →
- 3D performance → use the skill. If the request is about performance,
jank, or shipping readiness and the project renders a three.js / WebGL
scene (
threeinpackage.json, or a canvas with a render loop), invoke theoptimize-3d-sceneskill first and follow its order of fixes — don't improvise one. Seeobsidian/workflows/optimize-3d-scene.md. - Routes stay static; crawlers get the robot form. Never
headers(),cookies()orisBot()in a page, view, layout,lib/siteor the SEO helpers —src/proxy.tsroutes bots (search and AI crawlers) to/robot-view. Don't add anapp/loading.tsxwithout a real skeleton (an empty one hides the page from non-JS crawlers). Every page is registered insrc/lib/routes.ts(sitemap,/llms.txt, breadcrumbs read it);yarn qa:seochecks the served values. The consent banner is server-rendered — it is often the phone's LCP. Seeobsidian/frontend/robot-form.md,.claude/rules/seo-robot.md. - Loops and frames. Every looping spring reads
useMotionOff()(reduced motion and the robot form would otherwise freeze the page). Per-frame code scales bydtin seconds (src/lib/scene/per-frame.ts) — 120 Hz phones run per-frame steps twice as fast. No fixed frame cap on phones (it reads as choppy); desktop scenes may gate the draw at ~60 fps (createDrawGate). Never stop drawing a canvas that is on screen; recover lost WebGL contexts (src/lib/scene/webgl-context.ts). See.claude/rules/scenes.md. - Phones are checked on phones. Lab tools miss what a person sees on an
iPhone: Safari's toolbar resizing the viewport, 120 Hz speed, lost GPU
contexts, menus under the bottom bar, dark-mode overlays, touch sliders.
Full-screen scene boxes use the large viewport (
<SceneViewport>); menus useh-dvh+ the safe area, their own colour token and a portal under<body>. Something wrong on a phone →mobile-device-qa(/mobile,yarn qa:ios,qa:fps,qa:context,qa:webkit— WebKit for iOS-only bugs). Before calling UI done, have it opened on a real phone; if that didn't happen, say so. Seeobsidian/workflows/mobile-device-qa.md. - No placeholders at launch.
src/lib/site.tsshipsTODO:values on purpose: every build warns and a Vercel production build fails until the name, description, URL and brand assets are filled (brand kit:yarn qa:brand). Seeobsidian/frontend/seo-metadata.md.
After making changes
Update the vault: dependency changes → tech-stack.md + changelog.md;
a measured fix or a trap worth keeping → obsidian/knowledge/ (evidence rules in
its README);
architectural choices → an ADR in decisions-log.md; new component/hook/util →
the relevant catalog note. The vault-librarian agent can do this pass for you.
<!-- BEGIN:nextjs-agent-rules -->This is NOT the Next.js you know
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.
This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
<!-- END:nextjs-agent-rules -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

