9단계: 목표 아키텍처와 현재 프로젝트 비교하기

핵심 요약

8단계에서 Login, Admin Dashboard, Text Tool과 통합 실행 구조를 만들었습니다. 이번 단계에서는 코드를 대규모로 바꾸지 않고 최종 구성과의 차이를 기록합니다.

현재 상태 확인
→ 유지할 기능 고정
→ 부족한 구성 식별
→ 적용 순서 결정
→ 회귀 검사 기준 고정

이 내용은 기존 시스템을 함부로 바꾸지 않고, 안전하게 개선하기 위한 작업 순서를 말합니다.

1. 현재 상태 확인

지금 프로그램이 어떻게 구성되어 있고 무엇이 정상 작동하는지 먼저 확인합니다.

2. 유지할 기능 고정

로그인, Dashboard처럼 현재 잘 작동하는 기능 중 반드시 그대로 유지해야 할 것을 정합니다.

3. 부족한 구성 식별

Redis 세션, Nginx, HTTPS 등 현재 빠져 있거나 개선해야 할 부분을 찾습니다.

4. 적용 순서 결정

무엇부터 수정할지 순서를 정합니다. 예: Docker Compose 통합 → Redis 세션 → Nginx → HTTPS

5. 회귀 검사 기준 고정

새로운 기능을 추가한 뒤 원래 잘 되던 기능이 망가지지 않았는지 다시 검사할 기준을 정합니다.

이번 단계의 Vibe Coding 작업 지시서

학습용 간단한 지시 설명서

08단계 통합 구성을 변경하지 말고 최종 목표와의 Architecture Gap 보고서를 작성해 줘.
Login, Session, Dashboard와 Text Tool을 변경 금지 Baseline으로 고정해 줘.
현재 구조를 최종 Stack과 권장 프로젝트 구조에 비교하고 각 Gap의 영향, 위험, 순서와 회귀 검사를 정리해 줘.
파일 삭제, Package 변경과 대규모 Refactor는 하지 마.
현재 8080 WebUI Gate 결과와 10~18 실행 순서를 보고해 줘.

정식 작업 지시서

다음 코드 블록 전체가 09단계 구현의 유일한 정식 작업 지시서입니다. 내용을 줄이거나 별도의 상세 프롬프트로 복제하지 않고 docs/work-orders/09-architecture-gap-analysis.md에 저장합니다.

# 09단계 정식 작업 지시서

## 단계별 상세 지시
루트 AGENTS.md, 요구사항과 docs/work-orders/09-architecture-gap-analysis.md를 먼저 읽어 줘.
08단계의 전체 Compose 실행, 8080 WebUI 통합 검증, MySQL 데이터 보존, Redis Session 유지와 공개 Port 검사 결과를 확인하고 현재 상태를 Baseline으로 기록한다.
5173 개발 환경은 08단계에서 다시 실행했는지, 07단계 기준선을 재사용했는지 또는 구성만 보존했는지 구분한다. 실행하지 않은 5173 검사를 새로 통과한 것으로 기록하지 않는다.

이번 단계는 분석과 문서화만 수행한다.
Gap 보고서는 docs/requirements/architecture-gap-analysis.md에 작성한다.
허용 범위는 docs/requirements/, docs/work-orders/와 docs/development-guides/의 관련 문서다.
Application Source, Package, Compose와 실행 설정을 변경하지 않는다.

현재 파일 구조와 실행 구성을 01단계의 최종 Stack·권장 프로젝트 구조와 비교한다.
Login, Session, Admin 권한, Dashboard, Sidebar, Text Tool, MySQL 데이터, Redis Session과 Nginx 8080 단일 진입점을 보존 항목으로 고정한다.
각 Gap에는 현재 상태와 근거 파일, 목표 상태와 요구사항 근거, 직접·간접 영향 파일, Backend와 Frontend Contract 영향, 선행·후속 단계, 데이터·보안 위험, 적용 순서, 실패·중단 기준, 실제 되돌리기 절차, 자동 검사 명령, 검사 환경과 Test 데이터 격리 방법, 성공·실패 판정 기준, 사용자 WebUI 확인 항목과 세부 내용의 확정·미확정 상태를 기록한다.
10 Backend 구조, 11 Zod, 12 Prisma, 13 Redis, 14 Compose, 15 Nginx, 16 보안, 17 자동 Test, 18 운영 점검은 요구사항에 정의된 상위 순서만 확인한다. 아직 각 단계의 정식 작업 지시서가 없으면 세부 허용 범위, 영향 파일과 의존성이 확정되었다고 기록하지 않고 해당 단계의 정식 작업 지시서를 작성할 때 확정한다고 명시한다.

실패·중단 기준과 실제 되돌리기 절차를 구분한다. `중단한다`, `사용하지 않는다`, `완료로 기록하지 않는다`만으로 되돌리기 절차를 대신하지 않는다. 실제 복구 절차에는 복귀할 파일·이미지·설정, 데이터와 Session 확인 및 사용자 승인 경계를 기록한다.
Schema 또는 Migration 변경 단계에는 변경 전 Backup 생성, Backup 식별 방법, 격리된 Restore 검증, 변경 전후 데이터 확인, 적용 후 실패 시 복구 대상과 사용자 승인 경계를 포함한다. 검증된 Backup·Restore 절차가 없으면 임의의 명령을 만들지 않고 해당 단계 시작 전에 검증 절차를 먼저 확정한다고 기록한다.
공통 API 응답 형식 변경 단계에는 변경할 필드, 보존할 기존 API Contract와 HTTP 상태 코드, Health Endpoint 포함 여부, 영향을 받는 Backend·Frontend 파일과 Test를 기록한다.
회귀 검사에는 실행 명령, 실행 위치, 환경 전제, 격리된 Test DB·Redis 사용 여부와 성공 기준을 기록한다. Mock 또는 MemoryStore 검사와 실제 MySQL·Redis 통합 검사를 구분하고 단계별 Frontend typecheck, lint, test와 build 적용 여부를 명시한다.
보안 Gap에는 존재하는 계정과 존재하지 않는 계정의 로그인 응답 시간 차이에 따른 Timing Enumeration 위험을 포함한다. Redis Session 설명에서는 Backend만 재시작하는 경우와 Redis 컨테이너 재시작·재생성 결과를 구분하고, 현재 Redis에 Volume과 Persistence가 없으면 Redis 재생성 시 Session이 사라진다고 명시한다.
현재 생성된 파일이 최상위 책임 경계를 지키는 것과 목표 구조가 모두 구현된 것을 구분한다. 미구현 폴더나 구성이 있으면 전체 구조가 일치한다고 기록하지 않는다.

삭제, 대규모 Refactor, Migration 실행, Package 설치와 기능 추가를 하지 않는다.
확인하지 못한 상태를 구현 완료로 표시하지 않는다.

