项目说明书 AGENTS.md：把规矩焊进 Codex 的开工流程

📚 सीरीज नेविगेशन: पिछला लेख 10 · क्लाउड Codex Cloud काम को क्लाउड पर रन करने और PR प्राप्त करने की पूरी प्रक्रिया को समझाता है। यह लेख स्थानीय वातावरण के एक बहुत महत्वपूर्ण दस्तावेज—AGENTS.md—के बारे में है। यह प्रोजेक्ट की वह निर्देशिका है जिसे Codex काम शुरू करने से पहले हर बार पढ़ता है, लेकिन अधिकांश उपयोगकर्ता इसे ठीक से नहीं लिख पाते।

Codex का उपयोग शुरू करते समय मुझसे हुई एक बेवकूफी की कहानी देखें।

पिछले साल मैंने एक Node प्रोजेक्ट पर काम करने के लिए Codex को रूट डायरेक्टरी में AGENTS.md फ़ाइल बनाकर निर्देश दिया: "इस प्रोजेक्ट में pnpm का उपयोग करें, npm का नहीं"। लेकिन उसने सीधे npm install चला दिया। मुझे लगा कि उसने फ़ाइल नहीं पढ़ी, इसलिए मैंने उस नियम को तीन बार कॉपी किया, उसे बोल्ड किया और विस्मयादिबोधक चिह्न (!) भी लगाया। लेकिन फिर भी उसने वही किया।

काफी समय बाद मुझे समझ आया—उसने फ़ाइल पढ़ी थी, लेकिन वह नियम 140वीं लाइन पर लिखा हुआ था। उससे पहले मैंने कंपनी का परिचय, प्रोजेक्ट का रोडमैप और तकनीकी चयन के इतिहास के बारे में लगभग सौ से अधिक लाइनें लिखी हुई थीं। Codex जब तक 'npm का उपयोग न करें' लाइन तक पहुँचा, उसका ध्यान फालतू विवरणों में भटक चुका था। समस्या उसके बात न मानने की नहीं थी, बल्कि यह थी कि मैंने मुख्य नियम को फालतू जानकारी के बीच छिपा दिया था।

Codex के लिए AGENTS.md का वही महत्व है जो Claude Code के लिए CLAUDE.md का है—यह एक ही अवधारणा का दूसरा नाम है। लेकिन Codex में इसके लोड होने के नियम, ओवरराइड करने की व्यवस्था और साइज लिमिट अलग हैं, जहाँ एरर आ सकती है। इस लेख में हम इन सभी बातों को समझेंगे।

इस लेख को पढ़ने के बाद, आपको मिलेगा:

• Codex द्वारा AGENTS.md फ़ाइल को खोजने का तरीका (ग्लोबल स्तर → प्रोजेक्ट स्तर → फ़ाइलों का संयोजन)
• AGENTS.override.md फ़ाइल का परिचय (जो Claude Code में नहीं है)
• एक तुलनात्मक सूची "क्या लिखना है बनाम क्या नहीं लिखना है"
• फ़ाइल का नाम बदलना (project_doc_fallback_filenames) और साइज लिमिट बढ़ाना (project_doc_max_bytes)
• यह सत्यापित करने का अभ्यास कि क्या Codex वास्तव में निर्देशिका पढ़ रहा है

ध्यान दें: यह लेख केवल AGENTS.md फ़ाइल को लिखने और लोड होने की प्रक्रिया पर केंद्रित है। 'मेमोरी (Memories)' की व्यवस्था इससे अलग होती है। याद रखें: प्रोजेक्ट के स्थायी नियम हमेशा AGENTS.md में लिखें, मेमोरी पर निर्भर न रहें।

---

01 AGENTS.md क्या है: Codex के काम के लिए नियम निर्देशिका

निष्कर्ष देखें: AGENTS.md Codex को दिया जाने वाला एक स्थायी निर्देश है, जिसे वह काम शुरू करने से पहले हर बार पढ़ता है ताकि प्रोजेक्ट के नियमों को संदर्भ में सहेज सके।

