# راهنمای AGENTS.md: راه‌اندازی و CLAUDE.md

> **آخرین بازبینی**: 2026-10-20 · 📄 بر اساس مستندات رسمی (AGENTS.md، Codex، Claude Code)

`AGENTS.md` یک فایل دستورالعمل Markdown باز برای عامل‌های کدنویسی است: Codex آن را می‌خواند و Claude Code نسخه v2.1.277 و بالاتر، وقتی `CLAUDE.md` وجود نداشته باشد، آن را مستقیماً می‌خواند. یک فایل می‌تواند هم‌زمان به چند ابزار خدمت کند.

`AGENTS.md` برای Codex همان نقشی را دارد که `CLAUDE.md` برای Claude Code دارد. این یک فایل Markdown است که در پروژه شما قرار می‌گیرد و به دستیار کدنویسی با هوش مصنوعی می‌گوید: این پروژه از چه استانداردهایی پیروی می‌کند، کد باید چگونه نوشته شود و از چه چیزهایی پرهیز شود.

اگر پیش‌تر از `CLAUDE.md` در Claude Code استفاده می‌کنید، مفهوم `AGENTS.md` برای شما آشنا خواهد بود. آن‌ها فلسفه یکسانی دارند، اما در برخی جزئیات قالب‌بندی تفاوت دارند. این راهنما پیکربندی `AGENTS.md` را به‌طور عمیق پوشش می‌دهد و نشان می‌دهد چگونه استانداردهای پروژه را به‌شکل کارآمد در هر دو ابزار بازاستفاده کنید.

---

> **این دیگر فقط یک فایل Codex نیست.** سایت AGENTS.md آن را «یک قالب ساده و باز برای راهنمایی عامل‌های کدنویسی» می‌نامد که بیش از 60k پروژه متن‌باز از آن استفاده می‌کنند (بررسی‌شده در 2026-10-20). اکنون سرپرستی آن بر عهده بنیاد Agentic AI زیر نظر Linux Foundation است و عبارت‌بندی سایت این است: «یک AGENTS.md در بسیاری از عامل‌ها کار می‌کند»: ابزارهای فهرست‌شده در آن عبارت‌اند از Codex، Jules، Factory، Aider، goose، opencode، Zed، Warp، VS Code، Devin، Cursor، RooCode، Gemini CLI، Kilo Code، GitHub Copilot، Windsurf، Augment Code، Amp و دیگران. در عمل این یعنی یک `AGENTS.md` توسط مجموعه‌ای در حال رشد از ابزارها خوانده می‌شود، نه فقط Codex. پیش‌زمینه: در مارس 2026، Anthropic، OpenAI، Google، AWS، Microsoft و Salesforce بنیاد Agentic AI (AAIF) را بنیان گذاشتند که MCP، AGENTS.md و Goose را به‌عنوان زمینه مشترک پذیرفت.

## AGENTS.md در برابر CLAUDE.md

پیش از ورود به جزئیات `AGENTS.md`، مقایسه آن با `CLAUDE.md` را ببینید:

| جنبه | AGENTS.md (Codex) | CLAUDE.md (Claude Code) |
|--------|---------------------|--------------------------|
| ابزار | OpenAI Codex CLI | Anthropic Claude Code |
| قالب فایل | Markdown | Markdown |
| سلسله‌مراتب بارگذاری | سراسری `~/.codex`، سپس ریشه پروژه تا دایرکتوری جاری | سراسری `~/.claude/CLAUDE.md`، ریشه پروژه و زیردایرکتوری‌ها، به‌علاوه `.claude/rules/` |
| مکان سراسری | `~/.codex/AGENTS.md` (`AGENTS.override.md` اولویت دارد) | `~/.claude/CLAUDE.md` |
| سازوکار بازنویسی | زیردایرکتوری می‌تواند قواعد والد را بازنویسی کند | زیردایرکتوری می‌تواند قواعد را بیفزاید/بازنویسی کند |
| سبک نگارش | به فهرست‌های مختصر و سبک دستوری تمایل دارد | از توضیحات مفصل پشتیبانی می‌کند؛ سبک گفتاری نیز کارساز است |
| پذیرش در جامعه | به‌سرعت در حال رشد است و بسیاری از پروژه‌های متن‌باز پیش‌تر آن را پذیرفته‌اند | به‌طور گسترده پذیرفته شده و زیست‌بوم آن بالغ است |
| کنترل نسخه | توصیه می‌شود در مخزن کامیت شود | توصیه می‌شود در مخزن کامیت شود |
| شناسایی متقابل | CLAUDE.md را نمی‌خواند | وقتی `CLAUDE.md` وجود نداشته باشد، AGENTS.md را می‌خواند (v2.1.277+) |