변경 전·후 8080 전체 Gate를 실행하여 Baseline이 유지됨을 확인한다.
분석 결과는 Gap 보고서에 정리하고 Gate 결과는 완료 보고에 통과, 실패와 미수행으로 구분한다. 검증 기록 개발 가이드 갱신은 사용자가 확인을 마친 뒤 별도 Prompt로 수행한다.
Baseline에 오류가 있거나 요구사항에 정의된 10~18단계의 상위 순서를 확인하지 못하면 10단계로 진행하지 않는다.

## 완료 조건

1. docs/requirements/architecture-gap-analysis.md가 생성되고 현재 상태 판정마다 실제 파일 근거가 있다.
2. 10~18단계의 상위 순서와 각 단계 작업 지시서에서 확정할 세부 범위가 구분되어 있다.
3. 영향 파일에 Backend와 Frontend Contract 영향이 포함되어 있다.
4. 실패·중단 기준과 실제 되돌리기 절차가 구분되어 있다.
5. 데이터 변경 단계에 Backup·Restore 검증 요구사항과 사용자 승인 경계가 있다.
6. 회귀 검사에 명령, 환경, Test 데이터 격리 방법과 성공 기준이 있다.
7. 8080 WebUI 회귀 검사를 실제로 통과했다.
8. 실제 수행 결과, 기존 기록 재사용과 미수행이 구분되어 있다.
9. 읽기 전용 기술 검토에서 수정 필요 항목이 남아 있지 않다.

위 조건 중 하나라도 충족하지 않으면 09단계를 완료로 기록하거나 10단계 진행 가능으로 보고하지 않는다.

## 완료 보고 형식

- 생성하거나 변경한 파일
- 실행한 명령과 실제 결과
- 통과, 실패와 미수행 검증
- 분석 범위별 확인 결과와 문서 변경 이유
- 남은 제한, 위험과 다음 단계 진행 가능 여부

정식 작업 지시서 저장과 실행 순서

다음 순서는 Windows 관리 PC의 VS Code에서 Remote SSH로 개발 서버에 연결한 상태를 기준으로 합니다. 앞 단계가 실패했거나 기존 변경과 충돌하면 다음 번호로 넘어가지 않습니다.

1. 프로젝트와 이전 단계 상태 확인

VS Code의 원격 터미널에서 프로젝트 루트로 이동하고 현재 상태를 확인합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
pwd
git status --short

AI 코딩 에이전트에게 변경을 맡기기 전에 이전 단계의 완료 기록과 현재 사용자 변경을 구분합니다. 예상하지 못한 변경이 있으면 보존 방법을 먼저 결정합니다.

2. 정식 작업 지시서 저장

VS Code에서 docs/work-orders/09-architecture-gap-analysis.md를 만들고, 위 정식 작업 지시서 코드 블록의 내용을 빠짐없이 저장합니다. 간단한 지시서와 정식 작업 지시서를 서로 다른 실행 프롬프트로 보내지 않습니다.

mkdir -p docs/work-orders
touch docs/work-orders/09-architecture-gap-analysis.md

VS Code의 Explorer에서 docs/work-orders/09-architecture-gap-analysis.md를 선택해 열고, 위 정식 작업 지시서 코드 블록 전체를 복사해 붙여넣은 뒤 Ctrl+S로 저장합니다.

저장한 다음 VS Code 원격 터미널에서 파일 내용과 변경 사항을 확인합니다.

test -s docs/work-orders/09-architecture-gap-analysis.md
git diff -- docs/work-orders/09-architecture-gap-analysis.md

저장한 파일에 목표, 허용 범위, 제외 범위, 완료 조건, 검증과 중단 조건이 모두 포함되어 있는지 직접 확인합니다.

3. 작업 지시서 Git 기준점 기록

내용을 검토한 뒤 작업 지시서만 먼저 Commit하여 구현 기준을 고정합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
git status --short
git add docs/work-orders/09-architecture-gap-analysis.md
git diff --cached --name-only
git diff --cached --check
git commit -m "docs: add 09 step work order"

git diff --cached에서 예상하지 않은 파일이 보이면 커밋하지 않고 스테이징 범위를 바로잡습니다.

4. Codex CLI 실행과 공통 프롬프트 전달

프로젝트 루트에서 Codex CLI를 실행합니다.

codex -C /home/apple2ne1/projects/vibe-coding-platform

Codex CLI에 단계별 구현 조건을 다시 길게 복사하지 않고 다음 공통 프롬프트를 전달합니다. 선행 조건이나 기록이 맞지 않아도 사용자가 원인을 직접 판정하지 않습니다. Codex가 안전하게 해결할 수 있는 문제는 기존 작업을 보존하면서 바로잡고 다시 검사합니다.

루트 AGENTS.md, docs/requirements/admin-platform.md와
docs/work-orders/09-architecture-gap-analysis.md를 먼저 읽어 줘.

이 문서는 비전공자가 따라 하는 단계별 실습이야.
사용자에게 Git 상태, 문서 충돌이나 오류 원인을 직접 판정하게 하지 마.

먼저 다음 내용을 확인해 줘.

1. 현재 단계와 목표
2. Git 상태와 보존해야 할 기존 변경
3. 이전 단계 완료 여부와 문서 간 현재 단계 기록
4. 생성하거나 변경할 파일
5. 실행할 자동 검사와 사용자가 확인할 WebUI 또는 대체 검사
6. 위험, 충돌과 중단 조건

선행 조건이나 단계 기록이 맞지 않으면 보고만 하고 멈추지 말고 원인을 확인해 줘.
현재 코드와 확인된 검증 기록으로 이전 단계 완료를 확인할 수 있는데 README.md,
docs/requirements/admin-platform.md, docs/development-guides/local-development.md 또는
docs/development-guides/webui-gate.md의 단계 기록만 오래되었거나 서로 다르면,
요구사항과 기존 기록을 삭제하지 말고 실제 상태에 맞게 서로 일치시킨 뒤 다시 검사해 줘.

누락된 문서 생성, 잘못된 경로·파일명, 안전한 설정 수정처럼 현재 단계 범위에서 복구할 수 있는 문제는
기존 사용자 변경을 보존하면서 직접 복구하고 관련 검사를 다시 실행해 줘.
파일 삭제, 기존 변경 덮어쓰기, Git Reset, Secret 입력, sudo 권한이나 사용자의 실제 WebUI 확인처럼
사용자 결정이나 조작이 꼭 필요한 일은 임의로 진행하지 마.
그 경우에는 사용자가 해야 할 행동 한 가지만 쉬운 문장으로 설명하고, 복사할 명령이 있으면 코드 블록 하나로 제공한 뒤 결과를 기다려 줘.

선행 조건이 해결되면 별도의 재요청을 기다리지 말고 정식 작업 지시서의 허용 범위만 구현해 줘.
제외 범위와 다음 단계 기능은 추가하지 마.
실행하지 못한 검사는 통과로 기록하지 말고 필수 검사 실패를 완료로 판정하지 마.

Gap 보고서를 작성한 뒤 완료 보고 전에 실제 프로젝트와 다시 대조해 줘.

