@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false

title تغییر جلسات — از جلسه 1 تا 150+
legend top
    |= Couleur |= Projet |
    | <#4CAF50> | cheroliv.com |
    | <#2196F3> | plantuml-plugin |
    | <#FF9800> | bakery-plugin |
    | <#9C27B0> | magic-stick |
endlegend

concise "جلسات فعال" as S

@S
0 is ".md خام"
1 is "هجرت
AsciiDoc"
10 is "Eager/Lazy
فرمالیزه"
62 is "قانون ایمنی\n(site.yml)"
87 is "شکستگی
بافت"
109 is "بهینه‌سازی
-60% توکن‌ها"
133 is "133 sessions\n240 tests PASS"

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 "ریشهٔ پروژه (حماسی - بارگذاری خودکار)" {
    component "<b>AGENT.adoc</b>
قوانین مطلق
ساختار و کنوانسیون‌ها" as AGENT
    component "<b>PROMPT_REPRISE.adoc</b>
مهمت جلسه N
خلاصه N-1" as PROMPT
    component "<b>INDEX.adoc</b>\nنقطه ورودی\nقوانین + جلسات" as INDEX
    component "<b>*_ESSENTIALS.adoc</b>\nمحیط کاری\nبحرانی" as ESS
}

package ".agents/ (Lazy - بارگذاری عند الطلب)" {
    component "<b>sessions/N-*.adoc</b>
آرشیوهای دقیق
تصمیمات & خروجی" as SESS
    component "<b>SESSIONS_HISTORY.adoc</b>\nجدول خلاصه\nتاریخ/نوع/امتیاز" as HIST
    component "<b>PROCEDURES.adoc</b>
قالب‌های پایان جلسه
6 مرحله" as PROC
    component "<b>*_REFERENCE.adoc</b>
معماری کامل
مراجع فنی" as REF
    component "<b>COMPLETED_TASKS_ARCHIVE</b>\nوظائف تکمیل‌شده\nماهانه" as ARCH
    component "<b>AGENT_MODUS_OPERANDI.adoc</b>\nمستندات استراتژی\nروش‌شناسی" as MOD
    component "<b>*_REFERENCE.adoc</b>\nBoot tests, A/B partition\nبخش‌های خاص" as SPEC
}

AGENT --> PROMPT : "منابع"
AGENT --> INDEX : "منابع"
INDEX --> SESS : "فهرست"
INDEX --> HIST : "فهرست"
INDEX --> PROC : "مرجع"
INDEX --> ARCH : "مرجع"
INDEX --> REF : "مرجع"
PROMPT --> SESS : "آرشیو N-1"
PROMPT --> ESS : "کontekst کاری 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`** -- یک افزودن تازه (جلسه 109، افزونه plantuml-plugin) برای بهینه‌سازی بیشتر زمینه Eager. به جای بارگذاری 200 خط از زمینه کاری بر روی havuz کلید API، من 50 خط از جوهر را بارگذاری می‌کنم، و 150 خط دیگر در حالت LAZY داخل`*_REFERENCE.adoc`.

نتیجهٔ اندازه‌گیری شده : عبور از**~25k توکن EAGER به ~10k توکن**(سود 60%). عامل دیگر به یادآوری‌های پرانرژی نیاز ندارد.

==== لینک گمشده : `opencode.json

باید به شما بگویم یک چیزی که تقریباً فراموش کردم اسناد کنم. در بالای تمام این فایل‌های `.adoc`، یک فایل JSON کوچک وجود دارد که بدون آن هیچ‌چیز کار نمی‌کند. اسمش`opencode.json`و آن شش خط است. به حرفی، شش خط.

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

این فایل به Opencode می‌گوید: « هنگام شروع، بارگذاری `AGENT.adoc`خودکارانه. » بدون او، عامل یک صفحه سفید دقیقاً همانند چیزی که من در ابتدای مقاله توصیف کردم. با او، عامل قبلاً در دستش دارد قوانین قطعی، معماری پروژه و دستورات ضروری — حتی قبل از اینکه من سلام بگویم.

من تصادفی اهمیت این فایل را کشف کردم. روی`bakery-plugin`, آن وجود نداشت. من می‌پرسیدم چرا عامل به‌طور منظم در این پروژه « گم‌شده » بیشتر از دیگر پروژه‌ها بود. قوانین مطلقاً به خوبی در`AGENT.adoc`— اما`AGENT.adoc`به هرگز بارگذاری نشده بود. عامل تنها همان چیزی را که من به او می‌گفتم بخواند، به‌صورت دستی، در هر جلسه می‌خواند. این جلسه ۱۱ بود از`bakery-plugin`وقتی متوجه شدم عدم وجود`opencode.json`. من آن را ایجاد کردم — و جلسه 12 همانند سایر جلسات آغاز شد.

این فایل برایم الآن اینقدر واضح شده که دیگر اصلاً به آن فکر نمی‌کردم. یک اشتباه کلاسیک برای توسعه‌دهنده‌ای که ابزارش را خیلی خوب می‌شناسد. امروز من آن را به‌طور منظم *قبل* می‌سازم`AGENT.adoc`. این اولین سنگ است.

==== دوالیت `INDEX.adoc

