@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 "移行\nAsciiDoc"
10 is "Eager/Lazy\n形式化された"
62 is "安全ルール
(site.yml)"
87 is "クラック
コンテキスト"
109 is "最適化
-60% トークン"
133 is "133回のセッション\n240テスト合格"

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 "プロジェクトのルート (Eager - 自動読み込み)" {
    component "<b>AGENT.adoc</b>
絶対のルール
構造 & 慣習" as AGENT
    component "<b>PROMPT_REPRISE.adoc</b>
セッション Nのミッション
概要 N-1" as PROMPT
    component "<b>INDEX.adoc</b>
エントリーポイント
ルール + セッション" as INDEX
    component "<b>*_ESSENTIALS.adoc</b>\n業務コンテキスト\n重要" as ESS
}

package ".agents/ (Lazy - オンデマンドで読み込み)" {
    component "<b>sessions/N-*.adoc</b>\n詳細なアーカイブ\n決定 & 出力" as SESS
    component "<b>SESSIONS_HISTORY.adoc</b>
サマリーテーブル
日付/タイプ/スコア" as HIST
    component "<b>PROCEDURES.adoc</b>
セッション終了テンプレート
6ステップ" as PROC
    component "<b>*_REFERENCE.adoc</b>
完全なアーキテクチャ
技術参照" as REF
    component "<b>COMPLETED_TASKS_ARCHIVE</b>
完了したタスク
月ごと" as ARCH
    component "<b>AGENT_MODUS_OPERANDI.adoc</b>
戦略ドキュメント
方法論" as MOD
    component "<b>*_REFERENCE.adoc</b>
Boot tests, A/B partition
特定のコンテキスト" as SPEC
}

AGENT --> PROMPT : "参考文献"
AGENT --> INDEX : "参考文献"
INDEX --> SESS : "インデックスする"
INDEX --> HIST : "インデックスする"
INDEX --> PROC : "参照"
INDEX --> ARCH : "参照"
INDEX --> REF : "参照"
PROMPT --> SESS : "アーカイブ N-1"
PROMPT --> ESS : "ビジネスコンテキスト 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 |
----

(No content)`*_ESSENTIALS.adoc`-- Session 109（plantuml-plugin）による最近の追加で、Eagerコンテキストをさらに最適化。API キー プール上のビジネス コンテキスト 200 行をロードする代わりに、必須の 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`一度も充電されていなかった。 エージェントは私が読むように言ったものだけを、各セッションごとに手動で読んでいた。 これはセッション11の`bakery-plugin`私がその欠如に気づいたとき`opencode.json`. 私はそれを作成しました — そしてセッション12は他のセッションと同様に開始されました。

このファイルは今では私にとってとても明白で、もうそれについて考えることすらしなくなった。ツールに詳しすぎる開発者が陥りがちな典型的なミスだ。今日では、私はこれを常に*avant*作成するようにしている。`AGENT.adoc`. これが最初の石です。

==== INDEX.adoc`の二重性

もう一つ、明確にすべき微妙な点があります：`INDEX.adoc`に住んでいる`.agents/`— LAZYとして提示したフォルダ。しかし、私はこれをすべてのテーブルでEAGERとしてリストしている。ここには明らかな緊張がある。

実際の現場 : ファイル`.agents/INDEX.adoc`自動的に正しく読み込まれ、同様に`AGENT.adoc` et `PROMPT_REPRISE.adoc`. 彼らは中に`.agents/`組織上の理由により — 根を侵さないように — しかし、彼らの動作はEAGERである。

上に`plantuml-plugin`, `INDEX.adoc`これは200行で、過去のセッションの教訓である歴史とともに、絶対に*完全な*ルール、スコア付きのEPIC、そしてプロジェクトのポートフォリオを含んでいます。これはエージェントが「現在の状況」を確認するために参照するドキュメントです。Sur`bakery-plugin`, 最近のロードマップとセッションで150行です。

意図的な冗長性の間`AGENT.adoc` et `INDEX.adoc`� 驚くかもしれません。 絶対的なルールは両方に存在します。 なぜ？ なぜなら、それらは二つの異なる役割を果たしているから：の中で`AGENT.adoc`, それらは*説明的*です (ルールのストーリーテリング、学んだ教訓) ; 中で`INDEX.adoc`, それらは *実行可能* (裸のルール、正当化なし、迅速な参照のため)。 エージェントは読む`AGENT.adoc`一度理解するために；彼は読み返す`INDEX.adoc`各セッションで*適用*する。2つの用途、2つのフォーマット。

