# AGENTS.md

## 목적
이 앱은 하수관로 운영관리 시스템 프론트엔드 `sn` 프로젝트이다.

현재 목표는 리팩토링 전용 작업이 아니라, 하수관로 운영관리 시스템 2차사업 고도화를 수행하는 것이다.
즉, 기존 `sn` 화면과 흐름을 안정적으로 유지하면서 2차 요구사항에 해당하는 화면 개발, 기능 확장, 백엔드 연동 보완을 수행해야 한다.

## 사용자 작업 범위: UI/UX 및 퍼블리싱

현재 사용자와 진행하는 작업의 기본 범위는 UI/UX 및 프론트엔드 퍼블리싱으로 제한한다.
사용자가 별도로 명시하지 않는 한 아래 기준을 모든 후속 작업에 적용한다.

### 허용 범위

- 화면 레이아웃과 시각적 위계 조정
- JSX 마크업, Tailwind CSS, CSS 스타일 수정
- 색상, 여백, 간격, 크기, 타이포그래피, 아이콘, 테두리, 배경 조정
- 반응형 화면, 접근성, 포커스와 시각적 상태 개선
- 표시 전용 컴포넌트 구성과 퍼블리싱 품질 개선
- 기존 화면 내용과 동작을 유지하는 범위의 UI 구조 정리

### 기본 금지 범위

- 백엔드 코드, API 계약, 요청·응답 데이터 구조 변경
- `.env*`, middleware, 프록시, 인증과 권한 설정 변경
- 업무 로직, 상태 모델, 데이터 가공 및 저장 흐름 변경
- 데이터베이스, 서버 프로세스와 배포 설정 변경
- 패키지 설치·업데이트와 의존성 구조 변경
- 사용자 요청 없이 화면의 문구, 데이터 항목, 기능 동작 변경

금지 범위의 변경이 필요해 보이면 직접 수정하지 않고 원인과 필요한 작업만 사용자에게 설명한다.

### UI 검증 안전 기준

- 사용자가 실행한 개발 서버가 있는지 실제 앱 포트까지 먼저 확인한다.
- 개발 서버 실행 중에는 같은 앱의 `next build`를 실행하지 않는다.
- UI 작업의 기본 검증은 실행 중인 개발 서버의 HMR, 브라우저 화면 확인, `git diff --check`로 제한한다.
- 개발 서버 종료, `.next` 정리, 전체 빌드와 프로세스 재시작은 사용자가 명시적으로 승인한 경우에만 수행한다.
- UI 변경 전후에 기존 문구, 데이터, 이벤트와 업무 동작이 유지되는지 확인한다.

---

## 공통 시작 기준

개발자마다 드라이브와 상위 작업 폴더 위치가 다르므로 특정 드라이브·사용자 디렉터리의 절대경로를 기준으로 사용하지 않는다.

경로 별칭은 `apps/sn/AGENTS.md`가 있는 디렉터리(`FE_APP_ROOT`)를 기준으로 다음과 같이 해석한다. 상대경로는 현재 셸의 실행 위치가 아니라 이 파일의 위치를 기준으로 계산한다.

- `FE_APP_ROOT`: 이 파일이 있는 `apps/sn` 디렉터리
- `FE_REPO_ROOT`: `FE_APP_ROOT/../..`
- `WORKSPACE_ROOT`: `FE_APP_ROOT/../../..`
- `COMMON_ROOT_AGENTS`: `WORKSPACE_ROOT/AGENTS.md`
- `BE_REPO_ROOT`: `WORKSPACE_ROOT/IIPBS` (Backend Git 저장소 루트)
- `BE_SERVICE_ROOT`: `BE_REPO_ROOT/sewerage-service` (하수관로 백엔드 서비스 모듈)
- `COMMON_DOCS_ROOT`: `BE_REPO_ROOT/docs`
- `FE_APP_DOCS_ROOT`: `FE_APP_ROOT/docs`

경로 결정은 아래 우선순위를 따른다.

