ui
AGENTS.md901 starsChanged 19 days agoMITView on GitHub
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…
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 repository4 other files it gives its agents.
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
47 rules. About 0 are common, 25 are distinctive, and 22 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈25
Distinctive · estimate
This author's own choices. Worth a look.
22
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
Write code that is accessible, performant, type-safe, and maintainable.
- Distinctive: line 31
Use explicit types for function parameters and return values when they enhance clarity
- Very specific: line 32
Prefer unknown over any when the type is genuinely unknown
- Very specific: line 33
Use const assertions (as const) for immutable values and literal types
- Distinctive: line 35
Use meaningful variable names instead of magic numbers - extract constants with descriptive names
- Distinctive: line 39
Use arrow functions for callbacks and short functions
- Very specific: line 40
Prefer for...of loops over .forEach() and indexed for loops
- Very specific: line 41
Use optional chaining (?.) and nullish coalescing (??) for safer property access
- Distinctive: line 42
Prefer template literals over string concatenation
- Distinctive: line 43
Use destructuring for object and array assignments
- Very specific: line 44
Use const by default, let only when reassignment is needed, never var
- Very specific: line 48
Always await promises in async functions - don't forget to use the return value
- Very specific: line 49
Use async/await syntax instead of promise chains for better readability
- Distinctive: line 51
Don't use async functions as Promise executors
- Distinctive: line 55
Use function components over class components
- Distinctive: line 56
Call hooks at the top level only, never conditionally
- Very specific: line 58
Use the key prop for elements in iterables (prefer unique IDs over array indices)
- Distinctive: line 60
Don't define components inside other components
- Distinctive: line 61
Use semantic HTML and ARIA attributes for accessibility:
- Distinctive: line 63
Use proper heading hierarchy
- Distinctive: line 64
Add labels for form inputs
- Very specific: line 66
Use semantic elements (<button>, <nav>, etc.) instead of divs with roles
- Very specific: line 70
Remove console.log, debugger, and alert statements from production code
- Very specific: line 72
Use try-catch blocks meaningfully - don't catch errors just to rethrow them
- Distinctive: line 73
Prefer early returns over nested conditionals for error cases
- Distinctive: line 77
Keep functions focused and under reasonable cognitive complexity limits
- Distinctive: line 79
Use early returns to reduce nesting
- Distinctive: line 80
Prefer simple conditionals over nested ternary operators
- Very specific: line 85
Add rel="noopener" when using target="_blank" on links
- Very specific: line 86
Avoid dangerouslySetInnerHTML unless absolutely necessary
- Very specific: line 87
Don't use eval() or assign directly to document.cookie
- Distinctive: line 92
Avoid spread syntax in accumulators within loops
- Distinctive: line 93
Use top-level regex literals instead of creating them in loops
- Distinctive: line 94
Prefer specific imports over namespace imports
- Distinctive: line 95
Avoid barrel files (index files that re-export everything)
- Very specific: line 96
Use proper image components (e.g., Next.js <Image>) over <img> tags
- Very specific: line 102
Use Next.js <Image> component for images
- Very specific: line 103
Use next/head or App Router metadata API for head elements
- Distinctive: line 104
Use Server Components for async data fetching instead of async Client Components
- Very specific: line 108
Use ref as a prop instead of React.forwardRef
- Very specific: line 112
Use class and for attributes (not className or htmlFor)
- Very specific: line 118
Write assertions inside it() or test() blocks
- Distinctive: line 119
Avoid done callbacks in async tests - use async/await instead
- Very specific: line 120
Don't use .only or .skip in committed code
- Very specific: line 121
Keep test suites reasonably flat - avoid excessive describe nesting
- Distinctive: line 128
Meaningful naming: - Use descriptive names for functions, variables, and types
- Distinctive: line 132
Documentation: - Add comments for complex logic, but prefer self-documenting code
≈ “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
<!-- 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 -->Ultracite Code Standards
This project uses Ultracite, a zero-config preset that enforces strict code quality standards through automated formatting and linting.
Quick Reference
- Format code:
npx ultracite fix - Check for issues:
npx ultracite check - Diagnose setup:
npx ultracite doctor
Oxlint + Oxfmt (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.
Core Principles
Write code that is accessible, performant, type-safe, and maintainable. Focus on clarity and explicit intent over brevity.
Type Safety & Explicitness
- Use explicit types for function parameters and return values when they enhance clarity
- Prefer
unknownoveranywhen the type is genuinely unknown - Use const assertions (
as const) for immutable values and literal types - Leverage TypeScript's type narrowing instead of type assertions
- Use meaningful variable names instead of magic numbers - extract constants with descriptive names
Modern JavaScript/TypeScript
- Use arrow functions for callbacks and short functions
- Prefer
for...ofloops over.forEach()and indexedforloops - Use optional chaining (
?.) and nullish coalescing (??) for safer property access - Prefer template literals over string concatenation
- Use destructuring for object and array assignments
- Use
constby default,letonly when reassignment is needed, nevervar
Async & Promises
- Always
awaitpromises in async functions - don't forget to use the return value - Use
async/awaitsyntax instead of promise chains for better readability - Handle errors appropriately in async code with try-catch blocks
- Don't use async functions as Promise executors
React & JSX
- Use function components over class components
- Call hooks at the top level only, never conditionally
- Specify all dependencies in hook dependency arrays correctly
- Use the
keyprop for elements in iterables (prefer unique IDs over array indices) - Nest children between opening and closing tags instead of passing as props
- Don't define components inside other components
- Use semantic HTML and ARIA attributes for accessibility:
- Provide meaningful alt text for images
- Use proper heading hierarchy
- Add labels for form inputs
- Include keyboard event handlers alongside mouse events
- Use semantic elements (
<button>,<nav>, etc.) instead of divs with roles
Error Handling & Debugging
- Remove
console.log,debugger, andalertstatements from production code - Throw
Errorobjects with descriptive messages, not strings or other values - Use
try-catchblocks meaningfully - don't catch errors just to rethrow them - Prefer early returns over nested conditionals for error cases
Code Organization
- Keep functions focused and under reasonable cognitive complexity limits
- Extract complex conditions into well-named boolean variables
- Use early returns to reduce nesting
- Prefer simple conditionals over nested ternary operators
- Group related code together and separate concerns
Security
- Add
rel="noopener"when usingtarget="_blank"on links - Avoid
dangerouslySetInnerHTMLunless absolutely necessary - Don't use
eval()or assign directly todocument.cookie - Validate and sanitize user input
Performance
- Avoid spread syntax in accumulators within loops
- Use top-level regex literals instead of creating them in loops
- Prefer specific imports over namespace imports
- Avoid barrel files (index files that re-export everything)
- Use proper image components (e.g., Next.js
<Image>) over<img>tags
Framework-Specific Guidance
Next.js:
- Use Next.js
<Image>component for images - Use
next/heador App Router metadata API for head elements - Use Server Components for async data fetching instead of async Client Components
React 19+:
- Use ref as a prop instead of
React.forwardRef
Solid/Svelte/Vue/Qwik:
- Use
classandforattributes (notclassNameorhtmlFor)
Testing
- Write assertions inside
it()ortest()blocks - Avoid done callbacks in async tests - use async/await instead
- Don't use
.onlyor.skipin committed code - Keep test suites reasonably flat - avoid excessive
describenesting
When Oxlint + Oxfmt Can't Help
Oxlint + Oxfmt will catch most mechanical issues automatically. Focus your attention on:
- Business logic correctness - Oxlint + Oxfmt can't validate your algorithms
- Meaningful naming - Use descriptive names for functions, variables, and types
- Architecture decisions - Component structure, data flow, and API design
- Edge cases - Handle boundary conditions and error states
- User experience - Accessibility, performance, and usability considerations
- Documentation - Add comments for complex logic, but prefer self-documenting code
Most formatting and common issues are automatically fixed by Oxlint + Oxfmt. Run npx ultracite fix before committing to ensure compliance.
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.