इसकी आवश्यकता क्यों है? क्योंकि Codex का हर नया सत्र (TUI में प्रत्येक नया सत्र) बिल्कुल शुरू से शुरू होता है। पिछले सत्र में दी गई जानकारी (जैसे 'pnpm का उपयोग करें, legacy/ फ़ोल्डर को न छुएं') उसे याद नहीं रहती। यदि AGENTS.md नहीं होगी, तो आपको हर बार निर्देश दोबारा देने होंगे।

सादृश्य: शिफ्ट बदलने के बाद काम सौंपना। जब फैक्ट्री में काम की शिफ्ट बदलती है, तो जाने वाला कर्मचारी बोर्ड पर लिख जाता है कि कौन सी मशीन खराब है, किस सामान की जांच करनी है और किससे संपर्क करना है। आने वाला कर्मचारी उसे पढ़कर काम जारी रखता है। AGENTS.md वही बोर्ड है।

इसके नियम कब बदलने चाहिए:

• जब Codex एक ही गलती दोबारा करे—ताकि उसे स्थायी रूप से सुधारा जा सके।
• जब आपको हर सत्र में एक ही निर्देश बार-बार टाइप करना पड़े।
• जब कोड रिव्यू में लगे कि Codex को प्रोजेक्ट के बुनियादी नियमों की जानकारी होनी चाहिए।
• जब टीम के किसी नए सदस्य को प्रोजेक्ट की सेटिंग्स समझाने की आवश्यकता हो।

मेरा अनुभव: मैं इसका उपयोग फीडबैक लूप की तरह करता हूँ। जब भी Codex कोई गलत धारणा बनाता है, मैं उसे चैट में सुधारने के साथ-साथ AGENTS.md में भी लिख देता हूँ। एक प्रोजेक्ट पर काम करते हुए मेरी AGENTS.md बीस लाइनों की हो गई, जिसमें उसके द्वारा की गई सभी गलतियों के सुधार लिखे थे, और अब वह दोबारा वैसी गलतियाँ नहीं करता।

💡 संक्षेप में: AGENTS.md Codex के लिए हर सत्र की निर्देशिका है, गलती होने पर तुरंत नियम जोड़ें ताकि वह दोबारा गलती न करे।

---

02 Codex द्वारा निर्देशों को खोजने की प्रक्रिया

AGENTS.md को कई जगहों पर रखा जा सकता है। Codex शुरू होते समय इन सभी फाइलों को एक निश्चित क्रम में पढ़कर कंबाइन (combine) कर लेता है। यह Claude Code से अलग व्यवस्था है, इसे ध्यान से समझें।

दस्तावेज़ों के अनुसार यह प्रक्रिया तीन स्तरों पर काम करती है:

1. ग्लोबल स्तर (Global scope): आपके Codex डिफ़ॉल्ट डायरेक्टरी (~/.codex) में Codex पहले AGENTS.override.md फ़ाइल की जांच करता है, और यदि वह न हो तो AGENTS.md फ़ाइल को पढ़ता है। इस स्तर पर वह केवल एक ही फ़ाइल लेता है, दोनों को नहीं पढ़ता।

2. प्रोजेक्ट स्तर (Project scope): प्रोजेक्ट की रूट डायरेक्टरी से शुरू होकर आप जिस सब-डायरेक्टरी में काम कर रहे हैं, वहाँ तक प्रत्येक फ़ोल्डर में Codex इस क्रम में फ़ाइल खोजता है: पहले AGENTS.override.md, फिर AGENTS.md, और फिर आपके द्वारा कॉन्फ़िगर की गई कोई बैकअप फ़ाइल (project_doc_fallback_filenames)। प्रत्येक फ़ोल्डर से वह केवल एक ही फ़ाइल लेता है।

3. संयोजन (Merge): अंत में Codex इन सभी फाइलों को ऊपर से नीचे के क्रम में जोड़ लेता है (एक खाली लाइन के अंतर के साथ)। आप जिस डायरेक्टरी में काम कर रहे हैं, उसके सबसे पास वाली फ़ाइल का निर्देश अंतिम संयोजन में सबसे नीचे आता है, इसलिए वह ऊपर वाले निर्देशों को ओवरराइड कर सकता है।

