Pier_v1/RAG/design-model-box-sample_2/docs/AGENTS.md

Drawing Model Studio — 에이전트 작업 지침

사용자가 이 프로그램을 개발하며 정한 기준과 기존 정책문서를 통합한 저장소 지침이다. 저장소 전체의 코드 수정·모델 생성·검증·뷰어·캐시·보고서·배포 작업에 적용한다. 정리일: 2026-10-06.

목적과 우선순위

• 목표는 입력 도면에 대응하는 범용 공통 코드다. 도면명·시트 수·과거 모델에 의존하지 않고 현재 도면의 객체·치수·상세·배근 근거로 생성하며, 새 도면을 지원하도록 수정한 코드로 기존 검증 모델도 재현해야 한다.
• 사용자는 엔지니어다. 원도면과 사용자가 정한 기준을 결과에 맞춰 임의로 변경하지 않는다. 기존에 되는 코드를 먼저 확인하고, 안 되는 부분의 원인을 고친다.
• 현재 사용자의 명시적 지시가 기존 프로젝트 문서보다 우선한다. 개별 도면·제작행에 허용한 예외를 다른 객체나 새 도면에 확대하지 않는다.
• 기준 충돌은 적용 대상과 근거를 확인해 해결한다. 과거 문서의 작업 한정 제외·중단 조건을 전체 기능의 영구 제한으로 옮기지 않는다.
• 문서 작성, 코드 반영, 모델 생성, 화면 표시, 자동 검사 통과, 사용자 확정은 각각 실제 수행 여부를 구분해 보고한다.

작업 전 읽을 문서

코드 위치와 실행 방법은 README.md를 확인한다. 작업에 해당하는 아래 문서는 수정 전에 끝까지 읽는다.

• 형상·철근 생성 또는 검증: DRAWING_MODELING_RULES.md.
• 객체 귀속·부분 병합·공통 생성: OBJECT_MODEL_CONTRACT.md, 객체별 역할 및 모델링 적용 기준.
• 본체 사이클·일반부/경사부·배근 분류: 기존 배근 알고리즘 기준. 문서의 특정 모델 본수·피치와 작업 한정 날개벽 제외를 범용 상수·제외 규칙으로 사용하지 않는다.
• 개별 작업에 별도 검증 기준이 있으면 그 작업에서만 읽고 적용한다. 전용 객체 수·철근 치수·본수를 공통 생성 기준으로 복사하지 않는다.
• 콘크리트 공제·산식: 저장소의 수량 산출 기준 문서와 실제 보고서 계산 코드. 외부 기준을 변경하거나 최신 기준이라고 설명할 때는 적용 문서·판본·조항을 다시 확인한다. 기준 문서가 없으면 확인한 출처와 적용 범위를 기록한다.
• 이전 검증을 참고할 때: 해당 브랜치에 보관된 공통 코드 검증 기록. 기록이 없는 검사를 통과했다고 가정하지 않으며 부분 검사 결과를 전체 모델 검증으로 확대하지 않는다.

도면 일치와 수정 완료 기준

모든 형상은 객체별로 원도면의 평면·종단·정면·단면·상세와 일치해야 한다. 불일치하면 원인을 확인하고 생성 코드 또는 도면 연결을 수정한 뒤 재생성·재검증한다. 도면과 맞지 않는 형상을 완료 결과로 내보내지 않는다.