1. 작업 환경이나 사용자가 `WORKSPACE_ROOT`, `COMMON_DOCS_ROOT`, `BE_REPO_ROOT`, `BE_SERVICE_ROOT` 등의 유효한 경로를 명시한 경우 그 값을 우선한다. 저장소를 서로 다른 상위 폴더에 배치한 개발자도 이 방식으로 사용할 수 있다.
2. 명시값이 없으면 위의 `FE_APP_ROOT` 기준 상대경로로 계산한다. 드라이브 문자나 사용자별 상위 디렉터리 이름이 달라도 같은 저장소 배치 구조를 사용할 수 있다.
3. 계산한 경로는 사용 전에 대상 파일이나 디렉터리의 존재 여부를 확인한다. 없거나 후보가 여러 개인 경우 특정 절대경로를 추측하지 말고 현재 저장소에서 확인 가능한 작업만 진행한 뒤 필요한 경로를 사용자에게 확인한다.
4. 작업 문서와 결과 보고에는 특별한 사유가 없으면 개발자별 절대경로 대신 위 경로 별칭이나 저장소 기준 상대경로를 기록한다.

PowerShell에서 현재 프론트엔드 저장소를 기준으로 확인할 때는 다음처럼 동적으로 계산할 수 있다. 각 단계는 앞 단계에서 찾은 저장소 위치를 기반으로 하므로 개발자별 설치 경로에 의존하지 않는다.

```powershell
$feRepoRoot = (git rev-parse --show-toplevel).Trim()
$feAppRoot = Join-Path $feRepoRoot 'apps/sn'
$workspaceRoot = Split-Path $feRepoRoot -Parent
$commonRootAgents = Join-Path $workspaceRoot 'AGENTS.md'
$beRepoRoot = Join-Path $workspaceRoot 'IIPBS'
$beServiceRoot = Join-Path $beRepoRoot 'sewerage-service'
$commonDocsRoot = Join-Path $beRepoRoot 'docs'
```

공통 시작 기준은 `COMMON_ROOT_AGENTS`를 따른다.

이 파일은 프론트엔드 `sn` 앱 세부 기준이다.

백엔드(`sewerage-service`)와 함께 수정하거나 API/응답/DB/인증/권한 연동 영향이 있는 작업은 아래 파일을 함께 확인한다.

- 공통 시작 기준: `AGENTS.md`
- 백엔드 세부 기준: `BE_SERVICE_ROOT/AGENTS.md`
- 프론트엔드 `sn` 앱 기준: `FE_APP_ROOT/AGENTS.md`

---

## 작업 대상

이번 작업에서 직접 수정 가능한 경로는 아래 두 곳만 허용한다.

- `apps/sn/**`
- `packages/common/business_components/**`

위 두 경로를 제외한 나머지 경로는 모두 기본적으로 읽기 전용으로 간주한다.

예를 들어 아래 경로는 직접 수정하면 안 된다.

- `apps/as/**`
- `apps/cm/**`
- `apps/cs/**`
- `apps/dc/**`
- `apps/dm/**`
- `apps/dm_new/**`
- `apps/fo/**`
- `apps/st/**`
- `apps/wr/**`
- `apps/common/**`
- `docs/**`
- `packages/common/assets/**`
- `packages/common/auth/**`
- `packages/common/components/**`
- `packages/common/config/**`
- `packages/common/network/**`
- `packages/mindone/**`
- `packages/oneandall/**`
- `packages/rsone/**`

수정이 꼭 필요해 보이는 문제가 위 경로에서 발견되더라도, 임의로 수정하지 말고 아래 내용을 먼저 정리해서 공유한다.

- 문제 원인
- 수정 필요 경로
- `sn` 영향 범위
- 타 앱 영향 가능성

---

## Monorepo 이해

이 저장소는 pnpm workspace + Turborepo 기반 monorepo이며, 여러 회사/서비스가 함께 들어 있다.

워크스페이스 구조는 아래와 같다.

- `apps/*`
- `apps/common/*`
- `packages/*`
- `packages/common/*`

현재 작업 대상은 아래 두 축이다.

- 서비스 앱: `apps/sn`
- 공통 비즈니스 UI 패키지: `packages/common/business_components`

