AGENTS.md, HUMAN.md గురించి పూర్తి వివరణ

AGENTS.md అంటే ఏమిటి

AGENTS.md అనేది repository root లో ఉండే సాధారణ Markdown file. ఆ project పై ఎలా పని చేయాలో coding agent కు ఇది తెలియజేస్తుంది. Official site దీన్ని “agents కోసం README: AI coding agents మీ project పై పని చేయడానికి అవసరమైన context మరియు instructions అందించే ప్రత్యేక, ఊహించగల స్థలం”గా వివరిస్తుంది. ఈ format ను Linux Foundation ఆధ్వర్యంలోని Agentic AI Foundation నిర్వహిస్తుంది. July 2026 నాటికి Codex, Cursor, Jules, Devin, GitHub Copilot సహా ఇరవైకి పైగా agents దీన్ని చదువుతున్నాయి.

ఈ convention ఉండటానికి కారణం ఆచరణాత్మకమైనది. మీ team లో కొత్త వ్యక్తి README చదివి build command ను ఊహిస్తాడు. ఆ ఊహ తప్పైతే ఎవరినైనా అడుగుతాడు. Agent అడగలేడు. అది `npm test ను అమలు చేస్తుంది, కానీ project pnpm test` ను ఉపయోగిస్తుంటే అది విఫలమవుతుంది. ఆ failure ను చదివి agent మరొక మార్గాన్ని ప్రయత్నిస్తుంది. ఆ ప్రయత్నాల్లో ఉపయోగించిన ప్రతి token కు మీరు చెల్లించాలి. సరైన command ను ఒక్కసారి రాసి ఉంచితే, ఈ మొత్తం రకమైన failure తొలగిపోతుంది.

తప్పనిసరి fields ఏవీ లేవు. Site దీన్ని స్పష్టంగా చెబుతుంది: “AGENTS.md అనేది కేవలం standard Markdown. మీకు నచ్చిన headings ను ఉపయోగించండి; agent మీరు అందించిన text ను మాత్రమే parse చేస్తుంది.” ఇదే పూర్తి specification. దీని విలువ format లో లేదు. ప్రతి tool ఇప్పటికే పరిశీలించే path వద్ద ఈ file ఉండటంలో ఉంది.

ఫైల్ ఎక్కడ ఉండాలి, ఏ ఫైల్‌కు ప్రాధాన్యం ఉంటుంది

మొదటి ఫైల్‌ను 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 ను validate చేయాలి" వంటి నియమం endpoints పక్కనే ఉండాలి. దీన్ని root ఫైల్‌లో ఉంచితే, సంబంధం లేని ప్రతి task సమయంలో అది load అవుతుంది. దాంతో ఎలాంటి ప్రయోజనం ఉండదు. మీ root ఫైల్‌లో ఇప్పటికే ప్రతి service కోసం ప్రత్యేక section పెరిగి ఉంటే, దాన్ని nested layout గా విభజించడం సరైన పరిష్కారం. ఏ నియమాలు దిగువకు తరలాలి, ఏవి పై స్థాయిలో ఉండాలి అన్నదీ ఇది స్పష్టం చేస్తుంది.

AGENTS.md లో ఏమి ఉండాలి

కోడ్ చదివి agent స్వయంగా తెలుసుకోలేని విషయాలను రాయండి. Terminalలో paste చేసే రూపంలో ఖచ్చితమైన build, test, lint commands ముందుగా ఇవ్వండి. ఒకే test ను ఎలా అమలు చేయాలో కూడా command ఇవ్వండి. మొత్తం suite ను ఎలా అమలు చేయాలో మాత్రమే తెలిసిన agent, మొత్తం suite ను నలభై సార్లు అమలు చేస్తుంది. Tool default కు భిన్నంగా ఉన్న conventions ను పేర్కొనండి. Agent కు default ఇప్పటికే తెలుసు; మీరు అనుసరించే భిన్నమైన నియమాలను మాత్రమే తెలియజేయాలి. మీ వద్ద commit message format మరియు pull request rules ఉంటే వాటిని కూడా జోడించండి.

ఒక ప్రకటనను తనిఖీ చేయగలిగేంత స్పష్టంగా రాయండి. "2-space indentation ఉపయోగించండి" అనేది ఉపయోగకరమైన instruction, ఎందుకంటే అది పాటించబడిందా లేదా అనేది నిర్ధారించవచ్చు. "కోడ్‌ను సరిగ్గా format చేయండి" అనేది ఉపయోగకరం కాదు, ఎందుకంటే దాన్ని ఎలా verify చేయాలో అందులో లేదు. Locations విషయంలో కూడా ఇదే వర్తిస్తుంది: "API handlers src/api/handlers/ లో ఉంటాయి" అనేది "files ను క్రమబద్ధంగా ఉంచండి" కంటే మెరుగైనది.

