AGENTS.md Guide: Setup & CLAUDE.md

your-project/
  AGENTS.md          <- repo-level config
  src/
  tests/
  package.json

# AGENTS.md

- All code should be written in TypeScript with strict mode enabled
- Use Prettier for formatting, ESLint for linting
- Tests use Vitest, placed in `__tests__/` directories
- Run `npm run lint && npm test` before completing any task
- Never modify files in the `vendor/` directory
- API responses must follow the standard envelope format: `{ code, data, message }`

# AGENTS.md

## Code Standards

- Use TypeScript strict mode
- Variables use camelCase, types use PascalCase
- Each function should be no more than 50 lines

## Testing Requirements

- Unit test coverage target: 80%
- Test files share the source file name with a `.test.ts` suffix
- Mock external dependencies; no real network requests in tests

## Prohibited Practices

- Do not use the `any` type
- Do not manipulate the DOM directly (use React state management)
- Do not use `await` inside loops (use `Promise.all` instead)

# Global AGENTS.md

## General Standards

- Write code comments in English
- Git commit messages follow Conventional Commits
- Never hardcode passwords, keys, or tokens in source code
- Read existing related code before generating new code to maintain consistency
- If unsure about the impact of a change, add a comment explaining it rather than making assumptions

## Output Preferences

- Prefer existing project dependencies; don't introduce new ones unnecessarily
- Error handling must be thorough; never swallow exceptions silently
- Log messages should be meaningful and include context

# AGENTS.md

## Project Overview
A React + Node.js full-stack e-commerce project built with TypeScript.

## Tech Stack

- Frontend: React 19 + TailwindCSS + Zustand
- Backend: Node.js + Fastify + Prisma
- Database: PostgreSQL 16
- Testing: Vitest + Playwright

## Code Standards

- Component files use PascalCase: `UserProfile.tsx`
- Utility functions use camelCase: `formatDate.ts`
- API routes use kebab-case: `/api/user-orders`
- Database fields use snake_case: `created_at`

## Project Structure

- `src/components/` - React components
- `src/pages/` - Page components
- `src/api/` - Backend API routes
- `src/lib/` - Shared utility library
- `prisma/` - Database schema and migrations

## Commands

- `npm run dev` - Start the dev server
- `npm run build` - Build for production
- `npm test` - Run all tests
- `npm run lint` - Run linting
- `npx prisma migrate dev` - Run database migrations

your-project/
  AGENTS.md                  <- project-level rules
  src/
    components/
      AGENTS.md              <- component directory rules
    api/
      AGENTS.md              <- API directory rules

# Component Standards

- All components must be function components (no class components)
- Props must have a TypeScript interface definition
- Every component must have a displayName
- Use TailwindCSS for styling; no inline styles
- Split complex components into sub-components; keep each file under 200 lines
- Reusable components go in the `ui/` subdirectory

# API Standards

- All endpoints must validate request parameters (using Zod schemas)
- Uniform error format: `{ code: number, message: string, details?: any }`
- Database operations must run inside transactions
- Sensitive operations must be audit-logged
- Pagination endpoints use cursor-based pagination

Global (~/.codex/AGENTS.md)
  | overridden by repo-level
Repo root (project/AGENTS.md)
  | overridden by subdirectory
Subdirectory (project/src/api/AGENTS.md) <- highest priority

# AGENTS.md

## Project Info
React 19 + TypeScript + TailwindCSS frontend project.

## Code Standards

- Use function components + Hooks; class components are prohibited
- State management uses Zustand; do not introduce Redux
- Styling with TailwindCSS; no CSS files
- Use `@/` path alias to reference modules under src
- Define component Props as an interface named `{ComponentName}Props`

## File Naming

- Component files: PascalCase (`UserAvatar.tsx`)
- Hook files: camelCase + use prefix (`useAuth.ts`)
- Utility files: camelCase (`formatDate.ts`)
- Constant files: camelCase (`apiEndpoints.ts`)

## Component Rules

- Export both the Props type and the component itself
- Wrap pure presentational components with `React.memo`
- Name event handlers as `handle{EventName}`
- Avoid creating new objects or functions inside render

## Testing

- Framework: Vitest + React Testing Library
- Test files go in `__tests__/` directories
- Test user behavior, not implementation details
- Run command: `npm test`

## Dependency Management

- Before adding a new dependency, check if existing ones already cover the need
- Prefer lightweight libraries
- All dependencies must have TypeScript type definitions

# AGENTS.md

## Project Info
Python 3.12 + FastAPI + SQLAlchemy backend service.

## Code Standards

- Type annotations: all function parameters and return values must have type annotations
- Async first: all IO operations must use async/await
- Docstrings: all public functions use Google-style docstrings
- Import ordering: stdlib -> third-party -> local modules (managed by isort)

## Project Structure

- `app/api/` - API routes (organized by feature router)
- `app/models/` - SQLAlchemy data models
- `app/schemas/` - Pydantic request/response models
- `app/services/` - Business logic layer
- `app/core/` - Configuration, security, dependency injection
- `tests/` - Test files, mirroring the app directory structure
- `alembic/` - Database migrations

