sn > agents.md 추가

apps/sn/AGENTS.md

@@ -1,43 +1,238 @@
-## Project
-This repository contains a Next.js web application.
+# AGENTS.md
 
-Main technologies:
-- Next.js
-- TypeScript
-- pnpm workspace
-- turborepo
+## 목적
+이 앱은 하수관로 운영관리 시스템 프론트엔드 `sn` 프로젝트이다.
 
-이 저장소는 pnpm workspace + Turborepo 기반 monorepo이다.
+이 문서는 `apps/sn` 작업 시 따라야 할 전용 작업 기준을 정의한다.
+이 저장소는 pnpm workspace + Turborepo 기반 monorepo이며, 여러 회사/서비스가 함께 들어 있다.
+따라서 `sn` 작업 시에는 작업 가능 범위와 수정 금지 범위를 엄격하게 지켜야 한다.
 
-- 워크스페이스 범위는 `apps/*`, `apps/common/*`, `packages/*`, `packages/common/*`
-- 루트 스크립트는 `turbo run build`, `turbo run dev` 를 사용한다
-- `build` 작업은 의존 패키지의 `build` 를 먼저 수행한다 (`dependsOn: ["^build"]`)
-- `dev` 는 캐시하지 않는 지속 실행 작업이다
-- 변경 범위만 선택 실행할 수 있으므로, 전체 빌드보다 `--filter` 사용을 우선한다
+---
 
-## Encoding 
-- UTF-8 
-- 한글이 깨지지 않도록 주의할 것
+## 작업 대상
 
-## 주석 comment
-- 한글 주석을 삭제하지 말 것
+이번 작업에서 수정 가능한 경로는 아래 두 곳만 허용한다.
 
-## html 디렉토리
-- apps/sn/app/html
-- 이 디렉토리의 목적은 코드를 화면 publishing과 로직 설정을 위한 폴더이다.
-- html 하위 *.md 요청 작업시 html 디렉토리 이외의 수정이 되지 않도록 해야 한다.
+- `apps/sn/**`
+- `packages/common/business_components/**`
 
-## Monorepo structure
-apps/
-  _template
-  as
-  cm
-  cs
-  dc
-  dm
-  dm_new
-  fo
-  sn
-  st
-  wr
+위 두 경로를 제외한 나머지 경로는 모두 기본적으로 읽기 전용으로 간주한다.
 
