AGENTS.md और CLAUDE.md: एक ऐसी Config फ़ाइल कैसे लिखें जिसे आपका Agent वाकई इस्तेमाल करे

एक अच्छी config फ़ाइल लिखना agentic coding में सबसे अधिक प्रभाव डालने वाला और सबसे कम मेहनत वाला काम है। एक बार संदर्भ सेट करें और हर session को फ़ायदा मिलता है: agent आपका test command अंदाज़ा लगाना बंद कर देता है, अपने defaults के अनुसार reformatting बंद कर देता है, और उस directory को edit करना बंद कर देता है जिसे आपने off-limits बताया था। यह पेज AI-Native "context & configuration" skill — 17 AI-native skills में से एक — की व्यावहारिक craft है, जिसे हम levels के पार grade करते हैं। CLAUDE.md / AGENTS.md में durable project memory रखना Level 3 Agentic Developer की एक पहचान है, इसलिए इसे सही तरीके से करना ज़रूरी है।

मूल विचार हर tool में एक जैसा है, भले ही mechanics अलग-अलग हों: एक config फ़ाइल उन चीज़ों को रखती है जिन्हें agent code से खुद नहीं समझ सकता। model आपकी भाषा पहले से जानता है। वह यह नहीं जानता कि आपके tests को एक specific flag की ज़रूरत है, कि आपने तीन महीने पहले किसी library से माइग्रेट किया, या कि infra/ generated है और उसे कभी हाथ से edit नहीं करना चाहिए। यही खाई यह फ़ाइल भरती है।

Landscape: एक दर्शन, कई फ़ाइलें

हर प्रमुख agent एक project context फ़ाइल पढ़ता है। सभी एक ही दर्शन साझा करते हैं लेकिन filename और loading mechanics पर अलग होते हैं। 2026 का नक्शा यहाँ है:

File	Tool(s)	Status
AGENTS.md	OpenAI Codex, Cursor, GitHub Copilot agent, + ~20 tools	Open cross-tool standard
CLAUDE.md	Claude Code	Claude Code का native format
GEMINI.md	Gemini CLI	Gemini का native format
.github/copilot-instructions.md	GitHub Copilot	Copilot की repo instructions
.cursor/rules (formerly .cursorrules)	Cursor	Cursor का rules format

निष्कर्ष: AGENTS.md उभरता हुआ single source of truth है — एक open spec जिसे ~20 tools पहले से पढ़ते हैं। पेंच यह है कि Claude Code AGENTS.md को natively नहीं पढ़ता; वह केवल CLAUDE.md पढ़ता है। इसलिए canonical one-source-of-truth pattern यह है कि AGENTS.md को canonical रखें और एक छोटी CLAUDE.md से Claude को bridge करें जो उसे import करे:

@AGENTS.md

<!-- Claude-specific notes can go below -->

एक symlink भी काम करता है (ln -s AGENTS.md CLAUDE.md), लेकिन Windows पर @import prefer करें — वहाँ symlinks के लिए admin rights चाहिए। अब आप एक फ़ाइल maintain करते हैं, और दोनों ecosystems इसे पढ़ते हैं।

इसमें असल में क्या डालें

GitHub के 2,500 से अधिक repositories के विश्लेषण ("How to write a great AGENTS.md") से पता चला कि जो configs agents की मापनीय रूप से मदद करती हैं उनमें छह sections होते हैं। मोटे तौर पर priority के क्रम में:

1. Commands — शुरुआत में रखें, exact executable commands और flags के साथ (npm test, npm run build, pytest -v), सिर्फ tool names नहीं। यह सबसे अधिक ROI वाला section है: agents पहले से जानते हैं कि pytest मौजूद है; वे आपके project के required flags नहीं जानते। इसे ऊपर रखें।
2. Testing practices — आप कैसे test करते हैं, commit से पहले क्या चलाएं, coverage की उम्मीदें।
3. Project structure — चीज़ें कहाँ हैं, ताकि agent ढूंढता न रहे।
4. Code style — तीन paragraphs के बजाय एक असली code snippet दिखाएं।
5. Git workflow — branch naming, commit conventions, PR नियम।
6. Boundaries — agent को क्या कभी नहीं छूना चाहिए (generated dirs, secrets, vendored code, migrations)।

