특강 — Todo List 웹서비스 만들기: Pages, Worker, D1, 도메인 연결¶

0. 오늘 만들 전체 그림¶

오늘은 간단한 Todo List를 만든다. 사용자가 할 일을 입력하면, 서버가 내용을 확인한 뒤 데이터베이스에 저장한다. 완료한 일에는 체크 표시를 할 수 있다.

클라이언트 (Cloudflare Pages로 배포한 웹페이지)
사용자 브라우저 · www.example.com · HTML/CSS/JavaScript
                         │ ① 페이지 열기 / ② API 요청
                         ▼
서버 (Cloudflare Worker)
api.example.com · 입력 검증 · API 처리
                         │
                         ▼
데이터베이스 (Cloudflare D1)
todos 테이블 · SQL 데이터 저장

구성 요소	하는 일	이번 특강의 실제 예시
클라이언트(프론트엔드)	사용자가 보는 화면, 클릭·입력 처리	웹페이지(HTML/CSS/JavaScript), 배포(Cloudflare Pages)
서버(백엔드)	요청 확인, 규칙 적용, 데이터 처리	서버리스 API 서버(Cloudflare Worker)
데이터베이스(DB)	새로고침해도 남아야 하는 데이터 저장	SQL 데이터베이스(Cloudflare D1)
도메인·DNS	사람이 읽는 주소를 서비스 위치에 연결	DNS 관리자(Cloudflare DNS)

핵심 원칙: 브라우저에 보낸 코드는 누구나 볼 수 있다. 비밀번호, 결제 키, 외부 API 키 같은 비밀 값은 반드시 서버(Worker)에만 둔다. D1은 비밀번호를 브라우저에 전달하지 않고 Worker의 바인딩으로 연결한다.

1. 먼저 이해할 웹의 언어¶

1.1 클라이언트와 서버¶

웹사이트를 카페로 생각해 보자.

카페	웹 서비스
손님	클라이언트(브라우저)
주문서	HTTP 요청(Request)
주방	서버(백엔드)
조리 규칙	서버 코드
식재료 창고·장부	데이터베이스
완성된 메뉴	HTTP 응답(Response)

브라우저는 “할 일 목록을 주세요”라고 요청하고, 서버는 데이터베이스에서 가져온 결과를 응답한다. 브라우저는 DB에 직접 접속하지 않고 정해진 서버 API를 통해 필요한 일만 요청하는 것이 기본 구조다.

GET https://api.example.com/todos
                       │
                       ▼
HTTP 200 OK
[{ "id": 1, "title": "Cloudflare Pages 배포", "is_done": false }]

1.2 URL, HTTP, JSON¶

https://api.example.com/todos를 나누어 보면 다음과 같다.

부분	의미
`https`	데이터를 암호화해 보내는 통신 규칙
`api.example.com`	서버의 주소(호스트 이름)
`/todos`	서버 안에서 원하는 기능·자원의 경로

HTTP 메서드는 “무엇을 할지”를 표현한다.

메서드	뜻	Todo List 예
`GET`	조회	`GET /todos` 목록 보기
`POST`	새로 만들기	`POST /todos` 할 일 등록
`PATCH`	일부 수정	`PATCH /todos/3` 완료 상태 변경
`DELETE`	삭제	`DELETE /todos/3` 할 일 삭제

클라이언트와 서버는 주로 JSON이라는 텍스트 형식으로 대화한다.

{
  "title": "첫 Todo List 배포하기",
  "is_done": false
}

1.3 상태 코드: 서버의 답장 신호¶

코드	뜻	지금 해야 할 일
`200`	요청 성공	받은 데이터를 화면에 표시
`201`	새 데이터 생성 성공	목록을 새로 고침
`400`	요청 내용이 잘못됨	입력값을 확인
`401`	로그인 필요	로그인 화면으로 안내
`403`	권한 없음	해당 작업을 막음
`404`	주소 또는 데이터 없음	URL·ID를 확인
`500`	서버 내부 오류	서버 로그를 확인

2. AI 에이전트와 함께 개발하기 — Codex·Claude Code¶

Codex와 Claude Code는 모두 프로젝트 파일을 읽고, 계획을 세우고, 코드를 수정하고, 명령을 실행해 결과를 확인하는 코딩 AI 에이전트다. 서비스마다 화면은 다르지만, 사람이 목표·제약·승인 기준을 정하고 에이전트가 구현·검증을 돕는 흐름은 같다.

AI가 만든 코드도 배포 책임은 사람에게 있다. DB 삭제, 비밀 값, 결제·로그인, DNS·운영 배포는 계획과 변경 내용을 확인한 뒤 승인한다.

2.1 에이전트, 토큰, 컨텍스트¶

에이전트는 단순히 답변하는 채팅창과 달리, 필요한 도구를 써서 여러 단계를 수행한다. 토큰은 AI가 읽고 쓰는 텍스트·코드의 작은 단위이며, 컨텍스트는 이번 작업에서 AI가 참고하는 대화·파일·명령 결과의 묶음이다. 긴 로그나 큰 저장소를 한 번에 모두 이해한다고 기대하기보다, 관련 파일과 오류만 골라 주는 편이 빠르고 정확하다.

사람: 목표와 제약을 설명하고 계획을 승인
          ↓
에이전트: 파일 확인 → 계획 → 구현 → 테스트 → 변경·결과 보고
          ↓
사람: diff·테스트·배포 설정 검토 후 승인

2.2 좋은 명령은 ‘목표·맥락·제약·완료 기준’으로 쓴다¶

프롬프트 엔지니어링은 어려운 문장을 만드는 일이 아니라, 에이전트가 추측하지 않도록 작업 조건을 주는 일이다. 처음에는 계획만 받고, 그 뒤 구현과 검증을 시키는 계획 → 구현 → 독립 검토 흐름이 현재 가장 실용적이다. 특히 새 채팅에서 별도 에이전트에게 git diff와 계획을 비교하게 하면 작성자와 다른 관점의 검토를 받을 수 있다.

목표: Todo List에서 할 일을 추가하고 완료 상태를 바꾸게 해 주세요.
맥락: frontend는 Cloudflare Pages, API는 Worker, 데이터는 Cloudflare D1을 사용합니다.
제약: 비밀 키를 코드·Git·화면에 넣지 말고, 기존 파일 구조를 유지하세요.
완료 기준: 목록 조회·추가·완료 변경을 테스트하고, 수정 파일·실행 명령·결과를 보고하세요.
진행: 먼저 파일을 읽고 계획만 제시하세요. 제 승인 뒤에 구현하세요.

요청이 끝난 뒤에는 “계획과 비교해 누락·보안 위험·테스트 부족을 찾아 주세요. 수정은 하지 말고 우선순위와 근거만 보고하세요.”라고 새 세션에 요청한다. 에이전트의 결과를 무조건 믿기보다 작은 변경 단위, Git diff, Preview 배포, 독립 검토를 함께 쓰는 방식이 최근 에이전트 개발에서 널리 권장된다.

2.3 Codex 모델: GPT-5.6 Sol·Terra·Luna¶

모델	잘 맞는 일	Todo List 예시
Sol	모호하고 복잡한 설계·보안·배포 문제	전체 구조와 권한 위험 검토
Terra	일상적인 구현·탐색·문서 확인	파일 구조 파악, 화면·API 기능 작업
Luna	작고 반복적인 정리 작업	파일명·표·문서 형식 정리

추론 수준이 높을수록 대체로 더 오래 생각하고 토큰을 더 사용할 수 있다. 처음에는 Terra와 기본 수준으로 시작하고, 설계·보안·복잡한 버그에서 Sol 또는 더 높은 추론 수준을 선택한다. Codex에서 실제로 보이는 모델은 로그인 방식과 플랜에 따라 다를 수 있으므로 /model에서 확인한다.

2.4 설치와 프로젝트에서 시작하기¶

Windows에서 처음 시작한다면 Codex 앱을 먼저 사용하고, 같은 프로젝트에서 CLI도 함께 익히는 방식을 권장한다. 앱은 폴더 열기·변경 내용 검토·내장 터미널을 한 화면에서 할 수 있고, CLI는 터미널 중심 작업과 자동화에 적합하다.

방법 A. Windows용 Codex 앱 사용하기¶

Microsoft Store에서 ChatGPT 데스크톱 앱을 설치하거나, PowerShell에서 아래 명령을 실행한다.
앱을 열어 ChatGPT 계정으로 로그인하고 Codex 작업 화면을 선택한다.
Ctrl + O로 Todo List 프로젝트 폴더를 연다. 예: C:\Users\내이름\Documents\todo-list
메시지 입력창 아래의 승인 설정은 Ask for approval(승인 요청)으로 둔다.
“현재 폴더를 읽고 Todo List 작업 계획만 작성해 주세요.”라고 요청한다.
계획을 승인한 뒤 구현을 요청하고, 앱의 변경 사항(Diff) 화면과 Preview 주소에서 결과를 확인한다.

# Windows PowerShell: ChatGPT 데스크톱 앱 설치
winget install --id 9PLM9XGG6VKS -s msstore

처음에는 앱 안의 Open folder, Diff, Integrated terminal만 익혀도 충분하다. 파일 수정과 명령 실행을 무제한 허용하는 Full access보다, 승인 요청 모드에서 한 단계씩 확인하는 편이 안전하다.

