Codex के नियम: वैश्विक निर्देश, AGENTS.md और Mac ऐप

मैंने Codex का गंभीरता से इस्तेमाल अभी करीब एक महीने पहले ही शुरू किया है, खासकर तब से जब GPT-5.4 ने इसे मेरे लिए सच में उपयोगी बना दिया। इसलिए यह कोई "पांच साल की कड़ी परीक्षा से निकली समझ" वाला लेख नहीं है। मेरी बात इससे कहीं सीधी है: Codex मेरे लिए उसी दिन बेहतर हुआ, जब मैंने उसे एक और चमकदार प्रॉम्प्ट बॉक्स की तरह लेना बंद किया और शुरू से ही उसे स्थिर निर्देश देने लगा।

OpenAI के पास Codex CLI भी है और Mac ऐप भी। मेरे लिए दोनों का मूल विचार एक ही है: स्थायी निर्देश, AGENTS.md, रिपॉज़िटरी के नियम, और ऐसा एजेंट जो मेरे काम करने के तरीके को पहले से समझकर चले। मैं Mac ऐप को इसलिए पसंद करता हूं, क्योंकि उसमें काम करना एक और टर्मिनल विंडो में फंसे रहने से कहीं ज़्यादा सहज लगता है।

Codex CLI यह काम पहले से अच्छी तरह कर लेता है। Mac ऐप उसी मूल कार्यप्रवाह को बस अधिक साफ, सुंदर और आरामदेह रूप देता है। मैं हर नए काम में बार-बार यह नहीं समझाना चाहता कि मुझे कड़ा प्रकार-निर्धारण चाहिए, बदलाव छोटे और सीधे हों, त्रुटियां साफ दिखाई दें, बेवजह की बचाव-व्यवस्थाएं न हों, और बिखरी हुई व्याख्याओं की जगह कोड के भीतर docstrings लिखी जाएं। मैं चाहता हूं कि यह आधार शुरू से मौजूद रहे।

व्यवहार में यह सब Settings -> Personalization -> Custom instructions में रहता है।

असल में ऐप के ये निर्देश आपकी निजी AGENTS.md फ़ाइल से जुड़े होते हैं। यह मेरे लिए अच्छी बात है। इससे एक ओर बेहतर ऐप अनुभव मिलता है, और दूसरी ओर CLI जैसी फ़ाइल-आधारित स्पष्टता भी बनी रहती है।

Codex के Custom Instructions वास्तव में कहाँ रहते हैं

अगर इस लेख से आपको सिर्फ एक स्क्रीन याद रखनी हो, तो वही यह स्क्रीन होनी चाहिए।

ऐप में वैश्विक निर्देश Settings -> Personalization -> Custom instructions के अंदर रहते हैं। मैं सबसे पहले यही स्क्रीन दिखाऊंगा।

OpenAI के Codex docs कहते हैं कि Codex आपकी Codex होम डायरेक्टरी में रखी वैश्विक निर्देश-फ़ाइल पढ़ सकता है, जो आम तौर पर ~/.codex/AGENTS.md होती है। Codex settings docs यह भी कहते हैं कि Custom Instructions में किया गया बदलाव आपकी निजी AGENTS.md को अपडेट करता है।

मुझे यही ढांचा चाहिए। मैं ऐप को अपना मुख्य इंटरफ़ेस बना सकता हूं, और फिर भी उसके पीछे मौजूद असली फ़ाइल की स्पष्टता नहीं खोता।

मेरे मन में इसकी परतें कुछ इस तरह बैठती हैं:

1. अलग-अलग परियोजनाओं में लागू मेरी डिफ़ॉल्ट प्राथमिकताओं के लिए व्यक्तिगत ~/.codex/AGENTS.md
2. टीम और रिपॉज़िटरी से जुड़े निर्देशों के लिए रिपॉज़िटरी AGENTS.md
3. इन नियमों के आसपास Codex ऐप की सेटिंग्स और रिपॉज़िटरी मार्गदर्शन