प्राथमिकता के क्रम पर ध्यान दें। "Commands with flags" पहले है, इसका कारण है: यह वह अकेली चीज़ है जो model सबसे कम अंदाज़ा लगा सकता है और सबसे अधिक गलत करता है। अगर आप कुछ और अच्छी तरह नहीं लिखते, तो यह लिखें।

क्या शामिल करें / क्या न करें: line-by-line परीक्षण

Anthropic के memory docs एक स्पष्ट दो-कॉलम रेखा खींचते हैं। हर उस line के लिए इसे filter की तरह इस्तेमाल करें जिसे आप जोड़ने की सोच रहे हैं।

शामिल करें	बाहर रखें
Bash commands जो agent अंदाज़ा नहीं लगा सकता	जो कुछ भी code से समझा जा सकता हो
Code-style नियम जो defaults से अलग हों	Standard language conventions जो model पहले से जानता हो
Testing instructions / पसंदीदा test runner	विस्तृत API docs (link दें बजाय)
Repo etiquette (branch naming, PR conventions)	बदलती रहने वाली जानकारी
Project-specific architectural decisions	लंबी व्याख्याएं और tutorials
Dev-env की खासियतें (required env vars)	File-by-file codebase descriptions
गैर-स्पष्ट gotchas	स्व-स्पष्ट practices जैसे "clean code लिखें"

एक परीक्षण है जो पूरी table को एक आदत में बदल देता है:

Per-line परीक्षण: "अगर यह line हटा दूं तो क्या agent गलतियाँ करेगा? अगर नहीं, तो हटा दो।"

हर line पर यह परीक्षण करें। "Use TypeScript" — agent .ts files देख सकता है; हटा दो। "Run database migrations with npm run db:migrate, never edit migrations/ by hand" — यह अंदाज़ा नहीं लगाया जा सकता था, और गलत करने से state corrupt होती है; रखो।

सही ऊँचाई पर लिखें

Anthropic का context-engineering guidance अच्छे authoring को चार सिद्धांतों में समेटता है।

1. Specificity / verifiability. नियम इतने concrete लिखें कि agent के output के विरुद्ध जाँचे जा सकें। अस्पष्ट guidance verify नहीं हो सकती, इसलिए भरोसेमंद तरीके से follow नहीं हो सकती।

• "2-space indentation इस्तेमाल करें" — न कि "Code को ठीक से format करें।"
• "Commit से पहले npm test चलाएं" — न कि "अपने बदलाव test करें।"
• "API handlers src/api/handlers/ में हैं" — न कि "Files को व्यवस्थित रखें।"

2. सही ऊँचाई। brittle hardcoded logic और अस्पष्ट hand-waving के बीच निशाना लगाएं: "व्यवहार को guide करने के लिए काफी specific, लेकिन एक मजबूत heuristic बनने के लिए काफी flexible।" बहुत rigid हो तो पहले edge case पर टूट जाएगा; बहुत loose हो तो कुछ guide नहीं होगा।

3. Minimal-but-sufficient. Minimal का मतलब छोटा नहीं है। इसका मतलब है पर्याप्त context upfront देना ताकि agent को अंदाज़ा न लगाना पड़े — और उससे आगे कुछ नहीं। filler हटाएं, ज़रूरी detail रखें।

4. Structure. Labeled sections इस्तेमाल करें — Markdown headers या XML tags। एक scannable फ़ाइल वह है जिसे agent (और आपके teammates) वाकई parse करते हैं।

इसे lean रखें

Lean रहने की असली वजह token budget है। Config फ़ाइल हर single session में पूरी load होती है। यह demand पर retrieve नहीं होती; यह launch पर context में prepend होती है। इसलिए bloat का सीधा, मापा हुआ cost है: एक bloated CLAUDE.md instruction adherence को मापनीय रूप से कम करती है। Anthropic का अपना framing स्पष्ट है — bloated CLAUDE.md files Claude को आपकी असली instructions ignore करने पर मजबूर करती हैं। आप जो भी junk line जोड़ते हैं, वह आपकी अच्छी lines को कमज़ोर करती है।

Targets concrete हैं:

