docs(handoff): 모노레포 적용 맥락을 보강한다

HANDOFF.md

@@ -2,7 +2,54 @@
 
 작성일: 2026-08-04
 
-## 현재 타겟
+## 이 핸드오프가 다루는 일반 환경
+
+이 문서는 특정 프로젝트의 기능 구현 핸드오프가 아니다. **여러 애플리케이션과 라이브러리를 가진 프런트엔드 모노레포에서, 특정 제품 모듈에만 AI coding-agent 운영 규칙을 로컬 PoC로 적용하려는 상황**을 다룬다.
+
+대상 모노레포는 보통 다음과 같은 형태다. 실제 다음 세션이 원본 프로젝트에 접근하지 못하더라도 이 구조를 기준으로 적용 대상을 식별한다.
+
+```text
+<monorepo>/
+├── package.json, nx.json, tsconfig.base.json, lint/test 공통 설정
+├── <legacy agent entry files>          # repo 전체를 설명하는 대형 지시문
+├── apps/
+│   ├── <target-app>/                   # 사용자가 변경하려는 제품 앱
+│   ├── <target-app>-e2e/               # 대상 앱의 E2E/브라우저 검증
+│   └── <unrelated-apps...>/            # 이번 PoC 범위 밖 제품
+└── libs/
+    ├── <target-feature-lib>/           # 대상 앱의 기능·UI·상태 로직
+    └── <unrelated-libs...>/
+```
+
+적용 대상은 `<target-app>`, `<target-feature-lib>`, `<target-app>-e2e`의 세 코드 영역이다. 루트 설정은 이들이 빌드·lint·test·E2E를 실행하기 위해 읽어야 하는 공유 기반이며, 다른 앱/라이브러리는 변경 대상이 아니다.
+
+### 해결하려는 문제
+
+대형 모노레포는 보통 루트에 Gemini/Cursor/Claude 등의 지시문을 여러 개 둔다. 이 문서들은 전체 앱 목록, 공통 개발 규약, 팀별 예외, PR 자동 검토 절차를 함께 품기 쉬워서 특정 모듈 작업에도 불필요한 컨텍스트가 많이 들어간다. 도구마다 자동 인식하는 파일명이 다르면 같은 작업도 에이전트별 초기 토큰과 동작이 달라진다.
+
+목표는 다음 두 가지를 동시에 만족하는 것이다.
+
+1. 대상 모듈 작업에는 짧은 AgentOps 공통 룰과 최소 범위 경계만 처음부터 제공한다.
+2. 모노레포의 실제 workspace/config 탐색은 유지해 루트 빌드 설정, 의존성, test target을 잃지 않는다.
+
+따라서 이 PoC에서 말하는 “기존 진입점을 무시한다”는 **자동 instruction 주입만 선택적으로 막는다**는 뜻이다. 파일시스템 접근, Git/Nx workspace 인식, root package/config 탐색을 없애는 뜻이 아니다.
+
+### 적용하기 좋은 조건과 피해야 할 조건
+
+적합한 경우는 다음과 같다.
+
+- 한 제품 모듈의 앱·기능 라이브러리·E2E 경로가 명확히 식별된다.
+- 루트 문서가 여러 에이전트용으로 크거나 중복되어, 모듈 작업에 전체 문서를 항상 넣을 이유가 없다.
+- Codex, Claude Code, Gemini CLI, Pi 중 둘 이상을 사용하며 각 도구의 context discovery 차이를 통제할 필요가 있다.
+- 팀 공용 레포 설정은 건드리지 않고, 한 사용자가 먼저 효과와 부작용을 검증하려 한다.
+
+부적합하거나 별도 설계가 필요한 경우는 다음과 같다.
+
+- 대상 모듈이 공통 플랫폼 계약, 배포 설정, 보안 정책을 매 작업마다 광범위하게 변경한다.
+- 앱/라이브러리/E2E 경계를 식별할 수 없거나 실제 test target이 전역 코드를 수정한다.
+- 팀 전체가 동일한 behavior를 즉시 강제해야 하는 상황이다. 이 경우 사용자 로컬 launcher PoC가 아니라 레포 차원의 합의와 설정 변경이 필요하다.
+
+## 구체 대상 매핑(프로젝트가 있을 때)
 
 `uhdc-elf` 전체가 아닌 아래 Nerget 코드 범위에만 AgentOps 공통 룰을 적용하는 사용자 로컬 PoC이다.
 
@@ -20,6 +67,33 @@
 - Nx 모노레포의 workspace/config 탐색은 유지한다. 프로젝트 루트 탐색 전체를 차단하지 않는다.
 - `init-agent-ops.sh`는 사용하지 않는다. 이 스크립트는 대상 루트의 `GEMINI.md`, `AGENTS.md`, `.cursorrules` 등을 복사·덮어쓴다.
 
+## 적용 경계의 구분
+
+| 구분 | PoC에서의 처리 | 이유 |
+|---|---|---|
+| 코드 변경 범위 | 대상 앱·기능 라이브러리·E2E만 기본 후보 | 다른 제품의 변경·검증을 이번 실험에서 분리한다 |
+| workspace/config 탐색 | 유지 | package manager, Nx target, TypeScript path, lint/test 설정이 루트에 있을 수 있다 |
+| legacy instruction 자동 주입 | 에이전트별로 선택 차단 | 대형 전역 문서가 대상 모듈 컨텍스트를 잠식하지 않게 한다 |
+| legacy 문서 직접 열람 | 명시 요청 또는 범위 내 정보 부족 시 허용 | 필요한 전사/전역 규칙까지 잃지 않는다 |
+| AgentOps common | 사용자 로컬 실행기에서만 주입 | 팀 공용 파일을 변경하지 않고 효과를 비교한다 |
+| project/domain rule | 실제 코드 변경 PoC가 시작될 때만 최소로 추가 검토 | common rule만으로 제품별 도메인 판단까지 강제하지 않는다 |
+
+이 구분이 중요하다. `--bare`, `--no-approve`, project-root 탐색 차단처럼 범위가 넓은 옵션은 instruction뿐 아니라 인증·plugin·hook·LSP·프로젝트 설정까지 함께 끌 수 있다. 기본 경로가 아니라 비교 실험에서만 사용한다.
+
+## 원본 프로젝트에 접근할 수 없을 때의 인계 원칙
+
+이 문서만 전달받고 원본 모노레포를 보지 못하는 에이전트는 설정 파일을 만들거나 일반 초기화 스크립트를 실행하지 않는다. 현재 확정된 것은 “특정 제품 모듈에 한정한 로컬 PoC”라는 방향뿐이며, 실제 경로·도구 인증·빌드 명령은 원본 checkout에서 다시 확인해야 한다.
+
+원본에 다시 접근하면 아래 순서로 일반 모델을 실제 구조에 매핑한다.
+
+1. 루트 build orchestrator와 공통 config를 확인한다.
+2. 대상 앱, 그 앱의 기능 라이브러리, 대응 E2E를 각각 하나의 path set으로 확정한다.
+3. 루트의 legacy instruction 파일과 에이전트별 자동 discovery 범위를 조사한다.
+4. user-home 전용 launcher가 필요한 instruction만 교체하도록 만든다.
+5. lint/test/build 하나로 root workspace 탐색이 남아 있는지 검증한다.
+
+이 다섯 항목이 확인되기 전에는 “모듈 한정 적용이 가능하다”는 PoC 판단을 실제 설정 완료로 바꾸지 않는다.
+
 ## 근거
 
 ELF의 legacy 진입 문서는 합계 4,735 lines / 132,394 bytes다.