1. 현재 상태의 모든 판정에 실제 파일 근거가 있는지
2. 아직 없는 10~18단계 작업 지시서의 세부 범위를 확정했다고 쓰지 않았는지
3. 직접·간접 영향 파일과 Backend Contract 변경에 따른 Frontend 영향이 포함되었는지
4. 변경할 API 응답 필드와 보존할 기존 Contract가 구분되었는지
5. 실패·중단 기준과 실제 되돌리기 절차가 분리되었는지
6. 데이터 변경 단계에 Backup과 격리 Restore 검증 및 사용자 승인 경계가 있는지
7. 회귀 검사에 명령, 환경, Test 데이터 격리 방법과 성공 기준이 있는지
8. Mock 검사와 실제 MySQL·Redis 통합 검사가 구분되었는지
9. 단계별 Frontend typecheck, lint, test와 build 적용 여부가 있는지
10. Login Timing Enumeration 위험이 포함되었는지
11. Backend 재시작과 Redis 재생성의 Session 결과가 구분되었는지
12. 현재 구조와 미구현 목표 구조를 모순되게 설명하지 않았는지
13. 실행하지 않은 검사를 통과로 기록하지 않았는지

문제가 발견되면 완료 보고 전에 Gap 보고서를 허용 범위 안에서 수정하고 다시 검사해 줘.
확인할 근거가 없으면 추정하여 확정하지 말고 미확정 항목과 확정 시점을 기록해 줘.

자동 검사가 끝나면 사용자가 직접 확인해야 할 WebUI 또는 대체 검사만 번호가 있는 짧은 목록으로 안내해 줘.
검증 결과 기록, 스테이징과 커밋은 사용자가 실제 확인을 마친 뒤 별도 Prompt로 요청할 것이므로 지금 실행하지 마.

마지막에는 비전공자도 이해할 수 있게 다음 내용만 보고해 줘.

1. 자동으로 해결한 문제
2. 구현한 내용과 변경 파일
3. 통과·실패·미수행 검사
4. 사용자가 지금 확인할 항목
5. 다음 절차 진행 가능 여부

5. Codex의 자동 확인·복구 후 구현

위 프롬프트는 사전 확인에서 안전하게 해결할 수 있는 문제를 발견하면 Codex가 기존 작업을 보존하면서 직접 복구하고 다시 검사한 뒤 구현을 계속하도록 요청합니다. 사용자는 Git 상태, 문서 간 단계 충돌과 명령 오류를 직접 판정하지 않습니다.

Codex가 사용자 조작이 필요한 문제를 발견하면 한 번에 한 가지 행동만 안내합니다. 안내된 명령이나 WebUI 확인을 수행한 뒤 결과 전체를 같은 Codex CLI 대화에 붙여 넣습니다. Codex가 다음 절차 진행 가능이라고 보고하면 아래 구현 결과 확인으로 이동합니다. 진행 불가라고 보고하면 임의로 다음 단계로 넘어가지 않고, 마지막 보고 전체를 그대로 Codex에 다시 전달하여 해결을 계속 요청합니다.

구현 결과 WebUI 실행과 확인

09단계는 새 화면이나 기능을 구현하지 않고 현재 구조와 최종 목표의 차이를 분석합니다. 따라서 08단계의 8080 WebUI가 그대로 동작하는지 확인하는 회귀 검사와 Codex가 작성한 구조 차이 분석 보고서 확인을 함께 수행합니다. 5173 개발 환경은 별도로 실행하지 않습니다.

1. 전체 Compose 서비스 상태 확인

VS Code 원격 터미널에서 프로젝트 루트로 이동한 뒤 서비스 상태를 확인합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
docker compose ps

백엔드, MySQL, Redis와 Nginx가 모두 실행 또는 정상 상태이면 다음 단계로 이동해도 됩니다.

전체 Compose 환경이 다시 정상적으로 시작되는지도 확인하려면 서비스를 한 번 중지합니다. docker compose down은 이 Compose 프로젝트의 컨테이너와 네트워크를 제거합니다. -v 옵션을 사용하지 않으므로 MySQL의 명명된 볼륨은 삭제하지 않습니다. 현재 Redis에 별도의 볼륨이나 Persistence가 없다면 Redis 컨테이너가 제거될 때 기존 Session은 보존되지 않으므로 다시 로그인해야 합니다.

docker compose down

같은 터미널에서 전체 Compose 환경을 시작한 뒤 다시 확인합니다.

docker compose up -d
docker compose ps
docker compose logs --tail 100 backend mysql redis nginx

Nginx만 호스트의 8080 포트에 게시되고 백엔드, MySQL과 Redis에는 호스트 공개 포트가 없어야 합니다. 로그에 반복되는 연결 오류가 있거나 서비스가 정상 상태가 되지 않으면 WebUI 검사를 진행하지 않고 아래의 오류 전달 절차를 사용합니다.

2. 8080 로그인과 화면 기준선 확인

Windows 관리 PC의 웹 브라우저에서 다음 주소를 엽니다.

http://192.168.1.231:8080

로그인 화면이 나타나면 다음 공개 실습용 계정으로 로그인합니다. 이 값은 운영 환경에서 재사용할 수 없는 실습용 예시입니다.

이메일: admin@example.test
암호: vibe-admin-04-demo

로그인 후 다음 순서로 확인합니다.

1. Admin Dashboard가 열리고 Sidebar 메뉴가 표시되는지 확인합니다.

1. Text Tool을 열어 짧은 문장을 입력하고 실행 결과가 표시되는지 확인합니다.

1. 웹 브라우저의 새로고침 버튼을 눌러 로그인 상태와 현재 화면이 유지되는지 확인합니다.
2. 주소 표시줄에 http://192.168.1.231:8080/admin을 직접 입력해 관리자 화면이 열리는지 확인합니다.
3. 주소 표시줄에 http://192.168.1.231:8080/admin/text-tool을 직접 입력해 Text Tool 화면이 열리는지 확인합니다.
4. Logout을 실행한 뒤 위 두 관리자 주소 중 하나를 다시 열어 로그인 화면으로 이동하는지 확인합니다.

09단계에서는 화면 디자인이나 기능이 달라지면 안 됩니다. 위 항목이 08단계와 동일하게 동작하면 WebUI 기준선은 통과입니다.

3. 소스와 실행 설정의 변경 금지 기준 확인

VS Code 원격 터미널에서 Codex가 변경한 파일을 확인합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
git status --short
git diff --name-only

변경 파일은 정식 작업 지시서에서 허용한 문서와 구조 차이 분석 보고서 범위여야 합니다. backend/, frontend/, compose.yaml, Dockerfile, Nginx 설정이나 package.json이 표시되면 09단계의 변경 금지 범위를 벗어난 것이므로 완료로 판단하지 않습니다.

이 단계의 구조 차이 분석 보고서는 다음 파일입니다.

docs/requirements/architecture-gap-analysis.md

구조 차이 분석 보고서가 실제로 생성되었는지 확인하고 내용을 읽습니다.

test -s docs/requirements/architecture-gap-analysis.md
sed -n '1,240p' docs/requirements/architecture-gap-analysis.md