• Anthropic CLAUDE.md के लिए soft goal के रूप में ~200 lines से कम को target करता है।
• Codex AGENTS.md पर 32 KiB की hard cap लागू करता है (project_doc_max_bytes); oversized files को truncate किया जाता है, इसलिए cap के बाद कुछ भी चुपचाप load नहीं होता।

एक जाल का नाम लेना ज़रूरी है: imports budget बचाते नहीं। एक @imported फ़ाइल फिर भी launch पर context में load होती है — आपने फ़ाइल split की, footprint कम नहीं किया। हर session में जो load होता है उसे वाकई कम करने के लिए, conditionally-relevant content को offload करें:

• Path-scoped rules cross-cutting concerns के लिए जो कई files को छूती हैं — वे तभी load होती हैं जब agent उस path में काम कर रहा हो।
• Skills on-demand procedures के लिए — वे तभी load होती हैं जब invoke की जाएं।
• Links लंबी या विस्तृत reference material के लिए — उसे inline करने की बजाय point करें।

सिद्धांत वही है जो per-line test enforce करता है, section level पर लागू: अगर यह कभी-कभी ही relevant है, तो यह always-loaded फ़ाइल में नहीं होना चाहिए।

DESIGN.md: एक team convention, कोई standard नहीं

DESIGN.md "config को lean रखो, detail को link करो" का पाठ्यपुस्तक application है। यह एक अलग design/architecture doc है — key decisions, domain model, architectural patterns, यह इस तरह क्यों बना है — जिसे आपकी AGENTS.md inline करने की बजाय @import करती है या reference देती है। इससे always-loaded config छोटी रहती है जबकि deep context एक hop दूर रहता है।

हालांकि इसकी status के बारे में ईमानदार रहें: AGENTS.md और CLAUDE.md के विपरीत, कोई primary source नहीं है जो DESIGN.md को एक standard agent-config file के रूप में स्थापित करे। यह एक शक्तिशाली team convention है, कोई documented standard नहीं। इसे इसलिए इस्तेमाल करें क्योंकि यह आपकी team के लिए काम करता है, न इसलिए कि कोई spec इसे अनिवार्य करती हो।

Scope और hierarchy

दोनों ecosystems files को broad से specific तक layer करते हैं, लेकिन precedence अलग-अलग तरीके से resolve करते हैं।

CLAUDE.md के चार scopes हैं, broad → specific loading:

1. Managed policy — आपके org / IT द्वारा set, organization-wide लागू।
2. User — ~/.claude/CLAUDE.md, आपके सभी projects पर लागू।
3. Project — ./CLAUDE.md, git में checked in और team के साथ shared।
4. Local — ./CLAUDE.local.md, gitignored, आपके personal overrides के लिए।

Monorepos में, parent-directory files auto-load होती हैं और child-directory files demand पर load होती हैं। Imports @path/to/file syntax इस्तेमाल करते हैं (relative या absolute), 4 hops तक nest होते हैं, और parser code blocks skip करता है इसलिए fenced block के अंदर path को import नहीं माना जाता।

AGENTS.md closest-wins resolve करता है। Codex Git root से नीचे आपकी current working directory तक चलता है और मिली files को root-first concatenate करता है। क्योंकि closer files बाद में आती हैं, वे override करती हैं — closest file जीतती है। Monorepo में प्रत्येक package में एक AGENTS.md रखें, और जो code edit हो रहा है उसके सबसे नज़दीक वाली precedence लेती है। इन सब से ऊपर: chat में explicit instruction हर file को override करती है।

और पहले का cross-tool bridge दोनों systems को जोड़ता है: AGENTS.md को canonical रखें, एक CLAUDE.md जोड़ें जो @AGENTS.md करे, और आपकी hierarchy duplication के बिना tools में shared हो जाती है।

Advisory, enforcement नहीं

यहाँ वह nuance है जो आपको गलत sense of safety से बचाती है: ये files advisory context हैं, deterministic enforcement नहीं। ये agent को steer करती हैं; इसे bind नहीं करतीं।

IMPORTANT और YOU MUST जैसे emphasis words adherence को मापनीय रूप से बेहतर बनाते हैं — लेकिन वे इसकी गारंटी नहीं देते। ऐसी requirements के लिए जो हर बार होनी ही चाहिए (formatter चलाना, failing tests वाला commit block करना, main पर कभी न लिखना), deterministic backstop config में मज़बूत wording नहीं बल्कि Claude Code में hooks हैं।

