AGENTS.md at HUMAN.md: Gabay para sa Coding Agent

Ano ang AGENTS.md

Ang AGENTS.md ay isang plain Markdown file sa root ng repository na nagsasabi sa coding agent kung paano gagana sa project na iyon. Inilalarawan ito ng official site bilang "README para sa mga agent: isang nakalaan at predictable na lugar para ilagay ang context at mga instruction na kailangan ng AI coding agent para gumana sa project." Pinangangasiwaan ng Agentic AI Foundation sa ilalim ng Linux Foundation ang format nito. Mahigit dalawampung agent ang bumabasa nito, kabilang ang Codex, Cursor, Jules, Devin, at GitHub Copilot (mula Hulyo 2026).

Praktikal ang dahilan kung bakit umiiral ang convention na ito. Babasahin ng bagong miyembro ng team ang README, huhulaan ang build command, at magtatanong kapag mali ang hula. Hindi makapagtatanong ang isang agent. Manghuhula ito, tatakbo ng npm test sa project na gumagamit ng pnpm test, babasahin ang failure, at susubukan ang iba. Binabayaran mo ang bawat isa sa mga token na iyon. Kapag isinulat nang isang beses ang aktuwal na command, maaalis ang buong uri ng failure na iyon.

Walang required na field. Malinaw ito sa site: "Ang AGENTS.md ay karaniwang Markdown lamang. Gumamit ng anumang heading na gusto mo; bina-parse lang ng agent ang text na ibinigay mo." Iyon ang buong specification. Wala sa format ang value nito. Nasa file ito, sa path na awtom nang tinitingnan ng bawat tool.

Kung saan inilalagay ang file at kung alin ang mananaig

Ilagay ang unang file sa root ng repository. Sa isang monorepo, maaari kang magdagdag ng higit pang file sa loob ng bawat subproject. Simple ang panuntunan: “Awtomatikong binabasa ng mga agent ang pinakamalapit na file sa directory tree, kaya mananaig ang pinakamalapit na file.” Kapag may conflict sa pagitan ng dalawang file, ang file na ine-edit ang mananaig. Ang anumang ita-type mo sa chat ay mananaig sa dalawang ito.

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

Kapaki-pakinabang ang nesting dahil ito lamang ang paraan para magsabi ng panuntunang totoo sa isang folder ngunit hindi totoo sa kasunod na folder. Ang panuntunang “vina-validate ng bawat endpoint ang input nito” ay dapat ilagay katabi ng mga endpoint. Kung nasa root file ito, nilo-load ito sa bawat hindi kaugnay na task at walang naidudulot na pakinabang. Kung mayroon nang isang section para sa bawat service ang root file mo, ang paghahati nito sa nested layout ang tamang ayos. Sinasaklaw nito kung aling mga panuntunan ang ililipat sa mas mababang level at kung alin ang mananatili sa itaas.

Ano ang dapat ilagay sa AGENTS.md

Isulat ang mga bagay na hindi matutukoy ng agent sa pagbasa lamang ng code. Unahin ang eksaktong mga command para sa build, test, at lint, sa anyong maaari mong i-paste sa terminal. Idagdag ang command para magpatakbo ng isang test, dahil ang agent na alam lamang kung paano patakbuhin ang buong suite ay patatakbuhin ang buong suite nang apatnapung beses. Banggitin ang mga convention na naiiba sa default ng tool, dahil alam na ng agent ang default at kailangan lamang nitong malaman ang iyong deviation. Idagdag ang format ng commit message at ang mga panuntunan sa pull request kung mayroon ka ng mga ito.

Magbigay ng sapat na tiyak na detalye upang masuri ang bawat pahayag. Magagamit na instruction ang “Gumamit ng 2-space indentation” dahil malinaw kung nagawa ito o hindi. Hindi magagamit ang “I-format nang maayos ang code” dahil walang partikular na bagay na maaaring i-verify rito. Ganito rin sa mga lokasyon: mas mabuti ang “Nasa src/api/handlers/ ang mga API handler” kaysa sa “Panatilihing organisado ang mga file.”

Mahalaga rin ang mga negatibong panuntunan. Pinipigilan ng “Huwag kailanman i-edit ang mga file sa ilalim ng dist/; generated ang mga ito ng npm run build” ang isang partikular na pagkakamali. Dahil binabanggit nito ang sanhi, matutukoy ng agent ang katumbas na sitwasyong hindi mo tahasang isinulat. Dapat ding ilagay dito ang panuntunan tungkol sa scope, dahil kung sariling pagpapasya ng agent ang gagamitin, mas marami itong babaguhin kaysa sa hiniling mo: may isang malawak na kinopyang skill na ang tanging layunin ay igiit ang pinakamaliit na pagbabagong gumagana.

Ano ang hindi dapat ilagay sa isa sa mga ito