docs/development-guides/와 README.md는 구조 차이 분석 보고서가 아닙니다. 두 경로는 WebUI 검증 기록과 현재 통합 상태를 나중에 갱신하는 관련 문서입니다. 추적 중인 관련 문서에 변경이 있다면 다음 명령으로 내용을 읽기 전용으로 확인합니다.

git diff -- docs/requirements docs/work-orders docs/development-guides README.md

git status --short에서 ?? docs/requirements/architecture-gap-analysis.md로 표시되면 구조 차이 분석 보고서가 아직 Git이 추적하지 않는 새 파일이라는 뜻입니다. 새 파일은 git diff에 내용이 표시되지 않으므로 위의 sed 명령이나 VS Code의 Explorer로 직접 열어 확인합니다.

4. 구조 차이 분석 보고서 완료 기준 확인

이 작업의 목적은 본격적으로 10단계 이후 개발을 시작하기 전에, 현재 시스템 상태와 앞으로 할 작업을 정확히 정리해서 실수나 재작업을 줄이는 것입니다.

사용자와 Codex의 확인 역할을 다음과 같이 구분합니다.

사용자는 다음 항목만 직접 확인합니다.

1. docs/requirements/architecture-gap-analysis.md 파일이 실제로 열립니다.
2. 보고서에 현재 상태, 목표 상태와 10~18단계의 작업 순서가 구분되어 있습니다.
3. Codex의 설명에서 발견한 문제와 10단계 진행 가능 여부를 이해할 수 있습니다.
4. 앞에서 확인한 8080 WebUI가 08단계와 동일하게 동작합니다.

보고서 내용의 기술적 타당성은 다음 프롬프트로 Codex에 대조·수정·재검토를 한 번에 요청합니다. Codex는 실제 프로젝트를 읽기 전용으로 조사하고, 발견한 문제는 구조 차이 분석 보고서 안에서만 수정합니다.

docs/requirements/architecture-gap-analysis.md를 실제 Source, Package, Compose, Nginx, 요구사항과 작업 지시서에 대조해 줘.
실제 프로젝트 조사는 읽기 전용으로 수행하고, 발견한 문제는 docs/requirements/architecture-gap-analysis.md 안에서만 수정해 줘.
애플리케이션 Source, Package, Compose, Nginx와 실행 설정은 변경하지 마.
기존 사용자 변경과 확인된 사실을 보존하고 근거가 없는 내용은 확정하지 마.
스테이징과 커밋은 실행하지 마.

비전공자가 직접 기술적 타당성을 판정하지 않아도 되도록 다음 항목을 확인해 줘.

1. 현재 상태와 목표 상태가 실제 코드, 패키지, Compose와 문서에 맞는지 확인해 줘.
2. 10~18단계는 요구사항의 상위 순서와 각 단계 작업 지시서에서 확정할 세부 범위가 구분되어 있는지 확인해 줘.
3. 직접·간접 영향 파일과 Backend API Contract 변경에 따른 Frontend Source·Test 영향이 포함됐는지 확인해 줘.
4. API 오류 Contract를 Endpoint별 실제 상태 코드와 응답 형식에 맞게 기록해 줘. Logout의 Session 삭제 오류가 현재 범용 오류 처리기를 거쳐 400을 반환하는지 확인하고, 이를 보존할지 10단계에서 수정할지는 미확정으로 구분해 줘.
5. 데이터 위험과 보안 위험이 빠지거나 과장되지 않았는지 확인해 줘.
6. 12단계 Backup 요구사항에 접근 권한, 안전한 저장 위치, 암호화 판단, 보존·폐기 기준, 민감정보의 Log·완료 보고 출력 금지, Checksum과 격리 Restore 검증이 포함됐는지 확인해 줘. 실제 명령은 12단계 작업 지시서에서 확정한다고 구분해 줘.
7. 실패·중단 기준과 실제 되돌리기 절차를 구분해 줘. 정확한 Commit, Image Tag, 변경 파일과 복구 명령이 아직 없으면 실행 가능한 절차라고 표현하지 말고 `되돌리기 요구사항` 또는 `되돌리기 초안`으로 기록해 줘.
8. 각 Gap에 사용자가 직접 확인할 WebUI 항목을 명시해 줘. 화면 변경이 없는 단계는 Codex가 실행할 자동·통합 검사와 사용자가 확인할 최소 결과를 구분해 줘.
9. 회귀 검사에 실행 명령, 실행 위치, 환경 전제, Test 데이터 격리 방법과 성공 기준이 있는지 확인해 줘. Mock·MemoryStore 검사와 실제 MySQL·Redis 통합 검사를 구분하고 단계별 Frontend typecheck, lint, test와 build 적용 여부를 기록해 줘.
10. 14단계 개발용 MySQL·Redis 접근은 Loopback 주소 또는 안전한 SSH Tunnel로 한정하고 외부 Interface 게시 금지를 명시해 줘. 실제 방식은 14단계 작업 지시서에서 확정한다고 기록해 줘.
11. 15단계에 Certificate Private Key의 Git 포함, 과도한 파일 권한, Docker Image 포함, Log·완료 보고 출력과 갱신 과정 노출 위험이 포함됐는지 확인해 줘.
12. Login Timing Enumeration 위험이 포함됐는지 확인해 줘.
13. Redis URL이 없을 때 session-store.ts가 undefined를 반환하고 express-session이 기본 MemoryStore를 사용한다는 실제 책임 주체를 정확히 기록해 줘.
14. Backend만 재시작하는 경우와 Redis 컨테이너 재시작·재생성의 Session 결과가 구분됐는지 확인해 줘.
15. 17단계에 npm ci, package-lock.json 변경 검토, latest 범위의 대규모 Upgrade 위험과 의존성 취약점 검사 범위가 포함됐는지 확인해 줘.
16. 현재 파일이 최상위 책임 경계를 지키는 것과 목표 구조가 모두 구현된 것을 혼동하지 않았는지 확인해 줘.
17. 아직 구현하지 않은 목표나 실행하지 않은 검사를 완료 또는 통과로 기록하지 않았는지 확인해 줘.
18. 서로 모순되거나 비전공자가 오해할 표현이 있는지 확인해 줘.

문제를 발견하면 위 허용 범위 안에서 Gap 보고서를 수정하고 실제 프로젝트와 다시 대조해 줘.
수정 후에도 근거가 부족한 항목은 추정하지 말고 미확정 내용과 확정할 단계를 기록해 줘.

마지막에는 다음 형식으로 쉽게 보고해 줘.

1. 확인한 보고서 경로
2. 수정한 파일
3. 발견한 문제와 수정 내용 및 실제 근거
4. 문제가 없는 항목
5. 여전히 미확정인 항목과 확정할 단계
6. 남은 모순·누락·과장된 확정 또는 수정 필요 항목
7. 09단계 Gap 보고서 기술 검토 통과 여부
8. 사용자가 확인하거나 기록해야 할 WebUI 항목
9. 09단계 완료 조건 충족 여부
10. 10단계 진행 가능 여부

Codex는 다음 기준을 모두 확인해야 합니다.

