@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 "크래킹\n맥락"
109 is "최적화
-60% 토큰"
133 is "133 세션
240 테스트 통과"

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중요한 비즈니스 컨텍스트" 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 |
----

**`*_ESSENTIALS.adoc`** -- 최근 추가된 사항(세션 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`quand 나는 ...의 부재를 깨달았을 때`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`200줄에 *완전한* 절대 규칙과 그 기록(지난 세션의 교훈)과 함께, EPIC과 점수, 그리고 프로젝트 포트폴리오가 포함되어 있습니다. 이것은 에이전트가 '현재 진행 상황'을 알기 위해 참조하는 문서입니다. 위`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
(근원 — EAGER)" as AGENT #E3F2FD {
  rectangle "📖 **서사 형식**
규칙의 스토리텔링
배운 교훈, 맥락" as NARR
  rectangle "🏗️ **완전한 아키텍처**
프로젝트 구조, 구성 요소
상세한 US 백로그" as ARCHI
  rectangle "📋 **설명 규칙**
왜 규칙이 존재하는가
사건 기록" as EXPL
}

rectangle "INDEX.adoc\n(.agents/ — 열망하는)" as INDEX #E8F5E9 {
  rectangle "⚡ **실행 형식**
규칙 자체만, 정당화 없이
빠른 상담" as EXEC
  rectangle "📊 **Roadmap & EPICs**\n요약 표\n진행 상황, 점수, 우선순위" as ROAD
  rectangle "🌐 **프로젝트 포트폴리오**
횡단 뷰
5개의 동기화된 프로젝트" as PORT
}