प्रक्रिया का आरेख:

यह आरेख दिखाता है कि पहले ग्लोबल स्तर से और फिर प्रोजेक्ट स्तर के प्रत्येक फ़ोल्डर से एक-एक फ़ाइल लेकर कंबाइन किया जाता है—जो फ़ाइल काम की जगह के जितनी पास होगी, उसका नियम उतना ही महत्वपूर्ण होगा।

दो मुख्य बातें:

• निर्देश कंबाइन होते हैं, डिलीट नहीं: ग्लोबल और प्रोजेक्ट स्तर की फाइलें एक साथ काम करती हैं। ऐसा नहीं है कि प्रोजेक्ट फ़ाइल होने पर ग्लोबल फ़ाइल बेकार हो जाएगी। दोनों के नियम साथ काम करेंगे, बस विरोधी नियमों के होने पर पास वाली फ़ाइल का नियम लागू होगा।
• पास वाला नियम जीतता है: यदि ग्लोबल फ़ाइल कहती है 'सिंगल कोट का उपयोग करें' और प्रोजेक्ट फ़ाइल कहती है 'डबल कोट का उपयोग करें', तो प्रोजेक्ट फ़ाइल का नियम लागू होगा क्योंकि वह प्रोजेक्ट के अधिक पास है।

सादृश्य: नक्शे के तीन स्तर। देश का नक्शा (ग्लोबल स्तर), शहर का नक्शा (प्रोजेक्ट रूट), और कॉलोनी का नक्शा (सब-डायरेक्टरी)। तीनों नक्शे सही हैं, लेकिन कॉलोनी में कोडिंग करते समय कॉलोनी का नक्शा ही अंतिम निर्णय होगा।

निर्देशों का आरेख:

यह दिखाता है कि कैसे ग्लोबल स्तर (~/.codex), रिपॉजिटरी रूट और सब-डायरेक्टरी के नियम मिलकर काम करते हैं; और दाहिनी ओर की प्राथमिकता रेखा दर्शाती है कि काम की जगह के पास वाला नियम सबसे ऊपर (सबसे महत्वपूर्ण) रहता है।

💡 संक्षेप में: Codex ग्लोबल स्तर (एक फ़ाइल) → प्रोजेक्ट स्तर के प्रत्येक फोल्डर (एक फ़ाइल) से नियमों को लेकर कंबाइन करता है, और पास वाला नियम अधिक प्रभावी होता है।

---

03 AGENTS.override.md: अस्थाई नियमों के लिए विशेष फ़ाइल

ऊपर हमने AGENTS.override.md फ़ाइल का नाम देखा था। यह Codex की एक विशेष व्यवस्था है।

यह फ़ाइल तब उपयोगी होती है जब आप ग्लोबल AGENTS.md के नियमों को डिलीट किए बिना किसी प्रोजेक्ट के लिए अस्थाई रूप से नए नियम सेट करना चाहते हैं।

सादृश्य: नियमों पर एक नोट चिपकाना। मूल नियम सुरक्षित रहते हैं, लेकिन अस्थाई काम के लिए एक नोट लिख दिया जाता है कि "इस सप्ताह इस नियम का पालन करें"। काम पूरा होने पर नोट हटा दिया जाता है और पुराने नियम पुनः लागू हो जाते हैं। AGENTS.override.md वही नोट है—यदि यह मौजूद है, तो उसी डायरेक्टरी की AGENTS.md फ़ाइल को छोड़ दिया जाता है; और इसे डिलीट करने पर AGENTS.md पुनः काम करने लगती है।

दो मुख्य उपयोग के परिदृश्य:

• ग्लोबल ओवरराइड: ~/.codex/AGENTS.override.md बनाकर अस्थाई नियम सेट करना, ताकि मूल ग्लोबल फ़ाइल अप्रभावित रहे।
• सब-डायरेक्टरी के विशेष नियम: किसी सब-डायरेक्टरी के लिए अलग नियम सेट करना। जैसे पेमेंट फोल्डर services/payments/ में AGENTS.override.md बनाना:

