CLAUDE.md at AGENTS.md: ano ang mga ito, ano ang dapat isulat, at bakit binabalewala ng agent ang mga panuntunan

Ano ang CLAUDE.md at AGENTS.md

Ito ay mga ordinaryong Markdown file sa root ng repository na awtomatikong ikinakarga ng agent sa context sa simula ng session. Sa pamamagitan ng mga ito, sinasabi mo sa agent ang mga bagay na hindi nito mahuhulaan mula sa code: paano itayo ang kapaligiran, aling mga command ang gagamitin para suriin ang trabaho, aling mga panuntunan ng proyekto ang hindi pinagtatalunan, at nasaan ang detalyadong dokumentasyon.

CLAUDE.md ang file na binabasa ng Claude Code. Ang AGENTS.md ay bukas na format na may parehong ideya, at sinusuportahan ito ng maraming coding agent. Kung iba-iba ang agent ng iyong team, mainam na ilagay ang pangunahing nilalaman sa AGENTS.md at i-reference ito mula sa CLAUDE.md. Sinusuportahan ng Claude Code ang pag-import ng ibang file gamit ang linyang nagsisimula sa @:

# CLAUDE.md
@AGENTS.md

Sa ganitong paraan, nasa iisang lugar ang mga panuntunan at hindi nagkakaiba ang dalawang file.

Paano binabasa ng agent ang mga file na ito

Ang nilalaman ng file ng tagubilin ay inilalagay sa context window ng modelo kasama ng system prompt, at nananatili roon sa buong session. Tatlong mahalagang kahihinatnan nito ang lumalabas.

• Bawat linya ay umuubos ng espasyo sa context. Binabasa nang buo ang file sa bawat pagsisimula, kahit isang ikasampu lang ang kailangan para sa kasalukuyang gawain.
• Teksto ito, hindi executable na panuntunan. Isinasaalang-alang ito ng modelo kasabay ng iba pang context, at walang garantiyang susundin ito nang 100%. Ang mahigpit na pagbabawal ay kailangang suportahan ng mekanismo: verification, hook, at access rights.
• Maaaring i-nest ang mga file. Ikinakarga ng Claude Code ang CLAUDE.md mula sa root ng proyekto at mula sa user folder na ~/.claude/, habang ang mga file sa subfolder ay ikinakarga kapag gumagawa ang agent sa mga file sa mga folder na iyon. Kaya maaaring ilagay ang mga panuntunan ng isang module sa tabi mismo ng module.

Ano ang dapat isulat sa CLAUDE.md at AGENTS.md

Ang mabuting file ng tagubilin ay mapa, hindi textbook. Sinasagot nito ang mga tanong na itatanong ng agent sa isang bihasang kasamahan sa unang araw.

1. Paano itayo at suriin ang proyekto

Ito ang pinakamahalagang bahagi. Mga partikular na command na dapat patakbuhin ng agent bago sabihing «tapos na»: test, linter, type check, at pagbukas ng kapaligiran. Kung wala ang mga ito, sinusuri ng agent ang sarili nitong trabaho sa pamamagitan ng hula.

2. Mahigpit na limitasyon

Maikling listahan ng mga bagay na hindi dapat labagin sa anumang sitwasyon: mga invariant ng seguridad at datos. Isulat ang mga ito bilang invariant, hindi bilang tagubilin sa implementasyon: «lahat ng SQL query ay parameterized», at hindi «gamitin ang function na iyon sa file na iyon».

3. Mapa ng proyekto

Nasaan ang bawat bagay: ilang linya tungkol sa istruktura ng folder at kung saan hahanapin ang mga detalye. Para sa bawat malaking paksa, may link sa hiwalay na dokumento na bubuksan lang ng agent kapag gagawin nito ang paksang iyon.

4. Saan nakatira ang estado ng trabaho

Saan titingin para maipagpatuloy ang trabaho mula sa nakaraang session: plan file, progress log, backlog. Ito ang lunas sa «amnesia» ng agent sa pagitan ng mga session.

Ano ang hindi dapat isulat

