AGENTS.md Configuration

1Codex looks for AGENTS.md in these locations:
2
31. Repository root
4   /AGENTS.md                    # Primary location
5
62. Subdirectories (for monorepos)
7   /packages/api/AGENTS.md       # Package-specific
8   /apps/web/AGENTS.md           # App-specific
9
103. Nested directories (context inheritance)
11   /src/AGENTS.md                # src-specific overrides
12   /src/api/AGENTS.md            # api-specific overrides
13
14Note: More specific files override less specific ones.

1# AGENTS.md
2
3## Project Overview
4
5Brief description of what this project does.
6
7## Tech Stack
8
9- Language: TypeScript
10- Framework: Next.js 14
11- Database: PostgreSQL with Prisma
12- Testing: Jest + React Testing Library
13- Styling: Tailwind CSS
14
15## Architecture
16
17```
18src/
19├── app/           # Next.js App Router pages
20├── components/    # React components
21├── lib/           # Utility functions
22├── server/        # Server-side code
23│   ├── api/       # API route handlers
24│   └── db/        # Database operations
25└── types/         # TypeScript definitions
26```
27
28## Development Commands
29
30```bash
31# Install dependencies
32npm install
33
34# Run development server
35npm run dev
36
37# Run tests
38npm test
39
40# Type check
41npx tsc --noEmit
42
43# Lint
44npm run lint
45
46# Build for production
47npm run build
48```
49
50## Code Conventions
51
52### Naming
53- Components: PascalCase (UserProfile.tsx)
54- Utilities: camelCase (formatDate.ts)
55- Constants: UPPER_SNAKE_CASE
56- Types/Interfaces: PascalCase with prefix (IUser, TResponse)
57
58### File Organization
59- One component per file
60- Co-locate related files (component + test + styles)
61- Export from index.ts barrel files
62
63### Patterns
64- Use functional components with hooks
65- Prefer composition over inheritance
66- Use Zod for runtime validation
67
68## Testing Requirements
69
70- All new features need tests
71- Minimum 80% coverage for new code
72- Use data-testid for test selectors
73- Mock external services
74
75## What NOT to Do
76
77- Do not modify /generated directory
78- Do not add new npm dependencies without discussion
79- Do not use `any` type without justification
80- Do not commit .env files
81- Do not modify database schema without migration
82
83## API Guidelines
84
85### Response Format
86```typescript
87{
88  success: boolean;
89  data?: T;
90  error?: { code: string; message: string };
91}
92```
93
94### Error Codes
95- AUTH_REQUIRED: Authentication needed
96- FORBIDDEN: Insufficient permissions
97- NOT_FOUND: Resource not found
98- VALIDATION_ERROR: Invalid input
99
100## Database
101
102### Naming
103- Tables: PascalCase singular (User, Post)
104- Columns: camelCase (createdAt, userId)
105- Foreign keys: resourceId (userId, postId)
106
107### Migrations
108Always use Prisma migrations:
109```bash
110npx prisma migrate dev --name description
111```

1# AGENTS.md - Monorepo Root
2
3## Structure
4
5This is a Turborepo monorepo:
6
7```
8apps/
9├── web/         # Next.js frontend
10├── api/         # Express backend
11└── admin/       # Admin dashboard
12
13packages/
14├── ui/          # Shared UI components
15├── database/    # Prisma schema and client
16├── config/      # Shared configuration
17└── types/       # Shared TypeScript types
18```
19
20## Commands
21
22```bash
23# Run all apps in development
24npm run dev
25
26# Run specific app
27npm run dev --filter=web
28
29# Build all
30npm run build
31
32# Test all
33npm run test
34```
35
36## Cross-Package Rules
37
381. apps/* can import from packages/*
392. packages/* cannot import from apps/*
403. packages/* can import from other packages/*
414. Circular dependencies are forbidden
42
43## Shared Packages
44
45When modifying packages/, remember:
46- Changes affect multiple apps
47- Run tests for all consuming apps
48- Consider backwards compatibility

1# AGENTS.md - API Service
2
3## Service Overview
4
5REST API service handling user authentication and data management.
6
7## Key Files
8
9- `src/index.ts` - Entry point
10- `src/routes/` - Route definitions
11- `src/controllers/` - Request handlers
12- `src/services/` - Business logic
13- `src/repositories/` - Data access
14
15## Authentication
16
17All routes except /health and /auth/* require JWT.
18
19Use the `authenticate` middleware:
20```typescript
21import { authenticate } from '@/middleware/auth';
22
23router.get('/users', authenticate, getUsers);
24```
25
26## Error Handling
27
28Always use AppError class:
29```typescript
30import { AppError } from '@/errors';
31
32throw new AppError('User not found', 404, 'USER_NOT_FOUND');
33```
34
35## Rate Limiting
36
37- Auth endpoints: 5 requests/minute
38- General endpoints: 100 requests/minute
39- Upload endpoints: 10 requests/minute
40
41## Environment Variables
42
43Required in .env:
44- DATABASE_URL: PostgreSQL connection
45- JWT_SECRET: For token signing
46- REDIS_URL: For sessions and caching

1## Commands
2
3# ❌ Vague
4Run tests before committing.
5
6# ✅ Explicit
7```bash
8# Run all tests
9npm test
10
11# Run specific test file
12npm test -- path/to/test.ts
13
14# Run with coverage
15npm run test:coverage
16```

1## Creating New API Endpoints
2
31. Create route file in `src/routes/`:
4```typescript
5// src/routes/widgets.ts
6import { Router } from 'express';
7import { authenticate } from '@/middleware/auth';
8import { validate } from '@/middleware/validate';
9import { widgetSchema } from '@/schemas/widget';
10import * as controller from '@/controllers/widgets';
11
12const router = Router();
13
14router.get('/', authenticate, controller.list);
15router.post('/', authenticate, validate(widgetSchema), controller.create);
16
17export default router;
18```
19
202. Register in `src/routes/index.ts`:
21```typescript
22import widgets from './widgets';
23router.use('/widgets', widgets);
24```
25
263. Create test in `tests/routes/widgets.test.ts`

1## Known Quirks
2
3### Authentication
4- Tokens expire after 24 hours
5- Refresh tokens last 7 days
6- Admin tokens have different expiry (30 days)
7
8### Database
9- All timestamps are UTC
10- Soft deletes use `deletedAt` column
11- IDs are UUIDs, not auto-increment
12
13### Testing
14- Tests run in isolated database
15- Seed data is in `tests/fixtures/`
16- Some tests require Redis running

1## Anti-Patterns to Avoid
2
3### Code
4- Do not use `console.log` in production code (use logger)
5- Do not catch errors and swallow them silently
6- Do not use string concatenation for SQL (use parameterized)
7
8### Architecture
9- Do not call repositories directly from routes (use services)
10- Do not put business logic in controllers
11- Do not create circular dependencies between services
12
13### Git
14- Do not commit directly to main
15- Do not force push to shared branches
16- Do not commit large binary files