방법 B. Windows PowerShell에서 Codex CLI 사용하기¶

Windows Terminal 또는 PowerShell을 열고, 공식 설치 스크립트를 실행한다. 설치 스크립트는 반드시 공식 도메인인지 확인한 뒤 실행한다.

# Windows PowerShell: Codex CLI 설치
irm https://chatgpt.com/codex/install.ps1 | iex

# 프로젝트 폴더에서 시작
cd C:\Users\내이름\Documents\todo-list
codex

처음 실행한 뒤 /status로 현재 작업 폴더·권한·토큰 상태를 확인한다. /plan으로 계획부터 받고, /diff와 /review로 변경을 확인한다.

WSL은 언제 쓰나?¶

Linux 명령어가 꼭 필요하거나 이미 Ubuntu·WSL 환경에서 개발 중이라면 WSL2를 선택한다. 그 외에는 Windows 파일 시스템의 프로젝트를 Codex 앱 또는 PowerShell CLI로 여는 편이 처음에는 단순하다. WSL2를 쓴다면 프로젝트는 /mnt/c/...보다 Linux 홈 폴더 아래(예: ~/code/todo-list)에 두는 편이 빠르고 권한 문제가 적다.

# 관리자 PowerShell에서 WSL2 설치가 필요할 때만 실행
wsl --install

# WSL 터미널 안에서 Codex CLI 설치와 실행
curl -fsSL https://chatgpt.com/codex/install.sh | sh
cd ~/code/todo-list
codex

macOS/Linux와 Claude Code CLI¶

# macOS/Linux: Codex CLI
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Claude Code CLI
curl -fsSL https://claude.ai/install.sh | bash

두 도구 모두 반드시 작업할 프로젝트 폴더에서 시작한다. Claude Code는 claude --version 또는 claude doctor로 설치 상태를 확인할 수 있다.

cd todo-list
codex       # Codex CLI 시작
claude      # Claude Code 시작

2.5 자주 쓰는 CLI·세션 명령¶

목적	Codex	Claude Code
시작	`codex`	`claude`
현재 모델·상태 확인	`/status`	`/status`
모델 선택	`/model`	`/model` 또는 `claude --model sonnet`
먼저 계획 세우기	`/plan`	`/plan` 또는 `claude --permission-mode plan`
변경 내용 보기	`/diff`	`/diff`
변경 검토 요청	`/review`	`/review`
연결한 MCP 확인	`/mcp`	`/mcp` 또는 `claude mcp`
대화가 길어졌을 때	`/compact`	`/compact`

명령 이름과 선택지는 버전에 따라 달라질 수 있으므로, 세션 안에서 /를 입력해 목록을 확인하는 습관이 좋다. 권한을 모두 건너뛰는 옵션은 편리해 보여도 초보 프로젝트에서는 사용하지 않는다.

2.6 반복 규칙은 `AGENTS.md` 또는 `CLAUDE.md`에 짧게 남긴다¶

프로젝트별 규칙은 채팅마다 길게 붙이지 말고 파일에 적는다. Codex는 AGENTS.md를, Claude Code는 CLAUDE.md를 사용할 수 있으며, 두 도구를 함께 쓴다면 핵심 규칙을 두 파일에 같은 내용으로 둔다.

# 프로젝트 규칙
- 작업 전 현재 파일과 Git 상태를 읽고, 큰 변경은 계획부터 제시한다.
- .env, .dev.vars, Secret Key는 읽거나 출력하거나 커밋하지 않는다.
- DB·DNS·배포 변경은 사용자 승인을 받은 뒤에만 실행한다.
- 작업 뒤에는 테스트, git diff, 변경 파일과 남은 위험을 보고한다.

최근에는 저장소 규칙을 짧고 최신 상태로 유지하고, MCP에는 필요한 서비스만 연결하며, Preview 환경에서 먼저 확인하는 방식을 많이 쓴다. 에이전트가 많아져도 한 파일을 동시에 고치게 하지 말고, 작업을 분리한 뒤 Git 브랜치·diff로 합친다.

3. 도메인과 DNS — 인터넷의 주소록¶

3.1 IP 주소와 도메인¶

컴퓨터끼리는 203.0.113.10 같은 IP 주소로 통신한다. 하지만 사람에게는 example.com처럼 읽기 쉬운 이름이 편하다. 이 이름이 도메인이다.

사람: example.com을 열고 싶다
DNS:  example.com은 이 서비스로 연결해야 한다
브라우저: 연결된 서비스에 HTTPS 요청을 보낸다

용어	쉬운 설명	예
도메인	인터넷에서 쓰는 사람이 읽는 주소	`example.com`
루트 도메인(apex)	도메인의 가장 기본 주소	`example.com`
서브도메인	기본 주소 앞에 역할을 붙인 주소	`www.example.com`, `api.example.com`
도메인 등록기관(Registrar)	도메인을 구매·갱신하는 곳	Cloudflare Registrar 등
DNS	도메인과 서비스 연결 정보를 보관하는 주소록	Cloudflare DNS
네임서버	“이 도메인의 DNS는 내가 관리한다”라고 답하는 서버	Cloudflare가 알려 주는 2개 주소

도메인을 구매하는 곳과 DNS를 관리하는 곳은 같을 수도, 다를 수도 있다. 예를 들어 다른 등록기관에서 산 도메인을 Cloudflare DNS에서 관리해도 된다.

3.2 DNS 레코드 종류¶

레코드	연결 대상	예
`A`	IPv4 주소	`example.com` → `203.0.113.10`
`AAAA`	IPv6 주소	`example.com` → IPv6 주소
`CNAME`	다른 도메인 이름	`www` → `my-site.pages.dev`
`MX`	이메일 수신 서버	Google Workspace 메일 서버
`TXT`	인증·메일 보안 등 텍스트 정보	도메인 소유 확인, SPF

DNS를 옮길 때 기존 MX, TXT 레코드를 빠뜨리면 이메일 수신이나 도메인 인증이 망가질 수 있다. 네임서버를 바꾸기 전에 Cloudflare가 가져온 레코드를 반드시 대조한다.

3.3 Cloudflare를 DNS 관리자로 연결하기¶

도메인은 주소의 소유권, 네임서버는 그 주소의 안내판(DNS)을 누가 관리하는지 알려 주는 표지판이라고 생각하면 쉽다.

도메인 구매처: "example.com의 등록 정보는 여기서 관리합니다."
네임서버:     "example.com의 실제 연결 주소는 Cloudflare에 물어보세요."
Cloudflare:    "www는 Pages, api는 Worker로 연결합니다."

도메인을 다른 곳에서 구매했어도 DNS 관리는 Cloudflare에 맡길 수 있다.

Cloudflare에서 Add a site로 example.com을 추가한다.
Cloudflare가 알려 주는 두 개의 네임서버를 도메인 구매처의 네임서버 설정에 입력한다.
Zone 상태가 Active가 되면 이후 www, api 같은 DNS 레코드는 Cloudflare에서 관리한다.

네임서버를 바꾸기 전에 기존 MX, TXT 레코드가 Cloudflare에 있는지 한 번만 확인한다. 이 레코드가 빠지면 이메일이나 도메인 인증이 영향을 받을 수 있다.

4. 실습 프로젝트 구조¶

한 저장소에 클라이언트와 서버를 분리한다. 각 폴더가 어떤 역할인지 한눈에 보여서 협업에도 좋다.

todo-list/
├── frontend/                 # Cloudflare Pages에 배포할 웹페이지
│   ├── index.html
│   ├── style.css
│   └── app.js
├── worker/                   # Cloudflare Worker에 배포할 API 서버
│   ├── src/index.js
│   ├── migrations/           # D1 테이블 변경 이력
│   │   └── 0001_create_todos.sql
│   ├── wrangler.jsonc
│   └── .dev.vars             # 외부 API를 붙일 때만 쓰는 로컬 비밀 값
├── .gitignore
└── README.md

.gitignore에는 최소한 아래를 넣는다.

worker/.dev.vars
.env
node_modules/

D1 연결 자체에는 .dev.vars나 DB 비밀번호가 필요하지 않다. 나중에 외부 API를 붙여 실제 비밀 키를 적었다면 GitHub에 올리지 않는다. 이미 올렸다면 파일만 지우지 말고 키를 즉시 교체(rotate)한다.

5. Git과 GitHub — 변경을 기록하고 공유하기¶

5.1 왜 Git을 사용하는가¶

Git은 파일의 변경 이력을 남기는 버전 관리 도구다. 단순히 최종, 진짜최종, 진짜최종2 폴더를 복사하는 대신, 의미 있는 시점마다 어떤 파일을 왜 바꿨는지 기록한다.

잘못 수정했을 때 이전 상태와 비교하거나 돌아갈 수 있다.
에이전트가 바꾼 내용을 git diff로 확인한 뒤 필요한 변경만 기록할 수 있다.
기능별 변경을 작은 커밋으로 나누면 오류가 생긴 지점을 찾기 쉽다.
여러 사람이 서로 다른 브랜치에서 작업하고 검토한 뒤 합칠 수 있다.
GitHub와 연결하면 원격 보관, 코드 리뷰, 자동 테스트·배포를 사용할 수 있다.

Git과 GitHub는 같은 것이 아니다.