> **نکته کلیدی**: Codex همچنان `CLAUDE.md` را نمی‌خواند، در حالی که Claude Code اکنون می‌تواند `AGENTS.md` را مستقیماً بخواند. برای اینکه هر دو فایل اثر کنند، در Claude Code دستور `/config` را تایپ کنید و «Project instructions» را روی `claude-md-and-agents-md` قرار دهید. محتوای اصلی همچنان می‌تواند مشترک باشد.

---
## پیکربندی پایه

### محل فایل

فایل `AGENTS.md` را در ریشه پروژه خود ایجاد کنید:

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

### نحو پایه

`AGENTS.md` یک فایل Markdown استاندارد است. Codex آن را هنگام راه‌اندازی می‌خواند و دستورهای داخل آن را دنبال می‌کند. رایج‌ترین قالب **فهرست‌های بدون ترتیب** است:

```markdown
# 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 }`
```

همچنین می‌توانید قواعد را با عنوان‌ها بر اساس دسته سازمان‌دهی کنید:

```markdown
# 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)
```

### انتخاب زبان

محتوای `AGENTS.md` را می‌توان به **چینی** یا **انگلیسی** نوشت. Codex هر دو زبان را درست می‌فهمد. در همکاری تیمی:

- **پروژه‌های شخصی**: از زبانی که با آن راحت‌تر هستید استفاده کنید
- **پروژه‌های تیمی**: انگلیسی توصیه می‌شود (هماهنگ با کد)
- **تیم‌های چینی‌زبان**: چینی هم کاملاً بی‌مشکل کار می‌کند

---

## پیکربندی لایه‌ای

`AGENTS.md` از سه سطح پیکربندی پشتیبانی می‌کند و قواعد را از سطح سراسری تا پوشه‌های مشخص دقیق‌تر می‌کند:

### سطح 1: پیکربندی سراسری

محل: `~/.codex/AGENTS.md`

استانداردهای سراسری که برای همه پروژه‌های شما اعمال می‌شوند:

```markdown
# 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
```

### سطح 2: پیکربندی سطح مخزن

محل: `AGENTS.md` در ریشه پروژه

استانداردهای مخصوص یک پروژه مشخص:

```markdown
# 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
```

### سطح 3: پیکربندی زیرپوشه

محل: `AGENTS.md` در هر زیرپوشه‌ای

قواعد تکمیلی برای ماژول‌های مشخص که **روی قواعد سطح والد لایه‌بندی می‌شوند**:

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

مثال `src/components/AGENTS.md`:

```markdown
# 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
```

مثال `src/api/AGENTS.md`:

```markdown
# 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
```

### اولویت بازنویسی

وقتی قواعد در چند سطح مختلف `AGENTS.md` با هم تعارض داشته باشند، **نزدیک‌تر اولویت دارد**:

```
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` زیرپوشه بر سطوح والد اولویت دارند
- قواعد والد که بازنویسی نشده‌اند همچنان اعمال می‌شوند
- قواعد چندسطحی **افزودنی** هستند، نه جایگزینی کامل

### ترتیب خواندن توسط Codex (بررسی‌شده در 2026-10-20)

- **سراسری**: در پوشه خانه Codex شما (به‌طور پیش‌فرض `~/.codex`؛ برای استفاده از پوشه‌ای دیگر `CODEX_HOME` را تنظیم کنید)، Codex اگر `AGENTS.override.md` وجود داشته باشد آن را می‌خواند، در غیر این صورت `AGENTS.md` را می‌خواند.
- **پروژه**: Codex با شروع از ریشه پروژه و حرکت به سمت پایین تا پوشه فعلی، در هر سطح `AGENTS.override.md`، سپس `AGENTS.md` و پس از آن هر نام جایگزین را بررسی می‌کند و حداکثر یک فایل از هر پوشه را شامل می‌شود.
- **ادغام**: فایل‌ها از ریشه به سمت پایین به هم متصل می‌شوند؛ بنابراین فایل‌های نزدیک‌تر به پوشه فعلی دیرتر ظاهر می‌شوند و راهنمایی‌های قبلی را بازنویسی می‌کنند.
- **محدودیت اندازه**: Codex زمانی که اندازه مجموع به `project_doc_max_bytes` برسد از افزودن فایل‌ها دست می‌کشد؛ این مقدار به‌طور پیش‌فرض 32 KiB است.
- **نام‌های جایگزین**: در پیکربندی Codex خود `project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]` را تنظیم کنید تا وقتی دو فایل اصلی وجود ندارند، آن فایل‌ها خوانده شوند.

### نحوه خواندن AGENTS.md توسط Claude Code (بررسی‌شده در 2026-10-20)

- **شرط پیش‌فرض**: Claude Code فقط زمانی `AGENTS.md` را می‌خواند که پوشه کاری شما و پوشه‌های بالاتر از آن هیچ‌کدام `CLAUDE.md`، `.claude/CLAUDE.md` یا `CLAUDE.local.md` نداشته باشند (نسخه v2.1.277 و بعد از آن). `~/.claude/CLAUDE.md`، CLAUDE.md مدیریت‌شده یک سازمان و `.claude/rules/` برای این بررسی به حساب نمی‌آیند و در کنار آن همچنان بارگذاری می‌شوند.
- **چه چیزی خوانده می‌شود**: در شروع نشست، `AGENTS.md` و `.claude/AGENTS.md` در پوشه کاری شما و پوشه‌های بالاتر از آن خوانده می‌شوند.
- **چه چیزی خوانده نمی‌شود**: `AGENTS.local.md`، `AGENTS.override.md` یا هر چیزی درون پوشه `.agents/`.
- **خواندن هر دو فایل**: در یک نشست `/config` را تایپ کنید و «Project instructions» را روی `claude-md-or-agents-md` (پیش‌فرض)، `claude-md-and-agents-md` (هر دو)، `claude-md` (فقط CLAUDE.md) یا `managed-only` تنظیم کنید.
- **الزام نسخه**: خواندن مستقیم به v2.1.277 یا بالاتر نیاز دارد؛ نشست‌هایی که نمی‌توانند آن را مستقیماً بخوانند همچنان می‌توانند آن را با `@AGENTS.md` از `CLAUDE.md` وارد کنند.

---
## قالب‌های عملی

در ادامه چند قالب آزموده‌شده در عمل آورده شده است که می‌توانید آن‌ها را مستقیماً در پروژه‌های خود کپی کنید.

### پروژه فرانت‌اند React

```markdown
# 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
```

### پروژه بک‌اند Python/FastAPI

```markdown
# 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
```

### پروژه فول‌استک

```markdown
# 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
```

---
## نکات پیشرفته

### هم‌زیستی با CLAUDE.md

اگر پروژه شما هم از Codex و هم از Claude Code استفاده می‌کند، می‌توانید هر دو فایل پیکربندی را در کنار هم نگه دارید:

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

**می‌توان استانداردهای اصلی را به اشتراک گذاشت**. بیشتر محتوای هر دو فایل (پشته فناوری، قراردادهای نام‌گذاری، ساختار پوشه‌ها و غیره) یکسان خواهد بود -- تنها دستورالعمل‌های مخصوص هر ابزار متفاوت‌اند.

روش توصیه‌شده:

1. یک مجموعه واحد از استانداردهای اصلی بنویسید
2. آن را در هر دو `AGENTS.md` و `CLAUDE.md` کپی کنید
3. قالب‌بندی را برای قراردادهای هر ابزار دقیق‌تر تنظیم کنید

یا روشی زیباتر -- ارجاع متقابل در بالای هر فایل:

```markdown
# 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)
```

### بهترین شیوه‌های همکاری تیمی

#### کامیت در کنترل نسخه

`AGENTS.md` باید در مخزن Git شما کامیت شود تا اعضای تیم استانداردهای یکسانی برای کدنویسی با هوش مصنوعی داشته باشند:

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

#### گنجاندن AGENTS.md در بازبینی کد

تغییرات `AGENTS.md` باید دقیقاً مانند تغییرات استانداردهای کدنویسی از بازبینی کد عبور کنند:

```markdown
<!-- 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
```

#### به‌تدریج تکرار کنید

لازم نیست همه‌چیز را یک‌جا بنویسید. روش توصیه‌شده:

1. **روز اول**: پشته فناوری پایه و قراردادهای نام‌گذاری را بنویسید (10-20 خط)
2. **هفته اول**: بر اساس رفتار واقعی Codex قاعده اضافه کنید
3. **مستمر**: هر بار که Codex کاری را انجام می‌دهد که نمی‌خواهید، قاعده‌ای به `AGENTS.md` اضافه کنید

### الگوهای دستورالعمل مؤثر

این گونه دستورالعمل‌ها در `AGENTS.md` بهترین نتیجه را می‌دهند:

```markdown
## 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
```

```markdown
## 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)
```

### قواعد شرطی

می‌توانید برای انواع فایل یا پوشه‌های مختلف قواعد متفاوتی تعیین کنید:

```markdown
## 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
```

---
## مهاجرت از CLAUDE.md

اگر از قبل یک `CLAUDE.md` دارید، تبدیل آن به `AGENTS.md` ساده است. هر دو در قالب Markdown هستند و محتوای اصلی مستقیماً منتقل می‌شود.

### مراحل مهاجرت

**گام 1: محتوای پایه را کپی کنید**

```bash
cp CLAUDE.md AGENTS.md
```

**گام 2: ارجاع‌های مخصوص Claude Code را جایگزین کنید**

مفاهیم مخصوص Claude Code را با معادل‌های Codex آن‌ها عوض کنید:

| در CLAUDE.md | در AGENTS.md |
|--------------|--------------|
| «وقتی Claude فایل‌ها را تغییر می‌دهد...» | «هنگام تغییر فایل‌ها...» |
| «برای فشرده‌سازی زمینه از `/compact` استفاده کنید» | (حذف کنید -- Codex این فرمان را ندارد) |
| «با `@` به فایل‌ها ارجاع دهید» | (حذف کنید -- Codex از روش ارجاع متفاوتی استفاده می‌کند) |
| «هوک: PostToolUse...» | «پس از تکمیل وظیفه، اجرا کنید...» |
| «زیرعامل مدیریت می‌کند...» | «از Cloud Exec استفاده کنید...» |

**گام 3: قالب را ساده‌تر کنید**

Codex دستورهای مختصر به سبک فهرست را ترجیح می‌دهد. اگر `CLAUDE.md` شما پاراگراف‌های توضیحی طولانی دارد، آن‌ها را در قالب موارد فهرست‌شده خلاصه کنید:

پیش از مهاجرت (سبک `CLAUDE.md`):

```markdown
## 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.
```

پس از مهاجرت (سبک `AGENTS.md`):

```markdown
## 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)
```

**گام 4: دستورهای مخصوص Codex را اضافه کنید**

```markdown
## 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
```

### جدول مرجع مهاجرت

| مفهوم | سبک CLAUDE.md | سبک AGENTS.md |
|---------|-----------------|-----------------|
| توضیحات پروژه | پاراگراف‌های آزاد | فهرست یا پاراگراف مختصر |
| استانداردهای کد | فهرست‌های Markdown | فهرست‌های Markdown (یکسان) |
| اقدامات ممنوع | «X را انجام ندهید» | «هرگز X را انجام ندهید» یا «X را انجام ندهید» |
| اجرای فرمان‌ها | «لطفاً `npm test` را اجرا کنید» | «`npm test` را اجرا کنید» یا فقط آن را فهرست کنید |
| ساختار فایل | بلوک کد دارای درخت پوشه | بلوک کد دارای درخت پوشه (یکسان) |
| پیکربندی ابزار | ارجاع‌های settings.json | ارجاع‌های config.toml |

### نگهداری هر دو فایل

اگر باید هر دو `AGENTS.md` و `CLAUDE.md` را در بلندمدت نگهداری کنید:

1. **یکی را به‌عنوان «اصلی» تعیین کنید**: معمولاً فایل مربوط به ابزاری است که بیشتر از آن استفاده می‌کنید
2. **پس از ویرایش فایل اصلی همگام‌سازی کنید**: می‌توانید یک اسکریپت ساده برای خودکارسازی این کار بنویسید
3. **قواعد مخصوص هر ابزار را جدا نگه دارید**: استانداردهای مشترک را در نیمه اول و قواعد مخصوص ابزار را در انتها قرار دهید

---
## اشکال‌زدایی و اعتبارسنجی

### تأیید فعال بودن AGENTS.md

ساده‌ترین راه برای تأیید این است که به Codex وظیفه‌ای بدهید که باید یک قاعده را فعال کند:

```bash
# 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
```

### عیب‌یابی قواعدی که اعمال نمی‌شوند

1. **محل فایل**: تأیید کنید که `AGENTS.md` در ریشه پروژه یا زیرپوشه مرتبط قرار دارد
2. **نام فایل**: باید `AGENTS.md` باشد (با حروف بزرگ، نه `agents.md`)
3. **مشکلات قالب‌بندی**: از قالب‌بندی صحیح Markdown مطمئن شوید (خط خالی پیش از فهرست‌ها و غیره)
4. **تعارض قواعد**: دستورهای متناقض را در سطوح مختلف `AGENTS.md` بررسی کنید
5. **بیش از حد مبهم**: جایگزینی با توضیح مشخص‌تر را امتحان کنید

---

## انتخاب بین CLAUDE.md و AGENTS.md

نگهداری هر دو فایل پیکربندی طبیعی به نظر می‌رسد، اما **دو نسخه معمولاً از هم واگرا می‌شوند**: شما قاعده‌ای را به `AGENTS.md` اضافه می‌کنید و فراموش می‌کنید آن را در `CLAUDE.md` هم منعکس کنید، و دو ابزار رفتار ناهماهنگ پیدا می‌کنند. راهنمای زیر به شما کمک می‌کند از این تله دوری کنید.

### با تعداد ابزارهایی که استفاده می‌کنید شروع کنید

- **فقط Claude Code (یک ابزار)**: فقط به یک `CLAUDE.md` نیاز دارید. Claude Code فایل `CLAUDE.md` را به‌صورت بومی می‌خواند و حافظه سراسری به‌همراه قواعد محدود به مسیر (فایل‌های تودرتوی `CLAUDE.md` / `.claude/rules`) را روی آن لایه‌بندی می‌کند. نیازی به نگهداری `AGENTS.md` هم نیست.
- **تیم چندابزاری (Claude Code + Codex / Cursor / Copilot / Cline / Gemini / Aider / Zed و غیره)**: `AGENTS.md` را **یگانه منبع حقیقت** کنید. بیشتر ابزارها جز Claude Code فایل `AGENTS.md` را می‌خوانند، و Claude Code نیز هنگامی که `CLAUDE.md` وجود ندارد آن را می‌خواند.

### توصیه‌شده برای تیم‌های چندابزاری: یک CLAUDE.md نازک که AGENTS.md را وارد می‌کند

دو نسخه کامل که از هم دور می‌افتند را نگه ندارید. استانداردهای مشترک را در `AGENTS.md` نگه دارید، سپس آن‌ها را با یک **`CLAUDE.md` نازک** وارد کنید تا Claude Code هم قواعد مشترک تیم و هم افزودنی‌های مخصوص Claude را دریافت کند:

```markdown
# 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
```

به این ترتیب، استانداردهای مشترک یک منبع واحد (`AGENTS.md`) دارند و `CLAUDE.md` فقط دستورهای مخصوص Claude Code را نگه می‌دارد -- و نسخه‌های تکراری واگرا را از ریشه حذف می‌کند.

Claude Code اکنون می‌تواند `AGENTS.md` را مستقیماً بخواند، بنابراین دیگر به یک `CLAUDE.md` نازک نیازی نیست؛ با این حال، تیم‌های چندابزاری باید همچنان `AGENTS.md` را به‌عنوان منبع واحد نگه دارند و فقط افزودنی‌های مخصوص Claude Code را در `CLAUDE.md` قرار دهند.

### جدول تصمیم‌گیری سریع

| سناریو | چه چیزی نگهداری شود | یادداشت‌ها |
|----------|------------------|-------|
| فقط Claude Code | فقط `CLAUDE.md` | به‌صورت بومی خوانده می‌شود؛ به `AGENTS.md` نیازی نیست |
| فقط Codex / ابزارهای دیگر | فقط `AGENTS.md` | این ابزارها `CLAUDE.md` را نمی‌خوانند |
| تیم چندابزاری | `AGENTS.md` (منبع حقیقت) + `CLAUDE.md` نازک (`@AGENTS.md`) | منبع واحد، بدون واگرایی |

> برای لایه‌بندی، قالب‌ها و کنترل زمینه در `CLAUDE.md`، به [راهنمای پیکربندی CLAUDE.md](/docs/usage/claude-md) مراجعه کنید.

---

## گام‌های بعدی

- [شروع سریع Codex](/docs/getting-started/codex-quick-start) -- نصب و پیکربندی Codex
- [Codex در برابر Claude Code: مقایسه عمیق](/docs/getting-started/codex-vs-claude-code) -- مقایسه کامل هر دو ابزار
- [سیستم Hooks](/docs/advanced/hooks) -- Hooks رویدادی Claude Code (مفهوم مشابه)
- [نکات و ترفندهای CLI](/docs/usage/cli-tips) -- نکات عملی برای کدنویسی پربازده‌تر با هوش مصنوعی