From d3187f7fe47c45d83174f10e219d233c1da63687 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yusuf=20=C4=B0pek?= <yusufipek@protonmail.com>
Date: Sun, 15 Feb 2026 11:22:03 +0300
Subject: [PATCH] docs: add AGENTS.md with coding guidelines for agents

---
 AGENTS.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 186 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6b6ffd1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,186 @@
+# AGENTS.md - Agent Coding Guidelines
+
+This document provides guidelines for agents working on the OpenFrame project.
+
+## Project Overview
+
+OpenFrame is a Next.js 16 video sharing platform with:
+- Next.js 16 App Router, TypeScript with strict mode, Tailwind CSS v4
+- Prisma ORM with PostgreSQL, NextAuth v5 (Auth.js), shadcn/ui components
+
+---
+
+## Build & Development Commands
+
+### Core Commands
+
+```bash
+bun run dev              # Start Next.js dev server
+bun run build            # Build for production (runs typecheck first)
+bun run typecheck        # Run TypeScript type checking only
+bun run lint             # Run ESLint
+bun test                 # Run all tests
+bun test path/to/test.ts # Run specific test file
+```
+
+### Database Commands
+
+```bash
+bun run db:generate      # Generate Prisma client
+bun run db:push          # Push schema to database
+bun run db:migrate       # Run database migrations
+bun run db:seed          # Seed database
+bun run db:setup         # Full DB setup: generate + push + extras
+```
+
+### Important Notes
+
+- **Always use bun** - Never use npm or pnpm.
+- Pre-build runs typecheck automatically via `prebuild` script.
+- Post-install runs `prisma generate` automatically.
+
+---
+
+## Code Style Guidelines
+
+### TypeScript
+
+- **Strict mode enabled** - All TypeScript strict checks are on
+- Use explicit types for function parameters and return types
+- Use `interface` for public APIs, `type` for unions/intersections
+- Avoid `any` - use `unknown` when type is truly unknown
+- Use optional chaining (`?.`) and nullish coalescing (`??`)
+
+```typescript
+// Good
+function getUserById(id: string): Promise<User | null>
+const name = user?.name ?? 'Anonymous'
+
+// Avoid
+function getUser(id) // Missing types
+```
+
+### Imports & Path Aliases
+
+- Use `@/` prefix for absolute imports (configured in tsconfig.json)
+- Order: React/Next → External libs → Internal modules (@/) → Relative
+
+```typescript
+import { useState, useEffect } from 'react'
+import { z } from 'zod'
+import { db } from '@/lib/db'
+import { cn } from '@/lib/utils'
+```
+
+### Components
+
+- Use functional components with TypeScript
+- Use shadcn/ui components from `components/ui/`
+- Use `cva` (class-variance-authority) for component variants
+- Use Radix UI primitives for accessible interactive components
+
+```typescript
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva("...", {
+  variants: {
+    variant: { default: "...", destructive: "..." },
+    size: { default: "...", sm: "..." },
+  },
+  defaultVariants: { variant: "default", size: "default" },
+})
+
+function Button({ className, variant, size, ...props }: ButtonProps) {
+  return <button className={cn(buttonVariants({ variant, size }), className)} {...props} />
+}
+```
+
+### Naming Conventions
+
+- **Files**: kebab-case for utilities (`rate-limit.ts`), PascalCase for components (`VideoCard.tsx`)
+- **Components**: PascalCase (`Button`, `VideoCard`)
+- **Functions**: camelCase (`getUserById`, `validateUrl`)
+- **Booleans**: Use `is`, `has`, `can`, `should` prefixes (`isLoading`, `hasAccess`)
+
+### Error Handling
+
+- Use try/catch with async/await
+- Return typed error results or use error boundaries
+- Log errors with console.error for server-side
+
+```typescript
+async function createProject(data: CreateProjectInput) {
+  try {
+    const project = await db.project.create({ data })
+    return { success: true, data: project }
+  } catch (error) {
+    console.error('Failed to create project:', error)
+    return { success: false, error: 'Failed to create project' }
+  }
+}
+```
+
+### Validation
+
+- Use Zod for runtime validation
+- Create reusable validation schemas
+- Validate at API boundaries (server actions, API routes)
+
+```typescript
+import { z } from 'zod'
+export const createProjectSchema = z.object({
+  name: z.string().min(1).max(100),
+  description: z.string().max(500).optional(),
+  visibility: z.enum(['PUBLIC', 'PRIVATE']),
+})
+```
+
+### Database (Prisma)
+
+- Use Prisma client from `@/lib/db`
+- Use transactions for multi-step operations
+- Include relations with `include` or `select`
+
+```typescript
+const project = await db.project.findUnique({
+  where: { id: projectId },
+  include: { owner: true, videos: true },
+})
+```
+
+### Authentication
+
+- Use NextAuth v5 from `@/lib/auth`
+- Use `auth()` for getting current session in server components
+- Use `checkProjectAccess()` and `checkWorkspaceAccess()` helpers for authorization
+
+### Styling
+
+- Use Tailwind CSS v4
+- Use `cn()` utility for conditional class merging
+- Components use `rounded-none` as default (per project design)
+
+### Next.js Patterns
+
+- Server components by default, add `'use client'` only when needed
+- Use loading.tsx for loading states
+- Use error.tsx for error boundaries, not-found.tsx for 404 pages
+
+### File Organization
+
+```
+app/              # Next.js App Router pages
+components/ui/    # shadcn/ui components
+lib/              # Utilities (db.ts, auth.ts, utils.ts, validation.ts)
+prisma/           # Database schema
+```
+
+---
+
+## Additional Guidelines
+
+1. **Run typecheck before committing** - `bun run typecheck` must pass
+2. **Run lint before committing** - `bun run lint` must pass
+3. **Environment variables** - Copy `.env.example` to `.env`
+4. **Database changes** - After modifying Prisma schema, run `bun run db:generate`