# services/payments/AGENTS.override.md

## 支付服务规则

- 用 `make test-payments` 替代 `npm test`
- 轮换 API Key 前必须先通知安全频道

(चीनी निर्देशों का अर्थ: "npm test के स्थान पर make test-payments चलाएं", और "API Key बदलने से पहले टीम को सूचित करें")

यहाँ एक बात समझें—यह फ़ाइल केवल उसी फोल्डर के नियमों को ओवरराइड करती है, पूरे प्रोजेक्ट के संयोजन को नहीं रोकती:

क्षेत्र	override फ़ाइल का प्रभाव
उसी फोल्डर के भीतर	इसके होने पर同級 AGENTS.md को छोड़ दिया जाता है
पूरे प्रोजेक्ट की चैन में	यह अन्य फोल्डर्स के नियमों को ब्लॉक नहीं करती, वे संयोजन में शामिल रहते हैं

संक्षेप में: यह केवल अपने फोल्डर के नियमों के लिए विकल्प है, पूरे प्रोजेक्ट के लिए नहीं। संयोजन की बाकी प्रक्रिया वैसी ही चलती है।

यदि Codex कोई ऐसा निर्देश रन करता है जो आपने नहीं लिखा है, तो जांचें कि क्या किसी फोल्डर में कोई AGENTS.override.md फ़ाइल छिपी हुई है।

💡 संक्षेप में: AGENTS.override.md अस्थाई नियम सेट करने के लिए है—इसके होने पर उसी फोल्डर की AGENTS.md छोड़ दी जाती है, लेकिन यह बाकी कंबाइन क्रेडेंशियल्स को प्रभावित नहीं करती।

---

04 क्या लिखना है और क्या नहीं

यह सबसे महत्वपूर्ण भाग है। AGENTS.md सही न लिखने पर Codex उसे अनदेखा कर सकता है।

क्या लिखना चाहिए—केवल वे नियम जो प्रत्येक कोडिंग चक्र में लागू होने आवश्यक हैं:

नियम का प्रकार	क्या लिखें	उदाहरण
प्रोजेक्ट का परिचय	एक लाइन में प्रोजेक्ट की जानकारी	"FastAPI पर आधारित ऑर्डर मैनेजमेंट सिस्टम"
तकनीकी चयन	भाषा, फ्रेमवर्क, डेटाबेस, मुख्य लाइब्रेरीज़	"Python 3.11 / PostgreSQL / pytest"
टेस्ट और लिनट कमांड्स	टेस्ट और कोड चेकर चलाने की कमांड्स	npm run lint, make test-payments
कोडिंग रूल्स	कोडिंग का स्टाइल और नियम	"सभी फंक्शन्स में टाइप एनोटेशन होना चाहिए", "डबल कोट का उपयोग करें"
क्या नहीं करना है	वह काम जो Codex को बिल्कुल नहीं करना चाहिए	"migrations फ़ोल्डर की पुरानी फाइलों को न बदलें", "नया पैकेज जोड़ने से पहले पुष्टि करें"

टेस्ट और चेकर की कमांड्स बहुत महत्वपूर्ण हैं—Codex कमिट करने या PR बनाने से पहले इन कमांड्स को चलाकर कोड की जांच करता है। क्या नहीं करना है की सूची सुरक्षा के लिए आवश्यक है।

क्या नहीं लिखना चाहिए:

• ❌ लंबा इतिहास: कंपनी का परिचय, प्रोजेक्ट का पुराना इतिहास—यह संदर्भ सीमा को भरता है और कोडिंग के लिए बेकार है।
• ❌ पुराने नियम: जो नियम अब लागू नहीं होते उन्हें डिलीट करें ताकि Codex भ्रमित न हो।
• ❌ वह जानकारी जो कोड से स्पष्ट है: फोल्डर का स्ट्रक्चर या फाइलों की लिस्ट न लिखें। Codex कोड पढ़कर इन्हें खुद समझ सकता है।

दस्तावेज़ों में साइज की एक सीमा दी गई है:

