lawn
AGENTS.md690 starsChanged 5 months agoMITView on GitHub
Generally speaking, you should browse the codebase to figure out what is going on. We have a few "philosophies" I want to make sure we honor throughout development: When in doubt, do the thing that makes the app feel the fastest to use. This includes things like Users should expect things to behave well by default. Less config is best. We should not compromise on simplicity and good ux. We want to be pleasant to use with as little friction…
- Reads credentials
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 31,700 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 repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- convex-create-componentSkill
- convex-migration-helperSkill
- convex-performance-auditSkill
- convex-quickstartSkill
- convex-setup-authSkill
- convexSkill
- convex-create-componentSkill
- convex-migration-helperSkill
- convex-performance-auditSkill
- convex-quickstartSkill
- convex-setup-authSkill
- convexSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
When in doubt, do the thing that makes the app feel the fastest to use.
- Distinctive: line 25
All links are "share" links by default
- Very specific: line 63
When working on Convex code, always read convex/_generated/ai/guidelines.md first for important guidelines on how to correctly use Convex …
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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 info
Generally speaking, you should browse the codebase to figure out what is going on.
We have a few "philosophies" I want to make sure we honor throughout development:
1. Performance above all else
When in doubt, do the thing that makes the app feel the fastest to use.
This includes things like
- Optimistic updates
- Using the custom data loader patterns and custom link components with prewarm on hover
- Avoiding waterfalls in anything from js to file fetching
2. Good defaults
Users should expect things to behave well by default. Less config is best.
3. Convenience
We should not compromise on simplicity and good ux. We want to be pleasant to use with as little friction as possible. This means things like:
- All links are "share" links by default
- Getting from homepage to latest video should always be fewer than 4 clicks
- Minimize blocking states to let users get into app asap
4. Security
We want to make things convenient, but we don't want to be insecure. Be thoughtful about how things are implemented. Check team status and user status before committing changes. Be VERY thoughtful about endpoints exposed "publicly". Use auth and auth checks where they make sense to.
Local development
bun run dev runs the app against a local Convex deployment that is unique
to this git worktree (anonymous mode, data in ./.convex, no login, offline).
This lets multiple Conductor workspaces run in parallel without sharing one
cloud dev backend. The script (scripts/dev.sh) provisions the deployment on
first run via scripts/convex-local-setup.sh, which configures it and seeds its
env vars from .env.local (plus CLERK_JWT_ISSUER_DOMAIN, derived from the
Clerk publishable key).
bun run dev— Vite + local Convex (the default).bun run dev:cloud— Vite + the shared cloud dev deployment (old behavior).bun run convex:local— re-provision the local deployment (or delete.convex/.seededand re-rundev).
Some deployment secrets live only in the Convex cloud dashboard and are not
in .env.local, so those features need extra setup to work locally — add the
values to .env.convex.local (git-ignored, auto-seeded):
RAILWAY_*— S3-compatible storage (video file uploads)MUX_*— Mux encoding / playback
They are read at runtime, so the function push still succeeds without them.
External webhooks (Stripe, Chunkify, Clerk) can't reach a 127.0.0.1 backend
without a tunnel, so use dev:cloud (or a tunnel) when testing webhook flows.
<!-- convex-ai-start -->This project uses Convex as its backend.
When working on Convex code, always read
convex/_generated/ai/guidelines.md first for important guidelines on
how to correctly use Convex APIs and patterns. The file contains rules that
override what you may have learned about Convex from training data.
Convex agent skills for common tasks can be installed by running
npx convex ai-files install.
<!-- convex-ai-end -->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.