구분	Git	GitHub
정체	내 컴퓨터에서 동작하는 버전 관리 프로그램	Git 저장소를 인터넷에 보관·협업하는 서비스
인터넷	커밋까지는 인터넷 없이 가능	로그인과 인터넷 연결이 필요
주요 역할	변경 비교, 커밋, 브랜치, 이력 관리	원격 저장소, 공유, Pull Request, 코드 리뷰, Actions
비유	내 컴퓨터의 작업 일지와 체크포인트	작업 일지를 팀과 보관·공유하는 온라인 공간

즉, Git으로 기록하고 GitHub로 공유한다. GitHub 없이도 Git은 쓸 수 있고, git commit만으로는 GitHub에 업로드되지 않는다.

5.2 `add → commit → push` 흐름¶

작업 폴더에서 파일 수정
          ↓ git add
스테이징 영역: 다음 기록에 넣을 변경만 선택
          ↓ git commit
로컬 Git 저장소: 내 컴퓨터에 체크포인트 저장
          ↓ git push
GitHub 원격 저장소: 인터넷에 커밋 공유

명령	쉬운 뜻	확인할 점
`git status`	현재 바뀐 파일과 선택된 파일 확인	작업 전후에 가장 먼저 실행
`git diff`	아직 스테이징하지 않은 변경 비교	의도하지 않은 수정이 없는지 확인
`git add 파일명`	다음 커밋에 넣을 변경 선택	Secret·임시 파일을 선택하지 않음
`git diff --staged`	커밋될 내용을 마지막으로 확인	커밋 직전에 반드시 검토
`git commit -m "설명"`	선택한 변경을 로컬 이력에 저장	무엇을 왜 바꿨는지 짧게 작성
`git push`	로컬 커밋을 GitHub에 전송	외부 공유이므로 저장소와 브랜치 확인

git add .은 현재 폴더의 변경을 한꺼번에 선택하므로 편하지만, 초보 단계에서는 비밀 값이나 불필요한 파일까지 포함할 수 있다. 먼저 .gitignore를 준비하고 git status를 본 뒤 파일이나 폴더 이름을 구체적으로 지정하는 습관이 안전하다.

5.3 새 프로젝트를 GitHub에 올리는 기본 예¶

gh는 터미널에서 GitHub 로그인·저장소·Pull Request 등을 다루는 GitHub CLI다. 먼저 gh --version으로 설치 여부를 확인한다. 명령을 찾을 수 없으면 Codex나 Claude Code에 다음처럼 요청하면 운영체제를 확인하고 공식 설치 방법으로 설치하도록 도와줄 수 있다.

현재 운영체제를 확인하고 GitHub 공식 문서를 기준으로 GitHub CLI(gh)를 설치해 주세요.
설치 전에 실행할 명령과 변경 사항을 설명하고 승인을 기다리세요.
설치 후 gh --version으로 확인하되, 로그인과 저장소 생성은 아직 하지 마세요.

설치가 끝나면 터미널에서 gh auth login을 한 번 실행해 GitHub 인증을 완료해야 한다. 화면 안내에 따라 GitHub.com과 HTTPS를 선택하고 브라우저에서 로그인·승인한다. 인증 정보가 저장되므로 일반적으로 매번 로그인할 필요는 없다. 일회용 코드나 토큰을 Codex·Claude Code 대화창에 붙이지 말고, 인증 화면에는 사람이 직접 입력한다.

아래 흐름은 Todo List 폴더에서 실행한다. gh repo create와 git push는 GitHub에 외부 변경을 만드는 명령이므로 계정·공개 범위·저장소 이름을 먼저 확인한다.

cd todo-list

# 현재 폴더에서 Git 이력 관리를 시작한다.
git init
git status

# 다음 커밋에 넣을 파일을 선택하고 내용을 검토한다.
git add .gitignore README.md frontend worker
git diff --staged

# 내 컴퓨터의 Git 이력에 저장한다.
git commit -m "feat: Todo List 기본 구조 추가"
git branch -M main

# GitHub 로그인 후 비공개 원격 저장소를 연결한다.
gh auth login
gh repo create todo-list --private --source=. --remote=origin

# 로컬 main 커밋을 GitHub에 처음 전송한다.
git push -u origin main

origin은 연결한 원격 저장소의 기본 별칭이고, main은 기본 브랜치 이름이다. -u는 다음부터 git push만 입력해도 같은 원격 브랜치로 보내도록 연결을 기억하게 한다.

5.4 에이전트에게 안전하게 요청하기¶

현재 todo-list 프로젝트에서 git status, git diff, .gitignore를 읽어 주세요.

- 변경 파일을 기능별로 나누어 커밋 계획만 제시하세요.
- Secret, .env, .dev.vars, 생성 파일, node_modules는 포함하지 마세요.
- git add, commit, push, gh repo create는 아직 실행하지 마세요.
- 커밋할 파일 목록과 제안 메시지를 보여 주고 승인을 기다리세요.

승인 뒤에도 먼저 git diff --staged를 보고 커밋한다. push, 저장소 생성, 공개 범위 변경은 로컬 커밋과 별개의 외부 작업이므로 다시 확인한다. 비밀 값이 한 번이라도 커밋됐다면 이후 파일에서 지우는 것만으로는 Git 이력에서 사라지지 않으므로 해당 키를 즉시 교체한다.

6. 데이터 저장소 만들기 — Cloudflare D1¶

Cloudflare D1은 Cloudflare가 운영하는 서버리스 SQL 데이터베이스다. 표 형태로 데이터를 저장하고 SQL로 읽고 쓰며, SQLite와 익숙한 문법을 사용한다. 이번 실습에서는 Pages·Worker·DB·DNS를 모두 Cloudflare 안에서 구성한다.

Worker는 비밀번호나 DB 주소를 코드에 넣지 않고 DB라는 바인딩으로 D1을 사용한다. 코드에서는 env.DB라고 부르면 된다.

6.1 에이전트에게 D1 구성을 요청하는 프롬프트¶

Cloudflare MCP가 연결되어 있으면 현재 계정과 프로젝트를 확인하는 데 사용하고, 실제 프로젝트 생성·로컬 시험은 Wrangler CLI를 기준으로 진행한다. Cloudflare 계정에 빈 D1을 만드는 작업도 외부 변경이므로 먼저 승인을 받고, 테이블 구조는 로컬 DB에서 시험한 뒤 원격에 적용한다.

현재 todo-list/worker 프로젝트를 읽고 Cloudflare D1 구성 계획을 작성해 주세요.
Cloudflare MCP가 연결되어 있으면 먼저 계정·Worker·D1 상태를 읽기 전용으로 확인하고,
그렇지 않으면 Wrangler CLI만 사용하세요.

- D1 데이터베이스 이름은 todo-list-db, Worker 바인딩 이름은 DB로 합니다.
- todos 테이블에는 id, title, is_done, created_at 열이 필요합니다.
- 스키마 변경은 migrations 폴더의 SQL 파일로 남깁니다.
- 먼저 생성할 파일, 실행할 명령, 되돌리는 방법을 설명하세요.
- 승인 후 빈 원격 D1과 DB 바인딩을 만들고, migration은 로컬 DB에만 적용해 조회 결과를 보고하세요.
- 원격 migration 적용·Worker 배포는 별도 승인 전에는 하지 마세요.
- 기존 데이터 삭제와 DROP·TRUNCATE·전체 DELETE는 실행하지 마세요.

에이전트가 제안할 대표 명령은 다음과 같다. 직접 외우기보다 로컬인지 원격인지를 확인하는 데 집중한다.

# D1 생성 후 Wrangler가 wrangler.jsonc에 DB 바인딩을 추가하도록 한다.
npx wrangler@latest d1 create todo-list-db

# 스키마 변경 파일을 만든다.
npx wrangler d1 migrations create todo-list-db create_todos

# 내 컴퓨터의 로컬 D1에 먼저 적용하고 확인한다.
npx wrangler d1 migrations apply todo-list-db --local
npx wrangler d1 execute todo-list-db --local --command="SELECT * FROM todos"

wrangler d1 create가 설정 추가 여부를 물으면 승인해 바인딩 이름을 DB로 맞춘다. 원격 DB에 적용하는 --remote는 로컬 테스트와 SQL 검토가 끝난 뒤 별도로 승인한다.

에이전트가 읽는 프로젝트 규칙은 다음 정도면 충분하다.

## Cloudflare D1
- Worker에서는 D1을 env.DB 바인딩으로 사용하고 DB 비밀번호를 만들지 않는다.
- 스키마 변경은 migrations 폴더에 기록하고 로컬 DB에 먼저 적용한다.
- 원격 migration, 배포, DROP, TRUNCATE, 전체 DELETE는 사용자 승인 뒤에만 실행한다.
- 사용자 값은 SQL 문자열에 직접 붙이지 말고 prepare().bind()로 전달한다.

prepare().bind()는 SQL 문장과 사용자 입력값을 분리해 전달한다. 제목에 특수문자가 들어가도 SQL 명령으로 오해하지 않게 해 주므로, SQL 삽입 공격을 막는 기본 습관이다.

7. 서버리스 API 서버 만들기 — Cloudflare Worker¶