AGENT --> INDEX : "에이전트가 AGENT.adoc를 읽음\n이해하기 위해 한 번"
INDEX --> AGENT : "Agent relit INDEX.adoc\n각 세션에 **적용하기 위해**"

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\n(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-일-마이그레이션.adoc" as S1
    file "109-정식화-게으른.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`, 가장 성숙한 프로젝트. 세 층의 깊이에 주의하세요: 루트 파일(메타데이터), 폴더`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_{월}.adoc**-- 완료된 작업들을 월별로 아카이브하여 활성 백로그를 과부하시키지 않도록 합니다. 사용자 스토리가 완료되면 여기서 이동합니다. 백로그는 읽기 쉬운 상태를 유지하며, 활성 항목은 최대 10개입니다.

**.agents/PROCEDURES.adoc**-- 세션 종료 절차의 상세 템플릿. 길지만, 에이전트가 방법을 배울 때 한 번만 읽음. 이후 절차는 기계적이 된다.

**.agents/AGENT_MODUS_OPERANDI.adoc**-- 전략적 문서 전체. 위에`plantuml-plugin`, 이 파일은**900+ 줄**그리고 실제로 불리는`AGENT_METHODOLOGIES.adoc`— 나는 이 기사를 쓰는 동안과 실제로 적용하는 사이에 이름을 바꾸었다. 이런 종류의 네이밍 차이는 진화하는 수공예 시스템에서는 피할 수 없다. 중요한 것은 이름 짓기 관습이다: 만약 파일이 *메서드*를 문서화한다면, 그것은 ...로 시작한다.`AGENT_`또는 명시적 접두사. Eager/Lazy 방법론을 문서화하고, 따라야 할 패턴과 피해야 할 안티패턴을 설명합니다. 이는 LAZY이기 때문인데, 에이전트는 매 세션마다 전체 전략을 다시 읽을 필요가 없고, 오직 애매함이 있을 때만 그렇게 한다.

**`*_REFERENCE.adoc`** -- 프로젝트에 특화된 기술 참조. 에`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 파일에서, 작업 유형에 따라 예상되는 워크플로우를 정의합니다.

|===
|에이전트 |파일 |역할 |프로젝트 |**코더** |`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>`페이지당_, _경로에 접두사 추가하기`${content.rootpath}`_, _언어를 선언`<html lang="${content.lang!"fr"}">`_. 이러한 협약은 한 번 작성되면 에이전트가 세션 1부터 자동으로 준수합니다.

파일`SCRUM_MASTER.adoc`산출물의 구조를 규정한다 :**목표**, **작업**(할당이 있는 좌표),**수용 기준**, **위험**. 행동 계획을 요청할 때, 에이전트는 내가 요청하지 않았음에도 이 구조를 생성합니다. 거버넌스**프로그램**요원.

==== 전문화된 에이전트가 필수적이 될 때

전문 에이전트의 생성은 자연스러운 곡선을 따릅니다. 프로젝트 초반에는 필요하지 않습니다 —`AGENT.adoc`충분합니다. 하지만 프로젝트가 커질 때 (예를 들어, 20세션을 넘어) 두 가지 신호가 당신을 경고해야 합니다 :

1. 에이전트는 서로 다른 두 분야의 규칙을 혼합합니다(예: PlantUML 구문과 CSS 규칙)
2. 당신은 이미 5번 설명한 관습에 대해 에이전트를 수정하는 데 더 많은 시간을 보냅니다.

위`cheroliv.com`, 세션에 도착했습니다... 1. 예, 처음부터. 왜냐하면 이 프로젝트는 세 가지 언어(`FTL`, `CSS`, `JS`)로 이루어진 웹사이트이며, `AsciiDoc` 콘텐츠와 `PlantUML` 다이어그램이 포함되어 있기 때문입니다 — 세 가지 분야가 전혀 관련이 없습니다. `CODER` 에이전트는 글꼴 크기와 미디어 쿼리를 알아야 하며, `PLANTUML_DESIGNER` 에이전트는 문법을 알아야 합니다.`@startuml`. 분리 없이, CODER 에이전트가 다이어그램을 제시해 주었고, 반대도 마찬가지였다. 혼란.

위에`jhipster-gradle-plugins`, 저는 Gradle 플러그인 개발에 맞춘 두 개의 전문화된 에이전트를 만들었습니다 :`PLUGIN_DEVELOPER.adoc` et `BACKLOG_MANAGER.adoc`. 첫 번째는 Kotlin/Gradle의 모든 규약을 인코딩합니다(아니오`!!`, 모델에 대한 데이터 클래스,`@TaskAction`작업들에 대해). 두 번째는 알고 있다`persistence`안정적이어야만`assistant`개발을 시작하지 않는다 — 모노레포에서의 중요한 의존성

실수하지 말아야 할 것 : 너무 많은 에이전트를 너무 일찍 만드는 것`plantuml-plugin`108번째 세션을 기다린 후 API 키 풀을 위한 전문 에이전트를 공식화했습니다. 그때까지 비즈니스 컨텍스트는`AGENT.adoc`. 경험칙 : 전문 에이전트는 그 업무 분야가 문서 100줄을 초과할 때 정당화된다.

==== 세션 명명 규칙

사소해 보이는 세부 사항이지만 100 세션에 도달하면 중요해집니다. 아카이브 파일 이름을 어떻게 지어야 하나요?

나는 힘들게 배웠는데, 하나의 관습이 필요하다는 것을 — 네 개의 프로젝트, 네 가지 다른 형식으로 시작했고, 나는 길을 잃었다. 오늘 내가 확립한 관습은:

구체적인 예시 :

* `1-chore-migration-gouvernance-agent.adoc`— 세션 1, 타입 안무
* `10-solidification-tests.adoc`— 세션 10, 명시적 타입이 없음 (주어가 충분함)
* `036-debug-graphify-symlink-epic9.adoc`— 세션 36, 3자리 숫자로 정렬

세션 번호가 주요 정렬 기준입니다. 3자리 숫자(001, 036, 133)를 사용하는 프로젝트는 99를 초과할 때 사전식 정렬 문제를 피합니다. 이것이 제가 지금부터 사용하는`magic-stick`:`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]