@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false

title Evolusi Sesi — Dari Sesi 1 hingga 150+
legend top
    |= Couleur |= Projet |
    | <#4CAF50> | cheroliv.com |
    | <#2196F3> | plantuml-plugin |
    | <#FF9800> | bakery-plugin |
    | <#9C27B0> | magic-stick |
endlegend

concise "Sesi aktif" as S

@S
0 is ".md mentah"
1 is "Migrasi\nAsciiDoc"
10 is "Bersemangat/Malas\ndiformalkan"
62 is "Aturan keamanan\n(site.yml)"
87 is "Pecah
konteks"
109 is "Optimasi
-60% token"
133 is "133 sesi
240 tes LULUS"

S@0 -> S@1 : Session 1\n(cheroliv.com)
S@1 -> S@10
S@10 -> S@62 : Session 62\n(plantuml-plugin)
S@62 -> S@87 : Session 87\n(Cry 4 help)
S@87 -> S@109 : Session 109\n(API Key Pool)
S@109 -> S@133 : Session 133\n(Aujourd'hui)

@enduml

@startuml
skinparam defaultTextAlignment center
skinparam wrapWidth 200

package "Akar Proyek (Eager - Dimuat otomatis)" {
    component "<b>AGENT.adoc</b>\nAturan mutlak\nStruktur & Konvensi" as AGENT
    component "<b>PROMPT_REPRISE.adoc</b>\nMisi sesi N\nRingkasan N-1" as PROMPT
    component "<b>INDEX.adoc</b>\nTitik masuk\nAturan + Sesi" as INDEX
    component "<b>*_ESSENTIALS.adoc</b>
Konteks bisnis
kritik" as ESS
}

package ".agents/ (Lazy - Dimuat saat diminta)" {
    component "<b>sessions/N-*.adoc</b>\nArsip terperinci\nKeputusan & Keluaran" as SESS
    component "<b>SESSIONS_HISTORY.adoc</b>\nRingkasan tabel\nTanggal/Jenis/Nilai" as HIST
    component "<b>PROCEDURES.adoc</b>
Templates akhir sesi
6 langkah" as PROC
    component "<b>*_REFERENCE.adoc</b>\nArsitektur lengkap\nReferensi teknis" as REF
    component "<b>COMPLETED_TASKS_ARCHIVE</b>\nTugas yang selesai\nPer bulan" as ARCH
    component "<b>AGENT_MODUS_OPERANDI.adoc</b>\nDokumentasi strategi\nMetodologi" as MOD
    component "<b>*_REFERENCE.adoc</b>
Pengujian boot, partisi A/B
Konteks spesifik" as SPEC
}

AGENT --> PROMPT : "Referensi"
AGENT --> INDEX : "Referensi"
INDEX --> SESS : "Indeks"
INDEX --> HIST : "Indeks"
INDEX --> PROC : "referensi"
INDEX --> ARCH : "referensi"
INDEX --> REF : "referensi"
PROMPT --> SESS : "Arsip N-1"
PROMPT --> ESS : "Konteks bisnis N"

@enduml

----
----
| magic-stick    | Session 23 | SCRIPT_VERIFICATION.adoc | 2026-04-27 |
| bakery-gradle  | Session 11 | TEST_COVERAGE_ANALYSIS   | 2026-04-27 |
| cheroliv.com   | Session 9  | TEST_COVERAGE_ANALYSIS   | 2026-04-27 |
| plantuml-gradle| Session 133| TEST_COVERAGE_ANALYSIS   | 2026-04-23 |
| jhipster-gradle-plugins | Session 1 | TEST_COVERAGE_ANALYSIS | 2026-04-28 |
----

**`*_ESSENTIALS.adoc`** -- Penambahan baru (Session 109, plantuml-plugin) untuk mengoptimalkan lagi konteks Eager. Alih-alih memuat 200 baris konteks bisnis di pool kunci API, saya memuat 50 baris dari inti, dan 150 baris lainnya tetap dalam keadaan LAZY di`*_REFERENCE.adoc`.

Hasil yang diukur: peralihan**~25k tokens EAGER ke ~10k tokens**(kenaikan 60%). Agen tidak lagi membutuhkan pengingat yang boros energi.

==== Rantai yang Hilang : `opencode.json

Saya harus mengakui suatu hal yang hampir saya lupa untuk didokumentasikan. Di atas semua file .adoc ini, terdapat sebuah file JSON sangat kecil yang tanpa-nya tidak ada yang berfungsi. Namanya`opencode.json`dan dia membuat enam baris. Secara literal enam baris.

[source,json]
----
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "AGENT.adoc"
  ]
}
----

Ini file yang memberitahu Opencode : « Saat mulai, muat`AGENT.adoc`secara otomatis. » Tanpa dia, agen itu merupakan halaman putih persis seperti yang saya gambarkan di awal artikel. Dengan dia, agen sudah memiliki di tangan rules absolut, arsitektur proyek, dan perintah penting — bahkan sebelum saya katakan halo.

Saya menemukan pentingnya file ini secara kebetulan. Tentang`bakery-plugin`, tidak ada. Saya bertanya-tanya mengapa agen tersebut secara konsisten lebih « bingung » pada proyek ini dibandingkan dengan yang lain. Aturan mutlak berada baik di`AGENT.adoc`— tapi`AGENT.adoc`tidak pernah terisi. Agen hanya membaca apa yang saya katakan kepadanya untuk dibaca, secara manual, di setiap sesi. Ini adalah sesi 11 dari`bakery-plugin`ketika saya menyadari ketidakhadirannya`opencode.json`. Saya telah membuatnya — dan sesi 12 dimulai seperti yang lain.

File ini sangat jelas bagi saya sekarang bahwa saya bahkan tidak lagi memikirkan itu. Ini adalah kesalahan klasik dari seorang pengembang yang terlalu familiar dengan alatnya. Hari ini, saya membuatnya secara sistematis *sebelumnya*.`AGENT.adoc`. Ini adalah batu pertama.

==== Dualitas dari `INDEX.adoc

Satu lagi hal halus yang layak diperjelas:`INDEX.adoc`hidup di`.agents/`— sebuah folder yang saya presentasikan sebagai LAZY. Namun, saya menentukannya sebagai EAGER di semua tabel saya. Ada ketegangan yang jelas di sini.

Realitas lapangan: file-file`.agents/INDEX.adoc`sudah dimuat secara otomatis pada awal sesi, sama seperti`AGENT.adoc` et `PROMPT_REPRISE.adoc`. Mereka berada di`.agents/`karena alasan organisasi — jangan menginvasi akar — tapi perilaku mereka EAGER.

Di`plantuml-plugin`, `INDEX.adoc`Memiliki 200 baris dan memuat aturan mutlak *lengkap* dengan histori mereka (pelajaran dari sesi sebelumnya), EPIC dengan skor, dan portofolio proyek. Ini adalah dokumen yang dikonsultasi oleh agen untuk mengetahui « di mana kita berada ». Pada`bakery-plugin`, dia membuat 150 baris dengan roadmap dan sesi terbaru.

Redundansi sengaja di antara`AGENT.adoc` et `INDEX.adoc`Mungkin mengejutkan. Aturan mutlak ada di keduanya. Mengapa? Karena mereka memenuhi dua peran yang berbeda: dalam`AGENT.adoc`, mereka adalah *explicatives* (storytelling dari aturan, pelajaran yang dipelajari) ; dalam`INDEX.adoc`, mereka adalah *eksekutif* (aturan telanjang, tanpa justifikasi, untuk konsultasi cepat). Agen membaca`AGENT.adoc`sekali untuk *memahami*; ia membaca kembali`INDEX.adoc`pada setiap sesi untuk *menerapkan*. Dua penggunaan, dua format.

[plantuml, format=svg, id=diag-dualite-agent-index, alt="Comparaison entre AGENT.adoc (narratif) et INDEX.adoc (exécutif)"]
----
@startuml
skinparam backgroundColor #FEFEFE
skinparam defaultTextAlignment center

title Dualitas AGENT.adoc ←→ INDEX.adoc
left to right direction

rectangle "AGENT.adoc\n(Akar — EAGER)" as AGENT #E3F2FD {
  rectangle "📖 **Format Narasi**
Storytelling dari aturan
pelajaran yang dipelajari, konteks" as NARR
  rectangle "🏗️ **Arsitektur Lengkap**
Struktur proyek, komponen
Backlog terinci US" as ARCHI
  rectangle "📋 **Aturan Penjelasan**
Mengapa aturan ada
Riwayat insiden" as EXPL
}

