This Agents.md file provides comprehensive guidance for the OpenAI Codex, GitHub Copilot, and other AI agents working with this codebase.
/docs
: Documentation files/src
: Source code that the AI Agent should analyze
/app
: App Router directory with route segments and layout files/auth
: Authentication-related files (better-auth)
- the AI Agent should follow the file-based routing and segment convention
/components
: React components and their Storybook stories that Agents.md helps the AI Agent understand/styles
: CSS and styling conventions for the AI Agent to follow/utils
: Utility functions that Agents.md documents for the AI Agent
/public
: Static assets (the AI Agent should not modify these directly)/tests
: Test files that the AI Agent should maintain and extend
- The AI Agent should consult the README.md for additional project-specific guidance.
- Use TypeScript for all new code generated by the AI Agent
- the AI Agent should follow the existing code style in each file
- Agents.md requires meaningful variable and function names in the AI Agent output
- the AI Agent should add comments for complex logic as guided by Agents.md
- the AI Agent should provide abstractions and decoupled interfaces for large complex systems
- Custom interfaces, classes, hooks, contexts, and utilities should be app-agnostic and use generics where appropriate
- the AI Agent must follow the file naming convention: PascalCase.tsx
- React components and schemas should start with a capital letter
- most other filenames and functions should start with a lower case letter
This project uses Better Auth for authentication. AI agents should be familiar with this system when working on authentication-related features.
The
/docs/better-auth.md
file contains Better Auth's LLM-specific documentation designed to help AI models understand how to properly interact with the authentication system.
- Always use
authClient.useSession()
for session state management in React components
- Handle authentication states with proper loading and error handling
- Maintain consistency with existing authentication UI patterns
- Always use a Data Access Layer (DAL) for database interactions involving sensitive data
- the AI Agent should use Prisma ORM for all database interactions
- the AI Agent should use functional components with hooks as specified in Agents.md
- Keep components generated by the AI Agent small and focused
- Agents.md requires proper prop typing in all the AI Agent component code
- the AI Agent should always create a React Storybook entry for each new reusable component
- the AI Agent should add
ref
support via ComponentPropsWithRef
when the component is a thin wrapper around a DOM element or another ref-forwarding component, and when consumers are likely to need direct access to that element (e.g., for focus, measurement, or scrolling).
- the AI Agent should NEVER use
forwardRef
as it will be deprecated.
- A full list of available components can be found in
docs/component-list.md
.
- The AI Agent should always update relevant documentation and stories when creating or modifying components, and must always update
docs/component-list.md
when adding/removing components.
- The AI Agent must follow the practices outlined in
docs/component-patterns.md
when implementing complex components, pages, and layouts.
- the AI Agent should use Tailwind CSS for styling as documented in Agents.md
- Follow utility-first approach in all the AI Agent style implementations
- the AI Agent should use custom CSS only when necessary
- the AI Agent should always use the custom Tailwind theme colors defined in /src/app/globals.css
- the AI Agent should use tailwind-variants when making new reusable components
the AI Agent should run tests with the following commands:
# Run all tests with the AI Agent
npm test
When the AI Agent helps create a PR, please ensure it:
- Includes a clear description of the changes as guided by Agents.md
- References any related issues that the AI Agent is addressing
- Ensures all tests pass for code generated by the AI Agent
- Includes screenshots for UI changes implemented with the AI Agent
- Keeps PRs focused on a single concern as specified in Agents.md
Before submitting changes generated by the AI Agent, run:
# Build check for the AI Agent implementations
npm run build
All checks must pass before the AI Agent generated code can be merged. Agents.md helps ensure the AI Agent follows these requirements.