کدکس در هر نشست AGENTS.md را به مدل می‌دهد، ولی اندازه‌ی واقعی این کار را هیچ‌جا اعلام نمی‌کند. روی codex-cli 0.158.0 اندازه گرفتم: هر فایل یک پوسته‌ی ثابت 284 توکنی دارد و هر بایت فایل 0.1806 توکن، یعنی یک توکن به ازای هر 5.5 بایت. فایل 4 KiB یعنی 1006 توکن که 28 درصدش پوسته است. سقف پیش‌فرض هم 32768 بایت است و بی‌صدا و وسط خط بریده می‌شود.
چرا این عدد را کسی اعلام نمی‌کند
فایل AGENTS.md قراردادی است که خود ابزار می‌خواند: مستندات رسمی می‌گویند پیش از هر کاری کدکس آن را می‌خواند، و وب‌سایت قرارداد می‌گوید چند ابزار مستقل از همین نام پیروی می‌کنند. مشکل این است که هیچ‌کدام نمی‌گویند این متن در پرامپت چقدر جا می‌گیرد. برای تیمی که دارد بودجه‌ی زمینه‌ی ایجنت را حساب می‌کند، همان بی‌صدایی یعنی یک عدد که نمی‌توان رویش بودجه بست.
دستور codex debug prompt-input همین شکاف را پر می‌کند. این فرمان درخواستی به شبکه نمی‌فرستد و فقط ورودی قابل‌مشاهده‌ی مدل را به صورت JSON رندر می‌کند. یعنی بدون کلید API می‌توانید دقیقاً ببینید چه چیزی به مدل می‌رسد، و برای سنجش هزینه‌ی توکن کافی است.
$ codex --version
codex-cli 0.158.0
$ codex debug --help
Debugging tools
Commands:
models Render the raw model catalog as JSON
app-server Tooling: helps debug the app server
prompt-input Render the model-visible prompt input list as JSON
خروجی یک آرایه‌ی JSON از پیام‌هاست و هر پیام یک برچسب content_item_kinds دارد. بلوک دستورالعمل پروژه با برچسب agents_md.instructions می‌آید و جدا شدنش از بقیه‌ی پیام‌ها کاری ندارد:
$ codex debug prompt-input "سلام" | python3 -c "
import json, sys
for m in json.load(sys.stdin):
kinds = (m.get('internal_chat_message_metadata_passthrough') or {}).get('content_item_kinds') or []
text = ''.join(c.get('text','') for c in m.get('content',[]))
print(f\"{m['role']:<9} {len(text):>5} ch {','.join(kinds)}\")
"
developer 7485 ch host_skills.instructions,permissions.instructions,collaboration_mode.instructions
developer 2429 ch multi_agent.role_instructions
developer 271 ch multi_agent.mode_instructions
user 1041 ch agents_md.instructions,environments.environment_context
user 4 ch user.text
اگر در پوشه‌ی جاری هیچ AGENTS.md نباشد، بلوکی با برچسب agents_md.instructions در خروجی نیست. همین نبودن، یک آزمون منفی است که به شما می‌گوید ابزار خراب نیست و واقعا فایل پیدا نشده است.
اندازه‌گیری هزینه‌ی واقعی هر فایل
شش فایل با اندازه‌های مختلف ساختم و برای هرکدام بلوک تحویل‌شده را اندازه گرفتم. ستون delivered فقط بایت‌های خود فایل است و پوسته‌ی ثابت را ندارد، پس نسبت آخر ستون قیمت واقعی هر بایت را نشان می‌دهد.
| اندازه‌ی فایل | بایت تحویل‌شده | توکن کل بلوک | توکن به ازای هر بایت |
|---|---|---|---|
| 144 | 144 | 310 | 2.153 |
| 510 | 510 | 374 | 0.733 |
| 998 | 998 | 464 | 0.465 |
| 1974 | 1974 | 640 | 0.324 |
| 2950 | 2950 | 816 | 0.277 |
| 3926 | 3926 | 993 | 0.253 |
نسبت آخر ستون با بزرگ شدن فایل کم می‌شود و این دقیقا همان چیزی است که از یک پوسته‌ی ثابت انتظار می‌رود. با برازش کمترین مربعات روی چهار سطر آخر، رابطه این است: توکن = ۲۸۳٫۵ + ۰٫۱۸۰۶ × بایت با ضریب تعیین 1.00000 که یعنی خطای پیش‌بینی در هر شش سطر زیر یک درصد می‌ماند.
دو عدد از این برازش قابل استفاده است و باقی‌اش نه. هزینه‌ی ثابت 284 توکنی است که سرصفحه و تگ‌ها می‌گیرند و با بزرگ شدن فایل کم نمی‌شود. نرخ حاشیه‌ای 0.1806 توکن بر بایت هم یعنی یک توکن به ازای هر 5.5 بایت. از این دو، اندازه‌ی فایل را می‌توانید قبل از نوشتن حساب کنید:
| اندازه‌ی فایل | هزینه‌ی تخمینی | سهم پوسته از کل |
|---|---|---|
| 500 B | 374 | 76٪ |
| 1 KiB | 464 | 61٪ |
| 2 KiB | 645 | 44٪ |
| 4 KiB | 1006 | 28٪ |
| 8 KiB | 1729 | 16٪ |
سطر اول جدول دوم از سطر دوم جدول اول آمده است، پس دو جدول با هم سازگارند. اما یک هشدار روش: ضریب 0.1806 را با متن فارسی اندازه گرفتم و متن لاتین ارزان‌تر تمام می‌شود، چون هر کلمه‌ی لاتین در یک توکن جا می‌شود. همان فایل با ۲۹۲۸ بایت متن فارسی تکراری 528 توکن شد و با ۱۸۲۶ بایت متن فارسی یکتا 324 توکن؛ نسبت‌ها نزدیک‌اند، پس برای تصمیم‌گیری در مقیاس کیلوبایت کافی است.
فایلی که کدکس می‌خواند فقط همان پوشه است
اینجا یک شکاف میان مستندات و رفتار نسخه‌ی 0.158.0 هست و برای مخزن چندلایه مهم است. مستندات رسمی می‌گویند کدکس از ریشه‌ی پروژه پایین می‌آید و فایل هر پوشه را با فایل پوشه‌های بالاتر به هم می‌چسباند [1][5]. اندازه‌گیری من خلاف آن را نشان داد: فقط فایل همان پوشه‌ی جاری تحویل داده می‌شود و فایل پوشه‌های بالاتر نمی‌آید.
$ cd probe && git init -q .
$ printf 'ROOT_RULES\n' > AGENTS.md
$ mkdir -p mid/leaf && printf 'MID_RULES\n' > mid/AGENTS.md
$ printf 'LEAF_RULES\n' > mid/leaf/AGENTS.md
$ for d in . mid mid/leaf; do
> printf '%-10s -> ' "$d"
> codex debug prompt-input "سلام" | grep -oE 'ROOT_RULES|MID_RULES|LEAF_RULES' | sort -u | paste -sd,
> done
. -> ROOT_RULES
mid -> MID_RULES
mid/leaf -> LEAF_RULES
این را در چهار ترکیب جداگانه هم تکرار کردم: با ریشه‌ی گیت و بدون آن، در دو مسیر متفاوت. نتیجه در هر هشت اجرا یکی بود و هیچ‌بار فایل پوشه‌ی بالاتر دیده نشد. در پوشه‌ای دو سطح پایین‌تر از فایل، بلوک پروژه اصلا وجود نداشت و تنها دستورالعمل سراسری می‌آمد.
یک استثنای رفتاری هم هست که ارزش دانستن دارد: اگر AGENTS.md در پوشه‌ی جاری خالی باشد، کدکس فایل خالی را رد می‌کند و هیچ چیز جایگزین نمی‌کند. فایل پدر با محتوا داشتم و باز هم بلوکی نرسید. برای تیمی که فایل خالی را به‌عنوان «فعلا چیزی» می‌گذارد، یعنی آن پوشه بدون هیچ دستورالعملی اجرا می‌شود.
سقف 32768 بایت بی‌صدا بریده می‌شود
کلید project_doc_max_bytes در مرجع پیکربندی سقف خواندن دستورالعمل پروژه است و مقدار پیش‌فرض آن 32768 بایت اعلام شده است. من این را با یک فایل 183000 بایتی اندازه گرفتم و عدد تحویل‌شده 32770 بایت بود. اختلاف دو بایت از یک خط خالی در انتهای فایل است، نه خطای اندازه‌گیری.
$ wc -c < AGENTS.md
183000
$ codex debug prompt-input "سلام" | python3 -c "
import json, re, sys
for m in json.load(sys.stdin):
k = (m.get('internal_chat_message_metadata_passthrough') or {}).get('content_item_kinds') or []
if 'agents_md.instructions' in k:
t = ''.join(c.get('text','') for c in m.get('content',[]))
b = re.findall(r'<INSTRUCTIONS>\n(.*?)\n</INSTRUCTIONS>', t, re.S)
print(sum(len(x.encode()) for x in b), 'bytes delivered')
"
32770 bytes delivered
نکته‌ی عملی این است که هیچ هشداری روی خروجی خطا نمی‌آید و بریدن وسط خط اتفاق می‌افتد. یعنی فایلی که از 32 KiB بگذرد، از همان نقطه به بعد برای مدل وجود ندارد و شما از این اتفاق خبردار نمی‌شوید. اگر سقف را بالا می‌برید، بدانید که project_doc_max_bytes فقط روی فایل پروژه اثر می‌گذارد: یک فایل سراسری 79202 بایتی در کنار فایل پروژه‌ی 8802 بایتی، هر دو کامل تحویل شدند.
برای بالا بردن سقف کافی است همین کلید را در ~/.codex/config.toml بگذارید، یا برای یک اجرا با -c موقت بدهید. این کار را پیش از نوشتن فایل بزرگ انجام دهید، چون بعدا فقط متوجه می‌شوید بخشی از قوانین تیم شما اصلا اجرا نشده است.
$ codex -c project_doc_max_bytes=65536 debug prompt-input "سلام" | python3 -c "
import json, re, sys
for m in json.load(sys.stdin):
k = (m.get('internal_chat_message_metadata_passthrough') or {}).get('content_item_kinds') or []
if 'agents_md.instructions' in k:
t = ''.join(c.get('text','') for c in m.get('content',[]))
b = re.findall(r'<INSTRUCTIONS>\n(.*?)\n</INSTRUCTIONS>', t, re.S)
print(sum(len(x.encode()) for x in b), 'bytes delivered')
"
65538 bytes delivered
کلید project_doc_fallback_filenames هم در همان مرجع تعریف شده و وقتی به فایل نام دیگری داشتید به کار می‌آید. بدون تنظیمش هیچ بلوکی برای TEAM_GUIDE.md نیامد و با تنظیمش همان فایل تحویل شد.
جمع‌بندی: فایل را کجا بگذارید
قاعده‌ی کاربردی این نوشته از اندازه‌گیری بیرون می‌آید و در یک جمله جمع می‌شود: AGENTS.md را در همان پوشه‌ای بگذارید که دستور فرمان را از آن اجرا می‌کنید، زیر 4 KiB نگه دارید، و قبل از هر نشست یک بار با codex debug prompt-input ببینید واقعا چه چیزی رسیده است.
سه عدد این تصمیم را می‌سازند. پوسته‌ی ثابت 284 توکن است که حتی یک فایل سه‌خطی هم آن را می‌پردازد. نرخ حاشیه‌ای 0.1806 توکن بر بایت است که برای متن فارسی اندازه‌گیری شده. سقف پیش‌فرض 32768 بایت است که بی‌صدا و بدون هشدار بریده می‌شود. اگر AGENTS.md شما بزرگ‌تر از این حد است، آن بخش آخر اصلا به مدل نمی‌رسد.
مهم‌تر از هر سه عدد، آن دو اختلاف با مستندات است: فایل پوشه‌های بالاتر در این نسخه خوانده نمی‌شود، و اگر سازمان شما یک ریشه‌ی مشترک دارد، آن فایل برای زیرشاخه‌ها بی‌اثر است. اگر این رفتار در نسخه‌ی شما فرق می‌کند، با همان فرمان رندر تفاوت را ببینید. برای فهم اینکه چرا شمارش توکن با تعداد نوبت یکی نیست، توکن و پنجره‌ی زمینه را نوشته‌ام؛ و برای وقتی که می‌خواهید بدانید یک پرچم در کدکس واقعا روشن است یا نه، خواندن وضعیت پرچم‌ها مسیر درست است.
منابع
- مستندات کدکس درباره‌ی AGENTS.md: ترتیب کشف، چسباندن فایل‌ها و سقف project_doc_max_bytes — خوانده در ۱۰ مهر ۱۴۰۵
- مرجع پیکربندی کدکس: project_doc_max_bytes، project_doc_fallback_filenames و project_root_markers — خوانده در ۱۰ مهر ۱۴۰۵
- یادداشت انتشار کدکس، شهریور ۱۴۰۵ — خوانده در ۱۰ مهر ۱۴۰۵
- مرجع خط فرمان کدکس: زیر‌فرمان‌های debug و features — خوانده در ۱۰ مهر ۱۴۰۵
- نسخه‌ی دوم همان صفحه‌ی مستندات AGENTS.md — خوانده در ۱۰ مهر ۱۴۰۵
- مخزن openai/codex
- انتشار Codex CLI 0.153.0 در گیت‌هاب — خوانده در ۱۰ مهر ۱۴۰۵
- مستندات پیکربندی در مخزن کدکس
- مخزن پیش‌نویس مشخصات AGENTS.md
- وب‌سایت قرارداد AGENTS.md
- مخزن tiktoken برای شمارش توکن با گذرگاه o200k_base
دیدگاه‌ها
۰ موردهنوز دیدگاهی ثبت نشده. اولین نفر باشید.