1단계: VS Code 원격 서버에서 Vibe Coding 환경 준비와 Codex CLI 실행

핵심 요약

이 문서의 목표는 Windows PC의 VS Code에서 project-dev-server에 접속한 뒤, Linux 서버의 프로젝트 폴더를 작업 기준점으로 삼아 Codex CLI를 실행하는 것입니다.

이 연재에서는 Codex CLI를 기준 도구로 사용하지만, Vibe Coding에 사용할 수 있는 AI 코딩 에이전트는 Codex CLI만 있는 것이 아닙니다. Claude Code, Gemini CLI 등 여러 도구를 사용할 수 있으며, 이미 사용 중인 AI 코딩 에이전트가 있다면 해당 도구를 사용해도 됩니다. 다만 도구마다 설치 방법, 실행 명령과 프로젝트 작업 규칙 파일이 다를 수 있으므로 이 문서의 Codex CLI 절차를 선택한 도구에 맞게 적용해야 합니다. 주요 도구의 특징과 차이는 AI 코딩 에이전트 추가 학습 문서에서 확인할 수 있습니다.

전체 흐름은 다음과 같습니다.

Windows PC
    ↓
VS Code
    ↓ Remote SSH
project-dev-server
    ↓
/home/apple2ne1/projects/vibe-coding-platform
    ↓
Codex CLI 실행
    ↓
작업 지시 → 파일 변경 확인 → 애플리케이션 검증

Codex CLI는 프로젝트마다 설치하는 프로그램이 아닙니다. Linux 사용자 환경에 한 번 설치하고, 실제 작업할 때는 반드시 대상 프로젝트의 루트 폴더에서 실행합니다.

이 문서에서 준비한 하나의 프로젝트를 02~18단계까지 계속 확장합니다. 최종 목표는 Nginx, Node.js, Vite, React, MySQL과 Redis로 구성한 Admin Web UI입니다.

웹 브라우저
  ↓
Nginx 단일 진입점
  ├── React Production Build
  └── Node.js·Express API
      ├── MySQL Admin 계정과 데이터
      └── Redis Session Store

Admin Web UI에는 Login, 보호된 Dashboard와 실제 기능 메뉴인 Text Tool 하나를 완성합니다. 이후 단계에서는 이 메뉴가 계속 동작하는지 회귀 검사하면서 운영 구성을 강화합니다.

1. 이 문서에서 완성할 환경

이 문서를 마치면 다음 작업을 할 수 있습니다.

• Windows의 VS Code에서 project-dev-server에 Remote SSH로 접속
• Linux 서버의 프로젝트 폴더를 VS Code 작업 영역으로 열기
• Codex CLI 설치 여부와 로그인 상태 확인
• 프로젝트 루트의 AGENTS.md로 작업 규칙 전달
• Codex CLI에 작은 작업을 지시하고 변경 내용을 검토
• 다음 단계인 Login과 Admin Dashboard 화면 구현으로 이동

2. 설치 위치와 실행 위치 구분

Codex CLI의 설치 위치와 작업 실행 위치는 서로 다릅니다.

Codex CLI를 설치하면 실행 파일은 /usr/local/bin/codex 또는 사용자의 npm 전역 설치 경로에 있습니다. 하지만 실제 작업은 다음 프로젝트 루트에서 시작해야 Codex CLI가 해당 프로젝트를 작업 범위로 인식합니다.

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

3. 시작하기 전에

다음 항목이 준비되어 있어야 합니다.

• Windows PC에 VS Code가 설치되어 있음
• VS Code의 Remote – SSH 확장을 사용할 수 있음
• project-dev-server에 SSH로 접속할 수 있음
• Linux 서버에 Node.js와 npm이 설치되어 있음
• OpenAI 계정 또는 사용할 수 있는 API 인증 방식이 준비되어 있음
• 프로젝트 파일을 저장할 Linux 경로를 결정함

서버 접속 정보, Password, API Key와 Token은 Markdown 문서나 Git 저장소에 기록하지 않습니다.

4. VS Code에서 project-dev-server 접속

4.1 Remote SSH 연결

VS Code의 Remote Explorer에서 project-dev-server를 펼치고 /home/apple2ne1 항목의 연결 버튼을 선택합니다. 현재 VS Code 창에서 열려면 Connect in Current Window…를 선택합니다.

4.2 터미널이 서버에 연결되었는지 확인

VS Code에서 새 터미널을 열고 다음 명령을 실행합니다.

whoami
hostname
pwd

예상 확인 항목은 다음과 같습니다.

• whoami: 서버 작업에 사용할 Linux 사용자
• hostname: project-dev-server 또는 실제로 설정한 Hostname
• pwd: 현재 Linux 작업 경로

5. 프로젝트 루트 준비

VS Code의 원격 터미널에서 프로젝트 폴더를 만들고 해당 폴더로 이동합니다.

mkdir -p /home/apple2ne1/projects/vibe-coding-platform
cd /home/apple2ne1/projects/vibe-coding-platform
pwd
ls -la

pwd에는 /home/apple2ne1/projects/vibe-coding-platform이 출력되어야 합니다. 새로 만든 빈 폴더에서 ls -la를 실행하면 현재 폴더를 나타내는 .과 상위 폴더를 나타내는 ..만 표시될 수 있습니다.

5.1 VS Code 작업 폴더로 열기

Remote Explorer에서 project-dev-server 오른쪽의 연결 버튼을 선택하고 Connect in Current Window…를 실행합니다.

원격 서버에 연결되었지만 작업 폴더가 열리지 않은 화면에서 Open Folder를 선택합니다.

Open Folder 입력란에 다음 경로를 입력하고 OK를 선택합니다.

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

폴더가 열리면 VS Code 창 제목과 Explorer의 최상위 폴더가 vibe-coding-platform인지 확인합니다.

5.2 새 터미널에서 프로젝트 루트 확인

VS Code 상단 메뉴에서 Terminal → New Terminal을 선택합니다.

새 터미널에서 현재 경로를 확인합니다.

pwd

다음 프로젝트 루트가 출력되면 작업 폴더가 올바르게 열린 것입니다.

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

앞으로 작업은 이 폴더에서 진행합니다. 다른 작업 중에도 언제든지 Remote Explorer를 통해 이 폴더에 접근할 수 있습니다.

6. Git 작업 기준점 만들기

Codex가 변경한 내용을 안전하게 비교하려면 Git 저장소를 먼저 준비하는 것이 좋습니다. 로컬 Git 저장소는 프로젝트의 변경 이력을 같은 컴퓨터 또는 개발 서버 안에 기록합니다. GitHub 같은 원격 저장소를 연결하지 않아도 사용할 수 있지만, 로컬에서 만든 Commit이 외부로 자동 전송되지는 않습니다.

새 프로젝트인 경우 프로젝트 루트에서 다음 명령을 한 번 실행합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
git init
git status

6.1 첫 커밋 전에 .gitignore 만들기

.gitignore는 첫 git add보다 먼저 만듭니다. 나중에 추가하면 이미 Git이 추적하기 시작한 Secret이나 생성 파일은 제외 규칙만으로 추적이 중단되지 않습니다.

touch .gitignore

현재 폴더에 .gitignore라는 빈 파일을 만듭니다.

이미 파일이 있으면 내용은 그대로 두고 수정 시간만 갱신합니다.

아래 내용을 .gitignore 에 입력합니다.

node_modules/
dist/
coverage/
*.log
.env
.env.*
!.env.example
!.env.*.example

이 내용은 .gitignore 파일에 넣는 규칙으로, Git이 추적하거나 GitHub에 올리지 않을 파일과 폴더를 지정합니다.

node_modules/

Node.js 패키지가 설치되는 node_modules 폴더를 제외합니다.

용량이 매우 크고 package.json으로 다시 설치할 수 있으므로 Git에 올리지 않습니다.

dist/

React·Vite 등의 빌드 결과가 저장되는 dist 폴더를 제외합니다.

coverage/

테스트 실행 후 생성되는 코드 테스트 범위 보고서 폴더를 제외합니다.

*.log

확장자가 .log인 모든 로그 파일을 제외합니다.

예:

error.log
npm-debug.log
server.log

.env

정확히 이름이 .env인 환경설정 파일을 제외합니다. 이 파일에는 비밀번호, 데이터베이스 정보, API 키 등이 들어갈 수 있습니다.

.env.*

.env.로 시작하는 모든 파일을 제외합니다.

예:

.env.local
.env.development
.env.production
.env.test

!.env.example

앞의 !는 제외 규칙을 취소하고 Git에 포함하라는 뜻입니다. 따라서 .env.example은 Git에 포함합니다.

!.env.*.example

.env.로 시작하고 .example로 끝나는 파일도 Git에 포함합니다.

예:

.env.development.example
.env.production.example

전체 의미를 정리하면 다음과 같습니다.

실제 비밀 환경설정 파일 → Git에서 제외
사용 방법을 보여 주는 example 파일 → Git에 포함

예를 들어:

.env.production          → 제외됨
.env.production.example  → 포함됨

.env.production.example에는 실제 비밀번호 대신 다음처럼 예시값을 작성합니다.

