docs(agent-ops): Nerget 평가 보고서를 제거한다
현재 작업 범위에서 더 이상 유지하지 않는 평가 보고서를 삭제한다.
This commit is contained in:
toki
parent
4cbf70c2b2
commit
031416e7ec
1 changed files with 0 additions and 215 deletions
|
|
@ -1,215 +0,0 @@
|
|||
# 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 작업 환경의 초기화 동작 비교 기준)
|
||||
Loading…
Reference in a new issue