ONAANDALL/frontend

Fork 0

Files

T

mind-one001 3641a21fc5 하수관로 md 추가

2026-04-17 11:28:03 +09:00

9.6 KiB

Raw Blame History

AGENTS.md

목적

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

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

공통 시작 기준

Codex 작업 루트는 가능하면 D:\workspace로 잡고, 공통 시작 기준은 D:\workspace\AGENTS.md를 따른다.

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

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

공통 시작 기준: D:\workspace\AGENTS.md
백엔드 세부 기준: D:\workspace\IIPBS\sewerage-service\AGENTS.md
프론트엔드 sn 앱 기준: D:\workspace\IIPBS-FRONTEND\frontend\apps\sn\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 내 타 앱 영향은 최소화한다.

작업 원칙

모든 변경은 2차 요구사항, 화면설계, 기능 명세 또는 승인된 작업 문서를 근거로 한다.
apps/sn과 packages/common/business_components 범위를 넘는 수정은 하지 않는다.
공통 패키지 수정은 sn 요구사항을 충족하기 위한 최소 범위로 제한한다.
다른 앱 전용 로직을 business_components에 넣지 않는다.
불확실한 경우 먼저 계획을 제시한다.
변경 전후 차이, 영향 범위, 검증 방법을 명확히 설명한다.
기존 주석은 임의로 제거하지 않는다.
복잡한 컴포넌트, 훅, 분기 로직, 상태 흐름, 데이터 변환 로직은 함수/메서드 단위 설명 주석을 충분히 작성한다.
한글이 깨지지 않도록 반드시 UTF-8로 유지한다.
작업 범위를 넓히기보다 sn 내부 해결을 우선한다.
백엔드 API 응답과 실제 브라우저 동작까지 함께 확인하는 것을 기본으로 한다.
작업 문서는 apps/sn/docs/ 하위에 작업 단위 폴더를 만들어 기록한다.

허용 작업

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

우선 판단 기준

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

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뿐 아니라 의존 패키지/타 앱 영향 가능성을 먼저 점검해야 한다.

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

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

타입 오류 처리 기준

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

주석 및 인코딩 규칙

파일 인코딩은 UTF-8로 유지한다.
한글 주석이 깨진 상태로 저장하지 않는다.
기존 주석은 정당한 이유 없이 삭제하지 않는다.
복잡한 렌더링 분기, 폼 처리, 데이터 변환, 트리 구조, 지도 연동, 표 컴포넌트 조합 로직은 함수/메서드 단위 주석을 상세히 작성한다.

문서 경로 기준

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

권장 경로:

apps/sn/docs/
apps/sn/docs/AI코딩하네스/
apps/sn/docs/응답표준화/
apps/sn/docs/검증/

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

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

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

결과 보고 형식

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

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

중요

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

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

9.6 KiB Raw Blame History