Cloudflare Worker는 요청이 들어올 때 JavaScript/TypeScript 코드를 실행하는 서버리스 API 서버다. 여기서 서버리스는 서버가 없다는 뜻이 아니다. 서버 장비 준비, 운영체제 설치, 계속 켜 두기, 기본적인 확장 같은 운영을 Cloudflare가 맡고 우리는 API 코드와 데이터 규칙에 집중한다는 뜻이다.

이번 실습의 서버 구조: 클라이언트가 /todos를 요청하면 서버리스 Worker가 입력을 검사하고, env.DB 바인딩으로 Cloudflare D1을 조회하거나 수정한 뒤 JSON을 돌려준다.

이 강의에서는 Worker가 /todos API를 제공하고 D1에 데이터를 저장한다. 코드를 한 줄씩 직접 작성하기보다, Codex에게 Wrangler CLI 또는 연결된 Cloudflare MCP를 사용해 만들도록 요청한다.

7.1 Wrangler CLI로 하는 기본 흐름¶

Wrangler는 Cloudflare 개발·배포 명령을 터미널에서 실행하는 도구다. 처음에는 Codex가 아래 명령을 제안·실행하고, 우리는 결과를 확인하면 된다.

cd todo-list
npm create cloudflare@latest worker
cd worker
npx wrangler login
npx wrangler dev

wrangler dev는 내 컴퓨터에서 시험하는 명령이다. 실제 인터넷에 공개하는 npx wrangler deploy는 테스트 결과를 확인한 뒤에만 실행한다.

7.2 Codex에게 Worker를 만드는 프롬프트¶

현재 todo-list 작업 폴더에서 Cloudflare MCP가 연결되어 있으면 그 도구를,
그렇지 않으면 Wrangler CLI를 사용해 Todo List API Worker를 만들어 주세요.

- GET /todos: 목록 조회, POST /todos: 할 일 추가,
  PATCH /todos/:id: 완료 상태 변경을 구현합니다.
- wrangler.jsonc의 DB 바인딩을 사용하고 Worker 코드에서는 env.DB로 D1에 접근합니다.
- 사용자 입력은 SQL에 직접 이어 붙이지 말고 prepare().bind()로 전달합니다.
- Pages의 실제 주소만 API 호출을 허용하도록 최소한으로 설정합니다.
- 먼저 현재 파일과 Wrangler 설정을 읽고 작업 계획을 보여 주세요.
- 로컬 D1 migration을 적용한 뒤 npx wrangler dev로 API를 테스트하고,
  실행한 명령·결과·남은 위험만 보고해 주세요.
- 원격 D1 변경, 배포, Secret 생성·변경, 직접 도메인 연결은 제 승인 전에는 하지 마세요.

7.3 Worker를 위한 에이전트 규칙¶

프로젝트의 AGENTS.md에 다음처럼 짧게 적어 두면 반복 설명을 줄일 수 있다.

## Cloudflare Worker
- Cloudflare 상태는 MCP 또는 Wrangler CLI로 먼저 읽고, 변경 계획을 제시한다.
- D1은 env.DB 바인딩으로 접근하고 사용자 입력은 prepare().bind()로 전달한다.
- 비밀 값은 Cloudflare Secret으로만 다루며 파일·코드·Git에 기록하지 않는다.
- 로컬 DB와 API를 먼저 시험하고, remote migration·deploy·route·custom domain·DNS 변경은 사용자 승인 뒤에만 한다.
- API는 필요한 요청 방식과 입력만 허용하고, Pages 주소 하나만 교차 출처 요청을 허용한다.

Cloudflare MCP가 연결되어 있다면 먼저 Worker·도메인·바인딩 정보를 읽기 전용으로 확인해 달라고 요청한다. 연결되어 있지 않다면 Wrangler CLI만으로 프로젝트 생성·로컬 실행·배포를 할 수 있다.

8. 웹페이지 만들기 — Cloudflare Pages¶

Cloudflare Pages는 HTML, CSS, JavaScript 같은 정적 파일을 전 세계에 배포하는 서비스다. Pages는 화면을 전달하고, 동적인 데이터 처리는 별도 Worker가 담당한다. 화면 코드와 배포도 Codex가 Cloudflare MCP 또는 Wrangler CLI를 기준으로 준비하게 한다.

8.1 Codex에게 웹페이지를 만드는 프롬프트¶

현재 todo-list 프로젝트에 Cloudflare Pages로 배포할 프론트엔드를 만들어 주세요.

- HTML, CSS, JavaScript로 접근하기 쉬운 Todo List 화면을 만듭니다.
- 목록 보기, 할 일 추가, 완료 체크를 Worker API와 연결합니다.
- API 주소는 설정값으로 분리하고, 비밀 키는 브라우저 코드에 절대 넣지 마세요.
- 모바일에서도 읽기 쉽고, 입력칸·버튼·상태 메시지의 용도를 알 수 있게 만드세요.
- 먼저 기존 파일과 배포 구조를 읽고 계획을 제시하세요.
- 구현 후 로컬 확인 방법과 변경 파일 목록을 보고하세요.
- 실제 Pages 배포와 도메인 연결은 제 승인 전에는 하지 마세요.

8.2 Wrangler CLI로 Preview 배포하기¶

Codex가 만든 정적 파일 폴더가 frontend라면, 승인 후 다음 명령으로 Preview 주소를 받을 수 있다.

npx wrangler pages deploy frontend --project-name todo-list

Preview 주소에서 화면·추가·완료 체크를 확인한 뒤에만 운영 배포를 요청한다. Pages는 공개 웹페이지이므로 OpenAI 키, 텔레그램 토큰 같은 비밀 값은 절대로 넣지 않는다. D1은 Pages가 아니라 Worker의 바인딩을 통해서만 사용한다.

8.3 Pages를 위한 에이전트 규칙¶

## Cloudflare Pages
- Cloudflare MCP 또는 Wrangler CLI로 현재 프로젝트와 배포 대상 폴더를 먼저 확인한다.
- 프론트엔드에는 공개 가능한 API 주소만 두고 모든 비밀 값은 제외한다.
- 먼저 Preview를 만들고, production 배포·custom domain·DNS 변경은 사용자 승인 뒤에만 한다.
- Pages 주소와 Worker의 허용 출처가 같은지 배포 전에 확인한다.

페이지와 API의 주소가 다르면 Worker에 Pages 주소만 허용해야 한다. 이 설정의 이름은 CORS지만, 여기서는 “페이지 주소와 Worker의 허용 주소를 일치시킨다”만 기억하면 충분하다.

9. 직접 도메인 연결 — www와 api 분리¶

이제 아래 주소를 만든다.

https://www.example.com       → Cloudflare Pages (웹페이지)
https://api.example.com       → Cloudflare Worker (API 서버)

9.1 Codex에게 도메인 연결을 계획하게 하기¶

도메인과 DNS는 잘못 바꾸면 기존 웹사이트·이메일에 영향을 줄 수 있다. 따라서 먼저 읽기 전용 점검과 계획, 그 다음 승인, 마지막으로 변경 순서를 지킨다.

Cloudflare MCP가 연결되어 있으면 MCP를, 아니면 Wrangler CLI와 Cloudflare 설정 파일을 사용해
현재 example.com의 Pages·Worker·DNS 구성을 읽기 전용으로 점검해 주세요.

- www.example.com은 Todo List Pages, api.example.com은 Todo List Worker에 연결할 계획입니다.
- 기존 A, CNAME, MX, TXT 레코드와 이미 연결된 custom domain을 나열하세요.
- 변경이 필요한 항목, 기존 이메일에 미치는 영향, 예상 결과를 계획으로만 작성하세요.
- DNS 레코드 변경, custom domain 생성, Worker 배포는 실행하지 마세요.

승인 후에는 같은 에이전트에게 www는 Pages Custom Domain, api는 Worker Custom Domain으로 연결하도록 요청한다. 완료 보고에는 두 HTTPS 주소, 바뀐 DNS 항목, Pages 주소와 Worker 허용 출처가 일치하는지 포함하게 한다.

9.2 연결 뒤 사람이 확인할 것¶

https://www.example.com에서 Todo List 화면이 열린다.
https://api.example.com/todos가 JSON 응답을 준다.
기존 이메일을 사용한다면 MX·SPF·DKIM 관련 레코드가 유지된다.
두 주소 모두 HTTPS 자물쇠가 표시된다.

10. 배포 전·후 점검표¶

10.1 기능 점검¶

[ ] https://프로젝트.pages.dev에서 화면이 열린다.
[ ] GET https://api.example.com/todos가 200과 JSON 배열을 돌려준다.
[ ] 폼을 제출하면 201이 나오고, 새 할 일이 목록에 보인다.
[ ] 체크 상자를 누르면 완료 상태가 바뀐다.
[ ] 새로고침 후에도 할 일이 남아 있다.

10.2 도메인·DNS 점검¶

[ ] Cloudflare Zone 상태가 Active다.
[ ] 기존 이메일을 쓴다면 MX·SPF·DKIM 관련 레코드가 유지되어 있다.
[ ] www.example.com이 Pages Custom domain에 연결되어 있다.
[ ] api.example.com이 Worker Custom Domain에 연결되어 있다.
[ ] 두 주소 모두 브라우저 자물쇠 아이콘(HTTPS)을 표시한다.

10.3 보안 점검¶

