AGENTS.md आणि HUMAN.md: सोप्या भाषेत स्पष्टीकरण

What AGENTS.md आहे

AGENTS.md ही repository च्या root मध्ये असलेली साधी Markdown file आहे. या file मध्ये coding agent ला त्या project वर कसे काम करायचे याच्या सूचना दिलेल्या असतात. अधिकृत site मध्ये तिचे वर्णन असे केले आहे: "ही agents साठी README आहे: तुमच्या project वर AI coding agents ना काम करण्यासाठी आवश्यक context आणि instructions देण्यासाठी एक समर्पित, अपेक्षित ठिकाण." या format ची देखरेख Linux Foundation अंतर्गत Agentic AI Foundation करते. July 2026 पर्यंत Codex, Cursor, Jules, Devin आणि GitHub Copilot यांसह वीसपेक्षा जास्त agents ती वाचतात.

ही पद्धत वापरण्याचे कारण व्यावहारिक आहे. तुमच्या team मध्ये नवीन व्यक्ती README वाचते, build command चा अंदाज घेते आणि तो अंदाज चुकीचा ठरल्यास कोणाला तरी विचारते. Agent प्रश्न विचारू शकत नाही. तो npm test चालवण्याचा प्रयत्न करतो, पण project मध्ये pnpm test वापरलेले असते. त्यानंतर तो failure वाचतो आणि दुसरा पर्याय वापरतो. या प्रत्येक प्रयत्नासाठी लागणाऱ्या tokens चे शुल्क तुम्हाला द्यावे लागते. योग्य command एकदाच लिहून ठेवल्यास या प्रकारच्या failure ची संपूर्ण शक्यता दूर होते.

यासाठी कोणतीही required fields नाहीत. Site वर हे स्पष्टपणे सांगितले आहे: "AGENTS.md ही फक्त standard Markdown आहे. तुम्हाला हवी ती headings वापरा; agent तुम्ही दिलेला text फक्त parse करतो." हीच संपूर्ण specification आहे. तिचे मूल्य format मध्ये नाही. प्रत्येक tool आधीपासून ज्या path वर पाहतो, त्या path वर ही file उपलब्ध असण्यात तिचे मूल्य आहे.

फाइल कुठे ठेवायची आणि कोणती फाइल लागू होते

पहिली फाइल repository root मध्ये ठेवा. Monorepo मध्ये प्रत्येक subproject च्या आत आणखी फाइल्स जोडता येतात. नियम सोपा आहे: "agents directory tree मधील सर्वांत जवळची फाइल आपोआप वाचतात, त्यामुळे सर्वांत जवळच्या फाइलला प्राधान्य मिळते." दोन फाइल्समध्ये conflict असल्यास, संपादित केली जात असलेल्या फाइलच्या जवळची फाइल लागू होते. Chat मध्ये तुम्ही टाइप केलेली कोणतीही गोष्ट दोन्ही फाइल्सपेक्षा प्राधान्याने लागू होते.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

ही nesting वापरणे उपयुक्त ठरते, कारण एखाद्या folder मध्ये सत्य आणि पुढील folder मध्ये असत्य असलेली गोष्ट सांगण्याचा हा एकमेव मार्ग आहे. "प्रत्येक endpoint त्याच्या input चे validation करतो" यासारखा नियम endpoints च्या शेजारी असावा. तो root file मध्ये ठेवल्यास प्रत्येक असंबंधित task साठीही load होतो आणि त्याचा काहीच फायदा होत नाही. तुमच्या root file मध्ये प्रत्येक service साठी आधीच स्वतंत्र section तयार झाला असेल, तर nested layout मध्ये विभाजन करणे हा उपाय आहे. यात कोणते rules खाली हलवायचे आणि कोणते top level वर ठेवायचे हेही स्पष्ट केले आहे.

AGENTS.md मध्ये काय असावे

कोड वाचून एजंटला समजणार नाही अशा गोष्टी लिहा. अचूक build, test आणि lint commands सर्वप्रथम द्या. त्या terminal मध्ये paste करता येतील अशा स्वरूपात असाव्यात. एक test चालवण्याची command देखील द्या. फक्त संपूर्ण suite कशी चालवायची हे माहीत असलेला एजंट ती suite चाळीस वेळा चालवेल. Tool च्या default पेक्षा वेगळ्या असलेल्या conventions नमूद करा. एजंटला default आधीच माहीत असतो; त्याला फक्त तुमचा वेगळा नियम सांगायचा असतो. Commit message चे स्वरूप आणि pull request चे नियम असल्यास तेही जोडा.