rectangle "INDEX.adoc\n(.agents/ — EAGER)" as INDEX #E8F5E9 {
  rectangle "⚡ **Format Eksekutif**
Aturan telanjang, tanpa justifikasi
Konsultasi cepat" as EXEC
  rectangle "📊 **Roadmap & EPICs**\nTabel ringkasan\nProgres, Skor, Prioritas" as ROAD
  rectangle "🌐 **Portofolio Proyek**
Tampilan melintang
5 proyek disinkronkan" as PORT
}

AGENT --> INDEX : "Agent membaca AGENT.adoc
1 kali untuk **memahami**"
INDEX --> AGENT : "Agent membaca kembali INDEX.adoc
setiap session untuk **menerapkan**"

note bottom of AGENT
  Taille max : 200 lignes
end note

note bottom of INDEX
  Taille max : 200 lignes
  Source de vérité en cas de divergence
end note

@enduml
----

Redundansi yang diasumsikan ini adalah pilihan desain. Dia mengonsumsi sekitar 50 baris tambahan token EAGER — namun ia menjamin bahwa agen selalu memiliki aturan di depan mata, termasuk dalam format singkat yang memfasilitasi kepatuhan segera.

=== File LAZY : Manual Pemilik

File-file ini hidup di`.agents/`dan hanya dibaca ketika agen membutuhkannya. Mereka merepresentasikan kekayaan sejati dari metode tersebut, karena mereka mengakumulasi pengetahuan proyek tanpa mencemari konteks saat ini.