1. 현재 상태와 목표 상태가 구분되어 있습니다.
2. 각 Gap에 영향 파일과 의존 단계가 기록되어 있습니다.
3. 데이터 위험과 보안 위험이 기록되어 있습니다.
4. 적용 순서, 회귀 검사, 실패·중단 기준과 실제 되돌리기 절차가 구분되어 있습니다.
5. 10단계 백엔드 구조부터 18단계 운영 점검까지 요구사항에 정의된 상위 순서가 정리되고 세부 범위는 미확정으로 구분되어 있습니다.
6. 아직 구현하지 않은 목표가 완료 또는 통과로 기록되지 않았습니다.

Codex가 기술적 문제 없음과 10단계 진행 가능을 보고하고 WebUI 기준선도 통과한 경우에만 다음 Codex에 검증 결과 기록 요청 절로 이동합니다. 문제가 발견되면 사용자가 직접 수정하지 않고 Codex의 보고 내용을 바탕으로 수정 요청을 먼저 진행합니다. 화면에 회귀가 있거나 요구사항에 정의된 상위 순서를 확인하지 못했다면 10단계로 진행하지 않습니다.

다음은 개념을 설명하기 위한 가상 예시이며, 09단계 현재 프로젝트의 실제 상태를 나타내지 않습니다. 현재 프로젝트에는 Redis 세션 저장소와 Nginx 단일 진입점이 이미 적용되어 있습니다.

가상의 프로젝트에서 현재는 MemoryStore를 사용하고 목표는 Redis 세션 저장소를 사용하는 것이라면 다음과 같이 정리할 수 있습니다.

현재: MemoryStore 목표: Redis 세션 저장소 구조 차이: Redis 기반 세션 저장소가 아직 적용되지 않음

또 다른 가상의 프로젝트에서 현재 React를 개발 서버로 실행하고 있지만 목표가 Nginx에서 배포용 빌드를 제공하는 것이라면 다음과 같이 정리할 수 있습니다.

현재: React 개발 서버 목표: Nginx가 React 배포용 빌드 제공 구조 차이: 배포용 빌드와 Nginx 서비스 구성이 아직 없음

즉, 구조 차이 분석 보고서는 “지금 무엇이 부족하고, 목표에 도달하려면 무엇을 더 해야 하는지 정리한 보고서”입니다.

아주 쉽게 말하면:

현재 상태와 완성된 상태 사이에서 빠진 것을 찾는 문서입니다.

5. 오류나 범위 밖 변경을 Codex에 전달

WebUI가 열리지 않거나 기능이 달라졌거나 허용 범위 밖 파일이 변경되었다면 오류 화면, docker compose ps, 관련 로그와 git status --short 결과를 같은 Codex CLI 대화에 전달합니다.

09단계 WebUI와 Gap 보고서 확인 중 문제가 발생했어.
아래에 docker compose ps, 관련 로그, git status --short 결과와 실제 화면 증상을 전달할게.

08단계의 8080 WebUI 기준선과 비교하여 로그인, Admin Dashboard, Text Tool, 새로고침과 로그아웃 중 어디에서 회귀가 발생했는지 확인해 줘.
애플리케이션 소스, 패키지, Compose와 실행 설정에 09단계 범위 밖 변경이 있는지도 확인해 줘.
기존 사용자 변경을 보존하고 원인, 허용 범위 안의 최소 수정, 재검사 결과를 구분해서 보고해 줘.
실행하지 않은 검사는 통과로 기록하지 말고, WebUI 기준선이나 Gap 적용 순서가 확인되지 않으면 10단계 진행 가능으로 보고하지 마.
스테이징과 커밋은 실행하지 마.

6. Codex에 검증 결과 기록 요청

사용자가 위 절차의 WebUI와 구조 차이 분석 보고서 기술 검토를 마친 뒤에는 실행 명령, 결과와 파일별 기록 내용을 다시 정리하지 않습니다. 같은 Codex CLI 대화에 다음 프롬프트 하나를 전달하면 Codex가 앞선 대화, 구조 차이 분석 보고서, Git 변경과 기존 검증 기록에서 확인 가능한 결과를 찾아 관련 문서에 기록합니다. 웹 브라우저에서만 확인할 수 있는 결과가 대화에 없을 때만 Codex가 사용자에게 한 가지씩 묻습니다.

사용자가 위 절차에 따른 09단계 분석과 Gap 보고서 기술 검토·재검토를 모두 마쳤다.
사용자는 8080 WebUI에서 Login 성공, Admin Dashboard 표시, Sidebar 표시와 메뉴 이동,
Text Tool 입력·실행·결과 표시, 새로고침 뒤 Login 상태와 현재 화면 유지,
Logout 성공과 Logout 뒤 보호 경로 차단 또는 Login 화면 이동,
Desktop 화면의 Console 오류 없음, `/api/` Network 요청의 예상 상태 코드와 응답,
Keyboard만 사용한 이동·입력·실행·Logout, Mobile 화면의 주요 내용·메뉴·조작 요소를 모두 실제로 확인했고 모두 정상이라고 검증했다.
이 프롬프트에 적은 확인 결과를 사용자가 전달한 실제 8080 WebUI 검증 결과로 사용해 줘.
검토·검증 완료를 기록 작업 시작 승인으로 간주하고, 같은 결과를 다시 요구하지 말고 아래 근거를 대조하여 검증 결과 기록을 시작해 줘.

09단계 분석, WebUI 검사와 Gap 보고서 기술 검토 결과를 관련 기록 문서에 반영해 줘.
사용자에게 실행 명령, 결과와 기록할 문장을 다시 정리하게 하지 말고 다음 근거를 직접 찾아 서로 대조해 줘.

1. 같은 Codex CLI 대화에서 실행한 명령과 실제 출력
2. 사용자가 같은 대화에 전달한 8080 WebUI 확인 결과와 오류
3. docs/requirements/architecture-gap-analysis.md의 현재 내용과 마지막 기술 검토 결과
4. docs/work-orders/09-architecture-gap-analysis.md의 완료 조건
5. git status와 git diff에 표시되는 실제 변경
6. README.md, docs/requirements/admin-platform.md,
   docs/development-guides/local-development.md와
   docs/development-guides/webui-gate.md의 기존 단계 기록

완료를 먼저 가정하지 말고 위 근거로 완료 조건 충족 여부를 판정해 줘.
사용자가 전달한 8080 WebUI 결과는 다시 실행하거나 다시 요구하지 마.
기록에 필요한 Backend·Frontend 검사, Production Build, `docker compose config`, 실행 중 서비스 Health와 공개 포트 확인의 실제 출력이 같은 대화나 기존 기록에 없으면 미완료로 보고하고 멈추지 마.
프로젝트의 `package.json`, Compose 파일과 작업 지시서에서 기존 검증 명령을 확인한 뒤, 자동으로 실행할 수 있는 해당 검사를 직접 실행하고 실제 출력과 성공·실패를 기록해 줘.
새 검증 명령을 임의로 만들거나 Package·Source·Compose·Nginx 설정을 변경하지 마. 실행에 Secret, `sudo`, 데이터 삭제·초기화 또는 사용자 조작이 필요할 때만 해당 검사를 미수행으로 구분하고 필요한 행동 한 가지를 안내해 줘.
웹 브라우저에서만 확인할 수 있는 필수 결과가 대화에 없으면 통과로 추정하지 말고,
사용자가 확인할 항목 한 가지만 쉬운 문장으로 질문한 뒤 답을 기다려 줘.

