핵심 요약
첫 메뉴는 외부 AI, WordPress나 이미지 생성 서비스를 연결하지 않습니다. 입력과 결과가 명확한 Text Tool 하나를 추가하여 Dashboard 기능 확장 방법을 학습합니다.
Sidebar에서 Text Tool 선택
↓
문장 입력
↓
POST /api/admin/tools/text-summary
↓
백엔드에서 공백 정리와 글자 수 계산
↓
WebUI에 결과 표시작은 기능 하나를 요구하고, 변경 파일을 검토하고, 웹 브라우저에서 검증하는 Vibe Coding 반복 과정을 만드는 것이 목표입니다.
이번 단계의 Vibe Coding 작업 지시서
학습용 간단한 지시 설명서
06단계 `Dashboard`에 실제 동작하는 `Text Tool` 메뉴 하나만 추가해 줘.
/admin/text-tool과 requireAdmin이 적용된 POST /api/admin/tools/text-summary를 구현해 줘.
1~2,000자 입력의 공백을 정리하고 글자 수와 단어 수를 반환하며 UI에 처리 중, 성공과 오류 상태를 표시해 줘.
외부 AI API, 데이터베이스 저장, 새 패키지와 다른 메뉴는 추가하지 마.
변경 전·후 Gate와 API 200, 400, 401, 403 및 웹 브라우저 결과를 보고해 줘.정식 작업 지시서
다음 코드 블록 전체가 07단계 구현의 유일한 정식 작업 지시서입니다. 내용을 줄이거나 별도의 상세 프롬프트로 복제하지 않고 docs/work-orders/07-first-sidebar-menu.md에 저장합니다.
# 07단계 정식 작업 지시서
## 단계별 상세 지시
루트 AGENTS.md, 요구사항과 docs/work-orders/07-first-sidebar-menu.md를 먼저 읽어 줘.
06단계 로그인, 세션, `Dashboard`와 공통 WebUI Gate가 통과했는지 확인한다.
허용 범위는 Text Tool에 필요한 frontend/와 backend/이다.
기존 인증, `Dashboard`와 API 계약을 관련 없이 변경하지 않는다.
변경 전에 경로, API 입력·응답 계약, 변경 파일과 검증 명령을 보고한다.
`Sidebar`에 `Text Tool` 메뉴 하나를 추가하고 경로는 `/admin/text-tool`로 만든다.
메뉴 항목은 고유 ID, 이름, 아이콘, 경로와 필요한 접근 조건을 한 데이터 구조에서 관리한다.
현재 경로와 메뉴 선택 상태를 일치시키고 새로고침 후에도 URL을 기준으로 복원한다.
키보드 탐색과 모바일 메뉴 열기·닫기를 유지하며 메뉴 선택 후 공통 `AdminLayout`의 본문 영역에 `Text Tool` 페이지를 표시한다.
이번 단계에서는 하위 메뉴를 만들지 않지만 이후 펼침·접힘 구조를 추가할 수 있는 데이터와 컴포넌트 경계를 유지한다.
`docs/requirements/admin-platform.md`와 `Attachments/admin-dashboard-reference-ui.webp`의 화면 구성 방향을 06단계 구현 결과에 맞게 이어받는다.
**이 항목은 작성자의 구현 의도에 맞게 변경 가능하다.** 메뉴 필드와 상호작용을 바꾸면 경로, 접근성 속성과 검증 기준도 함께 갱신한다.
보호 API POST /api/admin/tools/text-summary에 requireAdmin을 적용한다.
입력은 1자 이상 2,000자 이하의 문자열만 허용한다.
백엔드에서 연속 공백을 하나로 정리하고 정리된 텍스트, 글자 수와 단어 수를 반환한다.
프런트엔드에는 입력, 실행 버튼, 처리 중, 성공과 오류 상태를 구현한다.
중복 제출과 빈 입력을 안전하게 처리한다.
외부 AI API, WordPress, 이미지 생성 서비스, 데이터베이스 저장, 새 패키지와 두 번째 메뉴를 추가하지 않는다.
로그인, 세션, `Dashboard`와 **Logout**을 변경하지 않는다.
변경 전·후 전체 공통 WebUI Gate를 실행한다.
백엔드 typecheck, 프런트엔드 build, API 200, 400, 401, 403과 웹 브라우저의 `Text Tool` 실행을 검증한다.
새로고침, `Sidebar` 선택 상태, 키보드와 모바일 폭도 확인한다.
검사 결과는 완료 보고에 통과, 실패와 미수행으로 구분한다. 검증 기록 문서 갱신은 사용자가 WebUI 확인을 마친 뒤 별도 프롬프트로 수행하므로 이 작업에서는 실행하지 않는다.
기존 기능 회귀나 Gate 실패가 남으면 08단계 통합을 시작하지 않는다.
## 완료 보고 형식
- 생성하거나 변경한 파일
- 실행한 명령과 실제 결과
- 통과, 실패와 미수행 검증
- 요구사항별 구현 내용과 변경 이유
- 남은 제한, 위험과 다음 단계 진행 가능 여부정식 작업 지시서 저장과 실행 순서
다음 순서는 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/07-first-sidebar-menu.md를 만들고, 위 정식 작업 지시서 코드 블록의 내용을 빠짐없이 저장합니다. 간단한 지시서와 정식 작업 지시서를 서로 다른 실행 프롬프트로 보내지 않습니다.
mkdir -p docs/work-orders
touch docs/work-orders/07-first-sidebar-menu.md
VS Code의 Explorer에서 docs/work-orders/07-first-sidebar-menu.md를 선택해 열고, 위 정식 작업 지시서 코드 블록 전체를 복사해 붙여넣은 뒤 Ctrl+S로 저장합니다.
저장한 다음 VS Code 원격 터미널에서 파일 내용과 변경 사항을 확인합니다.
test -s docs/work-orders/07-first-sidebar-menu.md
git diff -- docs/work-orders/07-first-sidebar-menu.md
저장한 파일에 목표, 허용 범위, 제외 범위, 완료 조건, 검증과 중단 조건이 모두 포함되어 있는지 직접 확인합니다.
3. 작업 지시서 Git 기준점 기록
위 정식 작업 지시서 코드 블록 전체를 지정한 파일에 저장한 뒤, 해당 파일만 먼저 커밋하여 구현 기준을 고정합니다.
cd /home/apple2ne1/projects/vibe-coding-platform
git status --short
test -s docs/work-orders/07-first-sidebar-menu.md
git add -- docs/work-orders/07-first-sidebar-menu.md
git diff --cached --name-only
git diff --cached --check
git commit -m "docs: add 07 step work order"
스테이징 파일 목록에 docs/work-orders/07-first-sidebar-menu.md 하나만 표시되고 git diff --cached --check가 오류 없이 종료되면 기준점 커밋을 진행합니다. 다른 파일이 표시되거나 검사가 실패하면 커밋하지 않고 Codex에 표시된 파일과 오류를 전달해 수정을 요청합니다.
4. Codex CLI 실행과 공통 프롬프트 전달
프로젝트 루트에서 Codex CLI를 실행합니다.
codex -C /home/apple2ne1/projects/vibe-coding-platformCodex CLI에 단계별 구현 조건을 다시 길게 복사하지 않고 다음 공통 프롬프트를 전달합니다. 선행 조건이나 기록이 맞지 않아도 사용자가 원인을 직접 판정하지 않습니다. Codex가 안전하게 해결할 수 있는 문제는 기존 작업을 보존하면서 바로잡고 다시 검사합니다.
루트 AGENTS.md, docs/requirements/admin-platform.md와
docs/work-orders/07-first-sidebar-menu.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 확인처럼
사용자 결정이나 조작이 꼭 필요한 일은 임의로 진행하지 마.
그 경우에는 사용자가 해야 할 행동 한 가지만 쉬운 문장으로 설명하고, 복사할 명령이 있으면 코드 블록 하나로 제공한 뒤 결과를 기다려 줘.
선행 조건이 해결되면 별도의 재요청을 기다리지 말고 정식 작업 지시서의 허용 범위만 구현해 줘.
제외 범위와 다음 단계 기능은 추가하지 마.
실행하지 못한 검사는 통과로 기록하지 말고 필수 검사 실패를 완료로 판정하지 마.
자동 검사가 끝나면 사용자가 직접 확인해야 할 WebUI 또는 대체 검사만 번호가 있는 짧은 목록으로 안내해 줘.
검증 결과 기록, 스테이징과 커밋은 사용자가 실제 확인을 마친 뒤 별도 프롬프트로 요청할 것이므로 지금 실행하지 마.
마지막에는 비전공자도 이해할 수 있게 다음 내용만 보고해 줘.
1. 자동으로 해결한 문제
2. 구현한 내용과 변경 파일
3. 통과·실패·미수행 검사
4. 사용자가 지금 확인할 항목
5. 다음 절차 진행 가능 여부코드 블록 전체를 Codex CLI에 붙여 넣고 Enter를 누릅니다. 다음 화면처럼 현재 단계와 자동 검사, 사용자 확인 항목 및 위험 조건을 확인하는 공통 프롬프트가 전달되었는지 확인합니다.
Codex의 완료 보고에서 구현과 자동 검사가 끝났는지, 사용자가 직접 확인할 WebUI 항목과 다음 절차 진행 가능 여부가 구분되어 있는지 확인합니다.
5. Codex의 자동 확인·복구 후 구현
위 프롬프트는 사전 확인에서 안전하게 해결할 수 있는 문제를 발견하면 Codex가 기존 작업을 보존하면서 직접 복구하고 다시 검사한 뒤 구현을 계속하도록 요청합니다. 사용자는 Git 상태, 문서 간 단계 충돌과 명령 오류를 직접 판정하지 않습니다.
Codex가 사용자 조작이 필요한 문제를 발견하면 한 번에 한 가지 행동만 안내합니다. 안내된 명령이나 WebUI 확인을 수행한 뒤 결과 전체를 같은 Codex CLI 대화에 붙여 넣습니다. Codex가 다음 절차 진행 가능이라고 보고하면 아래 구현 결과 확인으로 이동합니다. 진행 불가라고 보고하면 임의로 다음 단계로 넘어가지 않고, 마지막 보고 전체를 그대로 Codex에 다시 전달하여 해결을 계속 요청합니다.
구현 결과 WebUI 실행과 확인
07단계는 06단계의 관리자 화면에 Text Tool 메뉴와 보호 API를 추가합니다. 서비스 준비 → 백엔드·프런트엔드 실행 → 로그인과 메뉴 확인 → 정상·오류 입력 확인 → 새로고침·모바일·키보드 확인 → 인증 회귀 확인 → 프로세스 중지 순서로 진행합니다.
WebUI가 열리지 않거나 기능이 동작하지 않으면 자동 검사 결과만으로 완료 처리하지 않습니다. 백엔드와 프런트엔드 터미널의 오류 및 웹 브라우저 개발자 도구의 Console·Network 결과를 Codex에 전달하여 해결합니다. 실제 암호, SESSION_SECRET, 운영 환경의 세션 ID와 쿠키 값은 전달하지 않습니다.
1. MySQL과 환경 변수 준비 상태 확인
프로젝트 루트에서 MySQL을 다시 시작하고 SESSION_SECRET 저장 여부를 확인합니다. 다음 명령은 SESSION_SECRET의 실제 값을 출력하지 않습니다.
cd /home/apple2ne1/projects/vibe-coding-platform
docker compose up -d mysql
docker compose ps mysql
grep -q '^SESSION_SECRET=.' backend/.env && echo "SESSION_SECRET 저장 확인 완료" || echo "SESSION_SECRET 확인 필요"
MySQL 상태가 healthy이고 SESSION_SECRET 저장 확인 완료가 표시되어야 합니다. MySQL이 starting이면 잠시 기다린 뒤 docker compose ps mysql을 다시 실행합니다. unhealthy, exited 또는 SESSION_SECRET 확인 필요가 표시되면 다음 단계로 넘어가지 않고 출력 결과를 Codex에 전달합니다.
2. 백엔드와 프런트엔드 실행
VS Code에서 터미널을 두 개 열고 각각 다음 명령을 실행합니다.
# 터미널 1: 백엔드
cd /home/apple2ne1/projects/vibe-coding-platform/backend
npm run dev
# 터미널 2: 프런트엔드
cd /home/apple2ne1/projects/vibe-coding-platform/frontend
npm run dev
백엔드 터미널에 Backend listening on http://127.0.0.1:3000이 표시되고, 프런트엔드 터미널에 http://서버-IP:5173 형식의 Vite 접속 주소가 표시되어야 합니다. 오류가 나타나면 WebUI 확인을 시작하지 않고 인증정보를 제외한 오류 출력을 Codex에 전달합니다.
3. 로그인과 Text Tool 메뉴 확인
Windows 관리 PC의 웹 브라우저에서 http://서버-IP:5173을 엽니다. 이 연재의 검증 환경에서는 http://192.168.1.231:5173을 사용합니다.
04단계에서 준비한 공개 실습용 관리자 이메일 admin@example.test와 암호 vibe-admin-04-demo로 로그인한 뒤 다음 항목을 확인합니다.
- 로그인 뒤
/admin으로 이동하고 로그인 화면으로 되돌아가지 않습니다. Sidebar에는Dashboard와 새로 추가한Text Tool만 표시됩니다.Text Tool을 선택하면 주소가/admin/text-tool로 바뀝니다.- 공통
Header와Sidebar는 유지되고 본문에 문장 입력, 실행 버튼과 결과 영역이 표시됩니다. Text Tool을 선택한 상태가 현재 메뉴로 구분되어 표시됩니다.
동작하지 않는 메뉴나 두 번째 기능이 추가되어 있으면 완료로 판정하지 않습니다.
로그인 직후에는 Dashboard가 현재 메뉴로 표시되고, 같은 Sidebar에 Text Tool이 추가되어 있어야 합니다.
Text Tool을 선택하면 공통 관리자 화면의 본문만 입력 화면으로 바뀌고 Text Tool이 현재 메뉴로 표시됩니다.
다음 절의 정상 입력 검증에서는 여러 칸의 공백이 포함된 예제 문장을 입력하고, 정리된 결과와 API 응답을 차례로 확인합니다.
4. 정상 입력과 API 성공 확인
Text Tool 입력란에 다음 문장을 입력합니다. 단어 사이의 공백은 일부러 여러 칸으로 입력합니다.
Vibe Coding Text Tool실행 버튼을 선택한 뒤 다음 결과를 확인합니다.
- 처리 중에는 진행 상태가 표시되고 실행 버튼을 반복해서 선택해도 중복 요청이 발생하지 않습니다.
- 결과에는 연속 공백이 하나로 정리된
Vibe Coding Text Tool이 표시됩니다. - 글자 수는 공백을 포함하여
21, 단어 수는4로 표시됩니다. - 개발자 도구의
Network에서text-summary요청 방법이POST이고 상태가200입니다. - 응답이나
Console에 스택 추적, SQL, 환경 변수와 인증정보가 표시되지 않습니다.
API 상태를 확인하기 전에 웹 브라우저 개발자 도구의 Network를 열고 기존 요청 목록을 비운 상태에서 예제 문장을 다시 실행합니다.
글자 수 계산 기준이 구현 보고와 다르게 정의되었다면 임의로 통과시키지 말고, 화면 결과와 Codex 완료 보고를 함께 전달하여 요구사항과 구현을 일치시킵니다.
5. 잘못된 입력과 중복 제출 확인
입력란을 비운 채 실행해 보고, 이어서 2,000자를 초과하는 문장을 붙여 넣어 확인합니다.
입력란이 비어 있으면 다음 화면처럼 문장을 입력하라는 오류가 표시되어야 합니다.
- 빈 입력과 2,000자 초과 입력은 실행되지 않거나 사용자가 이해할 수 있는 안전한 오류로 표시됩니다.
- 요청이 백엔드까지 전달된 경우
Network상태는400이고 기존 공통 오류 형식을 사용합니다. - 오류 응답에 입력한 전체 문장, 스택 추적과 인증정보가 노출되지 않습니다.
- 정상 문장을 입력하고 실행 버튼을 빠르게 여러 번 선택해도 같은 요청이 중복 처리되지 않습니다.
- 오류가 발생한 뒤 정상 문장을 다시 실행하면 성공 결과로 복구됩니다.
다음 화면의 글자 수 1,996과 단어 수 293은 2,000자 이하이므로 정상 처리되는 상한 근처 입력의 예입니다. 이 화면은 2,000자 초과 입력이 거부되는지를 확인한 결과가 아니므로, 초과 입력 검증은 위 절차에 따라 별도로 수행합니다.
프런트엔드가 잘못된 입력을 요청 전에 차단하면 Network에 400 요청이 나타나지 않을 수 있습니다. 이 경우 Codex 완료 보고에서 보호 API의 400 자동 검사가 통과했는지 확인합니다.
6. 새로고침·모바일·키보드 확인
/admin/text-tool에서 F5를 눌러 새로 고친 뒤 다음 항목을 확인합니다.
먼저 웹 브라우저 개발자 도구에서 화면 너비를 440px 정도로 줄이고, Text Tool의 제목, 입력란, 실행 버튼과 Logout이 화면 안에 표시되는지 확인합니다.
- 로그인 상태와
/admin/text-tool주소가 유지됩니다. Sidebar에서Text Tool이 현재 메뉴로 다시 표시됩니다.- 모바일 너비에서 메뉴 버튼으로
Sidebar를 열고 닫을 수 있습니다. - 모바일 메뉴에서
Text Tool을 선택하면 본문이 표시되고 메뉴가 의도한 방식으로 닫힙니다. Tab키로 메뉴, 입력란, 실행 버튼과 Logout에 이동할 수 있으며 포커스가 보입니다.- 키보드만으로 문장을 입력하고 실행하여 결과를 확인할 수 있습니다.
모바일 화면에서도 예제 문장을 실행한 뒤 정리 결과와 Network의 text-summary 요청 상태가 200인지 확인합니다.
위 두 화면은 모바일 화면 구성과 API 성공을 보여 주지만, Sidebar 열기·닫기와 키보드 포커스를 확인한 화면은 아닙니다. 목록의 3~6번 항목은 사용자가 직접 조작하여 별도로 확인합니다.
화면 겹침이나 가로 스크롤 때문에 주요 기능을 사용할 수 없거나 키보드 포커스가 보이지 않으면 완료로 판정하지 않습니다.
7. 인증 흐름과 자동 검사 결과 확인
Logout을 선택한 뒤 /admin/text-tool을 직접 열어 보호된 화면 대신 로그인 화면으로 이동하는지 확인합니다. 다시 로그인하면 Text Tool을 사용할 수 있어야 합니다.
Codex 완료 보고에서는 다음 결과를 확인합니다.
- 백엔드 형식 검사와 프런트엔드 빌드
- 보호 API의
200,400, 로그인하지 않은 요청의401, 관리자 권한이 없는 요청의403 - 기존 로그인, 세션,
Dashboard, 새로고침과 로그아웃 회귀 검사 - 통과, 실패와 미수행으로 구분된
Console,Network, 키보드와 모바일 결과
실습용 일반 사용자 계정이 준비되어 있지 않다면 사용자가 403을 만들기 위해 계정이나 데이터베이스를 임의로 변경하지 않습니다. Codex가 격리된 검사에서 확인한 실제 결과를 완료 보고에서 확인합니다.
화면 확인과 필수 자동 검사 가운데 하나라도 실패하거나 미수행이면 08단계로 진행하지 않습니다.
8. 실습 프로세스 중지
확인이 끝나면 프런트엔드 → 백엔드 → MySQL 순서로 중지합니다.
- 프런트엔드 터미널에서
q를 입력하고Enter를 누르거나Ctrl+C를 누릅니다. - 백엔드 터미널에서
Ctrl+C를 누릅니다. - 두 터미널에 셸 프롬프트가 다시 표시되었는지 확인합니다.
별도 터미널에서 3000번과 5173번 포트의 수신 프로세스가 남아 있지 않은지 확인합니다.
if ss -ltn | grep -Eq ':(3000|5173)\b'; then
echo "확인 필요: 3000 또는 5173 포트의 프로세스가 아직 실행 중입니다"
else
echo "백엔드와 프런트엔드가 중지되었습니다"
fi
확인 필요가 표시되면 다른 프로세스를 임의로 강제 종료하지 않습니다. 이번 실습에 사용한 터미널을 찾아 종료 키를 다시 사용한 뒤 포트를 재확인합니다.
백엔드와 프런트엔드가 중지되면 MySQL 데이터를 유지하면서 서비스만 중지합니다.
cd /home/apple2ne1/projects/vibe-coding-platform
docker compose stop mysql
docker compose ps -a mysql
MySQL의 STATUS가 Exited로 표시되면 정상적으로 중지된 것입니다. 이름 있는 볼륨을 삭제하는 docker compose down -v는 실행하지 않습니다.
9. Codex에 검증 결과 기록 요청
사용자가 위 절차의 WebUI 또는 대체 검사를 마친 뒤에는 여러 기록 파일을 직접 열어 맞추지 않습니다. 검증 결과가 성공이든 실패든 다음 프롬프트 하나를 Codex CLI에 전달하여 확인된 결과와 단계 상태를 정리합니다.
07단계 구현과 검증은 앞 절차에서 완료했어. 검증을 다시 실행하지 말고 현재 작업 기록과 실제 결과만 확인해 줘.
webui-gate.md에는 Text Tool API와 화면 회귀 결과를, local-development.md에는 Text Tool 실행과 오류 확인 방법을, README.md에는 Sidebar 메뉴와 보호 엔드포인트를 기록해 줘. admin-platform.md의 메뉴 요구사항과 검증 기준은 실제 기준이 변경된 경우에만 수정해 줘.
실행하지 않은 검사는 통과로 기록하지 말고 기존 기록을 삭제하거나 덮어쓰지 마.
현재 코드와 확인된 결과를 기준으로 README.md, docs/requirements/admin-platform.md,
docs/development-guides/local-development.md와 docs/development-guides/webui-gate.md의
현재 단계와 구현 완료 상태가 서로 다른지도 확인해 줘.
현재 단계와 구현 완료 상태는 요구사항 변경이 아니라 진행 기록이야. 현재 코드와 확인된 검증 결과로 이번 단계의 완료 조건을 충족한 것이 확인되면, admin-platform.md를 포함한 위 문서의 오래되거나 충돌하는 진행 기록을 사용자에게 다시 묻지 말고 이번 단계 완료로 일치시켜 줘. 요구사항·기준·기존 검증 결과는 바꾸지 마.
실패·미수행·확인 불가 항목 때문에 완료 조건을 충족하지 못했다면 완료로 바꾸지 말고 실제 상태와 다음 해결 방법을 기록해 줘.
실패나 미수행 결과가 있으면 완료로 만들지 말고 원인과 다음 해결 방법을 기록해 줘.
안전하게 해결할 수 있는 기록 누락이나 충돌은 직접 수정하고 다시 확인해 줘.
사용자 조작이 꼭 필요하면 사용자가 해야 할 행동 한 가지만 쉬운 문장으로 알려 줘.
마지막에는 비전공자도 이해할 수 있게 다음 내용만 보고해 줘.
1. 변경한 파일
2. 파일별로 기록한 실제 결과
3. 현재 단계 완료 기록이 서로 일치하는지
4. 남은 실패·미수행·확인 불가 항목
5. 다음 단계 진행 가능 여부
스테이징과 커밋은 실행하지 마.
Codex의 완료 보고에서 변경 파일과 실제 기록 결과, 문서 간 단계 상태, 남은 미수행 항목과 다음 단계 진행 가능 여부가 구분되어 있는지 확인합니다. 진행 기록만 오래되어 서로 다르면 요구사항과 기존 검증 결과를 바꾸지 않고 현재 코드와 확인된 결과에 맞게 일치시켜야 합니다.
10. 최종 변경 검토와 커밋
Codex는 완료 보고에서 이번 단계의 변경 파일을 알려 주지만 스테이징하지 않습니다. Windows 관리 PC에서는 자동 검사 결과와 변경 파일 목록을 확인한 뒤, 완료 보고와 일치하는 파일만 직접 스테이징합니다.
cd /home/apple2ne1/projects/vibe-coding-platform
git status --short
git add -- README.md backend/src/app.ts backend/test/app.test.ts docs/development-guides/local-development.md docs/development-guides/webui-gate.md docs/requirements/admin-platform.md frontend/src/App.test.tsx frontend/src/App.tsx frontend/src/components/AdminHeader.tsx frontend/src/components/AdminLayout.tsx frontend/src/components/AdminSidebar.tsx frontend/src/styles.css frontend/src/admin-menu.ts frontend/src/pages/TextToolPage.tsx
git --no-pager diff --cached --name-only
git diff --cached --check먼저 git status --short에서 07단계 구현과 검증 기록에 해당하는 변경 파일과 새 파일을 확인합니다. 위 git add -- 명령의 파일 목록은 이 문서에서 확인한 07단계 결과를 기준으로 합니다. Codex 완료 보고의 변경 파일과 다르면 명령을 그대로 실행하지 않고 실제 완료 보고와 일치하도록 경로를 조정합니다.
이번 단계의 변경을 스테이징한 뒤 git --no-pager diff --cached --name-only로 커밋에 포함될 파일 목록을 확인합니다.
git diff --cached --check가 별도 오류 없이 끝나면 스테이징된 변경에서 공백 오류가 발견되지 않은 것입니다.
스테이징 파일 목록이 Codex의 완료 보고와 같고 git diff --cached --check가 오류 없이 종료되면 단계 결과를 커밋합니다. 목록이 다르거나 검사가 실패하면 커밋하지 않고 Codex에 출력 결과를 전달해 수정을 요청합니다.
git commit -m "feat: complete 07 step"
정식 작업 지시서 해설
이 절은 새로운 작업을 지시하거나 추가 명령을 실행하는 단계가 아닙니다. 정식 작업 지시서 실행, 구현 결과 검증, Codex의 검증 기록 갱신과 커밋까지 마친 뒤 읽는 복습용 해설입니다.
비전공자도 앞서 수행한 요구사항이 왜 필요했는지, 어떤 구성 요소가 바뀌었는지, 구현이 어떻게 동작하고 무엇을 검증했는지를 이해할 수 있도록 쉽게 풀어서 설명합니다. 아래의 파일명, 주소와 명령은 완료된 구성을 이해하기 위한 참고 정보이며, 별도의 실행 안내가 없는 한 다시 실행하지 않습니다.
1. 완성된 결과
기존 관리자 화면의 Sidebar에 첫 번째 실제 기능인 Text Tool 메뉴를 추가했습니다. 관리자가 메뉴를 선택하면 /admin/text-tool로 이동하며, 공통 Header와 Sidebar는 유지되고 본문 영역에 텍스트 입력 화면이 표시됩니다.
입력한 문장은 보호된 POST /api/admin/tools/text-summary로 전달됩니다. 백엔드는 연속 공백을 하나로 정리하고 정리된 문장, 글자 수와 단어 수를 반환합니다. 프런트엔드는 처리 중 상태와 성공 결과 또는 안전한 오류를 화면에 표시합니다.
화면과 API는 06단계에서 완성한 로그인·세션·관리자 권한 검사를 그대로 사용합니다. 따라서 로그인하지 않은 사용자나 관리자 권한이 없는 사용자는 화면과 API를 사용할 수 없습니다.
07단계에서 채워진 주요 폴더와 파일
vibe-coding-platform/
├── docs/
│ └── work-orders/
│ └── 07-first-sidebar-menu.md
├── frontend/
│ └── src/
│ ├── <Sidebar 메뉴 데이터와 이동을 담당하는 실제 소스 파일>
│ └── <Text Tool 화면과 API 호출의 실제 소스 파일>
└── backend/
└── src/
└── <POST /api/admin/tools/text-summary 구현의 실제 소스 파일>07단계는 기존 프런트엔드와 백엔드 소스 폴더에 첫 번째 실제 관리자 기능을 채웁니다. 화면, API와 테스트 파일명은 기존 배치 방식을 유지하여 구현 완료 보고에서 확인한 경로로 기록합니다.
2. 메뉴와 화면 구조
메뉴의 고유 ID, 이름, 아이콘, 경로와 접근 조건은 한 데이터 구조에서 관리합니다. 메뉴를 여러 컴포넌트에 따로 작성하면 이름이나 주소를 바꿀 때 일부 화면만 오래된 값으로 남을 수 있습니다. 한 데이터 구조를 기준으로 사용하면 Sidebar 표시, 현재 메뉴 판정과 화면 표시 조건을 함께 관리할 수 있습니다. 다만 이 접근 조건은 프런트엔드의 메뉴 표시 기준이며 API 보안을 대신하지 않습니다. 실제 보안 경계는 백엔드의 requireAdmin입니다.
현재 주소와 선택된 메뉴도 서로 일치시킵니다. /admin/text-tool에서 새로고침해도 주소를 기준으로 Text Tool이 다시 선택되고 같은 화면이 표시되어야 합니다. 메뉴를 클릭했을 때만 화면이 바뀌고 새로고침하면 Dashboard로 돌아가는 방식은 사용하지 않습니다.
AdminLayout은 공통 Header, Sidebar와 본문 영역을 유지합니다. Text Tool을 선택하면 화면 전체를 새로 만들지 않고 본문만 TextToolPage로 바뀝니다. 이번 단계에서는 하위 메뉴를 만들지 않았지만 이후 펼침·접힘 메뉴를 추가할 때 전체 구조를 다시 작성하지 않도록 메뉴 데이터와 컴포넌트의 역할을 나눴습니다.
3. 프런트엔드와 백엔드의 역할
프런트엔드는 다음 역할을 담당합니다.
Sidebar에서 현재 메뉴를 표시하고/admin/text-tool로 이동- 1자 이상 2,000자 이하의 입력 조건을 먼저 확인
- 요청을 처리하는 동안 진행 상태를 표시하고 실행 버튼을 비활성화하여 빠른 연속 제출 차단
- 성공 결과 또는 사용자가 이해할 수 있는 오류 표시
- 오류 뒤에 정상 입력을 다시 실행할 수 있도록 상태 복구
백엔드는 프런트엔드 검사 결과를 신뢰하지 않고 같은 입력 조건을 다시 확인합니다. API는 웹 브라우저 이외의 도구로도 직접 호출할 수 있으므로 백엔드 재검증이 없으면 잘못된 값이 프런트엔드 검사를 우회할 수 있기 때문입니다.
정식 API 계약은 입력이 1자 이상 2,000자 이하인 문자열이어야 한다는 범위와 연속 공백을 하나로 정리한다는 결과를 정의합니다. 앞뒤 공백, 공백만 있는 입력, 길이 검사 시점과 글자·단어 계산 방법은 완료된 실제 구현과 자동 검사에서 확인된 기준으로 설명해야 하며, 해설에서 확인하지 않은 규칙을 추가로 가정하지 않습니다. 화면에 표시하는 글자 수와 단어 수 역시 API가 반환한 정리 결과를 그대로 사용합니다.
백엔드는 requireAdmin으로 세션과 관리자 권한을 확인한 뒤 입력을 처리합니다. 여러 칸의 공백을 하나로 정리하고, 정리된 문장과 글자 수 및 단어 수를 같은 응답으로 반환합니다. 입력한 전체 문장, 스택 추적, 환경 변수와 인증정보는 오류 응답에 포함하지 않습니다.
4. 요청과 응답 흐름
관리자가 문장을 입력하고 실행 버튼을 선택하면 다음 순서로 동작합니다.
- 프런트엔드가 빈 입력과 2,000자 초과 입력을 확인합니다.
- 조건에 맞으면 요청이 끝날 때까지 실행 버튼을 비활성화하고 진행 상태를 표시하여 사용자의 빠른 연속 제출을 막습니다. 이는 백엔드가 동일 요청을 식별하여 한 번만 처리하는 멱등성을 뜻하지 않습니다.
- 프런트엔드 API 함수가
POST /api/admin/tools/text-summary를 호출합니다. requireAdmin이 로그인 세션과 관리자 권한을 확인합니다.- 백엔드가 입력 조건을 다시 검사하고 연속 공백을 정리합니다.
- 백엔드가 정리된 문장, 글자 수와 단어 수를 반환합니다.
- React가 응답에 따라 성공 결과 또는 오류를 표시합니다.
API 상태 코드는 결과의 종류를 구분합니다.
200: 관리자로 인증되었고 입력값 처리에 성공했습니다.400: 빈 입력이나 2,000자 초과처럼 입력 조건에 맞지 않습니다.401: 로그인 세션이 없습니다.403: 세션은 있지만 현재 사용자가 비활성 상태이거나 관리자 권한이 없습니다.
401과 403 응답은 사용자 존재 여부, 내부 스택 추적과 인증정보를 노출하지 않는 안전한 공통 오류 형식을 유지해야 합니다.
5. 모바일·키보드·새로고침 검증의 의미
데스크톱 화면에서 메뉴와 API가 동작하는 것만으로는 공통 관리자 화면이 유지됐다고 판정할 수 없습니다. /admin/text-tool에서 새로고침한 뒤에도 로그인 상태, 주소와 선택 메뉴가 유지되는지 확인하여 URL을 기준으로 화면 상태를 복원하는지 검증했습니다.
모바일 너비에서는 메뉴 버튼으로 Sidebar를 열고 닫을 수 있어야 하며, 메뉴를 선택한 뒤 본문을 가리지 않도록 의도한 방식으로 닫혀야 합니다. 화면이 좁아도 제목, 입력란, 실행 버튼과 Logout을 사용할 수 있어야 합니다.
키보드 검증은 마우스 없이 메뉴, 입력란, 실행 버튼과 Logout으로 이동할 수 있는지 확인하는 절차입니다. Tab 키로 이동할 때 포커스가 보여야 하며, 키보드만으로 문장을 입력하고 결과를 확인할 수 있어야 합니다.
6. 회귀 검사와 완료 판정
07단계에서는 새 기능만 확인하지 않고 기존 로그인, 세션, Dashboard, 새로고침과 Logout도 다시 검사합니다. 첫 메뉴를 추가하면서 01~06단계의 기존 흐름이 손상되지 않았는지 확인하기 위한 회귀 검사입니다.
백엔드 typecheck는 TypeScript 자료형 오류를 검사하고, 프런트엔드 build는 배포용 결과물을 생성할 수 있는지 확인합니다. API 자동 검사는 200·400·401·403 응답을 확인하고, 변경 전·후 공통 WebUI Gate는 기존 기능의 회귀 여부를 비교합니다. 웹 브라우저에서는 정상 입력, 빈 입력, 2,000자 초과 입력, 빠른 연속 제출 차단, 오류 뒤 복구, 현재 메뉴, 새로고침, 모바일 화면과 키보드 이동을 확인합니다.
자동 검사는 완료 보고에 실행 명령과 실제 결과가 있는 경우에만 통과로 인정합니다. Codex가 실행한 자동 검사와 사용자가 확인한 WebUI 결과를 구분하며, 어느 한쪽이라도 실패하거나 실행하지 않았다면 완료로 판정하지 않습니다.
검사 결과는 통과·실패·미수행으로 구분합니다. 필수 자동 검사나 사용자가 확인해야 하는 WebUI 항목이 실패했거나 미수행이면 07단계 완료 또는 08단계 진행 가능으로 판정하지 않습니다.
7. 이번 단계에서 추가하지 않은 기능
07단계의 목적은 첫 번째 메뉴 하나의 전체 흐름을 작게 완성하는 것입니다. 다음 항목은 기능 범위와 오류 원인을 불필요하게 넓히므로 추가하지 않았습니다.
- 외부 AI API, WordPress와 이미지 생성 서비스 연동
- 데이터베이스 저장
- 새 패키지와 두 번째 메뉴
- 기존 로그인, 세션,
Dashboard와 Logout의 관련 없는 변경
Text Tool은 실제 외부 서비스를 연결하는 완성형 도구가 아니라, 메뉴 선택부터 보호 API와 결과 표시까지의 확장 방법을 학습하는 예제입니다.
8. 구현·검증·기록 단계의 구분
07단계 작업은 다음 세 단계로 구분합니다.
- 정식 작업 지시서에 따라 메뉴, 화면과 보호 API를 구현합니다.
- 자동 검사와 사용자의 WebUI 확인으로 실제 동작을 검증합니다.
- 검증이 끝난 뒤 별도의 9. Codex에 검증 결과 기록 요청 프롬프트로 확인된 결과만 관련 문서에 기록합니다.
세 번째 기록 단계에서는 구현하거나 검사를 다시 실행하지 않고, 앞 단계의 완료 보고와 사용자가 확인한 WebUI 결과만 사용합니다. 실제 기록이 없는 검사를 해설이나 예상 결과만으로 통과 처리하지 않습니다. Codex는 확인된 결과를 다음 문서에 나누어 기록합니다.
webui-gate.md: Text Tool API, 데스크톱·모바일·키보드와 기존 화면 회귀 결과local-development.md:/admin/text-tool실행 및 빈 입력·2,000자 초과·401·403·연결 오류 확인 방법README.md: 현재 07단계,Dashboard·Text Tool메뉴, 보호 경로와 APIadmin-platform.md: 요구사항이나 메뉴 기준은 유지하고, 오래된 구현 진행 상태만 07단계 완료로 갱신
여러 문서의 현재 단계가 다르면 요구사항 자체를 바꾸지 않고 현재 코드와 확인된 검증 결과에 맞춰 진행 기록만 일치시킵니다. 실패·미수행·확인 불가 항목이 남아 완료 조건을 충족하지 못했다면 완료 상태로 바꾸지 않습니다.
9. 다음 단계
다음 글에서는 지금까지 완성한 애플리케이션을 변경하지 않고 실행 환경을 Docker Compose, Redis와 Nginx로 차례로 확장합니다.
참고 자료 및 출처
- Express Middleware Guide: 보호 미들웨어와 경로 처리 순서 확인. 확인일: 2026-08-12
- React Router Routing: URL 경로와 화면 연결 방식 확인. 확인일: 2026-08-12
- Vite Server Options: 개발 서버의 호스트와 포트 설정 확인. 확인일: 2026-08-12
- Git diff Documentation:
git diff --cached --check의 스테이징 변경 검사 방식 확인. 확인일: 2026-08-12 - Docker Compose stop: 컨테이너를 삭제하지 않고 서비스를 중지하는 명령 확인. 확인일: 2026-08-12
- WAI-ARIA Keyboard Interface: 키보드 이동과 포커스 표시 원칙 확인. 확인일: 2026-08-12