Sarrera Agentic Coding-arekin IA
Inteligentzia Artifiziala (IA) software garapena ulertzeko modua aldatu du. Sistema bati kode lerro bat osatzeko eskatzea ez da nahikoa: gaur egun, helburuak ulertzen dituzten, konbentzioak jarraitzen dituzten, dokumentazioa bizirik mantentzen duten eta gurekin taldeko kide gisa elkarlanean aritzen diren agenteekin lan egin dezakegu. Hurbilpen hau “Agentic Coding” deitzen diogu. Gida honek, zabala eta praktikoa, ideia batetik profesionaltasun fluxora nola igaro azaltzen du, non IA zure eguneroko garatzaile gisa integratzen den, WordPress-i eta zure proiektuekin errepikatu ahal izango duzun prozesu errealean zentratuz.
Batetik, IA modernoaren ulertzeko beharrezko kontzeptu oinarriak aurkituko dituzu eta LLM (Large Language Models) rolari buruzko informazioa. Bestetik, prozesua artikulatzen duten gako fitxategiekin lan egiteko modua ikusi ahal izango duzu: AGENTS.md (arauak eta irismena), TODO.md (agentearen taula) eta Documents.md (bizirik dagoen dokumentazioa). Gainera, praktika onak, benetako murrizketak eta proiektuaren eskeleto gisa funtzionatuko duen adibide praktiko bat barne hartzen dugu, geroago zure inplementazio agentearekin elkarlanean teknika konkretuak (kodea, egiturak, etab.) txertatzeko espazioak argi markatuta.
1. Sarrera
1.1. Zer da Inteligentzia Artifiziala (IA) garapenean?
IA zereginak burutzea bilatzen duen diziplina zabala da, inteligentzia humanoarekin lotzen ditugun zereginak burutzen dituzten makinen bidez: hizkuntza natural ulertzea, deskribapenetatik arrazoitzea, datuetatik ikastea edo ekintzak planifikatzea. Aurrerapen hamarkada batzuen ondoren, azken salto kualitatiboa Large Language Models (LLM) etorri da. Modelo hauek testu masiboekin entrenatzen dira, hizkuntzaren patroiak ikasten dituzte eta testuinguru jakin batekin koherentea den kodea sortzeko gaitasuna lortzen dute.
Garapen arloan, hau esan nahi du ez garela jada tokenak iradokitzen dituzten tresnen menpe. Helburu altu-mailakoak deskribatu ditzakegu, estilo estandarrak ezarri, dokumentazio koherentea eskatzen eta zereginak koordinatzen. Balioa ez dago “autocompleting”-en, baizik eta egitura tekniko bat denbora luzean mantentzen laguntzen duen agente batekin lan egitean.
1.2. Laguntzaile puntualetatik agenteetara
Programatzaileen lehen kontaktua IA-rekin laguntzaile puntualen bidez etorri zen: IDE-n iradokizun motorra, galderak erantzuteko gai diren chatbotak edo funtzio solteak sortzeko gai direnak. Erabilgarriak, bai, baina murriztuta, asteetan edo hilabeteetan koherentzia duten sistemak eraikitzeko nahi badugu. Aldiz, Agentic Coding hurbilpenak prozesuak jarraitzen dituzten modeloen gaitasuna aprobetxatzen du, memoria operatiboa mantentzen du (fitxategien eta konbentzioen bidez) eta atzerako lanen artean planifikatuta mugitzen da. Hau da, laguntza erreaktibo batetik kolaborazio proaktibo batera pasatzen gara, proiektu artefaktuak gidatuta.
1.3. Zergatik ez da IA “soilako chatbotak”?
“Galderak erantzuten dituen chatbotaren” irudia laburra da. Garapenerako, IA modernoak:
- Kodea sortu eta refaktoreatu arkitektura patroiak, izendapen konbentzioak eta estandarrak (PHPCS, ESLint, etab.) jarraituz.
- Proba diseinatu eta inplementatu (unitarioak eta integrazioak) eta kasu mugak proposatu.
- Dokumentazioa idatzi eta mantendu teknikoa eta erabiltzailea garatzen ari den bitartean, ez amaieran.
- Tareas errepikakorrak automatizatu integrazioan, APIen migrazioan, itzulpenetan eta kodean iruzkinak.
- Hautaketa teknikoak aztertu argudioak erabiliz (errendimendua, segurtasuna, mantentzea).
1.4. Agentic Coding-en definizio operatiboa
Agentic Coding izendatuko dugu lan fluxu bat, non garatzaile humanoak arauak, helburuak eta estandarrak definitzen dituen, eta agente batek (adibidez, Codex) marko horretan funtzionatzen du zereginak burutzeko, azpizereginak proposatzeko, Pull Request-ak irekitzen, lan taula bizia mantentzen eta eraikitakoa dokumentatzen. Zure rola aldatzen da: kodea idaztetik sistemaren gidaritza izatera pasatzen zara, onartze irizpideak zehazten, PR-ak berrikusten eta blokeoak edo anbiguotasunak konpontzen laguntzaide baten laguntzarekin (adibidez, ChatGPT prozesuaren diseinua finetzeko edo AGENTS.md bezalako artefaktuak idazteko).
2. IA-rekin garatzaileentzako lan ekosistema
2.1. Hodeia, lokal eta hibridoa
Modeloak kontsumitzeko hiru modu nagusi daude:
- Hodeia (OpenAI, Anthropic, Google): erabilerraztasuna, automatikoki eskalatzea, atzerapen arrazoizkoa eta azken belaunaldiko modeloak CLI bidez lokalera nahi izanez gero. Desabantailak: kostu aldakorra eta datuen politikak. OpenAI-ren Codex bezalako modeloen erabilera posible da, finkatutako kostu bat duena, kontratatzen duzunaren arabera, Plus ($20/hilabete) nahikoa izaten da. Hemen Codex-i buruz hitz egingo dut.
- Lokal (Llama.cpp, Ollama, vLLM): kontrola eta pribatutasuna, hirugarrenekiko menpekotasun minimoa eta erabilera kostuak oso baxuak. Desabantailak: GPU/CPU indartsuak behar dituzu eta modeloen mantentzea.
- Hibrido: ekoizpen hodeiak eta esperimentazio, proba barneko edo datu sentikorretarako lokaleko modeloak. Normalean, praktika orekatuena izaten da.
2.2. Hautatzeko irizpideak
Zure erabakia honen araberakoa izango da:
- Pribatutasuna: datu sentikorren tratamendua? Lokal edo hibridoak lehentasunezkoak izan daitezke, nahiz eta teoriatik orain hodeian pribatutasuna bermatzen den, hala konfiguratzen baduzu.
- Kostua: proiektua erabileran haziko al da? Hodeian token bakoitzeko kostua igotzen da; lokalekoak azpiegitura ordaindu behar duzu.
- Abiarazteko abiadura: hodeiak irabazten du, gaur egun hastea nahi baduzu frikzio minimoarekin.
- Funtzionamendua eta mantentzea: lokalak DevOps gehiago eskatzen du; hodeiak konplexutasuna kanporatzen du.
2.3. Osagarriak
- Erregistroa: GitHub/GitLab/Bitbucket PR, arazo, berrikusketa.
- Editorea: VSCode, estandarrentzako luzapenekin (PHPCS, ESLint), formatzaileekin (Prettier), eta laguntzaileekin.
- CI/CD: proba automatikoak, linters eta kontrolatutako despliegua.
- Tasak kudeatzea: nahiz eta TODO.md agentearen bidez mantenduko den, erabilgarria da auditoretzarako etiketatutako arazoekin seinaleak integratzea.
3. Lan fluxuaren oinarria prestatzen
3.1. Sistema artikulatzen duen hirukotea
Hurbilpen honetan, zure prozesua hiru sinkronizatutako artefaktutan oinarritzen da:
- AGENTS.md: joko arauak. Helburua, irismena, estandarrak, egitura, konbentzioak, segurtasun irizpideak, kalitate irizpideak eta dokumentazio itxaropenak definitzen ditu. AGENTS.md-ri buruzko informazio gehiago nahi baduzu, hemen lor dezakezu.
- TODO.md: zeregin bizia. Agentearen bidez sortzen eta mantentzen da. Bertan, zer egingo duen, zer dagoen prozesuan eta zer amaitutzat jotzen den ikusten da. Era berean, agertzen diren zeregin berriak gehitzen ditu.
- Documents.md: dagoeneko eraikitakoaren bizirik dagoen dokumentazioa: API publikoa, funtzioak, klaseak, hooks, datu eskemak, fluxuak eta erabilera errezetak. Agentearen bidez mantentzen da aurrera doan heinean.
3.2. Rol argiak
- Zu: arkitektoa eta kalitate arduraduna. AGENTS.md-n arauak eta helburuak ezartzen dituzu, PR-ak berrikusten dituzu, anbiguotasunak argitzen dituzu, zuzenketak eta zeregin berriak eskatzen dituzu, hutsuneak aurkitzen badituzu.
- Inplementazio agentea (Codex): exekutatzen du, TODO.md-n operatiboa zehazten du, PR incrementalak egiten ditu eta Documents.md-n dokumentazioa erregistratzen du.
- Ideen laguntzailea (ChatGPT): AGENTS.md finetzeko, alternatibak arrazoitzeko, onartze irizpideak idazteko eta kodea berrikusteko laguntzen dizu, behar denean.
3.3. Iterazio diziplinatua
Arrakasta ez da “kode asko sortzen duen IA”-ren menpe, baizik eta iterazio diziplinatu batean: planifikatu (zu), exekutatu (agentea), berrikusi (zu), dokumentatu (agentea) eta berriro planifikatu. Pauso bakoitza txikiagoa eta egiaztagarria den heinean, sistema hobeago erantzuten du, teknika zorra murrizten da eta lana auditatzeko erraza da.
4. AGENTS.md: proiektuaren kontratua eta editorial lerroa
4.1. AGENTS.md-ren funtzio estrategikoa
AGENTS.md proiektuaren konpasua da. Hemen asmoa, irismena eta murrizketak ezartzen dituzu. Gainera, kodearen editorial lerroa ezartzen duzu: estiloa, izenak, egitura, segurtasuna eta dokumentazioa. Agentearen irudikapenak zure estandarren kanpoan inprobisatu ez dezan saihesteko dokumentua da. Pentsatu horretan “Guide for contributors” IA kolaboratzaile batentzat egokituta.
4.2. Eduki gomendatua
- Helburua eta irismena: zein arazo konpontzen duzun, zer ez den egingo proiektuak eta espero den emaitza.
- Estandarrak: WordPress Coding Standards, PHPCS, itzulpenak domeinu zehatzekin, docblocks obligatuak.
- Segurtasuna: sanitizazioa, escaping, nonces, rolak eta gutxieneko gaitasunak, datu pertsonalen kudeaketa.
- Fitxategien egitura: direktorioen zuhaitza eta fitxategi/klase bakoitzeko ardurak.
- Izen konbentzioak: funtzioen, klaseen, script eta estiloen “handles” aurprefijoak.
- Onartze irizpideak: zer kontsideratzen duzun “eginda” zeregin bakoitzean, nola probatzen den eta zein froga baliozkoak diren.
- Dokumentazio itxaropenak: nola mantentzen den Documents.md eta noiz eguneratu behar den.
4.3. Zuzeneko onura
AGENTS.md ondo eginda, zure agenteen PR-ak koherentzia handia erakusten dute: konbentzio berberak, egitura bera, praktika seguruenak. Zure berrikusketa azkarragoa da, proiektua mantentzeko errazagoa da eta hirugarrenak sartzea errazagoa da.
5. TODO.md: agentearen kudeatzen duen taula
5.1. Kontrol aldaketa funtzionala
Fluxu honetan, EZ duzu TODO.md idazten. Agentearen bidez sortzen eta mantentzen da lehen konpromisotik. Honek esan nahi du agenteak:
- Zereginak eta exekuzio ordena definitzen ditu.
- Elementuak egoeren artean mugitzen ditu: itxaron, prozesuan, amaituta.
- Behar berri edo arriskuak detektatzen dituenean agertzen diren zereginak gehitzen ditu.
Zer egiten duzu orduan? AGENTS.md-n norabidea markatzen duzu, PR-ak berrikusten dituzu eta, hutsuneak detektatzen badituzu, Codex-i eskatzen diozu zereginak TODO.md-n gehitzeko. Horrela, taulak nola ulertzen eta planifikatzen duen agenteak lana</em} islatzen du, mikro kudeatu beharrik gabe.
5.2. Hurbilpen honen abantailak
- Autonomia operatiboa: zereginak orkestratzeko delegatzen duzu, kontrol estrategikoa mantenduz.
- Transparentzia: TODO.md agenteak hartutako erabakiak auditatzen dituen erregistro bihurtzen da.
- Agility: zeregin berriak berehala sartzen dira garapenaren bitartean agertzen direnean.
6. Documents.md: memoria tekniko bizia
6.1. Zer da eta zergatik da garrantzitsua
Documents.md ez da amaieran idatzitako eskuliburu bat. Ezagutza bizia da, agenteak garatzen duen bitartean eguneratzen duena. Proiektuaren publikoaren gainazala erregistratu behar du: klaseak eta metodoak, funtzioak, shortcodeak, hooks (actions/filters), datu eskemak, gako fluxuak eta erabilera errezetak. Maxima sinplea da: Documents.md-n ez badago, hirugarrenentzat ez da existitzen.
6.2. Eguneroko erabilera
Proiektuari egun edo aste batzuetako atzera itzultzen zarenean, kodea jarraitu beharrik ez duzu. Documents.md ireki eta aurkituko duzu:
- Behar duzun funtzioaren izena eta zein parametro onartzen dituen.
- Comportamendua aldatzeko zein iragazki lotu behar duzun.
- Taula batean zein zutabe dauden eta zein indize definituta dauden.
- Fluxu bat nola luzatu edo erabili adibide minimo bideragarri batekin.
6.3. Eguneratze politika
- Publikoaren gainazala aldatzen duen edozein PR-k Documents.md-ren eguneratzea barne hartu behar du.
- API bat gehitzen bada, erabilera adibide bat gehitu behar da.
- Datuen eskema aldatzen bada, migratzea eta justifikazioa anotatu behar da.
7. Agentic Coding-en praktika onak
7.1. Estandarrekin scrupulosity
Koherentzia mantendu: WordPress Coding Standards PHPCS-rekin, docblocks argiak, i18n ingelesez (eta itzulpenak behar denean), eta izendapen aurreikusgarriak. Agentek hobeto funtzionatzen dute arauak argiak eta uniformeki aplikatzen direnean.
7.2. Segurtasuna lehenetsiz
- Sarrerak sanitizatu egokiak diren funtzioekin (
sanitize_text_field,sanitize_email, etab.). - Irteerak HTML-n (
esc_html,esc_attr,wp_ksesHTML baimendua badago) ihes egin. - Formulariotan nonces eta zerbitzari aldetik egiaztatu.
- Rolak/gaitasunetan gutxieneko pribilegioaren printzipioa.
7.3. Txikiak eta egiaztagarriak diren zereginak
Lanak entrega unitateetan desegiten dituzu, minutu gutxitan berrikusi ahal izateko. Agenteari PR txikiak eskatzen dizkiozu, asmo bakar batekin. Horrela, akatsak murrizten dituzu, berrikusketa azkartu eta sistemaren ikaskuntza incrementala sustatzen duzu.
7.4. Onartze irizpide argiak
AGENTS.md-n, “Definition of Done” definitu zeregin motetarako: adibidez, “funtzionaltasuna prest dagoenean:
- PHPCS pasatzen duenean.
- Proba oinarrizkoak edo egiaztapen pausoak barne hartzen dituenean.
- Documents.md eguneratzen duenean.
- i18n zuzen duenean.
7.5. Dokumentazioa paraleloa
Agenteari eskatzen diozu Documents.md eguneratzeko funtzionaltasun aldaketak sartzen dituen PR berean. Desincronizazioa saihesten duzu eta frikzioa murrizten duzu.
7.6. Etengabeko auditoretza
Zenbait PR-ren ondoren, “mugak” egonkorren berrikusketa egin: repoaren egitura, mendekotasunak, errendimendua, segurtasuna, dokumentazio estaldura. Degradazioa detektatzen baduzu, AGENTS.md indartu eta zuzenketa zereginak ireki (agentearen TODO.md-n islatuko ditu).
8. Murrizketak eta errealismo operatiboa
8.1. Testuinguruaren menpekotasuna
LLM-k testuinguru mugak dituzte. Agenteak ez du “ikusten” guztia aldi berean; bere errendimendua hobetzen da iterazio mugatuetan lan egiten duzunean, memoria finkatzen duten artefaktuak (AGENTS.md, Documents.md) eta PR txikiak erabiliz.
8.2. Anbiguotasuna eta bere kostua
Zure eskakizunak lausotu badira, agenteak hutsuneak betetzeko joera izango du. Emaitza: berriro lanak. Irtenbidea: helburuak, murrizketak eta adibideak definitzea. Hasierako argitasunak ziklo osoak aurrezten ditu.
8.3. Akats plauzibleak
IA-k “egonkor baina okerra” den kodea sor dezake. Arrisku hau murriztu linters, oinarrizko probak eta giza berrikuspenekin. Gogoratu: giza rolak ez da desagertzen, kuradore eta arkitekto izatera igotzen da.
8.4. Irismena aldatzea
Proiektu biziek eboluzionatzen dute. Agenteak hobe kudeatzen du, TODO.md-n eragin kolateralak detektatzen dituenean zeregin berriak proposatuz, eta zuk proposamen hori balidatu behar duzu exekutatu aurretik.
9. Adibide praktikoa: “Simple Contact Shortcode & Block” proiektuaren eskeletoa
Teoria benetako inplementazio batekin lotzeko, WordPress-en proiektu sinple bat anklatu nahi dugu, Agentic Coding fluxua demostratzeko. Puntuan ez dugu azken kodea sartuko (geroago zure agentearekin lan egingo dugu). Estrukturalak eta artefaktuak eta piezak teknikak txertatuko ditugun espazioak argi utziko ditugu. Horrela, gaur egungo gida argitaratu ahal izango duzu eta, pauso batzuetan, adibidea osatzen joan zaitezke sarrera idatzi beharrik gabe.
9.1. Pluginaren helburua
“Simple Contact Shortcode & Block” pluginak formulario sinple bat emango du (Izena eta Emaila) edozein orrialdetan gehitzeko bi modutan: shortcode baten bidez eta Gutenberg bloke baten bidez. Formularioa bidaliz, datuak berezko taula batean gordeko ditu datu basean eta webguneko administratzaileari email bidez jakinaraziko dio.
9.2. Espero den direktorio egitura
/simple-contact/
├─ simple-contact.php # Pluginaren Bootstrap
├─ uninstall.php # Desinstalatzen garbiketa
├─ includes/
│ ├─ class-sc-database.php # Eskema eta CRUD
│ ├─ class-sc-form.php # Render + submission
│ └─ class-sc-block.php # Blokeen erregistroa
├─ assets/
│ ├─ css/style.css # Frontend estiloak
│ └─ js/block.js # Bloke logika
└─ languages/
└─ simple-contact.pot # Itzulpenen txantiloia
9.3. Agentic fluxuaren artefaktuak
- AGENTS.md inplementazio arauak eta itxaropenak ezarriko ditu.
- TODO.md Codex-ek sortu eta mantenduko du. Hemen atzerako lanak eta agenteak erabakitako lehentasuna agertuko dira.
- Documents.md API, hooks eta fluxuen katalogoa haziko da inplementatzen den heinean.
9.4. Fitxategiak
Azaldu dugun bezala, AGENTS.md fitxategia sortu behar dugu, Codex-ek jarraituko duen.
Hori egiteko, nahi duzunaren ideia argia izan behar duzu, behin guztia argi dagoenean eta ChatGPT-rekin proiektuari buruz “hitzez hitz” aritu zaren heinean, AGENTS.md sortzeko eskatzen diozu, arauak eta proiektua definituz.
Ongi, orain AGENTS.md sortuko dugu hitz egin dugun guztiarekin Codex-ek zer egin eta nola egin behar duen gidatzeko.
Behar duzu AGENTS.md guztiz zuzen eta osorik sortzea proiektu honetarako.
Gehitu behar duzu fitxategien egitura guztia, WordPress-en segurtasun estandarrak jarraitu, segurtasun neurriak, fitxategien izenak, fitxategien, klaseen, funtzioen aurprefijoak, etab. estandarizatuak, goiburuak eta iruzkinak fitxategi, funtzio, kale eta metodo guztietan, WordPress-en zehaztutako moduan. Kate guztiak ingelesez izan behar dute, eta itzul daitezke. Oso garrantzitsua da PHPCS pasatzea, bere tabulazio eta espazioen lerrokatze guztiak mantenduz.
Era berean, TODO.md eta Documents.md-ren erabilera zehaztu eta azaldu behar duzu, hasieratik erabiltzeko eta ez geroago egin beharrik ez izateko. Fitxategi bat oso handia denean, adibidez itzulpen fitxategi batean, PR desberdinetan sortu behar duzu, beti PR-ak sortu ahal izateko eta tamainagatik egitea ezinezkoa ez izateko.
Erregistroak .gitignore fitxategiak (garapen junk eta OS fitxategiak) eta .gitattributes izan behar ditu, azken paketean egon behar duen guztia iritsi dadin eta ez iritsi behar diren OS fitxategiak.
Sortu AGENTS.md ingelesez.
Prompt honen ondoren, ChatGPT-k AGENTS.md-n itsatsi beharko dudan edukia itzultzen dit.
# AGENTS.md — Simple Contact Shortcode & Block
## Proiektu Helburua
WordPress plugin bat sortu **Simple Contact Shortcode & Block** izenekoa, formulario kontaktu sinple bat agerian jartzen duena:
- Shortcode bat: `[simple_contact]`
- Gutenberg bloke bat: `simple-contact/form`
Formulariak **Izena** eta **Emaila** biltzen ditu, bidalketak datu baseko taula pertsonal batean gorde eta webguneko administratzaileari jakinarazpen email bat bidaltzen du. Pluginak WordPress Coding Standards eta segurtasun praktika onenak zorrotz jarraitu behar ditu. Kodea eta dokumentazioa **Ingelesez** izan behar dira, eta erabiltzaileari agertzen zaizkion kate guztiak **itzul daitezke** **text domain `simple-contact`** erabiliz.
---
## Estandar ez negoziagarriak
1. **Kode estandarrak & PHPCS**
- **PHPCS** ofizialeko WordPress Coding Standards arauen arabera pasatu behar da.
- **Tabulazioak indentatzeko**, **espazioak lerrokatzeko**. Ez da espazio amaigabea utzi behar.
- Koherentziazko array formatuak, parametroen lerrokadura eta dokumentazio inlinea.
- Ez da inportazio erabilgarririk, kode hila edo iruzkinak utzi behar.
2. **Dokumentazio diziplina**
- PHP fitxategi bakoitzean: helburu, pakete, hasi, eta egilearen deskribapena PHPDoc.
- Klase, metodo eta funtzio bakoitzean: docblocks osoak (laburpena, `@param`, `@return`, `@since`, `@see` behar denean).
- Logika ez argi eta segurtasunari lotutako adarretarako iruzkin inlineak.
- Dokumentu eta iruzkin guztiak **Ingelesez**.
3. **Segurtasuna**
- **Sarrerak sanitizatu**: sanitizadore egokiak erabili (`sanitize_text_field`, `sanitize_email`, `absint`, `sanitize_key`, `wp_unslash`, etab.).
- **Irteerak ihes egin**: `esc_html`, `esc_attr`, `esc_url`, edo `wp_kses` (baimendutako HTML zorrotza) irudikatu aurretik.
- **Nonces**: formulario guztiek nonce bat izan behar dute eta zerbitzari aldetik egiaztatu behar dira `check_admin_referer` erabiliz.
- **SQL segurtasuna**: `$wpdb->prepare()` erabili behar da sarrerarik fidagabearekin SQL guztietan.
- **Gaitasunak**: administrazio ekintza edo orrialde guztiek gaitasun egokiak egiaztatu behar dituzte (adibidez, `manage_options` edo gaitasun pertsonalizatua).
- **Ez da sekreturik erregistroan**: API gakoak edo sekretuak ez dira konprometitu behar.
- **Ez da PII ihesik**: inoiz ez da erabiltzaile sarrera gordina irudikatu behar; loga arretaz egin (datu sentikorretatik saihestu).
4. **Internazionalizazioa (i18n)**
- Erabiltzaileari agertzen zaizkion kate guztiak itzulpen funtzioekin bildu behar dira: `__()`, `_e()`, `esc_html__()`, `esc_attr__()`, etab.
- Testu domeina: **`simple-contact`**.
- /languages/simple-contact.pot eskaintzea eta eguneratuta mantentzea.
5. **Pull Request (PR) politika**
- PR-ak **txikiak, fokalizatuak eta auto-bilteak** izan behar dira.
- Aldaketa **fitxategi oso handiak** (adibidez, `.pot`, vendor paketeak, sortutako aktiboak) baditu, **PR desberdinetan banatu** behar da, PR-ak berrikusteko eta tamaina mugak gainditzeko.
- PR bakoitzak:
- **PHPCS** pasatu behar du.
- Publikoaren gainazala ukitzen badu, **Documents.md** eguneratu behar du.
- **TODO.md** (Codex-ek mantendua) eguneratu behar du “Amaituta” mugitu dena eta aurkitutako zeregin berriak.
- Proba/egiaztapen notak argi izan behar ditu.
---
## Erregistroaren higienea: .gitignore eta .gitattributes
Iturri kontrol garbia eta askotariko pakete garbiak ziurtatzeko:
### 1) `.gitignore` (garapen junk eta OS fitxategiak)
Codex-ek .gitignore sortu behar du repoaren erroan, gutxienez barne hartuz:
OS fitxategiak
.DS_Store
.DS_Store?
Thumbs.db
ehthumbs.db
Icon?
._*
IDE/editore
.vscode/
.idea/
*.iml
Node / frontend eraikuntzak
node_modules/
npm-debug.log*
yarn-error.log
dist/
build/
PHP / tresneria
vendor/
composer.lock
Logak & tenporala
*.log
*.tmp
*.cache
Estaldura / txostenak
coverage/
.clover
.phpunit.result.cache
Proiektuak Composer edo eraikuntza pauso bat onartzen badu, luzatu behar da.
### 2) `.gitattributes` (zer iritsi behar den paketeetara kontrolatzea)
Codex-ek .gitattributes sortu behar du repoaren erroan **banatzeko fitxategi ez-distribuzioak** baztertzeko (GitHub “Download ZIP”, composer dist, etab.). `export-ignore` arauak erabili. Gutxienez:
/.gitattributes export-ignore
/.gitignore export-ignore
/.github/ export-ignore
/.vscode/ export-ignore
/.idea/ export-ignore
/tests/ export-ignore
/docs/ export-ignore
/.editorconfig export-ignore
/phpcs.xml* export-ignore
/phpmd.xml* export-ignore
/phpunit.xml* export-ignore
/CHANGELOG.md export-ignore
/README.md export-ignore
/CONTRIBUTING.md export-ignore
/package.json export-ignore
/package-lock.json export-ignore
/yarn.lock export-ignore
/webpack.* export-ignore
/rollup.* export-ignore
/vite.* export-ignore
/node_modules/ export-ignore
/src/ export-ignore
Zerrenda egokitu behar da tresneria eboluzionatzen den heinean. Helburua: **distribuzio ZIP-ak plugin-a exekutatzeko behar den guztia soilik barne hartu behar du** (PHP `includes/`, main bootstrap, runtime-rako eraikitako aktiboak, hizkuntzak). OS fitxategiak, hala nola .DS_Store eta Windows metadata paketeetan agertzen ez dira.
---
## Fitxategi & Izendapen Konbentzioak
### Direktorio Egitura
/simple-contact/
├─ simple-contact.php # Pluginaren bootstrap nagusia (hooks, konstanteak, kargatzaileak)
├─ uninstall.php # Desinstalatzen garbiketa
├─ includes/
│ ├─ class-sc-database.php # DB eskema + CRUD
│ ├─ class-sc-form.php # Formularioa renderizatu + submission handler + shortcode
│ └─ class-sc-block.php # Gutenberg blokeen erregistroa + aktibo logika
├─ assets/
│ ├─ css/style.css # Frontend estiloak (plugin klaseetan mugatua)
│ └─ js/block.js # Bloke editore script (block.json bidez erregistratua)
├─ languages/
│ └─ simple-contact.pot # Itzulpen txantiloia (itzultzaileentzat esportatua)
### Klase Izendapenak
- Aurprefijo: `SC_`
- Adibideak: `SC_Database`, `SC_Form`, `SC_Block`
### Global Funtzio Izendapenak
- Aurprefijo: `sc_`
- Adibidea: `sc_render_form()`
### Script & Estilo Handles
- Aurprefijo: `sc-`
- Adibideak: `sc-frontend`, `sc-block-editor`, `sc-block-style`
### PHP Fitxategi Goiburuak
Fitxategi bakoitzak PHPDoc goiburu bloke batekin hasi behar du:
- Laburpen lerroa (zer egiten duen fitxategi honek).
- `@package` plugin slug (adibidez, `simple-contact`).
- `@since` bertsio kate.
- Aukerazko `@author`.
### Metodo & Funtzio Docblocks
- Laburpen lerro bat, hutsune bat, eta gero deskribapen zehatza behar izanez gero.
- `@param` parametro bakoitzerako tipoa eta deskribapena.
- `@return` tipoa eta deskribapena.
- `@since` etiketa.
---
## Beharrezko Fitxategiak: Ardurak & Edukia
### 1) `simple-contact.php`
- **Plugin goiburu**: Izen, Deskribapena, Bertsioa, Egilea, Lizentzia, Testu Domeina, Domein Bidea.
- **Konstanteak**: `SC_PLUGIN_VERSION`, `SC_PLUGIN_FILE`, `SC_PLUGIN_DIR`, `SC_PLUGIN_URL`.
- **Testu domeina kargatu** `plugins_loaded`-en.
- **Inklusioak**: `includes/class-sc-database.php`, `includes/class-sc-form.php`, `includes/class-sc-block.php` behin betiko eskatzea.
- **Aktibazio hook**: DB taula sortu `SC_Database` bidez.
- **Desaktibazio hook**: ez da ekintza suntsitzaile bat; datuak mantendu behar dira desinstalatu arte.
- **Bootstrap**: singletonak sortu edo hooks hasieratu.
### 2) `uninstall.php`
- Egiaztatu `defined( 'WP_UNINSTALL_PLUGIN' )`.
- Taula pertsonala ezabatu.
- Plugin aukerak ezabatu (badira).
- Pluginak sortutako datu orphaned ez utzi (pluginaren jabetzako postak/erabiltzaileak izan ezik).
### 3) `includes/class-sc-database.php`
- Singleton patroi (`SC_Database::instance()`).
- `create_table()` `dbDelta()` erabiliz hasierako eskema.
- Eboluzionatzen denean bertsionatutako migrazioak `sc_db_version` aukera batekin.
- CRUD:
- `insert_contact( array $data ): int|WP_Error`
- `get_contacts( array $args = [] ): array`
- Mugak eta `$wpdb->prepare()` leku guztietan zorrozki sanitizatu.
- Timestamps **UTC**-n gorde.
### 4) `includes/class-sc-form.php`
- Singleton patroi (`SC_Form::instance()`).
- Renderizazio metodoa: `render_form( array $atts = [] ): string`
- Ezaugarriak: `success_message` (string), `css_class` (string).
- Irteera ihes eginda eta HTML ondo formateatuta.
- Submission handler: `handle_submission(): int|WP_Error`
- Nonce egiaztatu.
- Sarrerak sanitizatu.
- Emaila `is_email()` erabiliz balidatu.
- `SC_Database` bidez txertatu.
- Administratzaileari emaila bidali (iragazgarria).
- Shortcode erregistroa: `[simple_contact]` renderizazio metodoarekin mapatuta.
- Hooks:
- Ekintzak: `sc_before_insert_contact`, `sc_after_insert_contact`
- Iragazkiak: `sc_email_to`, `sc_email_subject`, `sc_email_headers`, `sc_success_message`
### 5) `includes/class-sc-block.php`
- Blokea erregistratzen du `block.json` bidez.
- Ezaugarriak shortcode ezaugarriekin islatzen direla ziurtatzen du:
- `successMessage` (string)
- `cssClass` (string)
- Editore script (`assets/js/block.js`) eta frontend estiloa (`assets/css/style.css`) erregistratu/erabiltzen ditu bertsionatutako maneiatuak erabiliz.
- Zerbitzari aldetik renderizazioa `SC_Form::render_form()` deituz egin daiteke shortcodearekin parekatzeko.
### 6) `assets/css/style.css`
- Minimoa, gaika lagungarria den CSS.
- Konflictuen saihesteko wrapper berezi batean (adibidez, `.sc-form`) azpimarratuta.
### 7) `assets/js/block.js`
- Bloke erregistroa (editatu + gorde).
- `successMessage` eta `cssClass` konfiguratzeko ikuskari kontrolak.
- Editore aurrebista arina eta koherentea.
### 8) `languages/simple-contact.pot`
- Iturrietatik esportatua, itzul daitezkeen kate guztiak barne hartzen ditu.
- .pot oso handia bada, PR-ak banatu behar dira berrikusteko (eguneratzeak ez utzi).
---
## Datu Base Eskema
Taula: `{$wpdb->prefix}sc_contacts`
| Kolumna | Mota | Oharrak |
|-------------|-----------------------------------|------------------------------------------------|
| id | BIGINT UNSIGNED AUTO_INCREMENT | Lehenetsitako giltza |
| izena | VARCHAR(120) | `sanitize_text_field()` bidez sanitizatuta |
| email | VARCHAR(190) | `is_email()` erabiliz balidatuta |
| created_at | DATETIME | UTC-n gorde |
| consent_ip | VARBINARY(16) NULL | Aukerakoa (IPv4/IPv6 binario gisa gorde) |
| user_agent | VARCHAR(255) NULL | Aukerakoa |
Indizeak:
- `PRIMARY (id)`
- `INDEX (email)`
- `INDEX (created_at)`
Migrazioak:
- Eboluzionatzen denean, `maybe_upgrade_schema()` inplementatu bertsio aukera batekin etorkizuneko aldaketak kudeatzeko.
---
## Shortcode Espezifikazioa
- **Etiketa**: `[simple_contact]`
- **Ezaugarriak**:
- `success_message` (string, aukerakoa; lokalizatutako string lehenetsia)
- `css_class` (string, aukerakoa)
- **Adibidea**:
[simple_contact success_message=“Eskerrik asko, laster kontaktatuko zaitugu.” css_class=“is-style-card”]
---
## Bloke Espezifikazioa
- **Izena**: `simple-contact/form`
- **Kategoria**: `widgets`
- **Ezaugarriak**:
- `successMessage` (string)
- `cssClass` (string)
- Ikuskari kontrolak biak konfiguratzeko aukera eman behar du.
- Gorde ezaugarriak eta ziurtatu aurreko portaera shortcodearekin parekatzen dela.
---
## Ekintzak & Iragazkiak (Publiko Gainazala)
**Ekintzak**
- `sc_before_insert_contact( array $sanitized_data )`
- `sc_after_insert_contact( int $contact_id, array $data )`
**Iragazkiak**
- `sc_email_to( string $recipient, array $data )`
- `sc_email_subject( string $subject, array $data )`
- `sc_email_headers( array $headers, array $data )`
- `sc_success_message( string $message, array $data )`
Ekintza/iragazki berri bat gehitzen edo aldatzen den bakoitzean, **Documents.md** eguneratu behar da sinadura, denbora eta erabilera adibidearekin.
---
## TODO.md-ren Rol (Codex-ek mantendua)
- `TODO.md` **Codex-ek jabetzen eta mantentzen du** lehen konpromisotik.
- Gutxienez, **Itxaron**, **Prozesuan**, **Amaituta** atalak barne hartu behar ditu.
- Codex-ek zereginak banatu eta ordena zehazten du, elementuak egoeren artean mugitzen ditu, eta **beharrezko zeregin berriak proaktiboki gehitzen ditu**.
- Giza kolaboratzaileek **ez dute** TODO.md zuzenean editatu behar; aldaketak eskatzen dituzte eta Codex-ek eguneratzen du.
---
## Documents.md-ren Rol (Codex-ek mantendua)
- `Documents.md` **egonkorra den ezagutza basea** da:
- Azkar nabigazioa
- Arkitektura (moduluak eta ardurak)
- Datu eskema eta migrazioak
- Publiko API (klaseak, metodoak, funtzioak)
- Ekintzen & Iragazkien katalogoa
- Shortcode eta Bloke erabilera
- Fluxuak (bidalketa, desinstalazioa)
- Nola egin (zabaldu/pertsonalizatu)
- Proba & QA
- Askotariko notak (laburrak); xehetasun osoak `CHANGELOG.md`-n
- Glosarioa (aurprefijoak, izenak, terminoak)
- **Publiko gainazala edo portaera aldatzen duen edozein PR-k Documents.md eguneratu behar du.** Dokumentazio eguneratze beharrezkoak ez dituzten PR-ak baztertuko dira.
---
## Proba & QA
- PR-en deskribapenetan egiaztapen pausoak deskribatu behar dira (formularioa irudikatzen, nonce egiaztatzen, email okerra baztertzen, arrakasta bideak errenkada gordetzen eta emaila bidaltzen, desinstalatzen garbitzen).
- Aplikagarria denean, oinarrizko probak edo errepikatzeko pausoak barne hartu.
- Irisgarritasuna: formularioaren etiketak/ids, botoi testuak, errore mezuek irakurtzeko eta lokalizatzeko moduan izan behar dute.
- Errendimendua: galdera ez beharrezkoak saihestu; behar denean bakarrik kargatu.
---
## Publikazio Pakete Politika
- **Banatutako ZIP** (WordPress plugin paketea) exekutatzeko behar den guztia soilik barne hartu behar du:
- `simple-contact.php`, `uninstall.php`, `/includes/`, runtime-rako eraikitako `/assets/`, `/languages/`.
- **Baztertu** garapen artefaktuak (probak, CI, editore konfigurazioak, node_modules, src, dokumentuak) .gitattributes `export-ignore` bidez.
- OS junk fitxategiak (adibidez, `.DS_Store`, `Thumbs.db`) paketeetan agertzen ez dira.
- Eraikuntza pipeline bat sartu bada, ziurtatu eraikitako aktiboak barne hartzen direla eta iturriak baztertzen direla politika honen arabera.
---
## Codex-en azken operazio arauak
- Beti idatzi **Ingelesez** kode iruzkinak eta dokumentuak.
- Beti bildu erabiltzaile kateak i18n funtzioekin `simple-contact` testu domeina erabiliz.
- Beti sanitizatu sarrera eta ihes irteera azken unean.
- Beti pasa **PHPCS** eta errespetatu tab/espazio konbentzioak (tabulazioak indentatu, espazioak lerrokatu).
- Mantendu **PR-ak txikiak**; aldaketa handiak PR desberdinetan banatu.
- Eguneratu **TODO.md** eta **Documents.md** kode aldaketen parean.
- Mantendu `.gitignore` eta `.gitattributes` beraz, repo garbia mantentzen da eta distribuzio ZIP-a minimal eta konforme da.
AGENTS.md-n arau hauetako edozein jarraitzea aldaketak eskatzea edo PR-a baztertzea ekar dezake.Ikusi duzu, gainera, praktika adibide bat prestatzeko, zure agentearekin osatu ahal izango duzuna: “Simple Contact”.
Garapenaren etorkizuna kolaboratiboa da: giza eta agenteak elkarrekin lan egiten dute prozesu argiekin, estandar sendoekin eta etengabeko frogekin. Has zaitez gaur zure fluxu eta zure arauekin; IA-k gainerako guztia egingo du zure gidaritzapean.