• 불일치는 작업 종료 이유가 아니다. 기존 정상 결과를 유지하면서 원도면 확인 → 원인 수정 → 재생성 → 재검증을 이어간다. 실제 근거 충돌이나 외부 장애는 구체적으로 보고하고, 독립적으로 진행할 수 있는 범위는 계속 처리한다.
• 결과가 나오게 하려고 도면 치수·좌표·수량, 검증 기준, 허용오차, 통과 조건을 바꾸지 않는다. 누락 검사를 건너뛰거나 상태 플래그만 바꿔 통과시키지 않는다.
• 정확도는 객체·절점·면·투영·치수·수량별 검사 근거로 확인한다. 화면이 비슷하거나 기존 캐시와 같다는 이유만으로 전체 일치를 선언하지 않는다. 수치 연산 오차와 실제 도면 불일치를 구분하고 오차를 숨기지 않는다.
• 근거가 부족하면 해당 원도면 영역·치수선·리더·설치면을 다시 확인한다. 카테고리 상식이나 이전 모델의 좌표로 빈 부분을 임의 완성하지 않는다.

객체별 정보와 부분 수정

• 상·하부 슬래브, 좌·우 벽체, 헌치, 날개벽, 난간벽, 접속슬래브, 브래킷 등 실제 물리 객체를 각각 유지한다. 여러 부재를 하나의 덩어리로 대체하지 않는다.
• 객체별 ID, 역할, 블럭, 좌우·시종점, 위치·표고, 사용한 도면 뷰, 접합 객체, 형상, 소속 철근, 물량, 검사 결과를 연결한다. 이름이 같아도 다른 물리 발생 객체는 독립적으로 남긴다.
• 설치 구역과 실제 분할 객체 수를 구분한다. 도면에 있는 이음으로 나뉜 객체를 임의로 합치거나, 발생 수를 문자 출현 횟수로 정하지 않는다.
• 철근은 그룹 호스트 목록과 별도로 한 본마다 소속 객체(occurrence_instance_ids)를 유지한다. 조회·이동·공제도 해당 한 본의 귀속을 사용한다.
• 검증된 객체는 보존한다. 수정 대상과 직접 연결된 범위만 다시 처리하고, 부분 결과로 전체 모델·본체·다른 블럭을 덮어쓰지 않는다.
• 객체별 구조는 향후 WBS·OBS·공정·자원·비용과 연결해 4D·5D BIM으로 확장할 기반이다. 이 연결을 위해 물리 ID·소속·물량을 보존하되, 아직 구현하지 않은 기능을 완료로 설명하지 않는다.

콘크리트 형상과 뷰어 방향

• 평면도는 위에서 본 도면이다. 평면에서 위치·방향·스큐·슬래브 절단 방향·날개벽 방향을 결정하고, 정면·종단·상세에서 높이·두께·구배·표고를 연결한다.
• 블럭별 종단 경사와 접속슬래브·브래킷 받침 높이를 함께 확인한다. 상·하부 슬래브와 접속슬래브의 두께·높이는 현재 도면에서 확인하며 특정 모델의 값을 범용 기본값으로 고정하지 않는다.
• 내부 헌치는 실제 삼각 단면을, 날개벽 접합 헌치는 실제 접촉 범위와 높이를 사용한다. 사각 덩어리나 본체 전체 길이로 대체하지 않는다.
• Top/Bottom, 축, 카메라 및 회전 조작 방향을 실제 투영으로 검사한다. 이미지를 맞추려고 모델 좌표·방향을 뒤집지 않는다. 치수보기 이미지 방향 수정과 모델 변경을 구분한다.
• 기본 뷰어에는 실제 형상 외곽과 물리 경계선을 표시한다. 평면 메시 삼각분할선은 숨기되 실제 절단·굴곡·객체 경계는 남긴다.
• 모델과 철근은 기존 뷰어에서 보여준다. 별도 형상검토창을 임의로 추가하지 않는다. 기존 톤·명칭·조작을 유지하고 화면을 바꾸면 실제 브라우저에서 확인한다.

철근 생성과 체결