[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
(根 — EAGER)" as AGENT #E3F2FD {
  rectangle "**ナラティブフォーマット**
ルールのストーリーテリング
学んだ教訓、コンテキスト" as NARR
  rectangle "🏗️**完全なアーキテクチャ**
プロジェクト構造、コンポーネント
詳細なユーザーストーリーバックログ" as ARCHI
  rectangle "📋 **解説ルール**
なぜルールは存在するのか
インシデントの履歴" as EXPL
}

rectangle "INDEX.adoc\n(.agents/ — EAGER)" as INDEX #E8F5E9 {
  rectangle "⚡ **エグゼクティブフォーマット**
裸のルール、正当化なし
迅速な相談" as EXEC
  rectangle "📊 **Roadmap & EPICs**
サマリーテーブル
進行状況, スコア, 優先度" as ROAD
  rectangle "🌐 **プロジェクトポートフォリオ**
横断ビュー
5つの同期プロジェクト" as PORT
}

AGENT --> INDEX : "Agent が AGENT.adoc を
1 回 読んで **理解する**"
INDEX --> AGENT : "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
----

この意図的な冗長性は設計上の選択です。これらはEAGERトークンの追加で約50行消費しますが、エージェントが常にルールを目の前に持てるように保証します。つまり、即時の従順を助ける簡潔なフォーマットでも同様です。

=== LAZY ファイル: 所有者のためのマニュアル

これらのファイルは[場所]に存在します`.agents/`それらは、エージェントが必要とする時だけ読まれる。それらは、方法の真の財産を構成する。なぜなら、それらは現在のコンテキストを汚すことなくプロジェクトの知識を蓄積するからである。