[ ] .dev.vars와 .env는 Git에 포함되지 않는다.
[ ] D1 바인딩 이름이 DB이고 Worker가 env.DB로 접근한다.
[ ] 원격 D1 migration은 로컬 시험과 SQL 검토 뒤에만 적용했다.
[ ] SQL에 사용자 입력을 붙이지 않고 prepare().bind()를 사용한다.
[ ] Worker는 입력 길이와 요청 방식을 검증한다.
[ ] 사용자 입력을 화면에 표시할 때 innerHTML이 아닌 textContent를 쓴다.
[ ] Worker의 허용 페이지 주소가 실제 Pages 도메인과 일치한다.

11. 오늘의 핵심 정리¶

도메인 구매/보유
    ↓
Cloudflare에 Zone 추가 → 네임서버 변경 → DNS 관리 시작
    ↓
프로젝트 폴더에서 git init → GitHub 원격 저장소 연결
    ↓
D1 생성 → DB 바인딩 연결 → migration을 로컬에서 먼저 적용
    ↓
Worker에 API 작성 → env.DB로 D1 조회·저장
    ↓
Pages에 화면 배포 → JavaScript fetch로 Worker API 호출
    ↓
www는 Pages, api는 Worker Custom Domain으로 연결

클라이언트는 화면을 보여 주고 HTTP 요청을 보낸다.
서버는 신뢰할 수 없는 입력을 검사하고, 비밀 값을 이용해 필요한 작업만 한다.
데이터베이스는 데이터를 오래 보관하며 테이블 구조와 제약 조건으로 잘못된 값을 줄인다.
DNS는 도메인을 올바른 서비스로 연결한다. 네임서버를 Cloudflare로 바꾸면 DNS 관리 장소도 Cloudflare로 바뀐다.
Pages는 프론트엔드 배포, Worker는 API 실행, D1은 SQL 데이터 저장에 각각 집중한다.
Git은 변경을 로컬 이력에 기록하고, GitHub는 승인한 커밋을 원격에서 보관·공유한다.

다음 확장 과제¶

DELETE /todos/:id와 마감일·검색·페이지네이션 추가하기
Cloudflare Access로 동아리 내부 사용자만 서비스에 접근하게 만들기
Worker에 Rate Limiting 또는 Turnstile을 추가해 스팸 방지하기
example.com과 www.example.com 중 하나로 리디렉션 통일하기
GitHub Actions 또는 Cloudflare 배포 미리보기로 팀 코드 리뷰 흐름 만들기

12. 에이전트로 개발할 때 실전 팁¶

작업 폴더부터 확인한다. 터미널을 열면 pwd와 ls로 현재 위치와 파일을 확인하고, cd todo-list로 프로젝트 폴더에 들어간 뒤 codex 또는 claude를 실행한다. 다른 폴더에서 에이전트를 시작하면 엉뚱한 파일을 읽거나 만들 수 있다.
처음에는 플랜 모드만 사용한다. “현재 파일을 읽고 작업 계획만 작성해 주세요. 아직 수정·설치·배포하지 마세요.”라고 요청한 뒤, 바꿀 파일과 외부 서비스가 맞는지 사람이 확인한다.
한 번에 기능 하나만 맡긴다. “웹사이트를 전부 만들어 주세요.”보다 “Todo 입력 폼을 만들고 로컬에서 확인해 주세요.”처럼 범위를 작게 준다. 화면, Worker API, D1, 도메인 연결을 차례대로 진행하면 오류 원인을 찾기 쉽다.
완료 기준을 문장으로 알려 준다. 무엇을 만들지뿐 아니라 “모바일에서 보이고, 새로고침 후 데이터가 남고, 비밀 키가 Git에 없고, 실행한 테스트 결과를 보고할 것”처럼 성공 조건까지 적는다.
Git을 작업 전후의 안전장치로 사용한다. 새 프로젝트는 git init으로 시작하고, GitHub CLI를 쓴다면 gh repo create로 원격 저장소를 연결한다. 작업 전후에는 git status와 git diff를 보고, 의미 있는 작은 단위로 커밋한다.
보고서는 사람이 읽기 쉬운 형태로 받는다. 에이전트에게 “변경 파일, 실행한 명령, 테스트 결과, 남은 주의점을 짧은 HTML 보고서로 작성해 주세요.”라고 요청한다. 학습 메모는 Markdown으로 남기고, 공유할 자료는 HTML이나 PDF로 변환하면 읽기 편하다.
외부 서비스는 읽기 전용 점검부터 한다. Cloudflare MCP에는 개발용 계정과 필요한 기능만 연결하고, 먼저 현재 D1·Worker·DNS 상태를 읽게 한다. 원격 DB 변경, Secret 등록, DNS 수정, 운영 배포는 계획을 확인한 뒤 따로 승인한다.
비밀 값은 대화와 코드에 붙이지 않는다. API Key, Secret, 토큰은 .env, .dev.vars 또는 배포 서비스의 Secret 기능으로 관리한다. 화면 캡처·HTML 보고서·GitHub에도 값이 나오지 않았는지 확인한다.
에이전트의 ‘완료’ 보고를 그대로 믿지 않는다. Preview 주소를 직접 열고, Todo 추가·완료·새로고침을 확인한다. 그다음 git diff를 보여 주고 “누락, 보안 위험, 불필요한 코드, 테스트 부족을 수정 없이 검토해 주세요.”라고 요청한다.
새 세션에서 한 번 더 검토한다. 구현에 사용한 대화와 분리된 새 Codex·Claude Code 세션에 계획과 diff를 주면, 앞선 판단을 그대로 따라가지 않는 독립 검토를 받을 수 있다.
병렬 작업은 서로 겹치지 않을 때만 사용한다. 문서 조사와 코드 검토처럼 독립된 일은 여러 에이전트에 나눌 수 있지만, 같은 파일을 동시에 수정하게 하지 않는다. Worktree를 사용했다면 결과가 어느 브랜치에 있는지 확인하고 필요한 변경만 main에 병합한다.
자동화는 수동 흐름이 안정된 뒤 추가한다. Todo List를 직접 실행·검증할 수 있게 된 다음 CI/CD, 정기 실행, 작업 완료 Telegram 알림을 붙인다. 자동화가 실패했을 때 사람이 어느 단계부터 다시 실행할지 알아야 한다.
공식 API와 문서를 먼저 찾는다. 뉴스나 블로그 데이터를 다룰 때는 공식 API와 이용 약관을 먼저 확인한다. 크롤링 도구는 허용된 데이터에만 사용하고, 요청 속도·로그인·유료 콘텐츠 제한을 지킨다.
긴 대화는 정리하고 새 작업을 시작한다. /status로 모델·작업 위치를 확인하고, 컨텍스트가 길어지면 /compact로 결정 사항을 요약한다. 새 기능은 새 세션에서 시작하되, 현재 상태와 남은 일을 짧게 전달한다.

바로 사용할 수 있는 기본 요청은 다음과 같다.

현재 todo-list 프로젝트를 먼저 읽고 Git 상태를 확인해 주세요.

목표: [이번에 만들 기능 한 가지]
제약: 비밀 값 출력 금지, 기존 기능 유지, 운영 배포 금지
완료 기준: [사용자가 직접 확인할 동작]과 테스트 결과 보고

지금은 파일을 수정하지 말고 계획만 작성해 주세요.
제가 계획을 확인한 뒤 구현을 요청하겠습니다.

13. 웹 언어·프레임워크·데이터 저장소 한눈에 보기¶

이 장은 전부 배워야 할 목록이 아니라, 프로젝트 설명에서 자주 만나는 이름을 어디에 쓰는지 구분하는 지도다. 이번 Todo List는 브라우저의 HTML·CSS·JavaScript, Worker의 JavaScript 또는 TypeScript, D1을 사용하면 충분하다.

13.1 언어와 대표 프레임워크¶

프레임워크는 로그인·주소 처리·화면 구성처럼 반복되는 웹 개발 구조를 미리 제공하는 도구다. 언어와 프레임워크는 하나씩 선택하면 되며, 아래 목록을 모두 섞어 쓸 필요는 없다.

언어	웹 프론트엔드에서의 쓰임	백엔드에서의 쓰임	대표 프레임워크·실행 환경
JavaScript(JS)	브라우저가 직접 실행하는 기본 동작 언어	Node.js나 Worker에서 API 작성	React, Express, Node.js
TypeScript(TS)	JavaScript에 타입 검사를 더해 큰 화면 코드를 안전하게 관리	Worker·Node.js API에서 실수를 미리 발견	React·Next.js, Node.js·Express
Python	일반 웹 브라우저 화면에는 거의 직접 쓰지 않음	데이터 수집·분석·AI·API 자동화에 강함	FastAPI·Django·Flask
Java	일반 웹 브라우저 화면에는 직접 쓰지 않음	대규모 기업 서비스와 오래 운영하는 서버에 널리 사용	Spring Boot
C	WebAssembly로 변환하는 특수 경우 외에는 화면에 거의 쓰지 않음	운영체제·장치·고성능 라이브러리 같은 낮은 단계에 주로 사용	범용 웹 입문용 프레임워크보다 시스템 라이브러리 중심
C++	WebAssembly로 고성능 모듈을 넣는 특수 경우에 사용	게임·미디어·고성능 서버와 기존 시스템에 사용	WebAssembly·고성능 서버 라이브러리
Rust	WebAssembly 모듈이나 특수한 고성능 화면 기능에 사용	안전성과 성능이 중요한 API·인프라에 사용	WebAssembly·시스템 도구

