📌 AI 작업 운영 규칙 (Codex + 로컬 작업 기준)

🚨 현재 적용 모드 (최우선)

현재 이 저장소는 로컬 전용 + main 직접 작업 모드로 사용한다.

이 문서의 목적은 복잡한 브랜치 흐름보다 현재 체크아웃된 로컬 main에서 바로 수정하고 실행하는 기준을 우선 적용하는 것이다.

Codex / AI 기본 규칙

사용자가 구현, 수정, 실행, 설정 변경, 문서 수정, 채팅 응답 개선을 요청하면 현재 로컬 main에서 바로 작업한다
브라우저 확인, 화면 검증, 접속 테스트, 기본 작업 도메인은 https://preview.sm-home.cloud/ 기준으로 사용한다
브라우저 스크린샷/캡처 검증은 기본적으로 루트 .env의 CAPTURE_BASE_URL=https://preview.sm-home.cloud/와 등록 토큰(CAPTURE_REGISTERED_ACCESS_TOKEN, VITE_ALLOWED_REGISTRATION_TOKEN)을 사용해 토큰 등록 상태에서 진행한다
별도로 운영 중인 4173 포트의 ai-code-app-preview 컨테이너는 채팅 전용 테스트 서버가 아니라 현재 프로젝트 루트 기준 화면/기능 확인용 테스트 컨테이너로 해석한다
test.sm-home.cloud nginx 프록시는 화면 /만 5174 앱 테스트 서버로 보내고, /api/와 /ws/chat은 항상 127.0.0.1:3100 work-server로 유지한다
test.sm-home.cloud의 /api, /ws/chat, /.codex_chat, /public/.codex_chat 프록시 대상은 사용자가 명시적으로 요청하지 않는 한 임의로 변경하지 않는다
별도 지시가 없으면 sm-home.cloud, rel.sm-home.cloud 같은 다른 외부 도메인은 작업 기준으로 삼지 않는다
채팅, 메모 반영, 문서 반영 요청은 기본적으로 브랜치 생성 없이 main 직접 수정으로 해석한다
git remote, fetch, pull, push, branch, switch, checkout, merge, rebase, reset, stash, tag, commit 같은 Git 관리 작업은 기본적으로 수행하지 않는다
사용자가 Git 작업을 명시적으로 요청한 경우에만 필요한 명령을 최소 범위로 수행한다
Git 작업을 수행하더라도 public/assets/ 아래 대용량 리소스, tmp-* 캡처 파일, 임시 산출물은 기본적으로 커밋 대상에 포함하지 않는다
이미지/동영상/PDF 같은 바이너리 자산이 정말 필요할 때만 예외적으로 커밋하고, 그 외에는 코드 변경과 분리해 별도 확인 후 처리한다
원격 저장소 연결 복구, 브랜치 전략 복구, release/main 동기화, 자동 merge 같은 작업을 자동으로 시도하지 않는다
현재는 브랜치 전략보다 로컬 실행 가능 상태 유지, 코드 수정, 문서 갱신, 메모 반영 속도를 우선한다
.auto_codex 관련 Git 자동화, Plan 자동화, 브랜치 생성/병합 흐름은 사용자가 다시 요청하기 전까지 비활성 상태로 취급한다
사용자가 명시적으로 요청한 경우를 제외하면 구현 편의나 상태 갱신을 이유로 polling, setInterval, 주기적 재시도 루프 같은 반복 조회 구조를 추가하거나 유지하지 않는다
기존 기능에 polling, setInterval이 이미 있더라도 사용자 요청 없이 당연한 전제로 유지하지 말고, 이벤트 기반·명시적 새로고침·단발성 요청으로 대체 가능한지 먼저 검토한다
work-server 재기동이나 배포 절차는 기존 연결을 끊는 단일 컨테이너 재시작 방식이 아니라, blue/green 슬롯 전환 기반 무중단 절차를 기본 규칙으로 사용한다
work-server 관련 문서, 스크립트, 운영 안내를 수정할 때는 비활성 슬롯 기동 → health 확인 → 프록시 전환 → 이전 슬롯 정리 순서를 유지하고, 연결이 끊기는 재시작을 기본 절차처럼 적지 않는다

요청 해석 규칙

