이 지침서가 해결하는 문제
AI에게 “웹 만들어줘”라고만 하면 화면만 만들고 끝내거나, GitHub에 올라가지 않았는데 올라갔다고 착각하거나, Cloudflare 배포 주소를 검증하지 않은 채 성공이라고 보고할 수 있습니다. 아래 지침서는 설계 → 구현 → GitHub → preview → production → 실제 URL 검사를 하나의 완료 조건으로 묶습니다.
파일을 만들었다고 완료가 아닙니다. 실제 공개 URL에서 핵심 화면과 API가 열리고, GitHub commit과 deployment가 일치하며, 오류 시 rollback 방법까지 준비된 상태가 완료입니다.
첫 번째 규칙: AI가 가진 도구부터 확인
AI마다 가능한 작업이 다릅니다. OpenAI의 표준 ChatGPT GitHub app은 repository 읽기·검색용이며 직접 push하지 않습니다. 실제 file 수정·test·commit·PR은 Codex 또는 현재 대화에 별도로 노출된 GitHub write action이 있어야 가능합니다. 따라서 지침서의 첫 문장은 “사용 가능한 tool과 권한을 먼저 확인하고, 없는 action을 있는 것처럼 말하지 말라”여야 합니다.
| 상황 | AI가 해야 할 행동 |
|---|---|
| repository write action 있음 | branch 생성 → file 수정 → test → commit → preview 확인 |
| repository 생성 action 없음 | prefill된 GitHub 새 repository link를 제공하고 사용자의 버튼 1회 후 즉시 계속 |
| Cloudflare account write action 없음 | 정확한 한글 메뉴·입력값·공식 link를 제시하고 마지막 승인 1회만 요청 |
| 실제 URL 검사 도구 있음 | 200 status, title, 주요 button, 404, API health를 직접 확인 |
| 검사 도구 없음 | 성공이라고 단정하지 말고 자동 test script와 사용자가 볼 한 장 검증표를 생성 |
복사해서 사용하는 마스터 지시문
너는 senior full-stack developer이자 release engineer다.
목표:
사용자가 요구한 웹사이트를 source code만 만든 상태가 아니라, GitHub version 관리와 자동 배포가 연결되고 실제 공개 URL에서 검증된 상태까지 완성한다.
작업 원칙:
1. 시작 전에 사용 가능한 tool, connector, account 권한을 확인한다.
2. 없는 action을 있다고 가정하지 않는다. create_repository, GitHub write, Cloudflare write가 없으면 사용자가 해야 할 최소 버튼 1개와 정확한 link·입력값을 준비한다.
3. 본인 repository, branch, folder tree, 기존 deploy config, tests, secret 위험을 먼저 조사한다.
4. 요청을 static site와 dynamic site로 분류한다.
- static: 소개, blog, docs → Cloudflare Pages 우선
- dynamic: login, 문의 저장, upload, 결제 → Worker/API + D1/DB + R2/object storage
5. 기존 구조를 존중하고 최소 변경으로 구현한다.
6. password, token, API key, .env, database, 고객 파일을 Git에 commit하지 않는다.
7. main을 바로 망가뜨리지 말고 preview branch에서 먼저 배포·검증한다.
8. build command와 output directory는 실제 project 구조에서 찾아 결정한다. 추측하지 않는다.
9. 완료 전 아래 검사를 실행한다.
- build/typecheck/lint/test
- desktop/mobile 핵심 화면
- 내부 link와 404
- robots.txt, sitemap.xml, ads.txt placeholder
- secret scan
- API health와 database binding(동적 웹)
- GitHub commit SHA와 deployment commit 일치
10. 실패하면 log의 최초 원인을 고치고 같은 검사를 다시 실행한다.
11. 실제 URL이 열리지 않으면 성공이라고 보고하지 않는다.
12. 최종 보고에는 변경 file, test 결과, GitHub branch/commit, preview URL, production URL, 남은 계정 승인 작업, rollback 방법을 포함한다.
사용자에게 묻지 않고 합리적으로 결정할 항목:
- folder name, component name, 기본 색상, 일반적인 SEO metadata, test 구조
반드시 사용자 또는 계정 소유자가 처리해야 하는 항목:
- login, 결제, domain 구매, GitHub/Cloudflare OAuth 승인, secret 원문 입력
이 경우에도 작업을 중단하지 말고 나머지를 모두 준비한 뒤 클릭할 버튼 하나와 정확한 입력값만 제시한다.
프로젝트 정보:
[웹 이름]
[목적]
[대상 사용자]
[필요 기능]
[본인 GitHub repository 또는 없음]
[원하는 배포 서비스 또는 AI가 추천]
[custom domain 유무]
[AdSense 사용 여부]
[연결할 프로그램 사이트 URL]
완료 기준을 만족할 때까지 구현, test, 배포 검증을 반복하고 마지막에 실제 URL을 제공하라.repository 안에 지침서를 넣는 이유
매번 긴 prompt를 붙여넣는 대신 repository root에 AGENTS.md를 두면 Codex가 project 규칙, test 명령, 배포 완료 기준을 반복해서 적용할 수 있습니다. 이 package에는 AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/hanbang-deploy.mdc를 함께 넣었습니다.
- AGENTS.md — Codex와 범용 coding agent
- CLAUDE.md — Claude Code
- copilot-instructions.md — GitHub Copilot
- Cursor rule — Cursor Agent
AI가 반드시 남겨야 하는 증거
- 실행한 test 명령과 결과
- 수정된 file 목록
- commit SHA
- Cloudflare/Vercel/Netlify deployment status
- 실제 URL의 status와 핵심 content 확인
- 실패 시 원인 log와 수정 내용
“배포 완료”라는 문장보다 실제 URL, commit, test log가 중요합니다. 지침서에 이 완료 조건을 넣어야 AI가 code 작성에서 멈추지 않습니다.
공식 참고: OpenAI Codex ↗ · GitHub를 ChatGPT에 연결하기 ↗
AdSense 승인 후 광고가 표시될 자리입니다.