codex.md - Codex 개발 워크플로우 통합 가이드 목적 이 문서는 Codex가 이 프로젝트에서 작업할 때 사용하는 모든 핵심 원칙과 워크플로우를 통합한 단일 참조 문서입니다. CODEX.md, agent.md, codex_answer.md, project_map.md, handoff.md, todolist.md, deepseek.md의 내용을 하나로 정리했습니다.
핵심 철학 "기억하지 말고, 기록하라. 추측하지 말고, 확인하라. 한 번에 많이 하지 말고, 작게 반복하라."
- 역할 정의 Codex의 강점 (이런 일에 집중) 작업 유형 설명 코드 수정/디버깅 오류 원인 추적, 기존 코드 수정, 로그 분석 기능 추가 화면, 버튼, API, 관리자 기능, 자동화 추가 코드 설명 파일, 함수, API 흐름, 오류 의미 설명 리팩터링 중복 제거, 함수 분리, 구조 개선 (동작 유지) 문서화 README, API 메모, 개발 지침, 인수인계 작성 보안/품질 점검 권한, 입력 검증, SQLi, 업로드, 세션, API 노출 확인 Codex의 약점 (주의 필요) 모호한 지시만으로 완성도 높은 디자인을 한 번에 만드는 작업
불명확한 요구사항에서 숨은 의도를 맞히는 작업
실제 파일을 읽지 않고 큰 아키텍처를 설계하는 작업
백업/롤백/테스트 없이 운영 파일을 수정하는 작업
외부 서비스/정책/라이브러리 최신 정보를 확인 없이 단정하는 작업
- 필수 준비물 매 작업 세션 시작 전, 아래를 반드시 확인합니다.
bash
1. 현재 작업 디렉토리 확인
pwd
/home/cafe/web/~~~
2. 관련 문서 최신 상태 확인
ls -la codex/
3. 현재 활성 테마 확인 (필요시)
themes/ 폴더에서 어떤 테마가 활성화되어 있는지 config.php나 DB에서 확인
- 7단계 최적화 워크플로우 단계 0: 세션 시작 (2분) 목표: "지금부터 무엇을 할 것인가"를 명확히 정의
markdown
[세션 시작] YYYY-MM-DD HH:MM
오늘의 목표:
[한 문장으로 압축]
작업 유형:
[ ] 신규 개발 [ ] 버그 수정 [ ] 기능 개선 [ ] 보안 패치 [ ] 문서화
예상 영향 범위:
[파일 또는 폴더 목록]
성공 기준:
[테스트로 확인할 수 있는 구체적 조건] 단계 1: 구조 확인 (3-5분) 목표: 관련된 모든 파일과 의존성을 파악
- 먼저 읽을 문서:
codex/project_map.md - 프로젝트 전체 구조
CLAUDE.md - 기존 개발 지침 (큰 작업 시)
system.md - 시스템 전역 동작
- 관련 파일 찾기:
bash
파일명으로 검색
find . -name "keyword" -type f
내용으로 검색
grep -r "function_name" --include="*.php" .
API 엔드포인트 추적
grep -r "api/endpoint" --include="*.php" . 3) 기록할 내용:
markdown
구조 스냅샷
진입점:
파일명.php- [역할]
데이터 흐름:
파일A→파일B호출파일B→DB쿼리- 결과 →
파일C에서 출력
의존성:
- DB 테이블: [테이블명]
- 설정 파일:
config.php의 [설정명] - 외부 API: [있으면 적기]
위험 지점:
- [ ] 세션/권한 확인 필요
- [ ] 캐시 영향 가능
- [ ] 다른 테마와 공유 코드 단계 3: 계획 수립 (2분) 목표: 구체적인 수정 대상과 방법을 결정
markdown
작업 계획
수정할 파일: (최대 3개로 제한)
path/to/file1.php- [수정 내용]path/to/file2.php- [수정 내용]path/to/file3.php- [수정 내용]
백업 계획:
- [ ] 파일별 백업:
filename.ext.1 - [ ] 폴더 백업:
folder_backup_YYYYMMDD/
테스트 계획:
- [ ] [테스트 항목 1]
- [ ] [테스트 항목 2]
- [ ] [테스트 항목 3]
롤백 조건:
- [ ] 홈페이지 로딩 실패
- [ ] 관리자 접근 불가
- [ ] 핵심 기능 중단 단계 4: 백업 실행 (1분) 목표: 언제든 원상복구 가능한 상태 보장
bash
단일 파일 백업
cp path/to/file.php path/to/file.php.1
여러 파일 백업
for f in file1.php file2.php file3.php; do cp $f $f.1 done
폴더 전체 백업
tar -czf backup$(date +%Y%m%d%H%M).tar.gz themes/current_theme/ 백업 확인:
bash ls -la path/to/*.1 # 백업 파일 존재 확인 단계 5: 집중 실행 (최대 15분) 목표: 최소 변경으로 목표 달성
실행 규칙:
한 번에 한 파일만 수정
수정 후 즉시 저장
저장 후 즉시 테스트 (단계 6)
문제 없으면 다음 파일로 이동
파일 헤더 규칙 (핵심 파일만):
php <?php /**
- [CODEX_DEV_MAP] path/to/file.php - 짧은 역할 - 버전/날짜
- [목적] 이 파일이 담당하는 기능.
- [핵심] 주요 API, 함수, 데이터 흐름, 의존성.
- [연관] 함께 확인해야 할 파일.
- [주의] 깨지기 쉬운 동작, 보안 주의점, 호환성 메모.
- [다음] 남은 작업 또는 후속 확인 사항. */ 수정 중 기록:
markdown
실행 로그
파일1 수정: file1.php - HH:MM
- 변경 내용: [구체적으로]
- 변경 이유: [왜 이렇게 했는지] 단계 6: 즉시 테스트 (2분) 목표: 변경이 의도대로 동작하는지 확인
bash
1. 기본 로딩 테스트
curl -s -o /dev/null -w "%{http_code}\n" https://your-site.com/
200이 아니면 즉시 롤백
2. 관련 페이지 테스트
curl -s -o /dev/null -w "%{http_code}\n" https://your-site.com/related-page/
3. API 테스트 (해당 시)
curl -X GET "https://your-site.com/api/endpoint" -H "Authorization: Bearer TOKEN"
4. PHP 오류 확인
tail -20 /path/to/php-error.log 테스트 체크리스트:
홈페이지 정상 로딩
관련 메뉴/버튼/링크 동작
브라우저 콘솔 에러 없음
모바일 화면 정상
PHP/API 응답 오류 없음
보안 관련: 입력 검증, 권한, 세션, 파일 접근, 데이터 노출 확인
단계 7: 문제 발생 시 롤백 (즉시) 목표: 손상된 상태를 빠르게 복구
bash
단일 파일 롤백
cp path/to/file.php.1 path/to/file.php
전체 롤백
tar -xzf backup_YYYYMMDD_HHMM.tar.gz -C ./ 즉시 롤백 조건:
홈페이지 로딩 실패
관리자 화면 접근 불가
메뉴/버튼/저장/발행/업로드/로그인 중단
브라우저 콘솔 차단성 오류
모바일 화면 깨짐
API fatal 오류
롤백 후 할 일:
복구 확인 (테스트 재실행)
문제 원인 분석 기록
더 작은 단위로 계획 수정
단계 3부터 다시 시작
단계 8: 세션 종료 (3분) 목표: 모든 상태를 기록하고 다음 작업자가 이어갈 수 있게 함
markdown
[세션 종료] YYYY-MM-DD HH:MM
수행한 작업:
file1.php- [변경 내용]file2.php- [변경 내용]
백업 파일:
file1.php.1file2.php.1backup_YYYYMMDD_HHMM.tar.gz
테스트 결과:
- [ ] 홈페이지 로딩: 정상
- [ ] 관련 기능: 정상
- [ ] 에러 로그: 이상 없음
- [ ] 모바일: 정상
남은 위험:
- [위험 항목이 있으면 명시]
다음 작업자 확인 사항:
- [확인 필요한 항목]
- [추가 검토 필요 항목]
최종 상태:
- [ ] 작업 완료
- [ ] 추가 작업 필요
- [ ] 보류/재검토 필요 갱신할 문서:
codex/todolist.md - 작업 상태 갱신
codex/handoff.md - 인수인계 기록 (다른 작업자 있을 시)
codex/project_map.md - 구조가 바뀌면 갱신
- 긴급 상황 대응 프로토콜
상황 1: "아까 무슨 파일을 수정했더라?"
bash
최근 수정 파일 확인
find . -name ".php" -mmin -30 -type f ls -lt .php | head -5 상황 2: "왜 이렇게 수정했더라?" bash
수정 파일의 변경 이력 확인
diff file.php file.php.1 git log -p -- file.php # git 사용 시 상황 3: "이게 원래 동작이 맞나?" bash
원본 파일과 비교
diff file.php file.php.1 cp file.php.1 file.php.test # 테스트용 복사
테스트 후 복원
- 명령어 치트시트 목적 명령어 관련 파일 찾기 find . -name "keyword" -type f | grep -v backup 함수 호출 추적 grep -r "functionName" --include=".php" . 최근 수정 파일 find . -name ".php" -mmin -60 -type f 백업 생성 cp file.php file.php.$(date +%Y%m%d_%H%M) 롤백 cp file.php.1 file.php PHP 오류 확인 tail -f /var/log/php_errors.log API 응답 확인 curl -s https://site.com/api/endpoint | jq .
- 인수인계 형식
Codex → Claude (다른 에이전트로 넘길 때)
markdown
Claude에게 인수인계
확인한 파일
[읽은 파일 목록]
수정한 파일
[수정 파일 목록]
백업 파일
[백업 위치]
변경 내용
[구체적 변경 사항]
테스트 결과
[테스트 완료 항목]
남은 위험
[알려진 위험]
Claude가 검토할 것
[집중 검토 필요 항목] Claude → Codex (다른 에이전트에게 받을 때) markdown
Codex에게 인수인계
목표
[최종 목표]
사용자 의도
[사용자 원하는 바]
인수 기준
[완료 조건]
관련 파일
[알려진 관련 파일]
제약 조건
[제한 사항]
질문
[불명확한 점] 7. 핵심 규칙 요약 규칙 이유 관련 구조 확인 전 수정 금지 맥락 없는 수정은 위험 없는 함수/변수/API 상상 금지 실제 존재하는 것만 사용 한 번에 3개 파일 이하 수정 영향 범위 통제 수정 전 항상 백업 즉시 롤백 가능 테스트 없이 완료 금지 확인되지 않은 변경은 위험 문제 발생 시 즉시 롤백 수정보다 복구가 빠름 모든 상태 기록 컨텍스트 유지 작업 세션 시작/종료 기록 다음 작업자 배려 기존 코드 스타일 유지 일관성 유지 모르는 내용은 모른다고 말함 추측 방지 8. 일일 체크리스트 markdown
[일일 시작] YYYY-MM-DD
어제까지의 상태:
- [ ]
handoff.md확인 - [ ]
todolist.md확인
오늘의 계획:
- [오늘 할 작업 1]
- [오늘 할 작업 2]
주의사항:
- [ ] 특이사항 1
- [ ] 특이사항 2
- 이 문서의 사용법 처음 작업할 때: 이 문서를 codex/codex.md로 저장 (또는 기존 CODEX.md를 대체)
매 작업 세션 시작: 단계 0부터 시작
혼란스러울 때: 이 문서로 돌아와서 현재 단계 확인
문제 발생 시: 단계 7 (롤백) 즉시 실행
작업 종료: 단계 8 (세션 종료) 반드시 실행
"이 문서가 당신의 두뇌를 대신하지 않습니다. 하지만 당신의 두뇌가 기억해야 할 것을 줄여줍니다."
부록: 프로젝트 주요 경로 text 루트: /home/cafe/web/blog.maocafe.com/public_html ├── api/ # API, 인증, 업로드, AI 생성 ├── db/ # DB 스키마와 마이그레이션 ├── themes/ # 사이트 테마 (startup, home, blog, shop, pro) ├── uploads/ # 업로드 파일 ├── codex/ # Codex 작업 문서 ├── config.php # 운영 설정 ├── index.php # 사이트 진입점 └── sitemap.php # 사이트맵 생성 핵심 API 파일:
api/auth.php - 인증/권한/세션
api/db.php - DB 연결/헬퍼
api/upload.php - 업로드 처리 (보안 점검 필수)
api/ai_*.php - AI 콘텐츠 생성 관련
api/env.php - 환경 설정 (노출 주의)
댓글 0