Codex कंबाइन करने पर खाली फाइलों को छोड़ देता है, और यदि कंबाइन फ़ाइल का कुल साइज project_doc_max_bytes (डिफ़ॉल्ट 32 KiB) से अधिक हो जाता है, तो वह आगे की फाइलों को लोड करना बंद कर देता है।

यह सीमा सभी फाइलों (ग्लोबल + प्रोजेक्ट) के संयोजन पर लागू होती है। इसलिए नियमों को छोटा और सटीक रखें।

एक नियम याद रखें: "क्या Codex कोड देखकर इस बात को खुद समझ सकता है? यदि हाँ, तो उसे निर्देशिका में न लिखें।" इससे निर्देशिका छोटी और प्रभावी रहेगी।

💡 संक्षेप में: निर्देशिका में केवल आवश्यक नियम (प्रोजेक्ट परिचय, कमांड्स, तकनीकी विवरण और कोडिंग सुरक्षा) लिखें, और अनावश्यक पृष्ठभूमि विवरण हटा दें; कंबाइन लिमिट डिफ़ॉल्ट रूप से 32 KiB (project_doc_max_bytes) है।

---

05 कॉन्फ़िगरेशन सेटिंग्स बदलना

यदि आप डिफ़ॉल्ट नामों या सीमाओं को बदलना चाहते हैं, तो आप ~/.codex/config.toml (यूज़र कॉन्फ़िगरेशन फ़ाइल) में बदलाव कर सकते हैं।

1. कस्टमाइज्ड फ़ाइल नाम का उपयोग

यदि आपके पास पहले से ही प्रोजेक्ट के नियमों की फ़ाइल है (जैसे TEAM_GUIDE.md) और आप उसे ही Codex के नियमों के लिए उपयोग करना चाहते हैं, तो project_doc_fallback_filenames का उपयोग करें:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

(कोड ब्लॉक को मूल रूप में रहने दें)

अब Codex फ़ाइलों की खोज इस क्रम में करेगा: AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md (जो भी फ़ाइल पहले मिले)।

2. साइज लिमिट बढ़ाना

यदि नियमों की फ़ाइल बड़ी है और वह 32 KiB की सीमा से बाहर जा रही है, तो project_doc_max_bytes से सीमा बढ़ा सकते हैं:

# ~/.codex/config.toml
project_doc_max_bytes = 65536

(कोड ब्लॉक को मूल रूप में रहने दें)

यह सीमा को 64 KiB कर देगा। लेकिन सीमा बढ़ाने से बेहतर है कि आप नियमों को छोटा करें या सब-डायरेक्टरीज़ में विभाजित करें ताकि token उपयोग कम हो।

आवश्यकता	क्या बदलें
पहले से बनी फ़ाइल (जैसे TEAM_GUIDE.md) को नियम फ़ाइल बनाना	project_doc_fallback_filenames में नाम जोड़ें
संयोजन फ़ाइल का साइज 32 KiB से अधिक होना	project_doc_max_bytes का मान बढ़ाएं
अलग सुरक्षा नियम सेट करना	एनवायरनमेंट वेरिएबल CODEX_HOME बदलें

⚠️ सेटिंग्स बदलने के बाद Codex को रीस्टार्ट करना आवश्यक है, अन्यथा नए नियम लागू नहीं होंगे।

💡 संक्षेप में: project_doc_fallback_filenames से कस्टम नाम और project_doc_max_bytes से साइज सीमा बदली जा सकती है; और बदलाव के बाद रीस्टार्ट आवश्यक है।

---

06 व्यावहारिक अभ्यास: नियम फ़ाइल बनाना और सत्यापन

अब हम एक छोटा अभ्यास करेंगे ताकि देख सकें कि नियम कैसे काम करते हैं।

अभ्यास के लिए विंडोज़ में PowerShell या Mac में टर्मिनल का उपयोग करें।

पहला कदम: प्रोजेक्ट फोल्डर बनाना और Git शुरू करना

mkdir agents-md-demo
cd agents-md-demo
git init