ప్రతికూల నియమాలకు కూడా ఇక్కడ స్థానం ఉంది. "dist/ కింద ఉన్న files ను ఎప్పుడూ edit చేయకండి; వాటిని npm run build generate చేస్తుంది" అని రాస్తే ఒక నిర్దిష్ట తప్పును నివారించవచ్చు. కారణాన్ని కూడా పేర్కొన్నందున, మీరు రాయకపోయిన సమానమైన పరిస్థితిని agent స్వయంగా గుర్తించగలదు. Scope గురించి ఒక rule కూడా ఇక్కడ ఉండాలి. Agent ను తన నిర్ణయానికి వదిలేస్తే, మీరు అడిగిన దానికంటే ఎక్కువ మార్పులను అది చేస్తుంది: విస్తృతంగా copy చేయబడిన ఒక skill, పనిచేసే అతి చిన్న మార్పుపైనే పట్టుబట్టడం తప్ప మరేమీ చేయదు.

ఒకటిలో ఎప్పటికీ ఏమి ఉంచకూడదు

ఈ ఫైళ్లలో ఏదైనా secret ను ఎప్పుడూ ఉంచవద్దు. ఈ file git కు commit అవుతుంది, ప్రతి session ప్రారంభంలో context లోకి load అవుతుంది, అలాగే ప్రతి request లో model provider కు పంపబడుతుంది. AGENTS.md లో ఉన్న API key మీ repository history లోనూ, third party logs లోనూ ఉన్న API key అవుతుంది. Secret ను నేరుగా paste చేయకుండా, దాని స్థానాన్ని సూచించండి: “database password .env లో ఉంది; అది gitignored చేయబడింది; దాన్ని చదవడానికి ముందు అడగండి.” విస్తృతమైన విధానం credentials ను agent పరిధికి దూరంగా ఉంచడంలో వివరించబడింది.

Agent చూసి స్వయంగా తెలుసుకోగల విషయాలను చేర్చవద్దు. Paste చేసిన directory listing, మీ dependency list యొక్క copy, folder names ను మళ్లీ చెప్పే architecture overview—ఇవన్నీ రాసిన వారం తర్వాతే పాతబడతాయి; అప్పటివరకు ప్రతి session లో context ఖర్చవుతుంది. సమస్యలకు దారితీసే అంశాలను, వాటి కారణాలను మాత్రం ఉంచండి. 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లో మీరు ప్రారంభించే ప్రతి session ఒకే configuration stackను లోడ్ చేస్తుంది. అందువల్ల ఒకే machineపై రెండు 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 ను run చేసి, Memory files కింద CLAUDE.md కనిపిస్తుందో నిర్ధారించండి. ఆ జాబితాలో అది లేకపోతే, file ఎప్పుడూ load కాలేదు. అందువల్ల అందులోని ఏ నియమమూ వర్తించలేదు. మొదటి draftను స్వయంగా రాయడానికి బదులుగా రూపొందించాలనుకుంటే /init ను run చేయండి. ఇది codebaseను చదివి ప్రారంభ fileను రూపొందిస్తుంది. CLAUDE.md ఇప్పటికే ఉంటే, దాన్ని overwrite చేయకుండా మెరుగుదలలను సూచిస్తుంది.

ప్రతి fileను సుమారు 200 linesలోపు ఉంచండి. పొడవైన files context windowలో ఎక్కువ స్థలాన్ని వినియోగిస్తాయి. దాంతో నియమాల అనుసరణ తగ్గుతుంది. ఆ స్థలానికి మరేం పోటీ పడుతుందో చూడాలనుకుంటే, agent context windowను వాస్తవంగా నింపేవి ఏమిటో అందులో వివరించబడింది.

ఒక అంశాన్ని ప్రత్యేకంగా గుర్తుంచుకోవాలి. AGENTS.md అనేది guidance మాత్రమే; అది permission system కాదు. దాని content సాధారణ contextగా చేరుతుంది. అందువల్ల model దాన్ని చదివి సాధారణంగా పాటిస్తుంది. అయితే దానికి విరుద్ధమైన actionను ఏదీ నిరోధించదు. మీరు రాసిన rule నిశ్శబ్దంగా skip అయి, కారణం అర్థం కాకపోతే, wordingను మూడోసారి మార్చే ముందు ఒక instruction ఎందుకు drop అవుతుందో చెప్పే కారణాలను పరిశీలించండి. ప్రతి సారి తప్పనిసరిగా అమలులో ఉండాల్సిన rule కోసం, ఉదాహరణకు "never push to main", hook లేదా permission settingను ఉపయోగించండి. అవి codeగా నడుస్తాయి, కాబట్టి model పాటించాలని నిర్ణయించడంపై ఆధారపడవు.

మీ కోసం ఈ ఫైళ్లను రూపొందించే సాధనాలు

30 July 2026 నాటి GitHub trending జాబితాలోని రెండు ప్రాజెక్టులు ఈ convention ఏ దిశగా వెళ్తుందో చూపిస్తున్నాయి.