• 형상을 먼저 확인하고 기존 생성 규칙으로 철근을 만든다. 일반부와 경사부의 설치 범위를 현재 도면에서 분리하며 경계 중복·누락·잘못된 연장을 허용하지 않는다.
• 사이클, 헌치근, 연결근은 도면에서 정한 소유 관계와 공통 station을 따른다. 임의 중앙정렬·독립 재분배·수량 맞추기용 간격 압축을 하지 않는다.
• 한 본 상세의 절점·절곡 순서·각도·반지름·직경·구간 길이·정착 방향을 유지한다. 외곽에 맞추려고 자르거나 늘이거나 축척하지 않는다.
• 제작 역할의 대응은 상세 형상과 설치면·객체 관계로 판단한다. 마크는 제작행 추적과 사용자가 지정한 이동 대상 식별에 사용하며, 같은 마크라는 이유만으로 다른 상세를 같게 생성하지 않는다.
• 피복은 객체·면별 도면값이다. 100(상면), 100(하면) 같은 표기를 연결하고 명목 피복과 철근 반지름을 구분한다. 임의 공통 피복으로 대체하지 않는다.
• 본체·날개벽·접속슬래브의 수평근·수직근 등 체결 대상 철근을 먼저 생성한 후 체결근을 배치한다. 콘크리트 안에 있다는 것만으로 체결로 판정하지 않고 실제 대상 철근을 감싸고 연결하는지 확인한다.
• 날개벽의 전면·배면·상부 수평근·수직근·단부근·연결근·체결근 등 현재 도면 제작행을 전수 확인한다. 특정 철근명을 전제로 생성하거나 도면에 존재하는 행을 누락하지 않는다.
• 연결철근의 긴 구간·경사 구간을 평면과 상세로 확인한다. 한쪽을 중복시키고 반대쪽 긴 부분을 비우지 않는다. 브래킷 철근도 현재 도면의 상세와 실제 각 발생 객체에 연결한다.
• 직경을 포함한 관 형상, 설치면, 정착 구간, 피복·외곽 이탈을 검사한다. 도면상 의도된 연결 틈·정착을 잘못된 돌출과 구분하며, 특정 마크의 검사 전체를 면제하지 않는다.
• 제작 상세 길이 합, 한 본 길이, 물리 본수, 총연장을 독립 대조한다. 도면 배근과 재료표가 실제로 충돌하면 둘의 값을 보존한다. 사용자가 도면 형상 우선으로 수량 차이를 허용한 범위는 그 허용을 기록하고 해당 수량 차이를 통과로 조작하지 않는다.
• 기존 철근 구분명과 블럭별 조회 순서를 유지한다. 역할 장부·화면 필터·물리 객체 귀속을 혼동하여 분류를 늘리거나 중복 집계하지 않는다.

사용자 피드백과 수정본

• 사용자가 지정한 객체·철근 번호·축·거리를 유지하고, 불확실한 항목만 채팅 안에서 실제 모델의 후보로 선택하게 한다. 이해하지 못했다는 이유로 포괄적인 제한이나 불필요한 기능 확장을 추가하지 않는다.
• 선택 전에는 변경하지 않으며, 선택하지 않은 객체와 철근은 보존한다. 모델이 바뀌면 이전 모델의 선택을 새 모델에 적용하지 않는다.
• 현재 철근 채팅의 범위는 번호 하나의 전체 또는 한 객체 소속 전체의 위치 이동이다. 이어지는 거리 입력을 같은 요청에 연결하며 회전·복사·새 철근 생성까지 임의 확대하지 않는다.
• 사용자가 요청한 도면 없는 기본 도형 생성과 후속 치수 변경을 지원하는 경로는 도면 근거 필수 규칙으로 막지 않는다. 이 경로의 입력 단위·치수와 기존 도면 모델을 구분한다.
• 사용자 요청에 따른 이동 미리보기·치수 수정·사용자 확정은 도면 자동 검사 승인과 구분한다. 새 좌표가 이전 좌표의 검사 결과를 상속하지 않는다.
• 철근 수정 후 OBJ는 수정 전 원본과 현재 수정된 모델을 선택해 내보낸다. 사용자에게 허용된 검토용 수정본도 실제 수정 좌표·철근을 포함하되 자동 승인본으로 바꾸지 않는다. 현재 각도 반영 선택과 mm 단위를 일관되게 반영한다.