यह रही वह स्क्रीन:

वे नियम जिन्हें मैं चाहता हूं कि Codex हर जगह पहले से साथ लाए

यह वही बुनियाद है जिसे मैं चाहता हूं कि Codex किसी भी रिपॉज़िटरी में परियोजना-विशेष निर्देश पढ़ने से पहले साथ लेकर पहुंचे।

# व्यक्तिगत AGENTS.md

## कोड शैली

- टिप्पणियां केवल अंग्रेज़ी में हों
- OOP की तुलना में फ़ंक्शनल प्रोग्रामिंग को प्राथमिकता दें
- OOP क्लासों का उपयोग केवल कनेक्टरों और बाहरी प्रणालियों के इंटरफ़ेस के लिए करें
- शुद्ध फ़ंक्शन लिखें - बदलाव केवल लौटाए गए मानों में दिखें, इनपुट पैरामीटर या वैश्विक स्थिति में नहीं
- DRY, KISS और YAGNI सिद्धांतों का पालन करें
- हर जगह कड़ा प्रकार-निर्धारण रखें - फ़ंक्शन के लौटाए गए मान, चर और संग्रह सब में
- नया कोड लिखने से पहले जांच लें कि वही तर्क पहले से मौजूद तो नहीं है
- बिना प्रकार बताए गए चर और generic प्रकारों से बचें
- किसी पैरामीटर का डिफ़ॉल्ट मान न दें - हर पैरामीटर को स्पष्ट रखें
- जटिल डेटा संरचनाओं के लिए सही प्रकार-परिभाषाएं बनाएं
- सभी import कथन फ़ाइल की शुरुआत में हों
- सरल, एक ही काम करने वाले फ़ंक्शन लिखें - बहु-मोड व्यवहार नहीं, और ऐसे फ्लैग पैरामीटर नहीं जो तर्क बदल दें

## त्रुटि-प्रबंधन

- त्रुटियां हमेशा स्पष्ट रूप से उठाएं, उन्हें चुपचाप अनदेखा न करें
- ऐसे विशिष्ट त्रुटि-प्रकार इस्तेमाल करें जो साफ बताएं कि क्या गलत हुआ
- ऐसे exception handlers से बचें जो हर चीज़ को एक साथ पकड़कर मूल कारण छिपा दें
- त्रुटि संदेश साफ और काम के होने चाहिए
- जब तक मैं साफ न कहूं, वैकल्पिक सहारा न जोड़ें
- लक्षण नहीं, मूल कारण ठीक करें
- बाहरी API या सेवा कॉल में चेतावनी के साथ पुनःप्रयास करें, फिर आखिरी त्रुटि उठाएं
- त्रुटि संदेशों में जाँच-पड़ताल के लिए पर्याप्त संदर्भ हो: request params, response body, status codes
- logging में बदलती हुई values को message strings में पिरोने के बजाय structured fields का उपयोग करें

## टूलिंग और निर्भरताएं

- `pyproject.toml` और `package.json` जैसी आधुनिक पैकेज प्रबंधन फ़ाइलों को प्राथमिकता दें
- dependencies को global रूप से नहीं, project environments में install करें
- dependencies को project config files में जोड़ें, अलग से एक-बार वाले installs के रूप में नहीं
- जरूरत पड़ने पर install की गई dependencies का source code पढ़ें, व्यवहार का अनुमान न लगाएं

## परीक्षण

- रिपॉज़िटरी की मौजूदा testing strategy और मौजूदा test suite का सम्मान करें
- डिफ़ॉल्ट रूप से नए unit tests न जोड़ें
- जब tests की जरूरत हो, तो integration, end-to-end या smoke tests को प्राथमिकता दें जो वास्तविक behavior को परखें
- unit tests का उपयोग कम ही करें, मुख्यतः stable datasets या pure data transformations के लिए
- केवल coverage numbers बढ़ाने के लिए unit tests कभी न जोड़ें
- जहां real calls व्यावहारिक हों, वहां mocks से बचें
- अक्सर mock-based coverage बनाए रखने की तुलना में real API या service calls पर थोड़ा खर्च करना बेहतर होता है
- मांगे गए बदलाव के लिए जितनी जरूरत हो, उतना ही न्यूनतम test coverage जोड़ें

