diff --git a/NERGET_AGENT_OPS_SCOPED_ADOPTION_REPORT.md b/NERGET_AGENT_OPS_SCOPED_ADOPTION_REPORT.md new file mode 100644 index 00000000..4aab03df --- /dev/null +++ b/NERGET_AGENT_OPS_SCOPED_ADOPTION_REPORT.md @@ -0,0 +1,215 @@ +# Nerget 범위 Agent-Ops 도입 평가 보고서 + +작성일: 2026-08-03 + +대상: `uhdc-elf` 모노레포의 Nerget 작업 범위 +상태: 제안 — 이 문서는 설정을 변경하지 않는다. + +## 결론 + +Nerget에만 적용하는 얇은 Agent-Ops 구조는 권장한다. 다만 현재 표준 `init-agent-ops`를 저장소 루트에 그대로 실행하면 안 된다. 루트의 `GEMINI.md`, `GEMINI_NERGET.md`, `.cursorrules`, `.gitignore`, GitHub Actions를 바꾸지 않는 **서브트리 한정 모드**가 먼저 필요하다. + +목표는 기존 대형 가이드를 삭제하는 것이 아니다. 일반 개발·수정 작업은 짧은 Nerget 규칙만 읽게 하고, 기존 가이드는 심층 PR 리뷰 또는 필요한 주제의 참조 문서로 전환한다. 이 방식은 입력 토큰, 컨텍스트 포화, 모델 응답 지연을 낮추고 로컬 모델 사용 가능 범위를 넓힌다. + +여기서 “서브모듈”은 Git submodule이 아니라, 아래 Nerget 관련 모노레포 서브트리를 뜻한다. + +- `apps/mbfo-nerget/**` +- `libs/feature-mbfo-nerget/**` +- `apps/mbfo-nerget-e2e/**` + +## 현재 상태와 문제 + +### 대형 진입 가이드 + +| 파일 | 크기 | 현재 역할 | 관찰된 문제 | +|---|---:|---|---| +| `GEMINI.md` | 1,671줄 / 41,237바이트 | ELF 전체 Gemini PR 리뷰 가이드 | 코드 예시, 구조도, 기술 스택, 리뷰 템플릿까지 항상 한 문서에 있다. | +| `GEMINI_NERGET.md` | 1,890줄 / 47,892바이트 | Nerget Gemini PR 리뷰 가이드 | 공통 `GEMINI.md`를 사실상 복제하고 Nerget 특화 내용을 앞에 더한다. 비교 결과는 222줄 추가, 3줄 삭제다. | +| `.cursorrules` | 1,174줄 / 43,265바이트 | Cursor용 전역 프로젝트 가이드 | 구조, 코드 규칙, UI 시스템, CI/CD, 코드 예시를 넓게 반복한다. 상단 앱 목록에는 현재 존재하는 Nerget이 포함되지 않아 최신성 확인도 필요하다. | + +세 파일은 합계 4,735줄 / 132,394바이트다. 바이트 수는 토큰 수와 같지 않지만, 도구와 토크나이저에 따라 수만 입력 토큰이 될 수 있는 충분히 큰 정적 컨텍스트다. + +### Nerget PR 리뷰의 넓은 컨텍스트 + +`.github/workflows/pr_review_gemini.yml`의 Nerget 전체 리뷰 경로는 다음 특성을 가진다. + +- `full-review` 라벨의 PR에서 실행한다. +- `GEMINI_NERGET.md`와 `GEMINI.md`를 모두 필수 참조로 지정한다. +- `useFullRepoContext: true`, `onlyChangedFiles: false`다. +- 최대 8,000파일과 65MB의 전체 컨텍스트를 허용한다. + +따라서 해당 리뷰는 약 89KB의 정적 Gemini 가이드(그 안의 중복 포함)에 전체 저장소 컨텍스트까지 결합될 수 있다. 심층 릴리스 리뷰에는 유효할 수 있으나, 일상 변경의 기본 경로로 사용하면 토큰과 대기 시간을 크게 늘린다. + +### 운영상 문제 + +1. **상시 입력 비용이 크다.** 작업과 무관한 UI 컴포넌트 목록, 코드 예시, 다른 서비스의 설명도 읽을 가능성이 있다. +2. **동일 규칙이 중복된다.** Nerget 문서가 공통 Gemini 문서를 복제하므로 유지보수와 입력량이 함께 증가한다. +3. **규칙의 우선순위가 불명확하다.** Gemini, Nerget Gemini, Cursor 문서가 비슷한 주제를 다른 형식으로 말한다. 충돌 또는 갱신 누락 시 모델이 무엇을 우선할지 불명확하다. +4. **현재성 비용이 높다.** 전체 앱/라이브러리 목록을 여러 문서에서 유지해야 한다. 한 문서의 목록이 실제 구조와 달라질 수 있다. +5. **작업 절차가 경로와 연결되지 않는다.** 어떤 변경에 Storybook, E2E, 타입 검사, 실시간 연결 검토가 필요한지가 코드 경로 기준으로 라우팅되지 않는다. +6. **로컬 모델의 여유가 작다.** 짧은 컨텍스트 창을 가진 모델은 규칙만으로 많은 여유를 잃고 실제 diff·코드·도구 결과를 충분히 받을 수 없다. + +## 방식 비교 + +| 항목 | 현재 대형 가이드 방식 | Nerget 한정 Agent-Ops 방식 | +|---|---|---| +| 기본 진입 | 도구별 루트 문서 전체 | 짧은 로컬 진입 규칙과 경로 라우팅 | +| 규칙 저장 | 공통·특화·Cursor 문서에 반복 | 공통 원칙 한 곳, Nerget 규칙 한 곳, 주제별 조건부 문서 | +| 로딩 단위 | 프로젝트 전반 설명과 예시까지 넓게 | 현재 변경 경로와 작업 종류에 필요한 규칙만 | +| 테스트 연결 | 문서 속 안내 중심 | 앱·feature·E2E 경로별 명령과 검증 기준 | +| PR 심층 리뷰 | 전체 레포 컨텍스트 중심 | 기본은 diff/영향 범위, 전체 리뷰는 명시적 예외 | +| 유지보수 | 같은 내용을 여러 문서에서 수정 | 공통과 Nerget 특화를 분리해 한 번만 수정 | + +Agent-Ops가 기존 심층 리뷰 문서보다 “더 많은 지식”을 제공하는 것은 아니다. 이점은 지식을 작업 시점에 맞게 선택해 읽는 데 있다. + +## 권장 서브트리 한정 설계 + +### 적용 경계 + +저장소 루트에는 전역 Agent-Ops 진입 파일을 생성하거나 교체하지 않는다. 특히 다음 파일은 이 도입의 변경 대상이 아니다. + +- `GEMINI.md` +- `GEMINI_NERGET.md` +- `.cursorrules` +- 루트 `.gitignore` +- 기존 GitHub Actions 워크플로 + +Nerget 전용 설정은 `libs/feature-mbfo-nerget/agent-ops/`에 두고, 세 관리 경로에는 짧은 bridge entry만 둔다. bridge entry는 전역 규칙을 복제하지 않고 공유 Nerget 규칙의 위치와 적용 범위만 알려야 한다. + +```text +libs/feature-mbfo-nerget/ +├── agent-ops/ +│ ├── rules/project/rules.md # Nerget의 짧은 공통 작업 규칙 +│ ├── rules/project/domain/realtime/ # WebSocket/SSE, 추적, PII +│ ├── rules/project/domain/experience/ # UI, Storybook, 접근성 +│ ├── rules/project/domain/experiments/ # Feature Flag, A/B 테스트 +│ └── rules/project/domain/e2e/ # Playwright와 검증 경계 +└── AGENTS.md # feature 라이브러리 bridge entry + +apps/mbfo-nerget/AGENTS.md # 동일 규칙을 가리키는 app bridge entry +apps/mbfo-nerget-e2e/AGENTS.md # 동일 규칙을 가리키는 E2E bridge entry +``` + +각 bridge entry는 20~40줄 이내를 목표로 한다. 변경 경로가 Nerget 범위 밖이면 해당 규칙을 적용하지 않으며, 필요한 공통 가이드는 기존 루트 문서를 명시적으로 참조한다. + +### 표준 초기화 스크립트에 필요한 변경 + +현행 `init-agent-ops`는 대상 디렉터리에 모든 진입 파일과 기본 구조를 만드는 전역 초기화에 가깝다. Nerget 한정 적용에는 아래 기능이 필요하다. + +1. `--scope` allowlist로 관리 경로 세 곳을 명시하고, 경로 밖의 변경에는 규칙을 적용하지 않는다. +2. workspace 루트를 target으로 지정하면 실패하도록 하여 전역 진입 파일 덮어쓰기를 막는다. +3. 루트 `.gitignore`와 기존 도구별 진입 파일을 수정하지 않는다. +4. 공유 규칙은 feature 라이브러리 아래 한 곳에 두고, app/E2E에는 짧은 bridge entry만 만든다. +5. roadmap, 전역 task archive, 공통 agent-ops 동기화는 생성하지 않는다. Nerget 범위에서 실제 반복 작업이 확인되기 전에는 프로젝트 skill도 만들지 않는다. +6. 모든 생성·갱신 전에 대상 경로와 기존 진입 파일을 검사하고, 덮어쓸 파일이 있으면 중단한다. + +이 변경이 없으면 “Nerget에만 적용”하더라도 루트 규칙이나 다른 앱의 AI 동작에 영향을 줄 수 있다. + +## 토큰 절약 관점 + +### 현재 비용 구조 + +각 모델 호출의 입력은 대체로 아래처럼 구성된다. + +```text +입력 컨텍스트 = 상시 규칙 + 대화 이력/요약 + 현재 요청 + 선택된 코드와 도구 결과 +``` + +상시 규칙은 세션에 한 번만 읽는 것처럼 보여도, API 호출마다 컨텍스트에 다시 포함되거나 캐시 키로 참조될 수 있다. 프롬프트 캐시는 입력 비용을 낮출 수 있지만, 컨텍스트 창을 점유하고 모델의 주의를 분산시키는 문제를 없애지는 않는다. + +Nerget 전체 리뷰에서는 `GEMINI_NERGET.md`와 `GEMINI.md`가 함께 필수 참조여서 공통 가이드가 중복된다. 이는 품질 근거가 명확하지 않은 고정 입력 비용이다. + +### 목표 컨텍스트 예산 + +아래 수치는 토큰 보장이 아니라 문서 원문 크기를 통제하기 위한 설계 예산이다. + +| 상황 | 현재 정적 가이드 | 제안 목표 | +|---|---:|---:| +| Nerget 일반 코드 작업 | 도구에 따라 루트 가이드 수십 KB | bridge entry + 공통 Nerget rule, 합계 2~6KB | +| 실시간 연결/추적 변경 | 동일한 전역 가이드 | 일반 규칙 + `realtime` rule, 합계 4~8KB | +| Storybook·접근성 변경 | 동일한 전역 가이드 | 일반 규칙 + `experience` rule, 합계 4~8KB | +| Feature Flag/A-B 변경 | 동일한 전역 가이드 | 일반 규칙 + `experiments` rule, 합계 4~8KB | +| 명시적 전체 PR 리뷰 | 공통·Nerget 문서와 전체 레포 | 별도 예외 경로. 이 경우에만 큰 참고 문서와 넓은 컨텍스트 허용 | + +문서 예산을 지키면 일반 Nerget 작업에서 현재 수십 KB 정적 가이드를 단일 자릿수 KB로 줄일 수 있다. 실제 절감 토큰과 비용은 사용 모델의 tokenizer, 캐시, 호출 패턴에 따라 측정해야 한다. + +## 성능 영향 + +이 도입이 개선하는 성능은 유플닷컴 런타임 성능이 아니라 **AI 작업 경로의 성능**이다. + +| 기대 효과 | 원인 | 검증 지표 | +|---|---|---| +| 첫 응답과 도구 호출 시작 시간 감소 | 매 요청에 읽는 정적 규칙과 불필요한 코드 수가 감소 | 요청별 p50/p95 응답 시작 시간 | +| 컨텍스트 포화 감소 | 변경과 무관한 문서·코드가 기본 입력에서 빠짐 | 입력 토큰, compact 발생 횟수, 남은 컨텍스트 | +| 응답 정확도 향상 가능성 | Nerget 변경에는 Nerget 규칙만 집중해 지시 충돌이 줄어듦 | 리뷰 false positive, 재작업 횟수, 규칙 위반 누락 | +| PR 리뷰 비용 감소 | 기본 리뷰를 영향 파일 중심으로 전환 | PR당 uncached/cached input token, 완료 시간 | + +Agent-Ops만 추가한다고 GitHub Gemini workflow의 전체 레포 읽기가 자동으로 줄지는 않는다. 실제 비용 개선에는 Nerget PR 흐름을 다음처럼 분리해야 한다. + +- 기본: 변경 파일·의존 파일·Nerget 규칙만 읽는 targeted review +- 예외: 릴리스, 보안, 대규모 마이그레이션에 `full-review` 라벨을 붙여 전체 컨텍스트 사용 + +## 로컬 모델 사용 가능성 + +가능성은 높아진다. 현재처럼 수만 토큰의 가이드와 전체 레포를 먼저 넣는 구조는 짧은 컨텍스트 창의 로컬 모델에 불리하다. 얇은 라우팅 구조는 코드와 도구 결과에 더 많은 컨텍스트를 남긴다. + +| 모델 컨텍스트 예산 | Nerget 한정 Agent-Ops 적용 후 적합한 작업 | 부적합하거나 추가 검색이 필요한 작업 | +|---|---|---| +| 8~16K | 단일 컴포넌트 수정, 타입 오류, Storybook 보강, 작은 테스트 | 전체 PR 리뷰, 여러 앱을 가로지르는 구조 변경 | +| 32K | feature·app 단위 변경, 실시간 훅 검토, 선택된 E2E 실패 분석 | 전체 레포 의미 분석, 대규모 마이그레이션 | +| 64K 이상 | 영향 파일을 검색해 묶은 중간 규모 리뷰 | 전체 65MB 컨텍스트를 그대로 넣는 리뷰 | + +로컬 모델에 필요한 추가 운영 장치도 있다. + +- 파일 검색과 dependency graph로 후보 파일을 먼저 좁힌다. +- 코드·로그 출력 길이에 상한을 둔다. +- 시스템/진입 규칙, 사용자 요청, 검사 결과의 우선순위를 고정한다. +- 대형 보안·릴리스 리뷰는 더 큰 컨텍스트의 원격 모델 또는 명시적 full-review로 올린다. + +따라서 이 설계는 “로컬 모델로 모든 리뷰를 대체”하는 방안이 아니라, 일상 Nerget 개발·테스트·소규모 리뷰를 로컬 모델로 처리할 수 있게 만드는 컨텍스트 최적화다. + +## 해결되는 부분과 남는 부분 + +| 항목 | Nerget 한정 Agent-Ops로 해결 | 추가 조치 필요 | +|---|---|---| +| 중복된 공통 가이드의 상시 로딩 | 예. 기본 작업에서 제외 가능 | 기존 Gemini 문서 자체의 중복 정리는 별도 결정 | +| Nerget 변경에 필요한 규칙 선택 | 예. 경로·작업 유형 라우팅으로 해결 | 규칙을 짧고 최신으로 유지해야 함 | +| 전역 진입 파일 덮어쓰기 위험 | 예. `--scope`와 bridge entry로 회피 | 초기화 스크립트의 scoped 모드 구현 필요 | +| 전체 레포 PR 리뷰의 토큰 소비 | 일부. 기본 경로를 좁힐 수 있음 | workflow의 `useFullRepoContext`와 prompt를 바꿔야 함 | +| 애플리케이션 런타임 성능 | 아니오 | 별도 번들·렌더링·API 성능 작업 필요 | +| 로컬 모델 사용 | 예. 일반 작업의 컨텍스트 요구량을 낮춤 | 검색, 파일 선택, 모델별 품질 검증 필요 | + +## 단계적 도입과 검증 + +1. **설계 확정**: 세 Nerget 경로와 rule 책임을 승인한다. 루트 파일은 변경하지 않는다. +2. **scoped initializer 구현**: allowlist, 루트 보호, bridge entry, 덮어쓰기 중단을 구현한다. +3. **문서 이관**: `GEMINI_NERGET.md`의 특화 내용에서 실행 규칙만 추출한다. 코드 예시와 장문의 설명은 기존 참고 문서에 남긴다. +4. **로컬 파일 검증**: 신규 bridge entry가 세 경로에서만 발견되고, 루트 파일과 비-Nerget 경로의 diff가 없음을 확인한다. +5. **Nerget pilot**: 컴포넌트, 실시간 훅, Feature Flag, E2E 변경을 각각 한 건씩 수행한다. +6. **토큰·품질 측정**: 동일 또는 유사 작업에서 아래 지표를 도입 전후 비교한다. + + - 요청당 input / cached input / output token + - p50/p95 응답 시작 시간과 완료 시간 + - compact 또는 context limit 발생 횟수 + - 작업당 수정 재시도와 리뷰 false positive + - 로컬 모델 완료율과 원격 모델 승격률 + +7. **PR workflow 분리 결정**: pilot 결과가 확인된 뒤에만 Nerget 기본 리뷰를 targeted review로 바꾸고, `full-review`는 예외 경로로 유지한다. + +## 결정 요청 + +이 보고서는 Nerget 범위의 Agent-Ops 설계 방향만 제안한다. 실제 적용 전에는 다음을 확정해야 한다. + +1. `apps/mbfo-nerget`, `libs/feature-mbfo-nerget`, `apps/mbfo-nerget-e2e`를 모두 관리 범위로 할지 +2. 기존 `GEMINI_NERGET.md`를 PR 심층 리뷰 참고 문서로 계속 유지할지 +3. Nerget 기본 PR 리뷰를 targeted review로 전환할지와 full-review 사용 조건 +4. 로컬 모델 pilot의 허용 범위와 성공 기준 + +## 근거 파일 + +- `GEMINI.md` +- `GEMINI_NERGET.md` +- `.cursorrules` +- `.github/workflows/pr_review_gemini.yml` +- `package.json` +- `agent-ops/skills/common/init-agent-ops/SKILL.md` (현재 IOP 작업 환경의 초기화 동작 비교 기준)