AGENTS.md आणि HUMAN.md: फरक व वापर समजून घ्या

AGENTS.md म्हणजे काय

AGENTS.md ही रिपॉझिटरीच्या रूटमध्ये असलेली साधी markdown फाइल आहे. या फाइलमध्ये coding agent ने त्या प्रकल्पावर कसे काम करावे, याच्या सूचना असतात. अधिकृत साइटनुसार, ती "agents साठी README: तुमच्या प्रकल्पावर AI coding agents ला काम करण्यासाठी आवश्यक संदर्भ आणि सूचना देण्याची समर्पित, अंदाज करता येण्याजोगी जागा" आहे. या फॉरमॅटचे व्यवस्थापन Linux Foundation अंतर्गत Agentic AI Foundation करते. जुलै 2026 पर्यंत Codex, Cursor, Jules, Devin आणि GitHub Copilot यांसह 20 पेक्षा जास्त agents ती वाचतात.

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

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

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

पहिली फाइल repository root मध्ये ठेवा. Monorepo मध्ये प्रत्येक subproject मध्ये आणखी फाइल्स जोडू शकता. नियम सोपा आहे: "agents directory tree मधील सर्वात जवळची फाइल आपोआप वाचतात, त्यामुळे सर्वात जवळच्या फाइलला प्राधान्य मिळते." दोन फाइल्समध्ये विरोध असल्यास, संपादित होत असलेल्या फाइलच्या जवळची फाइल लागू होते. 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 होतो आणि त्याचा काहीही उपयोग होत नाही.

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

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

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

नकारात्मक नियमांसाठीही जागा द्या. "dist/ अंतर्गत असलेल्या फायली कधीही संपादित करू नका; त्या npm run build द्वारे निर्माण केल्या जातात" हा एक विशिष्ट चुकीचा बदल रोखतो. त्यात कारण दिले असल्यामुळे, न लिहिलेल्या समतुल्य परिस्थितीबाबत agent स्वतः निष्कर्ष काढू शकतो.

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

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

Agent निरीक्षण करून जे ठरवू शकतो, ते लिहू नका. पेस्ट केलेली directory listing, dependency list ची प्रत किंवा folder names ची पुनरावृत्ती करणारा architecture overview यांसारखी सर्व माहिती तुम्ही लिहिल्यानंतरच्या आठवड्यातच कालबाह्य होते. तोपर्यंत प्रत्येक session मध्ये ही माहिती context वापरते. अडचणी आणि त्यामागील कारणे ठेवा. inventory काढून टाका.

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 सुरू केलेल्या ठिकाणाच्या सर्वात जवळची फाइल शेवटी वाचली जाते.

तुमच्या 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 दिसत असल्याची खात्री करा. ते त्या यादीत नसल्यास फाइल कधीही load झाली नाही, त्यामुळे तिच्यातील कोणतीही सूचना लागू झाली नाही. सुरुवातीचा मसुदा स्वतः लिहिण्याऐवजी तयार करायचा असल्यास /init चालवा. हे codebase वाचून सुरुवातीची फाइल तयार करते. CLAUDE.md आधीपासून असल्यास ती overwrite करण्याऐवजी सुधारणा सुचवते.

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

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

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

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

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

Initialize DOX tree for this project now.

त्यानंतर agent child AGENTS.md फाइल्स आणि त्यांचे indexes तयार करतो. कोणतीही गोष्ट edit करण्यापूर्वी तो त्या 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 किंवा त्यानंतरच्या आवृत्तीवर स्थानिकरित्या चालते. macOS ची permission दिल्यानंतर ते activity capture करते आणि MCP (model context protocol) द्वारे agents साठी परिणाम उपलब्ध करून देते. Install करण्याची संक्षिप्त पद्धत:

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

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

एक सावधगिरी आवश्यक आहे. HUMAN.md ही व्यक्तीची profile असल्यामुळे ती स्वभावतः संवेदनशील असते. ती public repository मध्ये ठेवू नका. ती ~/.claude/CLAUDE.md मध्ये ठेवा किंवा project root मधील gitignored CLAUDE.local.md मध्ये ठेवा. ही file 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 मध्ये दोनदा टाइप केली आहे. हा एक नियम फाइल उपयुक्त ठेवतो आणि मशीनसह कोणीही न वाचणाऱ्या दस्तऐवजात तिची अनावश्यक वाढ होऊ देत नाही. फाइल स्थिर झाल्यावर ती repository सोबत राहते. Agent तुमच्या laptop व्यतिरिक्त इतरत्र चालत असताना हे विशेष महत्त्वाचे ठरते: तुमच्या स्वतःच्या server वर coding agent चालवणे या मांडणीचे वर्णन करते.

FAQ

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

ही दोन फाइलनावे असलेली एकच संकल्पना आहे. Claude Code CLAUDE.md वाचते आणि तुम्ही त्यांना जोडलेले नसल्यास AGENTS.md दुर्लक्षित करते. एक फाइल मुख्य स्रोत म्हणून ठेवा आणि दुसरी तिच्याशी लिंक करा. यासाठी तुमच्या 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 मध्ये स्वतः लिहिलेल्या वीस ओळींमधूनही तुम्हाला यातील बहुतांश लाभ मिळतो. तिच्याकडे वैयक्तिक माहिती म्हणून पाहा आणि तुम्ही push करत असलेल्या कोणत्याही repository मध्ये ती ठेवू नका.