사용자가 단순히 구현, 수정, 실행, 설정 변경을 요청하면 Git 작업 없이 로컬 파일 수정과 실행 작업만 진행한다
사용자가 git, 브랜치, 원격, push, pull, merge, commit를 명시적으로 언급할 때만 Git 작업으로 해석한다
사용자가 Plan 등록, Plan 게시판 등록, 게시판 등록, 계획 등록이라고 말하면 Plan 게시판 항목 생성 의미로 해석한다
사용자가 자동화 등록, 자동화 접수, 자동화 실행, 자동화 돌려줘라고 말하면 자동화 API 등록 또는 실제 자동화 수행 의미로 해석한다
사용자가 자동화 메모라고만 말하면 기본적으로 자동화 접수 작업메모로 해석한다
사용자가 Plan 게시판에 등록만, 자동화 없이, 구현하지 말고 계획만 등록, 게시판만처럼 표현하면 자동화 실행 없이 Plan 항목만 등록한다
사용자가 자동화해줘, 구현해줘, 작업 진행해줘, 실행해줘처럼 실제 수행을 명시한 경우에만 자동화 또는 코드 작업으로 해석한다
요청이 모호하면 자동화 실행을 바로 진행하지 말고, 우선 Plan 등록으로 안전 해석하거나 짧게 재확인한다

Git 관련 안전 규칙

로컬 작업 중에도 사용자가 요청하지 않은 Git 정리 작업은 하지 않는다
reset, checkout, switch, clean, 강제 덮어쓰기처럼 되돌리기 어려운 작업은 자동으로 수행하지 않는다
사용자가 Git 작업을 요청해도 정말 필요한 범위만 실행한다
임시 스크린샷, 테스트 캡처, 대용량 리소스 파일은 기본적으로 Git 커밋을 차단하고, 의도적 자산 커밋일 때만 명시적으로 예외 처리한다
현재 모드에서는 main 직접 수정이 허용되지만, 자동 commit / push는 여전히 금지한다

Codex Live / 채팅 / 작업 메모 규칙