브라우저 화면은 결국 HTML·CSS·JavaScript로 전달된다. Python·Java·C·C++·Rust 백엔드를 선택해도 프론트엔드는 HTTP API를 호출하므로 서로 다른 언어를 함께 사용할 수 있다. 다만 Cloudflare Workers 실습은 JavaScript·TypeScript가 가장 단순하다. 현재 Cloudflare 공식 문서에서 Python Workers와 Rust는 Beta로 표시되므로 목적이 분명할 때 선택한다. Java·C·C++ 서버를 그대로 운영해야 한다면 일반 서버나 컨테이너를 제공하는 AWS 쪽이 더 자연스럽다.

13.2 관계형 DB, NoSQL, 객체 저장소¶

RDS는 데이터베이스 언어가 아니라 AWS가 MySQL·PostgreSQL·Oracle 같은 관계형 DB의 설치·백업·장애 복구를 대신 관리하는 서비스다. NoSQL은 고정된 표와 SQL만을 중심으로 하지 않고 문서·키와 값 같은 형태로 데이터를 저장하는 DB 범주다.

종류·제품	적합한 데이터와 특징	AWS에서의 선택	Cloudflare에서의 선택
SQLite / D1	작은 웹서비스의 표·행 데이터와 SQL. D1은 SQLite SQL 의미를 사용하는 서버리스 DB	완전히 같은 관리형 SQLite 서비스는 없음	D1; 이번 Todo List의 선택
MySQL	회원·주문·게시글처럼 관계와 트랜잭션이 중요한 일반 웹 데이터	Amazon RDS for MySQL 또는 Aurora MySQL	직접 대응 DB는 없음; 외부 MySQL을 Hyperdrive로 연결 가능
PostgreSQL	복잡한 SQL·확장 기능·분석 쿼리가 필요한 관계형 데이터	Amazon RDS for PostgreSQL 또는 Aurora PostgreSQL	직접 대응 DB는 없음; 외부 PostgreSQL을 Hyperdrive로 연결 가능
Oracle Database	기존 대기업 업무 시스템과 Oracle 전용 기능·지원이 필요한 경우	Amazon RDS for Oracle	직접 대응 없음
MongoDB	구조가 자주 달라지는 JSON과 비슷한 문서 데이터	MongoDB Atlas를 AWS에서 사용하거나 MongoDB 호환 Amazon DocumentDB 검토	직접 대응 없음; Worker에서 외부 서비스 API로 연결
키-값 NoSQL	키 하나로 값을 빠르게 찾는 설정·세션·캐시	DynamoDB; 캐시는 ElastiCache도 검토	Workers KV; 강한 순서 보장이 필요하면 Durable Objects도 검토
객체 저장소	이미지·PDF·원본 JSON·백업처럼 큰 파일 저장. SQL 검색용 DB가 아님	Amazon S3	Cloudflare R2; S3 호환 API 제공

MongoDB와 Amazon DocumentDB, DynamoDB와 Workers KV는 완전히 같은 제품이 아니다. 데이터 구조·쿼리·일관성·가격을 확인한 뒤 선택한다. Todo 제목과 완료 상태처럼 표로 조회·수정할 데이터는 D1에, 첨부 이미지나 수집한 원본 파일은 R2에 두는 식으로 역할을 나눈다.

13.3 AWS와 Cloudflare에서 비슷한 역할 찾기¶

필요한 역할	AWS의 대표 선택	Cloudflare의 대표 선택	같은 점과 차이
웹 프론트엔드 배포	S3 + CloudFront	Pages	정적 파일과 프론트엔드를 인터넷에 전달
서버리스 API 실행	Lambda + API Gateway	Workers	요청이 올 때 코드를 실행하지만 실행 환경과 지원 언어가 다름
관계형 데이터 저장	RDS·Aurora	D1	둘 다 SQL을 쓰지만 D1은 SQLite 계열이며 MySQL·PostgreSQL 서버와 같지 않음
키-값·NoSQL 저장	DynamoDB	Workers KV·Durable Objects	비슷한 용도가 있으나 쿼리와 일관성 모델이 다름
파일·객체 저장	S3	R2	둘 다 버킷에 객체를 저장하고 R2는 S3 호환 API를 제공
DNS 관리	Route 53	Cloudflare DNS	도메인 이름을 서비스 주소에 연결
CDN	CloudFront	Cloudflare CDN	사용자 가까운 위치에서 콘텐츠를 전달

이번 실습은 한 계정에서 흐름을 보기 쉽도록 Pages → Worker → D1, 파일이 필요해지면 R2, 주소는 Cloudflare DNS로 통일한다. AWS 표는 다른 프로젝트를 읽을 때 같은 역할을 찾기 위한 참고다.

14. 비전공자를 위한 용어집¶

이 용어집은 암기 목록이 아니다. 강의 중 낯선 단어가 나오면 찾아보는 번역표로 사용한다.

14.1 웹과 화면¶

용어	비전공자용 설명
Todo List	해야 할 일을 적고 완료 여부를 표시하는 목록 서비스
웹서비스	브라우저로 접속해 화면을 보고 기능을 사용하는 프로그램
브라우저	Chrome, Safari처럼 웹페이지를 여는 프로그램
클라이언트	서버에 필요한 일을 요청하는 쪽; 이 강의에서는 주로 브라우저
프론트엔드	사용자가 직접 보는 화면과 클릭·입력을 처리하는 부분
서버	클라이언트의 요청을 받아 규칙을 적용하고 결과를 돌려주는 쪽
백엔드	서버 코드, 데이터 처리, 권한 확인처럼 화면 뒤에서 일하는 부분
API	클라이언트가 서버 기능을 정해진 방식으로 요청하는 창구
URL	인터넷 자원의 전체 주소; 예: `https://api.example.com/todos`
호스트 이름	URL에서 접속할 서버를 가리키는 이름; 예: `api.example.com`
경로(Path)	서버 안에서 원하는 기능이나 자원의 위치; 예: `/todos`
HTTP	브라우저와 서버가 요청·응답을 주고받는 기본 통신 규칙
HTTPS	HTTP 내용을 암호화해 전달하는 안전한 통신 방식
요청(Request)	클라이언트가 서버에 보내는 “이 일을 해 주세요”라는 메시지
응답(Response)	서버가 요청을 처리한 뒤 돌려주는 결과 메시지
JSON	클라이언트와 서버가 데이터를 주고받을 때 자주 쓰는 텍스트 형식
배열(Array)	여러 값을 순서대로 묶은 목록; JSON에서는 `[ ]`로 표시
ID	데이터 한 건을 다른 데이터와 구별하는 고유 번호나 문자열
GET	데이터를 조회해 달라는 HTTP 방식
POST	새 데이터를 만들어 달라는 HTTP 방식
PATCH	기존 데이터의 일부를 바꿔 달라는 HTTP 방식
DELETE	데이터를 지워 달라는 HTTP 방식
상태 코드	요청 결과를 숫자로 알리는 신호; `200`은 성공, `404`는 없음
HTML	웹페이지의 제목·입력칸·버튼 같은 구조를 만드는 언어
CSS	글꼴·색상·간격·배치처럼 웹페이지의 모양을 정하는 언어
JavaScript	클릭·입력·API 호출처럼 웹페이지의 동작을 만드는 언어
TypeScript	JavaScript에 데이터 종류 검사를 더해 실수를 미리 찾는 언어
Python	데이터 수집·분석·AI·API 자동화에 자주 쓰는 프로그래밍 언어
Java	기업용 서버와 Android 앱 등에 널리 쓰이는 프로그래밍 언어
C·C++	운영체제·장치·게임·고성능 프로그램에 많이 쓰는 언어
Rust	메모리 안전성과 성능을 함께 중시하는 프로그래밍 언어
프레임워크	웹 개발의 반복 구조와 규칙을 미리 제공하는 도구 묶음
React·Next.js	JavaScript·TypeScript로 웹 화면을 구성할 때 쓰는 대표 도구
Express	Node.js로 API 서버를 만들 때 쓰는 대표 프레임워크
FastAPI·Django·Flask	Python으로 API와 웹 서버를 만들 때 쓰는 대표 프레임워크
Spring Boot	Java로 웹 백엔드를 만들 때 쓰는 대표 프레임워크
Node.js	JavaScript·TypeScript를 브라우저 밖의 서버와 개발 도구에서 실행하는 환경
WebAssembly	C·C++·Rust 등으로 만든 코드를 브라우저나 지원 실행 환경에서 돌리는 형식
폼(Form)	사용자가 글자·선택값을 입력해 서버로 보내는 화면 영역
정적 파일	서버가 매번 새로 계산하지 않고 그대로 전달하는 HTML·CSS·이미지 파일
CORS	다른 웹 주소의 API 호출을 어느 페이지에 허용할지 정하는 브라우저 보안 규칙
출처(Origin)	`프로토콜 + 호스트 + 포트`로 구분하는 웹 주소의 소속
입력 검증	사용자가 보낸 값의 형식·길이·범위가 안전한지 서버에서 확인하는 일
`textContent`	사용자 글자를 HTML 코드로 실행하지 않고 안전한 텍스트로 표시하는 방법
`innerHTML`	문자열을 HTML 구조로 해석해 넣는 기능; 사용자 입력에 그대로 쓰면 위험할 수 있음