가장 먼저 같은 대화에 8080 WebUI 전체 확인 결과가 있는지 찾아 줘.
다음 항목이 모두 실제로 확인되어야 해.

1. Login 성공
2. Admin Dashboard 표시
3. Sidebar 표시와 메뉴 이동
4. Text Tool 입력·실행·결과 표시
5. 새로고침 뒤 Login 상태와 현재 화면 유지
6. Logout 성공과 Logout 뒤 보호 경로 차단 또는 Login 화면 이동
7. Desktop 화면의 Console 오류 없음
8. `/api/` Network 요청의 예상 상태 코드와 응답 확인
9. Keyboard만 사용한 이동·입력·실행·Logout 가능
10. Mobile 화면에서 주요 내용, Sidebar 또는 메뉴와 조작 요소 확인

위 결과 중 하나라도 대화에 없거나 실패·확인 불가이면 8080 WebUI 전체 확인을 통과로 기록하지 마.
누락된 항목을 사용자가 실제로 확인하도록 안내하고 답을 기다린 뒤에만 기록 작업을 계속해 줘.

파일별 기록 범위는 다음과 같아.

- docs/development-guides/webui-gate.md:
  실제 수행한 Compose 상태 확인, 8080 로그인, Admin Dashboard, Sidebar, Text Tool,
  새로고침, 관리자 주소 직접 접근과 Logout 뒤 보호 경로 이동 결과를 기록해 줘.
  실행 명령, 확인 시각과 통과·실패·미수행을 확인 가능한 범위에서 구분해 줘.
- README.md:
  09단계에서 확인된 현재 통합 기준선과 10~18단계의 상위 개선 순서만 짧게 기록해 줘.
  아직 없는 단계별 작업 지시서의 세부 범위를 확정된 내용으로 쓰지 마.
- docs/requirements/admin-platform.md:
  09단계 완료 조건을 실제로 충족한 경우에만 현재 단계와 상위 진행 순서를 일치시켜 줘.
  제품 요구사항과 아직 구현하지 않은 목표는 변경하지 마.
- docs/development-guides/local-development.md:
  09단계에서 Compose 실행·중지·재시작 또는 접속 절차가 실제로 변경된 경우에만 갱신해 줘.
  변경이 없으면 파일을 수정하지 마.
- docs/requirements/architecture-gap-analysis.md:
  기술 검토에서 이미 수정·재대조한 원본 산출물로 보존해 줘.
  기록 문서 갱신을 이유로 분석 내용이나 미확정 항목을 임의로 바꾸지 마.

각 파일의 기존 기록을 삭제하거나 덮어쓰지 말고 현재 구조에 맞는 위치에 09단계 결과를 추가하거나 오래된 진행 상태만 바로잡아 줘.
같은 결과를 여러 문서에 장문으로 중복하지 말고 파일 역할에 맞게 기록해 줘.
docs/requirements/architecture-gap-analysis.md의 마지막 기술 검토에서 수정 필요 항목이 남았는지도 확인해 줘.

다음 조건을 모두 충족한 경우에만 09단계 완료로 기록해 줘.

1. Login부터 Mobile 화면까지 위 10개 항목의 8080 WebUI 전체 회귀 검사 통과
2. 실제 수행 명령과 결과 확인
3. Gap 보고서와 실제 프로젝트 상태 일치
4. Backend와 Frontend 영향 파일 및 의존 관계 검토 완료
5. 실패·중단 기준과 실제 되돌리기 절차 구분
6. 데이터 변경 단계의 Backup·Restore 검증 요구사항과 사용자 승인 경계 기록
7. 검사 명령, 환경, Test 데이터 격리 방법과 성공 기준 기록
8. 구현하지 않은 목표의 완료 오기록 없음
9. 10~18단계의 상위 순서와 미확정 세부 범위 구분
10. 대조·수정·재검토 결과에서 수정 필요 항목이 남아 있지 않음

하나라도 충족하지 못하면 09단계 완료로 기록하지 말고 미완료 이유, 수정 대상 파일과 다음 해결 방법을 기록해 줘.
실행하지 않은 검사, 대화에 없는 사용자 확인과 재현하지 못한 결과는 통과로 기록하지 마.
기존 단계 결과를 재사용했다면 이번에 새로 실행한 결과와 구분해 줘.
현재 코드와 확인된 결과를 기준으로 위 기록 문서의 현재 단계와 구현 완료 상태가 서로 다른지도 확인해 줘.
현재 단계와 구현 완료 상태는 요구사항 변경이 아니라 진행 기록이야. 현재 코드와 확인된 검증 결과로 이번 단계의 완료 조건을 충족한 것이 확인되면, admin-platform.md를 포함한 위 문서의 오래되거나 충돌하는 진행 기록을 사용자에게 다시 묻지 말고 이번 단계 완료로 일치시켜 줘. 요구사항·기준·기존 검증 결과는 바꾸지 마.
실패·미수행·확인 불가 항목 때문에 완료 조건을 충족하지 못했다면 완료로 바꾸지 말고 실제 상태와 다음 해결 방법을 기록해 줘.

실패나 미수행 결과가 있으면 완료로 만들지 말고 원인과 다음 해결 방법을 기록해 줘.
안전하게 해결할 수 있는 기록 누락이나 진행 상태 충돌은 직접 수정하고 문서 간 상태를 다시 확인해 줘.
사용자 조작이 꼭 필요하면 사용자가 해야 할 행동 한 가지만 쉬운 문장으로 알려 줘.

마지막에는 비전공자도 이해할 수 있게 다음 내용만 보고해 줘.

1. 변경한 파일
2. 파일별로 기록한 실제 결과
3. 근거를 찾은 위치와 기존 기록을 재사용했는지
4. 수정하지 않은 파일과 그 이유
5. 현재 단계 완료 기록이 서로 일치하는지
6. 남은 실패·미수행·확인 불가 항목
7. 다음 단계 진행 가능 여부

스테이징과 커밋은 실행하지 마.

7. 최종 변경 검토와 커밋

Codex의 완료 보고만으로 끝내지 않고 Windows 관리 PC에서 화면과 Git 변경을 직접 확인합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
git status --short
git diff

git diff 의 결과를 q 로 빠져 나옵니다.

q

정식 작업 지시서의 완료 조건을 모두 만족하고 예상한 파일만 변경되었을 때 단계 결과를 Commit합니다.

git add README.md \
  docs/development-guides/webui-gate.md \
  docs/requirements/admin-platform.md \
  docs/requirements/architecture-gap-analysis.md