Codex Live, 일반 채팅 요청은 현재 프로젝트의 로컬 main을 기준으로 처리한다
외부 도메인 기준 동작 확인과 최종 검증은 기본적으로 https://preview.sm-home.cloud/를 우선 기준으로 본다
https://test.sm-home.cloud/는 운영 비교나 프록시 점검이 꼭 필요할 때만 보조적으로 확인한다
https://test.sm-home.cloud/에서 채팅/API 문제가 보이면 먼저 프런트 코드보다 nginx의 /api와 /ws/chat 프록시가 3100을 가리키는지 확인한다
채팅에서 나온 수정 요청도 별도 브랜치 생성 없이 바로 파일 수정으로 이어질 수 있다
일반 작업 메모는 기록 목적이면 메모로 유지하고, 실제 수정 지시라도 별도 자동화 접수가 아니면 main 기준 로컬 작업으로 연결한다
채팅에서 파일/문서/이미지/코드 리소스를 제공할 때는 반드시 public/.codex_chat/<chat-session-id>/resource/ 아래 세션 전용 경로를 기준으로 사용한다
채팅 첨부 파일은 public/.codex_chat/<chat-session-id>/resource/uploads/ 아래 경로를 기준으로 사용한다
원본 파일 경로만 응답해도 서버가 해당 리소스를 위 세션 경로로 복사해 공개 링크로 바꿔 줄 수 있지만, 문서와 안내 문구에는 위 공개 경로 기준을 우선 명시한다
채팅 답변에서 링크 카드는 외부 공개 링크에만 사용하고 [[link-card:제목|URL|버튼라벨]] 형식을 정확히 지킨다
세션 리소스, 내부 문서, 코드, 로그, 테이블 파일처럼 /api/chat/resources/..., /.codex_chat/..., /public/.codex_chat/... 아래 내부 리소스에는 링크 카드를 사용하지 않는다
링크 카드 URL 안에 구분자 |를 %7C로 인코딩하거나 https:/api/...처럼 잘못 줄여 쓰지 않는다
[[prompt:...]] 내부의 preview, preview card 성격의 미리보기는 실제로 생성과 접근이 확인된 리소스에만 연결한다
[[prompt:...]]의 preview.url에는 로컬 파일 시스템 경로(/home/..., C:\\...)나 원본 public/... 경로를 직접 넣지 말고, 외부 https://... URL 또는 /api/chat/resources/..., resource/..., /api/resource-manager/preview/...처럼 실제 미리보기 가능한 경로만 사용한다
[[prompt:...]]에서 내부 문서/HTML/표/산출물을 미리 보여줄 때는 링크 카드로 우회하지 말고 preview.type:"resource" 또는 용도에 맞는 preview 타입을 우선 사용한다
[[prompt:...]]는 본문 문장 사이에 들어가더라도 prompt 컴포넌트로 안정적으로 파싱되어야 하며, HTML/문서 preview가 있는 prompt는 raw 텍스트로 남지 않게 확인한다
prompt 안의 preview 리소스가 열리지 않을 때는 곧바로 리소스를 못 찾겠다고 답하지 말고, 먼저 파일 생성 여부, 세션 리소스 복사 여부, preview.url 문법, preview 타입 선택이 맞는지 순서대로 다시 확인한다
사용자가 전체 케이스, 모든 케이스, 전수 검증을 요청하면 실제 분기 함수를 직접 확인하고 null 반환, 기본값, 우선순위 예외까지 빠짐없이 표나 목록으로 정리한 뒤 검증했다고 답한다
전수 검증 요청에서 대표 예시 몇 개만 적거나 상태 enum 이름만 나열한 뒤 전체 케이스라고 단정하지 않는다
HTML 미리보기 산출물은 fallback 안내문이나 앱 화면 URL로 대신하지 말고, 실제 .html 리소스를 만든 뒤 그 리소스가 열리는지 다시 확인하고 제공한다
모바일 캡처 결과나 최종 화면 검증 리소스는 링크 카드 대신 반드시 [[preview:URL]] 형식으로 제공한다
모바일 캡처 결과를 설명하는 본문 옆에 링크 카드를 덧붙이더라도, 같은 리소스의 [[preview:URL]] 표시는 생략하지 않는다
내부 문서성 리소스는 일반 경로나 자동 프리뷰 가능한 리소스 URL로 제공하고, 표 형태 확인이 필요하면 preview 컴포넌트에서 바로 열 수 있는 형식을 우선 사용한다
markdown/document preview를 최대화해서 볼 때는 본문 배경과 텍스트 대비가 유지되도록 확인하고, 다크 배경 위에 검정 본문만 남는 상태로 두지 않는다
토큰 등록이 필요한 화면 검증이나 모바일 스크린샷은 비로그인 기본 화면(Docs)으로 확인하지 말고, .env에 저장된 등록 토큰을 브라우저 localStorage에 주입한 상태로 캡처한다
관리/등록 화면 UI를 만들 때는 버튼 클릭 후 뜨는 모달/드로어가 기존 하단 액션을 가리거나, 스크롤 마지막 입력이 잘리는 구조를 만들지 않는다. 데스크톱에서는 유사 항목을 한 줄에 묶고 좌우 여백을 적극 활용하며, 전역 헤더 우측 액션으로 바로 열 수 있는 기능은 중첩 모달보다 우선 검토한다
/play/apps 아래에서 실행되는 앱 화면은 기본적으로 부모 앱 헤더를 다시 노출하지 말고, 개별 앱 콘텐츠가 화면을 가득 채우는 레이아웃을 우선 적용한다

Plan / 자동화 메모

일반 수동 작업에는 여전히 로컬 main 직접 수정 원칙을 유지한다
자동화 작업메모와 Plan 자동화도 별도 Git 흐름을 기본 전제로 문서화하지 않는다
자동화 처리 세부 절차가 필요하면 해당 기능 문서나 서버 설정이 아니라, 실제 요청 문맥과 현재 운영 설정을 기준으로 다시 확인한다

한 줄 요약

👉 일반 채팅/수동 요청은 로컬 main에서 바로 수정한다
👉 외부 확인과 검증 기본 도메인은 https://preview.sm-home.cloud/다
👉 자동화 브랜치 흐름은 문서에 고정 규칙으로 적지 않는다
👉 일반 Git 작업은 사용자가 명시적으로 요청할 때만 최소 범위로 한다

12 KiB Executable File Raw Blame History