+예를 들어 아래 경로는 직접 수정하면 안 된다.
+
+- `apps/as/**`
+- `apps/cm/**`
+- `apps/cs/**`
+- `apps/dc/**`
+- `apps/dm/**`
+- `apps/dm_new/**`
+- `apps/fo/**`
+- `apps/st/**`
+- `apps/wr/**`
+- `apps/common/**`
+- `packages/common/assets/**`
+- `packages/common/auth/**`
+- `packages/common/components/**`
+- `packages/common/config/**`
+- `packages/common/network/**`
+- `packages/mindone/**`
+- `packages/oneandall/**`
+- `packages/rsone/**`
+
+수정이 꼭 필요해 보이는 문제가 위 경로에서 발견되더라도, 임의로 수정하지 말고 영향 범위를 정리해서 먼저 보고해야 한다.
+
+---
+
+## 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` 등에 있으면 직접 수정하지 말고 보고만 한다.
+
+---
+
+## 작업 목표
+
+- 하수관로 운영관리 시스템 `sn`의 기존 화면 동작 유지
+- `sn` 내부 코드 가독성 향상
+- `sn` 화면/기능에 필요한 범위에서만 공통 비즈니스 UI 정리
+- `packages/common/business_components` 변경 시 `sn` 영향 범위 명확화
+- monorepo 내 타 앱 영향 최소화
+
+---
+
+## 작업 원칙
+
+1. 기존 외부 동작을 변경하지 않는다.
+2. `sn` 범위와 `business_components` 범위를 넘는 수정은 하지 않는다.
+3. 공통 패키지 수정은 `sn` 요구사항을 충족하기 위한 최소 범위로 제한한다.
+4. 다른 앱 전용 로직을 `business_components`에 넣지 않는다.
+5. 불확실한 경우 먼저 계획을 제시한다.
+6. 변경 전후 차이, 영향 범위, 검증 방법을 명확히 설명한다.
+7. 기존 주석은 임의로 제거하지 않는다.
+8. 복잡한 컴포넌트, 훅, 분기 로직을 수정할 때는 클래스/메서드/함수 단위 설명 주석을 충분히 작성한다.
+9. 한글이 깨지지 않도록 반드시 UTF-8로 유지한다.
+10. 작업 범위를 넓히기보다 `sn` 내부 해결을 우선한다.
+11. 작업 문서를 작성할때는 `apps/sn/docs` 폴더에 작업단위로 폴더를 생성해서 기록한다.
+
+---
+
+## 허용 작업
+
+- `apps/sn` 내부 화면/컴포넌트/훅/상태관리 코드 리팩토링
+- `apps/sn` 내부 API 호출부 정리
+- `apps/sn` 내부 타입 정리
+- `apps/sn` 내부 라우팅/화면 구조 보완
+- `packages/common/business_components` 내부 공통 비즈니스 컴포넌트 개선
+- `sn`이 사용하는 `business_components`의 타입/렌더링/구조 정리
+- 관련 문서 업데이트
+- 타입 오류 수정
+- 빌드 오류 수정
+
+---
+
+## 금지 작업
+
+- `sn`과 무관한 타 앱 수정
+- `packages/common/business_components` 외의 공통 패키지 수정
+- API 계약 임의 변경
+- 백엔드 응답 구조를 프론트에서 임의 가정하여 데이터 구조를 바꾸는 작업
+- 다른 회사/앱 전용 분기 추가
+- 권한 범위를 넘어서는 전역 리팩토링
+- 근거 없는 대량 수정
+
+---
+
+## 우선 판단 기준
+
+문제가 발생했을 때 아래 순서로 해결 범위를 판단한다.
+
+1. `apps/sn` 내부에서 해결 가능한가
+2. `packages/common/business_components` 수정으로 해결 가능한가
+3. 그 외 공통 패키지 수정이 필요한가
+
+3번에 해당하면 직접 수정하지 말고, 아래 내용을 정리해서 먼저 공유한다.
+
+- 문제 원인
+- 수정 필요 경로
+- `sn` 영향 범위
+- 타 앱 영향 가능성
+
+---
+
+## html 디렉터리 규칙
+
+- 경로: `apps/sn/app/html`
+- 이 디렉터리는 퍼블리싱/정적 HTML/로직 확인 목적의 별도 영역으로 본다.
+- `html` 하위 작업 요청이 있을 때는 해당 디렉터리 중심으로만 작업한다.
+- `html` 하위 요청이라고 해서 `sn`의 실제 앱 코드 전체를 함께 수정하지 않는다.
+- `html` 작업과 실제 서비스 앱 로직 변경이 같이 필요해 보이면 먼저 분리해서 설명한다.
+
+---
+
+## 빌드 및 검증 기준
+
+이 저장소는 `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`뿐 아니라 의존 패키지/타 앱 영향 가능성을 먼저 점검해야 한다.
+
+---
+
+## 타입 오류 처리 기준
+
+- push 실패 원인이 타입 오류라면 먼저 현재 수정 범위 안에서 해결 가능한지 확인한다.
+- `sn` 내부 타입 오류면 `apps/sn`에서 해결한다.
+- `business_components` 타입 오류면 그 패키지 안에서 해결한다.
+- 다른 공통 패키지 타입 오류가 원인이면 직접 고치지 말고 보고한다.
+
+---
+
+## 주석 및 인코딩 규칙
+
+- 파일 인코딩은 UTF-8로 유지한다.
+- 한글 주석이 깨진 상태로 저장하지 않는다.
+- 기존 주석은 정당한 이유 없이 삭제하지 않는다.
+- 복잡한 렌더링 분기, 폼 처리, 데이터 변환, 트리 구조, 지도 연동, 표 컴포넌트 조합 로직은 함수/메서드 단위 주석을 상세히 작성한다.
+
+---
+
+## 문서 경로 기준
+
+`sn` 관련 문서는 프론트 루트 `docs` 아래에서 별도 트랙으로 관리하는 것을 기본으로 한다.
+
+권장 경로:
+
+- `docs/sn/`
+- `docs/sn/refactoring/`
+- `docs/sn/response-standardization/`
+
+문서 작업 시에도 `sn` 범위를 벗어나는 앱 문서는 임의로 수정하지 않는다.
+
+---
+
+## 결과 보고 형식
+
+모든 작업 결과는 아래 형식을 따른다.
+
+- 작업 목적
+- 수정 대상 파일
+- 변경 내용 요약
+- 영향 범위
+- 테스트 / 검증 방법
+- 롤백 방법
+- 남은 리스크
+
+---
+
+## 중요
+
+이 모노레포는 여러 회사/서비스가 함께 사용하는 저장소다.
+이번 작업에서 직접 수정 가능한 범위는 `apps/sn`과 `packages/common/business_components` 두 곳뿐이다.
+
+이 범위를 넘는 변경이 필요해 보이더라도, 먼저 설명하고 승인을 받기 전에는 수정하지 않는다.