एखादा दावा पडताळता येईल इतके ठोस लिहा. "2-space indentation वापरा" ही वापरता येण्यासारखी सूचना आहे, कारण ती पाळली आहे किंवा नाही हे तपासता येते. "कोड योग्य प्रकारे format करा" ही सूचना उपयोगी नाही, कारण तिच्यातील कोणतीही गोष्ट पडताळता येत नाही. Locations बाबतही हेच लागू होते: "API handlers src/api/handlers/ मध्ये असतात" हे "फाइल्स व्यवस्थित ठेवा" यापेक्षा स्पष्ट आहे.

नकारात्मक नियमांनाही येथे स्थान द्या. "npm run build त्यांना generate करते, त्यामुळे dist/ अंतर्गत असलेल्या फाइल्स कधीही संपादित करू नका" हा एक विशिष्ट चुकीचा बदल थांबवतो. तसेच, कारण नमूद केल्यामुळे तुम्ही न लिहिलेल्या समतुल्य प्रकरणाचा निष्कर्षही एजंट काढू शकतो. Scope संबंधी नियमही येथे असावा. एजंटला स्वतःच्या निर्णयावर सोडल्यास, तुम्ही मागितल्यापेक्षा अधिक मोठे बदल तो करेल: मोठ्या प्रमाणावर कॉपी केलेले एक कौशल्य फक्त कार्य करणारा सर्वात छोटा बदल करण्यावर आग्रह धरते.

यापैकी कोणत्याही फाइलमध्ये कधीही काय ठेवू नये

यापैकी कोणत्याही फाइलमध्ये secret ठेवू नका. ही फाइल git मध्ये commit केली जाते, प्रत्येक session च्या सुरुवातीला context मध्ये लोड केली जाते आणि प्रत्येक request वेळी model provider कडे पाठवली जाते. AGENTS.md मधील API key तुमच्या repository history मध्ये आणि third party च्या logs मध्येही नोंदली जाते. Secret चा मजकूर थेट पेस्ट करण्याऐवजी त्याचा संदर्भ द्या: "database password .env मध्ये आहे; ही फाइल gitignored आहे; ती वाचण्यापूर्वी विचारा." यासंबंधीची व्यापक पद्धत agent च्या आवाक्याबाहेर credentials ठेवणे येथे दिली आहे.

Agent निरीक्षण करून जे निष्पन्न करू शकतो ते समाविष्ट करू नका. Pasted directory listing, dependency list ची प्रत किंवा folder names पुन्हा सांगणारा architecture overview: हे सर्व लिहिल्यानंतर एका आठवड्यातच कालबाह्य होते आणि तोपर्यंत प्रत्येक session मध्ये context वापरते. Pitfalls आणि त्यामागची कारणे ठेवा. Inventory काढून टाका. कारणे स्वतंत्रपणे नमूद करणे उपयुक्त आहे, कारण एखादी असामान्य रचना का अस्तित्वात आहे हे agent ला दिसत नसेल, तर तो ती शांतपणे refactor करून काढून टाकेल. याच फाइलच्या बाजूला DESIGN.md ठेवण्याचे हेच कारण आहे.

CLAUDE.md ही त्याच संकल्पनेची Claude Code आवृत्ती आहे

Claude Code CLAUDE.md वाचतो आणि AGENTS.md स्वतःहून वाचत नाही. प्रकल्पाची फाइल ./CLAUDE.md किंवा ./.claude/CLAUDE.md येथे असते. प्रत्येक प्रकल्पासाठीच्या वैयक्तिक पसंती ~/.claude/CLAUDE.md येथे ठेवतात. Linux वर संस्था संपूर्ण मशीनसाठीची फाइल /etc/claude-code/CLAUDE.md येथे ठेवू शकते. सापडलेल्या फाइल्स filesystem root पासून तुमच्या working directory पर्यंत क्रमाने एकत्र केल्या जातात. त्यामुळे तुम्ही session ज्या directory मधून सुरू केला, तिच्या सर्वात जवळची फाइल शेवटी वाचली जाते. त्या directory मध्ये सुरू केलेल्या प्रत्येक session मध्ये तोच configuration stack लोड होतो. त्यामुळे एकाच मशीनवर दोन session शेजारी चालवणे शक्य होते आणि ते session चालू असताना एकमेकांना काम सोपवू शकतात.

तुमच्या repository मध्ये आधीच AGENTS.md असल्यास, तिची दुसरी प्रत ठेवू नका. ती import करा आणि Claude साठी आवश्यक असलेले अतिरिक्त नियमच जोडा:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

जोडण्यासाठी काहीही अतिरिक्त नसल्यास symlink वापरा:

ln -s AGENTS.md CLAUDE.md