## Codex कार्यप्रवाह

- संपादन करने से पहले repository को समझें
- अनुमान लगाने से पहले लागू `AGENTS.md` फ़ाइलें पढ़ें
- बदलावों को न्यूनतम और मौजूदा अनुरोध से सीधे जुड़ा हुआ रखें
- repository की मौजूदा शैली से मेल रखें, भले ही वह मेरी व्यक्तिगत पसंद से अलग हो
- असंबंधित बदलावों को वापस न करें
- कोड खोज के लिए `rg` को प्राथमिकता दें
- flags वाले non-interactive commands का उपयोग करें
- हमेशा non-interactive git diff का उपयोग करें: `git --no-pager diff` या `git diff | cat`
- code में बदलाव के बाद वही उपयुक्त tests या validation commands चलाएं जिन्हें project पहले से परिभाषित करता है

## दस्तावेज़ीकरण

- कोड ही मुख्य दस्तावेज़ीकरण है - साफ naming, types और docstrings का उपयोग करें
- दस्तावेज़ीकरण को उन्हीं functions या classes की docstrings में रखें जिनका वह वर्णन करती है, अलग files में नहीं
- अलग documentation files तभी बनाएं जब कोई अवधारणा code में साफ व्यक्त न की जा सके
- दस्तावेज़ीकरण को अलग-अलग files में दोहराएं नहीं
- जानकारी को वर्तमान स्थिति के रूप में रखें, बदलावों की changelog की तरह नहीं

यह फ़ाइल सबसे अच्छे अर्थ में बिलकुल सीधी-सादी है।

इसका काम बस बार-बार होने वाली रगड़ कम करना है:

• जब मुझे बस छोटा सा patch चाहिए हो, तब Codex का पूरा refactor छेड़ देना
• Codex का अपनी अनिश्चितता को मुलायम भाषा के पीछे छिपा देना
• "सुरक्षा" के नाम पर अनावश्यक बचाव-व्यवस्था जोड़ देना
• जब निर्देश बहुत संकरे हों, तब रिपॉज़िटरी की परंपराओं को अनदेखा कर देना

जब ये नियम पहले से लोड होते हैं, तो पूरा सत्र कहीं ज़्यादा शांत हो जाता है।

मैं वैश्विक नियमों को रिपॉज़िटरी नियमों से ऊपर क्यों रखता हूं

Codex, AGENTS.md की परतदार व्यवस्था को अच्छी तरह संभालता है। OpenAI वैश्विक फ़ाइल ~/.codex/AGENTS.md का ज़िक्र करता है, और फिर जैसे-जैसे काम की निर्देशिका अधिक विशिष्ट होती जाती है, वैसे-वैसे रिपॉज़िटरी और भीतर की निर्देशिका-फ़ाइलें लागू होने लगती हैं।

यह परतदार व्यवस्था उपयोगी है, लेकिन पहली परत फिर भी मेरी होनी चाहिए।

मेरी निजी फ़ाइल को इन सवालों का जवाब देना चाहिए:

• मैं कोड लिखने का ढंग कितना सख्त रखना चाहता हूं
• मेरे लिए किस तरह का त्रुटि-प्रबंधन स्वीकार्य है
• बदलाव करते समय एजेंट कितना आक्रामक हो
• रोज़मर्रा के कोडिंग काम में किस बिंदु पर चीज़ को पूरा माना जाए

रिपॉज़िटरी फ़ाइल को इन सवालों का जवाब देना चाहिए:

• यह कोडबेस किस तरह व्यवस्थित है
• कौन-कौन सी कमांड चलानी हैं
• कौन से हिस्से नाज़ुक हैं
• टीम PR, commit या दस्तावेज़ीकरण को कैसे संभालना चाहती है