14.2 도메인과 Cloudflare¶

용어	비전공자용 설명
IP 주소	인터넷에서 컴퓨터나 서비스 위치를 구분하는 숫자 주소
도메인	사람이 읽기 쉬운 인터넷 주소; 예: `example.com`
루트 도메인(Apex)	`www` 같은 앞부분이 없는 기본 도메인 주소
서브도메인	역할을 나누려고 기본 도메인 앞에 붙인 이름; 예: `api.example.com`
도메인 등록기관(Registrar)	도메인을 구매하고 갱신하는 업체
DNS	도메인을 실제 서비스 위치와 연결하는 인터넷 주소록
네임서버	그 도메인의 DNS 정보를 어디에서 관리하는지 알려 주는 서버
DNS Zone	Cloudflare에서 한 도메인의 DNS 레코드를 묶어 관리하는 영역
Active	네임서버 연결이 확인되어 Cloudflare Zone이 정상 작동하는 상태
DNS 레코드	도메인을 웹·메일·인증 서비스와 연결하는 한 줄의 설정 정보
A 레코드	도메인을 IPv4 숫자 주소에 연결하는 DNS 레코드
AAAA 레코드	도메인을 IPv6 숫자 주소에 연결하는 DNS 레코드
CNAME	한 도메인 이름을 다른 도메인 이름에 연결하는 DNS 레코드
MX	해당 도메인의 이메일을 받을 서버를 지정하는 DNS 레코드
TXT	도메인 소유 확인이나 메일 보안 정보를 적는 DNS 레코드
SPF·DKIM	이메일이 위조되지 않았는지 확인하는 데 쓰는 DNS 기반 메일 보안 설정
CDN	웹 파일을 여러 지역에 복사해 사용자 가까운 곳에서 빠르게 전달하는 서비스
Cloudflare Pages	HTML·CSS·JavaScript 같은 웹페이지 파일을 배포하는 서비스
Cloudflare Worker	서버 컴퓨터를 직접 관리하지 않고 API 코드를 실행하는 서비스
AWS	서버·DB·파일 저장소 등 다양한 클라우드 서비스를 제공하는 플랫폼
AWS Lambda	요청이나 이벤트가 있을 때 서버 코드를 실행하는 AWS 서비스
API Gateway	인터넷 요청을 Lambda 같은 AWS 백엔드로 전달하는 API 입구 서비스
CloudFront	사용자 가까운 위치에서 웹 콘텐츠를 전달하는 AWS CDN
Route 53	도메인과 DNS를 관리하는 AWS 서비스
서버리스	서버가 없다는 뜻이 아니라, 서버 장비 관리를 서비스 업체가 대신하는 방식
Custom Domain	`pages.dev`·`workers.dev` 대신 내가 가진 도메인을 서비스에 연결한 주소
Route	어떤 주소와 경로의 요청을 특정 Worker로 보낼지 정하는 규칙
Binding	Worker 코드가 DB·저장소·환경 설정을 사용할 수 있도록 연결한 이름
Wrangler	Cloudflare 프로젝트를 만들고 시험·배포하는 공식 명령줄 도구
Preview	운영 공개 전에 별도 주소에서 확인하는 시험 배포
Production	실제 사용자가 접속하는 운영 환경
Deploy(배포)	내 컴퓨터의 프로그램을 인터넷에서 실행되도록 올리는 작업
Redirect(리디렉션)	한 웹 주소로 들어온 사용자를 다른 주소로 자동 이동시키는 설정

14.3 데이터베이스와 보안¶

용어	비전공자용 설명
데이터베이스(DB)	데이터를 일정한 규칙으로 저장하고 다시 찾는 시스템
관계형 데이터베이스(RDB)	표와 표 사이의 관계를 이용해 데이터를 관리하는 DB
D1	SQLite SQL 의미를 사용하며 Worker와 바인딩으로 연결하는 Cloudflare 서버리스 DB
SQLite	별도 DB 서버 없이 가볍게 사용할 수 있는 관계형 데이터베이스 엔진
MySQL	일반 웹서비스에서 널리 쓰는 오픈소스 관계형 데이터베이스
PostgreSQL	복잡한 SQL과 확장 기능을 지원하는 오픈소스 관계형 데이터베이스
Oracle Database	Oracle이 제공하는 상용 관계형 데이터베이스 제품
MongoDB	JSON과 비슷한 문서 형태로 저장하는 대표적인 NoSQL 데이터베이스
NoSQL	관계형 표와 SQL만을 중심으로 하지 않는 문서·키-값 등의 DB 범주
Amazon RDS	MySQL·PostgreSQL·Oracle 등의 운영·백업을 AWS가 관리하는 관계형 DB 서비스
Amazon Aurora	MySQL·PostgreSQL과 호환되도록 AWS가 만든 관리형 관계형 DB
Amazon DynamoDB	AWS의 관리형 키-값·문서형 NoSQL 데이터베이스
Amazon DocumentDB	MongoDB와의 호환성을 제공하는 AWS의 문서형 DB; MongoDB 자체와는 다름
Workers KV	키로 값을 빠르게 읽는 Cloudflare의 전역 키-값 저장소
Durable Objects	한 객체의 상태를 일관되게 처리하도록 실행과 저장을 묶는 Cloudflare 기능
Hyperdrive	Worker에서 외부 PostgreSQL·MySQL DB 연결을 재사용하고 빠르게 만드는 기능
테이블	같은 종류의 데이터를 행과 열로 정리한 표
행(Row)	테이블에 저장된 데이터 한 건; Todo 한 개에 해당
열(Column)	제목·완료 여부처럼 각 데이터가 갖는 항목
`id`·`title`·`is_done`·`created_at`	Todo의 고유 번호·제목·완료 여부·생성 시각을 저장하는 열 이름
Schema	테이블·열·관계·권한이 어떻게 구성됐는지 나타내는 DB 구조
SQL	관계형 데이터베이스에 조회·생성·수정을 요청하는 언어
Migration	DB 구조 변경 내용을 파일과 순서로 기록해 다시 적용할 수 있게 하는 방식
Prepared Statement·`prepare().bind()`	SQL 문장과 사용자 값을 분리해 SQL 삽입을 막는 실행 방식
SQL 삽입(SQL Injection)	사용자 입력을 SQL 명령으로 실행시켜 DB를 읽거나 바꾸려는 공격
제약 조건(Constraint)	잘못된 값이나 중복 값이 DB에 저장되지 않도록 막는 규칙
DROP·TRUNCATE	테이블 자체를 없애거나 안의 데이터를 모두 비우는 파괴적인 SQL 명령
Auth	사용자가 누구인지 로그인으로 확인하는 기능
객체 저장소	이미지·PDF·원본 JSON 같은 파일을 객체 단위로 저장하는 서비스; 관계형 DB와 다름
객체(Object)·버킷(Bucket)	저장하는 파일 한 개와 그 파일들을 담는 큰 보관함
Amazon S3	AWS의 객체 저장소 서비스
Cloudflare R2	Cloudflare의 객체 저장소로, S3 호환 API를 제공함
S3 호환 API	S3용 도구와 요청 방식을 다른 객체 저장소에서도 사용할 수 있게 맞춘 인터페이스
Secret·Secret Key	서버만 알고 있어야 하는 비밀 값이나 인증 키
API Key	프로그램이 외부 API를 호출할 권한이 있음을 보여 주는 키
환경 변수	코드와 분리해 실행 환경에서 전달하는 설정값
`.env`·`.dev.vars`	로컬 개발용 환경 변수와 Secret을 적는 파일; Git에 올리지 않음
개발 환경(Development)	기능을 만들고 시험하는 안전한 작업 환경
운영 환경(Production)	실제 사용자와 실제 데이터가 있는 서비스 환경
읽기 전용(Read-only)	내용을 볼 수는 있지만 만들기·수정·삭제는 할 수 없는 권한
권한	사용자나 도구가 읽기·수정·삭제 중 무엇을 할 수 있는지 정한 범위
Rate Limit	짧은 시간에 너무 많은 요청을 보내지 못하도록 횟수를 제한하는 장치
CAPTCHA	요청자가 자동 프로그램이 아니라 사람인지 확인하는 장치
Rotate	노출 가능성이 있는 키를 폐기하고 새 키로 교체하는 작업

14.4 AI 에이전트와 개발 도구¶