캐시·JSON·수량·보고서

• 동일 도면의 원본 바이트 해시와 도면 묶음으로 저장 결과를 먼저 조회한다. 이름만 같다는 이유로 다른 모델을 재사용하지 않는다. HTTP 환경에서도 서버 해시 조회가 작동해야 한다.
• 기존 캐시가 있는데 전체 도면 분석을 다시 시작하는 문제를 조사할 때 파일명 정규화·도면 묶음·해시·저장 경로·검증 버전을 확인한다. 캐시를 통과시키려고 근거와 검사 상태를 바꾸지 않는다.
• 원도면 추출·근거·잠긴 형상을 재사용하고 수정 범위만 다시 해석한다. 반복 배치·좌표·길이·체적·수량 계산은 코드로 수행한다. 필요 없는 AI 호출을 추가하지 않는다.
• 같은 서버를 여는 다른 PC에서도 저장 모델을 조회할 수 있도록 서버의 영구 저장소를 사용한다. 다른 PC에 Git을 클론하는 것과 캐시를 이전하는 것은 다르므로 배포용 데이터 전달·설치 경로를 확인한다.
• 사용자가 보존하도록 지정한 도면 묶음·모델 캐시·관련 JSON을 유지한다. 보존 대상을 특정 도면명이나 고정 개수로 제한하지 않는다. 기타 파일·백업 정리는 실제 대상과 복구 여부를 확인한 뒤 수행하며 작업 캐시·필수 실행 파일을 임의 삭제하지 않는다.
• JSON 불러오기 후 콘크리트·철근·객체 귀속·수정 상태를 복원하고, 저장·내보내기와 왕복 확인한다. 캐시 조회·불러오기만으로 분석이나 수정을 자동 재개하지 않는다.
• 모델제작순서 안내는 처음 한 번만 표시하고 도면 입력 때 반복 표시하지 않는다. 보고서와 검사 기능은 저장 모델에서도 연결한다. 특정 모델의 느림은 불필요한 메시 분할·반복 계산·검사 캐시부터 확인한다.
• 수량은 콘크리트와 철근을 나눠 표시한다. 콘크리트는 길이 × 폭 × 두께, 사다리꼴 넓이 × 두께, 삼각 단면 넓이 × 길이 등 실제 형상에 맞는 치수 산식을 표시한다. 계산 완료 문구나 체적을 역산한 가짜 식으로 대체하지 않는다.
• 철근 미공제와 공제, 적용 가능한 LH 설비 공제·할증을 사용자가 선택할 수 있게 유지한다. 기준·판본·적용 범위·산식·타설량과 재료량을 함께 관리하며 특정 발주처 기준을 모든 공사에 강제하지 않는다.
• 철근 공제는 직경과 각 객체 내부의 실제 철근 구간을 사용한다. 여러 객체를 지나는 구간과 겹침은 중복 공제하지 않으며 외부 구간은 제외한다. 미확인 입력을 0으로 간주하거나 전체 중량을 객체별로 임의 비례 배분하지 않는다.

공통 코드·서비스·배포