[plantuml, format=svg, id=diag-agents-tree, alt="Arborescence complète du dossier .agents/"]
----
@startuml
skinparam folderBackgroundColor #E3F2FD
skinparam folderBorderColor #1565C0
skinparam fileBackgroundColor #FFF3E0
skinparam fileBorderColor #EF6C00

folder ".agents/" as ROOT {
  file "INDEX.adoc
(EAGER -- 200 baris)" as IDX #E8F5E9
  file "AGENT_SESSION_MANAGER.adoc\n(Sesi template)" as ASM
  file "SESSION_CHECKLIST.adoc
(Kapan mengubah)" as CHK
  file "PROCEDURES.adoc\n(6 langkah + LAZY/EAGER)" as PRO
  file "SESSIONS_HISTORY.adoc\n(Semua sesi)" as HIS

  folder "sesi/" as SESS {
    file "1-chore-migration.adoc" as S1
    file "109-formalisasi-lazy.adoc" as S109 #FFECB3
    file "133-epic11-article.adoc" as S133
    file "... +130 lainnya" as SMORE
  }

  folder "arsip/" as ARCH {
    file "COMPLETED_TASKS_2026-04.adoc" as CTA
    file "SESSIONS_HISTORY_83-95.adoc" as SHIST
    folder "sessions_summaries/" as SUM {
      file "SESSION_64_SUMMARY.adoc" as SU64
      file "SESSION_73_SUMMARY.adoc" as SU73
      file "..." as SUMORE
    }
    folder "prompts_archive/" as PARCH {
      file "PROMPT_REPRISE_S65.adoc" as PR65
      file "PROMPT_REPRISE_S75.adoc" as PR75
      file "..." as PMORE
    }
  }
}

IDX --> SESS : "Indeks"
IDX --> HIS : "Indeks"
IDX --> ARCH : "Referensi"

note right of S109
  Session 109 =
  Formalisation stratégie
  LAZY/EAGER
  Token : ~25k → ~10k
end note

@enduml
----

Struktur direktori di atas menunjukkan struktur sebenarnya dari folder`.agents/`di atas`plantuml-plugin`, proyek paling matang. Perhatikan kedalaman dalam tiga lapisan: file akar (metadat), folder`sessions/`(arsip kronologis), dan file`archives/`(agregasi dan ringkasan). Ini adalah kedalaman yang mengubah tata kelola dari sebuah file TODO sederhana menjadi**memori organisasional lengkap**.

**.agents/sessions/{N}-{titre}.adoc**-- Arsip terperinci setiap sesi. Saat ini :

* `plantuml-plugin`:**133 sesi terarsip**dari sesi 1 hingga 133
* `bakery-plugin` : **11 sesi**
* `magic-stick`:**23 sesi**
* `cheroliv.com`:**9 sesi formal**+ 7 sesi pra-sistem yang direkonstruksi secara retroaktif

Setiap arsip berisi konteks lengkap sesi, keputusan yang diambil, masalah yang dihadapi dan penyelesaiannya, perintah yang dijalankan dan output.

**.agents/SESSIONS_HISTORY.adoc**-- Sebuah tabel ringkasan dari semua sesi dengan skor. Contoh pada`cheroliv.com` :

----