यशस्वी झाल्यावर command काहीही output देत नाही. पुढील session मध्ये /context चालवा आणि Memory files अंतर्गत CLAUDE.md दिसत आहे का ते तपासा. ती यादीत नसल्यास फाइल लोड झालेली नाही, त्यामुळे तिच्यातील कोणताही नियम लागू झालेला नाही. स्वतः फाइल लिहिण्याऐवजी पहिला मसुदा तयार करण्यासाठी /init चालवा. ते codebase वाचून सुरुवातीची फाइल तयार करते. CLAUDE.md आधीपासून असल्यास ती overwrite न करता सुधारणा सुचवते.

प्रत्येक फाइल साधारण 200 lines पेक्षा कमी ठेवा. मोठ्या फाइल्स window मधील अधिक जागा वापरतात आणि नियमांचे पालन कमी होते. त्या जागेसाठी आणखी काय स्पर्धा करते हे पाहायचे असल्यास, agent च्या context window मध्ये प्रत्यक्षात काय भरते याचे स्पष्टीकरण पाहा.

एका मुद्द्यावर विशेष भर देणे आवश्यक आहे. AGENTS.md ही मार्गदर्शक सूचना आहे; ती permission system नाही. तिचा मजकूर सामान्य context म्हणून येतो. त्यामुळे model तो वाचतो आणि सामान्यतः त्याचे पालन करतो. मात्र तिच्या विरोधातील action रोखण्यासाठी काहीही अंमलात येत नाही. तुम्ही लिहिलेला एखादा नियम शांतपणे वगळला गेला आणि त्याचे कारण समजत नसेल, तर wording तिसऱ्यांदा बदलण्यापूर्वी एखादी instruction का वगळली जाते याची कारणे तपासा. प्रत्येक वेळी लागू राहणाऱ्या नियमासाठी, उदाहरणार्थ "never push to main", hook किंवा permission setting वापरा. ते code म्हणून चालतात आणि model ने पालन करण्याचा निर्णय घ्यावा यावर अवलंबून राहत नाहीत.

ही फाइल्स तुमच्यासाठी लिहिणारी साधने

30 July 2026 रोजी GitHub च्या trending list मधील दोन प्रकल्प ही पद्धत कोणत्या दिशेने जात आहे ते दाखवतात.

agent0ai/dox (July 2026 पर्यंत 1,368 stars) हा AGENTS.md फाइल्सची tree अद्ययावत ठेवण्यासाठीचा framework आहे. तो कोणतेही package किंवा runtime release करत नाही. त्यातील AGENTS.md चा मजकूर तुमच्या स्वतःच्या root AGENTS.md मध्ये copy करणे हाच install आहे. आधीपासून अस्तित्वात असलेल्या प्रकल्पासाठी तुम्ही तुमच्या agent ला असे सांगता:

Initialize DOX tree for this project now.

त्यानंतर agent child AGENTS.md फाइल्स आणि त्यांचे indexes तयार करतो. कोणतेही संपादन करण्यापूर्वी तो त्या tree मधून जातो. एखादा बदल लागू झाल्यानंतर प्रभावित documentation अद्ययावत करतो. यामागील गृहितक असे आहे की agent आपल्या कामाचा परिणाम म्हणून अद्ययावत ठेवत असलेले documentation अचूक राहते; परंतु एखादी व्यक्ती हाताने अद्ययावत करत असलेले documentation तसे राहत नाही.

HUMAN.md, तुमच्याकडे लागू केलेली तीच युक्ती

Intuition-Lab/personal-model (July 2026 पर्यंत 1,260 stars) ही पद्धत repository ऐवजी व्यक्तीवर लागू करते. हा प्रकल्प तुमचे HUMAN.md तुम्ही लिहिलेली file नसून system चा output आहे, असे मांडतो: “सध्या काय महत्त्वाचे आहे, तुम्ही साधारणपणे निर्णय कसे घेता आणि तुमचे लक्ष कुठे वळत आहे याचे सतत अद्ययावत model.” हे macOS 13 किंवा त्यानंतरच्या आवृत्तीवर locally चालते, तुम्ही macOS permission दिल्यानंतर activity capture करते आणि MCP (model context protocol) द्वारे agents ना result उपलब्ध करून देते. Install करण्याची संक्षिप्त पद्धत:

uv tool install personal-model
persome onboard
persome model open --after 30

बहुतांश लाभ मिळवण्यासाठी यापैकी काहीही आवश्यक नाही. स्वतः लिहिलेले HUMAN.md साधारण वीस ओळींचे असते: तुमची भूमिका, तुमचा timezone, तुम्ही प्रत्यक्षात वापरत असलेला stack, तुम्ही आधीच घेतलेले आणि पुन्हा चर्चेला आणायचे नसलेले निर्णय, तसेच तुम्हाला परत किती explanation हवे आहे. Project file ज्या repeated explaining ची गरज कमी करते, त्याच प्रकारची गरज हे एक स्तर वर कमी करते.