• 운영 기준은 8097과 공통 소스다. 8098은 검증용이었던 페이지이며 별도 생성 규칙으로 분기하지 않는다. 현재 사용자가 요청하지 않으면 8098 서비스를 다시 만들거나 실행하지 않는다.
• 기본 8097에는 시공 미리보기를 숨기고 /-1에서 표시한다. 선택한 분리 타설 시나리오의 날개벽은 벽체 단계에 연결한다. 새로운 시공 순서는 근거 확인 후 사용자 선택을 반영한다.
• 로컬 주소 10.13.36.102:8097과 배포 주소 http://10.14.12.22/box-sample/, 배포 포트 5092의 역할을 구분한다. 배포 서버는 로컬 8097이나 VS Code 종료에 의존하지 않아야 한다.
• 배포 배치는 서버에서 다운로드 → 이미지 로드/빌드 → 실행 → 서비스 주소 확인을 연결한다. 기존 데이터·프록시 설정을 보존하고 서버 재부팅 후 자동 시작을 실제 환경에서 검증한다. 접근할 수 없는 서버까지 확인했다고 말하지 않는다.
• 지정된 사내 공유·AI 사용 승인은 해당 범위에 유지한다. 토큰·로그인 비밀을 코드·Git·보고서에 넣지 않는다. 페이지 AI의 모델 설정은 사용자의 최신 요청과 실제 지원 여부를 확인한다.
• Git 게시 요청 시 지정 브랜치 Hyein을 확인하고 요청 범위만 커밋한다. 관련 기능 설명은 README에 반영하며 사용자 작업을 덮어쓰지 않는다. push 후 원격 커밋을 확인한다.

실행과 검증

저장소 루트에서 실행한다. 지원 환경은 README의 Python 3.14 및 Node 환경을 따른다. NODE_BINARY는 실제 설치 경로로 지정하며 VS Code 버전 폴더의 오래된 경로를 고정하지 않는다.

python src/backend/serve.py                  # 기본 8097
node --check src/frontend/src/app.js        # 프런트엔드 문법
python -m unittest discover -s src/backend -p 'test_frontend_asset_paths.py'
git diff --check

• 변경한 생성·표시·이동·수량 경로에 해당하는 기존 회귀 검사를 실행한다. 서버 시작 전 검사를 삭제하거나 우회하지 않는다. 원본 자료가 필요한 검사와 저장소만으로 실행 가능한 검사를 구분한다.
• 생성 코드가 바뀌면 현재 모델을 완료한 뒤 변경한 공통 코드로 기존 검증 도면과 새 입력 도면을 재생성하고 형상·방향·객체 목록·철근 상세·소속·본수·길이·체결·보고서를 대조한다. 도면의 유형·상세·객체 구성이 늘어나면 회귀 대상을 함께 확장한다. 캐시 표시나 일부 사이클 검사만으로 전수 재생성 통과를 선언하지 않는다.
• 브라우저에서 실제 대상 작업을 열어 Top 및 관련 뷰, 객체 필터, 캐시·JSON, 보고서, OBJ 결과를 변경 범위에 맞게 확인한다.
• 결과 보고에는 실제 검사 범위·실패·원인·수정·미완료 사항을 정확하게 적는다. 이미 알려준 조건을 다시 묻지 말고 승인된 작업을 이어가며, 필요한 선택은 좁은 항목으로 제시한다.

Code Review Rules

• 원도면 불일치를 숨기기 위해 생성 기준·검사 게이트·수량·허용오차를 완화한 변경을 지적한다.
• 파일명·job ID·특정 모델 좌표·마크만으로 생성 분기하거나 이전 경로를 새 도면 입력으로 복사한 변경을 지적한다.
• 부분 수정으로 다른 객체를 삭제하거나 다른 occurrence의 철근을 이동·중복 집계하는 변경을 지적한다.
• 카메라·치수 이미지 문제를 모델 좌표 반전으로 해결하거나 실제 외곽을 바꾸는 변경을 지적한다.
• 검사되지 않은 수정본에 과거 승인 결과를 복사하거나 사용자 확정을 자동 검사 통과로 처리하는 변경을 지적한다.
• 캐시·JSON·보고서·내보내기 연결이 끊긴 변경과 운영·배포 서버를 개인 PC 실행에 종속시킨 변경을 지적한다.

파일 배치와 지침 적용 방식은 OpenAI 공식 AGENTS.md 안내를 따른다. 이 파일은 에이전트 작업 지침이며 런타임 검증을 대신하지 않는다.