# Nerget 범위 한정 AgentOps 로컬 적용 핸드오프

작성일: 2026-08-04

## 현재 타겟

`uhdc-elf` 전체가 아닌 아래 Nerget 코드 범위에만 AgentOps 공통 룰을 적용하는 사용자 로컬 PoC이다.

- `apps/mbfo-nerget/**`
- `libs/feature-mbfo-nerget/**`
- `apps/mbfo-nerget-e2e/**`

범위는 957 tracked files, TypeScript/TSX 59,935 LOC, 스타일 3,035 LOC(합계 62,970 LOC)로 확인했다. IOP의 비생성 Go/Dart/Proto 소스 약 191k LOC와 비교하면 약 33% 규모다.

## 확정된 사용자 결정

- `uhdc-elf` 루트의 `GEMINI.md`, `GEMINI_NERGET.md`, `.cursorrules`는 삭제하거나 수정하지 않는다. legacy 참고 자료로 남긴다.
- 공통 룰은 레포에 새 진입 파일을 추가하는 대신 사용자 로컬 실행기에서만 주입한다.
- 단순히 공통 룰을 기존 지시문 뒤에 추가하지 않는다. 기존 지시문이 자동으로 로드되는 에이전트에서는 해당 **지시문 탐색만** 교체하거나 끈다.
- Nx 모노레포의 workspace/config 탐색은 유지한다. 프로젝트 루트 탐색 전체를 차단하지 않는다.
- `init-agent-ops.sh`는 사용하지 않는다. 이 스크립트는 대상 루트의 `GEMINI.md`, `AGENTS.md`, `.cursorrules` 등을 복사·덮어쓴다.

## 근거

ELF의 legacy 진입 문서는 합계 4,735 lines / 132,394 bytes다.

| 파일 | lines | bytes |
|---|---:|---:|
| `GEMINI.md` | 1,671 | 41,237 |
| `GEMINI_NERGET.md` | 1,890 | 47,892 |
| `.cursorrules` | 1,174 | 43,265 |

검토 당시 IOP의 `agent-ops/rules/common/rules.md`는 58 lines / 6,429 bytes였다. legacy 문서 전량 주입 경로와 비교하는 경우 바이트 기준 약 95% 작다. 다만 Codex·Claude·Pi가 이 세 legacy 파일을 모두 자동으로 읽는 것은 아니므로, 에이전트별 실제 instruction source를 검증해야 한다.

Nerget은 루트 `package.json`, `nx.json`, `tsconfig.base.json`, `.eslintrc.json`, `jest.config.ts`를 상속한다. 특히 테스트/E2E target이 `{workspaceRoot}` coverage/dist 경로를 사용한다. 따라서 `project_root_markers=[]`, Claude `--bare`, Pi `--no-approve` 같은 광범위한 탐색 차단을 기본 설정으로 사용하면 Nx 실행·인증·plugin·hook·LSP 맥락을 잃을 수 있다.

## 권장 구조

공용 로컬 파일은 예를 들어 `~/.agent-ops/nerget/`에 둔다.

```text
common-rules.md       # canonical AgentOps common rules 동기화본
nerget-boundary.md    # Nerget 세 경로와 legacy reference-only 정책만 기록
launch/               # codex-nerget, claude-nerget, gemini-nerget, pi-nerget
```

`nerget-boundary.md`는 AgentOps project/domain rule이 아니다. 다음처럼 짧은 실행 경계만 둔다.

- 대상 코드 범위는 Nerget의 세 경로다.
- legacy 진입 문서는 사용자가 명시하거나 범위 내 정보가 부족한 경우에만 참고한다.
- 공통 룰을 수정하지 않는다.

## 에이전트별 기본 모드