یک ظریف دیگر که باید صریح شود:`INDEX.adoc`زندگی می‌کند در`.agents/`— یک فایل که من آن را به‌عنوان LAZY ارائه دادم. اما من آن را در تمام جدول‌هایم به‌عنوان EAGER فهرست می‌کنم. اینجا یک تنش واضح وجود دارد.

واقعیت الميدان: پرونده‌ها`.agents/INDEX.adoc`به‌صورت خودکار در ابتدای جلسه به خوبی بارگذاری می‌شوند، به همان ترتیب که`AGENT.adoc` et `PROMPT_REPRISE.adoc`. آنها در`.agents/`به دلایل سازماندهی — نه ریشه را اشغال نکنیم — اما رفتار آنها EAGER است.

روی`plantuml-plugin`, `INDEX.adoc`شامل ۲۰۰ خط است و حاوی قوانین مطلق *کامل* با تاریخچهٔ آن (دروس جلسات گذشته) است، EPICs با امتیازات و portfolio پروژه‌ها. این اسناد است که عامل آن را برای درک «کجا هستیم» معاینه می‌کند. بر`bakery-plugin`, او 150 خط با نقشه مسیر و جلسات اخیر می‌نویسد.

تکرار عمدی بین`AGENT.adoc` et `INDEX.adoc`ممکن است شگفت‌انگیز باشد. قوانین مطلق در هر دو حضور دارند. چرا؟ چون آنها دو نقش مختلف را بر عهده دارند: در`AGENT.adoc`, آن‌ها *توضیحی* هستند (داستان‌گویی از قانون، درس آموخته) ; در`INDEX.adoc`, آنها *اجراپذیر* (قانون صریح، بدون توجیه، برای مشورت سریع). نماینده می‌خواند`AGENT.adoc`یک بار برای *comprendre* ; او دوباره می‌خواند`INDEX.adoc`در هر جلسه برای *اعمال*. دو کاربرد، دو فرمت.

[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 دوانگی AGENT.adoc ←→ INDEX.adoc
left to right direction

rectangle "AGENT.adoc\n(ریشه — EAGER)" as AGENT #E3F2FD {
  rectangle "📖 **فرمت روایی**
روایت کردن قانون
درس آموخته، بستر" as NARR
  rectangle "🏗️ **معماری کامل**
ساختار پروژه، اجزاء
بک‌لاگ مفصل US" as ARCHI
  rectangle "📋 **قوانین توضیحی**
چرا این قانون وجود دارد
تاریخچه حادثه" as EXPL
}

rectangle "INDEX.adoc
(.agents/ — EAGER)" as INDEX #E8F5E9 {
  rectangle "⚡ **فرمت اجرایی**
قاعده بی‌پوشش، بدون توجیه
مشاوره سریع" as EXEC
  rectangle "📊 **نقشه راه & EPICs**
جدول خلاصه
پیشرفت، امتیاز، اولویت" as ROAD
  rectangle "**پورتفوی پروژه‌ها**
دید افقی
5 پروژه همگام‌سازی‌شده" as PORT
}

AGENT --> INDEX : "عامل AGENT.adoc را می‌خواند\nیک بار تا **comprendre**"
INDEX --> AGENT : "عامل فایل INDEX.adoc را دوباره خواند
هر جلسه برای **اعمال**"

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

این redundantitu که به‌عنوان یک گزینش طراحی است، حدود ۵۰ خط توکن EAGER اضافی مصرف می‌کند — اما تضمین می‌کند که عامل همیشه قواعد را در پیش‌ روی خود داشته باشد، حتی در فرم خلاصه‌ای که اطاعت فوری را تسهیل می‌کند.