git --no-pager diff --cached --name-only
git commit -m "docs: complete 09 step"

변경 파일이 여러 개이면 검토한 경로를 모두 나열합니다. 문서·검증만 수행한 단계라면 실제 변경 성격에 맞게 docs:, test: 또는 chore: 커밋 메시지를 사용합니다. 필수 검사가 실패하면 커밋으로 완료 상태를 만들거나 다음 단계 작업 지시서를 실행하지 않습니다.

정식 작업 지시서 해설

이 절은 새로운 작업을 지시하거나 추가 명령을 실행하는 단계가 아닙니다. 정식 작업 지시서 실행, 구현 결과 검증, Codex의 검증 기록 갱신과 커밋까지 마친 뒤 읽는 복습용 해설입니다.

비전공자도 앞서 수행한 분석이 왜 필요했는지, 현재 구성과 목표 구성의 차이를 어떻게 판정했는지, 무엇을 검증하고 기록했는지를 이해할 수 있도록 쉽게 풀어서 설명합니다. 09단계에서는 애플리케이션 소스, 패키지, Compose와 실행 설정을 변경하지 않았습니다. 아래의 파일명, 주소와 명령은 분석 결과와 검증 기준을 이해하기 위한 참고 정보이며, 별도의 실행 안내가 없는 한 다시 실행하지 않습니다.

1. 완성된 결과

새 기능을 추가하지 않고 08단계 1차 통합 환경과 목표 구조 사이의 차이를 분석했습니다. 현재 정상 동작을 변경 금지 기준선으로 기록하고 이후 개선 순서를 10~18단계로 정리했습니다.

여기서 목표 구조는 01단계에서 정한 기술 구성, 권장 프로젝트 구조와 docs/requirements/admin-platform.md의 완료 조건이 18단계까지 반영된 목표 상태입니다. 10~18단계의 세부 설계와 영향 파일이 이미 모두 확정되었다는 뜻은 아닙니다. 각 단계의 세부 허용 범위, 의존 관계와 완료 조건은 해당 단계의 정식 작업 지시서를 작성할 때 실제 프로젝트에 대조하여 확정합니다.

09단계에서 채워진 주요 폴더와 파일

vibe-coding-platform/
└── docs/
    ├── work-orders/
    │   └── 09-architecture-gap-analysis.md
    └── requirements/
        └── architecture-gap-analysis.md

09단계는 분석 문서만 추가하고 backend/, frontend/, compose.yaml, Dockerfile과 Nginx 설정은 변경하지 않습니다. architecture-gap-analysis.md에는 현재 구조, 목표 구조, 차이, 영향과 10~18단계의 상위 개선 순서를 기록합니다.

2. 구조 차이 분석의 의미

Gap은 현재 구성이 잘못됐다는 뜻이 아니라 목표 상태에 도달하려면 더 구현하거나 강화해야 하는 차이입니다. 08단계에서 Docker Compose, Redis 세션 저장소와 Nginx 단일 진입점은 이미 적용했으므로 이를 미구현 항목으로 다시 기록하지 않습니다. 현재 확인된 1차 통합 구성을 출발점으로 삼아 백엔드 구조, 입력 검증, Prisma, Redis 안정성, 개발·통합 Compose 환경 분리, HTTPS, 보안, 자동 검사와 운영 점검을 단계별로 나눴습니다.

현재 상태와 목표 상태의 차이는 다음과 같은 방식으로 이해할 수 있습니다.

• 현재 Redis 세션 저장소 사용 → Redis 장애·재시작·재생성에 대비한 세션 정책과 운영 안정성 강화
• 현재 단일 Compose 구성 → 개발 환경과 통합 환경의 Compose 구성 분리
• 현재 Nginx 8080 HTTP 진입점 → 실제 도메인, 인증서와 secure 쿠키를 사용하는 HTTPS 진입점
• 현재 동작 중심의 백엔드 구성 → 책임과 API 계약을 명확히 구분한 백엔드 구조

따라서 09단계의 구조 차이 분석 보고서는 이미 완료한 구성을 다시 구현하기 위한 목록이 아니라, 현재 기준선을 보존하면서 다음 단계에서 강화할 차이와 순서를 기록한 문서입니다.

각 Gap에는 단순히 부족한 기능 이름만 적지 않습니다. 다음 내용을 함께 기록해야 이후 단계에서 안전하게 작업할 수 있습니다.

• 현재 상태와 이를 확인한 실제 파일
• 목표 상태와 요구사항 근거
• 직접·간접 영향 파일과 백엔드 API 변경에 따른 프런트엔드 영향
• 선행·후속 단계와 적용 순서
• 데이터·보안 위험
• 실패·중단 기준과 되돌리기 요구사항
• 자동 검사 명령, 실행 환경, 테스트 데이터 격리 방법과 성공·실패 기준
• 사용자가 확인할 WebUI 항목
• 현재 확정된 내용과 해당 단계에서 확정할 미확정 내용

이 구분은 아직 구현하지 않은 목표를 현재 완료 상태로 오해하거나, 작성되지 않은 후속 단계의 세부 범위를 미리 확정하는 일을 막아 줍니다.

3. 변경 금지 기준선

Login, Dashboard, Text Tool, 새로고침, Logout과 보호 경로처럼 검증된 동작은 이후 구조 변경에서도 유지해야 합니다. MySQL 데이터 보존, 백엔드 재시작 뒤 Redis 세션 유지, Nginx 8080 단일 진입점과 내부 서비스 포트 비공개 결과도 08단계의 통합 기준선에 포함합니다. 이 기준선으로 내부 구조를 바꾼 뒤 사용자 기능이나 실행 경계가 손상됐는지 판단합니다.

08단계의 사용자 수동 WebUI 검증은 8080 통합 환경에서 수행했습니다. 5173 개발 환경은 이번 검증에서 다시 실행하지 않았으므로 09단계 기준선에서도 새 통과 결과가 아니라 이전 기준선 또는 구성 보존 상태로 구분합니다.

08단계의 Compose, Redis와 Nginx 구성은 최종 운영 구성이 아니라 1차 통합 기준선입니다. 이후 단계에서는 이 기준선을 한꺼번에 다시 만들지 않고 백엔드 구조와 입력 검증, 데이터 접근, 세션 안정성, 환경 분리와 HTTPS 경계를 순서대로 강화합니다.

백엔드 컨테이너만 재시작했을 때 Redis에 저장된 세션이 유지되는 것과 Redis 컨테이너를 재시작하거나 재생성했을 때의 결과는 구분해야 합니다. 현재 Redis에 볼륨과 영속성 설정이 없다면 docker compose down으로 Redis 컨테이너를 제거한 뒤 다시 만들 때 기존 세션이 사라질 수 있습니다. 이는 백엔드 재시작 뒤 세션 유지 기준선과 모순되는 결과가 아니라 Redis 영속성의 현재 한계이며, 13단계에서 정책과 검증 범위를 확정할 항목입니다.

4. 검증 기준의 의미