• Mga bagay na matututunan ng agent mula sa code. Nasa package.json o pyproject.toml ang listahan ng dependency, at nasa code mismo ang istruktura ng mga class.
• Pangkalahatang payo. Ang «sumulat ng malinis na code» o «maging maingat» ay hindi nagbabago ng kilos at sumasakop lang ng espasyo.
• Kasaysayan ng proyekto at pansamantalang tala. Ang «noong Marso lumipat tayo mula MySQL 5.7» ay hindi nakakatulong sa kasalukuyang gawain.
• Detalyadong tagubilin para sa bihirang gawain. Ang proseso ng deploy o paglilipat ng datos na ginagawa minsan sa isang linggo ay dapat ilagay sa hiwalay na dokumento o skill.
• Mga lihim. Nasa repository ang file at buo itong ipinapasa sa modelo. Ilagay lang ang mga token at password sa environment variable.

Bakit binabalewala ng agent ang panuntunang nakasulat sa file

Karaniwang kuwento: nagkamali ang agent, may idinagdag na panuntunan sa file. Nagkamali ulit, may idinagdag pa. Makalipas ang ilang buwan, ilang daang linya na ang file, at binabalewala ng agent ang mahalagang panuntunan sa seguridad na parang wala ito. Karaniwang apat na dahilan ang nagkakasabay.

Namamagang file

Ang 600-linyang file ay humigit-kumulang 10–20 libong token. Mukhang malaki ang context window, pero kailangan itong pagsaluhan ng code, output ng command, at kasaysayan ng usapan. Kung mas maraming espasyo ang kinukuha ng mga tagubilin, mas kaunting atensyon ang bawat panuntunan at mas makitid ang espasyo para sa aktuwal na gawain.

Panuntunang nasa gitna

Mas mahina ang paggamit ng mga language model sa impormasyong nasa gitna ng mahabang teksto kaysa sa simula at dulo. Ang panuntunan sa linyang tatlong daan mula sa anim na raan ay nasa pinakamahinang bahagi.

Walang priyoridad

Ang hindi pinagtatalunang pagbabawal at ang maliit na tala tungkol sa estilo ay pareho ang anyo: isang linya sa listahan. Walang paraan ang agent para malaman kung alin ang mas mahalaga. Kung tatlong magkasalungat na panuntunan ng estilo ang nasa file, magiging random ang kilos sa bawat takbo.

Pagkabulok

Libre ang magdagdag ng panuntunan, pero nakakatakot tanggalin: «baka may nakasalalay dito». Kaya patuloy na lumalaki ang file, habang bumababa ang proporsyon ng mga kapaki-pakinabang na linya. Maaari itong sukatin bilang signal-to-noise ratio: ilang linya ang kailangan talaga para sa tipikal na gawain, at ilan ang hindi.

Paano ayusin: router sa halip na pader ng teksto

Walang saysay ang pag-aayos ng isang dahilan lang: kung paiikliin ang file pero walang estruktura, magkakahalo pa rin ang mga panuntunan. Kailangan ng kombinasyon ng mga hakbang.

1. Gawing router ang entry file. 50–150 linya: mga command sa verification, mahigpit na limitasyon, mapa ng proyekto, at mga link sa dokumento ayon sa paksa.
2. Ilabas ang mga paksa sa sarili nilang file. Halimbawa docs/agents/deploy.md, docs/agents/database.md. Binubuksan ito ng agent kapag kailangan. Sa Claude Code, mainam ang skills para sa mga paulit-ulit na proseso dahil nakakarga lang ang mga ito kapag kailangan.
3. Itaas ang mahalaga. Ilagay ang mahigpit na limitasyon sa itaas ng file, bilang maikling bloke na may malinaw na markang MUST.
4. Alisin ang mga salungatan. Isang panuntunan lang bawat paksa. Kung may eksepsiyon, isulat ito sa tabi ng panuntunan.
5. Suportahan ang panuntunan ng mekanismo. Kung hindi katanggap-tanggap ang paglabag, hindi sapat ang teksto lang. Kailangan ng pagsusuring makakahuli dito: linter, test, pre-commit hook, hook ng agent, o pagharang sa pamamagitan ng access rights.
6. Suriin nang regular. Magtakda ng limitasyon sa bilang ng linya, at sa bawat pagdaragdag, itanong kung ano ang maaaring tanggalin o ilipat.