अपेक्षित परिणाम: फोल्डर में .git डायरेक्टरी बनेगी। Git चालू होने से Codex इसे प्रोजेक्ट रूट मान लेगा।

दूसरा कदम: नियम फ़ाइल बनाना

फोल्डर में AGENTS.md फ़ाइल बनाएं और यह कोड लिखें:

# agents-md-demo — 一个演示用的最小项目

只有用来演示 AGENTS.md 怎么写，没有真实业务逻辑。

## 常用命令

- `npm test` —— 运行测试

## 编程约定

- 所有函数必须有类型注解
- 字符串一律用双引号

## 注意事项

- 不要新增任何生产依赖，需要时先问我

(कोड ब्लॉक के चीनी कमेंट्स को ही रहने दें)

अपेक्षित परिणाम: फोल्डर में नियम फ़ाइल तैयार हो जाएगी।

तीसरा कदम: Codex से नियमों की समीक्षा करवाना

कमांड चलाएं:

codex --ask-for-approval never "Summarize the current instructions."

(चीनी निर्देश का अर्थ: "वर्तमान नियमों का सारांश बताएं")

अपेक्षित परिणाम: Codex काम शुरू करने से पहले आपके लिखे नियमों (टाइप एनोटेशन, डबल कोट, dependency नियम) का सारांश स्क्रीन पर दिखाएगा। इससे पुष्टि होती है कि उसने नियम पढ़ लिए हैं।

चौथा कदम: सब-डायरेक्टरी में ओवरराइड की जांच

अब एक सब-डायरेक्टरी बनाकर अलग नियम सेट करें:

mkdir -p services/payments

services/payments/AGENTS.override.md फ़ाइल बनाएं और लिखें:

# services/payments/AGENTS.override.md

## 支付服务规则

- 用 `make test-payments` 替代 `npm test`

अब इस डायरेक्टरी से Codex चलाकर नियमों की जांच करें:

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

(चीनी निर्देश का अर्थ: "लोड की गई निर्देश फाइलों की सूची बताएं")

अपेक्षित परिणाम: Codex दिखाएगा कि उसने भुगतान फोल्डर की override फ़ाइल लोड की है, और वहां टेस्ट कमांड make test-payments लागू होगी, जिसने रूट की कमांड npm test को बदल दिया है।

यदि Codex नियमों का पालन नहीं कर रहा है, तो codex status से प्रोजेक्ट पाथ की जांच करें और देखें कि कोई override फ़ाइल नियमों को ब्लॉक तो नहीं कर रही।

---

07 सारांश

इस लेख में हमने AGENTS.md नियम फ़ाइल के बारे में सीखा:

• परिभाषा: यह कोडिंग नियमों की स्थायी निर्देशिका है जिसे Codex प्रत्येक सत्र में लोड करता है।
• खोज क्रम: ग्लोबल (~/.codex) → प्रोजेक्ट रूट → सब-डायरेक्टरीज़ (सभी फाइलों का संयोजन)।
• प्राथमिकता: संयोजन में सब-डायरेक्टरी की फ़ाइल (काम की जगह के पास वाली) सबसे महत्वपूर्ण होती है।
• override: अस्थाई नियमों के लिए AGENTS.override.md का उपयोग किया जाता है।
• सामग्री: केवल आवश्यक नियम (तकनीकी जानकारी, कमांड्स, कोडिंग रूल्स) लिखें, फालतू विवरण हटाएं।
• सीमा: कंबाइन सीमा 32 KiB है, जिसे project_doc_max_bytes से बढ़ाया जा सकता है।

उचित नियम फ़ाइल कोडिंग को सुरक्षित और नियंत्रित रखती है।

अगले लेख 12斜杠 (slash) कमांड्स और शॉर्टकट्स में हम TUI के भीतर काम को तेज़ बनाने वाले शॉर्टकट्स और कमांड्स को विस्तार से समझेंगे।

---

अनुशंसित पठन

• कोडिंग सर्वोत्तम अभ्यास गाइड
• प्रॉम्प्ट के आकार को छोटा रखना और स्पीड बढ़ाना
• कमांड लाइन CLI का उपयोग