용어	비전공자용 설명
AI 에이전트	목표를 받고 파일 읽기·수정·명령 실행·검증을 여러 단계로 수행하는 AI
Codex	OpenAI의 코딩 AI 에이전트
Codex 앱	ChatGPT 데스크톱 앱 안에서 프로젝트를 열고 Codex와 작업하는 화면
Claude Code	Anthropic의 터미널 기반 코딩 AI 에이전트
Sonnet	Claude Code에서 선택할 수 있는 일반적인 Claude 모델 별칭
모델	요청을 이해하고 답·코드·계획을 만드는 AI 엔진
Sol	복잡한 설계·보안·여러 단계의 문제에 맞는 Codex GPT-5.6 모델
Terra	일반적인 구현·탐색 작업에 맞는 Codex GPT-5.6 모델
Luna	작고 반복적인 정리 작업에 맞는 Codex GPT-5.6 모델
추론 수준	모델이 답을 내기 전에 얼마나 깊게 검토할지 정하는 정도
토큰	AI가 글과 코드를 읽고 만드는 작은 처리 단위
컨텍스트	현재 작업에서 AI가 참고하는 대화·파일·명령 결과의 묶음
컨텍스트 윈도우	모델이 한 작업에서 참고할 수 있는 정보량의 한도
프롬프트	사람에게서 AI 에이전트로 전달하는 작업 요청
프롬프트 엔지니어링	목표·맥락·제약·완료 기준을 분명히 적어 결과 품질을 높이는 방법
플랜 모드	파일을 바꾸기 전에 조사와 작업 계획부터 제시하게 하는 모드
세션	에이전트와 한 작업 흐름을 이어 가는 대화 단위
도구(Tool)	에이전트가 파일·터미널·브라우저·외부 서비스를 다루는 수단
MCP	에이전트가 Cloudflare 같은 외부 도구와 연결되는 표준 방식
`AGENTS.md`	Codex가 저장소에서 반복해 참고하는 프로젝트 작업 규칙 파일
`CLAUDE.md`	Claude Code가 프로젝트에서 반복해 참고하는 작업 규칙 파일
CLI	마우스 대신 터미널에 글자 명령을 입력해 프로그램을 사용하는 방식
터미널	`cd`, `git`, `codex` 같은 명령을 입력하는 프로그램
셸(Shell)	터미널에서 입력한 명령을 해석하고 실행하는 프로그램
PowerShell	Windows에서 기본으로 쓰는 명령줄 셸
Windows Terminal	PowerShell·명령 프롬프트·WSL 등을 탭으로 열 수 있는 Windows 터미널 앱
Integrated terminal	Codex 앱 안에서 명령을 실행할 수 있는 내장 터미널
Diff 화면	파일에서 무엇이 바뀌었는지 전후를 비교해 보는 화면
Ask for approval	Codex가 파일 수정·명령 실행 같은 행동 전에 사람에게 확인을 요청하는 설정
Full access	Codex에 넓은 파일·명령 권한을 주는 설정; 초보 실습에는 권장하지 않음
WSL2	Windows 안에서 Linux 환경을 실행하는 기능
winget	Windows에서 프로그램을 설치·업데이트하는 공식 패키지 관리자
프로젝트	하나의 프로그램을 만들기 위해 모아 둔 코드·설정·문서 전체
폴더·디렉터리	파일을 목적별로 묶어 두는 공간; 두 말은 같은 뜻으로 사용
소스 코드	사람이 읽고 수정할 수 있는 프로그램의 원본 명령문
`pwd`	현재 작업 중인 폴더의 전체 경로를 보여 주는 명령
`ls`	현재 폴더의 파일과 하위 폴더를 보여 주는 명령
`cd`	다른 작업 폴더로 이동하는 명령
`mkdir`	새 폴더를 만드는 명령
`curl`	인터넷 주소에서 문서나 설치 파일을 받아오는 터미널 명령
`irm`	PowerShell에서 인터넷 주소의 내용을 받아오는 명령 별칭
`iex`	PowerShell에서 받은 문자열을 명령으로 실행하는 명령 별칭
설치 스크립트	프로그램 설치 과정을 여러 명령으로 묶어 자동 실행하는 파일
파이프(Pipe)	세로 막대 기호로 앞 명령의 결과를 뒤 명령의 입력에 전달하는 기능
npm	JavaScript 패키지를 설치·관리하는 도구
npx	설치된 JavaScript 명령줄 도구를 실행하는 명령
`.gitignore`	Git이 기록하지 않을 파일과 폴더를 적는 설정 파일
`README.md`	프로젝트 목적·설치·사용법을 사람에게 설명하는 안내 문서
`node_modules`	npm으로 설치한 JavaScript 패키지가 모이는 폴더
`wrangler.jsonc`	Worker 이름·실행 환경·연결 정보를 적는 Wrangler 설정 파일
저장소(Repository)	한 프로젝트의 코드·문서·변경 이력을 모아 둔 공간
버전 관리	파일 변경 시점과 내용을 기록해 비교·복구·협업할 수 있게 하는 방식
Git	파일의 변경 이력을 기록하고 이전 상태와 비교하는 도구
GitHub	Git 저장소를 인터넷에서 보관·공유하는 서비스
GitHub CLI(`gh`)	터미널에서 GitHub 저장소와 작업을 관리하는 도구
`gh --version`	GitHub CLI가 설치됐는지와 설치된 버전을 확인하는 명령
`gh auth login`	GitHub CLI를 GitHub 계정에 인증하는 최초 로그인 명령
작업 폴더(Working Tree)	현재 직접 열어 수정하고 있는 프로젝트 파일 상태
스테이징 영역(Staging Area)	다음 커밋에 넣기로 선택한 변경을 잠시 모아 두는 곳
로컬 저장소	내 컴퓨터에 있는 Git 파일과 전체 커밋 이력
원격 저장소(Remote)	GitHub처럼 인터넷에 연결된 Git 저장소
`origin`	처음 연결한 원격 저장소에 관례적으로 붙이는 기본 별칭
`git init`	현재 폴더를 새 Git 저장소로 만드는 명령
`git status`	어떤 파일이 바뀌었는지 보여 주는 명령
`git diff`	파일의 이전 내용과 바뀐 내용을 비교해 보여 주는 명령
`git add`	다음 커밋에 포함할 변경을 스테이징 영역에 선택하는 명령
`git diff --staged`	다음 커밋에 실제로 들어갈 변경만 비교하는 명령
`git commit`	스테이징한 변경을 설명과 함께 로컬 Git 이력에 저장하는 명령
`git push`	로컬 커밋을 GitHub 같은 원격 저장소로 전송하는 명령
`git log`	지금까지 기록한 커밋 이력을 보여 주는 명령
Commit(커밋)	의미 있는 변경 묶음을 설명과 함께 Git 이력에 기록하는 일
Pull Request	GitHub에서 브랜치 변경을 검토하고 합쳐 달라고 제안하는 기능
Branch(브랜치)	기존 코드와 분리해 변경을 진행하는 작업선
Worktree	한 Git 저장소의 여러 브랜치를 서로 다른 폴더에서 동시에 여는 기능
Merge(병합)	다른 브랜치의 변경을 현재 브랜치에 합치는 작업
`main`	많은 Git 저장소에서 최종 기준으로 사용하는 기본 브랜치 이름
코드 리뷰	변경된 코드의 오류·보안·품질 문제를 확인하는 과정
Diff	변경 전과 변경 후의 차이
테스트	기능이 기대대로 동작하는지 반복 확인하는 절차
로그	프로그램이 실행 중 남긴 상태·요청·오류 기록
CI/CD	코드 변경을 자동으로 테스트하고 배포하는 흐름
GitHub Actions	GitHub에서 테스트·빌드·배포 자동화를 실행하는 기능
Telegram Bot	프로그램이 Telegram 사용자에게 자동으로 메시지를 보내거나 명령을 받는 계정
공식 API	서비스 제공자가 사용 방법과 제한을 문서로 공개한 데이터·기능 창구
크롤링	프로그램이 웹페이지를 방문해 허용된 정보를 수집하는 작업
이용 약관	서비스를 사용할 때 지켜야 할 허용 범위와 금지 사항
Markdown·HTML 보고서·PDF	Markdown은 편집하기 쉬운 텍스트, HTML은 브라우저용 보고서, PDF는 같은 배치를 유지하는 공유 문서 형식

15. 참고 — Supabase라는 선택지도 있다¶

Supabase는 PostgreSQL 데이터베이스, 사용자 로그인(Auth), 파일 저장, API를 한 플랫폼에서 제공하는 별도 서비스다. 사용자별 데이터 권한을 DB의 RLS 규칙으로 관리하거나 PostgreSQL 기능이 꼭 필요한 프로젝트에서 검토할 수 있다.

이번 Todo List 실습에서는 Supabase 프로젝트·MCP·API Key·테이블 설정을 사용하지 않는다. Pages → Worker → D1이라는 Cloudflare 흐름에 집중하고, 나중에 회원가입·로그인과 PostgreSQL이 필요한 프로젝트를 시작할 때 공식 문서에서 비교해 보면 충분하다.

선택	이번 문서에서의 위치	나중에 검토할 때
Cloudflare D1	Todo List 실습 DB	Worker와 가까운 간단한 SQL 서비스가 필요할 때
Supabase	참고 서비스	PostgreSQL·Auth·RLS를 한 서비스에서 사용하고 싶을 때

용어만 알아 두자. RLS(Row Level Security) 는 로그인한 사용자에 따라 볼 수 있는 행을 제한하는 DB 규칙이고, Policy 는 그 허용 조건이다. Supabase MCP는 에이전트가 Supabase 프로젝트를 읽거나 관리하도록 연결하는 개발 도구지만 이 특강에서는 설정하지 않는다.

참고 문서¶

아래 항목은 모두 서비스 제공자나 프로젝트가 운영하는 공식 문서다. 제목 링크를 눌러도 되고, 주소: 뒤의 URL을 복사해도 된다.