एक सावधगिरी. HUMAN.md हे व्यक्तीचे profile असल्याने ते मूलतः sensitive असते. ते public repository मध्ये ठेवू नका. ते ~/.claude/CLAUDE.md मध्ये किंवा project root मधील gitignored CLAUDE.local.md मध्ये ठेवा. हे committed file सोबत load होते आणि त्याच पद्धतीने हाताळले जाते.

कॉपी करता येईल असा प्रारंभिक नमुना

हा नमुना मुद्दाम संक्षिप्त ठेवला आहे. लागू नसलेले विभाग काढून टाका आणि अद्ययावत ठेवता येणार नाहीत असे विभाग जोडणे टाळा.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

नमुना लिहा आणि त्यातच दुरुस्ती करा. एखादी ओळ जोडण्याचा संकेत म्हणजे तीच दुरुस्ती तुम्ही chat मध्ये दोनदा लिहिली आहे. या एका नियमामुळे फाइल उपयुक्त राहते. तसेच ही फाइल कोणीही वाचत नाही अशा दस्तऐवजात वाढत जाण्यापासून, machines सह, थांबते. नमुना स्थिर झाल्यावर तो repository सोबत राहतो. agent तुमच्या laptop ऐवजी अन्यत्र चालत असताना हे विशेष महत्त्वाचे ठरते: तुमच्या स्वतःच्या server वर coding agent चालवणे या setup मध्ये ते स्पष्ट केले आहे.

FAQ

AGENTS.md ही CLAUDE.md सारखीच फाइल आहे का?

दोन वेगवेगळ्या फाइलनावांखाली हीच संकल्पना आहे. Claude Code CLAUDE.md वाचतो आणि त्यांना जोडले नसल्यास AGENTS.md दुर्लक्षित करतो. एक फाइल सत्याचा मुख्य स्रोत ठेवा आणि दुसरी फाइल तिच्याशी link करा. यासाठी तुमच्या CLAUDE.md च्या सुरुवातीला @AGENTS.md ही ओळ लिहा किंवा ln -s AGENTS.md CLAUDE.md वापरा. स्वतंत्रपणे सांभाळलेल्या दोन पूर्ण प्रती एका महिन्यात परस्पर विसंगत होतील.

AGENTS.md लिहिल्याने agent ते नक्की पाळतो का?

नाही. मजकूर context म्हणून दिला जातो. त्यामुळे model तो वाचतो आणि सामान्यतः त्याचे पालन करतो. मात्र त्याच्या विरुद्ध असलेली कृती काहीही आपोआप रोखत नाही. संदिग्ध सूचनांचे पालन सर्वांत कमी विश्वासार्ह असते. तसेच परस्परविरोधी मार्गदर्शन देणाऱ्या दोन फाइल्स असल्यास agent मनमानीने त्यांपैकी एक निवडतो. प्रत्येक वेळी लागू होणारा नियम आवश्यक असल्यास hook किंवा permission rule वापरा. model काहीही ठरवो, client हे नियम लागू करतो.

AGENTS.md git मध्ये commit करावी का?

होय, प्रकल्पाबद्दल सत्य असलेल्या कोणत्याही माहितीसाठी ती commit करा: build commands, layout आणि conventions. हीच त्या फाइलची भूमिका आहे. त्यामुळे तुमच्या सहकाऱ्यांचे agents देखील तुमच्या agent सारख्याच context ने सुरू होतात. वैयक्तिक किंवा एखाद्या मशीनपुरती मर्यादित माहिती स्वतंत्र gitignored फाइलमध्ये ठेवा. credentials दोन्हीपैकी कोणत्याही ठिकाणी ठेवू नका.

HUMAN.md म्हणजे काय आणि मला ती आवश्यक आहे का?

HUMAN.md ही प्रकल्पाऐवजी व्यक्तीचा machine-readable profile असलेली फाइल आहे. त्यात तुमची भूमिका, तुमच्या मर्यादा आणि आधीच निश्चित केलेले निर्णय असतात. त्यामुळे प्रत्येक session मध्ये ते निर्णय पुन्हा उघडावे लागत नाहीत. सुरुवात करण्यासाठी कोणत्याही tooling ची आवश्यकता नाही. तुमच्या user-level instructions file मध्ये स्वतः लिहिलेल्या वीस ओळींमधूनही बहुतेक लाभ मिळतो. तिच्याकडे personal data म्हणून पाहा आणि तुम्ही push करत असलेल्या कोणत्याही repository मध्ये ती ठेवू नका.