=== فایل‌های LAZY: راهنمای مالک

این فایل‌ها در`.agents/`و فقط وقتی که عامل به آنها نیاز دارد، خوانده می‌شوند. آن‌ها واقعی‌ترین ثروت روش را تشکیل می‌دهند، زیرا دانش پروژه را جمع‌آوری می‌کنند بدون/context فعلی را آلوده نکنند.

[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 خط)" as IDX #E8F5E9
  file "AGENT_SESSION_MANAGER.adoc
(جلسه الگو)" as ASM
  file "SESSION_CHECKLIST.adoc
(زمان تغییر)" as CHK
  file "PROCEDURES.adoc
(6 مراحل + LAZY/EAGER)" as PRO
  file "SESSIONS_HISTORY.adoc
(همه جلسات)" as HIS

  folder "جلسات/" as SESS {
    file "1-chore-migration.adoc" as S1
    file "109-فرم‌سازی-سست.adoc" as S109 #FFECB3
    file "133-epic11-مقاله.adoc" as S133
    file "... +130 دیگر" as SMORE
  }

  folder "بایگانی‌ها/" as ARCH {
    file "COMPLETED_TASKS_2026-04.adoc" as CTA
    file "SESSIONS_HISTORY_83-95.adoc" as SHIST
    folder "خلاصه‌های جلسات/" 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 : "فهرست"
IDX --> HIS : "فهرست"
IDX --> ARCH : "مرجع"

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

@enduml
----

ساختار واقعی پوشه را درخت بالا نشان می‌دهد`.agents/`sur? Wait, we need Persian: "روی". So output: " روی". Let's output that.

</think>
 روی`plantuml-plugin`، پروژه بالغ‌ترین. توجه کنید به عمق در سه لایه: فایل‌های ریشه (متراداده), پوشه`sessions/`(آرشیوهای زمانی), و پرونده`archives/`( تجمیع‌ها و خلاصه‌ها ). این عمق است که حاکمیت یک فایل TODO ساده را به**حافظه سازمانی کامل**.

**.agents/sessions/{N}-{titre}.adoc**-- بایگانی‌های جزئی هر جلسه. در حال حاضر :

* `plantuml-plugin`:**133 جلسات بایگانی شده**(از جلسه 1 تا 133)
* `bakery-plugin`:**11 جلسات**
* `magic-stick`:**23 جلسات**
* `cheroliv.com`:**9 جلسه رسمی**+ 7 جلسات پیش‑سیستم بازسازی شده به‌صورت رجوعی

هر بایگانی شاملcontext کامل جلسه، تصمیمات گرفته شده، مشکلات مواجه شده و راه‌حل آن‌ها، دستورات اجرا شده و خروجی آن‌ها است.

**.agents/SESSIONS_HISTORY.adoc**-- جدول خلاصه‌ای از تمام جلسات با یک امتیاز. مثال بر`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**-- وظائف تکمیل‌شده ماهانه بایگانی می‌شوند تا از بارگذاری بیش از حد البکلگ فعال جلوگیری شود. وقتی یک داستان کاربر تکمیل شود، اینجا منتقل می‌شود. البکلگ قابل خواندن می‌شود: حداکثر 10 مورد فعال.

**.agents/PROCEDURES.adoc**-- قالب‌های دقیق از رویه پایان جلسه. طولانی، اما یکبار توسط عامل خوانده می‌شود وقتی روش را یاد می‌گیرد. سپس، رویه به‌صورت مکانیکی می‌شود.

**.agents/AGENT_MODUS_OPERANDI.adoc**-- مستندات استراتژیک کامل. روی`plantuml-plugin`, این فایل می‌کند**900+ خط**و در واقع به نام`AGENT_METHODOLOGIES.adoc`— من نام را بین نوشتن این مقاله و پیاده‌سازی واقعی تغییر دادم. چنین اختلاف نام‌گذاری در یک سیستم حرفه‌ای که در حال تحول است، اجتناب‌ناپذیر است. مهم این است که کنوانسیون نام‌گذاری باشد: اگر فایل *روش* را مستند می‌کند، با`AGENT_`یا یک پیشوند صریح. روش Eager/Lazy را مستند می‌کند، الگوهایی که باید دنبال کرد و anti‑pattern‑هایی که باید اجتناب کرد. چون یک agent نیازی ندارد که در هر جلسه، استراتژی کامل را دوباره بخواند، بلکه تنها زمانی که ambiguït (ابهام) وجود دارد.

**`*_REFERENCE.adoc`** -- المراجع الفنية الخاصة بالمشروع. Sur`magic-stick`, دو فایل LAZY πυκν� :

* `AB_PARTITION_REFERENCE.adoc`(147 خط) -- معماری پارتیشن A/B GPT, اسکریپت‌ها`update-system.sh`, اندازهای تخمین‌ شده، مکانیزم بازگشت
* `BOOT_TEST_REFERENCE.adoc`(144 خط) -- روش QEMU + VNC برای آزمایش بوت ISO بدون سخت‌افزار فیزیکی، چک‌لیست BIOS/UEFI، محدودیت‌های CI/CD

بر`plantuml-plugin`:

* `ARCHITECTURE.adoc`(134 خط) -- ساختار 11 کلاس داده، نکات توجه (اخطارهایی که باید اجتناب شوند)، دستورات تست بهینه‌شده
* `API_KEY_POOL_REFERENCE.adoc`-- جزئیات کامل مجموعه کلید (LAZY در حالی که`ESSENTIALS`است EAGER)

== عملئان تخصصی : یک تیم مجازی

حاکمیت فقط به فایل‌های پسیو محدود نیست. من آن‌ها را رسمی کردم**نقش‌های عوامل تخصصی**در فایل‌های LAZY مخصص، که workflow مورد انتظار را بر اساس نوع وظیفه تعریف می‌کنند.

|===
|نماینده |فایل |نقش |پروژه |**کد کردن** |`CODER.adoc` |پیاده‌سازی FTL/CSS/JS، برچسب‌های معنایی، معیارهای دسترسی |cheroliv.com |**اسکرام ماستر** |`SCRUM_MASTER.adoc` |برنامه‌ریزی US, تقسیم به زیرکارها, تشخیص وابستگی‌ها |cheroliv.com |**طراح PlantUML** |`PLANTUML_DESIGNER.adoc` |ایجاد نمودارهای، سینتکس PUML، ادغام JBake |cheroliv.com
|===

فایل`CODER.adoc`بر`cheroliv.com`شامل قوانین concretes است: _یک`<h1>`بر حسب صفحه_ _پیشوندگذاری مسیرها با`${content.rootpath}`_, _اعلان کردن زبان`<html lang="${content.lang!"fr"}">`_. این کنوانسیون‌ها، که یک بار نوشته شده‌اند، به‌طور خودکار از جلسه ۱ توسط عامل احترام گذاشته می‌شوند.

فایل`SCRUM_MASTER.adoc`یک ساختار تحویل‌پذیر اعمال می‌شود :**هدف**, **کارها**(به ترتیب با تخصیص),**معیارهای پذیرش**, **خطرات**. وقتی که من یک برنامه عمل می‌طلبم، عامل این ساختار را بدون اینکه من آن را درخواست کنم، تولید می‌کند. الحکومت**برنامه**facteur.

==== وقتی که نمایندگان تخصصی ضروری می‌شوند

ایجاد عوامل مخصوص یک منحنی طبیعی را دنبال می‌کند. در ابتدای یک پروژه، به آن نیاز ندارید —`AGENT.adoc`بسیار کافی است. اما وقتی پروژه رشد می‌کند (بیایید بگوییم، بیش از ۲۰ جلسه)، دو سیگنال باید شما را اخطار دهند:

1. نماینده کنوانسیون‌های دو حوزه متمایز را ترکیب می‌کند (مثلاً: سینتکس PlantUML و قوانین CSS)
2. شما زمان بیشتری را برای اصلاح عامل دربارهٔ قوانین صرف می‌کنید که قبلا 5 بار به او توضیح داده‌اید.

بر`cheroliv.com`این اتفاق در جلسه رخ داد... 1. بله، از ابتدا. زیرا این پروژه یک وب‌سایت با سه زبان (FTL, CSS, JS)، محتوای AsciiDoc و نمودارهای PlantUML است — سه حوزه‌ای که هیچ ارتباطی ندارند. عامل CODER باید بداند سایزهای فونت و media queries چگونه باشند؛ عامل PLANTUML_DESIGNER باید بداند سینتکس را.`@startuml`. بدون جدایی، عامل CODER به من نمودارهای پیشنهاد می‌داد و به‌طور معکوس. بی‌ترتیبی.

روی`jhipster-gradle-plugins`, من دو عامل تخصصی سازگار با توسعه پلاگین‌های Gradle ایجاد کرده‌ام :`PLUGIN_DEVELOPER.adoc` et `BACKLOG_MANAGER.adoc`. اولین کدگذاری می‌کند تمام اتفاقيات Kotlin/Gradle (بدون`!!`, کلاس‌های داده برای مدل‌ها,`@TaskAction`برای کارها). دوم می‌داند که`persistence`باید پیش از آن پایدار باشد`assistant`نه توسعه آن را شروع نمی‌کند — یک وابستگی حرج در یک مخزن تک‌ماگولار.

خطایی که نباید مرتکب شود: ایجاد بیش از حد نمایندگان زود.`plantuml-plugin`او تا قبل از جلسه ۱۰۸ صبر کرد تا یک عامل مخصص برای مجموعه کلید API را تثبیت کند. پیش از آن، زمینه کسب‌وکار در ... قرار داشت`AGENT.adoc`. قاعدهٔ تجربی : یک عامل تخصصی موجه است وقتی که حوزهٔ کاری او بیش از ۱۰۰ خط مستند باشد.

==== کنوانسیون نامگذاری جلسات

یک جزئی که به‌نظر بی‌اهمیت می‌آید اما وقتی به 100 جلسه می‌رسیم، به‌اهمیت می‌رسد. نام فایل‌های بایگانی را چگونه انتخاب کنیم؟

من به سخت‌طریق یاد گرفتم که یک کنوانسیون لازم است — چهار پروژه، چهار قالب مختلف در ابتدا، و من نتوانستم پی ببرم. امروز، کنوانسیون که من تثبیت کرده‌ام، این است:

نمونه‌های ملموس :

* `1-chore-migration-gouvernance-agent.adoc`— جلسه 1، نوع کار
* `10-solidification-tests.adoc`— جلسه ۱۰، بدون نوع صریح (موضوع کافی است)
* `036-debug-graphify-symlink-epic9.adoc`— جلسه 36 با شماره 3 رقم برای مرتب‌سازی

شماره جلسه معیار اصلی مرتب‌سازی است. پروژه‌هایی که از شماره‌های سه رقمی (001، 036، 133) استفاده می‌کنند، مشکلات مرتب‌سازی لیექსیکافیک را وقتی عدد ۹۹ را فراتر می‌رود، جلوگیری می‌کنند. این همان چیزی است که من اکنون از آن استفاده می‌کنم بر`magic-stick`:`001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`.

نوع اختیاری است و از کلیدواژه‌های جلسه (debug, feature, refactor, docs, chore, test) استخراج می‌شود. موضوع در قالب kebab-case، بخش مهم‌ترین است: باید امکان بازگرداندن یک جلسه را بدون باز کردن فایل فراهم کند. اگر می‌پرسید « کدام جلسه بود که timeout تست‌های یکپارچه را رفع کردیم؟ »، پاسخ این است`124-fix-timeout-integration-test.adoc`.

برای جلسات تاریخی بازسازی‌شده (پروژه‌های متولد پیش از حاکمیت)، شماره‌های منفی استفاده می‌کنم. بر`cheroliv.com`, جلسات -6 تا 0 تمام تاریخ پیش‌حکومت پروژه را پوشش می‌دهند. و برای جلسات « بدون مستندسازی » یا گمشده، یک ورودی ایجاد می‌کنم در`SESSIONS_HISTORY.adoc`بدون بایگانی متناظر، با یک امتیاز`?`. این صریح‌تر از تظاهر کردن است.

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

==== TEST_COVERAGE_ANALYSIS.adoc` — مرحله 5 تجزیه و تحلیل

مرحله 5 از پایان جلسه، بیشترین مبهم است. می‌گوید « به‌روزرسانی`TEST_COVERAGE_ANALYSIS.adoc`اگر تست‌ها اضافه یا تغییر داده شده باشند. اما این فایل چطور است؟

روی`plantuml-plugin`, او از چند خط تا یک ساختار کامل پیشرفته شد. این شکل تثبیت‌شده آن :

[source]