| 에이전트 | 유지할 것 | legacy instruction 처리 | 공통 룰 주입 |
|---|---|---|---|
| Codex | workspace 탐색과 전역 인증/플러그인 | 현재 ELF 루트에는 `AGENTS.md`가 없고 `GEMINI.md`/`.cursorrules`는 Codex 자동 instruction 대상이 아님 | `--profile nerget`의 `developer_instructions`에 common + boundary 생성본 |
| Claude Code | 기본 설정, hook, LSP, gateway 인증 | 현재 Nerget 경로에 `CLAUDE.md` 없음 | `--append-system-prompt-file`로 common + boundary 추가. `--bare`는 A/B 격리 실험 때만 사용 |
| Gemini CLI | workspace와 기존 사용자 인증 | 전용 context filename `AGENT_OPS_NERGET.md`만 찾도록 설정해 `GEMINI.md` 계열을 자동 대상에서 제외 | 사용자 로컬 custom context 파일에 common + boundary 생성. 현재 이 Mac에서는 `gemini` 명령이 PATH에 없음 |
| Pi | 전역 model/provider 설정 | `--no-context-files`로 `AGENTS.md`/`CLAUDE.md` 자동 탐색만 중지 | `--append-system-prompt`로 common + boundary 추가. `--no-approve`, `--no-extensions`, `--no-skills`는 A/B 격리 실험 때만 사용 |

Gemini의 전용 context filename 설정은 `GEMINI_CLI_SYSTEM_SETTINGS_PATH`를 통해 사용자 로컬 settings 파일로 전달하는 방식을 우선 검토한다. `GEMINI_CLI_HOME`을 새로 설정하면 현재 OAuth/config state가 분리될 수 있으므로 기본안으로 사용하지 않는다.

## 실제 변경 및 미변경 상태

- 수행함: ELF/IOP 구조, 각 entry file 규모, Codex·Claude·Gemini·Pi의 instruction discovery와 로컬 설치 상태를 읽기 전용으로 조사했다.
- 수행하지 않음: `uhdc-elf` 코드/설정, ELF root entry file, 사용자 홈의 Codex/Claude/Gemini/Pi 설정, AgentOps common rule을 변경하지 않았다.
- `uhdc-elf` 확인 시점: `develop` / `706549175` / clean.
- Claude Code `2.1.208`, Pi `0.80.3`은 설치되어 있다. Gemini CLI executable은 PATH에서 발견되지 않았다.

## 다음 세션의 시작 순서

1. canonical common rule source를 확정한다. 검토 기준 IOP checkout은 `dev` / `031416e`이며 `origin/dev`보다 5 commits 뒤처져 있고 untracked `.env.simply_canvas`가 있다. 먼저 unrelated 파일을 건드리지 않고 source 선택 또는 IOP sync 필요성을 판단한다.
2. 이 repository의 최신 `agent-ops/rules/common/rules.md`와 선택한 IOP source의 차이를 확인한 뒤, local `common-rules.md` 생성/동기화 방식을 정한다.
3. 사용자 홈에만 launcher와 공통 룰 생성본을 만든다. `uhdc-elf` tracked 파일이나 루트 entry file은 변경하지 않는다.
4. 각 launcher에서 실제 instruction source를 출력하는 점검을 수행한다. Gemini는 `/memory show`; Codex/Claude/Pi는 각 도구의 session/debug 출력으로 확인한다.
5. Nerget의 lint/test/build 중 하나를 실행해 workspace discovery가 유지되는지 확인한다. 이 단계 전에는 sandbox/hook으로 파일 쓰기를 강제 차단하지 않는다.

## 주의 사항

- “무시”는 자동 instruction 주입을 막는 의미다. 사용자가 명시하면 에이전트가 legacy 파일을 직접 읽는 것은 허용한다.
- 공통 룰만으로 Nerget의 domain mapping까지 해결되지 않는다. 실제 코드 변경 PoC를 시작할 때만 최소 project/domain rule이 필요한지 별도 판단한다.
- 이 문서는 적용 완료나 PoC 성공을 의미하지 않는다. 사용자 로컬 설정은 아직 만들어지지 않았다.

## 검증 근거

- `git -C /Users/leedongmyung/works/axops/uhdc-elf status -sb` → `## develop...origin/develop`
- `wc -l -c`로 공통 룰 및 legacy entry file의 lines/bytes 확인
- Nerget Nx target과 workspace config 참조 확인
- `claude --help`, `pi --help`, Gemini CLI 공식 configuration 문서로 에이전트별 instruction 제어 경로 확인