[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\n(テンプレート セッション)" as ASM
  file "SESSION_CHECKLIST.adoc
(いつ変更するか)" as CHK
  file "PROCEDURES.adoc\n(6段階 + LAZY/EAGER)" as PRO
  file "SESSIONS_HISTORY.adoc\n(すべてのセッション)" as HIS

  folder "セッション/" as SESS {
    file "1-chore-migration.adoc" as S1
    file "109-形式化-lazy.adoc" as S109 #FFECB3
    file "133-epic11-article.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 "プロンプトアーカイブ/" 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/`上に`plantuml-plugin`, 最も成熟したプロジェクト。 注目してください 3層の深さ : ルートファイル（メタデータ）, ディレクトリ`sessions/`（年代順アーカイブ）, と ファイル`archives/`(集約と要約)。この深さが、単なるTODOファイルのガバナンスを変える**完全な組織記憶**。

**.agents/sessions/{N}-{titre}.adoc**-- 各セッションの詳細なアーカイブ。現在：

* `plantuml-plugin`:**133件のアーカイブ済みセッション**(セッション1から133まで)
* `bakery-plugin` : **11 セッション**
* `magic-stick` : **23セッション**
* `cheroliv.com` : **9 正式なセッション**+ 7セッション（プリシステム）が遡及的に再構築されました

各アーカイブはセッションの完全なコンテキスト、行われた決定、遭遇した問題とその解決、実行されたコマンドとその出力を含みます。

**.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の手法を文書化し、従うべきパターンと避けるべきアンチパターンを示しています。LAZYであるのは、エージェントが各セッションごとに戦略全体を読み直す必要がなく、あいまいさがあるときだけだからです。

(Empty)`*_REFERENCE.adoc`** -- プロジェクト固有の技術的参照。について`magic-stick`, 密集した2つの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 pendant que`ESSENTIALS`です EAGER)

== �専門エージェント：仮想チーム

ガバナンスは受動的なファイルに限定されません。私は形式化した**�専門エージェントの役割**専用のLAZYファイル内に、タスクの種類に応じた期待されるワークフローが定義されています。

|===
|エージェント |ファイル |役割 |プロジェクト |**コードを書く** |`CODER.adoc` |FTL/CSS/JS の実装、セマンティックタグ、アクセシビリティ基準 |cheroliv.com |**スクラムマスター** |`SCRUM_MASTER.adoc` |ユーザーストーリーの計画、サブタスクへの分割、依存関係の検出 |cheroliv.com |**PlantUML デザイナー** |`PLANTUML_DESIGNER.adoc` |�図の作成, PUML構文, JBake統合 |cheroliv.com
|===

ファイル`CODER.adoc`上`cheroliv.com`具体的なルールが含まれています：_一つだけ`<h1>`python print("ページごとに、パスにプレフィックスをつける")`${content.rootpath}`_, _Déclarer la langue `<html lang="${content.lang!"fr"}">`_. これらの規則は一度書かれると、セッション1からエージェントによって自動的に遵守されます。

ファイル`SCRUM_MASTER.adoc`納品物の構造を課す：**目的**, **タスク**(代入付き座標),**受入基準**, **リスク**. 私がアクションプランを要求すると、エージェントは私が求めずにこの構造を生成します。ガバナンス**プログラム**エージェント。

==== 専門エージェントが不可欠になる時

専門エージェントの作成は自然な曲線に従います。プロジェクトの初めには、これらは必要ありません —`AGENT.adoc`十分です。しかしプロジェクトが大きくなる（たとえば、20セッションを超える場合）と、2つのシグナルがあなたに警告を発すべきです。

1. エージェントは2つの異なる分野の規則を混在させます（例：PlantUML構文とCSSルール）
2. あなたは、エージェントにすでに5回説明した慣習について訂正することに、もっと時間を費やしています。

上に`cheroliv.com`, これはセッションで起こったことです... 1. はい、最初からです。なぜなら、このプロジェクトはFTL、CSS、JSの3つの言語を使ったウェブサイトであり、AsciiDocのコンテンツとPlantUMLのダイアグラムを含んでいるからです — これらは全く関係のない3つの分野です。CODERエージェントはフォントサイズとメディアクエリを知る必要があり、PLANTUML_DESIGNERエージェントは構文を知る必要があります`@startuml`. 分離なく、エージェント CODER が私にダイアグラムを提案し、その逆も同様だった。混乱。

上`jhipster-gradle-plugins`, 私はGradleプラグイン開発に適した2つの専門エージェントを作成しました：`PLUGIN_DEVELOPER.adoc` et `BACKLOG_MANAGER.adoc`. 最初はすべての Kotlin/Gradle の規約をエンコードします（ただし`!!`, データクラス（モデル用）,`@TaskAction`タスクのため)。2番目は知っている`persistence`それになる前に安定している必要がある`assistant`開発を開始しない — mono-repo内のクリティカルな依存関係。

犯してはいけない間違い：早すぎる段階でエージェントを作りすぎること`plantuml-plugin`セッション108を待ち、APIキーのプール用の専門エージェントを正式化しました。それ以前は、業務コンテキストは`AGENT.adoc`. 経験則：専門的なエージェントは、その業務ドメインのドキュメントが100行を超えるとき正当化される。

==== セッション命名規約

小さくて取るに足らない詳細だが、100回のセッションに到達すると重要になる。アーカイブファイルはどのように命名すればよいでしょうか？

私は苦い経験から、規約が必要だと学びました — 初めは4つのプロジェクト、4つの異なるフォーマットがあり、訳がわからなくなりました。今日、私が確立した規約は：

具体例:

* `1-chore-migration-gouvernance-agent.adoc`— セッション 1、タイプの雑用
* `10-solidification-tests.adoc`— セッション10、明示的な型なし (主題だけで十分)
* `036-debug-graphify-symlink-epic9.adoc`— 3桁の番号付きソート用セッション36

セッション番号が主要なソート基準です。3桁の番号（001、036、133）を使用するプロジェクトは、99を超えたときの辞書順ソートの問題を回避します。これが今私が使っているものです`magic-stick`:

(Note: a leading space, colon, trailing space)`001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`。

タイプはオプションであり、セッションのキーワード (debug, feature, refactor, docs, chore, test) から派生します。kebab-case のサブジェクトは最も重要な部分です：ファイルを開かずにセッションを見つけられるようにする必要があります。「テストの統合のタイムアウトを修正したセッションはどれだったかな？」と疑問に思う場合、答えは`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]