09단계에서는 화면 기능을 새로 만들지 않았지만, 분석 전후에 기존 동작이 손상되지 않았는지 확인해야 합니다. 사용자는 8080에서 Login, Admin Dashboard, Sidebar, Text Tool, 새로고침, Logout, 보호 경로 차단, 웹 브라우저 Console·Network, 키보드 조작과 모바일 화면을 확인했습니다. Codex는 백엔드·프런트엔드 검사, 배포용 빌드, Compose 구성, 실행 중인 서비스 상태와 공개 포트를 확인했습니다.

자동 검사 이름만 기록해서는 같은 검증을 재현할 수 없습니다. 실행 명령, 실행 위치, 환경 전제, 격리된 테스트 데이터와 성공 기준을 함께 남깁니다. Mock 또는 MemoryStore 기반 검사는 코드 일부를 빠르게 확인하는 검사이고, 실제 MySQL·Redis 통합 검사는 실제 서비스 연결과 데이터·세션 동작을 확인하는 검사이므로 서로 구분합니다.

실패·중단 기준과 실제 되돌리기 절차도 같은 뜻이 아닙니다. 완료로 기록하지 않는다는 다음 단계 진행을 막는 판정 기준입니다. 실제 되돌리기에는 복귀할 커밋·파일·이미지·설정, 데이터와 세션 확인, 실행할 복구 명령과 사용자 승인 경계가 필요합니다. 아직 정확한 복구 대상과 명령이 확정되지 않았다면 실행 가능한 절차라고 쓰지 않고 되돌리기 요구사항 또는 되돌리기 초안으로 구분합니다.

Schema 또는 Migration처럼 영속 데이터를 바꾸는 단계에는 변경 전 백업, 백업 식별 방법, 안전한 저장과 폐기 기준, Checksum, 운영 원본과 분리된 복원 검증, 변경 전후 데이터 확인 및 사용자 승인 경계가 필요합니다. 09단계에서는 명령을 임의로 만들지 않고 이러한 요구사항을 해당 단계에서 확정하도록 기록합니다.

5. 읽기 전용 기술 검토의 의미

구조 차이 분석 보고서는 파일이 존재하고 항목이 채워졌다는 이유만으로 완료되지 않습니다. Codex가 실제 소스, 패키지, Compose, Nginx 설정과 요구사항을 읽기 전용으로 다시 조사하여 현재 상태의 근거, 영향 파일, 데이터·보안 위험과 회귀 검사의 타당성을 대조했습니다. 발견한 문제는 구조 차이 분석 보고서 안에서만 수정하고 애플리케이션 구성은 변경하지 않았습니다.

이 재검토를 통해 모순, 누락, 과장된 확정과 실행하지 않은 검사의 통과 기록이 남아 있지 않은지 확인합니다. 근거가 부족한 내용은 추정하지 않고 미확정 상태와 이를 확정할 후속 단계를 기록합니다.

6. 기록의 의미

중요한 구조 선택에는 결과뿐 아니라 선택 이유, 대안과 영향도 기록합니다. 이후 구성이 달라져도 당시 판단을 이해하고 안전하게 수정할 수 있게 하기 위해서입니다. 09단계의 기본 산출물은 docs/requirements/architecture-gap-analysis.md이며, 별도의 구조 결정 문서가 실제로 작성되지 않았다면 작성 완료로 표현하지 않습니다.

7. 다음 단계

10단계부터 백엔드 구조, Zod, Prisma, Redis, Compose 환경 분리, HTTPS, 보안, 자동 검사 통합과 운영 점검 순서로 진행합니다. 10~16단계에서는 각 단계에 이미 존재하는 자동 검사와 공통 Gate를 삭제하거나 약화하지 않고 변경 뒤 다시 실행합니다. 17단계에서는 그동안 누적한 검사와 부족한 회귀 검사를 하나의 Release Gate로 통합합니다. 앞 단계의 필수 Gate가 실패하면 다음 변경을 완료로 판단하지 않습니다.

Codex가 갱신한 단계 산출물과 검증 기록

앞의 6. Codex에 검증 결과 기록 요청에서 Codex가 이 단계의 산출물과 검증 기록을 갱신합니다. 아래 내용은 Codex가 기록할 항목에 대한 설명입니다.

이 작업은 여러 문서에 같은 단계의 실행 명령, 검증 결과와 현재 제한을 서로 맞게 기록해야 하므로 비전문가가 직접 수정하면 항목을 빠뜨리거나 서로 다른 내용을 남기기 쉽습니다. Codex는 앞 단계에서 확인한 작업 기록과 실제 결과를 기준으로 관련 문서를 한 번에 비교하여 갱신할 수 있으므로 사용자가 이 파일들을 직접 수정할 필요가 없습니다.

분석 시작 전 09단계 작업 지시서에 조사 범위와 변경 금지 기준을 확정합니다. 분석 결과는 docs/requirements/architecture-gap-analysis.md의 구조 차이 목록에 남깁니다. 별도의 구조 결정 기록이 필요한 선택은 실제 기록 파일과 형식이 확정된 경우에만 기록합니다. 요구사항과 실제 구현의 차이가 확인되면 어느 쪽을 기준으로 바꿀지 사용자 확인 후 요구사항 문서를 갱신합니다. 이 단계에서 구현하지 않은 목표를 실행 문서나 webui-gate.md의 통과 결과로 기록하지 않습니다.

Codex에 의해 local-development.md에 기록되는 내용

구조 차이 분석에서 현재 실행 구성과 문서의 불일치 또는 실행·접속 절차 변경이 확인된 경우에만 수정합니다. 변경이 없으면 이 파일을 수정하지 않습니다. 아직 구현하지 않은 목표 구성은 실행 절차로 작성하지 않고 향후 변경으로 구분하며, 현재 통과한 기준선 명령과 접속 주소만 유지합니다.

Codex에 의해 README.md에 기록되는 내용

구조 차이 분석을 마친 뒤 루트 README.md에 확정된 현재 상태와 다음 변경 방향을 기록합니다.

## 현재 단계

09단계: 목표 아키텍처와 현재 프로젝트 비교하기

## 현재 기준선

- 현재 서비스, 포트, 경로와 API 목록을 기록했습니다.
- 데이터베이스, 세션과 `Sidebar` 메뉴의 현재 상태를 확인했습니다.
- 권장 프로젝트 구조와 실제 파일 위치를 비교했습니다.
- 기존 동작을 보존해야 할 변경 금지 기준선을 확정했습니다.

## 남은 작업

- 10~18단계에서 처리할 구조 차이를 우선순위대로 기록합니다.
- 결정한 구조 변경은 실제로 사용하는 구조 결정 기록과 작업 지시서에 남깁니다.

## 검증

- 이 단계에서는 기존 기능을 변경하지 않고 공통 WebUI Gate로 기준선을 확인합니다.

다음 단계

• 이전: 8단계: 운영 구성을 차례로 추가하기
• 다음: 10단계: Backend 구조와 API 응답 형식 정리하기
• 상위 설계: 1단계: VS Code 원격 서버에서 Vibe Coding 환경 준비와 Codex CLI 실행