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

Ano ang AGENTS.md

Ang AGENTS.md ay isang plain markdown file sa root ng isang repository na nagsasabi sa isang coding agent kung paano gagawin ang trabaho sa project na iyon. Inilalarawan ito ng official site bilang “isang README para sa mga agent: isang nakalaan at predictable na lugar para ibigay ang context at mga instruction na makatutulong sa mga AI coding agent na magtrabaho sa project mo.” Pinangangasiwaan ang format ng Agentic AI Foundation sa ilalim ng Linux Foundation, at mahigit dalawampung agent ang nagbabasa nito, kabilang ang Codex, Cursor, Jules, Devin at GitHub Copilot (noong July 2026).

Praktikal ang dahilan kung bakit umiiral ang convention na ito. Binabasa ng bagong miyembro ng team ang README, hinuhulaan ang build command, at nagtatanong sa iba kapag mali ang hula. Hindi makapagtanong ang isang agent. Hinuhulaan nito ang command, pinapatakbo ang npm test sa project na gumagamit ng pnpm test, binabasa ang failure, at sumusubok ng ibang command. May bayad ang bawat token na ginagamit sa mga hakbang na iyon. Kapag isinulat nang isang beses ang tamang command, nawawala ang buong kategoryang ito ng failure.

Walang required na field. Malinaw ito sa site: “Ang AGENTS.md ay standard Markdown lamang. Gumamit ng anumang heading na gusto mo; bina-parse lamang ng agent ang text na ibinibigay mo.” Iyon ang buong specification. Hindi nasa format ang halaga nito. Nasa file ito na matatagpuan sa path na awtomatikong tinitingnan ng bawat tool.

Saan inilalagay ang file at kung aling file ang mananaig

Ilagay ang unang file sa root ng repository. Sa isang monorepo, maaari kang magdagdag ng higit pa sa loob ng bawat subproject. Simple ang panuntunan: “awtomatikong binabasa ng agents ang pinakamalapit na file sa directory tree, kaya mananaig ang pinakamalapit na file.” Kapag may conflict sa pagitan ng dalawang file, mananaig ang file na ine-edit. 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

Makabuluhang gamitin ang nesting dahil ito lamang ang paraan para magsabi ng patakarang totoo sa isang folder ngunit hindi sa kasunod na folder. Ang patakarang tulad ng “bine-validate ng bawat endpoint ang input nito” ay dapat ilagay sa tabi ng mga endpoint. Kapag nasa root file ito, nilo-load ito sa bawat hindi kaugnay na task at wala itong naidudulot.

Ano ang dapat ilagay sa AGENTS.md

Isulat ang mga bagay na hindi matutukoy ng isang 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 ang alam lamang ay kung paano patakbuhin ang buong suite ay patatakbuhin ang buong suite nang apatnapung beses. Tukuyin ang mga convention na naiiba sa default ng tool, dahil alam na ng agent ang default at kailangan lamang nitong malaman ang iyong paglihis dito. Idagdag ang format ng commit message at ang mga panuntunan sa pull request kung mayroon ka ng mga ito.

Magbigay ng sapat na konkretong detalye para masuri ang bawat pahayag. Ang “Gumamit ng 2-space indentation” ay magagamit na instruction dahil malinaw kung nangyari ito o hindi. Ang “I-format nang maayos ang code” ay hindi sapat dahil walang mapapatunayang partikular na kundisyon dito. Ganoon din sa mga lokasyon: mas mainam 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 tinutukoy nito ang sanhi, matutukoy ng agent ang katumbas na mga sitwasyong hindi mo tahasang isinulat.

Mga bagay na hindi dapat ilagay sa mga file na ito

Huwag kailanman maglagay ng secret sa alinman sa mga file na ito. Naka-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 history ng repository mo at sa mga log ng third party. Ituro ang lokasyon ng secret sa halip na i-paste ito: “ang database password ay nasa .env, na naka-gitignore; magtanong muna bago ito basahin.” Saklaw ng pag-iwas na mapasakamay ng agent ang mga credential ang mas malawak na disiplinang ito.

Huwag isama ang anumang kayang malaman ng agent sa pamamagitan ng pagtingin. Ang directory listing na naka-paste, kopya ng dependency list, o architecture overview na inuulit lang ang mga pangalan ng folder—lahat ng ito ay naluluma isang linggo matapos isulat, at kumakain ng context sa bawat session habang naroon pa. Panatilihin ang mga pitfall at ang mga dahilan. Alisin ang inventory.

Ang CLAUDE.md ang Claude Code na bersiyon 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 na preference para sa bawat proyekto ay nasa ~/.claude/CLAUDE.md, at maaaring maglagay ang isang organisasyon ng file na para sa buong machine sa /etc/claude-code/CLAUDE.md sa Linux. Pinagsasama ang mga natukoy na file mula sa root ng filesystem pababa sa working directory, kaya huling binabasa ang file na pinakamalapit sa lokasyon kung saan mo inilunsad ang session.

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

@AGENTS.md

## Claude Code

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

Gumagana ang isang symlink kung wala kang kailangang idagdag:

