7.6 KiB
AGENTS.md
목적
이 앱은 하수관로 운영관리 시스템 프론트엔드 sn 프로젝트이다.
이 문서는 apps/sn 작업 시 따라야 할 전용 작업 기준을 정의한다.
이 저장소는 pnpm workspace + Turborepo 기반 monorepo이며, 여러 회사/서비스가 함께 들어 있다.
따라서 sn 작업 시에는 작업 가능 범위와 수정 금지 범위를 엄격하게 지켜야 한다.
작업 대상
이번 작업에서 수정 가능한 경로는 아래 두 곳만 허용한다.
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/**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 내 타 앱 영향 최소화
작업 원칙
- 기존 외부 동작을 변경하지 않는다.
sn범위와business_components범위를 넘는 수정은 하지 않는다.- 공통 패키지 수정은
sn요구사항을 충족하기 위한 최소 범위로 제한한다. - 다른 앱 전용 로직을
business_components에 넣지 않는다. - 불확실한 경우 먼저 계획을 제시한다.
- 변경 전후 차이, 영향 범위, 검증 방법을 명확히 설명한다.
- 기존 주석은 임의로 제거하지 않는다.
- 복잡한 컴포넌트, 훅, 분기 로직을 수정할 때는 클래스/메서드/함수 단위 설명 주석을 충분히 작성한다.
- 한글이 깨지지 않도록 반드시 UTF-8로 유지한다.
- 작업 범위를 넓히기보다
sn내부 해결을 우선한다. - 작업 문서를 작성할때는
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 계약 임의 변경
- 백엔드 응답 구조를 프론트에서 임의 가정하여 데이터 구조를 바꾸는 작업
- 다른 회사/앱 전용 분기 추가
- 권한 범위를 넘어서는 전역 리팩토링
- 근거 없는 대량 수정
우선 판단 기준
문제가 발생했을 때 아래 순서로 해결 범위를 판단한다.
apps/sn내부에서 해결 가능한가packages/common/business_components수정으로 해결 가능한가- 그 외 공통 패키지 수정이 필요한가
3번에 해당하면 직접 수정하지 말고, 아래 내용을 정리해서 먼저 공유한다.
- 문제 원인
- 수정 필요 경로
sn영향 범위- 타 앱 영향 가능성
html 디렉터리 규칙
- 경로:
apps/sn/app/html - 이 디렉터리는 퍼블리싱/정적 HTML/로직 확인 목적의 별도 영역으로 본다.
html하위 작업 요청이 있을 때는 해당 디렉터리 중심으로만 작업한다.html하위 요청이라고 해서sn의 실제 앱 코드 전체를 함께 수정하지 않는다.html작업과 실제 서비스 앱 로직 변경이 같이 필요해 보이면 먼저 분리해서 설명한다.
빌드 및 검증 기준
이 저장소는 main 브랜치 push 전에 .husky/pre-push에서 아래 빌드를 수행한다.
pnpm turbo run build --filter="...[origin/$BRANCH]"
따라서 로컬 검증도 아래 순서로 수행하는 것을 기본으로 한다.
sn만 수정한 경우
pnpm --filter sn run build
pnpm turbo run build --filter=sn
business_components를 수정한 경우
pnpm --filter @common/business_components run build
pnpm --filter sn run build
pnpm turbo run build --filter="...[origin/main]"
pre-push와 동일한 최종 확인
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 두 곳뿐이다.
이 범위를 넘는 변경이 필요해 보이더라도, 먼저 설명하고 승인을 받기 전에는 수정하지 않는다.