# 프로젝트 운영 지침 통합본 모든파일의 첫줄에는 주석을통해서 프로젝트 _St 폴더부터 상대 폴더 위치 혹은 절대 위치를 넣도록 한다. 첫줄에 못하면 2째줄에 넣도록한다. 제미나이와 협업에 반드시 필요하다. .. 또는 ai_read*파일을 폴더별로 가능하니까 그 파일에서 파일명과 간략기능 을 넣어서 쉽게 이해할수있도록한다. ## A. 전체 프로젝트 공용 지침 ### 0. 기본 원칙 * 불필요한 사족 없이 핵심만 답변한다. * 요청 범위 안에서만 구현하며, 임의 추가·변경·삭제는 하지 않는다. * 소스 확인 전에는 원인, 파일명, 함수명, 수정 위치를 단정하지 않는다. * 수정안은 실제 소스 확인 후 확정한다. * 기능이 복잡하거나 파일이 커질 경우, 기능별 파일 분리 방식을 먼저 제안하고 사용자 동의를 받은 후 진행한다. * “되는 것처럼 보이는 상태”를 완료로 보지 않는다. * 완료는 코드 반영이 아니라 테스트 결과로 판단한다. --- ### 1. 기존 기능 유지 기준 기존 기능 유지 원칙은 작업 단계에 따라 다르게 적용한다. * 완성본 유지보수나 단순 버그 수정 단계에서는 기존 기능, UI, 파일 구조, 동작 흐름을 보수적으로 유지한다. * 초기 개발 단계에서는 구조 변경, 파일 분리, 기능 정리가 가능하되 사용자와 방향을 먼저 맞춘다. * 대폭 마이그레이션 단계에서는 기존 구조보다 새 구조의 안정성, 단순성, 확장성을 우선할 수 있다. * 기존 기능 제거 또는 큰 동작 변경이 있으면 이유와 영향 범위를 먼저 설명한다. * 작업 단계가 불명확하면 유지보수 단계 기준으로 판단한다. * 이전 완료 기능을 깨뜨릴 가능성이 있는 수정은 반드시 test_* 회귀 테스트 항목을 먼저 확인한다. --- ### 2. 작업 단계 구분 사용자가 정확히 “코딩 시작”이라고 말하기 전에는 검토, 분석, 설계, 그리고 필요시 코드 수정 까지만 진행한다. zip다운로드해서 전송은 대기한다. #### 코딩 시작 전 허용 작업 * 코드 구조 파악 * 원인 역추적 * 수정 위치 확인 * 충돌 가능성 검토 * 패치 방향 설계 * 수정 후보 정리 * diff 초안 또는 예시 코드 작성 * ai_read.md 정리 방향 또는 초안 준비 * test_list.md 계획 수립 * 다음 버전 번호 계획 * 테스트 항목 정리 * ZIP 내부 구조 확인을 위한 임시 해제 #### 코딩 시작 전 금지 작업 사용자가 정확히 “코딩 시작”이라고 말하기 전에는 다음 작업을 하지 않는다. * 최종 제출용 ZIP 생성 * 수정 완료본 파일 제공 * 전체 파일 재전송 * 사용자에게 최종 산출물처럼 보이는 결과 제공 --- ### 3. 코딩 시작 기준 사용자가 정확히 “코딩 시작”이라고 말하면 실제 파일 수정을 최종 대화에 맞줘 마무리 시작한다. #### 시작 순서 1. 최신 기준 ZIP 해제 2. ai_read.md 확인 3. ai_read_패치.md, ai_read_완료.md, ai_read_삭제.md 확인 4. test_list.md 확인 5. 현재 소스 구조 확인 6. 완료 예정 작업 목록을 대화창에 먼저 출력 7. 실제 코딩 시작 #### 기준 우선순위 1. 사용자 최신 지시 2. 현재 실제 소스 3. ai_read.md 4. ai_read_패치.md 5. ai_read_완료.md 6. ai_read_삭제.md 7. 과거 대화 기록 ai_read.md가 현재 소스나 사용자 최신 지시와 충돌하면 현재 소스와 사용자 최신 지시를 우선한다. --- ### 4. ai_read 문서 운영 원칙 ai_read 문서는 버전 일기장이 아니라 “현재 기준서”로 유지한다. #### 기준 문서명 * `ai_read.md` 현재 정상 기준, 절대 원칙, 현재 구조, 진행률 요약 * `ai_read_패치.md` 현재 작업 중인 항목, 예정, 진행중, 검증대기 항목 * `ai_read_완료.md` 테스트 로그로 완료 확인된 항목 * `ai_read_삭제.md` 삭제, 숨김, 누락, 제거, 폐기된 기능 기록 * `test_list.md` 전체 테스트 목록, 상태, 담당 폴더, 완료율, 다음 작업 #### ai_read.md에 유지할 내용 * 현재 절대 원칙 * 현재 정상 구조 * 현재 파일별 역할 * 현재 진행률 * 현재 남은 문제 * 바로 다음 작업 * 폐기된 로직 요약 * test_* 운영 기준 #### ai_read_완료.md 기준 * 완료는 실제 테스트 로그가 있을 때만 기록한다. * 코드 반영만 된 항목은 완료가 아니다. * 완료 항목에는 완료 버전, 테스트 파일명, 테스트 결과, 영향 범위를 기록한다. #### ai_read_삭제.md 기준 * 삭제 또는 폐기된 기능 * 되살리면 안 되는 로직 * 이전 패치에서 누락된 적 있는 기능 * 다시 누락되면 치명적인 기능 * 기존 기능에서 제거된 UI/버튼/상태값 --- ### 5. test_* 기반 완료 관리 원칙 모든 기능은 test_* 파일을 기준으로 관리한다. #### 핵심 원칙 * 각 모듈은 자기 폴더에 `test_*`로 시작하는 테스트 파일을 가진다. * `test_*` 파일에 없는 기능은 완료 기능으로 인정하지 않는다. * 완료는 코드 반영이 아니라 테스트 OK 로그가 있을 때만 완료로 표시한다. * 테스트가 없는 기능 추가는 임시 작업으로만 본다. * 기존 완료 기능은 test_* 회귀 테스트로 보호한다. #### 테스트 파일명 기준 모든 테스트 파일은 반드시 `test_*`로 시작한다. 예시: ```text Auto8700/ test_auto8700_module.py test_auto8700_cdp.py WS8771/ test_ws8771_module.py test_ws8771_mouse_coord.py test_ws8771_file_download.py Heart8772/ (( 폐기 함 미사용 )) test_heart8772_module.py test_heart8772_origin.py RTC8790_8791/ test_rtc8790_module.py test_rtc8790_control.py IG_Sorter_Yello/ test_ext_module.html test_ext_module.js test_ext_dom.js test_ext_ws_bridge.js Shared/ test_shared_canonical.py test_shared_log_policy.py ``` #### 테스트 단계 1. 모듈 단독 테스트 2. 모듈 간 연결 테스트 3. 통합 dry-run 테스트 4. 실제 동작 테스트 5. 회귀 테스트 #### 테스트 상태값 test_list.md에는 아래 상태값만 사용한다. ```text [예정] [진행중] [코드반영] [검증대기] [완료] [보류] [폐기] ``` #### 결과값 테스트 결과값은 아래 4개만 사용한다. ```text OK FAIL SKIP UNKNOWN ``` * `UNKNOWN`을 `OK`처럼 처리하지 않는다. * 실패를 성공처럼 처리하지 않는다. * 조용한 fallback으로 실패를 숨기지 않는다. #### 완료 조건 아래 조건을 모두 만족해야 `[완료]`로 표시한다. ```text 1. test_* 파일 존재 2. 테스트 실행 결과 OK 3. test_list.md 상태 완료 4. ai_read_완료.md 기록 5. 필요한 경우 manifest/version 반영 ``` --- ### 6. test_list.md 운영 기준 test_list.md는 전체 작업의 진행률 표이다. #### 필수 항목 각 테스트 항목은 아래 정보를 가진다. ```text ID 상태 모듈 테스트 파일 검증 기능 완료 기준 현재 결과 실패 원인 다음 작업 관련 ai_read 문서 ``` #### 예시 ```text | ID | 상태 | 모듈 | 테스트 파일 | 기능 | 완료 기준 | 현재 결과 | 다음 작업 | |---|---|---|---|---|---|---|---| | T-AUTO-001 | [예정] | Auto8700 | test_auto8700_cdp.py | CDP 8700 확인 | /json/version OK | UNKNOWN | 테스트 파일 생성 | | T-WS-001 | [완료] | WS8771 | test_ws8771_mouse_coord.py | origin+client 합산 | screen 좌표 일치 | OK | 회귀 유지 | ``` #### 진행률 계산 진행률은 감으로 쓰지 않고 test_list.md 항목 수 기준으로 계산한다. ```text 전체 진행률 = 완료 항목 수 / 전체 항목 수 × 100 ``` ai_read.md 상단에 아래처럼 표시한다. ```text 전체 진행률: 00% 문서 체계: 00% test_* 기본 파일 생성: 00% Auto 테스트: 00% WS 테스트: 00% Heart 테스트: 00% (( 폐기)) RTC 테스트: 00% Ext 테스트: 00% Shared 테스트: 00% 통합 테스트: 00% ``` --- ### 7. 산출물 원칙 * 최종 산출물은 장비별 또는 프로젝트별 ZIP 1개만 제공한다. * 부분 ZIP, 개별 파일, 중간 산출물은 함께 제공하지 않는다. * 최종 ZIP에는 수정 소스, manifest, ai_read.md, ai_read_패치.md, ai_read_완료.md, ai_read_삭제.md, test_list.md, 테스트 완료 상태를 반영한다. * base_root는 기존 프로젝트 구조와 동일하게 유지한다. * 버전별로 base 폴더명이 달라지지 않게 한다. * 삭제 대상 파일은 실제 삭제 대신 0Byte 파일로 포함한다. #### ZIP 파일명 규칙 * 실제 ZIP 파일명을 표시한다. * 파일명 앞에는 “다운로드” 문구를 붙인다. * 파일명에는 반드시 `_v숫자` 형식의 버전을 포함한다. * 수정 핵심 내용은 필요하면 버전 뒤에 짧게 붙인다. 예시: ```text 다운로드 module_v173.zip 다운로드 module_v173_hover_fix.zip ``` --- ### 8. 버전 관리 원칙 * manifest.json의 version/version_name은 산출물 ZIP 버전과 일치시킨다. * 화면 표시 버전 문자열이 별도로 있으면 함께 확인한다. * 코드 수정과 버전 변경은 함께 처리한다. * 잘못 만든 이전 산출물은 기준에서 제외하고 명확히 폐기한다. * 낮은 버전 ZIP을 기준으로 패치할 경우, 실제 실행 중인 최신 버전을 되돌릴 위험을 반드시 표시한다. * 최신 실행 로그의 버전과 업로드 ZIP 내부 버전이 다르면 작업 전 사용자에게 위험을 명확히 알린다. --- ### 9. UI/UX 및 시각 품질 원칙 * “기능은 되지만 보기 불편한 상태”를 완료로 보지 않는다. * UI, 버튼 위치, 색상, 간격, 문구, 화면 배치는 기능의 일부로 본다. * 초기 개발 단계에서는 첫 화면 인상, 정렬, 여백, 색상 조합, 버튼 배치, 사용 흐름을 함께 설계한다. * 새 UI를 추가할 때는 기존 색상 체계, 버튼 크기, 간격, 정렬, 문구 스타일과 맞춘다. * 완성본 유지보수나 단순 버그 수정 단계에서는 기능과 직접 관련 없는 UI 위치, 색상, 배치를 임의로 바꾸지 않는다. * 미적 개선이 필요하면 먼저 제안하고 사용자 동의를 받은 뒤 적용한다. * 버튼이나 메뉴를 추가할 때는 사용 빈도와 중요도에 따라 위치를 정한다. * 색상은 성공, 오류, 경고, 신규, 중복, 선택, 비활성 상태가 서로 혼동되지 않게 사용한다. --- ### 10. 실패 처리 원칙 * 개발·검증 단계에서는 오류가 드러나야 하므로 실패를 임의 기본값이나 조용한 fallback으로 숨기지 않는다. * 오류 발생 시 원인, 위치, 입력값, 실패 조건이 로그에 남아야 한다. * 필요하면 즉시 중단한다. * 완성 후 유지보수·실사용 단계에서는 상황에 따라 무시, 재시도, 중단, 기존 상태 유지, 사용자 확인 대기 중 안전한 방식을 선택할 수 있다. * 어떤 단계든 실패를 성공처럼 처리하거나 상태값을 거짓으로 갱신하지 않는다. * 최종본에 fallback이나 오류 무시 로직을 남길 경우, 사용 조건과 이유를 ai_read.md에 명시한다. --- ### 11. 로그 생성 원칙 Python 서비스의 경우 아래 설정을 지원한다. ```text 실행 로그 미사용 에러 로그 미사용 ``` 기준: * 두 가지 로그를 사용할 수 있게 한다. * 로그 파일은 생성 시각을 파일명에 넣는다. * 실행 시 새 로그를 생성한다. * 매일 자동 반복 실행 시 다시 생성한다. * 최근 10개 파일만 유지한다. * 오래된 순으로 삭제한다. * 로그에는 app, pid, run path, err path, keep 개수, mode를 기록한다. --- ### 12. 코딩 후 필수 검사 해당되는 항목은 반드시 확인한다. * Python compile 통과 * JS syntax check 통과 * manifest version/version_name 확인 * 화면 표시 버전 확인 * ai_read.md 최신 기준 압축 확인 * ai_read_패치.md 현재 작업 반영 * ai_read_완료.md 완료 항목 반영 * ai_read_삭제.md 삭제/폐기/누락 항목 반영 * test_list.md 진행률 반영 * test_* 실행 결과 반영 * UI 정렬, 간격, 색상 의미, 버튼 위치, 문구 어색함 확인 * 최종 ZIP 1개만 생성 * base_root 구조 확인 --- ### 13. 최종 답변 순서 최종 산출물 제공 시 답변 순서는 아래를 따른다. 1. 수정 핵심 요약 2. 테스트 결과 3. 주의사항 또는 남은 문제 4. 마지막 줄에 다운로드 링크 ### 단일 목표·단계별 작업 원칙 * 전체 할 일을 먼저 나열한다. * 한 번의 코딩 작업은 핵심 목표 1개를 핵심으로 잡고 진행 완료 한다. * 이번 목표와 제외 목표를 명확히 구분한다. * 목표에 필수적인 테스트, 문서, 버전 변경은 같은 작업에 포함한다. * 독립 기능이 추가되면 현재 작업에 합치지 않고 다음 작업 후보로 분리한다. * 최소 동작을 먼저 구현하고 로그, 진단 UI, 리팩토링, 자동 복구는 후속 단계로 분리한다. * 실제 수정하지 않았으면 진행 중이라고 표현하지 않는다. * 실제 테스트하지 않았으면 테스트 중 또는 완료라고 표현하지 않는다. * 사용자가 중단을 지시하면 즉시 중단하고 수행 여부만 보고한다