Panuntunan o pagsusuri?

Halimbawa ng compact na AGENTS.md

# AGENTS.md — payment backend (FastAPI, PostgreSQL)

## MUST — huwag labagin
- Ang halaga ng pera ay int sa sentimo, hindi kailanman float
- SQL na parameterized lang, walang f-string
- Huwag galawin ang mga migration na naipatupad na, magdagdag lang ng bago
- Ang mga secret ay mula lang sa environment variable

## Suriin bago sabihing «tapos na»
docker compose up -d     # kapaligiran
make lint                # ruff + mypy
make test                # pytest
make e2e                 # senaryo ng checkout
Berde ang unit test pero walang e2e ay hindi pa «tapos».

## Mapa
- app/payments/   — pagkalkula ng halaga, discount, webhook ng provider
- app/api/        — mga HTTP endpoint
- tests/e2e/      — mga senaryo ng user
Detalye: docs/agents/architecture.md, docs/agents/database.md

## Estado ng trabaho
- PLAN.md      — kasalukuyang layunin, pamantayan ng pagtatapos, susunod na hakbang
- PROGRESS.md  — ano ang nagawa at paano sinuri, mga dead end
- BACKLOG.md   — mga napansin na «habang nandiyan»: isulat dito, huwag ayusin ngayon

Sa pagtatapos ng session, i-update ang PROGRESS.md at ang susunod na hakbang sa PLAN.md.

Pansinin ang wala rito: listahan ng mga library, payo sa estilo, kasaysayan ng proyekto. Alinman sa makikita ito sa code, o natitiyak ng mga pagsusuri, o nasa dokumento ayon sa paksa.

Amnesia sa pagitan ng mga session: file ng tagubilin kasama ang plan file

Inilalarawan ng file ng tagubilin kung paano magtrabaho sa proyekto, pero hindi nito sinasabi kung ano ang nangyayari ngayon. Kailangan para dito ng hiwalay na state file na binabasa ng agent sa simula at ina-update sa dulo ng session. Dito nakalagay ang layunin, ang mga nagawa kasama kung paano sinuri, ang mga desisyon kasama ang dahilan, ang mga opsyong tinanggihan, at isang pangungusap na susunod na hakbang. Simple ang pagsubok ng kalidad: buksan ang bagong session, i-type ang «ituloy mo», at tingnan kung magsisimula ang agent ng kapaki-pakinabang na gawain nang walang tanong.

Huwag paghaluin ang dalawang file. Bihira magbago ang mga tagubilin at naaapektuhan nito ang lahat ng gawain. Nagbabago ang plano sa bawat session at tungkol lang sa kasalukuyang gawain. Kapag pinaghalo, mabilis na lalaki ang file ng tagubilin sa mga lumang tala.

Paano malalaman kung gumagana ang file

Kailangan ding suriin ang file ng tagubilin. Pumili ng ilang tipikal na gawain, gaya ng bug fix, maliit na feature, at refactor, at tingnan kung ano ang ginagawa ng agent nang walang tulong: nagpapatakbo ba ito ng tamang command, binubuksan ba nito ang tamang dokumento ayon sa paksa, sinusunod ba nito ang mahigpit na limitasyon. Kung nilabag ang panuntunan, itanong muna sa sarili kung nakikita ba ito, may salungatan ba ito sa iba, at maaari bang palitan ng awtomatikong pagsusuri. Ang pagdaragdag ng bagong linya ay huling opsyon.

Buod

Ang CLAUDE.md at AGENTS.md ang pasukan ng agent sa proyekto. Gumagana ang mga ito kapag nanatili silang maikling mapa: mga command sa verification, mahigpit na limitasyon sa itaas, mga link sa detalye at sa plan file. Kapag binabalewala ang panuntunan, halos palaging namamagang file na walang istruktura ang dahilan, at ang tunay na mahahalagang panuntunan ay kailangang suportahan ng pagsusuri at hook. Kung paano ayusin ang mga tagubilin at estado ng agent ay tinatalakay nang praktikal sa kursong harness engineering.