DB_HOST=localhost
DB_USER=your_username
DB_PASSWORD=

DB_PASSWORD는 실제 값을 예시 파일에 기록하지 않도록 비워 둡니다.

Lock 파일인 package-lock.json은 재현 가능한 설치를 위해 제외하지 않습니다. 저장한 뒤 실제 환경 파일은 제외되고 예시 파일은 제외되지 않는지 확인합니다.

git check-ignore -v --no-index .env
git check-ignore -v --no-index .env.mysql
git check-ignore -v --no-index .env.example

앞의 두 명령은 일치한 규칙을 출력해야 합니다. 마지막 명령은 아무것도 출력하지 않고 종료 상태 1을 반환하는 것이 정상입니다. 그다음 git status --short를 확인한 후에만 첫 git add를 실행합니다.

화면 예시에서는 초기 브랜치가 master로 생성되었습니다. 초기 브랜치 이름은 Git 버전과 init.defaultBranch 설정에 따라 main 등 다른 이름으로 표시될 수 있습니다.

기존 저장소라면 git init을 다시 실행하지 말고 상태만 확인합니다.

git status --short

6.2 첫 커밋 전에 작성자 정보 등록하기

로컬 Git 저장소만 사용하더라도 각 Commit에 누가 변경 내용을 기록했는지 남기려면 작성자 이름과 이메일 주소를 등록해야 합니다. 이 정보는 Commit 메타데이터에 기록되며, GitHub 로그인이나 원격 저장소 인증에 사용하는 계정 정보와는 다릅니다.

프로젝트 루트에서 다음 명령을 실행합니다. 예시값은 실제로 Commit을 작성할 때 사용할 이름과 이메일 주소로 바꿉니다.

git config --local user.name "Your Name"
git config --local user.email "you@example.com"

--local로 등록한 설정은 현재 Git 저장소에만 적용됩니다. 같은 개발 서버의 다른 저장소에는 영향을 주지 않습니다. 등록된 값을 확인합니다.

git config --local --get user.name
git config --local --get user.email

두 명령에서 설정한 이름과 이메일 주소가 각각 출력되는지 확인한 뒤 첫 Commit을 만듭니다. 공개 저장소로 전송할 가능성이 있다면 개인 이메일 주소 노출 여부를 미리 확인하고, 필요한 경우 Git 호스팅 서비스에서 제공하는 비공개 이메일 주소를 사용합니다.

최소한의 Git 작업 순서

한 단계의 작업을 마쳤을 때 다음 순서로 변경 내용을 확인하고 저장합니다.

git status
git add .
git diff --cached --name-only
git diff --cached --check
git commit -m "작업 내용 요약"

각 명령의 역할은 다음과 같습니다.

• git status: 수정된 파일, 새로 생긴 파일과 커밋할 준비가 된 파일을 표시합니다.
• git diff --cached --name-only: 스테이징된 파일명을 표시합니다.
• git diff --cached --check: 공백 오류와 충돌 표시를 자동으로 검사합니다.
• git commit -m "작업 내용 요약": 자동 검사를 통과한 스테이징 파일을 하나의 작업 기준점으로 저장합니다.

git status와 git diff로 변경 내용을 확인한 뒤 git add .을 실행하여 현재 프로젝트의 변경 파일을 모두 스테이징합니다. 이어서 git diff --cached --name-only의 출력에 예상하지 못한 파일이 없는지 확인하고, git diff --cached --check가 오류 없이 끝난 경우에만 커밋합니다. 출력이 다르면 커밋하지 않고 Codex에 출력 전체를 전달해 스테이징 범위를 바로잡도록 요청합니다. 실제 값이 있는 .env는 반드시 .gitignore로 제외합니다. 커밋한 뒤에는 git status --short를 실행하여 남은 변경을 확인합니다.

개발 서버에서 만든 Commit은 현재 프로젝트 폴더 안의 숨김 폴더인 .git에 저장됩니다.

/home/apple2ne1/projects/vibe-coding-platform/.git/

GitHub 같은 원격 저장소에 저장할 수 있으므로 .gitignore에는 최소한 위에서 설명한 파일을 제외합니다. AI 코딩 에이전트를 설치한 뒤에는 현재 기술 스택을 검사하여 제외 규칙을 보완하도록 요청할 수 있지만, 적용 전에는 결과를 직접 검토합니다.

Github 무료 저장소 : GitHub · Change is constant. GitHub keeps you ahead. · GitHub

개발 서버의 디스크가 고장 나거나 프로젝트 폴더와 .git이 함께 삭제되면 commit 기록도 사라질 수 있습니다. 중요한 프로젝트는 git push로 GitHub 같은 원격 저장소에도 보관하는 것이 안전합니다. 그러나 여기서는 다루지 않겠습니다.

7. Codex CLI 설치와 확인

사용할 AI 코딩 에이전트를 설치하고 확인합니다. 여기서는 Codex CLI를 사용합니다.

먼저 설치 여부를 확인합니다.

codex --version
command -v codex

정상이라면 Codex CLI 버전과 실행 파일 경로가 출력됩니다.

Codex CLI를 npm으로 설치하려면 먼저 Node.js와 npm이 필요합니다.

codex 명령을 찾지 못한다면 다음 명령으로 Node.js와 npm의 설치 여부를 확인합니다.

node --version
npm --version

화면에 표시된 apt 설치 명령은 Ubuntu가 제시한 안내입니다. 이 문서에서는 여러 Node.js 버전을 사용자 계정 단위로 관리하고 npm 전역 패키지를 sudo 없이 설치할 수 있도록 nvm을 사용합니다.

7.1 nvm으로 Node.js와 npm 설치

먼저 nvm 설치 스크립트를 내려받는 데 필요한 curl을 준비합니다.

sudo apt update

curl을 설치합니다. 이미 최신 버전이 설치되어 있다면 추가로 변경되는 패키지 없이 명령이 끝납니다.

sudo apt install curl

nvm-sh 공식 GitHub 저장소에서 안내하는 nvm 설치 스크립트를 실행합니다. 이 문서에서 직접 확인한 설치 버전은 v0.40.5입니다.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash

설치가 끝나면 현재 Bash 세션에 변경된 설정을 반영하고 nvm을 확인합니다.

source ~/.bashrc
command -v nvm

nvm이 출력되면 최신 LTS 버전의 Node.js를 설치합니다. npm은 Node.js와 함께 설치됩니다.

nvm install --lts
node --version
npm --version

node --version과 npm --version에서 각각 버전 번호가 출력되면 설치가 완료된 것입니다. 새 터미널에서 명령을 찾지 못하면 source ~/.bashrc를 다시 실행한 뒤 확인합니다.

7.2 bubblewrap 설치와 Codex 샌드박스 확인

Codex CLI는 Linux에서 명령과 파일 작업을 격리하기 위해 bwrap과 seccomp를 사용합니다. Ubuntu에서는 Codex CLI를 처음 실행하기 전에 Ubuntu 패키지의 bubblewrap을 설치합니다. 이 패키지가 없으면 Codex가 번들 보조 프로그램을 사용하다가 bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted와 같은 오류로 파일 편집을 중단할 수 있습니다.

VS Code 원격 터미널에서 다음 명령을 한 줄씩 실행합니다. 한 명령이 끝나 프롬프트가 다시 표시된 뒤 다음 명령을 실행합니다.

sudo apt install bubblewrap

설치 확인 질문이 표시되면 Y를 입력합니다. Service restarts being deferred나 User sessions running outdated binaries는 패키지 설치 후 재시작을 나중으로 미룬 서비스와 세션을 알리는 메시지입니다. 이 단계에서 Docker, 네트워크 또는 VS Code를 임의로 재시작하지 않습니다.

bwrap 실행 경로와 Version을 확인합니다.

command -v bwrap
bwrap --version

Ubuntu 26.04 검증 환경에서는 다음과 같이 표시되었습니다.

/usr/bin/bwrap
bubblewrap 0.11.1

다음 한 줄을 그대로 실행해 기본 샌드박스 동작을 확인합니다. 명령 다음의 설명 문장은 터미널에 입력하지 않습니다.

bwrap --ro-bind / / --dev /dev --proc /proc /bin/true; echo "종료 코드: $?"

정상 결과:

종료 코드: 0

0이 아닌 값이나 Operation not permitted 오류가 표시되면 Codex CLI를 실행하지 않고 오류 전체를 기록합니다. Docker, LXC 또는 다른 컨테이너 안의 Linux는 호스트의 Namespace·seccomp 제한으로 bwrap이 동작하지 않을 수 있으므로 임의로 제한을 해제하지 않습니다.

Codex CLI를 실행한 상태에서 bubblewrap을 설치했다면 기존 Codex 세션을 /exit 또는 Ctrl+C로 종료한 뒤 새로 실행합니다. 이미 생성된 프로젝트 파일은 삭제하거나 다시 생성하지 않습니다.

7.3 Codex CLI 설치

Node.js 환경이 준비된 경우, Windows PC의 VS Code에서 project-dev-server에 Remote SSH로 접속한 뒤 원격 터미널에서 Codex CLI를 전역으로 설치합니다.