संक्षेप में:

• व्यक्तिगत AGENTS.md बताता है कि मैं कैसे काम करता हूं
• रिपॉज़िटरी AGENTS.md बताता है कि यह कोडबेस कैसे चलती है

अगर मैं दोनों को मिला दूं, तो दोहराव होगा, धीरे-धीरे फर्क पैदा होगा, और आखिर में ऐसी फ़ाइल बनेगी जिसे कोई बनाए रखना नहीं चाहेगा।

यही वजहों में से एक है कि Codex मेरे लिए उम्मीद से बेहतर निकला। इसकी निर्देश-श्रृंखला साफ दिखाई देती है। यह किसी छिपे हुए प्रॉम्प्ट-जुगाड़ जैसा कम और एक वास्तविक व्यवस्था जैसा ज़्यादा लगता है।

Mac ऐप ही मेरा मुख्य इंटरफ़ेस है, और यह मायने रखता है

इस समय Codex Mac ऐप का हिस्सा मुझे सबसे ज़्यादा पसंद आ रहा है।

यह इसलिए नहीं कि CLI कमजोर है। CLI पहले से बहुत अच्छा है। ऐप बस रोज़मर्रा के इस्तेमाल के लिए ज़्यादा सुखद है। नीचे वही Codex है, ऊपर कहीं बेहतर अनुभव।

इसीलिए मैं इस लेख का केंद्र CLI को नहीं बना रहा, भले ही CLI महत्वपूर्ण हो। उसी व्यवस्था को इस्तेमाल करने का मेरे लिए बेहतर तरीका ऐप है।

ऐप को सिर्फ सजावटी चीज़ की जगह एक ठोस साधन बनाने वाली बात यह है कि उसके निर्देश अब भी AGENTS.md पर टिके हैं। ऐप के दस्तावेज़ कहते हैं कि Custom Instructions बदलने से निजी निर्देश AGENTS.md में अपडेट होते हैं, और मुझे यही रिश्ता चाहिए:

• सुविधा के लिए ऐप सेटिंग्स
• टिकाऊपन के लिए फ़ाइल-आधारित निर्देश

इससे बाद में CLI के उपयोग को समझना भी आसान हो जाता है, क्योंकि वही आधारभूत निर्देश आगे तक साथ चलते हैं।

रिपॉज़िटरी AGENTS.md अब भी ज़रूरी है, बस वही कहानी का मुख्य पात्र नहीं है

मैं नहीं चाहता कि यह लेख AGENTS.md की परतों पर पूरा मार्गदर्शक बन जाए, जबकि Codex यह काम ठीक से करता है।

मेरा तरीका इससे सरल है:

• व्यक्तिगत AGENTS.md Codex को मेरा बुनियादी व्यवहार देता है
• रिपॉज़िटरी AGENTS.md Codex को रिपॉज़िटरी से जुड़ी अपेक्षाएं देता है
• अंदरूनी स्तर की फ़ाइलें सिर्फ उन दुर्लभ जगहों के लिए हैं जहां उनकी सच में जरूरत हो

इससे पूरी व्यवस्था समझने में आसान रहती है।

अगर मैं कोई अनजान रिपॉज़िटरी खोलूं और Codex अजीब बर्ताव करे, तो मैं वजह जल्दी समझना चाहता हूं। आम तौर पर जवाब इनमें से एक होना चाहिए:

1. मेरे वैश्विक नियम पर्याप्त स्पष्ट नहीं हैं
2. रिपॉज़िटरी निर्देश गायब हैं
3. काम खुद बहुत व्यापक है

यह नहीं कि मुझे बैठकर सोचना पड़े कि सात छिपी हुई निर्देश-परतों में इस बार किसकी चली।

मेरी Codex व्यवस्था में CLI की जगह

Mac ऐप मेरा मुख्य इंटरफ़ेस है। CLI कोई दोयम दर्जे का सहारा नहीं है। वह वही Codex व्यवस्था है, बस उसका रूप अलग है।