agent0ai/dox (July 2026 నాటికి 1,368 stars) అనేది AGENTS.md ఫైళ్ల tree ను ఎల్లప్పుడూ తాజాగా ఉంచే framework. ఇది package లేదా runtime ను అందించదు. దాని AGENTS.md లోని విషయాన్ని మీ స్వంత root AGENTS.md లోకి copy చేయాలి. అదే installation.

ఇప్పటికే ఉన్న project కోసం మీ agent కు ఇలా చెప్పండి:

Initialize DOX tree for this project now.

ఆ తరువాత agent child AGENTS.md ఫైళ్లు మరియు వాటి indexes ను సృష్టిస్తుంది. ఏదైనా edit చేయడానికి ముందు ఆ tree ను పరిశీలిస్తుంది. మార్పు అమలైన తర్వాత ప్రభావిత documentation ను update చేస్తుంది. దీని వెనుక ఉన్న భావన ఏమిటంటే, agent తన పనిలో భాగంగా నిర్వహించే documentation ఎల్లప్పుడూ సరైనదిగా ఉంటుంది. వ్యక్తి చేతితో update చేసే documentation అలా ఉండదు.

HUMAN.md, మీకు వర్తించే అదే విధానం

Intuition-Lab/personal-model (July 2026 నాటికి 1,260 stars) ఈ విధానాన్ని repository బదులుగా ఒక వ్యక్తికి వర్తింపజేస్తుంది. ఈ ప్రాజెక్ట్ మీ HUMAN.md ను మీరు టైప్ చేసే file గా కాకుండా, system output గా పరిగణిస్తుంది: “ప్రస్తుతం ముఖ్యమైనది ఏమిటి, మీరు సాధారణంగా ఎలా నిర్ణయాలు తీసుకుంటారు, మీ దృష్టి ఏ దిశగా కదులుతోంది అనే living model.” ఇది macOS 13 లేదా ఆ తర్వాతి versions పై locally నడుస్తుంది. మీరు macOS permission ఇచ్చిన తర్వాత activity ను capture చేస్తుంది. MCP (model context protocol) ద్వారా agents కు ఆ ఫలితాన్ని అందిస్తుంది. సంక్షిప్త install విధానం:

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

దాదాపు మొత్తం ప్రయోజనం పొందడానికి వీటిలో ఏదీ అవసరం లేదు. చేతితో రాసిన HUMAN.md సాధారణంగా ఇరవై lines ఉంటుంది: మీ role, మీ timezone, మీరు వాస్తవంగా ఉపయోగించే stack, ఇప్పటికే తీసుకున్న మరియు మళ్లీ చర్చించకూడదనుకునే decisions, అలాగే మీకు తిరిగి ఎంత explanation కావాలో అందులో రాయాలి. Project file పదేపదే వివరించాల్సిన అవసరాన్ని తగ్గించినట్లే, ఇది కూడా అదే పునరావృత వివరణను ఒక స్థాయి పైకి తగ్గిస్తుంది.

ఒక జాగ్రత్త. 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 లో రెండుసార్లు టైప్ చేయడం. ఈ ఒక్క నియమం ఫైల్‌ను ఉపయోగకరంగా ఉంచుతుంది. అలాగే ఈ ఫైల్‌ను ఎవరూ చదవని document గా, 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 చేయాలా?

అవును. ప్రాజెక్ట్‌కు సంబంధించిన build commands, layout, conventions వంటి అంశాలను commit చేయాలి. ఈ ఫైల్ ఉద్దేశం అదే. దాంతో మీ teammates యొక్క agents కూడా మీ agent ప్రారంభమయ్యే అదే contextతో ప్రారంభమవుతాయి. వ్యక్తిగతమైన లేదా ఒకే machineకు సంబంధించిన అంశాలను ప్రత్యేక gitignored ఫైల్లో ఉంచాలి. Credentials ను ఈ రెండింటిలోనూ ఉంచకూడదు.

HUMAN.md అంటే ఏమిటి? నాకు అది అవసరమా?

HUMAN.md అనేది projectకు బదులుగా ఒక వ్యక్తి యొక్క machine-readable profile. ఇందులో మీ role, మీ constraints, అలాగే మీరు ఇప్పటికే ఖరారు చేసిన decisions ఉంటాయి. దాంతో ప్రతి sessionలో వాటిని మళ్లీ పరిశీలించాల్సిన అవసరం ఉండదు. ప్రారంభించడానికి ప్రత్యేక tooling అవసరం లేదు. మీ user-level instructions fileలో మీరే రాసిన ఇరవై పంక్తులు కూడా ఎక్కువ ప్రయోజనాన్ని అందిస్తాయి. దీన్ని personal dataగా పరిగణించి, మీరు push చేసే ఏ repositoryలోనూ ఉంచకండి.