ln -s AGENTS.md CLAUDE.md

Walang inilalabas 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 magsulat ng isa, 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 patungan ito.

Panatilihin ang bawat file sa humigit-kumulang 200 linya o mas kaunti. Mas maraming bahagi ng window ang ginagamit ng mas mahahabang file, kaya bumababa ang pagsunod. Kung gusto mong makita kung ano pa ang gumagamit 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 sistema ng pahintulot. Dumarating ang nilalaman bilang ordinaryong context, kaya binabasa ito ng model at karaniwan itong sinusunod, ngunit walang pumipigil sa isang aksiyong sumasalungat dito. Para sa panuntunang dapat sundin sa bawat pagkakataon, gaya ng "huwag kailanman mag-push sa main", gumamit ng hook o permission setting dahil tumatakbo ang mga ito bilang code at hindi nakadepende sa pagpapasyang sumunod ng model.

Mga tool na nagsusulat ng mga file para sa iyo

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

agent0ai/dox (1,368 stars noong July 2026) ay isang framework para panatilihing napapanahon ang isang tree ng mga AGENTS.md file. Wala itong package o runtime na ipinapadala. Kokopyahin mo ang laman ng AGENTS.md nito sa sarili mong root AGENTS.md, at iyon na ang installation. Para sa isang dati nang project, sasabihin mo 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, sinusuri ang tree na iyon bago mag-edit ng anuman, at ina-update ang apektadong documentation kapag nailapat na ang pagbabago. Ang batayan nito ay mananatiling tama ang documentation na ina-update ng agent bilang side effect ng trabaho nito, samantalang hindi mananatiling tama ang documentation na manu-manong ina-update ng tao.

HUMAN.md, ang parehong paraan na nakatuon sa iyo

Iniaangkop ng Intuition-Lab/personal-model (1,260 stars noong Hulyo 2026) ang pattern sa isang tao sa halip na sa isang repository. Itinuturing ng proyekto ang iyong HUMAN.md bilang output ng system sa halip na file na tina-type mo: “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 pagkatapos mong magbigay ng permission sa macOS, at inilalantad ang resulta sa mga agent gamit ang MCP (model context protocol). Ang maikling installation path:

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

Hindi mo kailangan ang alinman sa mga iyon para makuha ang karamihan ng pakinabang. Ang isang isinusulat-kamay na HUMAN.md ay humigit-kumulang dalawampung linya: ang iyong tungkulin, timezone, stack na aktuwal mong ginagamit, mga desisyong nagawa mo na at ayaw mong muling buksan, at kung gaano karaming paliwanag ang gusto mong matanggap. Nakatitipid ito sa parehong paulit-ulit na pagpapaliwanag na naiwasan ng isang project file, ngunit nasa mas mataas na antas.

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

Isang panimulang template na maaari mong kopyahin

Sinadya itong gawing maikli. Tanggalin 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 ito sa mismong lugar. Ang senyas na kailangan mong magdagdag ng linya ay kapag dalawang beses mong nai-type sa chat ang parehong pagwawasto. Pinananatiling kapaki-pakinabang ng iisang panuntunang iyon ang file, at pinipigilan nitong lumaki ang file bilang dokumentong walang nagbabasa, kabilang ang mga machine. Kapag stable na ito, kasama itong napupunta sa repository. Pinakamahalaga ito kapag tumatakbo ang agent sa ibang lugar kaysa sa laptop mo: saklaw ng pagpapatakbo ng coding agent sa sarili mong server ang setup na iyon.

FAQ

Pareho ba ang AGENTS.md at CLAUDE.md?

Pareho ang ideya ng mga ito ngunit magkaiba ang filename. Binabasa ng Claude Code ang CLAUDE.md at hindi pinapansin ang AGENTS.md maliban kung pag-uugnayin mo ang mga ito. Panatilihin ang isang file bilang pinagmumulan ng katotohanan at i-link ang isa rito, alinman sa pamamagitan ng linyang @AGENTS.md sa itaas ng iyong CLAUDE.md o sa pamamagitan ng ln -s AGENTS.md CLAUDE.md. Magkakaroon ng hindi pagkakatugma ang dalawang magkahiwalay na kumpletong kopya sa loob ng isang buwan.

Tinitiyak ba ng pagsulat ng AGENTS.md na susundin ito ng agent?

Hindi. Ipinapasa ang nilalaman bilang context, kaya binabasa ito ng model at karaniwan itong sinusunod. Gayunman, walang pumipigil sa isang action na sumasalungat dito. Pinakamadalas na hindi nasusunod nang maaasahan ang malalabong instruction, at kapag magkasalungat ang gabay sa dalawang file, 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 ang mga ito ng client anuman ang pasya ng model.

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

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

Ano ang HUMAN.md at kailangan ko ba nito?

Ang HUMAN.md ay isang 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 ang mga ito sa bawat session. Hindi mo kailangan ng tooling para magsimula: nagbibigay na ng malaking bahagi ng pakinabang ang dalawampung linyang isinulat mo mismo sa iyong user-level instructions file. Ituring ito bilang personal data at huwag itong isama sa anumang repository na iyong ipinapadala.