npm install --global @openai/codex

화면의 npm notice는 사용할 수 있는 새 npm 버전이 있다는 알림이며 Codex CLI 설치 오류가 아닙니다. 이 단계에서 npm을 바로 업데이트하지 않아도 됩니다.

설치 후 다시 확인합니다.

codex --version
command -v codex

8. Codex CLI 로그인

8.1 Windows PC의 웹 브라우저에서 로그인

VS Code로 접속한 project-dev-server의 원격 터미널에서 다음 명령을 실행합니다.

codex login

CLI가 표시하는 주소를 Windows PC의 웹 브라우저에서 엽니다. ChatGPT 계정을 Google과 연동하여 사용하고 있다면 Continue with Google을 선택하고, 기존에 사용하던 Google 계정으로 인증합니다. Google 계정 자체가 Codex 전용 계정이 되는 것은 아니며, Google 로그인을 통해 해당 ChatGPT 계정에 인증하는 절차입니다.

브라우저에 기존 ChatGPT 계정이 표시되면 사용할 계정을 선택합니다.

선택한 ChatGPT 계정을 확인하고 Continue를 선택합니다.

Signed in to Codex가 표시되면 브라우저 인증이 완료된 것입니다. 주소 표시줄에는 인증정보가 포함될 수 있으므로 화면을 기록하거나 공유할 때 반드시 가립니다.

인증이 끝나면 원격 터미널로 돌아와 로그인 상태를 확인합니다.

codex login status

8.2 로그인 후 Codex CLI 첫 실행 확인

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

codex

처음 실행할 때 프로젝트 폴더를 신뢰할 것인지 묻는 화면이 표시될 수 있습니다. 현재 프로젝트가 사용자가 직접 만들었거나 내용을 확인한 신뢰할 수 있는 폴더라면 Yes, continue를 선택합니다. 출처를 알 수 없는 프로젝트라면 실행을 중단하고 파일을 먼저 확인합니다.

Codex CLI의 입력 화면이 표시되면 로그인과 첫 실행이 완료된 것입니다.

화면의 bubblewrap 경고는 Linux 샌드박스에 사용할 시스템 bubblewrap을 PATH에서 찾지 못해 Codex가 번들 버전을 사용한다는 안내입니다. Codex CLI 입력 화면이 정상적으로 표시되었다면 로그인 실패 메시지는 아닙니다.

8.3 브라우저 인증이 연결되지 않는 경우

Remote SSH 환경에서 기본 브라우저 인증의 연결이 완료되지 않으면 Device Code 방식을 사용합니다.

codex login --device-auth

터미널에 표시된 주소를 Windows PC의 웹 브라우저에서 열고 일회용 코드를 입력한 뒤, 같은 ChatGPT 계정으로 인증합니다. Device Code 로그인이 표시되지 않으면 ChatGPT 계정 또는 작업 영역의 보안 설정에서 해당 기능을 사용할 수 있는지 확인합니다.

8.4 API Key를 사용하는 경우

API Key는 명령줄에 직접 붙여 넣거나 문서에 기록하지 않습니다. 환경변수로 준비한 뒤 표준 입력으로 전달합니다.

printenv OPENAI_API_KEY | codex login --with-api-key

실제 API Key 값이 화면, 셸 기록, Markdown 파일 또는 Git에 남지 않도록 주의합니다.

9. 권장 프로젝트 구조

Login부터 최종 운영 확인까지 모든 단계에서 다음 최상위 구조를 유지합니다.

vibe-coding-platform/
├── AGENTS.md
├── README.md
├── docs/
│   ├── requirements/
│   ├── work-orders/
│   └── development-guides/
├── frontend/
├── backend/
├── database/
├── nginx/
├── docker/
├── scripts/
├── .env.example
├── .gitignore
└── compose.yaml

각 폴더의 역할은 다음과 같습니다.

이 구조는 01단계에서 먼저 만들고 02~18단계에서 내용을 채웁니다. 이후 단계에서 같은 역할의 새 최상위 폴더를 임의로 만들지 않습니다. Git은 빈 폴더를 기록하지 않으므로 아직 내용이 없는 폴더에는 역할을 설명하는 README.md를 둡니다.

9.1 프로젝트 골격 만들기

프로젝트 루트에서 다음 폴더를 만듭니다.

mkdir -p docs/requirements docs/work-orders docs/development-guides

프런트엔드, 백엔드와 데이터베이스 자료를 저장할 폴더를 만듭니다.

mkdir -p frontend backend database/init database/backup

Nginx, Docker와 반복 실행 스크립트를 저장할 폴더를 만듭니다.

mkdir -p nginx docker scripts

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

다음 파일은 01단계에서 아래 순서로 준비합니다. 각 파일은 이름만 만들고 끝내지 않고, 이 문서에서 안내하는 최초 내용을 입력한 뒤 확인합니다. 바로 앞의 프로젝트 골격과 다음 파일 목록을 합친 구성이 01단계 완료 시점의 기본 구조입니다.

1. README.md
2. docs/requirements/admin-platform.md
3. docs/development-guides/local-development.md
4. .env.example
5. compose.yaml
6. AGENTS.md