Rule of thumb: guidance और heuristics के लिए config इस्तेमाल करें; hooks की ओर तब जाएं जब "agent आमतौर पर यह करता है" काफी न हो और आपको "agent हमेशा यह करता है" चाहिए।

इसे code की तरह maintain करें

Config फ़ाइल एक living artifact है, एक बार लिखकर भूल जाने वाली चीज़ नहीं। इसे उसी तरह treat करें जैसे repo का बाकी हिस्सा।

• /init से bootstrap करें। Tool को अपने codebase से पहला draft generate करने दें, फिर हाथ से refine करें — generated version एक starting point है, finished file नहीं।
• जब कुछ गलत हो तब review करें। जब भी agent कुछ गलत करे, पूछें कि क्या config में missing या misleading line इसकी वजह थी।
• नियमित रूप से prune करें। पूरी file पर per-line test फिर से चलाएं। पिछली तिमाही में ज़रूरी lines अब dead weight हो सकती हैं।
• Behavior से changes test करें। यह मत मानें कि edit ने मदद की — observe करें कि agent का व्यवहार वाकई बदला या नहीं। अगर आप फ़र्क नहीं देख सकते, तो शायद वह line काम नहीं कर रही।
• इसे git में check करें। Shared, version-controlled config का मतलब है पूरी team योगदान देती है और फ़ायदा उठाती है, और बदलाव review में दिखते हैं।

सबसे मूल्यवान आदत self-improving loop है: जब agent गलती करे, एक single one-line rule जोड़ें ताकि यह दोबारा न हो। कुछ हफ्तों में यह loop आपकी config को ठीक उन्हीं gotchas पर converge कर देती है जो आपके project में असल में हैं — न कम, न ज़्यादा।

एक starter AGENTS.md

यहाँ एक असली, copy-paste skeleton है जिसमें सभी छह high-ROI sections realistic placeholders के साथ भरे हैं। अपनी specifics डालें और per-line test के तहत जो भी अपनी जगह justify न करे उसे हटा दें।

# AGENTS.md

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Test (all): `npm test`
- Test (single file): `npm test -- path/to/file.test.ts`
- Lint + autofix: `npm run lint -- --fix`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Testing
- Run `npm test` and `npm run typecheck` before every commit.
- New code needs a test in the matching `*.test.ts` file.
- Integration tests need a running DB: `npm run db:up` first.

## Project structure
- `src/api/handlers/` — HTTP route handlers
- `src/services/` — business logic (no HTTP/DB code here)
- `src/db/` — schema + queries; migrations in `src/db/migrations/`
- `web/` — React frontend (separate AGENTS.md inside)

## Code style
- 2-space indentation, single quotes, no default exports.
- Throw typed errors from `src/errors.ts`, never bare `Error`.
```ts
// Good: typed error, narrow return
export async function getUser(id: string): Promise<User> {
  const user = await db.users.find(id);
  if (!user) throw new NotFoundError('user', id);
  return user;
}

Git workflow

• Branch from main: feature/<short-desc> or fix/<short-desc>.
• Conventional Commits (feat:, fix:, chore:).
• Open a PR; never push directly to main.

Boundaries

• NEVER edit src/db/migrations/ by hand — generate with npm run db:migrate:new.
• NEVER touch dist/, node_modules/, or *.generated.ts (all generated).
• NEVER commit secrets; required env vars are documented in .env.example.

Tools में single source of truth के लिए, इसके साथ `@AGENTS.md` वाली एक single-line `CLAUDE.md` रखें, और अपने deeper architecture notes (एक `DESIGN.md`, आपके ADRs) को link करें बजाय paste करने के।

## आगे कहाँ जाएं

एक lean, specific config फ़ाइल उन concrete behaviors में से एक है जो AI-assisted developers को सही मायने में AI-native developers से अलग करती है। तीन मिनट में [अपना AI-native level पता करें](/quiz) — यह बिल्कुल इसी तरह की craft को grade करता है — और जब आप अपना toolchain wire up करने के लिए तैयार हों, तो [ProCoders के recommended stack](/stack) से शुरू करें।