ONAANDALL/frontend

Fork 0

Files

T

mind-one001 d45cd79422 테스트코드 삭제

2026-09-23 16:00:28 +09:00

17 KiB

Raw Blame History

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 변경 전후에 기존 문구, 데이터, 이벤트와 업무 동작이 유지되는지 확인한다.

공통 시작 기준

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

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

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

공통 시작 기준: AGENTS.md
백엔드 세부 기준: BE_REPO_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 내 타 앱 영향은 최소화한다.

작업 원칙

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

우선 판단 기준

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

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

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 산출물을 갱신하면 개발 서버가 종료되거나 꼬일 수 있으므로, 빌드 검증은 사용자에게 확인한 뒤 개발 서버를 끄고 수행한다.

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

모든 세션·역할·문서/검증 섹션에 공통 D:/workspace/AGENTS.md의 테스트 파일 정리 기준을 적용한다. 에이전트가 테스트를 위해 만든 파일은 정식 회귀 테스트·재사용 가능한 소스·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에서 아래 빌드를 수행한다.

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로 유지한다.
한글 주석이 깨진 상태로 저장하지 않는다.
.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차사업 고도화 개발이다. 따라서 요구사항 구현은 적극적으로 수행하되, 범위를 넘는 변경은 먼저 설명하고 승인 없이 수정하지 않는다.

17 KiB Raw Blame History