## Coding Conventions

- Route function naming: `get_users`, `create_order` (verb_noun)
- Service layer methods: correspond to route functions
- Data model fields use snake_case
- All database operations go through the Service layer; routes never touch the ORM directly
- Sensitive data (passwords, tokens) must never appear in logs or responses

## Error Handling

- Business exceptions use custom Exception classes
- Unified exception handler returns standard format: `{"code": int, "message": str}`
- Database operations are wrapped in try/except to catch IntegrityError, etc.
- Never use bare except

## Testing

- Framework: pytest + pytest-asyncio + httpx
- Use fixtures to manage test database and client
- Run command: `pytest -v --cov=app`
- Minimum coverage target: 80%

## Environment Management

- Use .env files for configuration, loaded via pydantic-settings
- Environment-specific differences are handled via environment variable overrides
- Never hardcode database connection strings, secrets, etc. in code

# AGENTS.md

## Project Info
Full-stack web app: Next.js 15 frontend + API Routes + PostgreSQL.
Monorepo structure managed with Turborepo.

## Directory Structure

- `apps/web/` - Next.js frontend
- `apps/api/` - Standalone API service (Node.js + Fastify)
- `packages/ui/` - Shared UI component library
- `packages/types/` - Shared TypeScript types
- `packages/utils/` - Shared utility functions
- `packages/db/` - Database schema (Drizzle ORM)

## General Standards

- Language: TypeScript strict mode
- Formatting: Prettier (configured at root)
- Lint: ESLint (configured at root)
- Before committing, run: `turbo lint test`

## Frontend Standards (apps/web/)

- Use App Router, not Pages Router
- Server Components first; Client Components only when necessary
- Data fetching via Server Actions or Route Handlers
- Styling with TailwindCSS
- Images use the next/image component

## API Standards (apps/api/)

- RESTful design, URLs use kebab-case
- Request validation with Zod
- Response format: `{ success: boolean, data?: T, error?: string }`
- Authentication via JWT, validated in middleware
- Rate limiting rules go in route decorators

## Database Standards (packages/db/)

- Use Drizzle ORM; schema defined in the `schema/` directory
- Migration command: `pnpm db:migrate`
- Naming: table names are plural (`users`), fields use snake_case
- All tables must have `created_at` and `updated_at`
- Soft deletes use a `deleted_at` field

## Shared Package Standards

- Packages reference each other via workspace
- Shared type definitions go in `packages/types/`
- Packages must not import from apps

your-project/
  AGENTS.md          <- read by Codex
  CLAUDE.md          <- read by Claude Code
  src/
  ...

# AGENTS.md

> This project uses both Codex and Claude Code. Core standards are below.
> Claude Code users, refer to CLAUDE.md.

## Core Standards
(shared content)

git add AGENTS.md
git commit -m "feat: add AGENTS.md for Codex configuration"

<!-- PR description -->
## Change Summary
Updates to AGENTS.md:

- Added API pagination standard (cursor-based)
- Explicitly prohibited direct fetch calls in components
- Added logging format requirements

## High-Effectiveness Instructions (Codex follows these reliably)

- Explicit format requirements: Use PascalCase for component file names
- Explicit prohibitions: Do not use the any type
- Run commands: Run npm test after completing the task
- File location rules: Test files go in __tests__ directories
- Dependency constraints: Do not introduce new npm packages; use existing dependencies

## Low-Effectiveness Instructions (best avoided)

- Too vague: Write good code
- Subjective: Use best practices
- Out of scope: Consider user experience (AI can't run a UI)
- Contradictory: Prioritize performance + prioritize readability (need explicit priority)

## File Type Rules

### *.test.ts files

- No more than 10 tests per describe block
- Use factory functions to create test data; no hardcoding
- Async tests must have timeout settings

### *.api.ts files

- Must validate request parameters
- Must include error handling
- Return values must have type annotations

### migrations/*.sql files

- Do not modify directly; use the ORM migration tool to generate

cp CLAUDE.md AGENTS.md

## Code Style

In this project, we follow the Google TypeScript style guide. All variable
names use camelCase, class names use PascalCase. Note that enum values use
SCREAMING_SNAKE_CASE. Import statements should be ordered as follows: first
Node.js built-in modules, then third-party packages, and finally local
modules. Separate each group with a blank line.

## Code Style

- Follow the Google TypeScript style guide
- Variables: camelCase
- Classes: PascalCase
- Enum values: SCREAMING_SNAKE_CASE
- Import order: built-in modules -> third-party packages -> local modules (blank line between groups)

## Codex-Specific Configuration

- After all file modifications, run `npm run lint && npm test` to verify
- If tests fail, automatically fix and re-run
- Do not modify .env and .env.local files

# Assuming AGENTS.md requires TypeScript
codex "Create a hello world function"

# If AGENTS.md is active, Codex will generate a .ts file instead of .js

# CLAUDE.md

@AGENTS.md

## Claude Code-only extras

- Use `/model` to switch between Sonnet 4.6 / Opus 4.8 per task
- Run `/plan` before large changes
- Use `/clear` between unrelated tasks; `/compact` at logical breakpoints in long sessions