Huwag kailanman maglagay ng secret sa alinman sa mga file na ito. Nako-commit ang file sa git, nilo-load sa context sa simula ng bawat session, at ipinapadala sa model provider sa bawat request. Ang API key sa AGENTS.md ay API key na nasa repository history mo at nasa logs ng third party. Ituro ang lokasyon ng secret sa halip na i-paste ito: “nasa .env ang database password at naka-gitignore ito; magtanong muna bago basahin.” Sinasaklaw ng pag-iwas na maabot ng agent ang credentials ang mas malawak na disiplinang ito.

Iwanan ang anumang kayang malaman ng agent sa pamamagitan ng pagtingin. Nagiging stale agad ang naka-paste na directory listing, kopya ng dependency list, o architecture overview na inuulit lamang ang mga pangalan ng folder isang linggo matapos itong isulat. Kumokonsumo rin ang mga ito ng context sa bawat session habang naroon pa. Panatilihin ang mga pitfall at dahilan. Alisin ang inventory. Mahalagang paghiwalayin ang mga dahilan, dahil kapag hindi makita ng agent kung bakit ganoon ang hindi pangkaraniwang structure, tahimik nitong ire-refactor iyon. Ito ang dahilan kung bakit dapat panatilihin ang isang DESIGN.md sa tabi nito.

Ang CLAUDE.md ang Claude Code na katumbas ng parehong ideya

Binabasa ng Claude Code ang CLAUDE.md at hindi nito awtomatikong binabasa ang AGENTS.md. Ang file ng proyekto ay nasa ./CLAUDE.md o ./.claude/CLAUDE.md, ang mga personal preference para sa bawat proyekto ay inilalagay sa ~/.claude/CLAUDE.md, at maaaring maglagay ang isang organisasyon ng file na saklaw ang buong machine sa /etc/claude-code/CLAUDE.md sa Linux. Pinagsasama ang mga natuklasang file mula sa root ng filesystem pababa sa working directory, kaya huling binabasa ang file na pinakamalapit sa lugar kung saan mo inilunsad ang session. Pare-parehong nilo-load ng bawat session na sinisimulan mo sa directory na iyon ang parehong stack. Dahil dito, praktikal na magpatakbo ng dalawang session nang sabay sa isang machine, at maaaring magpasa ng trabaho ang mga session na iyon sa isa't isa habang tumatakbo ang mga ito.

Kung mayroon nang AGENTS.md ang repository mo, huwag magpanatili ng pangalawang kopya. I-import ito, saka idagdag lamang ang partikular sa Claude:

@AGENTS.md

## Claude Code

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

Gumagana ang symlink kung wala ka nang ibang idaragdag:

ln -s AGENTS.md CLAUDE.md

Walang inilalabas na text ang command kapag matagumpay. Sa susunod mong session, patakbuhin ang /context at tiyaking lumilitaw ang CLAUDE.md sa ilalim ng Memory files. Kung wala ito sa listahang iyon, hindi na-load ang file kaya walang nilalaman nito ang nailapat. Para bumuo ng unang draft sa halip na manu-manong magsulat, patakbuhin ang /init: binabasa nito ang codebase at gumagawa ng panimulang file. Kapag mayroon nang CLAUDE.md, nagmumungkahi ito ng mga pagpapahusay sa halip na i-overwrite ito.

Panatilihin ang bawat file sa humigit-kumulang 200 linya o mas maikli. Mas malaking bahagi ng window ang ginagamit ng mahahabang file, at bumababa ang pagsunod sa mga instruction. Kung gusto mong makita kung ano pa ang kumokonsumo sa espasyong iyon, inilalahad ito ng kung ano talaga ang pumupuno sa context window ng agent.

Mahalagang bigyang-diin ang isang punto. Ang AGENTS.md ay gabay, hindi permission system. Dumarating ang nilalaman bilang ordinaryong context, kaya binabasa ito ng model at karaniwan itong sinusunod. Ngunit walang pumipigil sa isang action na sumasalungat dito. Kapag tahimik na nalalaktawan ang isang rule na isinulat mo at hindi mo matukoy kung bakit, suriin muna ang mga dahilan kung bakit nalalagpasan ang isang instruction bago mo muling baguhin ang pagkakasulat nito. Para sa rule na dapat sundin sa bawat pagkakataon, gaya ng "never push to main", gumamit ng hook o permission setting. Tumatakbo ang mga ito bilang code at hindi nakadepende sa pagpapasyang sumunod ng model.

Mga tool na gumagawa ng mga file na ito para sa iyo

Ipinapakita ng dalawang proyekto sa GitHub trending list noong 30 July 2026 kung saan patungo ang convention.

Ang agent0ai/dox (1,368 stars noong July 2026) ay isang framework para panatilihing napapanahon ang tree ng mga AGENTS.md file. Wala itong ini-install na package o runtime. Kokopyahin mo ang laman ng AGENTS.md nito sa sarili mong root AGENTS.md, at iyon na ang installation. Para sa isang umiiral nang project, sabihin sa iyong agent:

Initialize DOX tree for this project now.

Pagkatapos, ginagawa ng agent ang mga child AGENTS.md file at ang mga index ng mga ito, binabasa ang tree bago ito mag-edit ng anuman, at ina-update ang mga apektadong documentation kapag nailapat na ang isang pagbabago. Ang batayan ng approach na ito ay nananatiling tama ang documentation na ina-update ng agent bilang bahagi ng trabaho nito, samantalang hindi ganoon ang documentation na mano-manong ina-update ng tao.

