From 572c1ed4335a1fbfbb97e4309a44058b34f29e6a Mon Sep 17 00:00:00 2001
From: Claude-51124 <claude@51124.local>
Date: Wed, 11 Mar 2026 17:30:48 +0900
Subject: [PATCH] docs: add agent framework and workspace cli research

---
 ...�크_및_workspace_cli_검증_리서치.md | 219 ++++++++++++++++++
 journey/research/README.md                    |   1 +
 2 files changed, 220 insertions(+)
 create mode 100644 journey/research/260311_자가수정_에이전트_프레임워크_및_workspace_cli_검증_리서치.md
diff --git a/journey/research/260311_자가수정_에이전트_프레임워크_및_workspace_cli_검증_리서치.md b/journey/research/260311_자가수정_에이전트_프레임워크_및_workspace_cli_검증_리서치.md
new file mode 100644
index 0000000..c64e33b
--- /dev/null
+++ b/journey/research/260311_자가수정_에이전트_프레임워크_및_workspace_cli_검증_리서치.md
@@ -0,0 +1,219 @@
+---
+tags: [research, agents, langgraph, pydantic-ai, gemini-cli, workspace, self-improvement]
+---
+
+# 자가수정 에이전트 프레임워크 및 Workspace CLI 검증 리서치
+
+## 목적
+- 로빙이 `슬랙/프론트 대화 + 이메일/뉴스/검색 + 향후 코드 수정/git 작업`까지 수행하려면 어떤 계층을 어떤 도구로 맡기는 게 맞는지 공식 문서 기준으로 정리합니다.
+- 아래 Gemini 대화에서 나온 주장 중 사실과 과장을 분리합니다.
+- 현재 `rb8001` 코드가 이미 무엇을 쓰고 있는지 확인해, 바로 수정 가능한 구조 판단 근거를 남깁니다.
+
+## 입력 질문
+- `Pydantic AI`를 쓰면 비용이 크게 늘어나는가
+- `LangGraph`는 정말 이점이 거의 없는가
+- `Gemini CLI`만으로 자가수정/git 작업이 가능한가
+- `Google Workspace CLI` 또는 Workspace용 공식 툴링은 무엇이 실제 기준인가
+- 현재 로빙 코드에서 가장 위험한 지점은 무엇인가
+
+## 요약 결론
+1. `LangGraph는 이점이 거의 없다`는 주장은 과장입니다. 공식 문서 기준으로 LangGraph의 핵심 가치는 `stateful multi-actor workflow`, `persistence`, `interrupt`, `durable execution`에 있고, 로빙은 이미 이 강점을 실제로 쓰고 있습니다.
+2. `Pydantic AI는 무료 오픈소스`는 맞습니다. 다만 `비용 거의 차이 없음`은 일반론일 뿐 보장 문장이 아닙니다. 출력 검증/재시도가 있으면 토큰 비용은 실제로 증가할 수 있습니다.
+3. `Gemini CLI`는 공식 오픈소스 AI agent CLI이며, `GEMINI.md`, headless 모드, sandbox/approval, tool/MCP 연결을 제공합니다. 하지만 현재 `rb8001`의 Gemini CLI 호출은 이런 안전장치 없이 단순 `gemini -p <prompt>` 호출에 가깝습니다.
+4. Google Workspace 쪽은 `Google Workspace Developer Tools`가 공식 진입점이며, 공식 개발자 문서는 `Gemini CLI extension`, `MCP`, `Apps Script CLI`, `Workspace APIs`를 안내합니다. pasted 답변처럼 특정 저장소 이름 하나만으로 SSOT를 잡는 것은 부정확합니다.
+5. 로빙의 권장 구조는 `LangGraph 제거`가 아니라 `역할 분리`입니다. 장기 상태/인터럽트 워크플로는 LangGraph 유지, typed I/O는 Pydantic 계층으로 보강, 코드수정/git 작업은 승인·격리된 operator agent로 분리하는 쪽이 맞습니다.
+
+## 공식 소스 검증
+
+### 1. Pydantic AI
+- 공식 문서: <https://ai.pydantic.dev/>
+- 공식 GitHub: <https://github.com/pydantic/pydantic-ai>
+- 라이선스: MIT (`LICENSE` 기준)
+- 공식 문서가 내세우는 핵심:
+  - type-safe agent
+  - tool calling
+  - structured output
+  - output validation / retry (`ModelRetry`, output validators)
+
+### 검증 판단
+- `무료 오픈소스`라는 말은 맞습니다.
+- `로그파이어를 안 쓰면 비용 0`도 라이브러리 자체 기준으로는 대체로 맞습니다.
+- 다만 `LLM 비용은 거의 차이 없음`은 SSOT 문장으로 쓰면 안 됩니다.
+  - 이유: Pydantic AI는 출력 검증 실패 시 재시도가 가능하고, 재시도는 곧 추가 모델 호출입니다.
+  - 따라서 비용은 `0 또는 미미`가 아니라 `검증 성공률에 따라 증가할 수 있음`이 정확한 표현입니다.
+- 결론: Pydantic AI는 `안정성 계층`으로 유의미하지만, `오케스트레이션 전체 대체`나 `비용 무시 가능` 같은 표현은 과장입니다.
+
+### 2. LangGraph
+- 공식 문서: <https://langchain-ai.github.io/langgraph/>
+- 공식 개요 문서가 강조하는 핵심:
+  - long-running, stateful workflows
+  - cycles
+  - persistence / durable execution
+  - human-in-the-loop / interrupts
+  - memory
+
+### 검증 판단
+- `이점이 전혀 없다`는 말은 공식 제품 가치와 충돌합니다.
+- LangGraph의 진짜 강점은 단순 질의응답이 아니라:
+  - 중간 상태 저장
+  - 사람 확인 후 재개
+  - 다단계 조건 분기
+  - 실패 후 같은 thread 상태에서 재실행
+  에 있습니다.
+- 반대로 단점도 실제로 있습니다.
+  - 선형 코드보다 디버깅 난이도가 높아질 수 있음
+  - 단순 request/response엔 과함
+  - 팀이 상태 모델링을 못하면 그래프가 과설계되기 쉬움
+- 결론: `LangGraph 비추천`이 아니라 `LangGraph를 써야 할 문제와 쓰지 말아야 할 문제를 구분해야 함`이 맞습니다.
+
+### 3. Gemini CLI
+- 공식 GitHub: <https://github.com/google-gemini/gemini-cli>
+- 공식 문서: <https://gemini-cli.xyz/docs/cli/configuration/context/>
+- 공식 문서: <https://gemini-cli.xyz/docs/cli/configuration/headless/>
+- 공식 문서: <https://gemini-cli.xyz/docs/tools/workspace/>
+- 공식 문서: <https://developers.googleblog.com/en/introducing-gemini-cli-open-source-ai-agent/>
+
+### 검증 판단
+- `Gemini CLI로 코드 수정/git 작업 가능`은 방향상 맞습니다.
+- 공식 문서 기준 Gemini CLI는 다음을 지원합니다.
+  - `GEMINI.md` context files
+  - headless/script mode
+  - workspace context
+  - approvals / sandboxing / trusted folders
+  - MCP/tool integration
+- 즉 `에이전트형 코드 작업기`로는 충분히 사용할 수 있습니다.
+- 다만 `컨텍스트 주입 없이도 잘 된다`는 식의 낙관은 틀렸습니다.
+  - 공식 문서 스스로 `context`와 `workspace` 설정을 별도 섹션으로 둡니다.
+  - 즉 안전한 사용 전제는 `GEMINI.md + workspace scope + approval/sandbox`입니다.
+
+### 4. Google Workspace 공식 툴링
+- 공식 개발자 문서: <https://developers.google.com/workspace/guides/developer-tools>
+- 공식 Codelab: <https://developers.google.com/codelabs/dev-tools-for-gws#0>
+- 공식 안내가 가리키는 GitHub 조직/저장소:
+  - `googleworkspace/developer-tools`
+  - `gemini-cli-extensions/workspace`
+
+### 검증 판단
+- `Google Workspace CLI가 며칠 전에 나왔다`는 방향은 일부 맞을 수 있으나, SSOT는 저장소 이름이 아니라 공식 개발자 문서입니다.
+- 공식 문서는 `Google Workspace Developer Tools`를 기준으로 설명하며, Gemini CLI extension/MCP/CLI 사용 흐름을 안내합니다.
+- pasted 답변의 `googleworkspace/cli` 단일 저장소 URL은 공식 문서가 직접 가리키는 기준 경로와 일치하지 않습니다.
+- 결론: Google Workspace 툴링을 도입할 때는 `developers.google.com/workspace/...`를 1차 SSOT로 삼아야 합니다.
+
+## Gemini 답변 검증표
+
+| 주장 | 판단 | 근거 |
+|---|---|---|
+| Pydantic AI는 무료 오픈소스다 | 대체로 맞음 | 공식 GitHub, MIT |
+| Pydantic AI는 비용이 거의 안 든다 | 과장 | 검증 실패/재시도는 추가 호출 비용 |
+| LangGraph는 거의 쓸모없다 | 틀림/과장 | 공식 문서가 persistence, interrupt, cycles를 핵심 가치로 제시 |
+| Gemini CLI로 자가수정/git 작업 가능 | 맞음 | 공식 오픈소스 agent CLI, headless/context/tooling 문서 존재 |
+| 컨텍스트 없이 Gemini CLI 쓰면 위험하다 | 맞음 | 공식 docs가 context/workspace/GEMINI.md를 별도 지원 |
+| Google Workspace CLI 주소 하나만 알면 충분하다 | 부정확 | 공식 기준은 Workspace Developer Tools 문서와 연결 저장소 |
+
+## 현재 로빙 코드 상태
+
+### 1. LangGraph는 이미 핵심 경로에서 실사용 중
+- 콜드메일 워크플로는 `interrupt`와 checkpoint를 전제로 설계돼 있습니다.
+  - [coldmail_workflow.py](/home/admin/robeing/rb8001/app/services/workflows/coldmail_workflow.py#L416)
+- 아침 헤드라인도 SQLite checkpointer 기반으로 실행됩니다.
+  - [headlines_workflow.py](/home/admin/robeing/rb8001/app/services/workflows/headlines_workflow.py#L196)
+- `docker-compose.yml`에도 LangGraph 상태 저장 디렉토리가 명시돼 있습니다.
+  - [docker-compose.yml](/home/admin/robeing/rb8001/docker-compose.yml#L77)
+
+### 2. Gemini CLI는 이미 연결돼 있지만 안전한 operator 모드가 아님
+- 현재 구현은 단순 subprocess로 `gemini -m <model> -p <prompt>`를 호출합니다.
+  - [gemini_handler.py](/home/admin/robeing/rb8001/app/services/llm/gemini_handler.py#L559)
+- 여기에는 현재 다음이 없습니다.
+  - `GEMINI.md` 주입 보장
+  - repo/workspace scope 제한
+  - diff preview 승인 절차
+  - git command allowlist
+  - branch/commit/push 정책 계층
+- 즉 현재 연결은 `LLM CLI caller`이지 `안전한 코드수정 에이전트`가 아닙니다.
+
+### 3. 자기개선은 DB/로그 계층까지만 있음
+- `self_improvement_endpoint.py`는 policy version과 self improvement run 저장 API를 제공합니다.
+  - [self_improvement_endpoint.py](/home/admin/robeing/rb8001/app/router/self_improvement_endpoint.py#L44)
+- `message_tracking_service.py`는 message flow artifacts를 DB에 기록합니다.
+  - [message_tracking_service.py](/home/admin/robeing/rb8001/app/services/message_tracking_service.py#L49)
+- 하지만 현재는 `코드 분석 -> 수정 -> 테스트 -> git branch -> commit -> push` operator loop는 없습니다.
+
+## 지금 풀어야 하는 실제 문제
+
+### 문제 1. 도구 선택 문제가 아니라 책임 분리 문제가 핵심
+- 현재 질문은 `LangGraph vs Pydantic AI vs Gemini CLI`처럼 보이지만, 실제 문제는 다음입니다.
+  - 어떤 계층이 `대화 오케스트레이션`을 맡는가
+  - 어떤 계층이 `typed validation`을 맡는가
+  - 어떤 계층이 `코드수정/git operator`를 맡는가
+
+### 문제 2. 현재 가장 큰 리스크는 Gemini CLI의 무맥락/무가드 호출
+- 로빙은 이미 Gemini CLI를 호출하지만, agent-safe 구조가 아닙니다.
+- 이 상태에서 코드수정/git까지 붙이면 다음 리스크가 큽니다.
+  - 잘못된 파일 수정
+  - 프로젝트 규칙 무시
+  - 의도하지 않은 git add/commit/push
+  - repo 경계 침범
+
+### 문제 3. LangGraph를 제거할 이유보다 남겨야 할 이유가 더 많음
+- 콜드메일처럼 `사람 확인 -> 재개`가 필요한 경로는 LangGraph 공식 강점과 정확히 일치합니다.
+- headlines/web_search처럼 stateful multi-step flow도 이미 자리잡았습니다.
+- 따라서 `LangGraph 전면 철거`는 현재 구조와 맞지 않습니다.
+
+## 권장 아키텍처
+
+### A. 대화/서비스 오케스트레이션
+- 유지:
+  - 현재 `LangGraph` 기반의 장기 상태/인터럽트 워크플로
+- 기준:
+  - `interrupt`, checkpoint, loop, resume가 필요한 경로만 LangGraph 유지
+  - 단순 단발성 request/response는 선형 서비스 함수 유지
+
+### B. typed I/O 안정화
+- 선택:
+  - 전체를 Pydantic AI로 갈아엎기보다, 기존 FastAPI/Pydantic 모델 위에 `typed output validation` 요구가 큰 경로만 부분 도입 검토
+- 이유:
+  - 로빙은 이미 FastAPI + Pydantic 기반이어서 기본 typed schema 자산이 큼
+  - 지금 가장 아픈 곳은 schema 부재보다 operator safety 부재임
+
+### C. 코드수정/git operator
+- 권장:
+  - `Gemini CLI` 또는 동급 coding agent를 별도 operator 계층으로 분리
+- 필수 조건:
+  1. `GEMINI.md` 또는 동등한 repo-specific instruction file
+  2. repo path scope 강제
+  3. 테스트 명령 allowlist
+  4. `git checkout -b`, `git status`, `git diff`, `git add`, `git commit`, `git push`에 대한 단계별 승인
+  5. diff/테스트 결과를 Slack 또는 프론트에 보고 후 최종 승인
+
+### D. Google Workspace 연동
+- 권장:
+  - Google Workspace Developer Tools를 `tool layer`로만 사용
+- 비권장:
+  - Workspace CLI를 에이전트 프레임워크의 중심 SSOT로 두는 것
+- 이유:
+  - 메일/드라이브/캘린더 접근은 도구 계층 문제이고, 오케스트레이션/자기수정 구조와는 별개이기 때문
+
+## 바로 수정 가능한 실행 항목
+1. `rb8001`의 Gemini CLI 호출 경로에 `operator mode`를 분리합니다.
+   - 현재 `chat()` 계열 호출과 코드수정용 CLI 호출을 분리해야 합니다.
+2. 코드수정용 경로는 `repo`, `branch`, `allowed_commands`, `required_tests`를 명시 입력으로 받아야 합니다.
+3. `GEMINI.md` 또는 동등한 프로젝트 헌법 파일을 repo별로 두고, agent-safe rules를 고정합니다.
+4. `자기개선 DB 로그`와 `실제 git/operator 실행 로그`를 별도 테이블 또는 이벤트로 분리합니다.
+5. Google Workspace 연동은 `tool plugin`으로만 붙이고, 에이전트 중심 설계를 흔들지 않게 분리합니다.
+
+## 의사결정 문장
+- 로빙의 현재 문제는 `LangGraph를 버릴지`가 아니라 `Gemini CLI를 안전한 operator로 승격할 안전장치를 어떻게 붙일지`입니다.
+- 따라서 우선순위는 `LangGraph 제거`가 아니라 `Gemini CLI 무가드 호출 제거 + operator 경계 설계 + 승인 흐름 추가`입니다.
+
+## 참고 소스
+- Pydantic AI 공식 문서: <https://ai.pydantic.dev/>
+- Pydantic AI GitHub: <https://github.com/pydantic/pydantic-ai>
+- LangGraph 공식 문서: <https://langchain-ai.github.io/langgraph/>
+- Gemini CLI GitHub: <https://github.com/google-gemini/gemini-cli>
+- Gemini CLI docs:
+  - context: <https://gemini-cli.xyz/docs/cli/configuration/context/>
+  - headless: <https://gemini-cli.xyz/docs/cli/configuration/headless/>
+  - workspace tools: <https://gemini-cli.xyz/docs/tools/workspace/>
+- Google Workspace Developer Tools:
+  - overview: <https://developers.google.com/workspace/guides/developer-tools>
+  - codelab: <https://developers.google.com/codelabs/dev-tools-for-gws#0>
diff --git a/journey/research/README.md b/journey/research/README.md
index eb46ba2..b078426 100644
--- a/journey/research/README.md
+++ b/journey/research/README.md
@@ -10,6 +10,7 @@
 - [아침브리핑 형식혼선·동남아영어노출 원인확정 리서치 (260305)](./260305_아침브리핑_형식혼선_동남아영어노출_원인확정_리서치.md)
 - [51124 먹통 48시간 코드 차분 원인 확정 리서치 (260304)](./260304_51124_먹통_48시간_코드차분_원인확정_리서치.md)
 - [9시 네이버 이메일 분석 미전송 실패 은닉 리서치 (260309)](./260309_9시_네이버이메일분석_미전송_실패은닉_리서치.md)
+- [자가수정 에이전트 프레임워크 및 Workspace CLI 검증 리서치 (260311)](./260311_자가수정_에이전트_프레임워크_및_workspace_cli_검증_리서치.md)
 
 ### [기억(Memory)](./memory/README.md)
 - 장단기 기억 메커니즘