README.md부터 compose.yaml까지는 아래의 파일별 절차에 따라 만들고, AGENTS.md는 이어지는 [[#10. AGENTS.md로 작업 규칙 전달|10절]]에서 작성합니다. 01단계의 .env.example에는 보안 원칙을 설명하는 주석만 기록하고, compose.yaml에는 유효한 최소 Compose 구조만 기록합니다. 실제 환경변수와 서비스 구성은 해당 기능을 처음 사용하는 후속 단계에서 추가합니다.

9.1.1 구성 파일 생성·갱신 시점

구성 파일은 이름만 미리 만들어 두기보다 처음 사용하는 단계에서 내용을 작성하고 즉시 검증합니다.

README.md에는 프로젝트 목표, 현재 단계, 실행 주소와 검증 명령을 기록합니다. docs/requirements/admin-platform.md에는 Login, Admin 권한, Dashboard, Text Tool과 최종 Service 구성의 완료 조건을 기록합니다. 실제 Secret은 어떤 문서에도 넣지 않습니다.

9.1.2 README.md가 필요한 이유와 최초 작성

README.md는 프로젝트를 처음 연 사람과 AI 코딩 에이전트가 프로젝트의 목적, 현재 진행 단계, 폴더 역할과 실행·검증 방법을 빠르게 확인하기 위한 시작 문서입니다. 애플리케이션 실행에 반드시 필요한 파일은 아니지만, 01~18단계에서 구성이 계속 바뀌므로 실제 상태와 사용 방법을 잃지 않도록 각 단계가 끝날 때 갱신합니다.

README.md와 다른 기준 문서의 역할은 다음과 같이 구분합니다.

프로젝트 루트에서 파일을 만듭니다.

touch README.md

01단계에서는 다음과 같이 최초 내용을 작성합니다.

# Vibe Coding Platform

## 프로젝트 목표

Nginx, Node.js, Express, Vite, React, MySQL과 Redis로 구성된 Admin Web UI를 01~18단계에 걸쳐 구현하고 검증합니다.

## 현재 단계

01단계: VS Code 원격 서버에서 Vibe Coding 환경 준비와 Codex CLI 실행

## 현재 상태

- `project-dev-server`에 VS Code Remote SSH로 접속할 수 있습니다.
- 프로젝트 루트는 `/home/apple2ne1/projects/vibe-coding-platform`입니다.
- Git 저장소와 루트 `AGENTS.md`를 준비했습니다.
- Codex CLI 설치, 로그인과 프로젝트 규칙 확인을 완료했습니다.
- 애플리케이션 기능은 아직 구현하지 않았습니다.

## 프로젝트 구조

- `frontend/`: React, Vite와 TypeScript 프런트엔드
- `backend/`: Node.js, Express와 TypeScript API
- `database/`: MySQL 초기화, Schema와 백업·복원 자료
- `nginx/`: Nginx 설정
- `docker/`: Dockerfile과 환경별 Compose 보조 파일
- `docs/`: 요구사항, 작업 지시서와 개발 가이드
- `scripts/`: 반복 실행하는 검증과 운영 스크립트

## 실행 주소

현재 단계에서는 실행 가능한 애플리케이션이 없습니다.

## 기본 확인

```bash
pwd
git status --short
codex --version
codex login status
```

## 기준 문서

- 작업 규칙: `AGENTS.md`
- 요구사항: `docs/requirements/admin-platform.md`
- 작업 지시서: `docs/work-orders/`
- 개발 가이드: `docs/development-guides/`

## 단계별 갱신 원칙

- 각 단계 완료 후 `현재 단계`, `현재 상태`, `실행 주소`와 `검증 명령`을 실제 결과에 맞게 갱신합니다.
- 실행하지 않은 명령이나 확인하지 않은 결과를 완료로 기록하지 않습니다.
- 암호, API Key, Session ID와 기타 인증정보를 기록하지 않습니다.

README에 기록한 현재 단계와 실제 작업 지시서·저장소 상태가 다르면 다음 작업을 시작하기 전에 차이를 확인하고 바로잡습니다.

9.1.3 Admin Web UI 참고 화면과 공통 요구사항 기록

docs/requirements/admin-platform.md는 02~18단계에서 구현할 기능과 완료 조건을 정의하는 제품 요구사항 문서입니다. 작업 지시서가 현재 단계의 변경 범위를 정한다면, 이 문서는 전체 프로젝트가 최종적으로 도달해야 할 상태를 정합니다.

프로젝트 루트에서 파일을 만듭니다.

touch docs/requirements/admin-platform.md

다음 초기 내용을 작성합니다. 아직 구현하지 않은 기능은 요구사항으로만 기록하고 완료된 것으로 표시하지 않습니다.

# Admin Platform 요구사항

## 문서 목적

이 문서는 Vibe Coding Platform의 최종 기능, Architecture 경계와 완료 조건을 정의합니다. 각 단계의 작업 지시서는 이 요구사항을 현재 단계의 허용 범위로 나누어 구현합니다.

## 최종 목표

- Nginx, Node.js, Express, Vite, React, MySQL과 Redis로 구성한 Admin Web UI를 완성합니다.
- Admin Login, 서버 Session, 보호 Route, Dashboard와 Sidebar의 Text Tool을 구현합니다.
- 개발 환경과 Nginx 단일 진입점의 통합 환경을 분리합니다.
- 보안, 자동 Test, Release Gate, Backup, Restore, Log와 운영 확인 절차를 검증합니다.

## 사용자와 권한

- 비Login 사용자는 보호된 Admin 화면과 API에 접근할 수 없습니다.
- 활성화된 Admin User만 Admin Dashboard와 Text Tool을 사용할 수 있습니다.
- 일반 User와 비활성 User의 Admin 접근은 Backend에서 차단합니다.
- Frontend Route 검사는 사용성 보조 수단이며 Backend의 인증·권한 검사를 대신하지 않습니다.

## Login과 Session

- Login은 Email과 Password를 입력받습니다.
- Password는 평문으로 저장하지 않고 안전한 Hash로 비교합니다.
- Login 성공 후 Session ID를 재발급합니다.
- Session에는 필요한 최소 식별 정보만 저장합니다.
- Session Cookie에는 환경에 맞는 `HttpOnly`, `SameSite`와 `Secure` 정책을 적용합니다.
- Logout하면 서버 Session과 Browser Cookie를 제거합니다.
- Login 실패, Session 만료와 권한 부족 상태를 구분합니다.

## Admin Dashboard

- `/admin`은 Login과 Admin 권한이 필요한 보호 Route입니다.
- Dashboard는 Sidebar, Header와 본문 영역으로 구성합니다.
- Header에는 현재 Page 정보와 Login한 Admin 정보를 표시할 수 있습니다.
- Loading, 정상, 빈 결과와 오류 상태를 구분합니다.
- Keyboard Focus가 보이고 Mobile 화면에서도 주요 기능을 사용할 수 있어야 합니다.

## Sidebar와 Text Tool

- Sidebar에는 실제로 동작하는 메뉴만 표시합니다.
- 06단계에서는 Dashboard 메뉴를 제공하고, 07단계에서는 Text Tool을 추가합니다.
- Text Tool은 `/admin/text-tool` Route와 보호된 Backend Endpoint를 사용합니다.
- 메뉴 선택 상태는 현재 URL과 일치하고 새로고침 후에도 유지됩니다.
- Text Tool 입력은 Frontend와 Backend에서 각각 검증합니다.
- Logout은 Route 이동 메뉴가 아니라 Session을 종료하는 동작으로 구분합니다.

## 화면 구성 기준

- Desktop에서는 약 `240px`의 왼쪽 Sidebar와 오른쪽 작업 영역을 기본으로 합니다.
- 오른쪽 작업 영역은 Header와 현재 Route의 본문으로 구분합니다.
- Sidebar는 밝은 회색 계열을 기본으로 하고 현재 메뉴를 배경, 글자 굵기 또는 표식으로 구분합니다.
- 선 모양 아이콘은 일관된 크기와 굵기를 사용하고 Text 이름 또는 접근 가능한 이름을 제공합니다.
- 02단계의 시각적 원형, 06단계의 Dashboard 화면 구성과 07단계의 메뉴 데이터·상호작용 기준은 사용자의 명시적 지시 또는 요구사항 변경에 따라 조정할 수 있습니다.
- 변경한 화면 기준과 이유는 이 문서와 해당 단계의 작업 지시서에 기록합니다.

## Architecture 경계

- Frontend는 React, Vite와 TypeScript로 구성합니다.
- Backend는 Node.js, Express와 TypeScript로 구성합니다.
- Frontend에서 Database에 직접 연결하지 않습니다.
- Frontend의 API 요청은 고정 서버 IP 대신 `/api/` 상대 경로를 사용합니다.
- Backend는 Route, Controller, Service와 Repository 책임을 분리합니다.
- MySQL은 영구 User 데이터를 저장합니다.
- Redis는 Session Store로 사용합니다.
- Nginx는 React 정적 파일 제공과 `/api` 리버스 프록시를 담당합니다.

## 개발 및 통합 환경

- 02~07단계의 개발 환경은 Frontend `5173`을 기본 접속 포트로 사용합니다.
- Backend 개발 포트는 서버 내부 `127.0.0.1:3000`을 기본으로 합니다.
- MySQL과 Redis는 외부 네트워크에 직접 공개하지 않습니다.
- 08단계 이후 통합 환경은 Nginx `8080`을 단일 진입점으로 사용합니다.
- 개발과 통합 환경의 실행 명령, 환경변수와 Cookie 정책을 구분합니다.

## 보안과 Secret

- 실제 Password, Password Hash, API Key, Session ID, Cookie, Token과 Private Key를 Source, 문서, Screenshot과 Log에 기록하지 않습니다.
- Secret은 환경변수로 전달하고 `.env.example`에는 변수 이름과 안전한 예시만 기록합니다.
- Login 요청 제한, Security Header와 상태 변경 Request의 Origin 또는 CSRF 방어를 적용합니다.
- API Response와 Log에 내부 오류 상세와 민감정보를 포함하지 않습니다.
- 파괴 가능한 Database 작업은 Backup과 Restore 가능 여부를 확인한 뒤 사용자의 명시적 승인을 받아 수행합니다.

## 검증 기준

- 각 단계의 변경 전과 변경 후에 공통 WebUI Gate를 수행합니다.
- Typecheck, Lint, Unit Test, API Test, Frontend Test, Build와 Compose 검사를 현재 단계에 맞게 실행합니다.
- 자동 Test가 통과해도 Browser Console, Network, Keyboard와 Mobile 검증을 생략하지 않습니다.
- 실행하지 못한 검사는 통과로 기록하지 않고 `미수행`과 사유를 기록합니다.
- 이전 단계에서 완료한 Login, Session, Dashboard, Sidebar와 Text Tool을 이후 단계에서 회귀 검사합니다.

## 단계별 완료 조건

- 01단계: 개발 환경, Git, README, 요구사항, 작업 규칙과 Codex CLI 준비
- 02단계: Login 화면과 최소 Dashboard 시각적 원형
- 03단계: Express API와 Vite Proxy 연결
- 04단계: MySQL Admin User와 실제 Password 검증
- 05단계: 서버 Session과 보호된 Admin Route
- 06단계: 최소 Admin Dashboard 화면 구성
- 07단계: Sidebar의 Text Tool 기능
- 08단계: Docker Compose, Redis, Production Build와 Nginx 1차 통합
- 09단계: Architecture Gap과 변경 금지 기준선 확정
- 10단계: Backend 책임 분리와 공통 API 응답 형식
- 11단계: Runtime 입력값과 환경변수 검증
- 12단계: 기존 MySQL에 Prisma 적용과 Baseline
- 13단계: Redis Session Store 안정화
- 14단계: Docker Compose 개발·통합 환경 분리
- 15단계: Nginx 단일 진입점과 HTTPS 경계
- 16단계: Admin Login과 API 보안 강화
- 17단계: 자동 Test와 Release Gate
- 18단계: Backup, Restore, Log, Monitoring과 최종 Sidebar 확인

## 현재 구현 상태

- 현재 단계: 01단계
- 완료: 개발 환경과 프로젝트 기준 문서 준비
- 미구현: 02~18단계의 애플리케이션 기능과 운영 구성

## 변경 기록 원칙

- 요구사항을 변경할 때 변경한 내용, 이유와 적용 단계를 기록합니다.
- 해당 단계의 작업 지시서와 README도 같은 작업에서 갱신합니다.
- 직접 검증한 결과와 예정·미검증 내용을 구분합니다.

파일이 존재하고 비어 있지 않은지 확인합니다.

test -s docs/requirements/admin-platform.md && echo "admin-platform.md 준비 완료"

README.md의 기준 문서 목록과 02단계 정식 작업 지시서에서 이 경로를 정확히 사용합니다. 02단계를 시작하기 전에는 최소한 최종 목표, Login·권한 요구사항, 화면 구성, Architecture 경계와 단계별 완료 조건이 기록되어 있어야 합니다.

계획한 Admin Web UI는 Linear 스타일의 간결한 화면 구성을 기본 방향으로 삼습니다. Desktop에서는 약 240px의 왼쪽 Sidebar와 오른쪽 작업 영역으로 나누고, Sidebar 상단에는 회사 Logo를 둡니다. 오른쪽 작업 영역은 현재 Page 제목, Search와 사용자 영역을 배치할 수 있는 Header와 현재 Route의 본문 영역으로 구분합니다. Sidebar는 밝은 회색 계열을 기본으로 하고, 현재 메뉴만 배경, 글자 굵기 또는 표식으로 더 진하게 표시하며 아이콘은 Stroke와 크기가 일관된 단순한 선 모양을 사용합니다.

Dashboard 참고 목업(Mockup)을 서버 프로젝트에 저장

위 이미지의 원본 파일 admin-dashboard-reference-ui.webp는 02단계와 06단계의 화면 구성을 정하는 참고 목업입니다. 웹 브라우저에서 위 이미지를 마우스 오른쪽 버튼으로 선택한 뒤 이미지를 다른 이름으로 저장을 선택합니다. 파일명은 admin-dashboard-reference-ui.webp를 그대로 사용하고 Windows의 Downloads 폴더에 저장합니다. 화면을 다시 Capture하거나 파일명을 바꾸지 않습니다.

VS Code 원격 터미널에서 프로젝트 루트와 Attachments 폴더를 준비합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
mkdir -p Attachments

VS Code의 Explorer에서 새로 고침 아이콘을 선택해 Attachments 폴더가 표시되도록 한 뒤 다음 순서로 전송합니다.

1. Windows 파일 탐색기에서 Downloads 폴더를 엽니다.
2. admin-dashboard-reference-ui.webp 파일을 마우스로 선택한 채 버튼을 누르고 있습니다.

1. 파일을 VS Code 왼쪽 Explorer의 Attachments 폴더 위로 끌어옵니다.
2. Attachments 폴더가 강조되면 마우스 버튼을 놓습니다.

1. 로컬 Windows 파일이 SSH로 연결된 Ubuntu 서버의 Attachments 폴더로 복사될 때까지 기다립니다.
2. VS Code Explorer의 Attachments 폴더를 펼쳐 admin-dashboard-reference-ui.webp가 표시되는지 확인합니다.

끌어다 놓기가 동작하지 않으면 VS Code Explorer의 Attachments 폴더를 마우스 오른쪽 버튼으로 선택하고 Upload…을 선택한 뒤, Windows의 Downloads/admin-dashboard-reference-ui.webp를 열어 전송합니다.

대안: Windows PowerShell에서 scp로 전송

VS Code의 원격 터미널이 아니라 Windows의 PowerShell을 엽니다. PowerShell은 PS [Windows 사용자 폴더]>처럼 시작하며, 원격 터미널의 apple2ne1@project-dev-server:~$와 구분합니다.

PowerShell에서 다음 명령을 한 줄씩 실행합니다.

$sourceFile = Join-Path $env:USERPROFILE "Downloads\admin-dashboard-reference-ui.webp"
$remoteTarget = "apple2ne1@project-dev-server:projects/vibe-coding-platform/Attachments/"
Test-Path -LiteralPath $sourceFile
scp $sourceFile $remoteTarget

Test-Path의 결과가 True여야 합니다. scp가 완료되면 파일명과 100%가 표시됩니다. project-dev-server는 이 연재에서 이미 등록한 SSH Host 별칭이므로 서버-IP처럼 다시 바꿔 입력하지 않습니다.

전송이 끝나면 VS Code 원격 터미널에서 파일을 검사합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
test -s Attachments/admin-dashboard-reference-ui.webp \
  && echo "Dashboard 참고 목업 준비 완료" \
  || echo "파일이 없거나 비어 있습니다."
file Attachments/admin-dashboard-reference-ui.webp

Dashboard 참고 목업 준비 완료와 Web/P image가 표시되면 이후 작업 지시서가 같은 경로의 이미지를 사용할 수 있습니다. 파일이 없거나 비어 있습니다.가 표시되면 02단계로 넘어가지 않고 Windows 파일 탐색기의 끌어다 놓기 또는 VS Code Upload... 절차를 다시 실행합니다.

*Dashboard 화면 구성 은 실제로 작동하는 완성 화면이 아니라, 화면의 모양과 배치를 미리 보여주는 시안입니다.

선 모양 아이콘의 기본 Library로 Lucide Icons의 React 패키지인 lucide-react를 사용합니다. Lucide는 크기, 색상과 Stroke를 Props로 조정할 수 있고 사용하는 아이콘을 개별 Component로 Import할 수 있어 이 화면 방향에 적합합니다. 공식 License는 ISC License이며, License 고지 조건을 확인하고 프로젝트의 License 및 의존성 고지 방식에 맞게 보존합니다. 실제 설치는 Dashboard Component를 분리하는 06단계에서 한 번만 수행합니다.

┌──────────────┬───────────────────────────────┐
│ Logo         │ 상단 제목       Search  사용자  │
│              ├───────────────────────────────┤
│ Dashboard    │                               │
│ Users        │       현재 메뉴의 내용          │
│ Products     │                               │
│ Orders       │       카드 / 표 / 그래프        │
│ Reports      │                               │
│              │                               │
│ Settings     │                               │
│ Logout       │                               │
└──────────────┴───────────────────────────────┘

Dashboard, Users, Products, Orders, Reports, Settings와 Logout은 최종 메뉴 후보입니다. 01~18단계에서는 기존 학습 범위에 따라 실제로 완성된 메뉴만 표시하고, 동작하지 않는 메뉴 Placeholder를 한꺼번에 만들지 않습니다. Users부터 Settings까지는 각 기능의 Route, 권한, API와 검증 기준이 준비된 이후 별도 기능 작업에서 하나씩 추가합니다. Logout은 Route 메뉴가 아니라 Session을 종료하는 Action으로 구분합니다.

9.1.4 local-development.md가 필요한 이유와 최초 작성

docs/development-guides/local-development.md는 새 터미널이나 새로운 작업자가 같은 로컬 개발 환경을 다시 준비하고 실행할 수 있도록 설치 전제 조건, 실행 순서, 접속 주소와 확인 명령을 기록하는 문서입니다. README.md가 프로젝트 전체를 빠르게 소개한다면, local-development.md는 개발 환경을 실제로 재현하는 상세 절차를 제공합니다.

단계마다 관리할 파일과 갱신 시점

02~18단계에서는 다음 순서를 공통으로 적용합니다.

AGENTS.md는 매 단계의 진행 기록 파일이 아닙니다. 저장소 전체에 계속 적용할 작업 규칙이나 권한 기준이 실제로 변경될 때만 사용자 지시에 따라 갱신합니다. 요구사항과 작업 지시서가 일치하지 않으면 구현을 시작하지 않고 먼저 두 문서를 정리합니다.

문서별 역할은 다음과 같이 구분합니다.

이 파일은 02단계 작업 전에 실행 기준이 존재하도록 01단계에서 최초 작성하고, 실행 방법이나 Service 구성이 바뀌는 단계에서 누적 갱신합니다.

프로젝트 루트에서 파일을 만듭니다.

touch docs/development-guides/local-development.md

01단계에서는 다음 초기 내용을 작성합니다.

# 로컬 개발 가이드

## 문서 목적

이 문서는 `project-dev-server`에서 Vibe Coding Platform의 개발 환경을 준비하고 실행·검증하는 절차를 기록합니다. 확인하지 않은 명령이나 결과는 완료된 절차로 기록하지 않습니다.

## 현재 단계

01단계: VS Code 원격 서버에서 Vibe Coding 환경 준비와 Codex CLI 실행

## 개발 환경

- Windows 관리 PC의 VS Code
- VS Code Remote SSH
- Ubuntu Server의 `project-dev-server`
- 프로젝트 루트: `/home/apple2ne1/projects/vibe-coding-platform`
- Node.js와 npm은 `nvm`으로 사용자 환경에 설치
- 프로젝트 루트에서 Codex CLI 실행

실제 버전은 다음 명령으로 확인하고 검증 기록에 남깁니다.

```bash
node --version
npm --version
codex --version
```

## VS Code로 프로젝트 열기

1. Windows PC의 VS Code에서 `project-dev-server`에 Remote SSH로 접속합니다.
2. **Open Folder**에서 `/home/apple2ne1/projects/vibe-coding-platform`을 엽니다.
3. 새 터미널을 열고 현재 사용자, 호스트 이름과 경로를 확인합니다.

```bash
whoami
hostname
pwd
```

## 프로젝트 기본 확인

```bash
cd /home/apple2ne1/projects/vibe-coding-platform
git status --short
test -s README.md
test -s AGENTS.md
test -s docs/requirements/admin-platform.md
```

## Codex CLI 확인

```bash
codex --version
codex login status
```

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

```bash
cd /home/apple2ne1/projects/vibe-coding-platform
codex
```

## 실행 주소

현재 단계에서는 실행 가능한 Frontend와 Backend가 없습니다. 02단계부터 실제로 확인한 개발 주소와 실행 명령을 추가합니다.

## 중지 방법

현재 단계에는 중지할 애플리케이션 Service가 없습니다. 이후 단계에서 실행 명령을 추가할 때 대응하는 중지 방법도 함께 기록합니다.

## 보안 주의 사항

- 실제 Password, API Key, Token, Session ID와 Cookie를 이 문서에 기록하지 않습니다.
- `.env`의 실제 값을 붙여 넣지 않고 필요한 환경변수 이름만 기록합니다.
- 예시 IP 주소와 실제 접속 주소를 구분합니다.
- 실행하지 못한 검사는 통과로 기록하지 않고 `미수행`과 사유를 기록합니다.

## 단계별 갱신 원칙

- 실행 명령이 추가되면 실행 위치, 필요한 터미널 수, 접속 주소와 정상 결과를 함께 기록합니다.
- Service를 추가하면 실행·중지·재시작과 Log 확인 방법을 함께 기록합니다.
- 개발 환경과 통합 환경의 명령과 포트를 구분합니다.
- 명령이나 Port가 바뀌면 `README.md`, 관련 작업 지시서와 이 문서를 같은 작업에서 갱신합니다.

파일이 존재하고 비어 있지 않은지 확인합니다.

test -s docs/development-guides/local-development.md && echo "local-development.md 준비 완료"

01단계에서는 실행 가능한 애플리케이션이 아직 없으므로 존재하지 않는 실행 명령이나 접속 주소를 미리 완성된 값처럼 기록하지 않습니다. 각 후속 단계의 완료 확인표를 직접 검증한 뒤 실제로 성공한 절차만 이 문서에 추가합니다.

9.1.5 .env.example 최초 작성

.env.example은 프로젝트에 필요한 환경변수의 이름과 안전한 예시 형식을 공유하는 파일입니다. 실제 .env와 달리 Git에 포함하지만, 실제 암호, API Key, Token, 운영 도메인과 기타 인증정보는 기록하지 않습니다.

프로젝트 루트에서 파일을 만들고 편집기에서 엽니다.

touch .env.example

01단계에서는 아직 애플리케이션 환경변수가 정해지지 않았으므로 다음 주석을 최초 내용으로 작성합니다.

# Add variable names and safe example values when each service is introduced.
# Never store real passwords, tokens, API keys, or other secrets in this file.

04단계부터 실제 환경변수가 생기면 변수 이름과 안전한 예시값을 이 파일에 누적합니다. 실제 값을 저장하는 .env, .env.mysql과 backend/.env는 .gitignore로 제외하며, 예시 파일보다 먼저 Commit하지 않습니다.

파일이 비어 있지 않고 Git 제외 대상이 아닌지 확인합니다.

test -s .env.example && echo ".env.example 준비 완료"
git check-ignore -v --no-index .env.example

첫 명령은 완료 메시지를 출력해야 합니다. 두 번째 명령은 아무것도 출력하지 않고 종료 상태 1을 반환하는 것이 정상입니다.

9.1.6 compose.yaml 최소 구조 작성

compose.yaml은 Compose 프로젝트의 서비스를 선언하는 파일입니다. 01단계에서는 파일 존재 여부만 맞추기 위한 빈 파일을 만들지 않고, 프로젝트 이름과 빈 services 매핑을 가진 유효한 최소 구조로 시작합니다.

프로젝트 루트에서 파일을 만들고 편집기에서 엽니다.

touch compose.yaml

다음 내용을 작성합니다.

name: vibe-coding-platform

services: {}

name은 Compose 프로젝트 이름이고, services: {}는 아직 정의된 서비스가 없다는 뜻입니다. 따라서 이 파일은 01단계의 구조 확인용 기준 파일이며 애플리케이션을 실행하지 않습니다. 08단계에서 Frontend, Backend, MySQL과 Nginx의 실제 서비스 정의를 추가한 뒤 docker compose config로 병합 결과와 구문을 검증합니다.

01단계에서는 파일의 내용과 Git 상태를 확인합니다.

test -s compose.yaml && echo "compose.yaml 최소 구조 준비 완료"
grep -Fx "name: vibe-coding-platform" compose.yaml
grep -Fx "services: {}" compose.yaml
git status --short

두 grep 명령이 작성한 행을 각각 출력하는지 확인합니다. Docker Compose가 아직 설치되지 않았거나 실제 서비스가 정의되지 않은 상태에서는 실행 성공 여부를 검증한 것으로 기록하지 않습니다.

9.2 폴더별 최종 산출물

Prisma는 Backend Package와 함께 실행되므로 backend/prisma/에 둡니다. database/에는 Prisma와 중복되는 별도 Migration을 만들지 않고 초기 SQL과 운영 자료만 둡니다.

9.3 전체 단계 지도

각 단계는 이전 단계의 완료 확인표를 통과한 뒤 시작합니다. 오류가 남아 있으면 다음 기술을 추가하지 않고 현재 단계에서 원인을 해결합니다.

9.4 02~18 공통 WebUI Gate

모든 단계는 작업 전과 작업 후에 같은 WebUI Gate를 실행합니다. 아직 구현되지 않은 기능은 실패로 처리하지 않고 해당 없음과 사유를 기록합니다. 이전 단계에서 이미 구현된 기능은 다시 해당 없음으로 바꿀 수 없습니다.

단계별 적용 범위는 다음과 같습니다.

02~04  현재 구현된 Login과 API·Database 연결 항목 적용
05~06  Login, Session, 보호 Route와 Dashboard까지 적용
07~18  Dashboard와 Text Tool을 포함한 전체 Gate 적용

접속 주소는 02~07의 개발 확인에서는 5173, 8단계 이후 통합 확인에서는 8080을 기본으로 합니다. 14단계처럼 개발·통합 환경을 비교하는 단계는 두 주소에서 모두 실행합니다.

결과는 docs/development-guides/webui-gate.md에 단계별로 누적합니다. 01단계에서 다음 명령으로 파일을 만들어 저장하거나 VS Code Explorer 파일을 생성해서 만듭니다.

mkdir -p docs/development-guides
touch docs/development-guides/webui-gate.md

파일을 열어 다음 초기 내용을 저장합니다.

# WebUI Gate 검증 기록

각 단계의 변경 전·후 웹 브라우저 검증 결과를 누적하여 기록한다.

실행하지 않은 검사는 통과로 기록하지 않는다. 아직 구현되지 않은 기능은 `해당 없음`으로 기록하고 사유를 함께 남긴다.

## 01단계: 개발 환경 준비

### 변경 후 검증

단계: 01단계
검증 주소: 해당 없음
웹 브라우저와 Viewport: 미수행—실행 가능한 Frontend 없음
통과 항목: 프로젝트 기본 폴더와 기준 문서 준비 확인
해당 없음 항목과 사유: WebUI 전체—01단계에는 실행 가능한 Frontend가 없음
Console 결과: 미수행—실행 가능한 Frontend 없음
Network 결과: 미수행—실행 가능한 Frontend 없음
실패 항목과 수정 내용: 없음
최종 판정: 01단계 준비 완료, 02단계 Frontend 구현 진행 가능

위 초기 내용은 이 문서에서 제공한 01단계 파일을 그대로 저장한 상태를 기준으로 합니다. 다음 자동 검사로 필수 파일과 Compose 문법을 확인합니다.

for file in \
  .env.example \
  compose.yaml \
  README.md \
  docs/requirements/admin-platform.md \
  docs/development-guides/local-development.md \
  docs/development-guides/webui-gate.md \
  Attachments/admin-dashboard-reference-ui.webp
do
  test -s "$file" || { echo "누락 또는 빈 파일: $file"; exit 1; }
done
docker compose config --quiet
echo "01단계 자동 검사 완료"

01단계 자동 검사 완료가 출력되지 않으면 커밋하지 않고 표시된 누락 파일이나 Compose 오류를 Codex에 전달해 수정을 요청합니다.

자동 검사가 끝나면 현재 프로젝트의 변경 파일을 모두 스테이징하고 커밋 대상 목록을 확인합니다.

git add .
git diff --cached --name-only
git diff --cached --check
git commit -m "chore: complete 01 step baseline"
git status --short

스테이징 목록에 예상하지 못한 파일이 표시되거나 자동 검사가 실패하면 커밋하지 않고 Codex에 출력 결과를 전달해 수정을 요청합니다.

02단계부터는 각 단계의 변경 전·후 검증 결과를 같은 파일에 다음 항목으로 누적합니다.

단계:
검증 주소:
웹 브라우저와 Viewport:
통과 항목:
해당 없음 항목과 사유:
Console 결과:
Network 결과:
실패 항목과 수정 내용:
최종 판정:

공통 Gate가 실패하면 다음 단계로 이동하지 않습니다. 자동 Test가 통과했더라도 실제 Browser Gate를 생략하지 않습니다.

10. AGENTS.md로 작업 규칙 전달

Codex는 프로젝트에서 발견한 AGENTS.md를 읽어 작업 규칙으로 사용합니다. 프로젝트 전체에 적용할 규칙은 루트의 AGENTS.md에 작성합니다.

처음 시작할 때 Codex의 /init 명령으로 초안을 만들 수 있지만, 생성된 내용은 반드시 프로젝트 목적에 맞게 검토합니다.

프로젝트 루트에서 AGENTS.md를 만들고 편집기에서 엽니다.

다음 예시는 02~18단계 전체에 적용하는 루트 AGENTS.md입니다. 각 단계의 작업 지시서는 현재 단계의 변경 범위를 정하고, 루트 AGENTS.md는 모든 단계에서 지켜야 하는 상위 통제 규칙을 정합니다.

# 프로젝트 작업 규칙

## 최종 목표

- Nginx, Node.js, Express, Vite, React, MySQL과 Redis로 구성된 Admin Web UI를 완성한다.
- Admin Login, Session, 보호 Route, Dashboard와 Sidebar의 Text Tool을 구현한다.
- Admin Web UI는 `docs/requirements/admin-platform.md`에 기록한 참고 화면, 화면 구성, 색상과 메뉴 상호작용 기준을 단계별로 적용한다.
- 개발 환경과 Nginx 단일 진입점의 통합 환경을 분리한다.
- 보안, 자동 Test, Release Gate, Backup, Restore, Log와 운영 확인 절차까지 검증한다.

## 기준 문서와 우선순위

- 작업 전에 루트 `AGENTS.md`와 현재 단계의 `docs/work-orders/NN-*.md`를 읽는다.
- 제품 완료 조건은 `docs/requirements/admin-platform.md`를 기준으로 한다.
- 실행과 검증 방법은 `docs/development-guides/`를 기준으로 한다.
- 현재 작업 지시서는 이번 단계의 허용 범위와 제외 범위를 정한다.
- 루트 `AGENTS.md`만으로 현재 단계를 판단하지 않는다. 현재 작업 지시서, 이전 단계의 완료 기록과 저장소 상태를 함께 확인한다.
- 현재 단계를 확인할 수 없거나 서로 다른 단계의 기록과 저장소 상태가 충돌하면 작업을 시작하지 않고 확인 결과를 보고한다.
- 문서끼리 충돌하거나 현재 단계가 불명확하면 임의로 해석하지 말고 작업을 중단하여 보고한다.

## 고정 프로젝트 구조

- `frontend/`: React, Vite, TypeScript Source와 Test
- `backend/`: Node.js, Express, TypeScript API, Prisma와 Test
- `backend/prisma/`: Prisma Schema와 Migration
- `database/`: MySQL 초기 SQL, Schema 자료와 Backup·Restore 절차
- `nginx/`: Nginx 설정과 HTTPS 경계
- `docker/`: Dockerfile과 환경별 Compose Override
- `scripts/`: Release Gate, Backup·Restore와 운영 확인 Script
- `docs/`: 요구사항, 단계별 작업 지시서와 개발 가이드
- 역할이 같은 새 최상위 폴더를 만들지 않는다.
- Prisma Migration을 `database/`에 복제하지 않는다.

## 단계와 변경 범위 통제

- 02단계부터 18단계까지 번호 순서대로 진행한다.
- 이전 단계의 완료 확인표와 공통 WebUI Gate가 통과된 경우에만 다음 단계를 시작한다.
- 현재 작업 지시서에 포함된 기능과 파일만 변경하고 이후 단계의 기술을 미리 추가하지 않는다.
- 이전 단계에서 완료한 Login, Session, Dashboard, Sidebar와 Text Tool 동작을 보존한다.
- 02단계에서는 시각적 원형, 06단계에서는 보호된 Dashboard 화면 구성, 07단계에서는 실제 메뉴 데이터와 상호작용을 완성하며 이후 단계에서는 회귀 검사를 통과시킨다.
- 02단계의 시각적 원형, 06단계의 보호된 Dashboard 화면 구성과 07단계의 메뉴 데이터·상호작용 기준은 사용자의 명시적 지시 또는 요구사항 변경에 따라 변경할 수 있다. 변경한 기준과 이유는 요구사항 및 해당 작업 지시서에 기록한다.
- 변경 전에 현재 구조, 변경 예정 파일과 검증 명령을 먼저 보고한다.
- 관련 없는 Refactor, Package 교체와 화면 재설계를 함께 수행하지 않는다.
- 기존 파일과 사용자 변경을 보존한다.
- 삭제, 대규모 이동 또는 호환성이 깨지는 변경은 명시적인 승인을 받은 뒤 수행한다.

## Architecture 경계

- Frontend, Backend, Database, Nginx와 Docker의 책임을 분리한다.
- Frontend에서 Database에 직접 연결하지 않는다.
- Frontend Route 검사를 Backend의 인증·권한 검사 대신 사용하지 않는다.
- Frontend의 API 요청에는 고정 Server IP를 작성하지 않고 `/api/` 상대 경로를 사용한다.
- 10단계부터 Route, Controller, Service와 Repository 책임을 분리한다.
- 11단계부터 Browser 입력을 Runtime Schema로 검증한다.
- API Contract를 변경하면 Frontend, Backend Test와 관련 문서를 함께 갱신한다.

## Secret과 보안 규칙

- Secret은 환경 변수로 전달하고 `.env.example`에는 이름과 안전한 예시만 기록한다.
- `.env`, 인증정보, Password, Password Hash, Session ID, Cookie 값과 Redis Key를 Git, Source, 문서, Screenshot과 Log에 기록하지 않는다.
- Password Hash와 내부 오류 상세를 API Response에 포함하지 않는다.
- MySQL과 Redis 포트를 외부에 공개하지 않는다.
- Admin 권한은 Backend에서 확인한다.
- 보안 오류를 숨기기 위해 인증, Origin 검사, 요청 제한이나 Cookie 보호를 통째로 비활성화하지 않는다.

## Database와 파괴적 작업 통제

- 기존 MySQL Schema나 데이터를 변경하기 전에 Backup과 Restore 가능 여부를 확인한다.
- 기존 Database에 Migration을 적용하기 전에 현재 Schema와 Baseline을 확인한다.
- 기존 데이터가 있는 환경에서 Database Reset, `prisma migrate reset`과 무분별한 `prisma db push`를 실행하지 않는다.
- 대체 구현의 Test와 회귀 검사가 통과하기 전에 기존 Repository를 삭제하지 않는다.
- 일반 검증 과정에서 Docker Volume을 삭제하거나 초기화하지 않는다.
- 파괴 가능성이 있는 명령은 대상과 복구 방법을 보고하고 명시적인 승인을 받는다.

## 공통 WebUI Gate

- 모든 단계에서 변경 전과 변경 후에 `docs/development-guides/webui-gate.md`의 공통 WebUI Gate를 실행한다.
- 02~07단계는 `5173`, 08단계 이후 통합 확인은 `8080`을 기본으로 한다.
- 개발·통합 환경을 비교하는 단계는 두 주소에서 모두 확인한다.
- 아직 구현되지 않은 항목만 `해당 없음`으로 기록하고 사유를 남긴다.
- 이전 단계에서 구현한 항목을 다시 `해당 없음`으로 바꾸지 않는다.
- Browser Console, Network, Keyboard 조작과 지정한 Mobile 폭을 확인한다.
- 자동 Test가 통과해도 Browser 검증을 생략하지 않는다.
- 기존 환경이 실행되지 않아 변경 전 WebUI Gate를 수행할 수 없으면 이를 통과로 기록하지 않고 `미수행`으로 기록한다.
- 실행을 막은 선행 장애, 확인한 범위와 미검증 사유를 기록하고 장애가 해결된 뒤 WebUI Gate를 다시 수행한다.
- Gate가 실패하면 다음 단계로 이동하지 않고 현재 단계에서 원인을 수정한다.

## Test와 완료 판정

- 현재 단계에 해당하는 Typecheck, Lint, Unit Test, API Test, Frontend Test, Build와 Compose 검사를 실행한다.
- 실패한 검사를 삭제하거나 건너뛰거나 기준을 낮춰 통과시키지 않는다.
- 실행하지 못한 검사는 통과로 기록하지 않고 미검증 사유를 적는다.
- 실제 Certificate와 Domain을 확인하지 않았다면 HTTPS 완료로 기록하지 않는다.
- 완료 시 변경 파일, 실행 명령, Test 결과, WebUI Gate 결과와 남은 위험을 보고한다.
- 직접 확인한 결과와 추정 또는 미검증 내용을 구분한다.
- 동작이 바뀌면 관련 요구사항, 작업 지시서와 개발 가이드를 함께 갱신한다.

/Vibe-coding-platform/agnets.md 를 위 내용을 copy 하여 작성합니다.

이 예시는 최종 목표와 공통 제한을 정하지만 한 번에 18단계를 모두 구현하라는 뜻은 아닙니다. 실제 변경 범위는 항상 현재 단계의 작업 지시서가 더 좁게 제한합니다.

특정 하위 폴더에만 필요한 규칙이 많아지면 frontend/AGENTS.md 또는 backend/AGENTS.md를 추가할 수 있습니다. 하위 규칙은 루트 규칙을 완화하거나 무효화하지 않고 해당 폴더의 세부 기준만 추가해야 합니다.

10.1 Codex가 AGENTS.md를 찾는지 확인

AGENTS.md를 저장한 뒤 Codex CLI에 첫 검토를 요청합니다.

AGENTS.md를 읽고 검토해.

화면 예시에는 AI 코딩 에이전트에게 파일명 수정 명령을 전달하는 과정을 보여 주기 위해 소문자 agents.md를 입력했지만, 실제 요청에서는 Linux의 대소문자 구분에 맞춰 AGENTS.md를 사용합니다.

Codex가 현재 경로와 AGENTS.md 파일을 찾기 위한 읽기 전용 명령의 실행 승인을 요청할 수 있습니다. 표시된 명령과 검색 범위가 현재 프로젝트 안인지 확인한 뒤 Yes, proceed를 선택합니다.

Codex의 응답에서 루트 agents.md의 위치와 핵심 규칙을 올바르게 읽었는지 확인합니다. 파일을 찾지 못했다면 프로젝트 루트에 있는지와 파일명의 대소문자를 다시 확인합니다. 이후에도 승인 화면이 표시되면 명령, 실행 이유와 대상 범위를 확인한 뒤 허용 여부를 결정하면서 Vibe Coding을 진행합니다.

실수로 소문자 agents.md를 만들었다는 지적이 나오면 Codex CLI에 다음과 같이 파일명 변경을 요청합니다.

agents.md를 AGENTS.md로 수정해.

Codex의 완료 보고에서 파일 내용은 유지되고, 기존 소문자 파일이 남아 있지 않으며, 새 파일을 읽을 수 있는지 확인합니다.

마지막으로 VS Code Explorer와 편집기 탭에서 파일명이 정확히 AGENTS.md인지 확인합니다.

11. 다음 단계 작업 방식

01단계에서는 프로젝트 구조, 공통 요구사항, 루트 AGENTS.md, 개발 가이드와 공통 WebUI Gate까지 준비합니다. 02단계부터는 각 단계 문서의 학습용 간단한 지시 설명서로 목적과 제한을 이해한 뒤, 같은 문서의 정식 작업 지시서를 docs/work-orders/NN-*.md에 저장하여 유일한 구현 기준으로 사용합니다.

단계별 정식 작업 지시서의 저장, Git 기준점 생성, Codex CLI 실행, 공통 Prompt 전달, 검증, 문서 갱신과 최종 Commit 순서는 02-vibe-coding-login-admin-dashboard-ui-ko부터 각 단계 문서에 같은 형식으로 안내합니다. 비전공자가 구현 결과를 먼저 확인할 수 있도록 각 단계에서는 작업 지시서 실행 절차 다음에 구현 결과 실행과 WebUI 검토를 배치합니다. 화면과 기능을 확인한 뒤 검증 결과와 단계별 문서를 갱신하고, 모든 필수 검사가 통과한 경우에만 최종 변경을 검토하여 Commit합니다. 그다음 정식 작업 지시서 해설에서 구현 원리와 세부 기준을 학습합니다. 단계별 조건을 긴 Prompt로 다시 복제하지 않고, Codex CLI에는 루트 AGENTS.md, 전체 요구사항과 현재 작업 지시서를 읽도록 요청합니다.

12. 완료 확인표

• [ ] VS Code가 project-dev-server에 Remote SSH로 연결되었다.
• [ ] 터미널의 whoami, hostname, pwd 결과를 확인했다.
• [ ] VS Code에서 vibe-coding-platform 폴더를 열었다.
• [ ] 프로젝트 루트에 Git 저장소와 .gitignore가 준비되었다.
• [ ] 권장 최상위 폴더와 기본 파일을 만들었다.
• [ ] .env.example에 보안 주석을 기록하고 Git 제외 대상이 아닌지 확인했다.
• [ ] compose.yaml에 프로젝트 이름과 빈 services 매핑을 기록했다.
• [ ] docs/requirements/admin-platform.md에 최종 기능과 완료 조건을 기록했다.
• [ ] docs/work-orders에 단계별 작업 지시서를 저장할 규칙을 정했다.
• [ ] docs/development-guides/webui-gate.md에 공통 Gate 기록 양식을 준비했다.
• [ ] command -v bwrap, bwrap --version과 기본 샌드박스 검사가 정상이다.
• [ ] codex --version과 command -v codex가 정상 출력된다.
• [ ] codex login status로 로그인 상태를 확인했다.
• [ ] 프로젝트 루트에 AGENTS.md를 작성했다.
• [ ] 02~18단계에서 정식 작업 지시서를 저장할 공통 규칙을 확인했다.
• [ ] 프로젝트 루트 또는 codex -C로 Codex CLI를 실행할 위치를 확인했다.
• [ ] 다음 단계에서 변경 파일과 검증 결과를 Git으로 확인할 준비가 되었다.

13. 자주 발생하는 문제

codex: command not found

다음 항목을 차례로 확인합니다.

node --version
npm --version
npm config get prefix
command -v codex

설치했지만 찾지 못한다면 npm 전역 실행 경로가 PATH에 포함되어 있는지 확인합니다. 원인을 확인하지 않은 채 여러 설치 방법을 반복하지 않습니다.

로그인할 브라우저가 열리지 않음

원격 서버에서는 Device Code 방식을 사용합니다.

codex login --device-auth

Windows 브라우저에서 터미널의 안내에 따라 인증합니다.

Codex가 다른 폴더를 수정하려고 함

현재 위치를 확인하고 프로젝트 경로를 명시해 다시 실행합니다.

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

AGENTS.md 규칙이 적용되지 않는 것 같음

다음을 확인합니다.

• 파일명이 정확히 AGENTS.md인가
• 프로젝트 루트 또는 현재 작업 범위의 상위 폴더에 있는가
• 서로 다른 위치의 AGENTS.md 규칙이 충돌하지 않는가
• Prompt가 AGENTS.md의 금지 사항과 모순되지 않는가

기존 파일까지 많이 변경됨

작업을 중단하고 git diff로 범위를 확인합니다. 사용자 변경을 보존한 채, 더 작은 작업 지시서와 명확한 제외 범위로 다시 요청합니다. 확인 없이 git reset --hard나 파일 삭제 명령을 사용하지 않습니다.

14. Codex CLI를 사용하지 않는 선택지

같은 Vibe Coding 작업을 반드시 터미널에서만 해야 하는 것은 아닙니다.

• VS Code용 Codex 기능: Editor 안에서 파일과 변경 내용을 함께 검토
• Codex Desktop 또는 Web 환경: 작업을 분리하여 위임하고 결과를 검토
• 다른 AI Coding Agent: 프로젝트 규칙, 승인 범위와 검증 절차를 동일하게 적용
• 일반 ChatGPT 대화: 요구 사항, 작업 지시서와 오류 원인을 정리한 뒤 코드 작업에 활용

이 문서에서는 Linux 서버의 프로젝트 루트와 실제 실행 환경을 가장 직접적으로 이해할 수 있도록 Codex CLI를 기준으로 설명합니다.

15. 다음 단계

환경과 프로젝트 골격 준비가 끝나면 Frontend 화면부터 작게 구현합니다.

첫 단계의 목표는 브라우저에서 Vite 개발 서버의 5173번 포트에 접속해 Login 화면을 보고, 임시 Frontend 인증을 통과하면 Admin Dashboard로 전환되는 흐름을 만드는 것입니다.

02단계부터는 01단계에서 만든 최상위 구조를 유지합니다. Backend, MySQL, Redis, Nginx와 Docker Compose는 Login과 Dashboard 화면 흐름을 확인한 뒤 정해진 폴더에 단계별로 연결합니다.

다음 문서: 2단계: Login과 Admin Dashboard 화면 먼저 만들기

참고 자료 및 출처

• OpenAI, Codex Authentication: 로그인 방식, Device Code 인증과 인증정보 보관 원칙을 확인했습니다. 확인일: 2026-08-04
• OpenAI, AGENTS.md: 프로젝트 지침 파일의 탐색과 적용 방식을 확인했습니다. 확인일: 2026-08-04
• OpenAI, Codex Configuration: 사용자 및 프로젝트 설정 파일의 기본 위치와 적용 범위를 확인했습니다. 확인일: 2026-08-04
• OpenAI, Codex CLI 명령 참고: Codex CLI 0.146.0에서 -C, --sandbox, --ask-for-approval, login과 exec 옵션을 확인했습니다. 확인일: 2026-08-04
• Node.js, Download Node.js: Node.js LTS 배포 정보를 확인했습니다. 확인일: 2026-08-04
• nvm-sh, nvm: 설치 스크립트, 셸 설정 반영과 nvm install --lts 사용법을 확인했습니다. v0.40.5 설치는 작성자의 검증 환경에서 직접 수행했습니다. 확인일: 2026-08-04

관련 문서

• 02-vibe-coding-login-admin-dashboard-ui-ko
• 03-vibe-coding-express-api-connection-ko
• 04-vibe-coding-mysql-admin-account-ko