| -6 | 2025-05 | chore | Initialisation projet Gradle/JBake | 7/10 |  1 | 2026-04-25 | chore | Migration gouvernance agent | 8/10 |  7 | 2026-04-27 | debug/fix | Correction publishSite | 9/10 |  8 | 2026-04-27 | analyse | Analyse article 0108 | 7/10

**.agents/COMPLETED_TASKS_ARCHIVE_{mois}.adoc**Tugas yang selesai diarsipkan per bulan, agar tidak membebani backlog aktif. Saat sebuah user story selesai, ia pindah ke sini. Backlog tetap terbaca: maksimal 10 item aktif.

**.agents/PROCEDURES.adoc**-- Mtemplate terperinci prosedur akhir sesi. Panjang, tetapi hanya dibaca satu kali oleh agen ketika ia belajar metode. Selanjutnya, prosedur menjadi mekanis.

**.agents/AGENT_MODUS_OPERANDI.adoc**-- Dokumentasi strategi lengkap. pada`plantuml-plugin`, file ini melakukan**900+ baris**dan sebenarnya bernama`AGENT_METHODOLOGIES.adoc`— Saya telah mengubah nama antara penulisan artikel ini dan pelaksanaannya yang efektif. Jenis divergensi de naming seperti ini tidak terhindarkan dalam sistem artesan yang berkembang. Yang penting adalah konvensi penamaan: jika file dokumentasi *méthode*, maka dimulai dengan`AGENT_`atau sebuah awalan eksplisit. Dia mendokumentasikan metodologi Eager/Lazy, pola yang harus diikuti, dan anti-pola yang harus dihindari. Dia LAZY karena agen tidak perlu membaca ulang seluruh strategi di setiap sesi, hanya ketika ada ambiguïtas.

</think> (no output, as there is no French text provided to translate)`*_REFERENCE.adoc`Referensi teknis spesifik untuk proyek. pada`magic-stick`, dua file LAZY padat :

* `AB_PARTITION_REFERENCE.adoc`(147 baris) -- Arsitektur Parti A/B GPT, skrip`update-system.sh`, ukuran yang diperkirakan, mekanisme rollback
* `BOOT_TEST_REFERENCE.adoc`(144 baris) -- Prosedur QEMU + VNC untuk menguji proses boot ISO tanpa perangkat fisik, daftar periksa BIOS/UEFI, keterbatasan CI/CD

Di`plantuml-plugin` :

* `ARCHITECTURE.adoc`(134 baris) -- Struktur dari 11 kelas data, poin perhatian (jebakan yang harus dihindari), perintah pengujian yang dioptimalkan
* `API_KEY_POOL_REFERENCE.adoc`-- detail lengkap pool kunci (LAZY sementara`ESSENTIALS`EAGER)

== Agen Khusus: Tim Virtual

Governance tidak hanya berisi file pasif. Saya telah mengformalkan beberapa**peran agen spesialis**dalam file LAZY khusus, yang menentukan workflow yang diharapkan sesuai jenis tugas.

|===
|agen |File |peran |Proyek |**mengkode** |`CODER.adoc` |Implementasi FTL/CSS/JS, tag semantik, kriteria aksesibilitas |cheroliv.com |**SCRUM Master** |`SCRUM_MASTER.adoc` |Perencanaan US, pembagian menjadi subtugas, deteksi dependensi |cheroliv.com |**PlantUML Designer** |`PLANTUML_DESIGNER.adoc` |Pembuatan diagram, sintaksis PUML, integrasi JBake |cheroliv.com
|===

file`CODER.adoc`di atas`cheroliv.com`mengandung aturan konkret : _Hanya satu`<h1>`per halaman_, _Mengawali jalur dengan`${content.rootpath}`_, _Mendeklarasikan bahasa`<html lang="${content.lang!"fr"}">`_. Konvensi ini, yang ditulis sekali, dipatuhi secara otomatis oleh agen sejak sesi 1.

File File`SCRUM_MASTER.adoc`Menetapkan struktur hasil kerja:**Tujuan**, **tugas**(koordinat y dengan alokasi),**Kriteria penerimaan**, **Risiko**. Saat saya meminta rencana tindakan, agen menghasilkan struktur ini tanpa saya memintanya. Tata kelola**program**agen.

==== Ketika Agen Spesialis Menjadi Penting

Pembuatan agen spesialis mengikuti kurva alami. Di awal sebuah proyek, Anda tidak memerlukannya —`AGENT.adoc`Cukup lebih dari cukup. Tetapi ketika proyek bertumbuh (katakanlah, di atas 20 sesi), dua sinyal harus memperingatkanmu :