HUMAN.md, ang parehong technique na itinuro sa iyo

Ang Intuition-Lab/personal-model (1,260 stars noong July 2026) ay naglalapat ng pattern sa isang tao sa halip na sa isang repository. Itinuturing ng project na output ng system ang iyong HUMAN.md, hindi isang file na mano-mano mong tina-type: “isang buhay na modelo ng kung ano ang mahalaga ngayon, kung paano ka karaniwang nagpapasya, at kung saan napupunta ang iyong atensyon.” Lokal itong tumatakbo sa macOS 13 o mas bago, kumukuha ng activity matapos mong magbigay ng macOS permission, at inilalantad ang resulta sa mga agent sa pamamagitan ng MCP (model context protocol). Ang maikling install path:

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

Hindi mo kailangan ang alinman dito para makuha ang karamihan ng benepisyo. Humigit-kumulang dalawampung linya ang isang mano-manong isinulat na HUMAN.md: ang iyong role, timezone, aktuwal na ginagamit mong stack, mga desisyong nagawa mo na at ayaw mong muling buksan, at kung gaano karaming paliwanag ang gusto mong matanggap. Naiiwasan nito ang parehong paulit-ulit na pagpapaliwanag na naiwasan ng project file, pero nasa mas mataas na layer.

Isang paalala. Profile ng isang tao ang HUMAN.md, kaya sensitibo ito ayon sa likas na katangian nito. Huwag itong ilagay sa public repository. Ilagay ito sa ~/.claude/CLAUDE.md, o sa isang gitignored na CLAUDE.local.md sa project root. Nilo-load ito kasabay ng committed file at tinatrato sa parehong paraan.

Isang panimulang template na maaari mong kopyahin

Sadyang maikli ito. Burahin ang mga seksyong hindi naaangkop, at iwasang magdagdag ng mga seksyong hindi mo mapapanatiling napapanahon.

# 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.

Isulat ito, pagkatapos ay itama mismo sa file. Ang palatandaan na kailangan mong magdagdag ng linya ay kapag dalawang beses mong nai-type sa chat ang parehong correction. Pinananatiling kapaki-pakinabang ng isang panuntunang ito ang file, at pinipigilan nitong lumaki ang file bilang dokumentong walang nagbabasa, pati ang mga machine. Kapag stable na ito, kasama na ito ng repository. Mahalaga ito lalo na kapag tumatakbo ang agent sa ibang lugar kaysa sa laptop mo: pagpapatakbo ng coding agent sa sarili mong server ang tumatalakay sa setup na iyon.

FAQ

Pareho ba ang AGENTS.md at CLAUDE.md?

Pareho ang konsepto ng mga ito, ngunit magkaiba ang filename. Binabasa ng Claude Code ang CLAUDE.md at binabalewala ang AGENTS.md maliban kung pagdudugtungin mo ang mga ito. Panatilihing iisang file ang source of truth at i-link dito ang isa pa, alinman sa pamamagitan ng linyang @AGENTS.md sa itaas ng iyong CLAUDE.md o sa pamamagitan ng ln -s AGENTS.md CLAUDE.md. Hindi magtatagal at magkakaiba ang dalawang magkahiwalay na kopya na mano-manong pinapanatili.

Garantiya ba na susundin ng agent ang AGENTS.md kapag isinulat ito?

Hindi. Ipinapasa ang content bilang context, kaya binabasa ito ng model at karaniwan itong sinusunod. Gayunman, walang humahadlang sa isang action na sumasalungat dito. Hindi gaanong maaasahan ang pagsunod sa malalabong instruction. Kapag may dalawang file na nagbibigay ng magkasalungat na gabay, maaaring pumili ang agent ng isa nang walang tiyak na batayan. Para sa rule na dapat laging ipatupad, gumamit ng hook o permission rule. Ipinapatupad ito ng client anuman ang desisyon ng model.

Dapat bang i-commit sa git ang AGENTS.md?

Oo, para sa anumang impormasyong totoo tungkol sa project, gaya ng build command, layout, at convention. Iyan ang layunin ng file, dahil magsisimula ang mga agent ng iyong mga teammate gamit ang parehong context na ginagamit ng iyo. Ang anumang personal o partikular sa isang machine ay dapat nasa hiwalay na gitignored file. Ang credentials ay hindi dapat ilagay sa alinman sa mga ito.

Ano ang HUMAN.md at kailangan ko ba nito?

Ang HUMAN.md ay machine-readable profile ng isang tao, hindi ng isang project. Nilalaman nito ang iyong role, mga constraint, at mga desisyong napagkasunduan mo na upang hindi na muling buksan sa bawat session. Hindi mo kailangan ng tooling para magsimula. Karamihan sa pakinabang nito ay makukuha na sa dalawampung linyang ikaw mismo ang sumulat sa user-level instructions file. Ituring itong personal data at huwag itong isama sa anumang repository na iyong ipinapadala.