CLI कुछ वजहों से अब भी महत्वपूर्ण है:

• यह फ़ाइल-आधारित विन्यास को एकदम साफ कर देता है
• ठीक-ठीक व्यवहार को जांचना या उसे स्क्रिप्ट में ढालना इसमें आसान होता है

मैं CLI के लिए अलग सोच नहीं रखना चाहता। मैं वही व्यक्तिगत AGENTS.md, वही रिपॉज़िटरी मार्गदर्शन, और दोनों जगह वही सुरक्षा-सीमाएं चाहता हूं।

यही निरंतरता उस बड़ी वजह का हिस्सा है जिसके कारण यह उत्पाद मुझे एकसार लगता है।

अभी मेरी व्यावहारिक Codex व्यवस्था

अगर मैं आज Mac पर इसे बिल्कुल शुरुआत से सेट करूं, तो क्रम यही रखूंगा।

1. सबसे पहले ऐप में अपने निजी निर्देश लिखें

Cmd+, दबाकर Codex ऐप की सेटिंग्स खोलें, Personalization में जाएं, और सबसे पहले Custom Instructions वहीं लिखें। मैं अब भी ~/.codex/AGENTS.md के हिसाब से सोचता हूं, लेकिन इसे जमाने और समय-समय पर देखने की मेरी मुख्य जगह ऐप ही है।

2. व्यक्तिगत फ़ाइल छोटी रखें, लेकिन रुख साफ हो

परियोजना की संरचना यहां नहीं होनी चाहिए। यहां वे टिकाऊ नियम होने चाहिए जो हर जगह साथ चलें:

• कड़ा प्रकार-निर्धारण
• स्पष्ट त्रुटि-प्रबंधन
• चुपचाप दूसरी राह पकड़ लेने वाली व्यवस्था नहीं
• छोटे और सीधे बदलाव
• बिखरे हुए दस्तावेज़ों की जगह कोड के भीतर लिखी docstrings
• टर्मिनल के साफ-सुथरे तौर-तरीके

3. रिपॉज़िटरी AGENTS.md केवल रिपॉज़िटरी-सत्य के लिए जोड़ें

यहीं कमांड, बनावट, सीमाएं, नामकरण, परीक्षण की अपेक्षाएं और संवेदनशील हिस्सों की जानकारी होनी चाहिए। यही रिपॉज़िटरी वाली परत है।

अभी Codex मुझे आशाजनक क्यों लगता है

मैं अभी भी Codex के साथ शुरुआती दौर में हूं, इसलिए मैं इसे बढ़ा-चढ़ाकर पेश नहीं करूंगा।

लेकिन इसका मेल अभी से मजबूत लगता है:

• फ़ाइल पर आधारित निर्देशों की एक असली परत
• ऐप और CLI, जो एक-दूसरे से जुड़े लगते हैं, टकराते हुए नहीं

मेरे लिए इसे इस्तेमाल करते रहने के लिए इतना काफी है।

अब तक मेरे लिए सबसे असरदार साबित हुई व्यवस्था सबसे कम चमकदार भी है: ठोस स्थायी निर्देश लिखो, रिपॉज़िटरी मार्गदर्शन को अलग रखो, और एजेंट को ऐसे आधार से शुरू होने दो जो पहले से तुम्हारे काम करने के तरीके से मेल खाता हो।

ढर्रा Cursor जैसा ही है। Claude Code जैसा ही है। उत्पाद अलग है, सीख वही है: सत्र तब बेहतर होता है, जब एजेंट यह अंदाज़ा लगाना बंद कर दे कि आप कौन हैं।

अगर आप इससे जुड़े दूसरे लेख पढ़ना चाहते हैं, तो वे यहां हैं:

• Cursor IDE के नियम: https://kirill-markin.com/hi/gyan/cursor-ide-niyam-kritrim-buddhimatta-coding-ke-liye/
• Claude Code के नियम: https://kirill-markin.com/hi/gyan/claude-code-niyam-kritrim-buddhimatta-ke-liye/