`sn` 앱은 아래 공통 패키지들을 사용하지만, 이번 권한 범위상 직접 수정 가능한 공통 패키지는 `business_components`만이다.

- `@common/assets`
- `@common/business_components`
- `@common/components`
- `@common/config`

즉, `sn`에서 문제가 보이더라도 원인이 `@common/components`, `@common/auth`, `@common/network` 등에 있으면 직접 수정하지 말고 보고만 한다.

---

## 작업 목표

- 2차사업 요구사항을 `sn` 화면과 흐름에 반영한다.
- `sn` 앱의 기존 사용자 동작을 가능한 한 유지하면서 기능을 확장한다.
- 백엔드(`sewerage-service`)와의 연동을 기준으로 화면, 폼, 조회/저장 흐름을 정확히 맞춘다.
- `business_components` 수정이 필요할 때는 `sn` 요구사항을 만족하는 최소 범위로 수행한다.
- monorepo 내 타 앱 영향은 최소화한다.

---

## 작업 원칙

- `sn` 프론트엔드 엑셀 다운로드 기능을 신규 개발하거나 수정할 때는 `src/shared/util/download-excel-workbook.ts` 재사용을 먼저 검토한다. 세부 기준은 [컴포넌트정책의 공통 유틸 재사용 기준](docs/기준문서/004-컴포넌트정책.md#공통-유틸-재사용-기준)을 따른다. 이 코드 경로는 `FE_APP_ROOT` 기준이다.
- 일반 목록·모든 팝업은 공통 AGENTS.md의 서버 페이징·지도·Excel 계약을 따른다. 지도 전체 표출에 현재 그리드 페이지 배열을 재사용하지 않는다. Excel은 적용조건 전체를 사용하고 대량 원시 자료는 서버 생성으로 분리한다. 화면 페이징/페이징 없음 예외는 사유와 검증 범위를 메뉴 > 화면명별로 기록한다.

1. 모든 변경은 원본 요구사항정의서와 화면설계서, 2차 요구사항, 기능 명세 또는 승인된 작업 문서를 근거로 한다.
2. `apps/sn`과 `packages/common/business_components` 범위를 넘는 수정은 하지 않는다.
3. 공통 패키지 수정은 `sn` 요구사항을 충족하기 위한 최소 범위로 제한한다.
4. 다른 앱 전용 로직을 `business_components`에 넣지 않는다.
5. 불확실한 경우 먼저 계획을 제시한다.
6. 변경 전후 차이, 영향 범위, 검증 방법을 명확히 설명한다.
7. 기존 주석은 임의로 제거하지 않는다.
8. 신규/수정 함수, 주요 상수, 주요 변수, `useState`, `useRef`, `useMemo`, `useCallback`에는 화면/API/상태 흐름에서 맡는 역할을 알 수 있는 주석을 작성한다.
9. 한글이 깨지지 않도록 반드시 UTF-8로 유지한다.
10. 작업 범위를 넓히기보다 `sn` 내부 해결을 우선한다.
11. 백엔드 API 응답과 실제 브라우저 동작까지 함께 확인하는 것을 기본으로 한다.
12. 작업 문서는 `apps/sn/docs/` 하위에 작업 단위 폴더를 만들어 기록한다.
13. 신규 화면이나 UI 변경은 먼저 기존 `sn` 화면과 공통 컴포넌트/레이아웃 패턴을 따르는 방향으로 설계한다.
14. `BaseLayout`, `NoFooterLayout`, `PageLayout`, `SearchDiv`, `SearchFormLeft/Right`, `ListDiv`, `UiTable`, `UiModal`, `Gis` 조합을 우선 재사용한다.
15. 새 UI 구조가 꼭 필요하면 기존 패턴으로 해결되지 않는 이유를 먼저 설명한다.

## 원본 요구사항 사전 확인

- 모든 `sn` 화면 설계, 구현, 수정, 검증과 문서 작업은 시작 전에 아래 원본 파일에서 관련 범위를 직접 확인한다.
  - `COMMON_DOCS_ROOT/기준문서/화면설계서.pptx`
  - `COMMON_DOCS_ROOT/기준문서/요구사항정의서.xlsx`
- 화면설계서의 관련 슬라이드, 화면 ID, 입력항목, 버튼, 표 컬럼과 사용자 흐름을 확인한다.
- 요구사항정의서의 관련 시트, 요구사항 ID, 기능 목적과 완료 조건을 함께 대조한다.
- `de`나 메인 에이전트의 요약, 기존 작업계획 또는 현재 화면만으로 원본 확인을 대체하지 않는다.
- 확인한 요구사항 ID, 화면 ID와 슬라이드를 작업계획 또는 결과 보고에 남긴다.
- 원본에 없는 화면 동작이나 데이터 항목은 임의로 추가하지 않고 `설계 제안` 또는 `확인 필요`로 구분한다.
- 상세 절차는 `COMMON_DOCS_ROOT/기준문서/012-원본요구사항사전확인.md`를 따른다.

---

## 허용 작업

- `apps/sn` 내부 신규 화면/기능 개발
- `apps/sn` 내부 화면/컴포넌트/훅/상태관리 코드 보완 및 리팩토링
- `apps/sn` 내부 API 호출부 정리
- `apps/sn` 내부 타입 정리
- `apps/sn` 내부 라우팅/화면 구조 보완
- `packages/common/business_components` 내부 공통 비즈니스 컴포넌트 개선
- `sn`이 사용하는 `business_components`의 타입/렌더링/구조 개선
- 요구사항 반영을 위한 UI/UX 보완
- 문서 업데이트
- 타입 오류 수정
- 빌드 오류 수정
- 테스트/검증 코드 또는 검증용 산출물 작성

---

## 금지 작업

- `sn`과 무관한 타 앱 수정
- `packages/common/business_components` 외의 공통 패키지 수정
- 요구사항 근거 없는 기능 추가
- 백엔드 응답 구조를 프론트에서 임의 가정하여 계약을 바꾸는 작업
- 다른 회사/앱 전용 분기 추가
- 권한 범위를 넘어서는 전역 리팩토링
- 근거 없는 대량 수정

---

## 우선 판단 기준

문제가 발생했을 때 아래 순서로 해결 범위를 판단한다.

1. `apps/sn` 내부에서 해결 가능한가
2. `packages/common/business_components` 수정으로 해결 가능한가
3. 그 외 공통 패키지 수정이 필요한가

3번에 해당하면 직접 수정하지 말고, 아래 내용을 정리해서 먼저 공유한다.

- 문제 원인
- 수정 필요 경로
- `sn` 영향 범위
- 타 앱 영향 가능성

---

## html 디렉터리 규칙

- 경로: `apps/sn/app/html`
- 이 디렉터리는 퍼블리싱/정적 HTML/로직 검토 목적의 별도 영역으로 본다.
- 공식 HTML 시안은 기본적으로 `COMMON_DOCS_ROOT/작업계획/<작업폴더>/` 아래 단일 `.html` 파일로 만든다.
- `apps/sn/app/html` 작업은 사용자가 앱 라우트 기반 미리보기를 명시적으로 요청한 경우에만 사용한다.
- `html` 하위 요청이라고 해서 `sn`의 실제 앱 코드 전체를 함께 수정하지 않는다.
- `html` 작업과 실제 서비스 앱 로직 변경이 같이 필요해 보이면 먼저 분리해서 설명한다.

---

## 빌드 및 검증 기준

VSCode나 별도 터미널에서 `sn` Next 개발 서버가 실행 중이면 `next build`, `pnpm --filter sn run build`, `pnpm turbo run build --filter=sn` 같은 빌드 명령을 실행하지 않는다.
개발 서버와 빌드가 동시에 `.next` 산출물을 갱신하면 개발 서버가 종료되거나 꼬일 수 있으므로, 빌드 검증은 사용자에게 확인한 뒤 개발 서버를 끄고 수행한다.

### 프론트엔드 실행 프로세스 관리

- 모든 세션·역할·문서/검증 섹션에 `COMMON_ROOT_AGENTS`의 테스트 파일 정리 기준을 적용한다. 에이전트가 테스트를 위해 만든 파일은 정식 회귀 테스트·재사용 가능한 소스·fixture·mock·임시 라우트를 포함해 위치와 관계없이 결과를 요약한 뒤 작업 종료 전에 삭제한다(2026-09-23 사용자 지시). 전용 빈 폴더와 끊어진 실행 명령도 정리한다. 명시 보존 요청 파일·최종 산출물·사용자 원본/복구 백업은 유지한다. 기존 타 작업자 테스트 자산은 삭제 권한을 먼저 확인한다. 사용자 dev server의 .next·공유 캐시·node_modules는 포괄 삭제하지 않는다.

- Codex 에이전트가 작업 또는 검증을 위해 직접 기동한 `next dev`, `dev:sn`, Turborepo dev와 기타 프론트엔드 장시간 실행 프로세스는 작업 종료 전에 반드시 종료한다.
- 셸, 백그라운드, 숨김 창 등 VSCode 밖에서 에이전트가 기동한 프로세스도 종료 대상이다.
- 사용자가 VSCode 또는 별도 터미널에서 직접 실행한 프론트엔드 개발 서버는 임의로 종료·재시작·교체하지 않는다. 종료가 필요하면 먼저 사용자에게 확인한다.
- 기동 시 PID와 포트를 기록하고, 종료 시에는 에이전트가 기동한 정확한 PID와 하위 프로세스 트리만 종료한다.
- 사용자가 계속 실행해 두라고 명시한 경우에는 종료하지 않고 최종 보고에 PID, 포트와 종료 방법을 남긴다.
- 최종 보고 전에 에이전트가 사용한 프론트엔드 포트 해제와 임시 로그 파일 핸들 종료를 확인한다.

이 저장소는 `main` 브랜치 push 전에 `.husky/pre-push`에서 아래 빌드를 수행한다.

```sh
pnpm turbo run build --filter="...[origin/$BRANCH]"
```

따라서 로컬 검증도 아래 순서로 수행하는 것을 기본으로 한다.

### `sn`만 수정한 경우

```powershell
pnpm --filter sn run build
pnpm turbo run build --filter=sn
```

### `business_components`를 수정한 경우

```powershell
pnpm --filter @common/business_components run build
pnpm --filter sn run build
pnpm turbo run build --filter="...[origin/main]"
```

### pre-push와 동일한 최종 확인

```powershell
git fetch origin
pnpm turbo run build --filter="...[origin/main]" --dry-run
pnpm turbo run build --filter="...[origin/main]"
```

`business_components`를 수정했는데 이 빌드가 깨지면, `sn`뿐 아니라 의존 패키지/타 앱 영향 가능성을 먼저 점검해야 한다.

가능하면 아래 검증도 함께 수행한다.

- `sn` 개발 서버 실행
- 백엔드 연동 확인
- 브라우저 화면 동작 확인
- 네트워크 응답 확인

---

## 타입 오류 처리 기준

- push 실패 원인이 타입 오류라면 먼저 현재 수정 범위 안에서 해결 가능한지 확인한다.
- `sn` 내부 타입 오류면 `apps/sn`에서 해결한다.
- `business_components` 타입 오류면 그 패키지 안에서 해결한다.
- 다른 공통 패키지 타입 오류가 원인이면 직접 고치지 말고 보고한다.

---

## 주석 및 인코딩 규칙

- 파일 인코딩은 UTF-8로 유지한다.
- 한글 주석이 깨진 상태로 저장하지 않는다.
- `.md`, `.toml` 같은 한글 포함 텍스트 파일은 저장 직후 다시 열어 한글이 정상인지 확인한다.
- 한글이 많은 문서는 셸 리다이렉션(`>`, `>>`)이나 검증 없는 `Set-Content`, `Out-File`로 바로 덮어쓰지 않는다.
- 기존 주석은 정당한 이유 없이 삭제하지 않는다.
- 복잡한 렌더링 분기, 폼 처리, 데이터 변환, 트리 구조, 지도 연동, 표 컴포넌트 조합 로직은 함수/메서드 단위 주석을 상세히 작성한다.
- 신규/수정 상수와 변수는 이름만으로 의도가 충분히 드러나지 않으면 선언부 근처에 역할, 단위, 백엔드 계약, 화면 상태와의 관계를 주석으로 남긴다.
- `useRef`로 비동기 요청, 팝업 창, 지도 객체, 체크 상태를 보관하는 경우에는 왜 state가 아니라 ref를 쓰는지 주석으로 남긴다.

---

## 문서 경로 기준

`sn` 관련 문서는 앱 내부 문서로 관리하는 것을 기본으로 한다.

권장 경로:

- `apps/sn/docs/기준문서/`
- `apps/sn/docs/작업계획/`
- `apps/sn/docs/검증/`

공통 개발 흐름과 멀티에이전트 기준은 아래 공통 문서를 우선 참조한다.

- `COMMON_DOCS_ROOT/기준문서/010-AI개발작업흐름.md`
- `COMMON_DOCS_ROOT/기준문서/011-멀티에이전트운영.md`

1차 프로젝트 당시에는 AI 코딩 문서 체계를 사용하지 않았으므로, 신규 문서를 `phase2`처럼 별도 단계 폴더로 분리하지 않고 `apps/sn/docs/` 바로 아래 주제별 한글 폴더로 관리한다.

작업계획 문서는 아래 원칙으로 관리한다.

- `apps/sn/docs/작업계획/작업카드-템플릿.md`는 최상위에 유지한다.
- 실제 기능 문서는 `apps/sn/docs/작업계획/<기능ID-기능명>/` 폴더 단위로 관리한다.
- 같은 기능의 FE 작업카드, 관련 메모, 추가 계획 문서는 같은 기능 폴더 안에 함께 둔다.
- 역할이 있는 문서 파일명은 `<순번>-<역할>-<프로젝트>-<기능명>-<문서종류>.md` 형식을 우선 사용한다.
- 날짜는 파일명 보조 정보로만 사용하고, `apps/sn/docs/작업계획/` 아래에 날짜 파일을 평면으로 계속 쌓지 않는다.
- 기존 `md` 문서의 경로와 파일명은 사용자 요청이나 승인된 구조 개편 없이 임의로 바꾸지 않는다.
- 기존 문서를 수정할 때는 현재 경로와 파일명을 유지한 채 내용을 갱신하는 것을 기본으로 한다.
- 공통 기준은 `COMMON_DOCS_ROOT/작업계획/작업계획-폴더규칙.md`를 함께 참고한다.
- UI/레이아웃 기준은 `FE_APP_DOCS_ROOT/기준문서/013-UI레이아웃가이드.md`를 함께 참고한다.

문서 작업 시에도 `sn` 범위를 벗어나는 앱 문서는 임의로 수정하지 않는다.

루트 `docs/**`는 다른 회사/서비스 리소스를 포함할 수 있으므로 `sn` 작업 중 임의로 수정하지 않는다. 루트 `docs/**` 변경이 필요해 보이면 변경 이유, 영향 범위, `apps/sn/docs/**` 대체 가능 여부를 먼저 정리하고 사용자 승인을 받는다.

---

## 결과 보고 형식

모든 작업 결과는 아래 형식을 따른다.

- 작업 목적
- 수정 대상 파일
- 변경 내용 요약
- 영향 범위
- 테스트 / 검증 방법
- 롤백 방법
- 남은 리스크

---

## 중요

이 모노레포는 여러 회사/서비스가 함께 사용하는 저장소다.
이번 작업에서 직접 수정 가능한 범위는 `apps/sn`과 `packages/common/business_components` 두 곳뿐이다.

하지만 이번 프로젝트의 성격은 리팩토링 전용이 아니라 `sn` 2차사업 고도화 개발이다.
따라서 요구사항 구현은 적극적으로 수행하되, 범위를 넘는 변경은 먼저 설명하고 승인 없이 수정하지 않는다.