1. Agen mengcampur konvensi dari dua bidang yang berbeda (misalnya: sintaksis PlantUML dan aturan CSS)
2. Anda menghabiskan lebih banyak waktu untuk memperbaiki agen mengenai konvensi yang sudah Anda jelaskan kepadanya 5 kali

pada`cheroliv.com`, itu terjadi di sesi... 1. Ya, sejak awal. Karena proyek ini adalah situs web dengan tiga bahasa (FTL, CSS, JS), konten AsciiDoc, dan diagram PlantUML — tiga bidang yang tidak ada hubungannya. Agen CODER perlu mengetahui ukuran font dan media query; agen PLANTUML_DESIGNER perlu mengetahui sintaks.`@startuml`. Tanpa pemisahan, agen CODER memberikan saya diagram, dan sebaliknya. Kekacauan.

Di atas`jhipster-gradle-plugins`, saya telah membuat dua agen spesial yang disesuaikan untuk pengembangan plugin Gradle :`PLUGIN_DEVELOPER.adoc` et `BACKLOG_MANAGER.adoc`. Yang pertama mengkodekan semua konvensi Kotlin/Gradle (tidak ada`!!`, kelas data untuk model,`@TaskAction`untuk tugas). Yang kedua tahu bahwa`persistence`harus stabil sebelum`assistant`tidak memulai pengembangannya — sebuah dependensi kritis dalam mono-repo

Kesalahan yang harus dihindari: membuat terlalu banyak agen terlalu cepat.`plantuml-plugin`telah menunggu sesi 108 sebelum mengformalisasi agen khusus untuk kolam kunci API. Sebelum itu, konteks bisnis berada di`AGENT.adoc`. Catatan praktis: agen spesialis dapat dibenarkan ketika bidang bisnisnya melebihi 100 baris dokumentasi.

==== Konvensi Penamaan Sesi

Sepertinya detail yang terlihat sepele tetapi menjadi kritis ketika mencapai 100 sesi. Bagaimana menamai file arsip?

Saya belajar dengan cara keras bahwa sebuah konvensi diperlukan — empat proyek, empat format berbeda di awal, dan saya tidak bisa mengikuti. Hari ini, konvensi yang telah saya stabilkan adalah:

Contoh konkret :

* `1-chore-migration-gouvernance-agent.adoc`— sesi 1, tipe tugas
* `10-solidification-tests.adoc`— sesi 10, tanpa jenis eksplisit (subjek sudah cukup)
* `036-debug-graphify-symlink-epic9.adoc`— sesi 36 dengan nomor 3 digit untuk pengurutan

Nomor sesi adalah kriteria pengurutan utama. Proyek yang menggunakan nomor dengan 3 digit (001, 036, 133) menghindari masalah pengurutan leksikografis ketika melebihi 99. Itulah yang saya gunakan sekarang pada`magic-stick`:`001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`.

Tipe bersifat opsional dan diturunkan dari kata kunci sesi (debug, feature, refactor, docs, chore, test). Subjek dalam kebab-case adalah bagian paling penting: ia harus memungkinkan untuk menemukan sesi tanpa membuka file. Jika Anda bertanya « Session mana yang di mana kita memperbaiki timeout tes integrasi? », jawabannya adalah`124-fix-timeout-integration-test.adoc`.

Untuk sesi historis yang direkonstruksi (proyek yang lahir sebelum tata kelola), saya menggunakan angka negatif. pada`cheroliv.com`, sesi -6 hingga 0 mencakup seluruh sejarah pra-pemerintahan proyek. Dan untuk sesi « tidak terdokumentasi » atau yang hilang, saya membuat entri dalam`SESSIONS_HISTORY.adoc`tanpa arsip yang sesuai, dengan skor`?`. Ini lebih jujur daripada berpura-pura.

[plantuml, format=svg, id=diag-naming-convention, alt="Arbre de décision pour le nommage des fichiers de session"]

==== TEST_COVERAGE_ANALYSIS.adoc` — Langkah 5 Dijelaskan

Langkah 5 dari prosedur penutupan sesi adalah yang paling misterius. Dia berkata “Memperbarui`TEST_COVERAGE_ANALYSIS.adoc`jika tes telah ditambahkan atau diubah. » Tapi bagaimana struktur file ini?

pada`plantuml-plugin`, ia telah berkembang dari beberapa baris menjadi struktur lengkap. Berikut bentuk yang stabilnya:

[source]